{"id":28563174,"url":"https://github.com/harnesslabs/arbiter","last_synced_at":"2025-12-12T13:03:44.163Z","repository":{"id":63486872,"uuid":"567327580","full_name":"harnesslabs/arbiter","owner":"harnesslabs","description":"Multi-agent framework for design, simulation, and auditing.","archived":false,"fork":false,"pushed_at":"2025-06-01T18:56:30.000Z","size":10728,"stargazers_count":709,"open_issues_count":24,"forks_count":72,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-06-02T05:04:41.815Z","etag":null,"topics":["auditing","ethereum","rust","simulation-framework","smart-contracts"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/harnesslabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-11-17T14:58:09.000Z","updated_at":"2025-05-31T23:28:37.000Z","dependencies_parsed_at":"2024-02-12T22:39:22.630Z","dependency_job_id":"f756e99b-8ffb-40ca-a281-6488cc21a5ed","html_url":"https://github.com/harnesslabs/arbiter","commit_stats":{"total_commits":1740,"total_committers":34,"mean_commits":51.1764705882353,"dds":0.6316091954022989,"last_synced_commit":"f5d54088a72a90dc12261c6d1dd9f446d1063de0"},"previous_names":["anthias-labs/arbiter","harnesslabs/arbiter"],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harnesslabs%2Farbiter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harnesslabs%2Farbiter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harnesslabs%2Farbiter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harnesslabs%2Farbiter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/harnesslabs","download_url":"https://codeload.github.com/harnesslabs/arbiter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harnesslabs%2Farbiter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259080921,"owners_count":22802393,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auditing","ethereum","rust","simulation-framework","smart-contracts"],"created_at":"2025-06-10T13:01:32.280Z","updated_at":"2025-12-12T13:03:43.693Z","avatar_url":"https://github.com/harnesslabs.png","language":"Rust","readme":"\u003cimg width=\"529\" alt=\"arbiter\" src=\"https://user-images.githubusercontent.com/20118821/236929861-2a1fe071-0053-453c-ac86-224b32febcd6.png\"\u003e\n\n\u003e A Rust-based multi-agent framework.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://discord.gg/qEwPr3GMP2\"\u003e\u003cimg src=\"https://img.shields.io/discord/1363153354338861247?style=flat\u0026logo=discord\u0026logoColor=white\u0026label=Discord\u0026color=5865F2\" alt=\"Discord\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://x.com/harnesslabs\"\u003e\u003cimg src=\"https://badgen.net/badge/icon/twitter?icon=twitter\u0026label\" alt=\"Twitter\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://visitor-badge.laobi.icu/badge?page_id=arbiter\" alt=\"Visitors\"\u003e\n\u003c/p\u003e\n\n## Overview\n\u003e **Arbiter** is a multi-agent framework that lets developers orchestrate event-driven simulations.\n\n\n---\n\n## NOTE\nArbiter is under active development to enter into a new phase.\nWe are currently working on the following:\n- [ ] `arbiter`: crate should be a lib to re-export our sub crates. The bin never caught on anyway.\n- [ ] `arbiter-core` becomes `arbiter-ethereum` or `arbiter-evm`.\n- [ ] `arbiter-engine` overhauled to handle more generic agent setups. Maintains the structure of being the actual underlying move forward / event handling mechanism.\n- [ ] `arbiter-core` should then house abstractions for different types of environments and other DES type items to be used with the engine.\n\n---\n## Below is the original README.md for Arbiter\n\nArbiter allows for fine-grained control over a (Rust) Ethereum Virtual Machine (EVM) to provide stateful Ethereum smart-contract interactions and the creation of behaviors that can be coalesced into complex scenarios or automation. As such, Arbiter enables robust and granular simulation to be conducted.\nWe use an [`ethers-rs`](https://github.com/gakonst/ethers-rs) middleware on top of [revm](https://github.com/bluealloy/revm), which is used in ETH clients such as [`reth`](https://github.com/paradigmxyz/reth) as well as [`foundry`](https://github.com/foundry-rs/foundry).\nThis enables speed, configurability, and modularity that feels like a lightweight custom Ethereum node. \n\nThe primary use of Arbiter is to probe the mechanism security of smart contracts, and perform advanced economic modelling.\nIf mechanism security interests you, please see the [Vulnerability Corpus](https://anthias-labs.github.io/arbiter/vulnerability_corpus.html).\n\n---\n\nThe Arbiter workspace has five crates:\n- `arbiter`: The bin that exposes a command line interface for forking and binding contracts.\n- `arbiter-core`: A lib containing the core logic for the Arbiter framework, including the `ArbiterMiddleware` discussed before, and the `Environment`, our sandbox.\n- `arbiter-engine`: A lib that provides abstractions for building simulations, agents, and behaviors.\n- `arbiter-macros`: A lib crate that contains the macros used to simplify development with Arbiter.\n- `arbiter-bindings`: A lib crate containing bindings for utility smart contracts used for testing and development.\n\n\n## Book\nHere you can find the [Arbiter Documentation](https://anthias-labs.github.io/arbiter/).\nThis book highlights some key Arbiter usage patterns and explains all key functionality.\n\n## Motivation \nArbiter was built to allow you to work with smart contracts in a stateful sandbox and thus design agents that can be used alongside the contracts.\nThis gives you many capabilities.\nFor instance, smart contract engineers must test their contracts against various potentially adversarial environments and parameters instead of relying on static and stateless testing.\n\nIn Decentralized Finance (DeFi), a wide array of complex decentralized applications can use the testing described above. Still, implicit financial strategies also encompass many agents and parameterizations. \nA financial engineer may want to test their strategies against thousands of market conditions, contract settings, shocks, and autonomous or random AI agents while ensuring their approach isn't vulnerable to bytecode-level exploits.\nLikewise, the same engineer may want to develop searcher agents, solver agents, or other autonomous agents that can be run on the blockchain.\n\n## Working with the Arbiter Framework\nTo work with Arbiter, you must have Rust installed on your machine. \nYou can install Rust by following the instructions [here](https://www.rust-lang.org/tools/install). \nIt will also be helpful to get the `cargo-generate` package, which you can install by doing:\n```bash\ncargo install cargo-generate\n```\n\n### Examples\nWe have an example that will run what we have set up in a template.\nTo run this, you can clone the repository and update the submodules:\n```bash\ngit clone https://github.com/anthias-labs/arbiter.git\ncd arbiter\ngit submodule update --init --recursive\n```\nFrom here, you can now try running the following from the clone's root directory:\n```bash\ncargo run --example template \n```\nThis command will enter the template CLI and show you the commands and flags.\n\nTo run the `ModifiedCounter.sol` example and see some logging, try:\n```bash\ncargo run --example template simulate examples/template/configs/example.toml -vvv\n```\nThis sets the log level to `debug` so you can see what's happening internally.\n\n### Initialization\nTo create your own Arbiter project off of our template [arbiter-template](https://github.com/anthias-labs/arbiter-template), you can run the following:\n```bash\ncd \u003cyour/chosen/directory\u003e\ncargo generate https://github.com/anthias-labs/arbiter-template.git\n```\nYou'll be prompted to provide a project name, and the rest will be set up for you!\n\n### Binary\nTo install the Arbiter binary, run:\n```bash\ncargo install arbiter\n```\nThis will install the Arbiter binary on your machine. You can then run `arbiter --help` to see that Arbiter was correctly installed and see the help menu.\n\n### Bindings\nYou can load or write your own smart contracts in the `contracts/` directory of your templated project and begin writing your own simulations. \nArbiter treats Rust smart-contract bindings as first-class citizens. \nThe contract bindings are generated via Foundry's `forge` command. \n`arbiter bind` wraps `forge` with convenience features that generate all your bindings to `src/bindings` as a Rust module. \n[Foundry](https://github.com/foundry-rs/foundry) power-users can use `forge` directly.\n\n### Forking\nTo fork a state of an EVM network, you must first create a fork config file.\nAn example is provided in the `examples/fork` directory.\nEssentially, you provide your storage location for the data, the network you want, the block number you want, and metadata about the contracts you want to fork.\n\n```bash\narbiter fork \u003cfork_config.toml\u003e\n```\nThis will create a fork of the network you specified in the config file and store it in your specified location.\nIt can then be loaded into an `arbiter-core` `Environment` using the `Fork::from_disk()` method.\n\nForking is done this way to ensure that all emulation does not require a constant connection to an RPC endpoint.\nYou may find that [Anvil](https://book.getfoundry.sh/anvil/) has a more accessible forking interface. However, an online forking mechanism makes RPC calls to update the state as necessary.\nArbiter `Environment` forking is for creating a state, storing it locally, and being able to initialize a simulation from that state when desired.\nWe plan to allow `arbiter-engine` to integrate with other network types, such as Anvil, in the future!\n\n**Optional Arguments** \nYou can run `arbiter fork \u003cfork_config.toml\u003e --overwrite` to overwrite the fork if it already exists.\n\n## Cargo Docs\n\nTo see the Cargo docs for the Arbiter crates, please visit the following:\n- [`arbiter`](https://docs.rs/crate/arbiter/)\n- [`arbiter-bindings`](https://docs.rs/crate/arbiter-bindings/)\n- [`arbiter-core`](https://docs.rs/arbiter-core/)\n- [`arbiter-macros`](https://docs.rs/arbiter-macros/)\n- [`arbiter-engine`](https://docs.rs/arbiter-engine/)\n\nYou will find each of these on crates.io.\n\n## Benchmarks\nIn `arbiter-core`, we have a a small benchmarking suite that compares the `ArbiterMiddleware` implementation over the `Environment` to the [Anvil](https://github.com/foundry-rs/foundry/tree/master/crates/anvil) local testnet chain implementation.\nThe biggest reasons we chose to build Arbiter was to gain more control over the EVM environment and to have a more robust simulation framework. Still, we also wanted to gain speed, so we chose to build our own interface over `revm` instead of using Anvil (which uses `revm` under the hood). \nFor the following, Anvil was set to mine blocks for each transaction instead of setting an enforced block time. The `Environment` was configured with a block rate of 10.0.\nPreliminary benchmarks of the `ArbiterMiddleware` interface over `revm` against Anvil are given in the following table.\n\nTo run the benchmarking code yourself, you can run:\n```bash\ncargo bench --package arbiter-core\n```\n\n| Operation       |  ArbiterMiddleware |    Anvil     | Relative Difference |\n|-----------------|-----------------|--------------|---------------------|\n| Deploy          | 238.975µs       | 7712.436µs   | ~32.2729x           |\n| Lookup          | 565.617µs       | 17880.124µs  | ~31.6117x           |\n| Stateless Call  | 1402.524µs      | 10397.55µs   | ~7.413456x          |\n| Stateful Call   | 2043.88µs       | 154553.225µs | ~75.61756x          |\n\n\nThe above can be described by:\n- Deploy: Deploying a contract to the EVM. \nIn this method, we deployed both `ArbiterToken` and `ArbiterMath`, so you can divide the time by two to estimate the time it takes to deploy a single contract.\n\n- Lookup: Look up the `balanceOf` for a client's address for `ArbiterToken`.\nIn this method, we called `ArbiterToken`'s `balanceOf` function 100 times.\nDivide by 100 to get the time to look up a single balance.\n\n- Stateless Call: Calling a contract that does not mutate state. \nIn this method, we called `ArbiterMath`'s `cdf` function 100 times.\nDivide by 100 to get the time to call a single stateless function.\n\n- Stateful Call: Calling a contract that mutates state. \nIn this call, we called `ArbiterToken`'s `mint` function 100 times.\nDivide by 100 to get the time to call a single stateful function.\n\nThe benchmarking code can be found in the `arbiter-core/benches/` directory, and these specific times were achieved over a 1000 run average. \nThe above was achieved by running `cargo bench --package arbiter-core`, which will automatically run with the release profile.\nTimes were achieved on an Apple Macbook Pro M1 Max with 8 performance and 2 efficiency cores and 32GB of RAM.\n\nOf course, the use cases of Anvil and the `ArbiterMiddleware` can be different. \nAnvil represents a more realistic environment with networking and mining. At the same time, the `ArbiterMiddleware` is a simpler environment with the bare essentials to running stateful simulations.\nAnvil also mines blocks for each transaction, while the `ArbiterMiddleware` does not.\n\nPlease let us know if you need any help with these benchmarks or suggestions for improving them!\n\n## Testing\n\nIf you contribute, please write tests for any new code you write. To run the tests, you can run the following:\n\n```bash\ncargo test --all --all-features\n```\n\n## Contributing\n\nSee our [Contributing Guidelines](https://github.com/anthias-labs/arbiter/blob/main/.github/CONTRIBUTING.md)\n","funding_links":[],"categories":["Framework","AI Agents \u0026 Autonomy Frameworks"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharnesslabs%2Farbiter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharnesslabs%2Farbiter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharnesslabs%2Farbiter/lists"}