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 using curl
curl
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
For more details follow the official Rust guide.
Linux with apt
apt
sudo apt install protobuf-compiler
macOS with brew
brew
brew install protobuf
For more details follow the official downloads page.
There are three crates we publish to support Rust development of Smart Contracts. These can be found on crates.io, 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.
Each of the crates ships with API documentation and examples for each of the functions. Docs are located at https://docs.rs. For example, the contract API documentation for version 0.5.1 is located at: https://docs.rs/casperlabs-contract/0.5.1/casperlabs_contract/contract_api/index.html
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-casperlabs
cargo install cargo-casperlabs
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.
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.
contract
tests
my-project
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
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.
build
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.
--release
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 build.rs 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/lib.rs. You can change the value of KEY and observe how the smart contract is recompiled and the test fails.
build.rs
cargo test
contract/src/lib.rs
KEY