|
| 1 | +# `riscv32im-risc0-zkvm-elf` |
| 2 | + |
| 3 | +**Tier: 3** |
| 4 | + |
| 5 | +Succinct's ISA for the SP1 zkVM (Zero Knowledge Virtual Machine). |
| 6 | + |
| 7 | +## Target maintainers |
| 8 | + |
| 9 | +- John Guibas, `john@succinct.xyz`, https://github.com/jtguibas |
| 10 | +- Nathan Bustamante, `nathan@succinct.xyz`, https://github.com/nhtyy |
| 11 | + |
| 12 | +## Background |
| 13 | + |
| 14 | +This target is an execution environment to produce a proof of execution of |
| 15 | +a RISC-V ELF binary and any output that the developer of the binary wishes to |
| 16 | +display publicly. In order to do this, the target will execute the ELF and |
| 17 | +create a cryptographic proof of the "trace" of the programs runtime. |
| 18 | + |
| 19 | +We have a cargo extension called [cargo-prove] that allow users to generate |
| 20 | +project templates, install tools for improved user experience and build binaries. |
| 21 | + |
| 22 | +## Requirements |
| 23 | + |
| 24 | +The target only supports cross compilation and no host tools. The target |
| 25 | +supports `alloc` with a default allocator and will have support for std soon. |
| 26 | + |
| 27 | +The target's execution environment is single threaded, non-preemptive, and does |
| 28 | +not support any privileged instructions, nor unaligned accesses. At the time of |
| 29 | +writing the VM has 192 MB of memory and text/data, heap, and stack need to be |
| 30 | +with in the address range `0x400` - `0x0C000000`. The binaries themselves expect |
| 31 | +no operating system and can be thought of as running on bare-metal. The target |
| 32 | +does not use `#[target_feature(...)]` or `-C target-feature=` values. |
| 33 | + |
| 34 | +Calling `extern "C"` on the target uses the C calling convention outlined in the |
| 35 | +[RISC-V specification]. |
| 36 | + |
| 37 | +## Building for the zkVM |
| 38 | + |
| 39 | +Programs for the zkVM could be built by adding it to the `target` list in |
| 40 | +`config.toml`. However, we recommend building programs in our starter template |
| 41 | +generated by the [cargo-prove] utility and the [sp1-build] crate. This |
| 42 | +crate calls `rustc` with `-C "link-arg=-Ttext=` so that it maps the text in the |
| 43 | +appropriate location as well as generating variables that represent the ELF and |
| 44 | +a unique ID associated with the ELF. |
| 45 | + |
| 46 | +The starter template provides developers with system calls that are useful |
| 47 | +to zero knowledge computing such as writing to |
| 48 | +the public output, hashing using sha256, and multiply big integers. |
| 49 | + |
| 50 | +## Building Rust programs |
| 51 | + |
| 52 | +Rust does not yet ship pre-compiled artifacts for this target. To compile for |
| 53 | +this target, you will either need to build Rust with the target enabled (see |
| 54 | +"Building the target" above). We do not recommend using `build-std` as we have |
| 55 | +run into issues building core in the past on our starter template. An alternate |
| 56 | +solution is to download the risc0 tool chain by running `cargo prove install-toolchain`. |
| 57 | + |
| 58 | +## Testing |
| 59 | + |
| 60 | +Note: the target is implemented as a software emulator called the zkVM and there |
| 61 | +is no hardware implementation of the target. |
| 62 | + |
| 63 | +The most practical way to test the target program is to use our starter template |
| 64 | +that can be generated by using the `cargo prove new` command. The template |
| 65 | +generates a sample "host" and "guest" code. The guest code compiled to the |
| 66 | +target (which is RV32IM) whereas the "host" code is compiled to run on the |
| 67 | +programmer's machine running either a Linux distribution or macOS. |
| 68 | + |
| 69 | +The host program is responsible for running the guest binary on the zkVM and retrieving |
| 70 | +its public output. |
| 71 | + |
| 72 | +The target currently does not support running the Rust test suite. |
| 73 | + |
| 74 | +## Cross-compilation toolchains and C code |
| 75 | + |
| 76 | +Compatible C code can be built for this target on any compiler that has a RV32IM |
| 77 | +target. On clang and ld.lld linker, it can be generated using the |
| 78 | +`-march=rv32im`, `-mabi=ilp32` with llvm features flag `features=+m` and llvm |
| 79 | +target `riscv32-unknown-none`. |
| 80 | + |
| 81 | +[RISC-V specification]: https://riscv.org/wp-content/uploads/2015/01/riscv-calling.pdf |
| 82 | +[cargo-prove]: https://docs.succinct.xyz/docs/sp1/getting-started/install |
| 83 | +[sp1-build]: https://crates.io/crates/sp1-build |
0 commit comments