Crate tezos_smart_rollup
source ·Expand description
SDK for Tezos Smart Rollups.
To learn more about how Smart Rollups work in Tezos, see the Smart Rollup Documentation.
The purpose of this SDK is to make writing Smart Rollup kernels in Rust simpler.
To learn about the changes in the current version of the SDK, see the CHANGELOG.
Smart Rollup Kernels
A kernel is a 32bit WebAssembly program that runs on a Smart Rollup. It decides how the Rollup handles input messages, updates the Rollup state, and when to output messages targetting Layer 1.
While any programming-language with WebAssembly-compilation support could be used for writing a Rollup kernel, Rust is an excellent fit due to first-class WASM support, deterministic runtime, and safe memory management.
Setting-up Rust
rustup is the standard way to get Rust. Once rustup
is installed, enable
WASM as a compilation target with:
rustup target add wasm32-unknown-unknown
Rust also has a wasm64-unknown-unknown
compilation target. This target is not compatible
with Tezos Smart Rollups, which only provide a 32bit address space.
Installing Clang
In order to build the Rust SDK, clang >= 11
is required in addition to Rust. This can be installed
through your favourite package manager.
On MacOS, LLVM and the WebAssembly Binary Toolkit (WABT) can be installed through homebrew:
brew install llvm
brew install wabt
LLVM_PATH=$(brew --prefix llvm)
export AR="${LLVM_PATH}/bin/llvm-ar"
export CC="${LLVM_PATH}/bin/clang"
On Linux, often the default CC
is gcc, which is not supported for kernel builds. Ensure clang is being used:
export CC=clang
Features
Feature | Default? | Enables | About |
---|---|---|---|
std | ✅ | alloc | Disable for #![no_std] integration |
alloc | ✅ | Enables methods/types requiring alloc crate | |
panic-hook | ✅ | Print panics to debug log and abort | |
dlmalloc | ✅ | Enables dlmalloc as default allocator | |
crypto | ✅ | tezos_crypto_rs | Integration with tezos_crypto_rs types |
bls | ✅ | tezos_crypto_rs/bls | Dac Certificate signature verification |
data-encoding | ✅ | tezos_data_encoding | Integration with tezos_data_encoding traits |
testing | ❌ | crypto , tezos_smart_rollup_mock | Enables MockHost for writing tests |
Usage
The following Cargo.toml
file can be used to set up development with the Kernel SDK:
[package]
name = "kernel"
version = "0.1.0"
edition = "2021"
rust-version = "1.71.1"
[lib]
crate-type = ["cdylib", "rlib"]
[dependencies]
tezos-smart-rollup = "0.2.2"
tezos_data_encoding = "0.5"
tezos_crypto_rs = { version = "0.5", default-features = false }
nom = "7.1"
[dev-dependencies]
tezos-smart-rollup = { version = "0.2.0", features = ["testing"] }
Note that the cdylib
crate type is required to enable compilation to wasm.
The following lib.rs
file could then be used to get started with a ‘hello kernel’.
This kernel will run once per inbox level.
use tezos_smart_rollup::prelude::*;
use tezos_smart_rollup::kernel_entry;
kernel_entry!(hello_kernel);
fn hello_kernel(host: &mut impl Runtime) {
debug_msg!(host, "Hello, kernel!\n");
}
With those two files saved to Cargo.toml
& src/lib.rs
, you can compile the kernel:
cargo build --release --target wasm32-unknown-unknown
cp target/wasm32-unknown-unknown/release/kernel.wasm .
Often, large .wasm
files are produced. The size of these can be significantly reduced using wasm-strip, which will remove items such as debugging symbols & metadata from the binary, not required for execution on Smart Rollups:
wasm-strip kernel.wasm
You can test this kernel by using the octez-smart-rollup-wasm-debugger
.
# Create an empty inputs.json file - the 'hello world' kernel does not read inputs.
echo '[[], []]' > inputs.json
# Run the kernel:
octez-smart-rollup-wasm-debugger --kernel kernel.wasm --inputs inputs.json
Once in the debugger, you can run the following commands to test the kernel:
> load inputs
Loaded 0 inputs at level 0
> step kernel_run
Hello, kernel!
Evaluation took 11000000000 ticks so far
Status: Waiting for input
Internal_status: Collect
> load inputs
Loaded 0 inputs at level 1
> step kernel_run
Hello, kernel!
Evaluation took 11000000000 ticks so far
Status: Waiting for input
Internal_status: Collect
As you can see, on each level, the kernel prints Hello, kernel!
to the debug log.
Unit-testing
To learn about writing unit tests against a kernel, see MockHost
.
Re-exports
pub use tezos_smart_rollup_core as core_unsafe;
Modules
- Defines dac related types and functions.
- A low level, but safe, wrapper over the Smart Rollup host functions.
- Types & encodings for the inbox-half of the L1/L2 communication protocol
- Definitions & tezos-encodings for michelson data.
- Types & encodings for the outbox-half of the L1/L2 communication protocol
- Tezos smart rollup prelude - used by every kernel.
- Durable Storage allows state to be persisted between multiple calls to the kernel.
- Utilities for writing unit tests for kernels.
- Types used/returned elsewhere in the SDK.
Macros
- Derive
kernel_run
&mock_kernel_run
entrypoints.