{"id":16189960,"url":"https://github.com/brson/soroban-token-fuzzer","last_synced_at":"2025-08-30T15:32:02.324Z","repository":{"id":194657513,"uuid":"691299167","full_name":"brson/soroban-token-fuzzer","owner":"brson","description":null,"archived":false,"fork":false,"pushed_at":"2024-03-24T16:13:00.000Z","size":160,"stargazers_count":3,"open_issues_count":10,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-24T11:17:42.289Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2023-09-13T22:42:29.000Z","updated_at":"2024-04-01T14:54:14.000Z","dependencies_parsed_at":"2023-09-14T13:55:06.582Z","dependency_job_id":"efdd9d35-a832-4065-bc76-6a2f45d4a177","html_url":"https://github.com/brson/soroban-token-fuzzer","commit_stats":null,"previous_names":["aimeedeer/fuzz-native-token-contract","brson/soroban-token-fuzzer"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brson%2Fsoroban-token-fuzzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brson%2Fsoroban-token-fuzzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brson%2Fsoroban-token-fuzzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brson%2Fsoroban-token-fuzzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brson","download_url":"https://codeload.github.com/brson/soroban-token-fuzzer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231501580,"owners_count":18386285,"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":[],"created_at":"2024-10-10T07:37:45.234Z","updated_at":"2024-12-27T14:54:23.542Z","avatar_url":"https://github.com/brson.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# soroban-token-fuzzer\n\nThis is a reusable fuzzer for Soroban contracts\nthat implement the standard\n[`TokenInterface`](https://docs.rs/soroban-sdk/latest/soroban_sdk/token/trait.TokenInterface.html).\n\nSoroban contract authors implementing tokens can use it\nto gain confidence in their code.\n\n\n## Prerequisites\n\nAt present, this requires a specific commit of `rs-soroban-env`\nand `rs-soroban-sdk` to be checked out in directories adjacent to `soroban-token-fuzzer`.\n\n- rs-soroban-env repo  : https://github.com/stellar/rs-stellar-contract-env.git\n- rs-soroban-env commit: f035dda68e061a8fa18ab0c4e35b4b0618d15324\n- rs-soroban-sdk repo  : https://github.com/brson/rs-stellar-contract-sdk.git\n- rs-soroban-sdk commit: a2499ddb86f23f0820faeb77e46f391aa4194a3b\n\nThis changes over time as the SDK changes.\n\n\n## How to use\n\nInstall [`cargo-fuzz`](https://github.com/rust-fuzz/cargo-fuzz):\n\n```\ncargo install cargo-fuzz\n```\n\nRunning the fuzzer against two in-tree tokens:\n\n```\ncargo +nightly fuzz run fuzz_native_token\n```\n\n```\ncargo +nightly fuzz run fuzz_example_token\n```\n\nThe main part of this project is the\n`soroban-token-fuzzer` crate, in the root directory of this repo.\nIt is a library that implements reusable token fuzzing logic.\nCustomized token fuzzers are programs that link to `soroban-token-fuzzer`\nand run it with their own configuration.\n\nIn this repo, the `soroban-token-fuzzer-driver` crate,\nin the [`fuzz`](./fuzz) directory, is such a crate. It includes\nthe `fuzz_native_token` and `fuzz_example_token` fuzzers.\n\nThe easiest way to use this fuzzer is to clone this repo,\nand simply add another fuzzer to the `soroban-token-fuzzer-driver`\ncrate.\n\n### Adding a fuzzer to `soroban-token-fuzzer-driver`\n\n1) Copy `fuzz/fuzz_targets/fuzz_example_token.rs` to\n   e.g. `fuzz_my_token.rs`\n2) Edit `fuzz/Cargo.toml` to add your contract as a dependency, e.g.\n\n   ```toml\n   my-token.path = \"../tokens/my-token\"\n   my-token.features = [\"testutils\"]\n   ```\n\n   Make sure your crate has a \"testutils\" feature and it is activated.\n3) In `fuzz/Cargo.toml`, declare `fuzz_my_token.rs` as a binary:\n\n   ```toml\n   [[bin]]\n   name = \"fuzz_my_token\"\n   path = \"fuzz_targets/fuzz_my_token.rs\"\n   test = false\n   doc = false\n   ```\n\n4) Adapt `fuzz_my_token.rs` to use your token.\n\nNow you can fuzz your token with\n\n```\ncargo +nightly fuzz run fuzz_my_token\n```\n\n\n## How does it work?\n\nThe fuzzer generates several addresses,\none of which will be an admin.\nThese addresses may be contract addresses or native account addresses.\n\nIt uses token-specific code to initialize the contract.\n\nIt then executes some number of commands against the contract,\neither a method on the `TokenInterface` interface,\na token-specific `mint` method, or a command to advance time\nand begin a new transaction.\nFor each call it generates auths for a random subset of addresses.\n\nAfter every step the fuzzer makes general assertions about invariants,\nand specific assertions related to the executed command.\n\nIt maintains independent state about what it expects from the token's\ninternal state, including information about mints, burns, allowances and balances.\n\n\n## What is tested / asserted?\n\nAfter every step various invariants are asserted:\n\n- The sum of all balances is equal to the sum of mints minus the sum of burns.\n- All pairs of addresses have allowance equal to the fuzzer's own accounting of allowances.\n- All current balances are greater than or equal to 0.\n- All current balances are equal to the fuzzer's own accounting of balances.\n- Contract calls do not panic (unless it's with `panic_with_error!`).\n  An error of type [`WasmVm`](https://docs.rs/soroban-sdk/latest/soroban_sdk/xdr/enum.ScErrorType.html#variant.WasmVm)\n  and code [`InvalidAction`](https://docs.rs/soroban-sdk/latest/soroban_sdk/xdr/enum.ScErrorCode.html#variant.InvalidAction)\n  is considered a panic,\n  as that is what the runtime generates on panic.\n- Math does not overflow (detected as a panic).\n- For `approve`, `transfer`, `transfer_from`, `burn_from`, `burn`,\n  if the input amount is negative, the call returns an error.\n- If the correct auths have not been provided the call fails.\n- The results of the `name`, `symbol` and `decimals`\n  methods have not changed.\n\n\n## What is yet to be tested?\n\n- Admin methods other than `mint`. There is no standard\n  admin interface for Soroban tokens.\n- Accessor methods don't mutate internal state.\n- More assertions about negative numbers in various situations.\n- More assertions about expected results of individual calls.\n- Intentionally expiring allowances, the contract etc.\n- Assertions about expected events.\n- Comparison to reference implementation\n  - We can test that many tokens all have the same / similar behavior as a reference implementation\n\n\n## Tips for writing fuzzable Soroban contracts\n\nThe most important thing to know about fuzzing soroban contracts:\nnever call `panic!` and related functions to handle errors that may\noccur during normal operation: the fuzzer views panics as bugs.\nInstead, use the Soroban-specific\n[`panic_with_error!`](https://docs.rs/soroban-sdk/latest/soroban_sdk/macro.panic_with_error.html)\nmacro, which the fuzzer can distinguish from a bare `panic!`.\n\nFor additional tips see the end of\n[this video presentation](https://www.youtube.com/watch?v=EzhMdIaPETo\u0026pp=ygUec3RlbGxhciBmdXp6aW5nIGJyaWFuIGFuZGVyc29u).\n\n\n## License\n\nMIT/Apache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrson%2Fsoroban-token-fuzzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrson%2Fsoroban-token-fuzzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrson%2Fsoroban-token-fuzzer/lists"}