Skip to content

refactor: extract wsdb/lmdblib/kvdb into native-packages, decoupled from barretenberg - #24392

Open
charlielye wants to merge 1 commit into
nextfrom
cl/wsdb-decouple
Open

refactor: extract wsdb/lmdblib/kvdb into native-packages, decoupled from barretenberg#24392
charlielye wants to merge 1 commit into
nextfrom
cl/wsdb-decouple

Conversation

@charlielye

@charlielye charlielye commented Jun 30, 2026

Copy link
Copy Markdown
Contributor

What

Two changes that belong together, in one commit:

  1. Extract the world-state DB server + persistent merkle (wsdb), the lmdb C++ wrapper (lmdblib), and the kv-store NAPI (kvdb) out of barretenberg into top-level native-packages/ siblings, leaving barretenberg free of DB code.
  2. Decouple the extracted wsdb from barretenberg's C++ headers, so its world-state/merkle/storage core, its test suite, and the aztec-wsdb binary compile with zero barretenberg headers on the include path — barretenberg is only linked (libbarretenberg.a), purely to satisfy a small flat poseidon2 c_bind.

Together this lets wsdb/lmdblib/kvdb and barretenberg eventually live in independently-owned repos / CI without sharing a compiler, stdlib, or build flags — the only things wsdb and barretenberg share are the IPC schema (already the case) and a couple of extern "C" hash calls.

Extraction (barretenberg → native-packages/)

  • New native-packages/ siblings: wsdb (world-state DB server + persistent content-addressed merkle), lmdblib (the C++ lmdb wrapper), kvdb (the kv-store nodejs_module.node NAPI addon that owns the LMDBStore wrapper).
  • Barretenberg's merkle_tree headers are split: barretenberg keeps only the response/types the AVM's LowLevelMerkleDBInterface returns and its hints serialize; the full async tree engine (content-addressed trees + world_state) and its response/tree_meta/types move into wsdb. world_state, lmdblib, wsdb, and the merkle-tree benchmarks are deleted from barretenberg/cpp.
  • Build: the standalone aztec-wsdb binary and the kvdb .node build against prebuilt barretenberg; lmdblib/kvdb are fully barretenberg-free. lmdblib switches to upstream msgpack + FetchContent. The lmdblib/wsdb C++ tests are wired into the CI test engine.

Decoupling wsdb from barretenberg headers

  • Hash c_bind (barretenberg/crypto/poseidon2/poseidon2_capi.cpp, in libbarretenberg.a): flat bb_poseidon2_hash + bb_poseidon2_hash_pair_with_separator. Field elements cross as 32 canonical bytes — no bb field type, stdlib, or build-flag agreement required. This is the only computation wsdb can't own (it must match what the AVM proves and what is committed on L1), so it is single-sourced in barretenberg.
  • azteclabs::wsdb::FieldElement: a 32-byte field value with no arithmetic (wsdb only stores/orders/compares/serialises field values and feeds them to the hash). A using fr = FieldElement; alias inside namespace azteclabs::wsdb lets the forked merkle headers compile unchanged.
  • Forked the shared merkle headers (types, hash_path, merkle_tree_id, tree_meta, indexed_leaf, response, memory_tree, signal) into wsdb under namespace azteclabs::wsdb::merkle_tree, swapping SERIALIZATION_FIELDSMSGPACK_DEFINE_MAP (msgpack-c directly). The msgpack values are byte-identical to bb::fr, so on-disk lmdb data and the IPC wire are unchanged.
  • Owns bb-free common utils: log, assert, thread_pool, bitop, random, a minimal uint256_t (for the reference/test nullifier abs-diff search), aztec_constants, and vendored cli11.

Proof

  • aztec-wsdb + wsdb_tests build with BB_SRC removed from the include dirs; 0 bb #includes remain in the decoupled set. (Also verified locally from the combined commit: lmdblib + aztec-wsdb compile and link.)
  • 150 decoupled wsdb_tests pass.
  • A bb-linked parity target (-DWSDB_BUILD_BB_TESTS=ON) proves FieldElement + the c_bind are byte-identical to bb::fr and bb's Poseidon2HashPolicy (hash, msgpack, ordering, domain separators) — 6 tests pass.
  • The decoupled core compiles under libstdc++ (≠ bb's libc++), demonstrating header independence. The shipping build deliberately stays on bb's toolchain (libc++/-march).

Notes / follow-ups

  • lmdb key byte order changed from uint256 little-endian to canonical big-endian (FrKeyType = fr, comparator value_cmp<fr>). msgpack values are unchanged. This is fine for a fresh service (re-sync) but is not backward-compatible with databases written before this change.
  • The MemoryMerkleDB equivalence test (wsdb/memory_merkle_db.test.cpp) is left in-tree but not wired into the default build; reviving it (it links both wsdb's forked merkle headers and barretenberg's real ones in one TU) is a follow-up. The bb-linked parity target covers the consensus-critical byte-identity guarantee in the meantime.

@charlielye

Copy link
Copy Markdown
Contributor Author

!ci

@charlielye
charlielye force-pushed the cl/native-packages-wsdb branch from b9d3ca7 to cb30112 Compare July 1, 2026 16:52
@charlielye

Copy link
Copy Markdown
Contributor Author

!ci

1 similar comment
@charlielye

Copy link
Copy Markdown
Contributor Author

!ci

@charlielye

Copy link
Copy Markdown
Contributor Author

!ci

@charlielye

Copy link
Copy Markdown
Contributor Author

!ci

@charlielye

Copy link
Copy Markdown
Contributor Author

!ci

@charlielye

Copy link
Copy Markdown
Contributor Author

!ci

@charlielye
charlielye force-pushed the cl/native-packages-wsdb branch from cb30112 to 9685f11 Compare July 2, 2026 13:53
@charlielye

Copy link
Copy Markdown
Contributor Author

!ci

@charlielye
charlielye force-pushed the cl/native-packages-wsdb branch from 9685f11 to 74d5b73 Compare July 2, 2026 15:33
@charlielye

Copy link
Copy Markdown
Contributor Author

!ci

@charlielye
charlielye force-pushed the cl/native-packages-wsdb branch from 74d5b73 to 2218d58 Compare July 2, 2026 15:45
@charlielye charlielye changed the title feat: decouple wsdb from barretenberg C++ headers refactor: extract wsdb/lmdblib/kvdb into native-packages, decoupled from barretenberg Jul 4, 2026
@charlielye
charlielye force-pushed the cl/ipc-6-memory-merkle-db branch from 029257b to 62ffd7a Compare July 7, 2026 16:42
@charlielye
charlielye force-pushed the cl/ipc-6-memory-merkle-db branch from 62ffd7a to 8443e1a Compare July 17, 2026 15:25
@charlielye
charlielye force-pushed the cl/wsdb-decouple branch 2 times, most recently from 8b2ae61 to 6113a7c Compare July 20, 2026 15:53
@charlielye
charlielye force-pushed the cl/ipc-6-memory-merkle-db branch from 8443e1a to 3b9cd59 Compare July 23, 2026 10:02
@charlielye
charlielye force-pushed the cl/ipc-6-memory-merkle-db branch from 3b9cd59 to ec066c6 Compare July 23, 2026 11:26
@charlielye
charlielye force-pushed the cl/ipc-6-memory-merkle-db branch from 638fa33 to 6b50835 Compare July 31, 2026 17:30
@charlielye
charlielye force-pushed the cl/wsdb-decouple branch 3 times, most recently from a8a2b77 to ee71811 Compare August 3, 2026 10:38
@charlielye
charlielye force-pushed the cl/ipc-6-memory-merkle-db branch from c601182 to bebe8ca Compare August 4, 2026 12:54
@charlielye
charlielye force-pushed the cl/wsdb-decouple branch 2 times, most recently from 1bd6411 to 9f1b36b Compare August 4, 2026 13:29
@charlielye
charlielye force-pushed the cl/ipc-6-memory-merkle-db branch from 0a5f500 to af48fb8 Compare August 4, 2026 14:20
@charlielye
charlielye force-pushed the cl/wsdb-decouple branch 2 times, most recently from d559569 to a500914 Compare August 4, 2026 16:23
rangozd pushed a commit to rangozd/aztec-packages that referenced this pull request Aug 5, 2026
…otocol#23697)

## Summary

Cuts the public simulator over from the legacy in-process NAPI AVM path
to the generated `@aztec/bb-avm-sim` IPC service package introduced in
AztecProtocol#23084.

The simulator now drives a pool of out-of-process AVM instances over IPC
and owns a TypeScript CDB IPC server for contract-data callbacks, while
world-state access continues through the generated wsdb package/service
from the lower stack.

## Stack

Merged into `next`: AztecProtocol#23610 `cl/ipc-foundation` · AztecProtocol#23611
`cl/ipc-wsdb-migrate` · AztecProtocol#23036 `cl/ipc-3-avm-wsdb-cutover` · AztecProtocol#23084
`cl/ipc-4-avm-binary`

This chain (bottom → top):

1. AztecProtocol#23697 `cl/ipc-5-avm-cutover` — **this PR** (base `next`)
2. AztecProtocol#24306 `cl/ipc-6-memory-merkle-db` — in-memory `MemoryMerkleDB`
reference; drops `world_state` from vm2
3. AztecProtocol#24392 `cl/wsdb-decouple` — extract wsdb/lmdblib/kvdb into
`native-packages/`, decoupled from barretenberg headers

Parallel IPC stack (independent, also based on `next`): AztecProtocol#23612
`cl/ipc-bb-migrate` → AztecProtocol#23613 `cl/ipc-bb-rs-migrate` → AztecProtocol#23614
`cl/ipc-bb-js-migrate`.

## What changes

### AVM simulator cutover

- Adds `AvmSimulatorPool`, which owns the out-of-process
`@aztec/bb-avm-sim` instances and implements a small `AvmSimulator`
interface (`simulate` / `simulateWithHints`). Checkout/return is fully
internal: `simulate` blocks until an instance is free and releases it
when done, so callers never see the pool mechanics or the IPC transport.
- Bundles the pool and the CDB server into an `AvmExecutor` facade.
`AvmExecutor.forFork(forkId, contractsDB, timestamp)` hands out a
`ForkedAvmSimulator` that registers the fork's contracts DB with the CDB
server for the duration of each `simulate` call. The executor is spawned
once and injected into the node, public processor, checkpoint builder,
TXE, and the fuzzer.
- Adds `AbortSignal`-based cancellation end to end: `PublicTxSimulator`
cancels via an `AbortController`, which signals the external C++ AVM
process (SIGUSR1) to stop at the next opcode / before the next
world-state write, replacing the old in-process cancellation.
- Renames socket-specific parameters to generic IPC paths where the
value may be UDS or SHM.
- Uses explicit async disposal (`AsyncDisposable` / `await using`) for
the AVM executor, CDB server, wsdb service, and the tests/fixtures that
own those resources.

### CDB server generation

- Converts the AVM and CDB schemas to the newer friendly schema format.
- Removes the unused CDB shutdown command; process backends are
controlled by normal process signalling.
- Generates TypeScript CDB server command/response types and request
dispatch from the CDB schema.
- Backs `CdbIpcServer` with the shared `UdsIpcServer` transport from
`@aztec/ipc-runtime` (socket, framing, per-connection response ordering)
rather than hand-rolled framing; `CdbIpcServer` only implements the
generated handler interface.
- Ignores generated CDB TypeScript output and produces it from the
`simulator` generation step during bootstrap.

### Legacy NAPI cleanup

- Deletes the old AVM NAPI simulation implementation.
- Deletes the remaining msgpack client side-channel code from
`nodejs_module`.
- Removes AVM simulation exports from `@aztec/native`, leaving the
remaining native module focused on the native pieces that still live
there.

## Validation

- `yarn build` from `yarn-project/simulator`
- `make bb-avm-sim`
- `cmake --build build --target bb-avm-sim nodejs_module` from
`barretenberg/cpp`
- `yarn build` from `yarn-project`
- `./bootstrap.sh format --check simulator` from `yarn-project`
- `JEST_MAX_WORKERS=1 yarn test public/cdb_ipc_server.test.ts
public/public_processor/apps_tests/token.test.ts
public/public_tx_simulator/apps_tests/token.test.ts
public/public_processor/apps_tests/deployments.test.ts
public/public_processor/public_processor.test.ts` from
`yarn-project/simulator`
@charlielye
charlielye force-pushed the cl/ipc-6-memory-merkle-db branch from 5041b6b to fafdd72 Compare August 5, 2026 08:27
@charlielye
charlielye force-pushed the cl/ipc-6-memory-merkle-db branch from fafdd72 to 94d004c Compare August 5, 2026 13:25
Base automatically changed from cl/ipc-6-memory-merkle-db to next August 12, 2026 10:21
Moves the world-state DB service (world_state engine, persistent
content-addressed merkle storage, lmdb tree store, IPC server) out of
barretenberg into native-packages/wsdb, compiling with zero barretenberg
headers: bb is linked only as a prebuilt archive for the poseidon2 c_bind and
for the new bb_wsref_* C ABI over the in-memory reference world state
(world_state_reference), against which this package's conformance test drives
its WorldState and asserts agreement on roots, sibling paths, low-leaf
lookups, preimages and checkpointing.

Constants stay in lockstep via a wsdb-local remake-constants hook on the
protocol constants-codegen (generated header, no longer checked in).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant