```bash
# ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
# ░░ ░░░ ░░░ ░░░ ░░░░ ░░░ ░░ ░░░ ░░ ░░ ░░ ░░░
# ▒ ▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒ ▒▒▒ ▒▒ ▒▒▒ ▒▒▒ ▒▒ ▒▒▒ ▒▒▒ ▒▒▒▒▒ ▒▒▒▒▒▒ ▒▒▒▒▒ ▒▒▒▒▒▒ ▒▒▒ ▒▒
# ▓▓ ▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓ ▓▓ ▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓ ▓▓▓
# ██████ ████ █████ ██ ███ ███ ██ ███ ███ █████ ██████ █████ ██████ ███ ██
# ██ █████ █████ ███ ██ ████ ██ ███ ██ ███ ████ █████ ██ ████ █
# ███████████████████████████████████████████████████████████████████████████████████████████
```
> Expanding the Starknet tooling ecosystem.
(https://twitter.com/PragmaOracle)
## Overview
> **Starkbiter** is a framework for orchestrating event based agentic simulations on top of Starknet Devnet sandbox.
Starkbiter provides a Full JSON-RPC Starknet Node capabilities with additional methods to control block production, contract and account deployments and declaration. It integrates deeply with starknet-devnet and starknet-rs types crates allowing for seamless integration for all the tooling that depends on those. Thus, it also provides additional layer of well known contract bindings generated by [cainome](https://github.com/cartridge-gg/cainome).
The primary use of Starkbiter is to probe the mechanism security of smart contracts, and perform advanced economic modelling.
---
The Starkbiter workspace has five crates:
- `starkbiter`: The bin that exposes a command line interface for contract bindings.
- `starkbiter-core`: A lib containing the core logic for the Starkbiter framework, including the `StarkbiterMiddleware` discussed before, and the `Environment`, our sandbox.
- `starkbiter-engine`: A lib that provides abstractions for building simulations, agents, and behaviors.
- `starkbiter-macros`: A lib crate that contains the macros used to simplify development with Starkbiter.
- `starkbiter-bindings`: A lib crate containing bindings for utility smart contracts used for testing and development.
## WIP
- [ ] non-blocking event polling
- [x] bin docs
- [x] core docs
- [x] main readme
- [ ] docs docs
- [x] getting started
- [ ] usage
- [x] index
- [ ] benchmarks
- [ ] python bindings
- [x] more test cases
- [ ] coverage report
- [x] support for replaying mainnet transactions mixing them with simulated ones.
- [x] github workflows revival
- [ ] contribute to cainome and remove fork dep
- [ ] contribute to starknet-rs and remove fork dep + Fix generic Runtime error with more specific errors from within Provider
- [ ] contribute to starknet-devnet and remove fork dep
- [x] test that toml config parameters for forking work
- [x] contract execution logging and traces from Devnet
- [ ] test for simultaneous connection usage by different contracts.
## Book
TODO: Does not exist yet
## Motivation
Starkbiter was adapted from [Arbiter](https://github.com/harnesslabs/arbiter) code to allow you to work with smart contracts in a stateful sandbox and thus design agents that can be used alongside the contracts.
This gives you many capabilities.
For instance, smart contract engineers must test their contracts against various potentially adversarial environments and parameters instead of relying on static and stateless testing.
In 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.
A 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.
Likewise, the same engineer may want to develop searcher agents, solver agents, or other autonomous agents that can be run on the blockchain.
## Working with the Starkbiter Framework
To work with Starkbiter, you must have Rust installed on your machine.
You can install Rust by following the instructions [here](https://www.rust-lang.org/tools/install).
It will also be helpful to get the `cargo-generate` package, which you can install by doing:
```bash
cargo install cargo-generate
```
### Examples
We have an example that will run what we have set up in a template.
To run this, you can clone the repository and update the submodules:
```bash
git clone https://github.com/astraly-labs/starkbiter
cd starkbiter
```
From here, you can now try running the following from the clone's root directory:
```bash
cargo run --example minter
```
This command will enter the template CLI and show you the commands and flags.
To run the `ModifiedCounter.sol` example and see some logging, try:
```bash
cargo run --example minter simulate ./examples/minter/config.toml -vvvv
```
This sets the log level to `trace` so you can see what's happening internally.
### Binary
To install the Starkbiter binary, run:
```bash
cargo install starkbiter
```
This will install the Starkbiter binary on your machine. You can then run `starkbiter --help` to see that Starkbiter was correctly installed and see the help menu.
### Bindings
You can put your compiled sierra 1.0 contract jsons in the `contracts/` directory of your templated project, you'll need to run:
```bash
starkbiter bind
```
to generate rust bindings and you are good to go. You can use those within your contracts now.
Starkbiter uses `cainome` to generate rust bindings and in turn `cainome` relies on starknet-rs account abstraction implementation. You can easily generate an account using `create_single_owner_account` method of the environment (and middleware) and pass it to create an instance of the contract you you want to execute.
### Forking
To fork a state of an Starknet network, you need to specify fork parameters upon instantiating environment. Fork is being initialised lazily, this mechanics is inherited from starknet devnet implementation.
```rust
let env = Environment::builder()
.with_chain_id(chain_id.into())
.with_fork(
Url::from_str("http://json-rpc-provider-to-fork-from:1234").unwrap(),
1000, // Block number to fork from
Some(Felt::from_str("0xblock_hash").unwrap()),
)
.build();
```
This will instantiate environment which will upon request fetch missing bits of state and store those in memory, locally. Current implementation implies we need to have endpoint rpc endpoint available during the simulation.
## Cargo Docs
To see the Cargo docs for the Starkbiter crates, please visit the following:
- [`starkbiter`](https://docs.rs/crate/starkbiter/)
- [`starkbiter-bindings`](https://docs.rs/crate/starkbiter-bindings/)
- [`starkbiter-core`](https://docs.rs/starkbiter-core/)
- [`starkbiter-macros`](https://docs.rs/starkbiter-macros/)
- [`starkbiter-engine`](https://docs.rs/starkbiter-engine/)
You will find each of these on crates.io.
## Benchmarks
In `starkbiter-core`, we have a a small benchmarking suite that currently is under WIP.
TODO: benchmarks. What are we benchmarking against?
## Testing
If you contribute, please write tests for any new code you write. To run the tests, you can run the following:
```bash
cargo test --all --all-features
```
## Contributing
See our [Contributing Guidelines](https://github.com/astraly-labs/starkbiter/blob/main/.github/CONTRIBUTING.md)
Raw data
{
"_id": null,
"home_page": null,
"name": "starkbiter",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "starknet, cairo, emulator, simulator, simulation, agents, bindings, testing, smart-contracts",
"author": "Baitcode <batiyiv@gmail.com>, Matthias <matthias@pragma.build>",
"author_email": "Baitcode <batiyiv@gmail.com>, Matthias <matthias@pragma.build>",
"download_url": null,
"platform": null,
"description": "```bash\n# \u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\n# \u2591\u2591 \u2591\u2591\u2591 \u2591\u2591\u2591 \u2591\u2591\u2591 \u2591\u2591\u2591\u2591 \u2591\u2591\u2591 \u2591\u2591 \u2591\u2591\u2591 \u2591\u2591 \u2591\u2591 \u2591\u2591 \u2591\u2591\u2591\n# \u2592 \u2592\u2592\u2592\u2592\u2592\u2592\u2592\u2592\u2592 \u2592\u2592\u2592\u2592\u2592 \u2592\u2592\u2592 \u2592\u2592 \u2592\u2592\u2592 \u2592\u2592\u2592 \u2592\u2592 \u2592\u2592\u2592 \u2592\u2592\u2592 \u2592\u2592\u2592\u2592\u2592 \u2592\u2592\u2592\u2592\u2592\u2592 \u2592\u2592\u2592\u2592\u2592 \u2592\u2592\u2592\u2592\u2592\u2592 \u2592\u2592\u2592 \u2592\u2592\n# \u2593\u2593 \u2593\u2593\u2593\u2593\u2593 \u2593\u2593\u2593\u2593\u2593 \u2593\u2593\u2593 \u2593\u2593 \u2593\u2593\u2593\u2593\u2593 \u2593\u2593\u2593\u2593\u2593 \u2593\u2593\u2593\u2593\u2593\u2593 \u2593\u2593\u2593\u2593\u2593\u2593 \u2593\u2593\u2593\u2593\u2593 \u2593\u2593\u2593\u2593 \u2593\u2593\u2593\n# \u2588\u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588 \u2588\u2588 \u2588\u2588\u2588 \u2588\u2588\u2588 \u2588\u2588 \u2588\u2588\u2588 \u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588 \u2588\u2588\n# \u2588\u2588 \u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588 \u2588\u2588 \u2588\u2588\u2588\u2588 \u2588\u2588 \u2588\u2588\u2588 \u2588\u2588 \u2588\u2588\u2588 \u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588 \u2588\u2588 \u2588\u2588\u2588\u2588 \u2588\n# \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\n```\n> Expanding the Starknet tooling ecosystem.\n\n\n(https://twitter.com/PragmaOracle)\n\n## Overview\n> **Starkbiter** is a framework for orchestrating event based agentic simulations on top of Starknet Devnet sandbox.\n\nStarkbiter provides a Full JSON-RPC Starknet Node capabilities with additional methods to control block production, contract and account deployments and declaration. It integrates deeply with starknet-devnet and starknet-rs types crates allowing for seamless integration for all the tooling that depends on those. Thus, it also provides additional layer of well known contract bindings generated by [cainome](https://github.com/cartridge-gg/cainome).\n\nThe primary use of Starkbiter is to probe the mechanism security of smart contracts, and perform advanced economic modelling.\n\n---\n\nThe Starkbiter workspace has five crates:\n- `starkbiter`: The bin that exposes a command line interface for contract bindings.\n- `starkbiter-core`: A lib containing the core logic for the Starkbiter framework, including the `StarkbiterMiddleware` discussed before, and the `Environment`, our sandbox.\n- `starkbiter-engine`: A lib that provides abstractions for building simulations, agents, and behaviors.\n- `starkbiter-macros`: A lib crate that contains the macros used to simplify development with Starkbiter.\n- `starkbiter-bindings`: A lib crate containing bindings for utility smart contracts used for testing and development.\n\n## WIP\n\n- [ ] non-blocking event polling\n- [x] bin docs\n- [x] core docs\n- [x] main readme\n- [ ] docs docs\n - [x] getting started\n - [ ] usage\n - [x] index\n- [ ] benchmarks\n- [ ] python bindings\n- [x] more test cases\n- [ ] coverage report\n- [x] support for replaying mainnet transactions mixing them with simulated ones.\n- [x] github workflows revival\n- [ ] contribute to cainome and remove fork dep\n- [ ] contribute to starknet-rs and remove fork dep + Fix generic Runtime error with more specific errors from within Provider\n- [ ] contribute to starknet-devnet and remove fork dep\n- [x] test that toml config parameters for forking work\n- [x] contract execution logging and traces from Devnet\n- [ ] test for simultaneous connection usage by different contracts.\n\n\n## Book\nTODO: Does not exist yet\n\n## Motivation\nStarkbiter was adapted from [Arbiter](https://github.com/harnesslabs/arbiter) code 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 Starkbiter Framework\nTo work with Starkbiter, 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/astraly-labs/starkbiter\ncd starkbiter\n```\n\nFrom here, you can now try running the following from the clone's root directory:\n```bash\ncargo run --example minter\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 minter simulate ./examples/minter/config.toml -vvvv\n```\nThis sets the log level to `trace` so you can see what's happening internally.\n\n### Binary\nTo install the Starkbiter binary, run:\n```bash\ncargo install starkbiter\n```\nThis will install the Starkbiter binary on your machine. You can then run `starkbiter --help` to see that Starkbiter was correctly installed and see the help menu.\n\n### Bindings\nYou can put your compiled sierra 1.0 contract jsons in the `contracts/` directory of your templated project, you'll need to run:\n\n```bash\nstarkbiter bind\n```\n\nto generate rust bindings and you are good to go. You can use those within your contracts now.\nStarkbiter uses `cainome` to generate rust bindings and in turn `cainome` relies on starknet-rs account abstraction implementation. You can easily generate an account using `create_single_owner_account` method of the environment (and middleware) and pass it to create an instance of the contract you you want to execute.\n\n### Forking\nTo fork a state of an Starknet network, you need to specify fork parameters upon instantiating environment. Fork is being initialised lazily, this mechanics is inherited from starknet devnet implementation.\n\n```rust\nlet env = Environment::builder()\n .with_chain_id(chain_id.into())\n .with_fork(\n Url::from_str(\"http://json-rpc-provider-to-fork-from:1234\").unwrap(),\n 1000, // Block number to fork from\n Some(Felt::from_str(\"0xblock_hash\").unwrap()),\n )\n .build();\n```\n\nThis will instantiate environment which will upon request fetch missing bits of state and store those in memory, locally. Current implementation implies we need to have endpoint rpc endpoint available during the simulation.\n\n## Cargo Docs\n\nTo see the Cargo docs for the Starkbiter crates, please visit the following:\n- [`starkbiter`](https://docs.rs/crate/starkbiter/)\n- [`starkbiter-bindings`](https://docs.rs/crate/starkbiter-bindings/)\n- [`starkbiter-core`](https://docs.rs/starkbiter-core/)\n- [`starkbiter-macros`](https://docs.rs/starkbiter-macros/)\n- [`starkbiter-engine`](https://docs.rs/starkbiter-engine/)\n\nYou will find each of these on crates.io.\n\n## Benchmarks\nIn `starkbiter-core`, we have a a small benchmarking suite that currently is under WIP.\nTODO: benchmarks. What are we benchmarking against?\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/astraly-labs/starkbiter/blob/main/.github/CONTRIBUTING.md)\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Allowing smart contract developers to do simulation driven development via an Starknet Devnet emulator",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [
"starknet",
" cairo",
" emulator",
" simulator",
" simulation",
" agents",
" bindings",
" testing",
" smart-contracts"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7d250e87f273a6ffa858d3b61c07095ea64c3213c9222c38a96213bec4ff2837",
"md5": "47b9bac0a4f1087136f4a22776c40b44",
"sha256": "49953bb154e0b6fbba61f7a10546f4f780c4846b422bf237570a88197fd83116"
},
"downloads": -1,
"filename": "starkbiter-0.1.0-py3-none-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "47b9bac0a4f1087136f4a22776c40b44",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1100323,
"upload_time": "2025-07-14T09:09:24",
"upload_time_iso_8601": "2025-07-14T09:09:24.374892Z",
"url": "https://files.pythonhosted.org/packages/7d/25/0e87f273a6ffa858d3b61c07095ea64c3213c9222c38a96213bec4ff2837/starkbiter-0.1.0-py3-none-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 09:09:24",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "starkbiter"
}
JSON