Skip to content

feat: kv-store over IPC; aztec-kvdb binary; LMDBStore NAPI scaffold [PR 4]#23698

Open
charlielye wants to merge 95 commits into
cl/ipc-5-avm-cutoverfrom
cl/ipc-6-kvdb
Open

feat: kv-store over IPC; aztec-kvdb binary; LMDBStore NAPI scaffold [PR 4]#23698
charlielye wants to merge 95 commits into
cl/ipc-5-avm-cutoverfrom
cl/ipc-6-kvdb

Conversation

@charlielye

Copy link
Copy Markdown
Contributor

Summary

Stacked on PR 3b (#23196). Adds an out-of-process `aztec-kvdb` binary that owns LMDB and serves it over UDS / MPSC SHM with the same `TypedMessage

` wire format `yarn-project/native/MsgpackChannel` already speaks. AztecLMDBStoreV2 will be migrated from `NativeLMDBStore` (NAPI) to `KvdbBackend` (IPC) in a follow-up commit on this same PR.

This first commit is inert: the binary builds and is shipped, but nothing in yarn-project uses it yet.

Why

After PR 3b lands, only one load-bearing NAPI consumer remains: the LMDB store used by archiver, p2p, pxe, slasher, and validator-ha-signer. Moving it out of NAPI removes the last embedding of a C++ subsystem in the Node.js process. The NAPI module is reduced to a thin SHM transport stub (`MsgpackClient`/`MsgpackClientAsync`, ~400 LOC) — pure IPC plumbing, no domain logic.

SHM is the production transport (~1–10 µs round-trip via futex doorbell); UDS is the dev/test fallback. This also activates the SHM code-path that has been dead in production since PR 1.

What's in this PR (so far)

C++:

  • `barretenberg/cpp/src/barretenberg/kvdb/` — `aztec-kvdb` binary. Wraps `lmdblib::LMDBStore`, runs a `bb::messaging::MessageDispatcher`, exposes the same op set as the NAPI LMDBStoreWrapper (open_database, get, has, start_cursor, advance_cursor, advance_cursor_count, close_cursor, batch, stats, copy_store).
  • `barretenberg/cpp/src/barretenberg/kvdb/kvdb_messages.hpp` — wire schema. Moved from `nodejs_module/lmdb_store/lmdb_store_message.hpp`; namespace renamed `bb::nodejs::lmdb_store` → `bb::kvdb`, enum `LMDBStoreMessageType` → `KvdbMessageType`. The NAPI wrapper temporarily includes the new location until it's deleted.

TypeScript (bb.js):

  • `barretenberg/ts/src/aztec-kvdb/index.ts` — `KvdbBackend`: spawns the binary, talks UDS or SHM, implements `IMsgpackBackendAsync`. Mirrors `WsdbBackend`.
  • `findKvdbBinary` in `bb_backends/node/platform.ts`.
  • `copy_native.sh` ships `aztec-kvdb` alongside the other binaries.

What's still ahead in this PR

  • Swap `new MsgpackChannel(new NativeLMDBStore(...))` → `new MsgpackChannel(new KvdbBackend(...))` inside `yarn-project/kv-store/src/lmdb-v2/store.ts`.
  • Update spawn sites (archiver, p2p, pxe, slasher, validator-ha-signer factories + `aztec-node/server.ts`) to construct/accept a `KvdbBackend`.
  • Default `useShm: true` in production callers; verify the SHM transport end-to-end.
  • Delete `barretenberg/cpp/src/barretenberg/nodejs_module/lmdb_store/`, the `LMDBStore` export in `init_module.cpp`, the `NativeLMDBStore` export in `@aztec/native`, and the thin `yarn-project/kv-store/src/lmdb-v2/native/` wrapper.

Stack

Test plan

  • `aztec-kvdb msgpack run --input /tmp/foo.sock --data-dir /tmp/lmdb-test` accepts UDS connections
  • `@aztec/kv-store` `lmdb-v2` tests pass against KvdbBackend over UDS and SHM
  • Bench hot `get`/cursor-page latency vs NAPI baseline (target ~5× over SHM)
  • e2e `e2e_block_building` / `e2e_archiver_` / `e2e_p2p/`
  • Sandbox boots and serves transactions

Recreated from original PR #23238. Same realignment caveats as PR above.

charlielye added 21 commits May 29, 2026 15:39
Two new top-level packages that no consumer in this PR uses yet — they
exist as a self-contained foundation that PR2..5 will adopt for the bb,
wsdb, bb.js, and barretenberg-rs migrations.

/ipc-codegen — multi-language codegen for msgpack-framed IPC services.
- src/{cpp,rust,typescript,zig}_codegen.ts emit per-language clients
  and servers from a schema JSON (committed by each service).
- examples/{cpp,rust,ts,zig}/echo are live cross-language wire-compat
  tests; the matrix verifies every (server-lang, client-lang) pair.
- examples/echo-schema/golden/ pins the wire format byte-for-byte.

/ipc-runtime — UDS + MPSC-SHM transport library plus per-language
bindings. C++ is the canonical implementation:
- cpp/ipc_runtime/{ipc_server,ipc_client,signal_handlers,serve_helper,
  named_union,schema,c_abi,...}.{hpp,cpp}
- cpp/ipc_runtime/shm/ (MPSC/SPSC ring-buffer SHM)
- rust/src/lib.rs binds the C ABI as the `ipc-runtime` crate
- ts/src/{uds_client,uds_server,shm_client,types,index}.ts is the
  `@aztec/ipc-runtime` Node package
- zig/src/{main,smoke}.zig binds the C ABI for Zig clients/servers

Strictly additive in this PR. The legacy `barretenberg/cpp/src/barretenberg/ipc/`
library (under namespace `bb::ipc`) stays in place — consumers continue
to use it. Follow-up PRs migrate one consumer at a time to `ipc::`
(top-level namespace, from ipc-runtime) and the legacy subdir is deleted
once nothing references it.

Build wiring:
- Makefile: new `ipc-codegen` / `ipc-codegen-tests` and `ipc-runtime` /
  `ipc-runtime-tests` targets; `ipc-codegen-tests` joins the `fast` set.
- barretenberg/cpp/src/CMakeLists.txt: `add_subdirectory` for
  ipc-runtime/cpp/ alongside the legacy barretenberg/ipc/.
- barretenberg/.gitignore: `**/generated/` (codegen output dirs).

Verification:
- `cd ipc-codegen && ./bootstrap.sh && ./bootstrap.sh test` — 18-test
  matrix (golden corpus × 2 + 4×4 cross-language). Green.
- `cd ipc-runtime && ./bootstrap.sh && ./cpp/build/ipc_runtime_tests` —
  2/2 SHM transport tests. Green.
- `cd ipc-runtime/rust && cargo build` — clean.
- `cd ipc-runtime/ts && yarn install && yarn build` — clean.
- `cd ipc-runtime/zig && zig build` — clean.
@charlielye charlielye force-pushed the cl/ipc-5-avm-cutover branch from 0df283e to 42d8d4f Compare May 30, 2026 16:57
@charlielye charlielye force-pushed the cl/ipc-5-avm-cutover branch 18 times, most recently from 7bd2e42 to 89c8c8c Compare June 18, 2026 16:00
@charlielye charlielye force-pushed the cl/ipc-5-avm-cutover branch 12 times, most recently from 184a3fc to b16faa7 Compare June 21, 2026 20:34
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