Setting Up the Rust Contract SDK

The SDK is the easiest way to get started with Smart Contract development. This guide will walk you through the steps to get set up.


Install Rust

Install Rust using curl

curl --proto '=https' --tlsv1.2 -sSf | sh

For more details follow the official Rust guide.

Install Google protobuf compiler

Linux with apt

sudo apt install protobuf-compiler

macOS with brew

brew install protobuf

For more details follow the official downloads page.

CasperLabs SDK

Available Packages

There are three crates we publish to support Rust development of Smart Contracts. These can be found on, and are:

  • CasperLabs Contract - library that supports communication with the blockchain. That’s the main library to use when writing smart contracts.

  • CasperLabs Test Support - in-memory virtual machine you can test your smart contracts against.

  • CasperLabs Types - library with types we use across the Rust ecosystem.

Technical Documentation for the Contract API

Each of the crates ships with API documentation and examples for each of the functions. Docs are located at For example, the contract API documentation for version 0.5.1 is located at:

Cargo CasperLabs

The best way to set up a CasperLabs Rust Smart Contract project is to use cargo-casperlabs. When you use this, it will set the project up with a simple contract and a runtime environment/testing framework with a simple test. It’s possible to use this configuration in your CI/CD pipeline as well. Instructions are also available on GitHub.

cargo install cargo-casperlabs

Develop Smart Contracts

In this tutorial we will use cargo-casperlabs. The CasperLabs blockchain uses WebAssembly (Wasm) in its runtime environment. Compilation targets for Wasm are available for Rust, giving developers access to all the tools in the Rust ecosystem when developing smart contracts.

Create a new project

cargo casperlabs my-project

This step will create two crates called contract and tests inside a new folder called my-project. This is a complete basic smart contract that saves a value, passed as an argument, on the blockchain. The tests crate provides a runtime environment of the CasperLabs virtual machine, and a basic test of the smart contract.

Configure Rust for Building the Contract and Test

The project requires a specific nightly version of Rust, and requires a Wasm target to be added to that Rust version. The steps to follow are shown by running

cargo casperlabs --help

These steps can be performed by running

cd my-project/contract
rustup install $(cat rust-toolchain)
rustup target add --toolchain $(cat rust-toolchain) wasm32-unknown-unknown

Build the Contract

The next step is to compile the smart contract into Wasm.

cd my-project/contract
cargo build --release

The build command produces a smart contract at my-project/contract/target/wasm32-unknown-unknown/release/contract.wasm.

NOTE: It’s important to build the contract using --release as a debug build will produce a contract which is much larger and more expensive to execute.

Test the Contract

The test crate will build the contract and test it in a CasperLabs runtime environment. A successful test run indicates that the smart contract environment is set up correctly.

cd ../tests
cargo test

The tests crate has a file: effectively a custom build script. It’s executed every time before running tests and it compiles the smart contract in release mode for your convenience. In practice, that means we only need to run cargo test in the tests crate during the development. Go ahead and modify contract/src/ You can change the value of KEY and observe how the smart contract is recompiled and the test fails.