diff --git a/AGENTS.md b/AGENTS.md index ef80099d1c..db3e9ceda2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,7 +67,7 @@ cargo fmt --all # max_width = 120 cargo machete --with-metadata # unused dependencies, dev ones included ``` -An x86-only `cfg` arm never compiles on an Apple machine, so type-check the other target before pushing anything `cfg`-gated (needs only `rustup target add x86_64-unknown-linux-gnu`; `bench` and the CLI are left out because jemalloc's build script wants a cross `gcc`): +An x86-only `cfg` arm never compiles on an Apple machine, so type-check the other target before pushing anything `cfg`-gated (needs only `rustup target add x86_64-unknown-linux-gnu`; `bench` and the binaries are left out because jemalloc's build script wants a cross `gcc`): ```bash RUSTFLAGS="-C target-cpu=znver4" \ diff --git a/Cargo.lock b/Cargo.lock index abba83434d..4ec5ad216b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -405,6 +405,25 @@ dependencies = [ "zkdsl_compiler", ] +[[package]] +name = "leanvm-sidecar" +version = "0.1.0" +dependencies = [ + "bench", + "clap", + "lean_vm", + "leanvm_sidecar_client", + "libc", + "tracing", +] + +[[package]] +name = "leanvm_sidecar_client" +version = "0.1.0" +dependencies = [ + "libc", +] + [[package]] name = "libc" version = "0.2.186" diff --git a/bins/leanvm-sidecar/Cargo.toml b/bins/leanvm-sidecar/Cargo.toml new file mode 100644 index 0000000000..6180edf03f --- /dev/null +++ b/bins/leanvm-sidecar/Cargo.toml @@ -0,0 +1,18 @@ +[package] +name = "leanvm-sidecar" +version.workspace = true +edition.workspace = true +publish = false + +[lints] +workspace = true + +[dependencies] +lean_vm = { path = "../../crates/lean_vm" } +bench.workspace = true +libc.workspace = true +tracing.workspace = true +clap = { version = "4", features = ["derive"] } + +[dev-dependencies] +leanvm_sidecar_client = { path = "../../crates/leanvm_sidecar_client" } diff --git a/bins/leanvm-sidecar/PROTOCOL.md b/bins/leanvm-sidecar/PROTOCOL.md new file mode 100644 index 0000000000..6a640e347d --- /dev/null +++ b/bins/leanvm-sidecar/PROTOCOL.md @@ -0,0 +1,131 @@ +# leanvm-sidecar protocol, version 1 + +`leanvm-sidecar` serves leanXMSS aggregation, recursion and verification to one client process over one shared file. The server creates the file; the client opens it read-write and maps all of it `MAP_SHARED`. Every integer is little-endian. Every offset is in bytes from the start of the file. + +Clients that implement this document: `crates/leanvm_sidecar_client` (Rust), `clients/go`, `clients/java`, `clients/typescript` and `clients/nim`. Each exposes `send`, which places a payload in the arena and queues its request, and `try_recv`, which returns the next response if there is one. + +The file holds a header, a request ring, a response ring and an arena. Payloads live in the arena; the rings carry 64-byte messages that point into it. + +## Header + +Twelve `u64` words at offset 0. The client reads them once after mapping; only `epoch` changes afterwards. + +| offset | field | meaning | +| --- | --- | --- | +| 0 | `magic` | the ASCII bytes `LEANVMSH` | +| 8 | `version` | 1 | +| 16 | `epoch` | incremented each time the server starts | +| 24 | `ring_cap` | slots in each ring, a power of two | +| 32 | `total` | file size | +| 40 | `req_ring` | offset of the request ring | +| 48 | `resp_ring` | offset of the response ring | +| 56 | `arena_off` | offset of the arena | +| 64 | `arena_len` | arena size, `total - arena_off` | +| 72 | `pub_key_size` | bytes in a leanXMSS public key | +| 80 | `message_len` | bytes in a message | +| 88 | `sig_size` | bytes in a leanXMSS signature | + +A client checks `magic` and `version` and takes every other number from the header. + +A request in flight when the server stops is lost. A client that reads a different `epoch` than the one it saw when it sent a request stops waiting for that request and sends it again. Requests still queued in the request ring survive a restart and are served. + +## Rings + +Each ring is single-producer, single-consumer: the client produces requests and consumes responses, the server the reverse. A client with several threads serializes its own access. + +| offset in ring | field | +| --- | --- | +| 0 | `head`, `u64`: messages consumed, written only by the consumer | +| 64 | `tail`, `u64`: messages produced, written only by the producer | +| 128 | `ring_cap` slots of 64 bytes | + +Both counters only grow. Message `i` is in slot `i mod ring_cap`. + +- Produce: read `tail` and `head`. If `tail - head == ring_cap` the ring is full: wait and retry. Otherwise write the message to slot `tail mod ring_cap`, then store `tail + 1`. +- Consume: read `head` and `tail`. If they are equal the ring is empty. Otherwise read slot `head mod ring_cap`, then store `head + 1`. + +`head` and `tail` are read and written with atomic 64-bit operations, and the store that follows a slot access must be a releasing (or sequentially consistent) store: `sync/atomic` in Go, a `VarHandle` `getVolatile`/`setVolatile` on the mapped buffer in Java. There is no wake-up primitive. Both sides poll; the server polls an empty request ring every 100 microseconds. + +## Arena + +The server never allocates in the arena. The client places each request's payload wherever it likes and names, in the request, a second region for the response. The client alone decides when a region is free again: a request's two regions are the server's from the moment the request is produced until its response is consumed. + +The server copies the payload out before decoding it, so a client may not rely on the server seeing a later write. + +## Messages + +Request, 64 bytes: + +| offset | field | meaning | +| --- | --- | --- | +| 0 | `id` `u64` | echoed in the response | +| 8 | `op` `u32` | below | +| 12 | `flags` `u32` | below | +| 16 | `req_off` `u64` | payload region | +| 24 | `req_len` `u64` | | +| 32 | `resp_off` `u64` | response region | +| 40 | `resp_cap` `u64` | its capacity | +| 48 | `log_inv_rate` `u32` | PCS rate of the proof to make, 1 through 4; higher is a smaller proof and slower proving. Ignored by `VERIFY` | +| 52 | zero | | + +Response, 64 bytes: + +| offset | field | meaning | +| --- | --- | --- | +| 0 | `id` `u64` | the request's | +| 8 | `status` `u32` | below | +| 12 | `detail` `u32` | depends on `status` | +| 16 | `resp_len` `u64` | bytes written at `resp_off`, except under `RESP_TOO_SMALL` | +| 24 | zero | | + +Both regions must lie inside the arena. Responses come in request order. + +## Payloads + +Building blocks: + +- `claims` := `n u32 | n x (pubkey | message)`. An aggregate's claims are strictly sorted on the bytes of `pubkey | message`, with no duplicate; a proof is rejected against claims that are not. +- `proof` := `len u64 | len bytes`. The bytes are opaque to the client. A proof carries no claims: the two always travel together. +- `signatures` := `n u32 | n x (pubkey | message | signature)`, in any order. A repeated `(pubkey, message)` counts once. + +| op | name | request payload | response body | +| --- | --- | --- | --- | +| 1 | `AGGREGATE` | `signatures` | `proof \| claims` | +| 2 | `RECURSE` | `n u32 \| n x (claims \| proof)` | `proof \| claims` | +| 3 | `VERIFY` | `claims \| proof` | empty | +| 4 | `VERIFY_NARROW` | `claims \| proof \| claims` | `proof \| claims` | +| 5 | `EXTEND` | `n u32 \| n x (claims \| proof) \| signatures` | `proof \| claims` | + +- `AGGREGATE` proves that every signature is valid. The signatures are assumed valid: an invalid one fails the whole request with `AGGREGATION_FAILED`, without saying which. +- `RECURSE` proves the union of its children's claims. With flag `VERIFY_CHILDREN` (bit 0) the server verifies each child first and reports the first bad one as `INVALID_PROOF` with its index. Without it the client asserts the children are verified; a bad child then fails the request late as `AGGREGATION_FAILED`, usually without its index. +- `VERIFY` checks a proof against the claims given. `OK` means exactly these public keys signed exactly these messages. +- `VERIFY_NARROW` verifies the proof against the first claims, then makes a proof of the second claims, which must be a subset of the first. +- `EXTEND` is `RECURSE` and `AGGREGATE` in one proof: it proves the union of its children's claims and the signatures' claims. `VERIFY_CHILDREN` and the rules for signatures apply as in those two. + +`RECURSE` and `EXTEND` take 1 to 16 children, the kept proof included. + +| flag | bit | ops | meaning | +| --- | --- | --- | --- | +| `VERIFY_CHILDREN` | 0 | `RECURSE`, `EXTEND` | verify each child in the payload before proving | +| `KEEP_PROOF` | 1 | every op but `VERIFY` | the server keeps the proof it returns, in place of any it held | +| `USE_KEPT` | 2 | `RECURSE`, `EXTEND` | the kept proof is one more child, after those in the payload, which may then be none | + +The server holds at most one kept proof, in memory. It lets a client grow a proof over several `EXTEND` requests without sending it back each time: `AGGREGATE` with `KEEP_PROOF`, then `EXTEND` with `USE_KEPT | KEEP_PROOF` and a payload of `0 u32 | signatures`, and the last `EXTEND` with `USE_KEPT` alone. A request with `USE_KEPT` that succeeds ends the keeping of that proof, so without `KEEP_PROOF` nothing is kept afterwards. A request that fails changes nothing, and `USE_KEPT` with nothing kept is `BAD_REQUEST`. A proof that did not fit its response region (`RESP_TOO_SMALL`) is kept all the same. The kept proof is never verified again, and a server restart loses it. + +The response body repeats the claims because the server sorts and deduplicates them. + +## Status + +| status | name | `detail` | body | +| --- | --- | --- | --- | +| 0 | `OK` | 0 | the op's response | +| 1 | `BAD_REQUEST` | 0 | text | +| 2 | `RESP_TOO_SMALL` | 0 | nothing; `resp_len` is the capacity needed | +| 3 | `INVALID_PROOF` | index of the proof in the request | text | +| 4 | `AGGREGATION_FAILED` | reason, below | text | + +`BAD_REQUEST` is a region outside the arena, an unknown op, or a payload that does not decode or has trailing bytes. The text of a failure is UTF-8 for a human, cut to `resp_cap`, possibly inside a character. + +`RESP_TOO_SMALL` is found only after the proof is made, and the proof is discarded: size the response region generously. + +`AGGREGATION_FAILED` reasons: 1 invalid child, 4 invalid signature, 11 proving failed (an invalid signature or child that was not caught earlier, or too many signatures for one proof), 12 invalid input (nothing to prove, a retained claim that is not among the proof's, too many children, `log_inv_rate` out of range); the text says which. 2, 3 and 5 through 10 are no longer sent: 12 replaces them. diff --git a/bins/leanvm-sidecar/README.md b/bins/leanvm-sidecar/README.md new file mode 100644 index 0000000000..e002a8feb6 --- /dev/null +++ b/bins/leanvm-sidecar/README.md @@ -0,0 +1,97 @@ +# leanvm-sidecar + +A long-lived leanVM prover and verifier for one client process on the same machine. The client and the sidecar share one file on tmpfs: payloads sit in an arena inside it, and two rings of 64-byte messages carry requests and responses. The client can be written in any language that can map a file and do an atomic 64-bit load and store. + +It serves five operations, on leanXMSS signatures only: + +| op | what it does | +| --- | --- | +| `AGGREGATE` | prove a batch of `(pubkey, message, signature)` | +| `RECURSE` | prove the union of up to 16 proofs' claims | +| `VERIFY` | check a proof against its claims | +| `VERIFY_NARROW` | check a proof, then prove a subset of its claims | +| `EXTEND` | prove the union of up to 16 proofs' claims and a batch of signatures | + +[`PROTOCOL.md`](PROTOCOL.md) is the byte-level specification: the file layout, the messages, the payload encodings and the status codes. + +## Build and run + +Release only: the guest compiler overflows the debug stack. + +```bash +cargo build --release -p leanvm-sidecar +target/release/leanvm-sidecar --path /dev/shm/leanvm --threads 16 +``` + +The sidecar builds the guest, runs its warm-up, creates the channel file and prints `serving `. The file appears only once it is ready, so a client may open it as soon as it exists. Stop the sidecar with a signal; it holds no state to flush. + +| flag | default | meaning | +| --- | --- | --- | +| `--path` | required | the channel file; put it on tmpfs (`/dev/shm`) | +| `--threads` | one per physical core | prover threads; verification always runs on one | +| `--arena-mib` | 64 | arena size; the payload and the response region of every request in flight have to fit | +| `--ring-cap` | 64 | slots in each ring, a power of two | +| `--warmup-signatures` | 1500 | signatures in the warm-up proofs; 0 skips the warm-up | +| `--warmup-rates` | `1,2` | the `log_inv_rate` values to warm up | +| `--tracing` | off | print a timing tree per request (`RUST_LOG` sets the level) | + +The warm-up is the discarded pass the benchmarks run before they measure: for each rate, one aggregation, one verification and one 16-wide recursion over signatures the sidecar makes for itself. Without it the first request of each shape is slower than the rest. Set `--warmup-signatures` to the largest batch expected and `--warmup-rates` to the rates requests will ask for. + +The whole file is faulted in at start, so the arena's memory is committed from then on. + +Requests are served one at a time, in order. A request in flight when the sidecar stops is lost; requests still queued are served after a restart on the same file. The header's `epoch` changes on every start, which is how a client notices. + +## Clients + +Each client exposes the same two calls, over raw payload bytes in the encodings of `PROTOCOL.md`: + +- `send(op, flags, log_inv_rate, payload, resp_cap)` copies the payload into the arena, reserves `resp_cap` bytes for the response and queues the request. It returns the request's id, or reports that the ring or the arena is full; it never blocks. +- `try_recv()` (`tryRecv` in Java, TypeScript and Nim) returns the next response with its body copied out, or nothing if the sidecar has not produced one. + +| language | where | notes | +| --- | --- | --- | +| Rust | [`crates/leanvm_sidecar_client`](../../crates/leanvm_sidecar_client) | depends on `libc` alone; links nothing of the prover | +| Go | [`clients/go`](clients/go) | package `leanvmsidecar`, standard library only | +| Java | [`clients/java`](clients/java) | `leanvmsidecar.Client`, Java 17 or later, no dependencies; channel files under 2 GiB | +| TypeScript | [`clients/typescript`](clients/typescript) | Node 18 or later; `client.ts` plus a small C addon (`mmap.c`) that maps the file, since Node cannot; `./build.sh` builds both into `dist/` | +| Nim | [`clients/nim`](clients/nim) | module `leanvmsidecar`, standard library only; needs the GCC or Clang backend for the atomics; the entry point is `openClient` | + +A client is for one thread at a time. Open one only while no request of an earlier client is outstanding: the sidecar would write that request's response into arena space the new client hands out again. + +The clients build no payloads and parse no bodies. The end-to-end runners below are the worked example in each language: `crates/leanvm_sidecar_client/examples/e2e.rs`, `clients/go/e2e/main.go`, `clients/java/leanvmsidecar/E2e.java`, `clients/typescript/e2e.ts` and `clients/nim/e2e.nim`. + +## End-to-end test + +```bash +bins/leanvm-sidecar/e2e.sh [--signatures N] [--batch-size N] [--aggregate-rate R] [--recurse-rate R] +``` + +| option | default | meaning | +| --- | --- | --- | +| `--signatures` | 1440 | signatures per batch, 1 to 1500 | +| `--batch-size` | `--signatures` | signatures per sub-batch | +| `--aggregate-rate` | 2 | `log_inv_rate` of each batch's proof | +| `--recurse-rate` | 1 | `log_inv_rate` of the recursion | + +The script builds the sidecar and the chosen language's runner, starts the sidecar with `` prover threads, and has the runner make sixteen `AGGREGATE` requests of `--signatures` signatures each, one after the other, then one `RECURSE` over the sixteen proofs and one `VERIFY` of the result. With `--batch-size`, each batch is instead built up in sub-batches of that size, the last one short: the first is an `AGGREGATE`, and each later one an `EXTEND` of the proof so far with the next signatures. The sidecar keeps that proof between the requests (flags `KEEP_PROOF` and `USE_KEPT`), so the runner sends only signatures. These run at `log_inv_rate` 1, except the last, which makes the batch's proof at `--aggregate-rate`. Each step prints its request, its response and the time from `send` to the response, as the client sees it. The script stops the sidecar and removes the channel file when the runner exits. + +```bash +bins/leanvm-sidecar/e2e.sh go 16 # Go client, 16 threads, defaults +bins/leanvm-sidecar/e2e.sh java 32 --signatures 1500 --aggregate-rate 1 # Java client, full batches, aggregate at rate 1 +bins/leanvm-sidecar/e2e.sh nim 32 --signatures 1400 --batch-size 150 # Nim client, each batch as 9 x 150 + 1 x 50 +``` + +The signatures are `testdata/signatures-24000.bin`: 24000 records of `pubkey | message | signature`, every record a different signer, signer `i` on message `i mod 4`. The signers are mock keys, real only at the leaf index they sign at; their signatures verify like any other. If the file is missing the script regenerates it with `examples/gen_signatures.rs`, which takes a minute or two. + +The Go runner needs `go` on `PATH`. The Java runner uses `javac` and `java` if they are on `PATH`, and otherwise the `eclipse-temurin:21-jdk` image through `docker`. The TypeScript runner needs `node`, `npm` and a C compiler: the script runs `clients/typescript/build.sh`, which installs the TypeScript compiler from npm on first use. The Nim runner uses `nim` if it is on `PATH`, and otherwise builds and runs in the `nimlang/nim:2.2.0` image through `docker`. + +## Tests + +```bash +cargo test --release -p leanvm-sidecar -p leanvm_sidecar_client +(cd bins/leanvm-sidecar/clients/go && go test ./...) +(cd bins/leanvm-sidecar/clients/typescript && ./build.sh && npm test) +nim c -r --outdir:target/leanvm-sidecar bins/leanvm-sidecar/clients/nim/leanvmsidecar.nim +``` + +The sidecar's test runs every op, and its failure cases, through the Rust client against the serving loop in one process. diff --git a/bins/leanvm-sidecar/clients/go/client.go b/bins/leanvm-sidecar/clients/go/client.go new file mode 100644 index 0000000000..c48214ddfe --- /dev/null +++ b/bins/leanvm-sidecar/clients/go/client.go @@ -0,0 +1,248 @@ +// Package leanvmsidecar is a client of the leanvm-sidecar service: Send a request, TryRecv its response. +// +// Payloads and response bodies are raw bytes in the encodings of PROTOCOL.md. It mirrors the Rust +// client in crates/leanvm_sidecar_client. +// +// One Client per channel, used from one goroutine at a time. Open it while no request of an earlier +// client is outstanding: the server would write that request's response into arena space this +// client hands out again. +// +// Little-endian hosts only: the ring counters are read as native words. +package leanvmsidecar + +import ( + "encoding/binary" + "errors" + "os" + "sync/atomic" + "syscall" + "unsafe" +) + +const ( + OpAggregate uint32 = 1 + OpRecurse uint32 = 2 + OpVerify uint32 = 3 + OpVerifyNarrow uint32 = 4 + OpExtend uint32 = 5 + + // FlagVerifyChildren makes OpRecurse and OpExtend verify every child natively before proving. + FlagVerifyChildren uint32 = 1 + // FlagKeepProof makes the server keep the proof it returns, in place of any it held. + FlagKeepProof uint32 = 2 + // FlagUseKept makes the kept proof one more child of OpRecurse and OpExtend; it is then no longer kept. + FlagUseKept uint32 = 4 + + StOK uint32 = 0 + StBadRequest uint32 = 1 + StRespTooSmall uint32 = 2 + StInvalidProof uint32 = 3 + StAggregationFailed uint32 = 4 +) + +const ( + magic = 0x48534d564e41454c // "LEANVMSH" + version = 1 + msgSize = 64 + + hMagic = 0 + hVersion = 8 + hEpoch = 16 + hRingCap = 24 + hTotal = 32 + hReqRing = 40 + hRespRing = 48 + hArenaOff = 56 + hArenaLen = 64 + hPubKeySize = 72 + hMessageLen = 80 + hSigSize = 88 + headerSize = 96 + + rHead = 0 + rTail = 64 + rSlots = 128 +) + +// ErrFull: the request ring or the arena has no room. Receive a response and retry. +var ErrFull = errors.New("leanvmsidecar: no room in the request ring or the arena") + +var errHeader = errors.New("leanvmsidecar: not a leanvm-sidecar channel of this version") + +type Response struct { + // ID is what Send returned for the request. + ID uint64 + Status uint32 + Detail uint32 + // RespLen is the body's length, or under StRespTooSmall the response capacity the request needed. + RespLen uint64 + // Body is the op's response under StOK, UTF-8 text for a human on a failure, empty under StRespTooSmall. + Body []byte +} + +// block is a request's arena region: its payload, then its response region. Offsets from the arena's start. +type block struct { + id uint64 + off uint64 + payloadLen uint64 + respCap uint64 +} + +func (b block) end() uint64 { return b.off + b.payloadLen + b.respCap } + +type Client struct { + data []byte + ringCap uint64 + reqRing uint64 + respRing uint64 + arenaOff uint64 + arenaLen uint64 + nextID uint64 + // Blocks of requests not yet answered, oldest first. The server answers in order, so the arena + // is a circular buffer of them: allocated at the back, freed at the front. + live []block +} + +// Open maps the channel the server created at path. Responses left by an earlier client are discarded. +func Open(path string) (*Client, error) { + file, err := os.OpenFile(path, os.O_RDWR, 0) + if err != nil { + return nil, err + } + defer file.Close() + info, err := file.Stat() + if err != nil { + return nil, err + } + total := uint64(info.Size()) + if total < headerSize { + return nil, errHeader + } + data, err := syscall.Mmap(int(file.Fd()), 0, int(total), syscall.PROT_READ|syscall.PROT_WRITE, syscall.MAP_SHARED|mapPopulate) + if err != nil { + return nil, err + } + c := &Client{data: data} + field := func(at uint64) uint64 { return atomic.LoadUint64(c.word(at)) } + c.ringCap, c.reqRing, c.respRing = field(hRingCap), field(hReqRing), field(hRespRing) + c.arenaOff, c.arenaLen = field(hArenaOff), field(hArenaLen) + // Every later access is in bounds given these: the rings sit below the arena, the arena inside the file. + ringFits := func(ring uint64) bool { + return ring%8 == 0 && ring+rSlots <= c.arenaOff && c.ringCap <= (c.arenaOff-ring-rSlots)/msgSize + } + ok := field(hMagic) == magic && field(hVersion) == version && field(hTotal) == total && + c.ringCap != 0 && c.ringCap&(c.ringCap-1) == 0 && + c.arenaOff <= total && c.arenaLen == total-c.arenaOff && + ringFits(c.reqRing) && ringFits(c.respRing) + if !ok { + syscall.Munmap(data) + return nil, errHeader + } + atomic.StoreUint64(c.word(c.respRing+rHead), atomic.LoadUint64(c.word(c.respRing+rTail))) + return c, nil +} + +// Close unmaps the channel. The Client must not be used afterwards. +func (c *Client) Close() error { + data := c.data + c.data = nil + return syscall.Munmap(data) +} + +// word is the u64 at an 8-aligned offset; the mapping is page-aligned. +func (c *Client) word(at uint64) *uint64 { + return (*uint64)(unsafe.Pointer(&c.data[at : at+8][0])) +} + +func (c *Client) slot(ring, index uint64) []byte { + at := ring + rSlots + (index&(c.ringCap-1))*msgSize + return c.data[at : at+msgSize] +} + +// Epoch is incremented each time the server starts. A request in flight across a restart gets no response. +func (c *Client) Epoch() uint64 { return atomic.LoadUint64(c.word(hEpoch)) } + +func (c *Client) PubKeySize() int { return int(atomic.LoadUint64(c.word(hPubKeySize))) } +func (c *Client) MessageLen() int { return int(atomic.LoadUint64(c.word(hMessageLen))) } +func (c *Client) SigSize() int { return int(atomic.LoadUint64(c.word(hSigSize))) } + +// place says where a block of n bytes goes, from the arena's start, given the blocks still held. +func place(live []block, arenaLen, n uint64) (uint64, bool) { + if len(live) == 0 { + return 0, n <= arenaLen + } + first, last := live[0], live[len(live)-1] + end := last.end() + switch { + case last.off < first.off: + // Wrapped: the gap up to the oldest block. + return end, n <= first.off-end + case n <= arenaLen-end: + return end, true + default: + // Wrap into the space before the oldest block. first.off > 0 keeps last.off < first.off meaning wrapped. + return 0, first.off > 0 && n <= first.off + } +} + +// Send queues a request and returns its id. respCap bytes of arena are reserved for the response: +// a proof that does not fit is discarded by the server (StRespTooSmall). +func (c *Client) Send(op, flags, logInvRate uint32, payload []byte, respCap int) (uint64, error) { + tail := atomic.LoadUint64(c.word(c.reqRing + rTail)) + if tail-atomic.LoadUint64(c.word(c.reqRing+rHead)) >= c.ringCap { + return 0, ErrFull + } + if respCap < 0 || uint64(respCap) > c.arenaLen || uint64(len(payload)) > c.arenaLen { + return 0, ErrFull + } + b := block{payloadLen: uint64(len(payload)), respCap: uint64(respCap)} + off, ok := place(c.live, c.arenaLen, b.payloadLen+b.respCap) + if !ok { + return 0, ErrFull + } + c.nextID++ + b.id, b.off = c.nextID, off + reqOff := c.arenaOff + off + copy(c.data[reqOff:reqOff+b.payloadLen], payload) + + msg := c.slot(c.reqRing, tail) + le := binary.LittleEndian + le.PutUint64(msg[0:], b.id) + le.PutUint32(msg[8:], op) + le.PutUint32(msg[12:], flags) + le.PutUint64(msg[16:], reqOff) + le.PutUint64(msg[24:], b.payloadLen) + le.PutUint64(msg[32:], reqOff+b.payloadLen) + le.PutUint64(msg[40:], b.respCap) + le.PutUint32(msg[48:], logInvRate) + clear(msg[52:]) + atomic.StoreUint64(c.word(c.reqRing+rTail), tail+1) + c.live = append(c.live, b) + return b.id, nil +} + +// TryRecv returns the next response, if the server has produced one. It frees the request's arena +// block, and those of earlier requests that a server restart left unanswered. +func (c *Client) TryRecv() (Response, bool) { + head := atomic.LoadUint64(c.word(c.respRing + rHead)) + if atomic.LoadUint64(c.word(c.respRing+rTail)) == head { + return Response{}, false + } + msg := c.slot(c.respRing, head) + le := binary.LittleEndian + r := Response{ID: le.Uint64(msg[0:]), Status: le.Uint32(msg[8:]), Detail: le.Uint32(msg[12:]), RespLen: le.Uint64(msg[16:])} + atomic.StoreUint64(c.word(c.respRing+rHead), head+1) + + for len(c.live) > 0 && c.live[0].id < r.ID { + c.live = c.live[1:] + } + if len(c.live) > 0 && c.live[0].id == r.ID { + b := c.live[0] + c.live = c.live[1:] + if r.Status != StRespTooSmall && r.RespLen <= b.respCap { + respOff := c.arenaOff + b.off + b.payloadLen + r.Body = append([]byte(nil), c.data[respOff:respOff+r.RespLen]...) + } + } + return r, true +} diff --git a/bins/leanvm-sidecar/clients/go/client_test.go b/bins/leanvm-sidecar/clients/go/client_test.go new file mode 100644 index 0000000000..67cc2d8fc4 --- /dev/null +++ b/bins/leanvm-sidecar/clients/go/client_test.go @@ -0,0 +1,34 @@ +package leanvmsidecar + +import "testing" + +// Random sends and in-order frees: a placed block is inside the arena and overlaps no live one. +func TestBlocksNeverOverlap(t *testing.T) { + const arenaLen = 100 + var live []block + state, placed := uint64(1), 0 + for id := uint64(0); id < 10000; id++ { + state = state*6364136223846793005 + 1442695040888963407 + n := (state >> 33) % 40 + if off, ok := place(live, arenaLen, n); ok { + if off+n > arenaLen { + t.Fatalf("block [%d, %d) outside the arena", off, off+n) + } + for _, b := range live { + if off+n > b.off && b.end() > off { + t.Fatalf("block [%d, %d) overlaps [%d, %d)", off, off+n, b.off, b.end()) + } + } + live = append(live, block{id: id, off: off, payloadLen: n}) + placed++ + } else { + live = live[1:] + } + if state>>63 == 1 && len(live) > 0 { + live = live[1:] + } + } + if placed <= 1000 { + t.Fatal("too few blocks placed") + } +} diff --git a/bins/leanvm-sidecar/clients/go/e2e/main.go b/bins/leanvm-sidecar/clients/go/e2e/main.go new file mode 100644 index 0000000000..42bad1fbd6 --- /dev/null +++ b/bins/leanvm-sidecar/clients/go/e2e/main.go @@ -0,0 +1,155 @@ +// The run e2e.sh drives: e2e +// +// Sixteen AGGREGATE requests of signatures-per-batch signatures each, one after the other, then one RECURSE over +// the sixteen proofs and one VERIFY of the result. With sub-batch below signatures-per-batch, each +// batch is instead built up in parts of sub-batch signatures: an AGGREGATE, then one EXTEND per part +// of the proof so far, which the server keeps. Parts run at rate 1, except the last at aggregate-rate. The file is records of pubkey | message | signature. +package main + +import ( + "encoding/binary" + "fmt" + "os" + "strconv" + "time" + + leanvmsidecar "github.com/leanEthereum/leanVM/bins/leanvm-sidecar/clients/go" +) + +const ( + batches = 16 + respCap = 16 << 20 +) + +func fatal(err error) { + if err != nil { + fmt.Fprintln(os.Stderr, err) + os.Exit(1) + } +} + +// call sends one request and waits for its response. +func call(client *leanvmsidecar.Client, op, flags, rate uint32, payload []byte) (leanvmsidecar.Response, time.Duration) { + started := time.Now() + id, err := client.Send(op, flags, rate, payload, respCap) + fatal(err) + for { + response, ok := client.TryRecv() + if !ok { + time.Sleep(100 * time.Microsecond) + continue + } + if response.ID != id { + fatal(fmt.Errorf("response %d to request %d", response.ID, id)) + } + return response, time.Since(started) + } +} + +func check(response leanvmsidecar.Response) { + if response.Status != leanvmsidecar.StOK { + fmt.Printf(" FAILED: status %d detail %d: %s\n", response.Status, response.Detail, response.Body) + os.Exit(1) + } +} + +// split cuts a proof | claims body into the two, each with its length prefix. +func split(response leanvmsidecar.Response) (proof, claims []byte) { + check(response) + proofLen := binary.LittleEndian.Uint64(response.Body) + return response.Body[:8+proofLen], response.Body[8+proofLen:] +} + +// step makes one proving request, prints it, with the time since a non-zero since, and returns the +// response's proof and claims. +func step(client *leanvmsidecar.Client, op, flags, rate uint32, payload []byte, label, what string, since time.Time) (proof, claims []byte) { + response, elapsed := call(client, op, flags, rate, payload) + batch := "" + if !since.IsZero() { + batch = fmt.Sprintf(", batch total %.3f s", time.Since(since).Seconds()) + } + proof, claims = split(response) + fmt.Printf("%s: %s, %d bytes, rate %d -> proof %d bytes, %d claims, %.3f s%s\n", + label, what, len(payload), rate, len(proof)-8, binary.LittleEndian.Uint32(claims), elapsed.Seconds(), batch) + return proof, claims +} + +// aggregate is an AGGREGATE over records, each record bytes; under FlagUseKept, an EXTEND of the proof +// the server kept with them. +func aggregate(client *leanvmsidecar.Client, flags uint32, records []byte, record int, rate uint32, label string, since time.Time) ([]byte, []byte) { + le := binary.LittleEndian + count := len(records) / record + op, what := leanvmsidecar.OpAggregate, fmt.Sprintf("%d signatures", count) + var payload []byte + if flags&leanvmsidecar.FlagUseKept != 0 { + op, what = leanvmsidecar.OpExtend, fmt.Sprintf("kept proof + %d signatures", count) + // No child in the payload. + payload = le.AppendUint32(payload, 0) + } + payload = append(le.AppendUint32(payload, uint32(count)), records...) + return step(client, op, flags, rate, payload, label, what, since) +} + +func main() { + if len(os.Args) != 7 { + fmt.Fprintln(os.Stderr, "usage: e2e ") + os.Exit(2) + } + aggregateRate, err := strconv.ParseUint(os.Args[3], 10, 32) + fatal(err) + recurseRate, err := strconv.ParseUint(os.Args[4], 10, 32) + fatal(err) + perBatch, err := strconv.Atoi(os.Args[5]) + fatal(err) + subBatch, err := strconv.Atoi(os.Args[6]) + fatal(err) + client, err := leanvmsidecar.Open(os.Args[1]) + fatal(err) + defer client.Close() + record := client.PubKeySize() + client.MessageLen() + client.SigSize() + signatures, err := os.ReadFile(os.Args[2]) + fatal(err) + if len(signatures) < batches*perBatch*record { + fatal(fmt.Errorf("signature file too short")) + } + + total := time.Now() + le := binary.LittleEndian + parts := (perBatch + subBatch - 1) / subBatch + recurse := le.AppendUint32(nil, batches) + for batch := 0; batch < batches; batch++ { + records := signatures[batch*perBatch*record : (batch+1)*perBatch*record] + var proof, claims []byte + started := time.Now() + for part := 0; part < parts; part++ { + sub := records[part*subBatch*record : min((part+1)*subBatch*record, len(records))] + // Every part but the first extends the proof the server kept; every part but the last + // has it keep the new one. The last part's proof is the batch's. + name, flags, rate := "aggregate", leanvmsidecar.FlagKeepProof, uint32(1) + if part > 0 { + name, flags = "extend ", flags|leanvmsidecar.FlagUseKept + } + var since time.Time + if part+1 == parts { + flags, rate = flags&^leanvmsidecar.FlagKeepProof, uint32(aggregateRate) + if parts > 1 { + since = started + } + } + label := fmt.Sprintf("%s %2d/%d", name, batch+1, batches) + if parts > 1 { + label += fmt.Sprintf(" part %2d/%d", part+1, parts) + } + proof, claims = aggregate(client, flags, sub, record, rate, label, since) + } + recurse = append(append(recurse, claims...), proof...) + } + proof, claims := step(client, leanvmsidecar.OpRecurse, 0, uint32(recurseRate), recurse, + fmt.Sprintf("recurse %d -> 1", batches), fmt.Sprintf("%d proofs", batches), time.Time{}) + verify := append(append([]byte(nil), claims...), proof...) + verdict, elapsed := call(client, leanvmsidecar.OpVerify, 0, 0, verify) + check(verdict) + fmt.Printf("verify: proof %d bytes, %d claims, %d bytes -> valid, %.3f s\n", + len(proof)-8, le.Uint32(claims), len(verify), elapsed.Seconds()) + fmt.Printf("total: %.3f s\n", time.Since(total).Seconds()) +} diff --git a/bins/leanvm-sidecar/clients/go/go.mod b/bins/leanvm-sidecar/clients/go/go.mod new file mode 100644 index 0000000000..6a675eae53 --- /dev/null +++ b/bins/leanvm-sidecar/clients/go/go.mod @@ -0,0 +1,3 @@ +module github.com/leanEthereum/leanVM/bins/leanvm-sidecar/clients/go + +go 1.21 diff --git a/bins/leanvm-sidecar/clients/go/populate_linux.go b/bins/leanvm-sidecar/clients/go/populate_linux.go new file mode 100644 index 0000000000..0a2872f45b --- /dev/null +++ b/bins/leanvm-sidecar/clients/go/populate_linux.go @@ -0,0 +1,6 @@ +package leanvmsidecar + +import "syscall" + +// mapPopulate maps every page at mmap, so no request takes this process's first-touch faults on the arena. +const mapPopulate = syscall.MAP_POPULATE diff --git a/bins/leanvm-sidecar/clients/go/populate_other.go b/bins/leanvm-sidecar/clients/go/populate_other.go new file mode 100644 index 0000000000..3b7d57d382 --- /dev/null +++ b/bins/leanvm-sidecar/clients/go/populate_other.go @@ -0,0 +1,5 @@ +//go:build !linux + +package leanvmsidecar + +const mapPopulate = 0 diff --git a/bins/leanvm-sidecar/clients/java/leanvmsidecar/Client.java b/bins/leanvm-sidecar/clients/java/leanvmsidecar/Client.java new file mode 100644 index 0000000000..30adc9c88a --- /dev/null +++ b/bins/leanvm-sidecar/clients/java/leanvmsidecar/Client.java @@ -0,0 +1,253 @@ +package leanvmsidecar; + +import java.io.IOException; +import java.lang.invoke.MethodHandles; +import java.lang.invoke.VarHandle; +import java.nio.ByteOrder; +import java.nio.MappedByteBuffer; +import java.nio.channels.FileChannel; +import java.nio.file.Path; +import java.nio.file.StandardOpenOption; +import java.util.ArrayDeque; + +/** + * Client of the leanvm-sidecar service: {@link #send} a request, {@link #tryRecv} its response. + * + *

Payloads and response bodies are raw bytes in the encodings of PROTOCOL.md. It mirrors the Rust + * client in crates/leanvm_sidecar_client. Java 17 or later; the channel file must be smaller than 2 GiB. + * + *

One Client per channel, used from one thread at a time. Open it while no request of an earlier + * client is outstanding: the server would write that request's response into arena space this client + * hands out again. The mapping lives until the Client is garbage collected. + */ +public final class Client { + public static final int OP_AGGREGATE = 1; + public static final int OP_RECURSE = 2; + public static final int OP_VERIFY = 3; + public static final int OP_VERIFY_NARROW = 4; + public static final int OP_EXTEND = 5; + + /** {@link #OP_RECURSE}, {@link #OP_EXTEND}: verify every child natively before proving. */ + public static final int FLAG_VERIFY_CHILDREN = 1; + /** A proving op: the server keeps the proof it returns, in place of any it held. */ + public static final int FLAG_KEEP_PROOF = 2; + /** {@link #OP_RECURSE}, {@link #OP_EXTEND}: the kept proof is one more child, and is no longer kept. */ + public static final int FLAG_USE_KEPT = 4; + + public static final int ST_OK = 0; + public static final int ST_BAD_REQUEST = 1; + public static final int ST_RESP_TOO_SMALL = 2; + public static final int ST_INVALID_PROOF = 3; + public static final int ST_AGGREGATION_FAILED = 4; + + /** + * @param id what {@link #send} returned for the request + * @param respLen the body's length, or under {@link #ST_RESP_TOO_SMALL} the response capacity the request needed + * @param body the op's response under {@link #ST_OK}, UTF-8 text for a human on a failure, empty under + * {@link #ST_RESP_TOO_SMALL} + */ + public record Response(long id, int status, int detail, long respLen, byte[] body) {} + + private static final long MAGIC = 0x48534d564e41454cL; // "LEANVMSH" + private static final long VERSION = 1; + private static final int MSG_SIZE = 64; + + private static final int H_MAGIC = 0; + private static final int H_VERSION = 8; + private static final int H_EPOCH = 16; + private static final int H_RING_CAP = 24; + private static final int H_TOTAL = 32; + private static final int H_REQ_RING = 40; + private static final int H_RESP_RING = 48; + private static final int H_ARENA_OFF = 56; + private static final int H_ARENA_LEN = 64; + private static final int H_PUB_KEY_SIZE = 72; + private static final int H_MESSAGE_LEN = 80; + private static final int H_SIG_SIZE = 88; + private static final int HEADER_SIZE = 96; + + private static final int R_HEAD = 0; + private static final int R_TAIL = 64; + private static final int R_SLOTS = 128; + + /** Atomic access to the u64 at an 8-aligned offset; the mapping is page-aligned. */ + private static final VarHandle WORD = + MethodHandles.byteBufferViewVarHandle(long[].class, ByteOrder.LITTLE_ENDIAN); + + /** A request's arena block: its payload, then its response region. Offsets from the arena's start. */ + private record Block(long id, int off, int payloadLen, int respCap) { + int end() { + return off + payloadLen + respCap; + } + } + + private final MappedByteBuffer buf; + private final int ringCap; + private final int reqRing; + private final int respRing; + private final int arenaOff; + private final int arenaLen; + private long nextId; + /** + * Blocks of requests not yet answered, oldest first. The server answers in order, so the arena is a + * circular buffer of them: allocated at the back, freed at the front. + */ + private final ArrayDeque live = new ArrayDeque<>(); + + private Client(MappedByteBuffer buf, int ringCap, int reqRing, int respRing, int arenaOff, int arenaLen) { + this.buf = buf; + this.ringCap = ringCap; + this.reqRing = reqRing; + this.respRing = respRing; + this.arenaOff = arenaOff; + this.arenaLen = arenaLen; + } + + /** Map the channel the server created at {@code path}. Responses left by an earlier client are discarded. */ + public static Client open(Path path) throws IOException { + MappedByteBuffer buf; + long total; + try (FileChannel file = FileChannel.open(path, StandardOpenOption.READ, StandardOpenOption.WRITE)) { + total = file.size(); + if (total < HEADER_SIZE || total > Integer.MAX_VALUE) { + throw new IOException("not a leanvm-sidecar channel, or 2 GiB or larger"); + } + buf = file.map(FileChannel.MapMode.READ_WRITE, 0, total); + } + // Map every page now, so no request takes this process's first-touch faults on the arena. + buf.load(); + buf.order(ByteOrder.LITTLE_ENDIAN); + long ringCap = buf.getLong(H_RING_CAP); + long reqRing = buf.getLong(H_REQ_RING); + long respRing = buf.getLong(H_RESP_RING); + long arenaOff = buf.getLong(H_ARENA_OFF); + long arenaLen = buf.getLong(H_ARENA_LEN); + // Every later access is in bounds given these: the rings sit below the arena, the arena inside the file. + boolean ok = buf.getLong(H_MAGIC) == MAGIC + && buf.getLong(H_VERSION) == VERSION + && buf.getLong(H_TOTAL) == total + && ringCap > 0 + && Long.bitCount(ringCap) == 1 + && arenaOff >= 0 + && arenaOff <= total + && arenaLen == total - arenaOff + && ringFits(reqRing, ringCap, arenaOff) + && ringFits(respRing, ringCap, arenaOff); + if (!ok) { + throw new IOException("not a leanvm-sidecar channel of this version"); + } + Client client = new Client(buf, (int) ringCap, (int) reqRing, (int) respRing, (int) arenaOff, (int) arenaLen); + WORD.setVolatile(buf, client.respRing + R_HEAD, (long) WORD.getVolatile(buf, client.respRing + R_TAIL)); + return client; + } + + private static boolean ringFits(long ring, long ringCap, long arenaOff) { + return ring >= 0 && ring % 8 == 0 && ring + R_SLOTS <= arenaOff && ringCap <= (arenaOff - ring - R_SLOTS) / MSG_SIZE; + } + + private int slot(int ring, long index) { + return ring + R_SLOTS + (int) (index & (ringCap - 1)) * MSG_SIZE; + } + + /** Incremented each time the server starts. A request in flight across a restart gets no response. */ + public long epoch() { + return (long) WORD.getVolatile(buf, H_EPOCH); + } + + public int pubKeySize() { + return (int) buf.getLong(H_PUB_KEY_SIZE); + } + + public int messageLen() { + return (int) buf.getLong(H_MESSAGE_LEN); + } + + public int sigSize() { + return (int) buf.getLong(H_SIG_SIZE); + } + + /** Where a block of {@code len} bytes goes, from the arena's start, given the blocks still held; -1 if nowhere. */ + static int place(ArrayDeque live, int arenaLen, long len) { + if (live.isEmpty()) { + return len <= arenaLen ? 0 : -1; + } + Block first = live.peekFirst(); + Block last = live.peekLast(); + int end = last.end(); + if (last.off() < first.off()) { + // Wrapped: the gap up to the oldest block. + return len <= first.off() - end ? end : -1; + } + if (len <= arenaLen - end) { + return end; + } + // Wrap into the space before the oldest block. first.off > 0 keeps last.off < first.off meaning wrapped. + return first.off() > 0 && len <= first.off() ? 0 : -1; + } + + /** + * Queue a request. {@code respCap} bytes of arena are reserved for the response: a proof that does not + * fit is discarded by the server ({@link #ST_RESP_TOO_SMALL}). + * + * @return the request's id, at least 1, or 0 if the request ring or the arena has no room: receive a + * response and retry + */ + public long send(int op, int flags, int logInvRate, byte[] payload, int respCap) { + long tail = (long) WORD.getVolatile(buf, reqRing + R_TAIL); + if (tail - (long) WORD.getVolatile(buf, reqRing + R_HEAD) >= ringCap || respCap < 0) { + return 0; + } + int off = place(live, arenaLen, (long) payload.length + respCap); + if (off < 0) { + return 0; + } + long id = ++nextId; + int reqOff = arenaOff + off; + buf.put(reqOff, payload, 0, payload.length); + + int msg = slot(reqRing, tail); + buf.putLong(msg, id); + buf.putInt(msg + 8, op); + buf.putInt(msg + 12, flags); + buf.putLong(msg + 16, reqOff); + buf.putLong(msg + 24, payload.length); + buf.putLong(msg + 32, reqOff + payload.length); + buf.putLong(msg + 40, respCap); + buf.putInt(msg + 48, logInvRate); + buf.putInt(msg + 52, 0); + buf.putLong(msg + 56, 0); + WORD.setVolatile(buf, reqRing + R_TAIL, tail + 1); + live.addLast(new Block(id, off, payload.length, respCap)); + return id; + } + + /** + * The next response, or null if the server has produced none. Frees the request's arena block, and + * those of earlier requests that a server restart left unanswered. + */ + public Response tryRecv() { + long head = (long) WORD.getVolatile(buf, respRing + R_HEAD); + if ((long) WORD.getVolatile(buf, respRing + R_TAIL) == head) { + return null; + } + int msg = slot(respRing, head); + long id = buf.getLong(msg); + int status = buf.getInt(msg + 8); + int detail = buf.getInt(msg + 12); + long respLen = buf.getLong(msg + 16); + WORD.setVolatile(buf, respRing + R_HEAD, head + 1); + + byte[] body = new byte[0]; + while (!live.isEmpty() && live.peekFirst().id() < id) { + live.removeFirst(); + } + if (!live.isEmpty() && live.peekFirst().id() == id) { + Block block = live.removeFirst(); + if (status != ST_RESP_TOO_SMALL && respLen >= 0 && respLen <= block.respCap()) { + body = new byte[(int) respLen]; + buf.get(arenaOff + block.off() + block.payloadLen(), body, 0, body.length); + } + } + return new Response(id, status, detail, respLen, body); + } +} diff --git a/bins/leanvm-sidecar/clients/java/leanvmsidecar/E2e.java b/bins/leanvm-sidecar/clients/java/leanvmsidecar/E2e.java new file mode 100644 index 0000000000..a21b55df21 --- /dev/null +++ b/bins/leanvm-sidecar/clients/java/leanvmsidecar/E2e.java @@ -0,0 +1,163 @@ +package leanvmsidecar; + +import java.io.ByteArrayOutputStream; +import java.nio.ByteBuffer; +import java.nio.ByteOrder; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; + +/** + * The run e2e.sh drives: E2e <channel> <signatures-file> <aggregate-rate> <recurse-rate> + * <signatures-per-batch> <sub-batch> + * + *

Sixteen AGGREGATE requests of signatures-per-batch signatures each, one after the other, then one RECURSE over the + * sixteen proofs and one VERIFY of the result. With sub-batch below signatures-per-batch, each batch is + * instead built up in parts of sub-batch signatures: an AGGREGATE, then one EXTEND per part of the proof so + * far, which the server keeps. Parts run at rate 1, except the last at aggregate-rate. The file is records of pubkey | message | signature. + */ +public final class E2e { + private static final int BATCHES = 16; + private static final int RESP_CAP = 16 << 20; + + private static long elapsedNanos; + + /** Send one request and wait for its response; the time taken is left in {@link #elapsedNanos}. */ + private static Client.Response call(Client client, int op, int flags, int rate, byte[] payload) + throws InterruptedException { + long started = System.nanoTime(); + long id = client.send(op, flags, rate, payload, RESP_CAP); + if (id == 0) { + throw new IllegalStateException("no room in the channel"); + } + Client.Response response; + while ((response = client.tryRecv()) == null) { + Thread.sleep(0, 100_000); + } + if (response.id() != id) { + throw new IllegalStateException("response " + response.id() + " to request " + id); + } + elapsedNanos = System.nanoTime() - started; + return response; + } + + private static void check(Client.Response response) { + if (response.status() != Client.ST_OK) { + String text = new String(response.body(), StandardCharsets.UTF_8); + System.out.printf(" FAILED: status %d detail %d: %s%n", response.status(), response.detail(), text); + System.exit(1); + } + } + + /** The length of the proof, prefix included, at the start of a proof | claims body. */ + private static int proofEnd(Client.Response response) { + check(response); + return 8 + (int) le(response.body()).getLong(0); + } + + private static ByteBuffer le(byte[] bytes) { + return ByteBuffer.wrap(bytes).order(ByteOrder.LITTLE_ENDIAN); + } + + private static byte[] u32(int value) { + return ByteBuffer.allocate(4).order(ByteOrder.LITTLE_ENDIAN).putInt(value).array(); + } + + /** + * One proving request: prints the step, with the time since the nanoTime since if not null, and returns the + * response's proof | claims body. + */ + private static byte[] step( + Client client, int op, int flags, int rate, byte[] payload, String label, String what, Long since) + throws InterruptedException { + Client.Response response = call(client, op, flags, rate, payload); + String batch = since == null ? "" : String.format(", batch total %.3f s", (System.nanoTime() - since) / 1e9); + int proofEnd = proofEnd(response); + System.out.printf( + "%s: %s, %d bytes, rate %d -> proof %d bytes, %d claims, %.3f s%s%n", + label, what, payload.length, rate, proofEnd - 8, le(response.body()).getInt(proofEnd), + elapsedNanos / 1e9, batch); + return response.body(); + } + + /** + * AGGREGATE over count records of record bytes each, starting at record from; under FLAG_USE_KEPT, EXTEND + * of the proof the server kept with them. + */ + private static byte[] aggregate( + Client client, int flags, byte[] signatures, int from, int count, int record, int rate, String label, + Long since) + throws InterruptedException { + boolean extend = (flags & Client.FLAG_USE_KEPT) != 0; + ByteArrayOutputStream payload = new ByteArrayOutputStream(); + if (extend) { + // No child in the payload. + payload.writeBytes(u32(0)); + } + payload.writeBytes(u32(count)); + payload.write(signatures, from * record, count * record); + int op = extend ? Client.OP_EXTEND : Client.OP_AGGREGATE; + String what = (extend ? "kept proof + " : "") + count + " signatures"; + return step(client, op, flags, rate, payload.toByteArray(), label, what, since); + } + + /** Append a proof | claims body as claims | proof. */ + private static void child(ByteArrayOutputStream out, byte[] body) { + int proofEnd = 8 + (int) le(body).getLong(0); + out.write(body, proofEnd, body.length - proofEnd); + out.write(body, 0, proofEnd); + } + + public static void main(String[] args) throws Exception { + if (args.length != 6) { + System.err.println("usage: E2e "); + System.exit(2); + } + int aggregateRate = Integer.parseInt(args[2]); + int recurseRate = Integer.parseInt(args[3]); + int perBatch = Integer.parseInt(args[4]); + int subBatch = Integer.parseInt(args[5]); + Client client = Client.open(Path.of(args[0])); + int record = client.pubKeySize() + client.messageLen() + client.sigSize(); + byte[] signatures = Files.readAllBytes(Path.of(args[1])); + if (signatures.length < BATCHES * perBatch * record) { + throw new IllegalArgumentException("signature file too short"); + } + + long total = System.nanoTime(); + int parts = (perBatch + subBatch - 1) / subBatch; + ByteArrayOutputStream recurse = new ByteArrayOutputStream(); + recurse.writeBytes(u32(BATCHES)); + for (int batch = 0; batch < BATCHES; batch++) { + byte[] body = null; + long started = System.nanoTime(); + for (int part = 0; part < parts; part++) { + boolean first = part == 0; + boolean last = part + 1 == parts; + int count = Math.min(subBatch, perBatch - part * subBatch); + String label = String.format("%s %2d/%d", first ? "aggregate" : "extend ", batch + 1, BATCHES); + if (parts > 1) { + label += String.format(" part %2d/%d", part + 1, parts); + } + // Every part but the first extends the proof the server kept; every part but the last has it + // keep the new one. The last part's proof is the batch's. + int flags = (first ? 0 : Client.FLAG_USE_KEPT) | (last ? 0 : Client.FLAG_KEEP_PROOF); + int rate = last ? aggregateRate : 1; + Long since = parts > 1 && last ? started : null; + int from = batch * perBatch + part * subBatch; + body = aggregate(client, flags, signatures, from, count, record, rate, label, since); + } + child(recurse, body); + } + byte[] body = step(client, Client.OP_RECURSE, 0, recurseRate, recurse.toByteArray(), + "recurse " + BATCHES + " -> 1", BATCHES + " proofs", null); + int proofEnd = 8 + (int) le(body).getLong(0); + ByteArrayOutputStream verify = new ByteArrayOutputStream(); + child(verify, body); + check(call(client, Client.OP_VERIFY, 0, 0, verify.toByteArray())); + System.out.printf( + "verify: proof %d bytes, %d claims, %d bytes -> valid, %.3f s%n", + proofEnd - 8, le(body).getInt(proofEnd), verify.size(), elapsedNanos / 1e9); + System.out.printf("total: %.3f s%n", (System.nanoTime() - total) / 1e9); + } +} diff --git a/bins/leanvm-sidecar/clients/nim/e2e.nim b/bins/leanvm-sidecar/clients/nim/e2e.nim new file mode 100644 index 0000000000..002cdcb7eb --- /dev/null +++ b/bins/leanvm-sidecar/clients/nim/e2e.nim @@ -0,0 +1,131 @@ +## The run e2e.sh drives: e2e +## +## Sixteen AGGREGATE requests of signatures-per-batch signatures each, one after the other, then one RECURSE over +## the sixteen proofs and one VERIFY of the result. With sub-batch below signatures-per-batch, each +## batch is instead built up in parts of sub-batch signatures: an AGGREGATE, then one EXTEND per part +## of the proof so far, which the server keeps. Parts run at rate 1, except the last at aggregate-rate. The file is records of pubkey | message | signature. + +import std/[monotimes, options, os, strformat, strutils, times] +from std/posix import usleep +import leanvmsidecar + +const + batches = 16 + respCap = 16'u64 shl 20 + +proc fatal(text: string) {.noreturn.} = + stderr.writeLine(text) + quit(1) + +proc seconds(since: MonoTime): float = float((getMonoTime() - since).inMicroseconds) / 1e6 + +proc putU32(buf: var seq[byte], value: uint32) = + for shift in [0, 8, 16, 24]: buf.add(byte((value shr shift) and 0xff)) + +func u32(buf: openArray[byte], at: int): uint32 = + for i in 0 ..< 4: result = result or (uint32(buf[at + i]) shl (8 * i)) + +func u64(buf: openArray[byte], at: int): uint64 = + for i in 0 ..< 8: result = result or (uint64(buf[at + i]) shl (8 * i)) + +# Sends one request and waits for its response. +proc call(client: var Client, op, flags, rate: uint32, payload: openArray[byte]): (Response, float) = + let + started = getMonoTime() + id = client.send(op, flags, rate, payload, respCap) + if id.isNone: fatal("no room in the request ring or the arena") + while true: + let response = client.tryRecv() + if response.isNone: + discard usleep(100) + continue + if response.get.id != id.get: fatal(&"response {response.get.id} to request {id.get}") + return (response.get, seconds(started)) + +proc check(response: Response) = + if response.status != StOk: + let text = cast[string](response.body) + fatal(&" FAILED: status {response.status} detail {response.detail}: {text}") + +# Cuts a proof | claims body into the two, each with its length prefix. +proc split(response: Response): (seq[byte], seq[byte]) = + check(response) + let cut = 8 + int(u64(response.body, 0)) + (response.body[0 ..< cut], response.body[cut .. ^1]) + +# One proving request: prints the step, with the time since `since` if given, and returns the +# response's (proof, claims). +proc step(client: var Client, op, flags, rate: uint32, payload: openArray[byte], label, what: string, + since = none(MonoTime)): (seq[byte], seq[byte]) = + let + (response, elapsed) = client.call(op, flags, rate, payload) + batch = if since.isSome: &", batch total {seconds(since.get):.3f} s" else: "" + result = split(response) + echo &"{label}: {what}, {payload.len} bytes, rate {rate}", + &" -> proof {result[0].len - 8} bytes, {u32(result[1], 0)} claims, {elapsed:.3f} s{batch}" + +# AGGREGATE over `count` records of `record` bytes each, starting at record `first`; under +# FlagUseKept, EXTEND of the proof the server kept with them. +proc aggregate(client: var Client, flags: uint32, signatures: string, first, count, record: int, rate: uint32, + label: string, since: Option[MonoTime]): (seq[byte], seq[byte]) = + let extend = (flags and FlagUseKept) != 0 + var payload: seq[byte] + # No child in the payload. + if extend: payload.putU32(0) + payload.putU32(uint32(count)) + let at = payload.len + payload.setLen(at + count * record) + copyMem(addr payload[at], addr signatures[first * record], count * record) + if extend: client.step(OpExtend, flags, rate, payload, label, &"kept proof + {count} signatures", since) + else: client.step(OpAggregate, flags, rate, payload, label, &"{count} signatures", since) + +proc main() = + if paramCount() != 6: + stderr.writeLine("usage: e2e ") + quit(2) + let + aggregateRate = uint32(parseUInt(paramStr(3))) + recurseRate = uint32(parseUInt(paramStr(4))) + perBatch = parseInt(paramStr(5)) + subBatch = parseInt(paramStr(6)) + var client = openClient(paramStr(1)) + let + record = client.pubKeySize + client.messageLen + client.sigSize + signatures = readFile(paramStr(2)) + parts = (perBatch + subBatch - 1) div subBatch + if signatures.len < batches * perBatch * record: fatal("signature file too short") + + let total = getMonoTime() + var recurse: seq[byte] + recurse.putU32(batches) + for batch in 0 ..< batches: + var proved: (seq[byte], seq[byte]) + let started = getMonoTime() + for part in 0 ..< parts: + let + first = part == 0 + last = part + 1 == parts + name = if first: "aggregate" else: "extend " + var label = &"{name} {batch + 1:2}/{batches}" + if parts > 1: label &= &" part {part + 1:2}/{parts}" + let + count = min(subBatch, perBatch - part * subBatch) + # Every part but the first extends the proof the server kept; every part but the last has + # it keep the new one. The last part's proof is the batch's. + flags = (if first: 0'u32 else: FlagUseKept) or (if last: 0'u32 else: FlagKeepProof) + rate = if last: aggregateRate else: 1'u32 + since = if parts > 1 and last: some(started) else: none(MonoTime) + proved = client.aggregate(flags, signatures, batch * perBatch + part * subBatch, count, record, rate, label, + since) + recurse.add(proved[1]) + recurse.add(proved[0]) + let + (proof, claims) = client.step(OpRecurse, 0, recurseRate, recurse, &"recurse {batches} -> 1", &"{batches} proofs") + verify = claims & proof + (verdict, verifyElapsed) = client.call(OpVerify, 0, 0, verify) + check(verdict) + echo &"verify: proof {proof.len - 8} bytes, {u32(claims, 0)} claims, {verify.len} bytes -> valid, {verifyElapsed:.3f} s" + echo &"total: {seconds(total):.3f} s" + client.close() + +main() diff --git a/bins/leanvm-sidecar/clients/nim/leanvmsidecar.nim b/bins/leanvm-sidecar/clients/nim/leanvmsidecar.nim new file mode 100644 index 0000000000..4a4c0ce6d7 --- /dev/null +++ b/bins/leanvm-sidecar/clients/nim/leanvmsidecar.nim @@ -0,0 +1,238 @@ +## Client of the leanvm-sidecar service: `send` a request, `tryRecv` its response. +## +## Payloads and response bodies are raw bytes in the encodings of PROTOCOL.md. It mirrors the Rust +## client in crates/leanvm_sidecar_client. +## +## One Client per channel, used from one thread at a time. Open it while no request of an earlier +## client is outstanding: the server would write that request's response into arena space this +## client hands out again. +## +## Little-endian hosts only: counters and message fields are read as native words. The atomics are +## the GCC and Clang builtins. + +import std/[deques, options, oserrors, posix] + +const + OpAggregate* = 1'u32 + OpRecurse* = 2'u32 + OpVerify* = 3'u32 + OpVerifyNarrow* = 4'u32 + OpExtend* = 5'u32 + + ## Makes OpRecurse and OpExtend verify every child natively before proving. + FlagVerifyChildren* = 1'u32 + ## A proving op: the server keeps the proof it returns, in place of any it held. + FlagKeepProof* = 2'u32 + ## OpRecurse, OpExtend: the kept proof is one more child, and is no longer kept. + FlagUseKept* = 4'u32 + + StOk* = 0'u32 + StBadRequest* = 1'u32 + StRespTooSmall* = 2'u32 + StInvalidProof* = 3'u32 + StAggregationFailed* = 4'u32 + +const + magic = 0x48534d564e41454c'u64 # "LEANVMSH" + version = 1'u64 + msgSize = 64'u64 + + hMagic = 0'u64 + hVersion = 8'u64 + hEpoch = 16'u64 + hRingCap = 24'u64 + hTotal = 32'u64 + hReqRing = 40'u64 + hRespRing = 48'u64 + hArenaOff = 56'u64 + hArenaLen = 64'u64 + hPubKeySize = 72'u64 + hMessageLen = 80'u64 + hSigSize = 88'u64 + headerSize = 96'u64 + + rHead = 0'u64 + rTail = 64'u64 + rSlots = 128'u64 + + mapPopulate = when defined(linux): MAP_POPULATE else: 0.cint + +type + Response* = object + id*: uint64 ## What `send` returned for the request. + status*: uint32 + detail*: uint32 + respLen*: uint64 ## The body's length, or under StRespTooSmall the response capacity the request needed. + body*: seq[byte] ## The op's response under StOk, UTF-8 text for a human on a failure, empty under StRespTooSmall. + + # A request's arena region: its payload, then its response region. Offsets from the arena's start. + Block = object + id, off, payloadLen, respCap: uint64 + + Client* = object + base: pointer + total, ringCap, reqRing, respRing, arenaOff, arenaLen, nextId: uint64 + # Blocks of requests not yet answered, oldest first. The server answers in order, so the arena + # is a circular buffer of them: allocated at the back, freed at the front. + live: Deque[Block] + +func stop(b: Block): uint64 = b.off + b.payloadLen + b.respCap + +func at(c: Client, off: uint64): pointer = cast[pointer](cast[uint](c.base) + uint(off)) + +# `off` is 8-aligned; the mapping is page-aligned. +proc load(c: Client, off: uint64): uint64 = atomicLoadN(cast[ptr uint64](c.at(off)), ATOMIC_ACQUIRE) + +proc store(c: Client, off, value: uint64) = atomicStoreN(cast[ptr uint64](c.at(off)), value, ATOMIC_RELEASE) + +func slot(c: Client, ring, index: uint64): pointer = c.at(ring + rSlots + (index and (c.ringCap - 1)) * msgSize) + +proc put[T](msg: pointer, off: uint, value: T) = + var v = value + copyMem(cast[pointer](cast[uint](msg) + off), addr v, sizeof(T)) + +proc get[T](msg: pointer, off: uint): T = copyMem(addr result, cast[pointer](cast[uint](msg) + off), sizeof(T)) + +proc openClient*(path: string): Client = + ## Maps the channel the server created at `path`. Responses left by an earlier client are discarded. + let fd = posix.open(path.cstring, O_RDWR) + if fd < 0: raiseOSError(osLastError(), path) + var st: Stat + if fstat(fd, st) != 0: + let err = osLastError() + discard posix.close(fd) + raiseOSError(err, path) + let total = uint64(st.st_size) + if total < headerSize: + discard posix.close(fd) + raise newException(IOError, "not a leanvm-sidecar channel of this version") + let base = mmap(nil, int(total), PROT_READ or PROT_WRITE, MAP_SHARED or mapPopulate, fd, 0) + let err = osLastError() + discard posix.close(fd) + if base == MAP_FAILED: raiseOSError(err, path) + + var c = Client(base: base, total: total) + c.ringCap = c.load(hRingCap) + c.reqRing = c.load(hReqRing) + c.respRing = c.load(hRespRing) + c.arenaOff = c.load(hArenaOff) + c.arenaLen = c.load(hArenaLen) + # Every later access is in bounds given these: the rings sit below the arena, the arena inside the file. + proc ringFits(ring: uint64): bool = + ring mod 8 == 0 and ring + rSlots <= c.arenaOff and c.ringCap <= (c.arenaOff - ring - rSlots) div msgSize + let ok = c.load(hMagic) == magic and c.load(hVersion) == version and c.load(hTotal) == total and + c.ringCap != 0 and (c.ringCap and (c.ringCap - 1)) == 0 and + c.arenaOff <= total and c.arenaLen == total - c.arenaOff and + ringFits(c.reqRing) and ringFits(c.respRing) + if not ok: + discard munmap(base, int(total)) + raise newException(IOError, "not a leanvm-sidecar channel of this version") + c.store(c.respRing + rHead, c.load(c.respRing + rTail)) + c + +proc close*(c: var Client) = + ## Unmaps the channel. The Client must not be used afterwards. + discard munmap(c.base, int(c.total)) + c.base = nil + +proc epoch*(c: Client): uint64 = + ## Incremented each time the server starts. A request in flight across a restart gets no response. + c.load(hEpoch) + +proc pubKeySize*(c: Client): int = int(c.load(hPubKeySize)) +proc messageLen*(c: Client): int = int(c.load(hMessageLen)) +proc sigSize*(c: Client): int = int(c.load(hSigSize)) + +# Where a block of `n` bytes goes, from the arena's start, given the blocks still held. +func place(live: Deque[Block], arenaLen, n: uint64): Option[uint64] = + if live.len == 0: + return if n <= arenaLen: some(0'u64) else: none(uint64) + let + first = live.peekFirst + last = live.peekLast + stop = last.stop + if last.off < first.off: + # Wrapped: the gap up to the oldest block. + if n <= first.off - stop: some(stop) else: none(uint64) + elif n <= arenaLen - stop: + some(stop) + # Wrap into the space before the oldest block. first.off > 0 keeps last.off < first.off meaning wrapped. + elif first.off > 0 and n <= first.off: + some(0'u64) + else: + none(uint64) + +proc send*(c: var Client, op, flags, logInvRate: uint32, payload: openArray[byte], respCap: uint64): Option[uint64] = + ## Queues a request and returns its id, or none if the request ring or the arena has no room: + ## receive a response and retry. `respCap` bytes of arena are reserved for the response: a proof + ## that does not fit is discarded by the server (StRespTooSmall). + let tail = c.load(c.reqRing + rTail) + if tail - c.load(c.reqRing + rHead) >= c.ringCap: return none(uint64) + let payloadLen = uint64(payload.len) + if respCap > c.arenaLen or payloadLen > c.arenaLen: return none(uint64) + let off = place(c.live, c.arenaLen, payloadLen + respCap) + if off.isNone: return none(uint64) + inc c.nextId + let + b = Block(id: c.nextId, off: off.get, payloadLen: payloadLen, respCap: respCap) + reqOff = c.arenaOff + b.off + if payload.len > 0: copyMem(c.at(reqOff), addr payload[0], payload.len) + + let msg = c.slot(c.reqRing, tail) + put(msg, 0, b.id) + put(msg, 8, op) + put(msg, 12, flags) + put(msg, 16, reqOff) + put(msg, 24, payloadLen) + put(msg, 32, reqOff + payloadLen) + put(msg, 40, respCap) + put(msg, 48, logInvRate) + zeroMem(cast[pointer](cast[uint](msg) + 52), 12) + c.store(c.reqRing + rTail, tail + 1) + c.live.addLast(b) + some(b.id) + +proc tryRecv*(c: var Client): Option[Response] = + ## The next response, if the server has produced one. Frees the request's arena block, and those + ## of earlier requests that a server restart left unanswered. + let head = c.load(c.respRing + rHead) + if c.load(c.respRing + rTail) == head: return none(Response) + let msg = c.slot(c.respRing, head) + var r = Response( + id: get[uint64](msg, 0), + status: get[uint32](msg, 8), + detail: get[uint32](msg, 12), + respLen: get[uint64](msg, 16), + ) + c.store(c.respRing + rHead, head + 1) + + while c.live.len > 0 and c.live.peekFirst.id < r.id: c.live.popFirst() + if c.live.len > 0 and c.live.peekFirst.id == r.id: + let b = c.live.popFirst() + if r.status != StRespTooSmall and r.respLen <= b.respCap and r.respLen > 0: + r.body = newSeq[byte](r.respLen) + copyMem(addr r.body[0], c.at(c.arenaOff + b.off + b.payloadLen), r.respLen) + some(r) + +when isMainModule: + # Random sends and in-order frees: a placed block is inside the arena and overlaps no live one. + const arenaLen = 100'u64 + var + live: Deque[Block] + state = 1'u64 + placed = 0 + for id in 0'u64 ..< 10000'u64: + state = state * 6364136223846793005'u64 + 1442695040888963407'u64 + let + n = (state shr 33) mod 40 + off = place(live, arenaLen, n) + if off.isSome: + doAssert off.get + n <= arenaLen, "block outside the arena" + for b in live: doAssert not (off.get + n > b.off and b.stop > off.get), "blocks overlap" + live.addLast(Block(id: id, off: off.get, payloadLen: n)) + inc placed + else: + live.popFirst() + if (state shr 63) == 1 and live.len > 0: live.popFirst() + doAssert placed > 1000, "too few blocks placed" + echo "ok" diff --git a/bins/leanvm-sidecar/clients/typescript/.gitignore b/bins/leanvm-sidecar/clients/typescript/.gitignore new file mode 100644 index 0000000000..f06235c460 --- /dev/null +++ b/bins/leanvm-sidecar/clients/typescript/.gitignore @@ -0,0 +1,2 @@ +node_modules +dist diff --git a/bins/leanvm-sidecar/clients/typescript/build.sh b/bins/leanvm-sidecar/clients/typescript/build.sh new file mode 100755 index 0000000000..27802ee274 --- /dev/null +++ b/bins/leanvm-sidecar/clients/typescript/build.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash +# Build the client into dist/: the mmap addon with the C compiler, the TypeScript with tsc. +# Needs Node's headers (they ship with Node; NODE_INCLUDE overrides where) and `npm install` for tsc. +set -euo pipefail +cd "$(dirname "$0")" +include=${NODE_INCLUDE:-$(node -p "require('path').resolve(process.execPath, '..', '..', 'include', 'node')")} +[[ -d node_modules ]] || npm install --no-audit --no-fund +mkdir -p dist +# An addon's N-API symbols resolve against the node binary when it is loaded. +if [[ $(uname) == Darwin ]]; then undefined=(-undefined dynamic_lookup); else undefined=(); fi +${CC:-cc} -O2 -Wall -Wextra -shared -fPIC "${undefined[@]}" -DNODE_GYP_MODULE_NAME=mmap -I"$include" mmap.c -o dist/mmap.node +npx tsc diff --git a/bins/leanvm-sidecar/clients/typescript/client.test.ts b/bins/leanvm-sidecar/clients/typescript/client.test.ts new file mode 100644 index 0000000000..ddeff78804 --- /dev/null +++ b/bins/leanvm-sidecar/clients/typescript/client.test.ts @@ -0,0 +1,31 @@ +import { strict as assert } from "node:assert"; +import { test } from "node:test"; +import { Block, place } from "./client"; + +// Random sends and in-order frees: a placed block is inside the arena and overlaps no live one. +test("blocks never overlap", () => { + const arenaLen = 100; + let live: Block[] = []; + let state = 1n; + let placed = 0; + for (let id = 0n; id < 10000n; id++) { + state = (state * 6364136223846793005n + 1442695040888963407n) & ((1n << 64n) - 1n); + const len = Number((state >> 33n) % 40n); + const off = place(live, arenaLen, len); + if (off !== null) { + assert.ok(off + len <= arenaLen); + for (const b of live) { + const bEnd = b.off + b.payloadLen + b.respCap; + assert.ok(off + len <= b.off || bEnd <= off); + } + live.push({ id, off, payloadLen: len, respCap: 0 }); + placed++; + } else { + live = live.slice(1); + } + if (state >> 63n === 1n) { + live = live.slice(1); + } + } + assert.ok(placed > 1000); +}); diff --git a/bins/leanvm-sidecar/clients/typescript/client.ts b/bins/leanvm-sidecar/clients/typescript/client.ts new file mode 100644 index 0000000000..8c26c1bdf0 --- /dev/null +++ b/bins/leanvm-sidecar/clients/typescript/client.ts @@ -0,0 +1,258 @@ +// Client of the leanvm-sidecar service: send a request, tryRecv its response. +// +// Payloads and response bodies are raw bytes in the encodings of PROTOCOL.md. It mirrors the Rust +// client in crates/leanvm_sidecar_client. Node has no mmap, so the mapping comes from the small +// addon in mmap.c; everything else is here. +// +// One Client per channel. Open it while no request of an earlier client is outstanding: the server +// would write that request's response into arena space this client hands out again. +// +// Little-endian hosts only: the ring counters are read as native words. + +import { join } from "node:path"; + +// eslint-disable-next-line @typescript-eslint/no-var-requires +const native: { map(path: string): ArrayBuffer } = require(join(__dirname, "mmap.node")); + +export const OP_AGGREGATE = 1; +export const OP_RECURSE = 2; +export const OP_VERIFY = 3; +export const OP_VERIFY_NARROW = 4; +export const OP_EXTEND = 5; + +/** OP_RECURSE, OP_EXTEND: verify every child natively before proving. */ +export const FLAG_VERIFY_CHILDREN = 1; +/** A proving op: the server keeps the proof it returns, in place of any it held. */ +export const FLAG_KEEP_PROOF = 2; +/** OP_RECURSE, OP_EXTEND: the kept proof is one more child, and is no longer kept. */ +export const FLAG_USE_KEPT = 4; + +export const ST_OK = 0; +export const ST_BAD_REQUEST = 1; +export const ST_RESP_TOO_SMALL = 2; +export const ST_INVALID_PROOF = 3; +export const ST_AGGREGATION_FAILED = 4; + +const MAGIC = 0x48534d564e41454cn; // "LEANVMSH" +const VERSION = 1n; +const MSG_SIZE = 64; + +const H_MAGIC = 0; +const H_VERSION = 8; +const H_EPOCH = 16; +const H_RING_CAP = 24; +const H_TOTAL = 32; +const H_REQ_RING = 40; +const H_RESP_RING = 48; +const H_ARENA_OFF = 56; +const H_ARENA_LEN = 64; +const H_PUB_KEY_SIZE = 72; +const H_MESSAGE_LEN = 80; +const H_SIG_SIZE = 88; +const HEADER_SIZE = 96; + +const R_HEAD = 0; +const R_TAIL = 64; +const R_SLOTS = 128; + +const U64_MASK = (1n << 64n) - 1n; + +export interface Response { + /** What send returned for the request. */ + id: bigint; + status: number; + detail: number; + /** The body's length, or under ST_RESP_TOO_SMALL the response capacity the request needed. */ + respLen: bigint; + /** The op's response under ST_OK, UTF-8 text for a human on a failure, empty under ST_RESP_TOO_SMALL. */ + body: Uint8Array; +} + +/** A request's arena block: its payload, then its response region. Offsets from the arena's start. */ +export interface Block { + id: bigint; + off: number; + payloadLen: number; + respCap: number; +} + +const end = (block: Block): number => block.off + block.payloadLen + block.respCap; + +/** Where a block of len bytes goes, from the arena's start, given the blocks still held; null if nowhere. */ +export function place(live: readonly Block[], arenaLen: number, len: number): number | null { + if (live.length === 0) { + return len <= arenaLen ? 0 : null; + } + const first = live[0]; + const last = live[live.length - 1]; + const lastEnd = end(last); + if (last.off < first.off) { + // Wrapped: the gap up to the oldest block. + return len <= first.off - lastEnd ? lastEnd : null; + } + if (len <= arenaLen - lastEnd) { + return lastEnd; + } + // Wrap into the space before the oldest block. first.off > 0 keeps last.off < first.off meaning wrapped. + return first.off > 0 && len <= first.off ? 0 : null; +} + +export class Client { + private readonly bytes: Uint8Array; + private readonly view: DataView; + /** The file as u64 words, for atomic access to the ring counters: word i is at offset 8 * i. */ + private readonly words: BigUint64Array; + private readonly ringCap: bigint; + private readonly reqRing: number; + private readonly respRing: number; + private readonly arenaOff: number; + private readonly arenaLen: number; + private nextId = 0n; + /** + * Blocks of requests not yet answered, oldest first. The server answers in order, so the arena is a + * circular buffer of them: allocated at the back, freed at the front. + */ + private live: Block[] = []; + + /** Map the channel the server created at path. Responses left by an earlier client are discarded. */ + static open(path: string): Client { + return new Client(native.map(path)); + } + + private constructor(buffer: ArrayBuffer) { + const total = buffer.byteLength; + if (total < HEADER_SIZE) { + throw new Error("not a leanvm-sidecar channel"); + } + this.bytes = new Uint8Array(buffer); + this.view = new DataView(buffer); + this.words = new BigUint64Array(buffer, 0, Math.floor(total / 8)); + const field = (at: number): bigint => this.view.getBigUint64(at, true); + const ringCap = field(H_RING_CAP); + const arenaOff = field(H_ARENA_OFF); + // Every later access is in bounds given these: the rings sit below the arena, the arena inside the file. + const ringFits = (ring: bigint): boolean => + ring % 8n === 0n && ring + BigInt(R_SLOTS) + ringCap * BigInt(MSG_SIZE) <= arenaOff; + const ok = + field(H_MAGIC) === MAGIC && + field(H_VERSION) === VERSION && + field(H_TOTAL) === BigInt(total) && + ringCap > 0n && + ringCap <= BigInt(total) && + (ringCap & (ringCap - 1n)) === 0n && + arenaOff <= BigInt(total) && + field(H_ARENA_LEN) === BigInt(total) - arenaOff && + ringFits(field(H_REQ_RING)) && + ringFits(field(H_RESP_RING)); + if (!ok) { + throw new Error("not a leanvm-sidecar channel of this version"); + } + this.ringCap = ringCap; + this.reqRing = Number(field(H_REQ_RING)); + this.respRing = Number(field(H_RESP_RING)); + this.arenaOff = Number(arenaOff); + this.arenaLen = total - this.arenaOff; + this.store(this.respRing + R_HEAD, this.load(this.respRing + R_TAIL)); + } + + /** Atomic load of the u64 at an 8-aligned offset. */ + private load(at: number): bigint { + return Atomics.load(this.words, at / 8); + } + + private store(at: number, value: bigint): void { + Atomics.store(this.words, at / 8, value); + } + + private slot(ring: number, index: bigint): number { + return ring + R_SLOTS + Number(index & (this.ringCap - 1n)) * MSG_SIZE; + } + + /** Incremented each time the server starts. A request in flight across a restart gets no response. */ + epoch(): bigint { + return this.load(H_EPOCH); + } + + pubKeySize(): number { + return Number(this.view.getBigUint64(H_PUB_KEY_SIZE, true)); + } + + messageLen(): number { + return Number(this.view.getBigUint64(H_MESSAGE_LEN, true)); + } + + sigSize(): number { + return Number(this.view.getBigUint64(H_SIG_SIZE, true)); + } + + /** + * Queue a request. respCap bytes of arena are reserved for the response: a proof that does not fit + * is discarded by the server (ST_RESP_TOO_SMALL). + * + * Returns the request's id, or null if the request ring or the arena has no room: receive a + * response and retry. + */ + send(op: number, flags: number, logInvRate: number, payload: Uint8Array, respCap: number): bigint | null { + const tail = this.load(this.reqRing + R_TAIL); + if (((tail - this.load(this.reqRing + R_HEAD)) & U64_MASK) >= this.ringCap) { + return null; + } + if (!Number.isSafeInteger(respCap) || respCap < 0) { + return null; + } + const off = place(this.live, this.arenaLen, payload.length + respCap); + if (off === null) { + return null; + } + const id = ++this.nextId; + const reqOff = this.arenaOff + off; + this.bytes.set(payload, reqOff); + + const msg = this.slot(this.reqRing, tail); + this.view.setBigUint64(msg, id, true); + this.view.setUint32(msg + 8, op, true); + this.view.setUint32(msg + 12, flags, true); + this.view.setBigUint64(msg + 16, BigInt(reqOff), true); + this.view.setBigUint64(msg + 24, BigInt(payload.length), true); + this.view.setBigUint64(msg + 32, BigInt(reqOff + payload.length), true); + this.view.setBigUint64(msg + 40, BigInt(respCap), true); + this.view.setUint32(msg + 48, logInvRate, true); + this.bytes.fill(0, msg + 52, msg + MSG_SIZE); + this.store(this.reqRing + R_TAIL, (tail + 1n) & U64_MASK); + this.live.push({ id, off, payloadLen: payload.length, respCap }); + return id; + } + + /** + * The next response, or null if the server has produced none. Frees the request's arena block, and + * those of earlier requests that a server restart left unanswered. + */ + tryRecv(): Response | null { + const head = this.load(this.respRing + R_HEAD); + if (this.load(this.respRing + R_TAIL) === head) { + return null; + } + const msg = this.slot(this.respRing, head); + const response: Response = { + id: this.view.getBigUint64(msg, true), + status: this.view.getUint32(msg + 8, true), + detail: this.view.getUint32(msg + 12, true), + respLen: this.view.getBigUint64(msg + 16, true), + body: new Uint8Array(0), + }; + this.store(this.respRing + R_HEAD, (head + 1n) & U64_MASK); + + while (this.live.length > 0 && this.live[0].id < response.id) { + this.live.shift(); + } + if (this.live.length > 0 && this.live[0].id === response.id) { + const block = this.live.shift()!; + if (response.status !== ST_RESP_TOO_SMALL && response.respLen <= BigInt(block.respCap)) { + const respOff = this.arenaOff + block.off + block.payloadLen; + // slice copies: the body outlives the arena block. + response.body = this.bytes.slice(respOff, respOff + Number(response.respLen)); + } + } + return response; + } +} diff --git a/bins/leanvm-sidecar/clients/typescript/e2e.ts b/bins/leanvm-sidecar/clients/typescript/e2e.ts new file mode 100644 index 0000000000..d471f9df1a --- /dev/null +++ b/bins/leanvm-sidecar/clients/typescript/e2e.ts @@ -0,0 +1,167 @@ +// The run e2e.sh drives: e2e +// +// Sixteen AGGREGATE requests of signatures-per-batch signatures each, one after the other, then one RECURSE over +// the sixteen proofs and one VERIFY of the result. With sub-batch below signatures-per-batch, each +// batch is instead built up in parts of sub-batch signatures: an AGGREGATE, then one EXTEND per part +// of the proof so far, which the server keeps. Parts run at rate 1, except the last at aggregate-rate. The file is records of pubkey | message | signature. + +import { readFileSync } from "node:fs"; +import { + Client, + FLAG_KEEP_PROOF, + FLAG_USE_KEPT, + OP_AGGREGATE, + OP_EXTEND, + OP_RECURSE, + OP_VERIFY, + Response, + ST_OK, +} from "./client"; + +const BATCHES = 16; +const RESP_CAP = 16 << 20; + +const sleeper = new Int32Array(new SharedArrayBuffer(4)); + +/** Send one request and wait for its response; also the seconds it took. */ +function call(client: Client, op: number, flags: number, rate: number, payload: Uint8Array): [Response, number] { + const started = process.hrtime.bigint(); + const id = client.send(op, flags, rate, payload, RESP_CAP); + if (id === null) { + throw new Error("no room in the channel"); + } + for (;;) { + const response = client.tryRecv(); + if (response === null) { + // A 100 microsecond sleep; nothing ever notifies. + Atomics.wait(sleeper, 0, 0, 0.1); + continue; + } + if (response.id !== id) { + throw new Error(`response ${response.id} to request ${id}`); + } + return [response, Number(process.hrtime.bigint() - started) / 1e9]; + } +} + +/** The body of a response that succeeded. */ +function check(response: Response): Buffer { + const body = Buffer.from(response.body.buffer, response.body.byteOffset, response.body.length); + if (response.status !== ST_OK) { + console.log(` FAILED: status ${response.status} detail ${response.detail}: ${body.toString("utf8")}`); + process.exit(1); + } + return body; +} + +/** A proof | claims body cut into the two, each with its length prefix. */ +function split(response: Response): [Buffer, Buffer] { + const body = check(response); + const proofEnd = 8 + Number(body.readBigUInt64LE(0)); + return [body.subarray(0, proofEnd), body.subarray(proofEnd)]; +} + +function u32(value: number): Buffer { + const out = Buffer.alloc(4); + out.writeUInt32LE(value); + return out; +} + +/** One proving request: prints the step, with the time since `since` if given, and returns the response's [proof, claims]. */ +function step( + client: Client, + op: number, + flags: number, + rate: number, + payload: Buffer, + label: string, + what: string, + since: bigint | null, +): [Buffer, Buffer] { + const [response, seconds] = call(client, op, flags, rate, payload); + const batch = + since === null ? "" : `, batch total ${(Number(process.hrtime.bigint() - since) / 1e9).toFixed(3)} s`; + const [proof, claims] = split(response); + console.log( + `${label}: ${what}, ${payload.length} bytes, rate ${rate} -> proof ${proof.length - 8} bytes, ` + + `${claims.readUInt32LE(0)} claims, ${seconds.toFixed(3)} s${batch}`, + ); + return [proof, claims]; +} + +/** AGGREGATE over records, each `record` bytes; under FLAG_USE_KEPT, EXTEND of the proof the server kept with them. */ +function aggregate( + client: Client, + flags: number, + records: Buffer, + record: number, + rate: number, + label: string, + since: bigint | null, +): [Buffer, Buffer] { + const count = records.length / record; + const signatures = [u32(count), records]; + if ((flags & FLAG_USE_KEPT) === 0) { + return step(client, OP_AGGREGATE, flags, rate, Buffer.concat(signatures), label, `${count} signatures`, since); + } + // No child in the payload. + const payload = Buffer.concat([u32(0), ...signatures]); + return step(client, OP_EXTEND, flags, rate, payload, label, `kept proof + ${count} signatures`, since); +} + +function main(): void { + const args = process.argv.slice(2); + if (args.length !== 6) { + console.error("usage: e2e "); + process.exit(2); + } + const aggregateRate = Number.parseInt(args[2], 10); + const recurseRate = Number.parseInt(args[3], 10); + const perBatch = Number.parseInt(args[4], 10); + const subBatch = Number.parseInt(args[5], 10); + const client = Client.open(args[0]); + const record = client.pubKeySize() + client.messageLen() + client.sigSize(); + const signatures = readFileSync(args[1]); + if (signatures.length < BATCHES * perBatch * record) { + throw new Error("signature file too short"); + } + + const total = process.hrtime.bigint(); + const parts = Math.ceil(perBatch / subBatch); + const recurse: Buffer[] = [u32(BATCHES)]; + for (let batch = 0; batch < BATCHES; batch++) { + const records = signatures.subarray(batch * perBatch * record, (batch + 1) * perBatch * record); + let proved: [Buffer, Buffer] | null = null; + const started = process.hrtime.bigint(); + for (let part = 0; part < parts; part++) { + const first = part === 0; + const last = part + 1 === parts; + // subarray clamps the last part to the batch. + const sub = records.subarray(part * subBatch * record, (part + 1) * subBatch * record); + let label = `${first ? "aggregate" : "extend "} ${String(batch + 1).padStart(2)}/${BATCHES}`; + if (parts > 1) { + label += ` part ${String(part + 1).padStart(2)}/${parts}`; + } + // Every part but the first extends the proof the server kept; every part but the last has it + // keep the new one. The last part's proof is the batch's. + const flags = (first ? 0 : FLAG_USE_KEPT) | (last ? 0 : FLAG_KEEP_PROOF); + const rate = last ? aggregateRate : 1; + const since = parts > 1 && last ? started : null; + proved = aggregate(client, flags, sub, record, rate, label, since); + } + recurse.push(proved![1], proved![0]); + } + const [proof, claims] = step( + client, OP_RECURSE, 0, recurseRate, Buffer.concat(recurse), `recurse ${BATCHES} -> 1`, `${BATCHES} proofs`, null, + ); + const verify = Buffer.concat([claims, proof]); + const [verdict, verifySeconds] = call(client, OP_VERIFY, 0, 0, verify); + check(verdict); + console.log( + `verify: proof ${proof.length - 8} bytes, ${claims.readUInt32LE(0)} claims, ${verify.length} bytes -> valid, ` + + `${verifySeconds.toFixed(3)} s`, + ); + console.log(`total: ${(Number(process.hrtime.bigint() - total) / 1e9).toFixed(3)} s`); +} + +main(); diff --git a/bins/leanvm-sidecar/clients/typescript/mmap.c b/bins/leanvm-sidecar/clients/typescript/mmap.c new file mode 100644 index 0000000000..e056f132fd --- /dev/null +++ b/bins/leanvm-sidecar/clients/typescript/mmap.c @@ -0,0 +1,72 @@ +// The one thing Node lacks: map(path) returns the whole file as an ArrayBuffer over a shared, +// writable mapping. The mapping is released when the ArrayBuffer is collected. + +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#ifndef MAP_POPULATE +#define MAP_POPULATE 0 +#endif + +static void unmap(napi_env env, void *data, void *hint) { + (void)env; + munmap(data, (size_t)(uintptr_t)hint); +} + +static napi_value fail(napi_env env, const char *what) { + napi_throw_error(env, NULL, what); + return NULL; +} + +static napi_value map(napi_env env, napi_callback_info info) { + size_t argc = 1; + napi_value arg; + char path[4096]; + size_t path_len; + if (napi_get_cb_info(env, info, &argc, &arg, NULL, NULL) != napi_ok || argc != 1 || + napi_get_value_string_utf8(env, arg, path, sizeof path, &path_len) != napi_ok || path_len == sizeof path - 1) { + return fail(env, "map(path): one string, shorter than 4095 bytes"); + } + int fd = open(path, O_RDWR | O_CLOEXEC); + if (fd < 0) { + return fail(env, strerror(errno)); + } + struct stat st; + if (fstat(fd, &st) != 0 || st.st_size <= 0) { + close(fd); + return fail(env, "cannot size the file, or it is empty"); + } + size_t len = (size_t)st.st_size; + // MAP_POPULATE: no request takes this process's first-touch faults on the arena. + void *base = mmap(NULL, len, PROT_READ | PROT_WRITE, MAP_SHARED | MAP_POPULATE, fd, 0); + int mmap_errno = errno; + close(fd); + if (base == MAP_FAILED) { + return fail(env, strerror(mmap_errno)); + } + napi_value buffer; + if (napi_create_external_arraybuffer(env, base, len, unmap, (void *)(uintptr_t)len, &buffer) != napi_ok) { + munmap(base, len); + return fail(env, "cannot wrap the mapping in an ArrayBuffer"); + } + return buffer; +} + +static napi_value init(napi_env env, napi_value exports) { + napi_value fn; + if (napi_create_function(env, "map", NAPI_AUTO_LENGTH, map, NULL, &fn) != napi_ok || + napi_set_named_property(env, exports, "map", fn) != napi_ok) { + return fail(env, "cannot export map"); + } + return exports; +} + +NAPI_MODULE(NODE_GYP_MODULE_NAME, init) diff --git a/bins/leanvm-sidecar/clients/typescript/package-lock.json b/bins/leanvm-sidecar/clients/typescript/package-lock.json new file mode 100644 index 0000000000..ca77b0b7d7 --- /dev/null +++ b/bins/leanvm-sidecar/clients/typescript/package-lock.json @@ -0,0 +1,44 @@ +{ + "name": "leanvm-sidecar-client", + "version": "0.1.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "leanvm-sidecar-client", + "version": "0.1.0", + "devDependencies": { + "@types/node": "^18.19.0", + "typescript": "^5.4.0" + } + }, + "node_modules/@types/node": { + "version": "18.19.130", + "resolved": "https://registry.npmjs.org/@types/node/-/node-18.19.130.tgz", + "integrity": "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg==", + "dev": true, + "dependencies": { + "undici-types": "~5.26.4" + } + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/undici-types": { + "version": "5.26.5", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.26.5.tgz", + "integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==", + "dev": true + } + } +} diff --git a/bins/leanvm-sidecar/clients/typescript/package.json b/bins/leanvm-sidecar/clients/typescript/package.json new file mode 100644 index 0000000000..825029f2d8 --- /dev/null +++ b/bins/leanvm-sidecar/clients/typescript/package.json @@ -0,0 +1,16 @@ +{ + "name": "leanvm-sidecar-client", + "version": "0.1.0", + "private": true, + "description": "Client of leanvm-sidecar: send a request, tryRecv its response", + "main": "dist/client.js", + "types": "dist/client.d.ts", + "scripts": { + "build": "./build.sh", + "test": "node --test dist/client.test.js" + }, + "devDependencies": { + "@types/node": "^18.19.0", + "typescript": "^5.4.0" + } +} diff --git a/bins/leanvm-sidecar/clients/typescript/tsconfig.json b/bins/leanvm-sidecar/clients/typescript/tsconfig.json new file mode 100644 index 0000000000..14784974c8 --- /dev/null +++ b/bins/leanvm-sidecar/clients/typescript/tsconfig.json @@ -0,0 +1,13 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "commonjs", + "strict": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "declaration": true, + "outDir": "dist", + "types": ["node"] + }, + "files": ["client.ts", "client.test.ts", "e2e.ts"] +} diff --git a/bins/leanvm-sidecar/e2e.sh b/bins/leanvm-sidecar/e2e.sh new file mode 100755 index 0000000000..0a9a8662f9 --- /dev/null +++ b/bins/leanvm-sidecar/e2e.sh @@ -0,0 +1,118 @@ +#!/usr/bin/env bash +# End-to-end run of leanvm-sidecar through one language's client: +# +# e2e.sh [--signatures N] [--batch-size N] +# [--aggregate-rate R] [--recurse-rate R] +# +# --signatures signatures per batch, 1 to 1500 (default 1440) +# --batch-size signatures per sub-batch (default: no split) +# --aggregate-rate log_inv_rate of the aggregations (default 2) +# --recurse-rate log_inv_rate of the recursion (default 1) +# +# Starts the server with prover threads, aggregates 16 batches of leanXMSS signatures +# one after the other, then recurses the 16 proofs into one and verifies it. Each step +# prints its request, its response and the time it took, as the client sees it. With --batch-size, +# each batch is instead built up in sub-batches, last one short: the first is aggregated, each +# later one extends the proof so far, which the server keeps, with its signatures. These run at log_inv_rate 1, except the +# last, which makes the batch's proof at --aggregate-rate. +# +# The signatures are testdata/signatures-24000.bin: 24000 signers, each signing one of 4 messages; +# examples/gen_signatures.rs regenerates the file if it is missing. Java uses the JDK on PATH, or +# else the eclipse-temurin:21-jdk container through docker. TypeScript needs node, npm and a C +# compiler (clients/typescript/build.sh). Nim uses the nim on PATH, or else the nimlang/nim:2.2.0 +# container through docker. +set -euo pipefail + +usage() { + sed -n '2,10p' "$0" >&2 + exit 2 +} +[[ $# -ge 2 ]] || usage +lang=$1 +threads=$2 +shift 2 +per_batch=1440 +sub_batch= +aggregate_rate=2 +recurse_rate=1 +while [[ $# -gt 0 ]]; do + [[ $# -ge 2 ]] || usage + case $1 in + --signatures) per_batch=$2 ;; + --batch-size | --batch_size) sub_batch=$2 ;; + --aggregate-rate) aggregate_rate=$2 ;; + --recurse-rate) recurse_rate=$2 ;; + *) usage ;; + esac + shift 2 +done +# The test file holds 16 batches of at most 1500. +[[ $per_batch =~ ^[0-9]+$ ]] && ((per_batch >= 1 && per_batch <= 1500)) || usage +sub_batch=${sub_batch:-$per_batch} +[[ $sub_batch =~ ^[0-9]+$ ]] && ((sub_batch >= 1)) || usage +[[ $lang == rust || $lang == go || $lang == java || $lang == ts || $lang == nim ]] || usage + +here=$(cd "$(dirname "$0")" && pwd) +root=$(cd "$here/../.." && pwd) +cd "$root" +work=$root/target/leanvm-sidecar +signatures=$here/testdata/signatures-24000.bin +channel=/dev/shm/leanvm-e2e-$$ +mkdir -p "$work" + +cargo build --release -p leanvm-sidecar -p leanvm_sidecar_client --examples --bins +if [[ ! -f $signatures ]]; then + echo "generating 24000 signatures into $signatures" + mkdir -p "$here/testdata" + target/release/examples/gen_signatures 24000 "$signatures.tmp" + mv "$signatures.tmp" "$signatures" +fi + +# Build the runner before the server starts, so the timings hold no compilation. +case $lang in +rust) runner=(target/release/examples/e2e) ;; +go) + (cd "$here/clients/go" && go build -o "$work/e2e-go" ./e2e) + runner=("$work/e2e-go") + ;; +java) + if command -v javac >/dev/null; then + javac -d "$work/java" "$here"/clients/java/leanvmsidecar/*.java + runner=(java -cp "$work/java" leanvmsidecar.E2e) + else + jdk=(docker run --rm -u "$(id -u):$(id -g)" -v /dev/shm:/dev/shm -v "$root:$root" -w "$root" eclipse-temurin:21-jdk) + "${jdk[@]}" javac -d "$work/java" "$here"/clients/java/leanvmsidecar/Client.java "$here"/clients/java/leanvmsidecar/E2e.java + runner=("${jdk[@]}" java -cp "$work/java" leanvmsidecar.E2e) + fi + ;; +ts) + "$here/clients/typescript/build.sh" + runner=(node "$here/clients/typescript/dist/e2e.js") + ;; +nim) + build=(nim c -d:release --hints:off --nimcache:"$work/nimcache" -o:"$work/e2e-nim" "$here/clients/nim/e2e.nim") + if command -v nim >/dev/null; then + "${build[@]}" + runner=("$work/e2e-nim") + else + # Built against the container's libc, so run there too. + box=(docker run --rm -u "$(id -u):$(id -g)" -e HOME=/tmp -v /dev/shm:/dev/shm -v "$root:$root" -w "$root" nimlang/nim:2.2.0) + "${box[@]}" "${build[@]}" + runner=("${box[@]}" "$work/e2e-nim") + fi + ;; +esac + +rm -f "$channel" +target/release/leanvm-sidecar --path "$channel" --threads "$threads" --arena-mib 256 & +server=$! +trap 'kill $server 2>/dev/null || true; wait $server 2>/dev/null || true; rm -f "$channel"' EXIT + +# The server creates the channel once the prover is warm. +until [[ -f $channel ]]; do + kill -0 $server 2>/dev/null || { echo "leanvm-sidecar exited" >&2; exit 1; } + sleep 0.1 +done + +echo "client $lang, $threads threads, $per_batch signatures per batch in sub-batches of $sub_batch, aggregate rate $aggregate_rate, recurse rate $recurse_rate" +"${runner[@]}" "$channel" "$signatures" "$aggregate_rate" "$recurse_rate" "$per_batch" "$sub_batch" diff --git a/bins/leanvm-sidecar/examples/gen_signatures.rs b/bins/leanvm-sidecar/examples/gen_signatures.rs new file mode 100644 index 0000000000..f9f8cedb67 --- /dev/null +++ b/bins/leanvm-sidecar/examples/gen_signatures.rs @@ -0,0 +1,55 @@ +//! Write the valid leanXMSS signatures `e2e.sh` reads: gen_signatures +//! +//! The file is `count` records of `pubkey | message | signature`, the triple of an `AGGREGATE` +//! payload. A full key is slow to generate, so the records share `KEYS` keys: record `i` is key +//! `i mod KEYS` signing, at leaf index `i / KEYS`, the message whose bytes spell that index. No two +//! records make the same claim, and no key signs twice at one leaf. The secret keys are derived +//! from the key's number and worth nothing. + +use lean_vm::lean_xmss::{self, LeafIndex, MESSAGE_LEN, PUB_KEY_SIZE, SECRET_KEY_LEN, SIG_SIZE}; +use std::io::Write; + +const KEYS: usize = 32; +const RECORD: usize = PUB_KEY_SIZE + MESSAGE_LEN + SIG_SIZE; + +fn main() { + let args: Vec = std::env::args().collect(); + let (count, path) = match args.as_slice() { + [_, count, path] => (count.parse::().expect("count"), path), + _ => { + eprintln!("usage: gen_signatures "); + std::process::exit(2); + } + }; + // One thread per key: its records are every `KEYS`-th, from its own number. + let per_key: Vec> = std::thread::scope(|scope| { + let workers: Vec<_> = (0..KEYS.min(count)) + .map(|key| { + scope.spawn(move || { + let mut seed = [0x5e; SECRET_KEY_LEN]; + seed[..8].copy_from_slice(&(key as u64).to_le_bytes()); + let (secret_key, pub_key) = lean_xmss::key_gen(&seed); + let record = |index: usize| { + let leaf_index = (index / KEYS) as LeafIndex; + let mut message = [0u8; MESSAGE_LEN]; + message[..4].copy_from_slice(&leaf_index.to_le_bytes()); + let signature = lean_xmss::sign(&secret_key, &message, leaf_index); + let mut record = [0u8; RECORD]; + let (head, tail) = record.split_at_mut(PUB_KEY_SIZE + MESSAGE_LEN); + head[..PUB_KEY_SIZE].copy_from_slice(&pub_key.to_bytes()); + head[PUB_KEY_SIZE..].copy_from_slice(&message); + tail.copy_from_slice(&signature.to_bytes()); + record + }; + (key..count).step_by(KEYS).map(record).collect() + }) + }) + .collect(); + workers.into_iter().map(|worker| worker.join().unwrap()).collect() + }); + let mut file = std::io::BufWriter::new(std::fs::File::create(path).expect("create")); + for index in 0..count { + file.write_all(&per_key[index % KEYS][index / KEYS]).expect("write"); + } + file.flush().expect("write"); +} diff --git a/bins/leanvm-sidecar/src/main.rs b/bins/leanvm-sidecar/src/main.rs new file mode 100644 index 0000000000..04634132e2 --- /dev/null +++ b/bins/leanvm-sidecar/src/main.rs @@ -0,0 +1,303 @@ +//! leanVM as a service over shared memory: leanXMSS aggregation, recursion and verification for one +//! client process, in any language. `PROTOCOL.md` specifies the channel file and the encodings. + +#[global_allocator] +static ALLOCATOR: bench::Jemalloc = bench::Jemalloc; + +use clap::Parser; +use shm::{Channel, Ring}; +use std::path::PathBuf; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::time::Duration; +use wire::{Request, Response, ST_OK, ST_RESP_TOO_SMALL}; + +mod serve; +mod shm; +mod warm; +mod wire; + +/// Wait between polls of an empty request ring. Far below the cost of any request. +const IDLE_POLL: Duration = Duration::from_micros(100); + +#[derive(Parser)] +struct Args { + /// The channel file, created if missing. Put it on tmpfs (/dev/shm). + #[arg(long)] + path: PathBuf, + + /// Prover performance-worker count (1 = sequential). Default: the pool's own, one per physical core. + #[arg(long, value_parser = clap::builder::RangedU64ValueParser::::new().range(1..))] + threads: Option, + + /// Arena size in MiB. One request's payload and response regions both have to fit. + #[arg(long, default_value_t = 64, value_parser = clap::builder::RangedU64ValueParser::::new().range(1..))] + arena_mib: usize, + + /// Slots in each ring; a power of two. + #[arg(long, default_value_t = 64)] + ring_cap: u32, + + /// Signatures in the discarded warm-up proofs run before serving; 0 skips them. Set it to the + /// largest batch expected: a larger proof than any before it still pays first-touch page faults. + #[arg(long, default_value_t = 1500)] + warmup_signatures: usize, + + /// WHIR inverse-rate logarithms to warm up, comma separated: the rates requests will ask for. + #[arg( + long, + value_delimiter = ',', + default_value = "1,2", + value_parser = clap::builder::RangedU64ValueParser::::new() + .range(lean_vm::MIN_LOG_INV_RATE as u64..=lean_vm::MAX_LOG_INV_RATE as u64) + )] + warmup_rates: Vec, + + /// Print a timing tree per request. Use RUST_LOG to adjust verbosity. + #[arg(long)] + tracing: bool, +} + +/// Serve requests one at a time until `stop`: `aggregate` must not run twice at once in a process. +fn run(chan: &Channel, stop: &AtomicBool) { + let mut kept = None; + while !stop.load(Ordering::Relaxed) { + let Some(msg) = chan.pop(Ring::Request) else { + std::thread::sleep(IDLE_POLL); + continue; + }; + let request = Request::decode(&msg); + let _span = tracing::info_span!("request", id = request.id, op = request.op).entered(); + + // Without a response region there is nowhere to put even an error's text. + let writable = chan.in_arena(request.resp_off, request.resp_cap); + let result = match chan.read(request.req_off, request.req_len) { + Some(payload) if writable => serve::handle(&request, &payload, &mut kept), + _ => Err(serve::Failure::bad_request("region outside the arena")), + }; + let (status, detail, resp_len, body) = match result { + Ok(body) if body.len() as u64 > request.resp_cap => (ST_RESP_TOO_SMALL, 0, body.len() as u64, Vec::new()), + Ok(body) => (ST_OK, 0, body.len() as u64, body), + Err(failure) => { + let mut text = failure.text.into_bytes(); + text.truncate(if writable { request.resp_cap as usize } else { 0 }); + (failure.status, failure.detail, text.len() as u64, text) + } + }; + chan.write(request.resp_off, &body); + let response = Response { + id: request.id, + status, + detail, + resp_len, + }; + chan.push(Ring::Response, &response.encode()); + } +} + +fn main() { + let args = Args::parse(); + if let Some(threads) = args.threads { + // SAFETY: no other thread exists yet. The pool reads this once, in `setup`. + unsafe { std::env::set_var("LEANVM_NUM_THREADS", threads.to_string()) }; + } + if args.tracing { + bench::init_tracing(); + } + lean_vm::setup(); + if args.warmup_signatures > 0 { + eprintln!("warming up..."); + let started = std::time::Instant::now(); + let signers = args + .threads + .or(std::thread::available_parallelism().ok().map(usize::from)) + .unwrap_or(1); + let _quiet = bench::suppress_tracing(); + warm::warm_up(args.warmup_signatures, &args.warmup_rates, signers); + eprintln!("warmed up in {:.1} s", started.elapsed().as_secs_f64()); + } + let chan = match Channel::create(&args.path, args.ring_cap, args.arena_mib << 20) { + Ok(chan) => chan, + Err(error) => { + eprintln!("{}: {error}", args.path.display()); + std::process::exit(1); + } + }; + eprintln!("serving {}", args.path.display()); + run(&chan, &AtomicBool::new(false)); +} + +#[cfg(test)] +mod tests { + use super::*; + use lean_vm::lean_xmss::{self, LeanXmssPublicKey, LeanXmssSignature, Message}; + use leanvm_sidecar_client::Client; + use wire::*; + + const RING_CAP: u32 = 4; + const ARENA_LEN: usize = 32 << 20; + const LOG_INV_RATE: u32 = 2; + const RESP_CAP: usize = 4 << 20; + + struct StopOnDrop<'a>(&'a AtomicBool); + + impl Drop for StopOnDrop<'_> { + fn drop(&mut self) { + self.0.store(true, Ordering::Relaxed); + } + } + + fn recv(client: &mut Client) -> leanvm_sidecar_client::Response { + loop { + match client.try_recv() { + Some(response) => return response, + None => std::thread::sleep(Duration::from_millis(1)), + } + } + } + + /// The response's status, detail and body. + fn call(client: &mut Client, op: u32, flags: u32, payload: &[u8]) -> (u32, u32, Vec) { + let id = client.send(op, flags, LOG_INV_RATE, payload, RESP_CAP).unwrap(); + let response = recv(client); + assert_eq!(response.id, id); + (response.status, response.detail, response.body) + } + + /// A `proof | claims` body. + fn proved(status: u32, body: &[u8]) -> (Vec, lean_vm::AggregateClaims) { + assert_eq!(status, ST_OK, "{}", String::from_utf8_lossy(body)); + let mut reader = Reader(body); + let proof = reader.proof().unwrap().to_vec(); + let claims = reader.claims().unwrap(); + reader.end().unwrap(); + (proof, claims) + } + + fn signatures(triples: &[(LeanXmssPublicKey, Message, LeanXmssSignature)]) -> Vec { + let mut out = (triples.len() as u32).to_le_bytes().to_vec(); + for (pub_key, message, signature) in triples { + out.extend(pub_key.to_bytes()); + out.extend(message); + out.extend(signature.to_bytes()); + } + out + } + + fn proof_with_claims(proof: &[u8], claims: &lean_vm::AggregateClaims) -> Vec { + let mut out = Vec::new(); + put_claims(&mut out, claims); + put_proof(&mut out, proof); + out + } + + fn client(path: &std::path::Path) { + let mut client = Client::open(path).unwrap(); + assert_eq!(client.sig_size(), lean_xmss::SIG_SIZE); + + let message = [7; lean_xmss::MESSAGE_LEN]; + let triples: Vec<_> = (0..3) + .map(|leaf_index| { + let (secret_key, pub_key) = lean_xmss::key_gen(&[leaf_index as u8; lean_xmss::SECRET_KEY_LEN]); + (pub_key, message, lean_xmss::sign(&secret_key, &message, leaf_index)) + }) + .collect(); + + // Two requests in flight: answered in order, each from its own arena block. + let first = client + .send(OP_AGGREGATE, 0, LOG_INV_RATE, &signatures(&triples[..2]), RESP_CAP) + .unwrap(); + let second = client + .send(OP_AGGREGATE, 0, LOG_INV_RATE, &signatures(&triples[2..]), RESP_CAP) + .unwrap(); + let (left, right) = (recv(&mut client), recv(&mut client)); + assert_eq!((left.id, right.id), (first, second)); + let (left, left_claims) = proved(left.status, &left.body); + let (right, right_claims) = proved(right.status, &right.body); + assert_eq!((left_claims.lean_xmss.len(), right_claims.lean_xmss.len()), (2, 1)); + + let verify = proof_with_claims(&left, &left_claims); + assert_eq!(call(&mut client, OP_VERIFY, 0, &verify).0, ST_OK); + let mut fewer = left_claims.clone(); + fewer.lean_xmss.pop(); + let (status, detail, _) = call(&mut client, OP_VERIFY, 0, &proof_with_claims(&left, &fewer)); + assert_eq!((status, detail), (ST_INVALID_PROOF, 0)); + + let mut recurse = 2u32.to_le_bytes().to_vec(); + recurse.extend(proof_with_claims(&left, &left_claims)); + recurse.extend(proof_with_claims(&right, &right_claims)); + let (status, _, body) = call(&mut client, OP_RECURSE, FLAG_VERIFY_CHILDREN, &recurse); + let (root, root_claims) = proved(status, &body); + assert_eq!(root_claims.lean_xmss.len(), 3); + + // The second child claims what the first proved: named by its index. + let mut swapped = 2u32.to_le_bytes().to_vec(); + swapped.extend(proof_with_claims(&left, &left_claims)); + swapped.extend(proof_with_claims(&right, &left_claims)); + let (status, detail, _) = call(&mut client, OP_RECURSE, FLAG_VERIFY_CHILDREN, &swapped); + assert_eq!((status, detail), (ST_INVALID_PROOF, 1)); + + // A proof and a raw signature in one request. + let mut extend = 1u32.to_le_bytes().to_vec(); + extend.extend(proof_with_claims(&left, &left_claims)); + extend.extend(signatures(&triples[2..])); + let (status, _, body) = call(&mut client, OP_EXTEND, FLAG_VERIFY_CHILDREN, &extend); + assert_eq!(proved(status, &body).1, root_claims); + + // The same through the proof the server keeps: no child in the payload. + let mut extend = 0u32.to_le_bytes().to_vec(); + extend.extend(signatures(&triples[2..])); + assert_eq!(call(&mut client, OP_EXTEND, FLAG_USE_KEPT, &extend).0, ST_BAD_REQUEST); + let (status, _, body) = call(&mut client, OP_AGGREGATE, FLAG_KEEP_PROOF, &signatures(&triples[..2])); + proved(status, &body); + let (status, _, body) = call(&mut client, OP_EXTEND, FLAG_USE_KEPT, &extend); + assert_eq!(proved(status, &body).1, root_claims); + // Used without FLAG_KEEP_PROOF: no longer kept. + assert_eq!(call(&mut client, OP_EXTEND, FLAG_USE_KEPT, &extend).0, ST_BAD_REQUEST); + + let mut retained = root_claims.clone(); + retained.lean_xmss.remove(1); + let mut narrow = proof_with_claims(&root, &root_claims); + put_claims(&mut narrow, &retained); + let (status, _, body) = call(&mut client, OP_VERIFY_NARROW, 0, &narrow); + let (narrowed, narrowed_claims) = proved(status, &body); + assert_eq!(narrowed_claims, retained); + let verify = proof_with_claims(&narrowed, &narrowed_claims); + assert_eq!(call(&mut client, OP_VERIFY, 0, &verify).0, ST_OK); + + // A response region too small for the proof: the size needed comes back, with no body. + client.send(OP_VERIFY_NARROW, 0, LOG_INV_RATE, &narrow, 8).unwrap(); + let response = recv(&mut client); + assert_eq!(response.status, ST_RESP_TOO_SMALL); + assert!(response.resp_len > 8 && response.body.is_empty()); + + assert_eq!( + call(&mut client, OP_VERIFY, 0, &verify[..verify.len() - 1]).0, + ST_BAD_REQUEST + ); + assert_eq!(call(&mut client, 99, 0, &[]).0, ST_BAD_REQUEST); + assert_eq!( + client.send(OP_VERIFY, 0, 0, &[], ARENA_LEN + 1), + Err(leanvm_sidecar_client::Full) + ); + } + + #[test] + fn serves_every_op() { + lean_vm::setup(); + let path = std::env::temp_dir().join(format!("leanvm-sidecar-test-{}", std::process::id())); + let chan = Channel::create(&path, RING_CAP, ARENA_LEN).unwrap(); + // Only the arena is addressable by a request. + assert!(chan.read(0, 8).is_none() && !chan.in_arena(u64::MAX, 2)); + let stop = AtomicBool::new(false); + std::thread::scope(|scope| { + let worker = scope.spawn(|| { + let _stop = StopOnDrop(&stop); + client(&path); + }); + run(&chan, &stop); + let outcome = worker.join(); + let _ = std::fs::remove_file(&path); + outcome.unwrap(); + }); + } +} diff --git a/bins/leanvm-sidecar/src/serve.rs b/bins/leanvm-sidecar/src/serve.rs new file mode 100644 index 0000000000..9040aae51f --- /dev/null +++ b/bins/leanvm-sidecar/src/serve.rs @@ -0,0 +1,139 @@ +//! One request, from its payload to its response body. + +use crate::wire::{ + FLAG_KEEP_PROOF, FLAG_USE_KEPT, FLAG_VERIFY_CHILDREN, OP_AGGREGATE, OP_EXTEND, OP_RECURSE, OP_VERIFY, + OP_VERIFY_NARROW, Reader, Request, ST_AGGREGATION_FAILED, ST_BAD_REQUEST, ST_INVALID_PROOF, proved, +}; +use lean_vm::lean_xmss::{LeanXmssPublicKey, LeanXmssSignature, Message}; +use lean_vm::{AggregateClaims, AggregateError, AggregateProof, MAX_RECURSIONS, OutputClaims, aggregate}; + +/// A proof with the claims it proves, which travel apart. +pub type Proved = (AggregateClaims, AggregateProof); + +pub struct Failure { + pub status: u32, + pub detail: u32, + /// For a human; written to the response region, truncated to its capacity. + pub text: String, +} + +impl Failure { + pub fn bad_request(text: &str) -> Self { + Self { + status: ST_BAD_REQUEST, + detail: 0, + text: text.into(), + } + } +} + +fn malformed() -> Failure { + Failure::bad_request("malformed payload") +} + +/// The `detail` of `ST_AGGREGATION_FAILED`. Part of the protocol: a variant keeps its number. +fn aggregation_code(error: &AggregateError) -> u32 { + match error { + AggregateError::InvalidChild => 1, + AggregateError::InvalidSignature => 4, + AggregateError::ProvingFailed => 11, + AggregateError::InvalidInput(_) => 12, + } +} + +/// Child `index` of the request, decoded and, if `verify`, natively verified against `claims`. +fn child(proof: &[u8], claims: AggregateClaims, index: usize, verify: bool) -> Result { + let invalid = |text: &str| Failure { + status: ST_INVALID_PROOF, + detail: index as u32, + text: text.into(), + }; + let proof = AggregateProof::from_bytes(proof).ok_or_else(|| invalid("the proof does not decode"))?; + if verify && !proof.verify(&claims) { + return Err(invalid("the proof does not verify against its claims")); + } + Ok((claims, proof)) +} + +fn prove( + children: &[Proved], + signatures: Vec<(LeanXmssPublicKey, Message, LeanXmssSignature)>, + declare: Option<&AggregateClaims>, + log_inv_rate: usize, +) -> Result { + let output = declare.map_or(OutputClaims::All, OutputClaims::Only); + aggregate(children, signatures, vec![], None, output, log_inv_rate).map_err(|error| Failure { + status: ST_AGGREGATION_FAILED, + detail: aggregation_code(&error), + text: error.to_string(), + }) +} + +/// The response body of `request`, whose payload is `payload`. `kept` is the proof held between +/// requests under `FLAG_KEEP_PROOF`; a request that fails leaves it as it was. +pub fn handle(request: &Request, payload: &[u8], kept: &mut Option) -> Result, Failure> { + let log_inv_rate = request.log_inv_rate as usize; + let mut reader = Reader(payload); + let proof = match request.op { + OP_AGGREGATE => { + let signatures = reader.signatures().ok_or_else(malformed)?; + reader.end().ok_or_else(malformed)?; + prove(&[], signatures, None, log_inv_rate)? + } + OP_RECURSE | OP_EXTEND => { + let use_kept = request.flags & FLAG_USE_KEPT != 0; + if use_kept && kept.is_none() { + return Err(Failure::bad_request("no kept proof")); + } + let count = reader.u32().ok_or_else(malformed)? as usize; + if !(1..=MAX_RECURSIONS).contains(&(count + usize::from(use_kept))) { + return Err(Failure::bad_request("child count outside 1..=16")); + } + let mut encoded = Vec::with_capacity(count); + for _ in 0..count { + let claims = reader.claims().ok_or_else(malformed)?; + encoded.push((claims, reader.proof().ok_or_else(malformed)?)); + } + let signatures = match request.op { + OP_EXTEND => reader.signatures().ok_or_else(malformed)?, + _ => vec![], + }; + reader.end().ok_or_else(malformed)?; + let verify = request.flags & FLAG_VERIFY_CHILDREN != 0; + let mut children = Vec::with_capacity(count); + for (index, (claims, proof)) in encoded.into_iter().enumerate() { + children.push(child(proof, claims, index, verify)?); + } + // Last, so a payload child keeps its index. + if use_kept { + children.extend(kept.take()); + } + let result = prove(&children, signatures, None, log_inv_rate); + if use_kept && result.is_err() { + *kept = children.pop(); + } + result? + } + OP_VERIFY => { + let claims = reader.claims().ok_or_else(malformed)?; + let proof = reader.proof().ok_or_else(malformed)?; + reader.end().ok_or_else(malformed)?; + child(proof, claims, 0, true)?; + return Ok(Vec::new()); + } + OP_VERIFY_NARROW => { + let claims = reader.claims().ok_or_else(malformed)?; + let proof = reader.proof().ok_or_else(malformed)?; + let retained = reader.claims().ok_or_else(malformed)?; + reader.end().ok_or_else(malformed)?; + let verified = child(proof, claims, 0, true)?; + prove(&[verified], vec![], Some(&retained), log_inv_rate)? + } + _ => return Err(Failure::bad_request("unknown op")), + }; + let body = proved(&proof.0, &proof.1); + if request.flags & FLAG_KEEP_PROOF != 0 { + *kept = Some(proof); + } + Ok(body) +} diff --git a/bins/leanvm-sidecar/src/shm.rs b/bins/leanvm-sidecar/src/shm.rs new file mode 100644 index 0000000000..406eb7d372 --- /dev/null +++ b/bins/leanvm-sidecar/src/shm.rs @@ -0,0 +1,236 @@ +//! The channel file: header, two SPSC rings, arena. All of the crate's `unsafe`. +//! +//! The peer is another process writing the same pages. Nothing read from the mapping is trusted: +//! ring counters only select a slot inside the ring, and arena regions are bounds-checked and +//! copied out before any decoding. + +use crate::wire::MSG_SIZE; +use lean_vm::lean_xmss::{MESSAGE_LEN, PUB_KEY_SIZE, SIG_SIZE}; +use std::fs::OpenOptions; +use std::io; +use std::os::fd::AsRawFd; +use std::path::Path; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::time::Duration; + +const MAGIC: u64 = u64::from_le_bytes(*b"LEANVMSH"); +const VERSION: u64 = 1; +const PAGE: usize = 4096; + +// Header: u64 words at these offsets. `H_EPOCH` is the only one written after creation. +const H_MAGIC: usize = 0; +const H_VERSION: usize = 8; +const H_EPOCH: usize = 16; +const H_RING_CAP: usize = 24; +const H_TOTAL: usize = 32; +const H_REQ_RING: usize = 40; +const H_RESP_RING: usize = 48; +const H_ARENA_OFF: usize = 56; +const H_ARENA_LEN: usize = 64; +const H_PUB_KEY_SIZE: usize = 72; +const H_MESSAGE_LEN: usize = 80; +const H_SIG_SIZE: usize = 88; + +// Ring: consumer and producer counters on separate cache lines, then the slots. +const R_HEAD: usize = 0; +const R_TAIL: usize = 64; +const R_SLOTS: usize = 128; + +/// Fault the whole file in at `mmap`: tmpfs allocates its pages then, not under the first requests. +#[cfg(target_os = "linux")] +const POPULATE: libc::c_int = libc::MAP_POPULATE; +#[cfg(not(target_os = "linux"))] +const POPULATE: libc::c_int = 0; + +/// Wait between polls of a full ring. +const FULL_POLL: Duration = Duration::from_micros(100); + +#[derive(Clone, Copy)] +pub enum Ring { + /// Client produces, server consumes. + Request, + /// Server produces, client consumes. + Response, +} + +pub struct Channel { + base: *mut u8, + total: usize, + ring_cap: u64, + req_ring: usize, + resp_ring: usize, + arena_off: usize, +} + +impl Channel { + /// Map the channel at `path`, creating it if needed, and start a new epoch. + /// + /// A file whose header already describes this geometry keeps its rings, so requests queued + /// across a restart are served. Any other file is reinitialized; a client still mapping the + /// old geometry has to reopen. + pub fn create(path: &Path, ring_cap: u32, arena_len: usize) -> io::Result { + if !ring_cap.is_power_of_two() { + return Err(io::Error::new( + io::ErrorKind::InvalidInput, + "ring capacity is not a power of two", + )); + } + let ring_bytes = (R_SLOTS + ring_cap as usize * MSG_SIZE).next_multiple_of(PAGE); + let (req_ring, resp_ring) = (PAGE, PAGE + ring_bytes); + let arena_off = resp_ring + ring_bytes; + let total = arena_off + arena_len; + + // A new channel is built under a staging name and renamed into place below, so a client + // that finds `path` finds its header written and its pages faulted in. + let mut staging = path.as_os_str().to_owned(); + staging.push(".init"); + let fresh = !path.exists(); + let open_at = if fresh { Path::new(&staging) } else { path }; + let file = OpenOptions::new() + .read(true) + .write(true) + .create(true) + .truncate(false) + .open(open_at)?; + if file.metadata()?.len() != total as u64 { + file.set_len(total as u64)?; + } + // SAFETY: a new shared mapping of `total` bytes of a file of that length, unmapped in `drop`. + let base = unsafe { + libc::mmap( + std::ptr::null_mut(), + total, + libc::PROT_READ | libc::PROT_WRITE, + libc::MAP_SHARED | POPULATE, + file.as_raw_fd(), + 0, + ) + }; + if base == libc::MAP_FAILED { + return Err(io::Error::last_os_error()); + } + let chan = Self { + base: base.cast(), + total, + ring_cap: u64::from(ring_cap), + req_ring, + resp_ring, + arena_off, + }; + + let header = [ + (H_MAGIC, MAGIC), + (H_VERSION, VERSION), + (H_RING_CAP, chan.ring_cap), + (H_TOTAL, total as u64), + (H_REQ_RING, req_ring as u64), + (H_RESP_RING, resp_ring as u64), + (H_ARENA_OFF, arena_off as u64), + (H_ARENA_LEN, arena_len as u64), + (H_PUB_KEY_SIZE, PUB_KEY_SIZE as u64), + (H_MESSAGE_LEN, MESSAGE_LEN as u64), + (H_SIG_SIZE, SIG_SIZE as u64), + ]; + let epoch = chan.word(H_EPOCH).load(Ordering::Relaxed); + if !header + .iter() + .all(|&(at, value)| chan.word(at).load(Ordering::Relaxed) == value) + { + // SAFETY: `[0, arena_off)` is inside the mapping. + unsafe { std::ptr::write_bytes(chan.base, 0, arena_off) }; + for (at, value) in header { + chan.word(at).store(value, Ordering::Relaxed); + } + } + // Survives reinitialization, so a client never sees an epoch repeat. + chan.word(H_EPOCH).store(epoch.wrapping_add(1), Ordering::Release); + if fresh { + std::fs::rename(&staging, path)?; + } + Ok(chan) + } + + fn word(&self, at: usize) -> &AtomicU64 { + assert!(at.is_multiple_of(8) && at + 8 <= self.total); + // SAFETY: in bounds and 8-aligned (the mapping is page-aligned). An `AtomicU64` is valid + // for any bit pattern and for concurrent writes by the peer. + unsafe { &*self.base.add(at).cast::() } + } + + fn ring(&self, ring: Ring) -> usize { + match ring { + Ring::Request => self.req_ring, + Ring::Response => self.resp_ring, + } + } + + fn slot(&self, ring: usize, index: u64) -> *mut u8 { + let slot = (index & (self.ring_cap - 1)) as usize; + // SAFETY: `slot < ring_cap`, and each ring spans `R_SLOTS + ring_cap * MSG_SIZE` bytes of the mapping. + unsafe { self.base.add(ring + R_SLOTS + slot * MSG_SIZE) } + } + + /// The oldest unconsumed message of `ring`. Only its one consumer may call this. + pub fn pop(&self, ring: Ring) -> Option<[u8; MSG_SIZE]> { + let ring = self.ring(ring); + let head = self.word(ring + R_HEAD).load(Ordering::Relaxed); + if self.word(ring + R_TAIL).load(Ordering::Acquire) == head { + return None; + } + let mut msg = [0; MSG_SIZE]; + // SAFETY: the slot is `MSG_SIZE` bytes inside the mapping. The producer published it with + // its Release store of the tail; a producer that breaks the protocol only garbles the bytes. + unsafe { std::ptr::copy_nonoverlapping(self.slot(ring, head), msg.as_mut_ptr(), MSG_SIZE) }; + self.word(ring + R_HEAD).store(head.wrapping_add(1), Ordering::Release); + Some(msg) + } + + /// Append `msg` to `ring`, waiting while it is full. Only its one producer may call this. + pub fn push(&self, ring: Ring, msg: &[u8; MSG_SIZE]) { + let ring = self.ring(ring); + let tail = self.word(ring + R_TAIL).load(Ordering::Relaxed); + while tail.wrapping_sub(self.word(ring + R_HEAD).load(Ordering::Acquire)) >= self.ring_cap { + std::thread::sleep(FULL_POLL); + } + // SAFETY: as in `pop`; the consumer does not read this slot before the tail moves past it. + unsafe { std::ptr::copy_nonoverlapping(msg.as_ptr(), self.slot(ring, tail), MSG_SIZE) }; + self.word(ring + R_TAIL).store(tail.wrapping_add(1), Ordering::Release); + } + + /// `[off, off + len)` as indices into the mapping, if it lies inside the arena. `off` is from the file's start. + fn region(&self, off: u64, len: u64) -> Option<(usize, usize)> { + let end = off.checked_add(len)?; + (off >= self.arena_off as u64 && end <= self.total as u64).then_some((off as usize, len as usize)) + } + + pub fn in_arena(&self, off: u64, len: u64) -> bool { + self.region(off, len).is_some() + } + + /// A private copy of an arena region. The peer can still write to the arena, so nothing is decoded in place. + pub fn read(&self, off: u64, len: u64) -> Option> { + let (off, len) = self.region(off, len)?; + let mut out = Vec::with_capacity(len); + // SAFETY: the source is inside the mapping and `out` has capacity `len`. A concurrent write + // by the peer yields arbitrary bytes, which the decoders treat as any other input. + unsafe { + std::ptr::copy_nonoverlapping(self.base.add(off), out.as_mut_ptr(), len); + out.set_len(len); + } + Some(out) + } + + /// Copy `bytes` into the arena at `off`. Panics on a region the caller did not check with [`Self::in_arena`]. + pub fn write(&self, off: u64, bytes: &[u8]) { + let (off, len) = self.region(off, bytes.len() as u64).expect("region outside the arena"); + // SAFETY: the destination is inside the mapping. + unsafe { std::ptr::copy_nonoverlapping(bytes.as_ptr(), self.base.add(off), len) }; + } +} + +impl Drop for Channel { + fn drop(&mut self) { + // SAFETY: the mapping `create` made; no reference into it outlives `self`. + unsafe { libc::munmap(self.base.cast(), self.total) }; + } +} diff --git a/bins/leanvm-sidecar/src/warm.rs b/bins/leanvm-sidecar/src/warm.rs new file mode 100644 index 0000000000..b0e1c93895 --- /dev/null +++ b/bins/leanvm-sidecar/src/warm.rs @@ -0,0 +1,40 @@ +//! The untimed pass the benchmarks run before measuring, done once before the first request. +//! +//! `lean_vm::setup` builds the guest and spawns the pool. What is left to the first proof of a +//! shape is first-touch page faults on the gigabytes it allocates, which jemalloc then keeps +//! mapped, and the tables the prover and verifier cache per size and rate. One discarded +//! aggregation, verification and full-width recursion per rate pays for both. + +use lean_vm::lean_xmss::{self, LeafIndex, MESSAGE_LEN, SECRET_KEY_LEN}; +use lean_vm::{MAX_RECURSIONS, OutputClaims, aggregate}; + +/// Prove, verify and recurse over `signatures` fresh signatures at each of `rates`, discarding the +/// results. `signers` threads sign; they are gone before the first proof. +pub fn warm_up(signatures: usize, rates: &[usize], signers: usize) { + let (secret_key, pub_key) = lean_xmss::key_gen(&[0x5e; SECRET_KEY_LEN]); + let secret_key = &secret_key; + // One key, a distinct message per leaf index: `signatures` distinct claims. + let raw: Vec<_> = std::thread::scope(|scope| { + let workers: Vec<_> = (0..signers) + .map(|worker| { + scope.spawn(move || { + let sign = |index: usize| { + let mut message = [0u8; MESSAGE_LEN]; + message[..8].copy_from_slice(&(index as u64).to_le_bytes()); + let signature = lean_xmss::sign(secret_key, &message, index as LeafIndex); + (pub_key, message, signature) + }; + (worker..signatures).step_by(signers).map(sign).collect::>() + }) + }) + .collect(); + workers.into_iter().flat_map(|worker| worker.join().unwrap()).collect() + }); + for &rate in rates { + let leaf = aggregate(&[], raw.clone(), vec![], None, OutputClaims::All, rate).expect("warm-up aggregation"); + assert!(leaf.1.verify(&leaf.0), "warm-up verification"); + // The same child in every slot: the recursion's full width, whatever the claims' union. + let children = vec![leaf; MAX_RECURSIONS]; + aggregate(&children, vec![], vec![], None, OutputClaims::All, rate).expect("warm-up recursion"); + } +} diff --git a/bins/leanvm-sidecar/src/wire.rs b/bins/leanvm-sidecar/src/wire.rs new file mode 100644 index 0000000000..bd8f306952 --- /dev/null +++ b/bins/leanvm-sidecar/src/wire.rs @@ -0,0 +1,161 @@ +//! Message and payload encodings: little-endian, fixed offsets. `PROTOCOL.md` is the specification. + +use lean_vm::lean_xmss::{LeanXmssPublicKey, LeanXmssSignature, MESSAGE_LEN, Message, PUB_KEY_SIZE, SIG_SIZE}; +use lean_vm::{AggregateClaims, AggregateProof}; + +/// Size of a ring slot, request or response. +pub const MSG_SIZE: usize = 64; + +pub const OP_AGGREGATE: u32 = 1; +pub const OP_RECURSE: u32 = 2; +pub const OP_VERIFY: u32 = 3; +pub const OP_VERIFY_NARROW: u32 = 4; +pub const OP_EXTEND: u32 = 5; + +/// `OP_RECURSE`, `OP_EXTEND`: verify every child natively before proving. +pub const FLAG_VERIFY_CHILDREN: u32 = 1; +/// A proving op: the server keeps the proof it returns, in place of any it held. +pub const FLAG_KEEP_PROOF: u32 = 2; +/// `OP_RECURSE`, `OP_EXTEND`: the kept proof is one more child, and is no longer kept. +pub const FLAG_USE_KEPT: u32 = 4; + +pub const ST_OK: u32 = 0; +/// A region outside the arena, an unknown op or a payload that does not decode. +pub const ST_BAD_REQUEST: u32 = 1; +/// The response does not fit `resp_cap`; `resp_len` is the size needed. +pub const ST_RESP_TOO_SMALL: u32 = 2; +/// A proof does not decode or verify against its claims; `detail` is its index in the request. +pub const ST_INVALID_PROOF: u32 = 3; +/// `aggregate` refused or failed; `detail` is the `AggregateError` variant. +pub const ST_AGGREGATION_FAILED: u32 = 4; + +const CLAIM_SIZE: usize = PUB_KEY_SIZE + MESSAGE_LEN; +const TRIPLE_SIZE: usize = CLAIM_SIZE + SIG_SIZE; + +pub struct Request { + pub id: u64, + pub op: u32, + pub flags: u32, + pub req_off: u64, + pub req_len: u64, + pub resp_off: u64, + pub resp_cap: u64, + pub log_inv_rate: u32, +} + +fn u32_at(bytes: &[u8; MSG_SIZE], at: usize) -> u32 { + u32::from_le_bytes(bytes[at..at + 4].try_into().unwrap()) +} + +fn u64_at(bytes: &[u8; MSG_SIZE], at: usize) -> u64 { + u64::from_le_bytes(bytes[at..at + 8].try_into().unwrap()) +} + +impl Request { + pub fn decode(bytes: &[u8; MSG_SIZE]) -> Self { + Self { + id: u64_at(bytes, 0), + op: u32_at(bytes, 8), + flags: u32_at(bytes, 12), + req_off: u64_at(bytes, 16), + req_len: u64_at(bytes, 24), + resp_off: u64_at(bytes, 32), + resp_cap: u64_at(bytes, 40), + log_inv_rate: u32_at(bytes, 48), + } + } +} + +pub struct Response { + pub id: u64, + pub status: u32, + pub detail: u32, + pub resp_len: u64, +} + +impl Response { + pub fn encode(&self) -> [u8; MSG_SIZE] { + let mut out = [0; MSG_SIZE]; + out[0..8].copy_from_slice(&self.id.to_le_bytes()); + out[8..12].copy_from_slice(&self.status.to_le_bytes()); + out[12..16].copy_from_slice(&self.detail.to_le_bytes()); + out[16..24].copy_from_slice(&self.resp_len.to_le_bytes()); + out + } +} + +/// A payload being decoded. Every count is checked against the bytes left before anything is allocated for it. +pub struct Reader<'a>(pub &'a [u8]); + +impl<'a> Reader<'a> { + fn bytes(&mut self, len: usize) -> Option<&'a [u8]> { + let (head, rest) = self.0.split_at_checked(len)?; + self.0 = rest; + Some(head) + } + + pub fn u32(&mut self) -> Option { + Some(u32::from_le_bytes(self.bytes(4)?.try_into().unwrap())) + } + + /// `n u32 | n x (pubkey | message)` + pub fn claims(&mut self) -> Option { + let count = self.u32()? as usize; + let raw = self.bytes(count.checked_mul(CLAIM_SIZE)?)?; + let lean_xmss = raw.as_chunks::().0.iter().map(claim).collect(); + Some(AggregateClaims { + lean_xmss, + ..AggregateClaims::default() + }) + } + + /// `len u64 | bytes` + pub fn proof(&mut self) -> Option<&'a [u8]> { + let len = u64::from_le_bytes(self.bytes(8)?.try_into().unwrap()); + self.bytes(usize::try_from(len).ok()?) + } + + /// `n u32 | n x (pubkey | message | signature)` + pub fn signatures(&mut self) -> Option> { + let count = self.u32()? as usize; + let raw = self.bytes(count.checked_mul(TRIPLE_SIZE)?)?; + let triples = raw.as_chunks::().0.iter().map(|triple| { + let (head, signature) = triple.split_first_chunk::().unwrap(); + let (pub_key, message) = claim(head); + let signature = LeanXmssSignature::from_bytes(signature.try_into().unwrap()); + (pub_key, message, signature) + }); + Some(triples.collect()) + } + + /// `Some` if the payload was consumed whole. + pub fn end(self) -> Option<()> { + self.0.is_empty().then_some(()) + } +} + +fn claim(bytes: &[u8; CLAIM_SIZE]) -> (LeanXmssPublicKey, Message) { + let (pub_key, message) = bytes.split_first_chunk::().unwrap(); + (LeanXmssPublicKey::from_bytes(pub_key), message.try_into().unwrap()) +} + +pub fn put_claims(out: &mut Vec, claims: &AggregateClaims) { + out.extend((claims.lean_xmss.len() as u32).to_le_bytes()); + for (pub_key, message) in &claims.lean_xmss { + out.extend(pub_key.to_bytes()); + out.extend(message); + } +} + +pub fn put_proof(out: &mut Vec, proof: &[u8]) { + out.extend((proof.len() as u64).to_le_bytes()); + out.extend(proof); +} + +/// `proof | claims`: the response to every op that proves. +pub fn proved(claims: &AggregateClaims, proof: &AggregateProof) -> Vec { + let mut out = Vec::new(); + put_proof(&mut out, &proof.to_bytes()); + put_claims(&mut out, claims); + out +} diff --git a/bins/leanvm-sidecar/testdata/signatures-24000.bin b/bins/leanvm-sidecar/testdata/signatures-24000.bin new file mode 100644 index 0000000000..15f2546604 Binary files /dev/null and b/bins/leanvm-sidecar/testdata/signatures-24000.bin differ diff --git a/crates/leanvm_sidecar_client/Cargo.toml b/crates/leanvm_sidecar_client/Cargo.toml new file mode 100644 index 0000000000..f60080f666 --- /dev/null +++ b/crates/leanvm_sidecar_client/Cargo.toml @@ -0,0 +1,11 @@ +[package] +name = "leanvm_sidecar_client" +version.workspace = true +edition.workspace = true +publish = false + +[lints] +workspace = true + +[dependencies] +libc.workspace = true diff --git a/crates/leanvm_sidecar_client/examples/e2e.rs b/crates/leanvm_sidecar_client/examples/e2e.rs new file mode 100644 index 0000000000..a873245b59 --- /dev/null +++ b/crates/leanvm_sidecar_client/examples/e2e.rs @@ -0,0 +1,173 @@ +//! The run `bins/leanvm-sidecar/e2e.sh` drives: +//! e2e +//! +//! Sixteen `AGGREGATE` requests of `signatures-per-batch` signatures each, one after the other, then +//! one `RECURSE` over the sixteen proofs and one `VERIFY` of the result. With `sub-batch` below +//! `signatures-per-batch`, each batch is instead built up in parts of `sub-batch` signatures: an +//! `AGGREGATE`, then one `EXTEND` per part of the proof so far, which the server keeps. Parts run at +//! rate 1, except the last at `aggregate-rate`. The file is records of `pubkey | message | signature`. + +use leanvm_sidecar_client::{ + Client, FLAG_KEEP_PROOF, FLAG_USE_KEPT, OP_AGGREGATE, OP_EXTEND, OP_RECURSE, OP_VERIFY, Response, ST_OK, +}; +use std::time::{Duration, Instant}; + +const BATCHES: usize = 16; +const RESP_CAP: usize = 16 << 20; + +/// Send one request and wait for its response. +fn call(client: &mut Client, op: u32, flags: u32, rate: u32, payload: &[u8]) -> (Response, Duration) { + let started = Instant::now(); + let id = client + .send(op, flags, rate, payload, RESP_CAP) + .expect("no room in the channel"); + let response = loop { + match client.try_recv() { + Some(response) => break response, + None => std::thread::sleep(Duration::from_micros(100)), + } + }; + assert_eq!(response.id, id); + (response, started.elapsed()) +} + +fn check(response: &Response) { + if response.status != ST_OK { + let text = String::from_utf8_lossy(&response.body); + println!( + " FAILED: status {} detail {}: {text}", + response.status, response.detail + ); + std::process::exit(1); + } +} + +/// A `proof | claims` body as `(proof, claims)`, each with its length prefix. +fn split(response: &Response) -> (&[u8], &[u8]) { + check(response); + let proof_len = u64::from_le_bytes(response.body[..8].try_into().unwrap()) as usize; + response.body.split_at(8 + proof_len) +} + +fn claim_count(claims: &[u8]) -> u32 { + u32::from_le_bytes(claims[..4].try_into().unwrap()) +} + +/// One proving request: prints the step as `what`, with the time since `since` if given, and returns +/// the response's `(proof, claims)`. +fn step( + client: &mut Client, + op: u32, + flags: u32, + rate: u32, + payload: &[u8], + what: &str, + since: Option, +) -> (Vec, Vec) { + let (response, elapsed) = call(client, op, flags, rate, payload); + let batch = since + .map(|since| format!(", batch total {:.3} s", since.elapsed().as_secs_f64())) + .unwrap_or_default(); + let (proof, claims) = split(&response); + println!( + "{what}, {} bytes, rate {rate} -> proof {} bytes, {} claims, {:.3} s{batch}", + payload.len(), + proof.len() - 8, + claim_count(claims), + elapsed.as_secs_f64(), + ); + (proof.to_vec(), claims.to_vec()) +} + +/// `AGGREGATE` over `records`, each `record` bytes; under `FLAG_USE_KEPT`, `EXTEND` of the proof the +/// server kept with them. +fn aggregate( + client: &mut Client, + flags: u32, + records: &[u8], + record: usize, + rate: u32, + label: &str, + since: Option, +) -> (Vec, Vec) { + let count = records.len() / record; + let mut payload = Vec::new(); + let (op, what) = if flags & FLAG_USE_KEPT != 0 { + // No child in the payload. + payload.extend(0u32.to_le_bytes()); + (OP_EXTEND, format!("{label}: kept proof + {count} signatures")) + } else { + (OP_AGGREGATE, format!("{label}: {count} signatures")) + }; + payload.extend((count as u32).to_le_bytes()); + payload.extend(records); + step(client, op, flags, rate, &payload, &what, since) +} + +fn main() { + let args: Vec = std::env::args().collect(); + let [ + _, + channel, + signatures, + aggregate_rate, + recurse_rate, + per_batch, + sub_batch, + ] = args.as_slice() + else { + eprintln!( + "usage: e2e " + ); + std::process::exit(2); + }; + let aggregate_rate: u32 = aggregate_rate.parse().expect("aggregate rate"); + let recurse_rate: u32 = recurse_rate.parse().expect("recurse rate"); + let per_batch: usize = per_batch.parse().expect("signatures per batch"); + let sub_batch: usize = sub_batch.parse().expect("sub-batch"); + let mut client = Client::open(channel.as_ref()).expect("open channel"); + let record = client.pub_key_size() + client.message_len() + client.sig_size(); + let signatures = std::fs::read(signatures).expect("read signatures"); + assert!( + signatures.len() >= BATCHES * per_batch * record, + "signature file too short" + ); + + let total = Instant::now(); + let parts = per_batch.div_ceil(sub_batch); + let mut recurse = (BATCHES as u32).to_le_bytes().to_vec(); + for (batch, records) in signatures.chunks_exact(per_batch * record).take(BATCHES).enumerate() { + let mut proved = (Vec::new(), Vec::new()); + let started = Instant::now(); + for (part, records) in records.chunks(sub_batch * record).enumerate() { + let (first, last) = (part == 0, part + 1 == parts); + let name = if first { "aggregate" } else { "extend " }; + let mut label = format!("{name} {:2}/{BATCHES}", batch + 1); + if parts > 1 { + label += &format!(" part {:2}/{parts}", part + 1); + } + // Every part but the first extends the proof the server kept; every part but the last + // has it keep the new one. The last part's proof is the batch's. + let flags = if first { 0 } else { FLAG_USE_KEPT } | if last { 0 } else { FLAG_KEEP_PROOF }; + let rate = if last { aggregate_rate } else { 1 }; + let since = (parts > 1 && last).then_some(started); + proved = aggregate(&mut client, flags, records, record, rate, &label, since); + } + let (proof, claims) = proved; + recurse.extend(claims); + recurse.extend(proof); + } + let what = format!("recurse {BATCHES} -> 1: {BATCHES} proofs"); + let (proof, claims) = step(&mut client, OP_RECURSE, 0, recurse_rate, &recurse, &what, None); + let verify = [claims.as_slice(), &proof].concat(); + let (verdict, elapsed) = call(&mut client, OP_VERIFY, 0, 0, &verify); + check(&verdict); + println!( + "verify: proof {} bytes, {} claims, {} bytes -> valid, {:.3} s", + proof.len() - 8, + claim_count(&claims), + verify.len(), + elapsed.as_secs_f64(), + ); + println!("total: {:.3} s", total.elapsed().as_secs_f64()); +} diff --git a/crates/leanvm_sidecar_client/src/lib.rs b/crates/leanvm_sidecar_client/src/lib.rs new file mode 100644 index 0000000000..209c7e4314 --- /dev/null +++ b/crates/leanvm_sidecar_client/src/lib.rs @@ -0,0 +1,357 @@ +//! Client of the `leanvm-sidecar` service: [`Client::send`] a request, [`Client::try_recv`] its response. +//! +//! Links nothing of the prover. Payloads and response bodies are raw bytes in the encodings of +//! `bins/leanvm-sidecar/PROTOCOL.md`; the Go and Java clients beside that file mirror this one. +//! +//! One `Client` per channel. Open it while no request of an earlier client is outstanding: the +//! server would write that request's response into arena space this client hands out again. + +use std::collections::VecDeque; +use std::fs::OpenOptions; +use std::io; +use std::os::fd::AsRawFd; +use std::path::Path; +use std::sync::atomic::{AtomicU64, Ordering}; + +pub const OP_AGGREGATE: u32 = 1; +pub const OP_RECURSE: u32 = 2; +pub const OP_VERIFY: u32 = 3; +pub const OP_VERIFY_NARROW: u32 = 4; +pub const OP_EXTEND: u32 = 5; + +/// `OP_RECURSE`, `OP_EXTEND`: verify every child natively before proving. +pub const FLAG_VERIFY_CHILDREN: u32 = 1; +/// A proving op: the server keeps the proof it returns, in place of any it held. +pub const FLAG_KEEP_PROOF: u32 = 2; +/// `OP_RECURSE`, `OP_EXTEND`: the kept proof is one more child, and is no longer kept. +pub const FLAG_USE_KEPT: u32 = 4; + +pub const ST_OK: u32 = 0; +pub const ST_BAD_REQUEST: u32 = 1; +pub const ST_RESP_TOO_SMALL: u32 = 2; +pub const ST_INVALID_PROOF: u32 = 3; +pub const ST_AGGREGATION_FAILED: u32 = 4; + +const MAGIC: u64 = u64::from_le_bytes(*b"LEANVMSH"); +const VERSION: u64 = 1; +const MSG_SIZE: usize = 64; + +const H_MAGIC: usize = 0; +const H_VERSION: usize = 8; +const H_EPOCH: usize = 16; +const H_RING_CAP: usize = 24; +const H_TOTAL: usize = 32; +const H_REQ_RING: usize = 40; +const H_RESP_RING: usize = 48; +const H_ARENA_OFF: usize = 56; +const H_ARENA_LEN: usize = 64; +const H_PUB_KEY_SIZE: usize = 72; +const H_MESSAGE_LEN: usize = 80; +const H_SIG_SIZE: usize = 88; +const HEADER_SIZE: usize = 96; + +/// Map every page at `mmap`, so no request takes this process's first-touch faults on the arena. +#[cfg(target_os = "linux")] +const POPULATE: libc::c_int = libc::MAP_POPULATE; +#[cfg(not(target_os = "linux"))] +const POPULATE: libc::c_int = 0; + +const R_HEAD: usize = 0; +const R_TAIL: usize = 64; +const R_SLOTS: usize = 128; + +/// The request ring or the arena has no room. Receive a response and retry. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Full; + +impl std::fmt::Display for Full { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(f, "no room in the request ring or the arena") + } +} + +impl std::error::Error for Full {} + +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Response { + /// What [`Client::send`] returned for the request. + pub id: u64, + pub status: u32, + pub detail: u32, + /// The body's length, or under [`ST_RESP_TOO_SMALL`] the response capacity the request needed. + pub resp_len: u64, + /// The op's response under [`ST_OK`], UTF-8 text for a human on a failure, empty under [`ST_RESP_TOO_SMALL`]. + pub body: Vec, +} + +/// A request's arena block: its payload, then its response region, both offsets from the arena's start. +struct Block { + id: u64, + off: usize, + payload_len: usize, + resp_cap: usize, +} + +impl Block { + fn end(&self) -> usize { + self.off + self.payload_len + self.resp_cap + } +} + +/// Where a block of `len` bytes goes, from the arena's start, given the blocks still held. +fn place(live: &VecDeque, arena_len: usize, len: usize) -> Option { + let (Some(first), Some(last)) = (live.front(), live.back()) else { + return (len <= arena_len).then_some(0); + }; + let end = last.end(); + if last.off < first.off { + // Wrapped: the gap up to the oldest block. + (len <= first.off - end).then_some(end) + } else if len <= arena_len - end { + Some(end) + } else { + // Wrap into the space before the oldest block. `first.off > 0` keeps `last.off < first.off` meaning wrapped. + (first.off > 0 && len <= first.off).then_some(0) + } +} + +pub struct Client { + base: *mut u8, + total: usize, + ring_cap: u64, + req_ring: usize, + resp_ring: usize, + arena_off: usize, + arena_len: usize, + next_id: u64, + /// Blocks of requests not yet answered, oldest first. The server answers in order, so the arena + /// is a circular buffer of them: allocated at the back, freed at the front. + live: VecDeque, +} + +// SAFETY: the mapping is owned by the `Client` and not tied to a thread. +unsafe impl Send for Client {} + +impl Client { + /// Map the channel the server created at `path`. Responses left by an earlier client are discarded. + pub fn open(path: &Path) -> io::Result { + let invalid = |what: &'static str| io::Error::new(io::ErrorKind::InvalidData, what); + let file = OpenOptions::new().read(true).write(true).open(path)?; + let total = usize::try_from(file.metadata()?.len()).map_err(|_| invalid("channel too large"))?; + if total < HEADER_SIZE { + return Err(invalid("not a leanvm-sidecar channel")); + } + // SAFETY: a new shared mapping of the whole file, unmapped in `drop`. + let base = unsafe { + libc::mmap( + std::ptr::null_mut(), + total, + libc::PROT_READ | libc::PROT_WRITE, + libc::MAP_SHARED | POPULATE, + file.as_raw_fd(), + 0, + ) + }; + if base == libc::MAP_FAILED { + return Err(io::Error::last_os_error()); + } + let mut client = Self { + base: base.cast(), + total, + ring_cap: 0, + req_ring: 0, + resp_ring: 0, + arena_off: 0, + arena_len: 0, + next_id: 0, + live: VecDeque::new(), + }; + let field = |at: usize| client.word(at).load(Ordering::Relaxed); + if field(H_MAGIC) != MAGIC || field(H_VERSION) != VERSION { + return Err(invalid("not a leanvm-sidecar channel of this version")); + } + let (ring_cap, req_ring, resp_ring) = (field(H_RING_CAP), field(H_REQ_RING), field(H_RESP_RING)); + let (arena_off, arena_len) = (field(H_ARENA_OFF), field(H_ARENA_LEN)); + // Every later access is in bounds given these: the rings sit below the arena, the arena inside the file. + let ring_bytes = ring_cap + .checked_mul(MSG_SIZE as u64) + .and_then(|slots| slots.checked_add(R_SLOTS as u64)); + let ring_fits = |ring: u64| { + let end = ring_bytes.and_then(|bytes| ring.checked_add(bytes)); + ring.is_multiple_of(8) && end.is_some_and(|end| end <= arena_off) + }; + if !ring_cap.is_power_of_two() + || field(H_TOTAL) != total as u64 + || !ring_fits(req_ring) + || !ring_fits(resp_ring) + || arena_off.checked_add(arena_len) != Some(total as u64) + { + return Err(invalid("inconsistent channel header")); + } + client.ring_cap = ring_cap; + client.req_ring = req_ring as usize; + client.resp_ring = resp_ring as usize; + client.arena_off = arena_off as usize; + client.arena_len = arena_len as usize; + let stale = client.word(client.resp_ring + R_TAIL).load(Ordering::Acquire); + client.word(client.resp_ring + R_HEAD).store(stale, Ordering::Release); + Ok(client) + } + + fn word(&self, at: usize) -> &AtomicU64 { + assert!(at.is_multiple_of(8) && at + 8 <= self.total); + // SAFETY: in bounds and 8-aligned (the mapping is page-aligned). An `AtomicU64` is valid + // for any bit pattern and for concurrent writes by the server. + unsafe { &*self.base.add(at).cast::() } + } + + fn slot(&self, ring: usize, index: u64) -> *mut u8 { + let slot = (index & (self.ring_cap - 1)) as usize; + // SAFETY: `slot < ring_cap`, and `open` checked that the ring's slots are inside the mapping. + unsafe { self.base.add(ring + R_SLOTS + slot * MSG_SIZE) } + } + + /// Incremented each time the server starts. A request in flight across a restart gets no response. + pub fn epoch(&self) -> u64 { + self.word(H_EPOCH).load(Ordering::Acquire) + } + + pub fn pub_key_size(&self) -> usize { + self.word(H_PUB_KEY_SIZE).load(Ordering::Relaxed) as usize + } + + pub fn message_len(&self) -> usize { + self.word(H_MESSAGE_LEN).load(Ordering::Relaxed) as usize + } + + pub fn sig_size(&self) -> usize { + self.word(H_SIG_SIZE).load(Ordering::Relaxed) as usize + } + + /// Queue a request and return its id. `resp_cap` bytes of arena are reserved for the response: + /// a proof that does not fit is discarded by the server ([`ST_RESP_TOO_SMALL`]). + pub fn send( + &mut self, + op: u32, + flags: u32, + log_inv_rate: u32, + payload: &[u8], + resp_cap: usize, + ) -> Result { + let tail = self.word(self.req_ring + R_TAIL).load(Ordering::Relaxed); + if tail.wrapping_sub(self.word(self.req_ring + R_HEAD).load(Ordering::Acquire)) >= self.ring_cap { + return Err(Full); + } + let len = payload.len().checked_add(resp_cap).ok_or(Full)?; + let off = place(&self.live, self.arena_len, len).ok_or(Full)?; + let req_off = self.arena_off + off; + // SAFETY: `place` returned a block inside the arena that no live request holds. + unsafe { std::ptr::copy_nonoverlapping(payload.as_ptr(), self.base.add(req_off), payload.len()) }; + + self.next_id += 1; + let id = self.next_id; + let mut msg = [0u8; MSG_SIZE]; + msg[0..8].copy_from_slice(&id.to_le_bytes()); + msg[8..12].copy_from_slice(&op.to_le_bytes()); + msg[12..16].copy_from_slice(&flags.to_le_bytes()); + msg[16..24].copy_from_slice(&(req_off as u64).to_le_bytes()); + msg[24..32].copy_from_slice(&(payload.len() as u64).to_le_bytes()); + msg[32..40].copy_from_slice(&((req_off + payload.len()) as u64).to_le_bytes()); + msg[40..48].copy_from_slice(&(resp_cap as u64).to_le_bytes()); + msg[48..52].copy_from_slice(&log_inv_rate.to_le_bytes()); + // SAFETY: the slot is inside the mapping, and the server does not read it before the tail moves past it. + unsafe { std::ptr::copy_nonoverlapping(msg.as_ptr(), self.slot(self.req_ring, tail), MSG_SIZE) }; + self.word(self.req_ring + R_TAIL) + .store(tail.wrapping_add(1), Ordering::Release); + self.live.push_back(Block { + id, + off, + payload_len: payload.len(), + resp_cap, + }); + Ok(id) + } + + /// The next response, if the server has produced one. Frees the request's arena block, and + /// those of earlier requests that a server restart left unanswered. + pub fn try_recv(&mut self) -> Option { + let head = self.word(self.resp_ring + R_HEAD).load(Ordering::Relaxed); + if self.word(self.resp_ring + R_TAIL).load(Ordering::Acquire) == head { + return None; + } + let mut msg = [0u8; MSG_SIZE]; + // SAFETY: the slot is inside the mapping; the server published it with its store of the tail. + unsafe { std::ptr::copy_nonoverlapping(self.slot(self.resp_ring, head), msg.as_mut_ptr(), MSG_SIZE) }; + self.word(self.resp_ring + R_HEAD) + .store(head.wrapping_add(1), Ordering::Release); + + let mut response = Response { + id: u64::from_le_bytes(msg[0..8].try_into().unwrap()), + status: u32::from_le_bytes(msg[8..12].try_into().unwrap()), + detail: u32::from_le_bytes(msg[12..16].try_into().unwrap()), + resp_len: u64::from_le_bytes(msg[16..24].try_into().unwrap()), + body: Vec::new(), + }; + while self.live.pop_front_if(|block| block.id < response.id).is_some() {} + // The body is read only for the request this answers, and only from inside its own block. + if let Some(block) = self.live.pop_front_if(|block| block.id == response.id) + && response.status != ST_RESP_TOO_SMALL + && response.resp_len <= block.resp_cap as u64 + { + let len = response.resp_len as usize; + let resp_off = self.arena_off + block.off + block.payload_len; + response.body.reserve_exact(len); + // SAFETY: `len <= resp_cap`, inside the block; `body` has capacity `len`. + unsafe { + std::ptr::copy_nonoverlapping(self.base.add(resp_off), response.body.as_mut_ptr(), len); + response.body.set_len(len); + } + } + Some(response) + } +} + +impl Drop for Client { + fn drop(&mut self) { + // SAFETY: the mapping `open` made; no reference into it outlives `self`. + unsafe { libc::munmap(self.base.cast(), self.total) }; + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// Random sends and in-order frees: a placed block is inside the arena and overlaps no live one. + #[test] + fn blocks_never_overlap() { + const ARENA_LEN: usize = 100; + let mut live = VecDeque::new(); + let mut state = 1u64; + let mut placed = 0; + for id in 0..10_000 { + state = state + .wrapping_mul(6364136223846793005) + .wrapping_add(1442695040888963407); + let len = (state >> 33) as usize % 40; + match place(&live, ARENA_LEN, len) { + Some(off) => { + assert!(off + len <= ARENA_LEN); + assert!(live.iter().all(|b: &Block| off + len <= b.off || b.end() <= off)); + live.push_back(Block { + id, + off, + payload_len: len, + resp_cap: 0, + }); + placed += 1; + } + None => assert!(live.pop_front().is_some()), + } + if state >> 63 == 1 { + live.pop_front(); + } + } + assert!(placed > 1000); + } +}