Quickstart: Write a smart contract in Rust using Stylus
Stylus is currently tagged as an alpha
release. The code has not been audited, and should not be used in production scenarios. This documentation is currently in public preview.
To provide feedback, click the Request an update button at the top of this document, join the Arbitrum Discord, or reach out to our team directly by completing this form.
This quickstart will guide you through the process of deploying a smart contract in Rust using Stylus. We'll cover the following steps:
- Setting up your development environment
- Creating a new Stylus project
- Checking the validity of your program
- Deploying your program
Prerequisites
Rust toolchain
Follow the instructions on Rust Lang’s installation page to get a full Rust toolchain installed on your system. Make sure after installation that you have access to the programs rustup
, rustc
, and cargo
from your preferred command line terminal (programs should be added to your system’s PATH, more instructions available on Rust’s website)
VS Code
We recommend VS Code as the IDE of choice for developing Stylus contracts for its excellent Rust support. See code.visualstudio.com to install. 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 the code.
- Even Better TOML: Improves syntax highlighting and other features for TOML files, often used in Rust projects.
- crates: Helps manage Rust crate versions directly from the editor.
Setting Up a Developer Wallet
When working on a testnet, it's important to use a separate wallet that holds no real assets. This is because you'll often need to input private keys into your command line to manage transactions, and you should never use personal accounts for development purposes. So avoid using personal accounts for development.
If you're using MetaMask, here’s how to set up a new account:
- Open MetaMask and click the dropdown menu at the top middle of the plugin.
- Select “Add Account” to create a new wallet. Consider naming it something like "dev wallet" or "Stylus" to remind you of its purpose.
- You'll need the private key of this new account—and some testnet ETH (like Sepolia ETH) if you plan to deploy smart contracts. To get your private key, follow the steps provided on MetaMask’s support page.
This setup ensures that your real assets are safe while you develop and test on Arbitrum.
Never share your “secret recovery phrase” with anyone. Never enter it anywhere. A private key is valid for an individual account only, but a secret recovery phrase can be used to gain access to ALL accounts in your wallet.
To interact with the Stylus testnet, you need to manually configure two specific networks in your MetaMask plugin. Here’s how to set them up (for more details, refer to the MetaMask documentation):
- Arbitrum Sepolia:
- Network Name: Arbitrum Sepolia
- New RPC URL:
https://sepolia-rollup.arbitrum.io/rpc
- Chain ID: 421614
- Currency Symbol: ETH
- Block Explorer URL:
https://sepolia.arbiscan.io
- Arbitrum Stylus Testnet:
- Network Name: Stylus testnet
- New RPC URL:
https://stylus-testnet.arbitrum.io/rpc
- Chain ID: 23011913
- Currency Symbol: ETH
- Block Explorer URL:
https://stylus-testnet-explorer.arbitrum.io/
Acquiring and Bridging Testnet ETH
To engage with the Stylus testnet, you will first need to acquire Sepolia ETH and then bridge it over:
- Start by visiting a faucet to get testnet ETH. Here are a few options:
- Enter your wallet address.
- Click
Claim
to receive your testnet ETH. Some faucets may require additional steps.
If you obtained your ETH through the Bware Labs faucet, you don't need to bridge it, as this ETH is already on the Stylus testnet. If you used other faucets, your Sepolia ETH will be in your Sepolia testnet wallet and requires bridging to the Stylus testnet:
- Go to the Arbitrum Bridge.
- Choose Arbitrum Sepolia as the source and Stylus Testnet as the destination.
- Connect your wallet and authorize the bridge to access your tokens.
- Specify the amount of Sepolia ETH you want to bridge and initiate the transfer by clicking
Move funds to Stylus Testnet
. Make sure to keep some ETH in the source chain to cover transaction fees.
To verify the transfer, you can track the transaction on the Arbiscan block explorer for the source and the Stylus testnet block explorer for the destination.
To check the existence and balance of your testnet ETH, use the Stylus testnet block explorer. This tool allows you to view transaction details and confirm that your ETH is available in the testnet environment. Simply navigate to the provided link and enter your specific wallet address to see your balance and recent transactions.
Your First Stylus Program
cargo-stylus
is a command-line tool that simplifies the process of building, verifying, and deploying Arbitrum Stylus programs written in Rust. It functions as a plugin to Cargo, the standard build tool for Rust, allowing seamless integration into existing Rust workflows.
Installation
Ensure that Rust is installed on your system. You can install it from the Rust installation page.
Next, install the cargo-stylus
tool by executing the following command in your terminal:
cargo install --force cargo-stylus cargo-stylus-check
To prepare your Rust environment for building WebAssembly (WASM) modules, add WASM as a build target with this command:
rustup target add wasm32-unknown-unknown
After installation, cargo-stylus
is accessible through the cargo command. To view the available options and commands, use:
❯ cargo stylus --help
This will display the following usage options:
Cargo subcommand for developing Stylus projects
Usage: cargo stylus <COMMAND>
Commands:
new Create a new Rust project
export-abi Export a Solidity ABI
check Check a contract can be activated onchain
deploy Deploy a Stylus contract
replay Replay a transaction in gdb
trace Trace a transaction
c-gen Generate C code
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
Creating a new Stylus project
The cargo stylus command comes with useful commands such as new
, check
and deploy
, and export-abi
for developing and deploying Stylus programs to Arbitrum chains. Here's a common workflow:
Start a new Stylus project with
cargo stylus new <YOUR_PROJECT_NAME>
This command clones a local copy of the stylus-hello-world repository, which contains a Rust implementation of the Solidity Counter
smart contract example. For further details, refer to the README in the stylus-hello-world
repository.
Alternatively, you can use cargo stylus new --minimal <YOUR_PROJECT_NAME>
to create a more barebones example with a Stylus entrypoint locally, useful for projects that don’t need all the Solidity plumbing.
Then, develop your Rust program normally and take advantage of all the features the stylus-sdk has to offer.
Checking your Stylus project is valid
To check whether or not your program will successfully deploy and activate onchain, use the cargo stylus check
subcommand:
cargo stylus check
This command verifies that your program can be deployed and activated onchain without a transaction, by connecting to a specified JSON-RPC endpoint. The default endpoint is the Arbitrum Stylus testnet: https://stylus-testnet.arbitrum.io/rpc
. For additional options, consult the help guide: cargo stylus check --help
.
A successful validation will display something like:
Finished `release` profile [optimized] target(s) in 0.20s
Reading WASM file at [YOUR-DIRECTORY]/target/wasm32-unknown-unknown/release/deps/stylus_hello_world.wasm
Uncompressed WASM size: 25.0 KB
Compressed WASM size to be deployed onchain: 9.0 KB
Connecting to Stylus RPC endpoint: https://stylus-testnet.arbitrum.io/rpc
Program succeeded Stylus onchain activation checks with Stylus version: 1
If the check fails, the output provides detailed error information, such as:
Reading WASM file at bad-export.wat
Compressed WASM size: 55 B
Stylus checks failed: program predeployment check failed when checking against
ARB_WASM_ADDRESS 0x0000…0071: (code: -32000, message: program activation failed: failed to parse program)
Caused by:
binary exports reserved symbol stylus_ink_left
Location:
prover/src/binary.rs:493:9, data: None)
For guidelines on what constitutes a valid or invalid WASM program, refer to VALID_WASM.
Deploying Your Program
Once validated, you can deploy your program using the cargo stylus deploy
subcommand. Start by estimating the gas required for deployment. --private-key-path
is a text file containing your private key.
cargo stylus deploy \
--private-key-path=<PRIVKEY_FILE_PATH> \
--estimate-gas-only
Among other details, you'll see an estimated gas cost for deployment:
...
====DEPLOYMENT====
Deploying program to address 0xD6bC450ED8D8054b7c971f6d42631Fc4ed59A099
Base fee: 0.100000000 gwei
Estimated gas for deployment: 11266639 gas units
Next, attempt an actual deployment. Two transactions will be sent onchain.
cargo stylus deploy \
--private-key-path=<PRIVKEY_FILE_PATH>
You'll see details about the deployment process, such as:
...
Uncompressed WASM size: 25.0 KB
Compressed WASM size to be deployed onchain: 9.0 KB
Connecting to Stylus RPC endpoint: https://stylus-testnet.arbitrum.io/rpc
Program succeeded Stylus onchain activation checks with Stylus version: 1
Deployer address: 0x44E623584f90D6FBaBe930221d47E0De4248e935
====DEPLOYMENT====
Deploying program to address 0xD6bC450ED8D8054b7c971f6d42631Fc4ed59A099
Base fee: 0.100000000 gwei
Estimated gas for deployment: 11266639 gas units
Submitting deployment tx...
Confirmed deployment tx 0xc95d7fab996934b38d2eb5e4559977aa222a658fb13e994bdea0f74746219ad5
Gas units used 10318928, effective gas price 0.100000000 gwei
Transaction fee: 0.001031892800000000 ETH
====ACTIVATION====
Activating program at address 0xD6bC450ED8D8054b7c971f6d42631Fc4ed59A099
Base fee: 0.100000000 gwei
Estimated gas for activation: 14224495 gas units
Submitting activation tx...
Confirmed activation tx 0x908459dab815e1403c36e21838673ac55877665c9d95c9c87bfb1c4543eab0e8
Gas units used 14184722, effective gas price 0.100000000 gwei
Transaction fee: 0.001418472200000000 ETH
You can verify the deployment and activation of your program on the Stylus testnet block explorer.
For further deployment options and transaction details, consult cargo stylus deploy --help
.
Deploying Non-Rust WASM Projects
The Stylus CLI tool can also deploy non-Rust, WASM projects to Stylus by specifying the WASM file directly with the --wasm-file-path
flag to any of the cargo stylus commands.
Even WebAssembly Text (WAT) 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.
For example:
(module
(type $t0 (func (param i32) (result i32)))
(func $add_one (export "add_one") (type $t0) (param $p0 i32) (result i32)
get_local $p0
i32.const 1
i32.add))
can be saved as add.wat
and used as cargo stylus check --wasm-file-path=add.wat
or cargo stylus deploy --priv-key-path=<YOUR PRIV KEY FILE PATH> --wasm-file-path=add.wat
Exporting Solidity ABIs
Stylus Rust projects that use the stylus-sdk have the option of exporting Solidity ABIs. The cargo stylus tool also makes this easy with the export-abi
command:
cargo stylus export-abi