Getting Started with Rust
This guide covers the basic tools you will need to write 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. This guide will walk you through the steps to set up your development environment and write your first contract.
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
The installation script automatically adds Rust to your system PATH after your next login. To start using Rust right away instead of restarting your terminal, run the following command in your shell to add Rust to your system PATH manually:
source $HOME/.cargo/env
You can also use brew on MacOS or apt on Linux to install Rust.
Once you finish installing Rust, check your version:
rustup --version
You will need the latest nightly toolchain to develop smart contracts in Rust. Please refer to the Rust Documentation on Channels and the Rust Documentation on Toolchains for further information.
We recommend setting up the rust-toolchain in the top level directory of your project.
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 - a 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. 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
Output:
cmake version 3.20.0 (or above)
CMake suite maintained and supported by Kitware (kitware.com/cmake).
Development Environment Setup
Installing the Casper Crates
The best and fastest way to set up a Casper Rust project is to use cargo casper. Using this will create 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, or npm and yarn for those familiar with Javascript). It is also possible to use this configuration in your CI/CD pipeline.
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.
- Note: Wasm allows for the use of other languages, including but not limited to: C/C++, C#, Go, Julia, Lobster and ZIG.
To compile the smart contract into Wasm, go into the my-project folder, and run the following commands:
cd my-project
make prepare
make build-contract
You can find the compiled contract on this path: my-project/contract/target/wasm32-unknown-unknown/release/contract.wasm.
Linting
Casper contracts support Rust tooling such as clippy for linting contracts. Feel free to use them! You can also use the make check-lint command for linting your contract. Run this command inside the my-project folder:
make check-lint
Test the Contract
In addition to creating the contract, the Casper crate also automatically created sample tests in the my-project/tests folder.
The Casper local environment provides a 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.
Since the test script automatically builds the contract, during development you only need to run the command make test without the need for make build-contract.
A successful test run indicates that your smart contract environment is set up correctly.
make test
After the compilation finishes, the test should run and you should see output similar to this message in your terminal:
running 2 tests
test tests::should_error_on_missing_runtime_arg ... 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.09s
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.
Installing the Casper Client
The Casper command-line client is a Rust CLI tool that can help you send deploys and install code on-chain. It's recommended to install the client as it's used to deploy contracts and session code in other on-chain tutorials.
Setting up an IDE
There are many IDEs available for Rust development. The most popular IDEs for Rust are the following:
You can use any IDE you wish. This documentation and examples use Visual Studio Code (VSC), a popular IDE with many extensions that might be helpful during development.
If you are using VSC, you might find the following extensions useful:
CodeLLDB– An important extension for debugging Rust coderust-analyzer– The official Rust language extensionBetter TOML– Support for formatting TOML filescrates– An extension to help manage cratesError Lens– Enhances the programming experience by highlighting syntax errors
Creating an Account
To interact with a Casper network and install code on-chain, you will need to create a Casper Account with a public and secret key pair.
Video Walkthrough
The following video tutorial complements this guide.
Rust Resources
These Rust resources are excellent and we highly recommend them: