Arbitrum docsReference
Stylus Rust SDK overview
Architecture, crate structure, feature flags, and documentation index for the Stylus Rust SDK v0.10.7
The Stylus Rust SDK (v0.10.7) lets you write Solidity ABI-equivalent smart contracts in Rust, compiled to WebAssembly and executed on Arbitrum chains. For a conceptual introduction, see Stylus: A Gentle Introduction. To deploy your first contract, see the Quickstart.
The SDK is built on Alloy, the standard Rust Ethereum primitive library. Because both share the same types, Stylus contracts are compatible with the broader Rust Ethereum ecosystem.
The SDK has been audited by OpenZeppelin:
- Initial Stylus Rust SDK audit (September 2024)
- Stylus SDK v0.10 audit (December 2025)
- Stylus SDK PR #370 audit (December 2025)
All reports are listed on the security audit reports page.
SDK architecture
The SDK is a Cargo workspace of six crates. Most developers only interact with stylus-sdk and cargo-stylus directly — the others are internal dependencies.
| Crate | Purpose |
|---|---|
stylus-sdk | Main SDK — storage types, ABI encoding, call abstractions, crypto, deploy, and the prelude module |
stylus-proc | Procedural macros: #[entrypoint], #[public], #[constructor], sol_storage!, sol_interface! |
stylus-core | Core trait definitions (Host, HostAccess) shared across the workspace |
stylus-test | Testing framework with TestVM for unit-testing contracts without a blockchain |
stylus-tools | Deployment, activation, verification, and caching operations (used by cargo-stylus) |
cargo-stylus | CLI tool for building, deploying, debugging, and managing Stylus contracts |
Requirements: Rust 1.91.0 or later (pinned in rust-toolchain.toml). Contracts compile to the wasm32-unknown-unknown target.
Feature flags
The stylus-sdk crate exposes these Cargo features:
| Feature | Default | Description |
|---|---|---|
mini-alloc | Yes | Uses an efficient WASM allocator. Disable to use a custom global allocator |
export-abi | No | Enables ABI export via cargo stylus export-abi. Adds debug and uses tiny-keccak |
debug | No | Enables the console! debugging macro for printing to the Blockchain Explorer's trace view |
hostio | No | Makes the low-level hostio module public for direct host I/O access |
stylus-test | No | Enables the testing module with TestVM for writing unit tests without deploying |
reentrant | No | Enables reentrancy support across stylus-proc, stylus-core, and stylus-test |
Public modules
The stylus-sdk crate re-exports these modules from its root:
| Module | Description |
|---|---|
abi | ABI encoding and decoding types |
call | Cross-contract call abstractions (static calls, delegate calls, value transfers) |
crypto | Cryptographic utilities (keccak256) |
debug | The console! macro for trace-level logging (requires the debug feature) |
deploy | Contract deployment via RawDeploy |
host | VM host interface (self.vm()) for accessing block context, message data, and storage |
hostio | Low-level host I/O FFI bindings (requires the hostio feature to be public) |
methods | Method routing utilities |
prelude | Common imports — re-exports the types most contracts need |
storage | Persistent storage types (StorageU256, StorageAddress, StorageMap, StorageVec, etc.) |
Documentation index
Fundamentals
| Article | Description |
|---|---|
| Structure of a contract | Project layout, the #[entrypoint] macro, and #[public] methods |
| Global variables and functions | Access blockchain context through self.vm() — message sender, block info, and crypto functions |
| Contracts | Storage definition, method declarations, and the contract lifecycle |
| Writing tests | Unit test contracts with TestVM without deploying to a blockchain |
Data types
| Article | Description |
|---|---|
| Primitives | Rust primitives (bool, integers, addresses) with automatic ABI encoding and Solidity type mappings |
| Compound types | Arrays, vectors, tuples, and custom structs |
| Storage | Persistent contract state using storage types and the sol_storage! macro |
| Conversions between types | Converting between Rust types and Solidity-compatible types |
Advanced topics
| Article | Description |
|---|---|
| Rust to Solidity differences | Key differences between writing contracts in Solidity versus Stylus Rust |
| Recommended packages | Third-party Rust crates that work well with Stylus |
| Minimal entrypoint contracts | Lightweight contracts with custom entrypoints for maximum gas efficiency |
| Hostio exports | Low-level host I/O functions for advanced contract behavior |
Using the CLI
| Article | Description |
|---|---|
| Commands reference | Complete reference for all cargo stylus commands, flags, and aliases |
| Verify contracts | Verify deployed contracts using reproducible builds |
| Exporting ABI | Generate Solidity-compatible ABI files for frontend integration |
| Debugging with replay | Debug transactions by replaying them locally with GDB, LLDB, or StylusDB |
| Optimizing WASM binary size | Reduce contract size for lower deployment costs |
| Deploying non-Rust WASM contracts | Deploy contracts written in C, C++, or other languages that compile to WebAssembly |
WASM concepts
| Article | Description |
|---|---|
| WebAssembly | How WASM compilation, deployment, and execution work in Arbitrum Nitro |
| VM differences | Behavioral differences between Stylus WASM execution and traditional EVM |
| Activation | The contract activation process required before a Stylus contract can execute |
| Caching strategy | Leveraging the WASM caching system for contract performance |
Troubleshooting
| Article | Description |
|---|---|
| Configuration reference | Complete reference for Stylus.toml, Cargo.toml, and rust-toolchain.toml options. |
| Troubleshooting | Find solutions to common issues encountered when building and deploying Stylus contracts. |
External references
| Resource | Description |
|---|---|
| Stylus by Example | Practical, annotated code examples covering common patterns |
| Rust SDK on docs.rs | API documentation generated from source |
| Source code | Complete source for the SDK workspace |
How is this guide?