Skip to content

feat(wsdb)!: aztec-wsdb takes its genesis only from Init; readable differential test against wsdb-ref - #25862

Open
charlielye wants to merge 4 commits into
cl/napi-ffi-libraryfrom
cl/wsdb-init
Open

charlielye wants to merge 4 commits into
cl/napi-ffi-libraryfrom
cl/wsdb-init

Conversation

@charlielye

@charlielye charlielye commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #25861.

What changes

aztec-wsdb takes its genesis only from Init. Before this PR, aztec-wsdb took its genesis as command-line options and answered Init with an error. The differential test opened it through a side constructor, wsdb_labs_ffi_open, which parsed a msgpack run command line. That function, its FFI entry and its CLI11 parsing all shipped in the aztec-wsdb binary, though only the test used them.

  • The genesis options are removed, together with their JSON and hex parsing:

    • --tree-heights
    • --tree-prefill
    • --initial-header-generator-point
    • --prefilled-public-data
    • --prefilled-nullifiers
    • --genesis-timestamp

    aztec-wsdb msgpack run now takes only --data-dir, --map-sizes, --threads and the ring sizes.

  • aztec-wsdb opens no stores until it receives Init, and refuses every other command until then with "send Init first". Init can be sent only once; a second one is an error.

  • WsdbService::call(span) runs a request in-process.

  • aztec-wsdb no longer generates an FFI entry. wsdb_ffi_service.{hpp,cpp} are deleted, and the codegen call drops --ffi --ffi-name wsdb_labs.

labs patch 0003. IpcWorldState.spawn starts aztec-wsdb with only the resource options, then sends Init with the genesis it used to put on the command line:

  • tree heights, prefill and header generator point from @aztec-foundation/protocol-genesis;
  • prefilled public data, nullifiers and timestamp from the node's GenesisData. A production node's is DEFAULT_GENESIS_DATA, built from the same package.

If Init fails, the process is destroyed and the error is rethrown.

The differential test, wsdb_ref_diff.test.cpp, is rewritten. It is no longer a seeded random workload sized by WSDB_DIFF_* environment variables. A fixture holds two WsdbApi clients: ref, over wsdb-ref's FFI entry, and labs, over a WsdbService in a temporary directory. Both get the same Init. Named scenarios then send both clients the same requests through two helpers:

  • same(...): both succeed and give equal answers. State references are compared in any order, and a full status is compared without its LMDB statistics.
  • both_fail(...): both refuse the request.

The scenarios cover:

  • genesis
  • appended leaves, with commit and rollback
  • nullifier and public-data insertions, including duplicates
  • blocks built on a fork and synced the way a node does
  • a SyncBlock with a wrong state or archive root
  • checkpoints
  • forks
  • unwinding, finalizing and removing history

wsdb_init.test.cpp (new) checks that commands sent before Init are refused, and that a second Init is refused.

Breaking

  • aztec-wsdb rejects the genesis options. A client must send Init before anything else. The only client that started aztec-wsdb itself was labs, which this PR's patch 0003 updates.

Build changes

  • aztec-wsdb's codegen is --server --client only (no --ffi).

Testing

  • wsdb_tests built with clang 20: 176/176 pass, including the 9 differential scenarios and the Init tests.
  • labs make labs-yarn-project against this tree, then world-state's tests: 96/96 in src/native (spawning aztec-wsdb and checking the genesis roots) and 93/93 in the rest.
  • labs-patches/bootstrap.sh check passes.

🤖 Generated with Claude Code

https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb

@charlielye charlielye changed the title feat(wsdb): aztec-wsdb takes its genesis from Init; readable differential test against wsdb-ref feat(wsdb)!: aztec-wsdb takes its genesis only from Init; readable differential test against wsdb-ref Nov 14, 2026
@charlielye
charlielye added this pull request to stack #25863 November 14, 2026 19:04
charlielye and others added 4 commits November 14, 2026 19:41
…y and wsdb_labs_ffi_open

aztec-wsdb answered Init with an error, so the differential test opened it in-process through a side
constructor, wsdb_labs_ffi_open, that parsed the `msgpack run` command line. That function, the FFI
entry behind it and its CLI11 parsing shipped in the aztec-wsdb binary, though only the test used them.

- Started without genesis options, aztec-wsdb opens no stores and refuses every command until Init,
  which opens them at its genesis. Init is sent once: a second one, or one to a service started with
  the genesis options, is an error. The data directory, map sizes and threads stay options.
- The genesis options still work, so labs' startup is unchanged. Genesis options without
  --tree-heights are an error.
- WsdbService::call runs a request in-process. The differential test runs a WsdbService per seed
  through it and sends it and wsdb-ref the same Init.
- aztec-wsdb no longer generates an FFI entry; wsdb_ffi_service.{hpp,cpp} are gone.
- wsdb_init.test.cpp: Init gives the same world state as the options, commands before Init are
  refused, and Init is refused the second time and by a service started with a genesis.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
The test was a seeded random workload sized by WSDB_DIFF_* environment variables. It now holds two WsdbApi
clients, one over wsdb-ref's FFI entry and one over an in-process WsdbService, sends both the same Init,
and runs named scenarios through `same(...)` (both answer, and equally) and `both_fail(...)` (both refuse):
genesis, appended leaves with commit and rollback, nullifier and public-data insertions including
duplicates, blocks built on a fork and synced as a node does, a SyncBlock with a wrong state or archive
root, checkpoints, forks, and unwind, finalize and history removal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
…nesis command-line options

aztec-wsdb no longer accepts --tree-heights, --tree-prefill, --initial-header-generator-point,
--prefilled-public-data, --prefilled-nullifiers or --genesis-timestamp, nor parses their JSON and hex. It
opens its stores when its client sends Init; the data directory, map sizes, threads and ring sizes stay
options.

labs patch 0003: IpcWorldState.spawn starts aztec-wsdb with those resource options and sends Init with the
genesis it used to pass on the command line (tree heights, prefill and header generator point from
@aztec-foundation/protocol-genesis; prefilled public data, nullifiers and timestamp from the node's
GenesisData). A failed Init destroys the process.

wsdb_init.test.cpp drops the tests of the options.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
…ode's genesis alone

getWsdbInit took the data directory and map sizes only to reach the tree heights through getWsdbOptions. The
protocol's tree heights and prefill are now module constants both use, so getWsdbInit(genesis) needs nothing
else and is exported for services that are not spawned, such as an in-process wsdb-ref.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant