{"id":13543879,"url":"https://github.com/OffchainLabs/cargo-stylus","last_synced_at":"2025-04-02T13:31:13.427Z","repository":{"id":191746606,"uuid":"682241519","full_name":"OffchainLabs/cargo-stylus","owner":"OffchainLabs","description":"Cargo subcommand for developing Arbitrum Stylus projects in Rust","archived":false,"fork":false,"pushed_at":"2025-03-25T21:09:32.000Z","size":1213,"stargazers_count":69,"open_issues_count":11,"forks_count":51,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-03-27T05:09:03.696Z","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/OffchainLabs.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-08-23T18:43:45.000Z","updated_at":"2025-03-25T19:49:43.000Z","dependencies_parsed_at":"2024-01-16T17:02:40.416Z","dependency_job_id":"bdf53243-7a80-4194-976e-c8b23edce653","html_url":"https://github.com/OffchainLabs/cargo-stylus","commit_stats":null,"previous_names":["offchainlabs/cargo-stylus"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OffchainLabs%2Fcargo-stylus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OffchainLabs%2Fcargo-stylus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OffchainLabs%2Fcargo-stylus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OffchainLabs%2Fcargo-stylus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OffchainLabs","download_url":"https://codeload.github.com/OffchainLabs/cargo-stylus/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246823680,"owners_count":20839760,"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-08-01T11:00:37.582Z","updated_at":"2025-04-02T13:31:08.406Z","avatar_url":"https://github.com/OffchainLabs.png","language":"Rust","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# Cargo Stylus\n\n[![linux](https://github.com/OffchainLabs/cargo-stylus/actions/workflows/linux.yml/badge.svg)](https://github.com/OffchainLabs/cargo-stylus/actions/workflows/linux.yml) [![mac](https://github.com/OffchainLabs/cargo-stylus/actions/workflows/mac.yml/badge.svg)](https://github.com/OffchainLabs/cargo-stylus/actions/workflows/mac.yml) [![lint](https://github.com/OffchainLabs/cargo-stylus/actions/workflows/check.yml/badge.svg)](https://github.com/OffchainLabs/cargo-stylus/actions/workflows/check.yml)\n\nA cargo subcommand for building, verifying, and deploying Arbitrum Stylus WASM contracts in Rust.\n\n\u003e [!NOTE]  \n\u003e Stylus contract verification will only be supported on Arbiscan for contracts deployed using cargo stylus `v0.5.0` or higher. We highly recommend deploying on Arbitrum Sepolia and verify your contracts on Sepolia Arbiscan first before going to mainnet.\n\n## Quick Start\n\n![Image](./header.png)\n\n### Installing With Cargo\n\nInstall [Rust](https://www.rust-lang.org/tools/install), and then install the plugin using the Cargo tool:\n\n```\ncargo install cargo-stylus\n```\n\nAdd the `wasm32-unknown-unknown` build target to your Rust compiler:\n\n```\nrustup target add wasm32-unknown-unknown\n```\n\nYou should now have it available as a Cargo subcommand:\n\n```\ncargo stylus --help\n\nCargo command for developing Arbitrum Stylus projects\n```\n\n### Building the Project Locally\nInstall [Rust](https://www.rust-lang.org/tools/install)\n\nClone the repo to your local device\n```\ngit clone https://github.com/OffchainLabs/cargo-stylus.git\ncd cargo-stylus\n```\n\nRun the `install.sh` script to build and install the local binaries to cargo\n```\n./install.sh\n```\n\nAdd the `wasm32-unknown-unknown` build target to your Rust compiler:\n```\nrustup target add wasm32-unknown-unknown\n```\n\nWhen testing changes to your local repository, ensure that commands such as `cargo stylus deploy` are run with the `--no-verify` flag to opt out of using Docker\n\nIf your changes are localized to a single package, you can avoid building and reinstalling all packages by running\n```\ncargo install --path \u003cworkspace_pkg_with_changes\u003e\n```\n\n### Overview\n\nThe cargo stylus command comes with useful commands such as `new`, `check` and `deploy`, and `export-abi` for developing and deploying Stylus contracts to Arbitrum chains. Here's a common workflow:\n\nStart a new Stylus project with\n\n```\ncargo stylus new \u003cYOUR_PROJECT_NAME\u003e\n```\n\nThe command above clones a local copy of the [stylus-hello-world](https://github.com/OffchainLabs/stylus-hello-world) starter project, which implements a Counter smart contract in Rust. See the [README](https://github.com/OffchainLabs/stylus-hello-world/blob/main/README.md) of stylus-hello-world for more details.\n\nYou can also use `cargo stylus new --minimal \u003cYOUR_PROJECT_NAME\u003e` to create a more barebones example with a Stylus entrypoint locally.\n\n### Testnet Information\n\nAll testnet information, including faucets and RPC endpoints can be found [here](https://docs.arbitrum.io/stylus/reference/testnet-information).\n\n\n### Developing With Stylus\n\nThen, develop your Rust contract normally and take advantage of all the features the [stylus-sdk](https://github.com/OffchainLabs/stylus-sdk-rs) has to offer. To check whether or not your contract will successfully deploy and activate onchain, use the `cargo stylus check` subcommand:\n\n```\ncargo stylus check\n```\n\nThis command will attempt to verify that your contract can be deployed and activated onchain without requiring a transaction by specifying a JSON-RPC endpoint. By default, it will use the public URL of the Stylus testnet as its endpoint. See [here](https://docs.arbitrum.io/stylus/reference/testnet-information) for available testnet RPC URLs. See `cargo stylus check --help` for more options.\n\nIf the command above fails, you'll see detailed information about why your WASM will be rejected:\n\n```\nReading WASM file at bad-export.wat\nCompressed WASM size: 55 B\nStylus checks failed: contract predeployment check failed when checking against\nARB_WASM_ADDRESS 0x0000…0071: (code: -32000, message: contract activation failed: failed to parse contract)\n\nCaused by:\n    binary exports reserved symbol stylus_ink_left\n\nLocation:\n    prover/src/binary.rs:493:9, data: None)\n```\n\nTo read more about what counts as valid vs. invalid user WASM contracts, see [VALID_WASM](./main/VALID_WASM.md).\n\nIf your contract succeeds, you'll see the following message:\n\n```\nFinished release [optimized] target(s) in 1.88s\nReading WASM file at hello-stylus/target/wasm32-unknown-unknown/release/hello-stylus.wasm\nCompressed WASM size: 3 KB\nContract succeeded Stylus onchain activation checks with Stylus version: 1\n```\n\nOnce you're ready to deploy your contract onchain, you can use the `cargo stylus deploy` subcommand as follows:\n\nFirst, we can estimate the gas required to perform our deployment and activation with:\n\n```\ncargo stylus deploy \\\n  --private-key-path=\u003cPRIVKEY_FILE_PATH\u003e \\\n  --estimate-gas\n```\n\nand see:\n\n```\nCompressed WASM size: 3 KB\nDeploying contract to address 0x457b1ba688e9854bdbed2f473f7510c476a3da09\nEstimated gas: 12756792\n```\n\nNext, attempt an actual deployment. Two transactions will be sent onchain.\n\n```\ncargo stylus deploy \\\n  --private-key-path=\u003cPRIVKEY_FILE_PATH\u003e\n```\n\nand see:\n\n```\nCompressed WASM size: 3 KB\nDeploying contract to address 0x457b1ba688e9854bdbed2f473f7510c476a3da09\nEstimated gas: 12756792\nSubmitting tx...\nConfirmed tx 0x42db…7311, gas used 11657164\nActivating contract at address 0x457b1ba688e9854bdbed2f473f7510c476a3da09\nEstimated gas: 14251759\nSubmitting tx...\nConfirmed tx 0x0bdb…3307, gas used 14204908\n```\n\n## Compiling and Checking Stylus Contracts\n\n**cargo stylus check**\n\nInstruments a Rust project using Stylus. This command runs compiled WASM code through Stylus instrumentation checks and reports any failures. It **verifies the contract can compile onchain** by making an eth_call to a Arbitrum chain RPC endpoint.\n\n```\nUsage: cargo stylus check [OPTIONS]\n```\n\nSee `--help` for all available flags and default values.\n\n## Deploying Stylus Contracts\n\n**cargo stylus deploy**\n\nInstruments a Rust project using Stylus and by outputting its brotli-compressed WASM code. Then, it submits **two transactions** by default: the first **deploys** the WASM contract code to an address and the second triggers an **activation onchain**. Developers can choose to split up the deploy and activate steps via this command as desired.\n\n```\nUsage: cargo stylus deploy [OPTIONS]\n```\n\nSee `--help` for all available flags and default values.\n\n## Verifying Stylus Contracts\n\nSee [here](https://hackmd.io/bpeMnrzbSvO4mohhvkrKqw)\n\n## Deploying Non-Rust WASM Projects\n\nThe Stylus tool can also be used to deploy non-Rust, WASM projects to Stylus by specifying the WASM file directly with the `--wasm-file` flag to any of the cargo stylus commands.\n\nEven WebAssembly Text [(WAT)](https://www.webassemblyman.com/wat_webassembly_text_format.html) files are supported. This means projects that are just individual WASM files can be deployed onchain without needing to have been compiled by Rust. WASMs produced by other languages, such as C, can be used with the tool this way.\n\nFor example:\n\n```js\n(module\n    (memory 0 0)\n    (export \"memory\" (memory 0))\n    (type $t0 (func (param i32) (result i32)))\n    (func $add_one (export \"add_one\") (type $t0) (param $p0 i32) (result i32)\n        local.get $p0\n        i32.const 1\n        i32.add)\n    (func (export \"user_entrypoint\") (param $args_len i32) (result i32)\n        (i32.const 0)\n    ))\n```\n\ncan be saved as `add.wat` and used as `cargo stylus check --wasm-file=add.wat` or `cargo stylus deploy --wasm-file=add.wat`.\n\n## Exporting Solidity ABIs\n\nStylus Rust projects that use the [stylus-sdk](https://github.com/OffchainLabs/stylus-sdk-rs) have the option of exporting Solidity ABIs. The cargo stylus tool also makes this easy with the `export-abi` command:\n\n```\ncargo stylus export-abi\n```\n\n## Optimizing Binary Sizes\n\nBrotli-compressed, Stylus contract WASM binaries must fit within the **24Kb** [code-size limit](https://ethereum.org/en/developers/tutorials/downsizing-contracts-to-fight-the-contract-size-limit/) of Ethereum smart contracts. By default, the `cargo stylus check` will attempt to compile a Rust contract into WASM with reasonable optimizations and verify its compressed size fits within the limit. However, there are additional options available in case a contract exceeds the 24Kb limit from using default settings. Deploying smaller binaries onchain is cheaper and better for the overall network, as deployed WASM contracts will exist on the Arbitrum chain's storage forever.\n\nWe recommend optimizing your Stylus contract's sizes to smaller sizes, but keep in mind the safety tradeoffs of using some of the more advanced optimizations. However, some small contracts when compiled to much smaller sizes can suffer performance penalties.\n\nFor a deep-dive into the different options for optimizing binary sizes using cargo stylus, see [OPTIMIZING_BINARIES.md](./main/OPTIMIZING_BINARIES.md).\n\n## License\n\nCargo Stylus is distributed under the terms of both the MIT license and the Apache License (Version 2.0).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOffchainLabs%2Fcargo-stylus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FOffchainLabs%2Fcargo-stylus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOffchainLabs%2Fcargo-stylus/lists"}