Using Stylus CLI
This guide will get you started using cargo stylus, a CLI toolkit to help developers manage, compile, and optimize their Stylus contracts efficiently.
This overview is meant to help discover cargo stylus' tools and learn to use them effectively.
Installing cargo stylus
Cargo stylus is available as a plugin to the standard cargo tool used for developing Rust programs.
Prerequisites
Rust toolchain
Follow the instructions on Rust Lang's installation page to install a complete Rust toolchain (v1.81 or older, v1.82 is currently not supported) on your system. After installation, ensure you can access the programs rustup, rustc, and cargo from your preferred terminal application.
VS Code
We recommend VSCode as the IDE of choice for its excellent Rust support, but feel free to use another text editor or IDE if you're comfortable with those.
Some helpful VS Code extensions for Rust development:
- rust-analyzer: Provides advanced features like smart code completion and on-the-fly error checks
- Error Lens: Immediately highlights errors and warnings in your code
- Even Better TOML: Improves syntax highlighting and other features for TOML files, often used in Rust projects
- Dependi: Helps manage Rust crate versions directly from the editor
Docker
The testnode we will use as well as some cargo stylus commands require Docker to operate.
You can download Docker from Docker's website.
Foundry's Cast
Foundry's Cast is a command-line tool that allows you to interact with your EVM contracts.
Nitro devnode
Stylus is available on Arbitrum Sepolia, but we'll use nitro devnode which has a pre-funded wallet saving us the effort of wallet provisioning or running out of tokens to send transactions.
git clone https://github.com/OffchainLabs/nitro-devnode.git
cd nitro-devnode
./run-dev-node.sh
Installation
In your terminal, run:
cargo install --force cargo-stylus
Add WASM (WebAssembly) as a build target for the specific Rust toolchain you are using. The below example sets your default Rust toolchain to 1.80 as well as adding the WASM build target:
rustup default 1.80
rustup target add wasm32-unknown-unknown --toolchain 1.80
You can verify that cargo stylus is installed by running cargo stylus -V in your terminal, returning something like:stylus 0.5.6
Using cargo stylus
Cargo Stylus commands reference
| Command | Description | Arguments | Options | Examples usage |
|---|---|---|---|---|
| new | Create a new Stylus project | • name: Project name (required) | • --minimal: Create a minimal contract | cargo stylus new <YOUR_PROJECT_NAME> |
| init | Initialize a Stylus project in current directory | • --minimal: Create a minimal contract | cargo stylus init --minimal | |
| export-abi | Export a Solidity ABI | • --output: Output file (defaults to stdout) • --json: Write JSON ABI using solc | cargo stylus export-abi --json | |
| activate | Activate an already deployed contract | • --address: Contract address to activate | • --data-fee-bump-percent: Percent to bump estimated fee (default 20%) • --estimate-gas: Only estimate gas without sending tx | cargo stylus new <YOUR_PROJECT_NAME> |
| cache | Cache contract using Stylus CacheManager | • bid: Place bid on contract • status: Check contract status • suggest-bid: Get suggested minimum bid | cargo stylus cache bid --address <CONTRACT_ADDRESS> | |
| check | Check a contract | • --wasm-file: WASM to check • --contract-address: Deploy address | ||
| deploy | Deploy a contract | • --contract-address <CONTRACT_ADDRESS> Where to deploy and activate the contract (defaults to a random address) | • --estimate-gas: Only perform estimation • --no-verify: Skip reproducible container • --cargo-stylus-version: Version for Docker image • --source-files-for-project-hash <SOURCE_FILES_FOR_PROJECT_HASH> Path to source files to include in the project hash • --max-fee-per-gas-gwei <MAX_FEE_PER_GAS_GWEI> Optional max fee per gas in gwei units • --wasm-file <WASM_FILE> The WASM to check (defaults to any found in the current directory) |
cargo stylus deploy \ --endpoint='http://localhost:8547' \ --private-key="<CONTRACT_ADDRESS>" \ --estimate-gas
|
| verify | Verify contract deployment | • --deployment-tx: Hash of deployment tx | • --no-verify: Skip reproducible container
• --cargo-stylus-version: Version for Docker image | |
| cgen | Generate C code bindings | • --input: Input file path
• --out_dir: Output directory path | | |
| replay | Replay transaction in gdb | • -t, --tx <TX> Tx to replay | • -p, --project <PROJECT>: Project path [default: .]
• -u, --use-native-tracer: If set, use the native tracer instead of the JavaScript one. Notice the native tracer might not be available in the node
• -s, --stable-rust: Whether to use stable Rust. Note that nightly is needed to expand macros
• --stable-rust: Use stable Rust
| cargo stylus replay --tx <TX> |
| trace | Trace a transaction | • --tx: Transaction hash | • --endpoint: RPC endpoint
• --project: Project path
• --use-native-tracer: Use native | |
Common options
These options are available across multiple commands:
| Option | Description |
|---|---|
| --endpoint | Arbitrum RPC endpoint (default: http://localhost:8547) |
| --verbose | Print debug info |
| --source-files-for-project-hash | Paths to source files for project hash |
| --max-fee-per-gas-gwei | Optional max fee per gas in gwei |
Authentication options
Available for commands involving transactions:
| Option | Description |
|---|---|
| --private-key-path | Path to file containing hex-encoded private key |
| --private-key | Private key as hex string (exposes to shell history) |
| --keystore-path | Path to Ethereum wallet keystore file |
| --keystore-password-path | Keystore password file path |
How-tos
| Topic | Description |
|---|---|
| Learn how to optimize WASM binaries | The cargo-stylus tool allows you to optimize WebAssembly (WASM) binaries, ensuring that your contracts are as efficient as possible. |
| Debug Stylus transactions | A guide to debugging transactions, helping you identify and fix issues. Gain insights into your Stylus contracts by debugging transactions. |
| Verify contracts | Ensure that your Stylus contracts are correctly verified. Step-by-step instructions on how to verify your contracts using cargo-stylus. |
| Run a Stylus dev node | Learn how to run a local Arbitrum dev node to test your Stylus contracts. |