Tutorial: Rust via Docker

This is a tutorial on setting up and using the Dockerized Valida zk-VM stack to write a Rust program, compile it to Valida, and provide its execution. The Valida Compiler Toolchain and Valida zk-VM pages provide the same information about the stack, in a more concise and complete reference-style format. You can safely skip this tutorial if you prefer that style of presentation, since there is no information about the stack which is contained in this tutorial and nowhere else.

Installation and cloning the project template

This section covers the following steps:

1. Install the toolchain via Docker.

2. Clone the Rust project template.

3. Validate that the installation is working correctly.

You can see all of the steps in this section performed in this video demo:

Prerequisites

First make sure that your system meets the requirements for following this tutorial. You will need a system which can run Docker containers. Your user will need to be part of the docker group. You will need at least 10 GB of free space on your filesystem.

Installation

To install the toolchain as a Docker image, run:

docker pull ghcr.io/lita-xyz/llvm-valida-releases/valida-build-container:v0.7.0-alpha

Cloning the template project

To clone the Rust project template, run:

git clone https://github.com/lita-xyz/fibonacci.git

Validating the installation

Follow the steps in this section to ensure that the toolchain is working correctly on your machine. After performing the above steps, cd into the template project:

cd fibonacci

Next, enter the Docker container:

docker run --platform linux/amd64 --entrypoint=/bin/bash -it --rm -v $(realpath .):/src ghcr.io/lita-xyz/llvm-valida-releases/valida-build-container:v0.7.0-alpha

From within the Docker container, build the template project:

cargo +valida build

Next, run the template project:

valida run target/valida-unknown-baremetal-gnu/debug/fibonacci log

You should see a prompt that looks like this:

Please enter a number from 0 to 46:

Enter a number between 0 and 46, and press enter. At this point, the program should print the answer and exit. For example:

valida> valida run target/valida-unknown-baremetal-gnu/debug/fibonacci log
Please enter a number from 0 to 46:
5
5
-th fibonacci number is:
5

At this point, you have validated that the toolchain is working on your system. You have also demonstrated how to compile a Rust program to a Valida executable, and run it on the zk-VM.

Looking at the template project

In the previous steps, you cloned the fibonacci template project. This contains a single Rust source file, src/main.rs. This is roughly what it should look like if you open it up in a text editor:

#![no_main]

#[no_mangle]

pub fn main() {
    println!("Please enter a number from 0 to 46:");
    // Read a line from stdin and parse it as an u8.
    let n = loop {
        match valida_rs::io::read_line::<u8>() {
            Ok(num) => break num,
            Err(e) => {
                println!(&format!("Error reading input: {}. Please try again:", e));
            }
        }
    };
    // n that is larger than 46 will overflow the u32 type.
    if n > 46 {
        println!("Error: n is too large. Please enter a number no more than 46.");
        return;
    }
    let mut a: u32 = 0;
    let mut b: u32 = 1;
    let mut sum: u32;
    for _ in 1..n {
        sum = a + b;
        a = b;
        b = sum;
    }

    println!(&n.to_string());
    println!("-th fibonacci number is:");
    println!(&b.to_string());
}

This program computes an element of the Fibonacci sequence based on user input. Here are some to observe about this program:

• This program begins with #![no_main]. This is a pragma indicating to the Rust compiler that this program has a non-standard entry point. It prevents the Rust compiler from emitting the standard boilerplate entry point which calls the standard main function. This is required because Valida does not currently support a main function which takes arguments. Every Valida Rust program must contain this #![no_main] pragma in its entry point (main.rs) file.

• The #[no_mangle] pragma on the main function turns off name mangling for this function, allowing it to be linked properly with the program entry point.

• The main function uses valida_rs::io::read_line::<u8> to read a number from standard in, in lieu of Rust standard library I/O functions.

Let's delete the application-specific logic from this file, in order to come up with a generic starting point for the project:

#![no_main]

#[no_mangle]

pub fn main() {
    // Your application code goes here
}

Application logic

Let's create a program which proves knowledge of the prime factorization of a 32-bit unsigned integer.

This tutorial demonstrates that multi-file Rust projects are supported by the Valida toolchain. We create a new file, call it src/lib.rs, which we fill with the following contents:

pub fn read_number() -> u32 {
    loop {
        match valida_rs::io::read_line::<u32>() {
            Ok(num) => break num,
            Err(e) => {
                println!(&format!("Error reading input: {}. Please try again:", e));
            }
        }
    }
}

pub fn check_prime_factorization(x: u32, ys: &[u32]) -> bool {
    let mut z = 1;
    for y in ys {
        if !is_prime(*y) {
            return false;
        }
        z *= *y;
    }
    z == x
}

pub fn is_prime(x: u32) -> bool {
    for y in 2..x {
        if x % y == 0 {
            return false;
        }
    }
    true
}

This module defines three functions: read_number, check_prime_factorization, and is_prime. Here is what each of these functions does:

• The read_number function attempts to read an unsigned 32-bit integer from the input tape. If it fails to do so, it outputs an error message and again attempts to read an unsigned integer, continuing until it succeeds.

• The check_prime_factorization function checks that ys is a prime factorization of x, outputting true if this is the case and false otherwise.

• The is_prime function outputs true if x is a prime number, and false otherwise.

Next, we'll edit the src/main.rs file so that it looks like this:

#![no_main]

use prime_factorization::{read_number, check_prime_factorization};

#[no_mangle]

pub fn main() {
    println!("Please enter a 32-bit number:");
    // Read a line from stdin and parse it as a u32.
    let x = read_number();

    println!("Please enter the number of prime factors (with multiplicity):");
    let n = read_number();

    let mut ys = vec![];
    for _i in 0..n {
        println!("Please enter the next prime factor:");
        ys.push(read_number());
    }

    if check_prime_factorization(x, ys.as_ref()) {
        println!("Verified prime factorization of:");
        println!(&x.to_string());
    } else {
        println!("Failed to verify prime factorization");
    }
}

This modifies the template src/main.rs file by adding imports from src/lib.rs and populating the main function. The new main function reads a 32-bit number x, followed by its number of prime factors, and then each of its prime factors. It then checks whether the claimed prime factors are in fact the prime factors of x, providing output which indicates whether or not this is the case.

Renaming the project

Let's rename the project so that it is no longer called fibonacci. First open the Cargo.toml file in the root folder of the project. You should see something like this:

[package]
name = "fibonacci"
version = "0.1.0"
edition = "2021"

[dependencies]
valida-rs = { git = "https://github.com/lita-xyz/valida-rs.git", branch = "no-deps" }

Edit the line name = "fibonacci" to read instead name = "prime_factorization".

Building, running, proving, and verifying

To build the program to run on Valida, simply run:

cargo +valida build --release

To run the program:

valida run --fast ./target/valida-unknown-baremetal-gnu/release/prime_factorization log

You will get a series of prompts. Here is an example interaction with this program:

Please enter a 32-bit number:
4
Please enter the number of prime factors (with multiplicity):
2
Please enter the next prime factor:
2
Please enter the next prime factor:
2
Verified prime factorization of:
4

At this point, the output of the program will have been written to log. To prove an execution of the program, run:

valida prove ./target/valida-unknown-baremetal-gnu/release/prime_factorization proof

You will again get a series of prompts, which you should respond to in the same way. The result should be that a proof of that execution is written to proof. You can verify this proof as follows:

valida verify ./target/valida-unknown-baremetal-gnu/release/prime_factorization proof --claimed_output log