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.

Prerequisites

Install Rust

The recommended way to from the official Rust guide to install Rust is by using curl

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

It is also possible to use brew or apt to install Rust.

Update cmake

Version 3.14.1 or greater is required.

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.

SDK

For a video walkthrough of these steps, feel free to check out this quick start video.

Available Packages

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

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

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

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

API Level Documentation for Smart Contracts

Each of the crates ships with API documentation and examples for each of the functions. Docs are located at https://docs.rs. The contract API documentation is specific for a given version, ex: for version 0.5.1 is located at: https://docs.rs/casper-contract/0.1.0

Development Environment Setup

The best & fastest way to set up a Casper Rust Smart Contract project is to use cargo-casper. 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.

$ cargo install cargo-casper
$ cargo casper 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 Casper virtual machine, and a basic test of the smart contract.

Compiling to wasm

The Casper 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. Casper Contracts support Rust tooling such as clippy for linting contracts. Feel free to use them!

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 casper --help

Set up your wasm compilation rust toolchain by doing the following

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 & verify your environment is correct

The test crate will build the contract and test it in a Casper 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/main.rs. You can change the value of KEY and observe how the smart contract is recompiled and the test fails.