MCPcopy Index your code
hub / github.com/Sin7Y/olavm

github.com/Sin7Y/olavm @main

Chat with this repo
repository ↗ · DeepWiki ↗ · + Follow
3,420 symbols 10,316 edges 368 files 484 documented · 14%
What it actually does AI analysis from the code graph — generated when you open this
loading…
README

OlaVM

LICENSE CI checks issues

OlaVM is a STARK-based ZK-friendly ZKVM, it is built on a small finite field called Goldilocks field. As the most important component of the Ola system, OlaVM is mainly used to execute a program and generate a valid proof for the programmable scalable case and the programmable private case.

Warning: This repository shouldn't be used for production case, as it is still in development phase and has not been audited, so it might contain many bugs and security holes..

Overview

OlaVM is a Turing complete VM, which means that it can execute any computation on it and at the same time it could generate a valid proof for it. For getting a smaller proof time, we have many powerful designs that are relevant with ZK-friendly.

  • if you want to know more about ZK-friendly and VM designs, check out the doc/olavm;
  • if you want to know more about the circuit design, check out circuit crate;
  • if you want to know more about the performance of OlaVM, check out Performance section;
  • if you want to know more about STARKS, check out References section;

Key Features

There are a lot of tricks to get a very ZK-friendly ZKVM in OlaVM. We would like to highlight some of them:

  • Algebraic RISC. The property of the instruction set of OlaVM is Algebraic RISC: "Algebraic" refers to the supported operations are field operation, "RISC" refers to the minimality of the instruction set. We can achieve a concise transition constraint based on this, see circuit/cpu to learn more;

  • Small finite field. The word defined in OlaVM is a finite field, Goldilocks. The prime of Goldilocks is p = 2^64 - 2^32 + 1, which is less than 64 bits. The computation based on these field elements could be expected to be much faster than other large finite fields;

  • Builtins. Since the cyclic group size is limited, it would be better if the trace table could contain as many transactions as possible. This means that if there are some computation cost a large trace lines in transaction logic, we should remove them from the main trace table and add a special sub-trace table to store them, this is the reason that introduce builtins, like hash, bitwise operation and so on, check the doc/olavm for more details;

  • Prophets. It is designed for non-deterministic computation, which means "implementation is expensive, verification is cheap". So to some extent Prophets is more like an external helper. It helps you compute the results of some non-deterministic computation, and then you verify the results using the instruction sets, should note that this verification is done by the VM, not by constraints which is different with builtins, see the doc/olavm for more details;

Status

Features Status
Algebraic RISC $\color{Green}{Done}$
Small finite field $\color{Green}{Done}$
Builtins - bitwise $\color{Green}{Done}$
Builtins - rangecheck $\color{Green}{Done}$
Builtins - cmp $\color{Green}{Done}$
Builtins - poseidon $\color{Green}{Done}$
Storage $\color{Green}{Done}$
Cross-contract call $\color{Green}{Done}$
Prover optimization $\color{Green}{Done}$
Builtins - ecdsa $\color{Yellow}{Doing}$
Prophet libs $\color{Yellow}{Doing}$
u32/u64/u256 lib $\color{Yellow}{Doing}$
Support privacy $\color{Yellow}{Doing}$

Project structure

This project consists of several crates:

Crate Description
core Define instruction structure and instruction sets
circuits 1. Constraints for instruction sets, builtins, memory; 2. Generate proof
executor Execute the programme and generate the execution trace for the Ola-prover
client Some commands can be used by developers
plonky2 A SNARK implementation based on techniques from PLONK and FRI techniques
infrastructure Write the execution trace to an Excel file

Performance

Many optimizations have not yet been applied, and we expect to see some speed improvements as we devote more time to performance optimization. The benchmarks below should only be used as a rough guide to expected future performance.

Algorithm Execution Instructions Lines in CPU Table Mac(8-cpu 16GB-Mem) Execution and Generate trace Time Mac(10-cpu 32GB-Mem) Prove Time Linux(64-cpu 128GB-Mem) Execution and Generate Trace Time Linux(64-cpu 128GB-Mem) Prove Time
Calculate the 47th Fibonacci number 1000 times. 866115 2^20 0.275s, 0.571s 80.524s 0.315s, 0.95s 39.767 s
Calculate the sqrt of 1,073,741,824 16000 times. 544113 2^20 0.892s, 0.572s 65.758s 1.185s, 0.955s 29.935 s

Overall, we don't expect the benchmarks to change significantly, but there will definitely be some deviation from the numbers below in the future.

A few general notes on performance:

Software:

Hardware:

  • Integrate GPU accelerated FFT
  • Integrate GPU accelerated polynomial evaluation
  • Integrate FPGA accelerated FFT
  • Integrate FPGA accelerated polynomial evaluation

References

OlaVM runs based on the Goldilocks field and uses STARK to generate proofs for the inner layer and more will use Plonky2 to generate recursive proofs for inner proofs. There are some resources to learn more about it.

Goldilocks field & plonky2

STARK

Vitalik Buterin's blog series on zk-STARKs:

  • Part-1: Proofs with Polynomials
  • Part-2: Thank Goodness It's FRI-day
  • Part-3: Into the Weeds

Alan Szepieniec's STARK tutorials:

Sin7Y's STARK explanation:

Privacy:

License

This project is under MIT licensed.

Extension points exported contracts — how you extend this code

Gate (Interface)
A custom gate. [20 implementers]
plonky2/plonky2/src/gates/gate.rs
Field (Interface)
A finite field. [6 implementers]
plonky2/field/src/types.rs
Stark (Interface)
Represents a STARK system. [13 implementers]
circuits/src/stark/stark.rs
MaybeParIter (Interface)
(no doc) [3 implementers]
plonky2/maybe_rayon/src/lib.rs
IteratorExt (Interface)
Iterator extension which provides additional methods to be used by iterators. [1 implementers]
core/src/merkle_tree/iter_ext/mod.rs
Traversal (Interface)
(no doc) [2 implementers]
interpreter/src/parser/traversal.rs
SimpleGenerator (Interface)
A generator which runs once after a list of dependencies is present in the witness. [28 implementers]
plonky2/plonky2/src/iop/generator.rs
Square (Interface)
(no doc) [6 implementers]
plonky2/field/src/ops.rs

Core symbols most depended-on inside this repo

iter
called by 573
plonky2/plonky2/src/plonk/vars.rs
push
called by 518
plonky2/plonky2/src/util/timing.rs
to_string
called by 455
interpreter/src/utils/number.rs
insert
called by 365
interpreter/src/sema/symbol.rs
constraint
called by 271
circuits/src/stark/constraint_consumer.rs
to_canonical_u64
called by 222
plonky2/field/src/goldilocks_field.rs
into_iter
called by 215
plonky2/plonky2/src/util/strided_view.rs
binary_bit_mask
called by 175
core/src/vm/opcodes.rs

Shape

Method 1,904
Function 1,017
Class 413
Enum 47
Interface 39

Languages

Rust100%
Python1%

Modules by API surface

plonky2/plonky2/src/plonk/circuit_builder.rs70 symbols
circuits/src/cpu/cpu_stark.rs62 symbols
plonky2/field/src/polynomial/mod.rs61 symbols
plonky2/field/src/types.rs49 symbols
plonky2/field/src/arch/x86_64/avx2_goldilocks_field.rs49 symbols
plonky2/plonky2/src/plonk/circuit_data.rs48 symbols
plonky2/field/src/arch/x86_64/avx512_goldilocks_field.rs48 symbols
circuits/src/stark/ola_stark.rs48 symbols
circuits/src/stark/cross_table_lookup.rs48 symbols
executor/src/contract_executor.rs45 symbols
plonky2/plonky2/src/util/serialization.rs44 symbols
plonky2/plonky2/src/gadgets/arithmetic_extension.rs44 symbols

For agents

$ claude mcp add olavm \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact