Skip to content

refine README.md #276

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TomWambsgans merged 1 commit into from
Sep 13, 2026
+70 −48
Merged

refine README.md #276

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 70 additions & 48 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<img src="./doc/images/banner.svg" alt="leanVM">
</p>

<h3 align="center">Minimal hash-based zkVM, for a Post-Quantum Ethereum.</h3>
<h3 align="center">minimal hash-based zkVM, for post-quantum Ethereum</h3>

<p align="center">
<a href="https://github.com/leanEthereum/leanVM/releases/download/doc-latest/leanVM.pdf"><img src="https://img.shields.io/badge/Documentation-PDF-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xNCAySDZjLTEuMSAwLTIgLjktMiAydjE2YzAgMS4xLjg5IDIgMS45OSAySDE4YzEuMSAwIDItLjkgMi0yVjhsLTYtNnpNOC41IDE0LjVoMS4yNWMuOTcgMCAxLjc1LS43OCAxLjc1LTEuNzVTMTAuNzIgMTEgOS43NSAxMUg3LjV2Nmgxdi0yLjV6bTAtMVYxMmgxLjI1Yy40MSAwIC43NS4zNC43NS43NXMtLjM0Ljc1LS43NS43NUg4LjV6bTUuNSAzLjVoMnYtMWgtMnYtMWgydi0xaC0ydi0xLjVjMC0uMjguMjItLjUuNS0uNUgxN3YtMWgtMmMtLjgzIDAtMS41LjY3LTEuNSAxLjVWMTd6TTEzIDlWMy41TDE4LjUgOUgxM3oiLz48L3N2Zz4=" alt="Documentation"></a>
Expand All @@ -13,30 +13,59 @@

<table align="center">
<tr>
<td><a href="#xmss-aggregation">XMSS aggregation</a></td>
<td align="right"><b>1,200 XMSS/s</b></td>
<td><a href="#xmss-aggregation">leanXMSS aggregation</a></td>
<td align="right"><b>1.2K/s</b></td>
</tr>
<tr>
<td><a href="#sphincs-aggregation">SPHINCS aggregation</a></td>
<td align="right"><b>250 SPHINCS/s</b></td>
<td><a href="#sphincs-aggregation">leanSPHINCS aggregation</a></td>
<td align="right"><b>250/s</b></td>
</tr>
<tr>
<td><a href="#recursion">Recursion 2 → 1</a></td>
<td align="right"><b>0.29 s</b></td>
<td><a href="#data-availability">leanDA commitment</a></td>
<td align="right"><b>2 MiB/s</b></td>
</tr>
</table>
<table align="center">
<tr>
<td><a href="#recursion">2-to-1 recursion</a></td>
<td align="right"><b>0.29s</b></td>
</tr>
<tr>
<td><a href="#data-availability">Data availability</a></td>
<td align="right"><b>16 blobs/s</b></td>
<td><a href="#hashing">hash compressions</a></td>
<td align="right"><b>480K/s</b></td>
</tr>
<tr>
<td><a href="#fibonacci">cheap cycles</a></td>
<td align="right"><b>5.4M/s</b></td>
</tr>
</table>

Warning: not (yet) production ready.
## security

leanVM is designed for security:

* 128-bit ROM (64-bit QROM) soundness
* no proximity gap conjecture
* end-to-end formal verification
* a traditional hash function

leanVM was originally designed over the [KoalaBear prime](https://crates.io/crates/p3-koala-bear) and [Poseidon](https://eprint.iacr.org/2019/458), still available in the [koalabear](https://github.com/leanEthereum/leanVM/tree/koalabear) branch; it is now using binary fields and BLAKE2s.
**warning**: Formal verification is in progress. leanVM is not (yet) production ready.

# Benchmarks
## work in progress

Machine: Mac M4 Max
Expect leanVM to change significantly:

* **hash**: BLAKE2s is a placeholder. SHA2, SHA3, BLAKE3 are actively considered.
* **ISA**: A migration from leanISA to RISC-V (rv64im) is planned.
* **zk**: Support for zero-knowledge is planned.

**note**: Prior to binary fields leanVM used [KoalaBear](https://crates.io/crates/p3-koala-bear) and [Poseidon](https://eprint.iacr.org/2019/458). The historical design is in [this branch](https://github.com/leanEthereum/leanVM/tree/koalabear).

## benchmarks

**machine**: M4 Max MacBook Pro (12 performance cores, 4 efficiency cores, 48GB RAM)

**note**: The Metal GPU was not used.

### XMSS aggregation

Expand Down Expand Up @@ -74,24 +103,7 @@ aggregation, 245 SPHINCS signatures
verifying : 3.969 ms
```

### Recursion


```bash
cargo run --release -- recursion --n 2 --xmss-per-leaf 900 --log-inv-rate 2 --repeat 3
```

```
recursion 2→1, over leaves of 900 XMSS signatures
cycles (VM steps) : 570,113 = 2^19.121
details : MUL 2^17.838 (41.1%) DEREF 2^16.988 (22.8%) XOR 2^16.747 (19.3%) SET 2^15.79 (9.9%) JUMP 2^14.488 (4.0%) BLAKE2S 2^13.978 (2.8%) MEMORY 2^19.507 TOTAL_COMMITTED 2^24.086
proof size : 191.3 KiB
proving time : 0.287 s ± 15.9% peak memory 10.124 GiB
verifying : 4.121 ms
```

### Data Availability

### data availability

```bash
cargo run --release -- aggregate --blobs 16 --log-inv-rate 1 --repeat 3
Expand All @@ -107,23 +119,22 @@ aggregation, 16 blobs
verifying : 6.659 ms
```

### Fibonacci

### recursion

```bash
cargo run --release -- fibonacci --n 2000000 --log-inv-rate 1 --repeat 3
cargo run --release -- recursion --n 2 --xmss-per-leaf 900 --log-inv-rate 2 --repeat 3
```

```
Fibonacci (in the exponent, i.e. modulo 2^64 - 1), N = 2,000,000
cycles (VM steps) : 2,127,880
details : MUL 2^20.944 (98.9%) SET 2^13.288 (0.5%) DEREF 2^12.967 (0.4%) JUMP 2^10.968 (0.1%) XOR2^10.966 (0.1%) MEMORY 2^20.96 TOTAL_COMMITTED 2^25.26
proof size : 285.4 KiB
proving : 0.391 s ± 1.1% 5,442,734 cycles/s peak memory 5.203 GiB
verifying : 2.092 ms
recursion 2→1, over leaves of 900 XMSS signatures
cycles (VM steps) : 570,113 = 2^19.121
details : MUL 2^17.838 (41.1%) DEREF 2^16.988 (22.8%) XOR 2^16.747 (19.3%) SET 2^15.79 (9.9%) JUMP 2^14.488 (4.0%) BLAKE2S 2^13.978 (2.8%) MEMORY 2^19.507 TOTAL_COMMITTED 2^24.086
proof size : 191.3 KiB
proving time : 0.287 s ± 15.9% peak memory 10.124 GiB
verifying : 4.121 ms
```

### Batch proving BLAKE2s
### hashing

```bash
BENCH_REPEAT=3 BENCH_COOLDOWN=2 FLOCK_N_LOG=18 cargo test --release --package flock --test batch_proving_hashes -- hash_batch_prove_verify --exact --nocapture --include-ignored
Expand All @@ -145,13 +156,24 @@ Flock BLAKE2s batch proving, 262,144 compressions (2^18 slots)
(~3289.9 XMSS/s equivalent at 146 compressions/signature)
```

## Security
### Fibonacci

- 128-bit (LDR Johnson, no proximity gaps conjecture)
```bash
cargo run --release -- fibonacci --n 2000000 --log-inv-rate 1 --repeat 3
```

```
Fibonacci (in the exponent, i.e. modulo 2^64 - 1), N = 2,000,000
cycles (VM steps) : 2,127,880
details : MUL 2^20.944 (98.9%) SET 2^13.288 (0.5%) DEREF 2^12.967 (0.4%) JUMP 2^10.968 (0.1%) XOR2^10.966 (0.1%) MEMORY 2^20.96 TOTAL_COMMITTED 2^25.26
proof size : 285.4 KiB
proving : 0.391 s ± 1.1% 5,442,734 cycles/s peak memory 5.203 GiB
verifying : 2.092 ms
```

## Snark machinery
## SNARK machinery

- Binary field of 192 bits (tower of degree 3 over the 64 bit field)
- PCS: [WHIR](https://eprint.iacr.org/2024/1586) (aka [Ligerito](https://eprint.iacr.org/2025/1187))
- Proving BLAKE2s by [Flock](https://github.com/succinctlabs/flock/tree/main)
- RingSwitching, M3 arithmetisation, (and more) by [Binius](https://github.com/IrreducibleOSS/binius) / [Binius64](https://github.com/binius-zk/binius64) (see [DP23](https://eprint.iacr.org/2023/1784) and [DP24](https://eprint.iacr.org/2024/504))
- 192-bit binary field (degree-3 tower over the 64-bit field)
- [WHIR](https://eprint.iacr.org/2024/1586) PCS, aka [Ligerito](https://eprint.iacr.org/2025/1187)
- [Flock](https://github.com/succinctlabs/flock/tree/main) hash proving
- [Binius](https://github.com/IrreducibleOSS/binius)/[Binius64](https://github.com/binius-zk/binius64) ring switching, M3 arithmetisation, and more (see [DP23](https://eprint.iacr.org/2023/1784) and [DP24](https://eprint.iacr.org/2024/504))
Loading