Getting Started with Rust Casper Contracts
This guide covers additional prerequisites for writing your first Casper smart contract. You will also 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 to WebAssembly. This guide will walk you through the steps to write your first contract, assuming you have already set up your development environment as described here.
Creating a Project
You can create a new sample project very easily with the cargo 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.
Reproducibility
Currently, cargo does not provide cross-platform reproducibility for binary files, including WebAssembly. The ability to compile a smart contract to the same binary file is important, for example, when verifying that the smart contract binary stored on the blockchain is the same as the provided source code.
To work around the issue, cargo casper crate provides rustc wrapper, which can be enabled using --wrapper option.
cargo casper my_project --wrapper
Using the nightly toolchain
Navigate to the my-project folder and open the rust-toolchain file. You will notice that the file's contents specify a nightly version of Rust. Here is an example:
nightly-2022-08-03
Having the latest nightly toolchain to develop smart contracts in Rust would be best. Please refer to the Rust Documentation on Channels and the Rust Documentation on Toolchains for further information.
As shown in this example, we recommend setting up the rust-toolchain file in your project's top-level directory.
You can also install the nightly Rust toolchain with this command:
rustup toolchain install nightly
Available Casper Rust crates
To support smart contract development with Rust, the following crates are published:
- casper-contract - a library supporting communication with the blockchain. This is the main library you will need to write smart contracts.
- casper-engine-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 that can be compiled into a binary or a library.
For a comprehensive list of crates, visit the Essential Casper Crates page.
Available API documentation
Each of the Casper crates comes with API documentation and examples for each function, located at https://docs.rs. The latest contract API documentation can be found here.
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
Testing 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.
Video Walkthrough
The following video tutorial complements this guide.
Rust Resources
These Rust resources are excellent and we highly recommend them: