feat: kv-store over IPC; aztec-kvdb binary; LMDBStore NAPI scaffold [PR 4]#23698
Open
charlielye wants to merge 95 commits into
Open
feat: kv-store over IPC; aztec-kvdb binary; LMDBStore NAPI scaffold [PR 4]#23698charlielye wants to merge 95 commits into
charlielye wants to merge 95 commits into
Conversation
charlielye
requested review from
IlyasRidhuan,
MirandaWood and
jeanmon
as code owners
charlielye
force-pushed
the
cl/ipc-5-avm-cutover
branch
from
1c8d4f9 to
a4e2e70
Compare
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
force-pushed
the
cl/ipc-5-avm-cutover
branch
from
a4e2e70 to
0df283e
Compare
charlielye
force-pushed
the
cl/ipc-5-avm-cutover
branch
from
0df283e to
42d8d4f
Compare
The third describe block in custom_bc.test.ts created a PublicTxSimulationTester (owns AvmSimulatorPool + CdbIpcServer) per test but only closed worldStateService in afterEach, leaking the AVM pool and CDB server each iteration. Jest could not exit after the suite completed and was killed at the 600s CI timeout. Add the missing tester.close() to match the other two describe blocks.
…erEach Same teardown leak as in simulator/.../apps_tests/custom_bc.test.ts: the third describe block's afterEach was missing await tester.close(), leaving the AvmProvingTester (which spawns an AvmSimulatorPool + CdbIpcServer) alive. Jest could not exit after the suite completed and was killed at the 600s CI timeout.
Mirrors the aztec-wsdb / aztec-cdb pattern: a standalone C++ binary that owns an lmdblib::LMDBStore and serves it over UDS (and, in a follow-up step, MPSC SHM) using the same NamedUnion msgpack protocol the rest of the stack uses. Commands are translated 1:1 from nodejs_module/lmdb_store/lmdb_store_message.hpp (open_database, get, has, start_cursor, advance_cursor, advance_cursor_count, close_cursor, batch, stats, copy_store) plus a shutdown sentinel. The handler bodies are lifted from nodejs_module/lmdb_store/lmdb_store_wrapper.cpp with NAPI removed — they call into the same lmdblib::LMDBStore primitives. Inert in this commit: nothing in yarn-project uses it yet. Following PRs in this stack wire it through @aztec/kv-store's lmdb-v2 backend and then delete the NAPI LMDBStore. Part of PR 4 — kv-store IPC migration.
Replaces the NamedUnion-style protocol I'd initially scaffolded with the
existing TypedMessage<P>{msgType,header,value} layout that MsgpackChannel
already speaks. AztecLMDBStoreV2 can swap from NativeLMDBStore to
KvdbBackend without changing the message schema.
C++:
- Move nodejs_module/lmdb_store/lmdb_store_message.hpp → kvdb/kvdb_messages.hpp,
rename namespace bb::nodejs::lmdb_store → bb::kvdb and enum LMDBStoreMessageType
→ KvdbMessageType. The NAPI LMDBStoreWrapper still compiles via the new
header location with `using namespace bb::kvdb`; it gets deleted later.
- Rewrite kvdb_ipc_server.cpp to use bb::messaging::MessageDispatcher; lift the
same handler logic (open_database, get, has, cursors, batch, stats, copy_store)
from lmdb_store_wrapper.cpp into the server, sans NAPI threading.
- Drop the NamedUnion command structs I'd started with.
TS:
- barretenberg/ts/src/aztec-kvdb/index.ts: KvdbBackend that spawns aztec-kvdb,
connects over UDS or SHM, implements IMsgpackBackendAsync. Same shape as
WsdbBackend but with the smaller kvdb CLI (data-dir, map-size, max-readers).
- No codegen for kvdb — the schema lives in yarn-project/kv-store/src/lmdb-v2/
message.ts already, and the wire format matches the existing NAPI client.
- findKvdbBinary in bb_backends/node/platform.ts; copy_native.sh ships aztec-kvdb.
Part of PR 4 — kv-store IPC migration. Inert until consumers are migrated in
the next commit.
Replaces `new MsgpackChannel(new NativeLMDBStore(...))` with `new MsgpackChannel(new KvdbBackend(...))`. KvdbBackend spawns aztec-kvdb, connects over SHM by default (UDS via KVDB_USE_UDS=1 for repro tests), and speaks the same TypedMessage<P> wire format the NAPI wrapper used — so nothing else in lmdb-v2 (read_transaction, write_transaction, map, set, multi_map, array, singleton, the cursor pool) changes. AztecLMDBStoreV2.new() resolves the binary via findKvdbBinary() and awaits KvdbBackend.waitUntilReady() before opening databases. close() now also destroys the backend so the child process terminates cleanly. Bonus: MsgpackChannel now accepts Uint8Array responses in addition to Buffer/ArrayBuffer. KvdbBackend.call returns Uint8Array (matches the IMsgpackBackendAsync contract used by WsdbBackend/AvmBackend); the new branch is a zero-copy view into the same backing ArrayBuffer. Tests: 91/91 lmdb-v2 suite passes against the IPC backend over SHM. NativeLMDBStore is still imported by kv-store today; that goes away in the NAPI cleanup commit at the end of this PR.
…nsport only
With AztecLMDBStoreV2 moved to aztec-kvdb in the previous commit, nothing in
the codebase imports LMDBStore from NAPI. Strip it:
C++:
- Delete barretenberg/cpp/src/barretenberg/nodejs_module/lmdb_store/ (the
LMDBStoreWrapper and its message-processor handlers).
- init_module.cpp no longer exports LMDBStore; only MsgpackClient and
MsgpackClientAsync remain (pure SHM transport wrappers).
- nodejs_module/CMakeLists.txt drops the world_state link — the transport
library doesn't need WorldState/LMDB symbols anymore.
TypeScript:
- yarn-project/native/src/native_module.ts deleted. The bb.js dependency on
@aztec/native is removed from package.json.
- yarn-project/native/src/index.ts now just re-exports MessageReceiver /
RoundtripDuration / MsgpackChannel.
Result: nodejs_module.node shrinks from ~1.2 MB to ~158 KB — IPC plumbing
only, no domain logic. The kv-store hot path runs out-of-process via
aztec-kvdb over SHM (with UDS as a dev/test fallback). NAPI's job in this
codebase is reduced to the MPSC SHM transport that aztec-{wsdb,avm,kvdb}
all use; everything else is gone.
Verifies: 91/91 @aztec/kv-store lmdb-v2 tests still pass.
…e layout
barretenberg/ipc/ipc_{client,server}.hpp → ipc_runtime/ipc_{client,server}.hpp.
target_link_libraries: ipc → ipc_runtime. bb::messaging::MessageDispatcher
(used for the kvdb wire dispatch) still exists in the first stack at
barretenberg/messaging/dispatcher.hpp.
charlielye
force-pushed
the
cl/ipc-5-avm-cutover
branch
7 times, most recently
from
ce6510f to
00868aa
Compare
charlielye
force-pushed
the
cl/ipc-5-avm-cutover
branch
7 times, most recently
from
242ae5a to
a5fddf3
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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++:
TypeScript (bb.js):
What's still ahead in this PR
Stack
Test plan
Recreated from original PR #23238. Same realignment caveats as PR above.