Cairo VM TypeScript
⚠️ This project is in its genesis, undergoing fast-paced development. It is not suitable for production yet. Expect frequent breaking changes.
Cairo stands for CPU AIR "o" (like insp"o", conv"o", 🤔).
It is a framework (a machine, an assembly and a language) which allows writing provable programs without having to understand the underneath ZK-technology.
A program written in Cairo (or Cairo Zero) is compiled to Cairo Assembly (CASM) and then executed on a Cairo VM which produces traces to be used for the STARK proof generation.
See resources for more information.
There are currently seven other Cairo VM implementations:
The Lambda Class alt-implementations comes with a detailed guide (Go, C++) on how they built their Cairo VM. It gives insights into the overall Cairo VM but is incomplete and rather specific to language details.
Why would you have different implementations of the same program in multiple languages? For implementation diversity.
More implementations provide more:
Implementation diversity also implies usage diversity. The primary goals of each implementation can differ.
For example, the EVM implementation in clients (e.g. geth and reth written in Go and Rust), whose primary goals are performance and safety, and the reference EVM implementation in Python, prioritizing readability and simplicity.
Analogous to the EVM implementations, the primary goals of the Rust Cairo VM are performance and safety. While the ones of our TypeScript implementation is education through readability and simplicity.
bun install # install all dependencies
bun test # run all tests
You can install the CLI cairo-vm-ts
by doing the following:
git clone git@github.com:kkrt-labs/cairo-vm-ts.git
cd cairo-vm-ts
bun install
bun link
Steps 3. and 4. can be replaced by make build
Example usage:
cairo run fibonacci.json --export-memory fib_mem.bin --print-memory --print-output
No package release has been done yet.
You can still add it as a dependency with a local copy:
git clone git@github.com:kkrt-labs/cairo-vm-ts.git
cd cairo-vm-ts
bun install
bun run build
cd ~/my-project
cairo-vm-ts
to your project dependency:
<bun | yarn | npm> add ~/path/to/cairo-vm-ts
Goals | Done? |
---|---|
Run basic Cairo Zero program | ☑ |
Run basic Cairo program | ☐ |
Add builtins | ☑ |
Add hints | ☐ |
Run StarkNet contracts | ☐ |
Benchmark against other VMs | ☐ |
Builtin | Done? |
---|---|
Output | ☑ |
Pedersen | ☑ |
Range Check | ☑ |
ECDSA | ☑ |
Bitwise | ☑ |
EcOp | ☑ |
Keccak | ☑ |
Poseidon | ☑ |
Range Check 96 | ☑ |
Segment Arena | ☐ |
AddMod | ☐ |
MulMod | ☐ |
Pre-requisite: make
Compare the encoded memory and trace of execution between different Cairo VM implementations on a broad range of Cairo programs.
It is currently only done in execution mode (non-proof mode) on programs with no hints. It uses the CLI of each VM implementation.
Cairo VM Implementations | Added to diff-test |
---|---|
Cairo VM TS | ☑ |
Cairo VM Rust | ☑ |
Cairo VM Python | ☑ |
Cairo VM Zig | ☑ |
Cairo VM Go - ProofMode only | ☐ |
To build the different projects CLI, you'll need the following dependencies:
To run the differential tests, simply use make diff-test
.
If you wanna compare an arbitrary amount of memory or trace files, you can
directly use the compare
command
compare memory fib.memory fib2.memory fib3.memory
compare trace fib.trace fib2.trace fib3.trace
For a quick benchmarking tool, one can run make bench
It uses hyperfine
to benchmark the CLI command of the different Cairo VM
implementations. These benchmarks might not be accurate, it should be done in a
proper environment.
The benchmark programs used currently come from the
cairo-vm/cairo_programs/benchmarks
. The workload of each program has been
reduced for slower implementations to finish () Only Cairo programs with no
hints are used at the moment:
Cairo Program | Description | Value |
---|---|---|
big_factorial.cairo |
Computes $n!$ | $n = 50000$ |
big_fibonacci.cairo |
Computes $un = u{n-1} + u_{n-2}, n \geq 2, u_0 = 0, u_1 = 1$ | $n = 40000$ |
integration_builtins.cairo |
Computes $N$ times $\text{Pedersen}(a, u_{20})$. $\forall n \in \mathbb{N^*}, un = D(u{n-1}, v_{n})$, $vn = 3v{n-1}$, $D(x, y) = (x \oplus y) \land (x \lor (y \gg 1))$. Verifies that $\forall n \in \mathbb{N}, v_n < 2^{64}$ and stores the value in the output segment | $N = 100$, $a = 123568$, $u_0 = 5673940$, $v_0 = 6783043740$ |
pedersen.cairo |
Computes $N$ times $\text{Pedersen}(a, b)$ | $N = 5000$, $a = 123568$, $b = 5673940$ |
A benchmark using each VM implementation API is developped at
cairo-vm-bench