This guide is designed to support developers getting started with the development of smart contracts on the Casper blockchain in AssemblyScript or Rust. For Rust, there is a contract development kit that includes a runtime environment, reference documentation, and test framework. You can install our environment locally, create and test Smart Contracts with our Smart Contracts and Test Libraries, and use these libraries to build your own applications.
It is recommended you have prior knowledge about Unix-based operating systems, like GNU/Linux or macOS, and programming knowledge with:
The topics on the index include present and future documentation initiatives in our roadmap and are organized so that you will be able to:
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.
Refer to our FAQ guide if you have questions or need help.
For a video walkthrough of this guide, feel free to check out this quick-start video.
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.57.0 and may differ for you):
$ rustup --version
rustup 1.24.3 (ce5817a94 2021-05-31)
info: This is the version for the rustup toolchain manager, not the rustc compiler.
info: The currently active `rustc` version is `rustc 1.57.0 (f1edd0429 2021-11-29)`.
Casper Rust Packages
We publish three crates on crates.io to support smart contract development with Rust:
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.
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
cmake version 3.20.0
CMake suite maintained and supported by Kitware (kitware.com/cmake).
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
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.
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.
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
Inside the contract folder, you will now see a
target folder that contains the compiled smart contract named
contract.wasm at
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
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 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
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 _KEYNAME value in the contract, and then
rerun the make test command. You should observe that the
smart contract recompiles and the test fails now.
These Rust resources are excellent and we highly recommend them: