Getting Started

This guide covers the basic tools you will need to set up your first Casper smart contract. You will also be able to build a sample smart contract and run a few basic tests on it on your local machine.

Casper’s blockchain is built upon the Rust programming language and compiles down to WebAssembly. The Rust contract SDK is the easiest way to get started with smart contract development. This guide will walk you through the steps to set up your development environment and build your first contract.

Video Tutorial

For a video walkthrough of this guide, feel free to check out this quick-start video.

Prerequisites

Installing Rust

Install the Rust programming language if you don’t already have it on your computer.

The official Rust guide recommends installing Rust by using curl.

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

You can also use brew on MacOS or apt on Linux to install Rust.

Once you finish installing Rust, check your version:

rustup --version

Your terminal output should resemble something like the following (note: at the time of the writing of this tutorial, the latest version of Rust was 1.23.1 and may differ for you):

$ rustup --version
rustup 1.23.1 (3df2264a9 2020-11-30)
info: This is the version for the rustup toolchain manager, not the rustc compiler.
info: The currently active `rustc` version is `rustc 1.52.0-nightly (0fc6756b4 2021-02-08)`

Configure Nightly Rust

After installing Rust you need to install and set the Rust nightly toolchain as the default.

$ rustup install nightly
$ rustup default nightly

Casper Rust Packages

We publish three crates on crates.io to support smart contract development with Rust:

  • Casper Contract - a library supporting communication with the blockchain. This is the main library you will need to write smart contracts.

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

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

A crate is a compilation unit, which can be compiled into a binary or a library.

API Documentation for Smart Contracts

Each of the Casper crates comes with API documentation and examples for each function, located at https://docs.rs. The contract API documentation is specific for a given version. For example, you can find documentation for version 0.7.6 at https://docs.rs/casper-contract/0.7.6.

Installing Dependencies

1. CMake

CMake is a popular build tool that we will utilize, and you may very well have it already installed. If you do, make sure that you have the latest version (currently 3.19.4). If you need to install or upgrade it, follow the steps located here: https://cmake.org/install/. Once installed, check your version as shown below.

cmake --version

Development Environment Setup

Installing the Casper Crates

The best and 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, a runtime environment and a testing framework with a simple test. Cargo is a build system and package manager for Rust (much like pip if you are familiar with Python). It is possible to use this configuration in your CI/CD pipeline as well.

cargo install cargo-casper

If you run into any issues with this command and you have not recently installed Rust from scratch, please make sure to update your Rust version with this command:

rustup update

Creating a Project

You can create a new sample project very easily with the Casper crate. For example, let’s say that I want to create a project named my-project for this tutorial (you can choose a different name if you wish), then I can simply run the command:

cargo casper my-project

If you look inside the newly-created my-project folder, you will find two crates: contract and tests. 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 smart contract test.

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 Rust ecosystem tools 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. You can see more information by running:

cargo casper --help

To build the project, go into the my-project folder, install the Rust toolchain and specify the target build as WebAssembly (wasm32):

cd my-project
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. Inside the contract folder, run the following command:

cd contract
cargo build --release

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.

Inside of the folder, you will now see a target folder that will contain the compiled smart contract named contract.wasm at my-project/contract/target/wasm32-unknown-unknown/release/contract.wasm.

Test the Contract

In addition to creating the contract, the Casper crate also automatically created sample tests in the my-project/tests folder.

Run the tests from the project folder, not from the tests folder. In this case, you need to navigate from the contract folder into my-project and run make test.

cd ..
make test

After the compilation finishes, the test should run and you should see output similar to this message in your terminal:

cd contract && cargo build --release --target wasm32-unknown-unknown
   Finished release [optimized] target(s) in 0.04s
wasm-strip contract/target/wasm32-unknown-unknown/release/contract.wasm 2>/dev/null | true
mkdir -p tests/wasm
cp contract/target/wasm32-unknown-unknown/release/contract.wasm tests/wasm
cd tests && cargo test
   Finished test [unoptimized + debuginfo] target(s) in 0.08s
   Running unittests (target/debug/deps/integration_tests-f54c86e3719442e8)

running 2 tests
test tests::should_error_on_missing_runtime_arg - should panic ... ok
test tests::should_store_hello_world ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.07s

The Casper local environment provides an in-memory virtual machine against which you can run your contract for testing. When you run the test crate, it will automatically build the smart contract in release mode and then run a series of tests against it in the Casper runtime environment. The custom build script is named build.rs if you are interested in looking more into it.

Note: Since the test script automatically builds the contract, during development you only need to run the command make test without the need for cargo build.

A successful test run indicates that your smart contract environment is set up correctly.

As a brief example, open up my-project/contract/src/main.rs in your editor, modify the KEY_NAME value in the contract, and then rerun the make test command. You should observe that the smart contract recompiles and the test fails now.

Developers Writing Smart Contracts