feat: preserve stores on schema version or rollup address change - #24631
Merged
mverzilli merged 51 commits intoJul 10, 2026
Merged
Conversation
Replaces wipe-on-mismatch with store selection keyed on (l1ChainId, rollupAddress, schemaVersion) for both PXE backends.
…) identity instead of wiped
…ress first boot Gate the schema-mismatch throw on a successfully parsed version file so a first boot with a zero rollup address (storedVersion (0, ZERO) vs (N, ZERO)) resets and opens instead of throwing forever. Split rollup-address mismatch handling into its own RollupAddressMismatchPolicy (default 'reset') so the validator HA signer keeps silent reset-on-rollup-change while schema mismatches stay fail-closed. For partitioned lmdb-v2 stores, use a sibling '<name>-stores' directory instead of nesting inside the legacy env dir, so an old binary's rollup-mismatch rm -rf of the legacy dir cannot destroy per-identity stores; force all three mismatch policies to 'throw' when partitionByIdentity is set.
… layout Update the database-version README reset conditions, the store-selection design doc (sibling <name>-stores layout, three throw policies, HA-signer reset default), and the migration note (ts fence, per-backend on-disk data location).
…let data-root constant
…ng to zero Opening a persistent sqlite-opfs store (or composing its identity slug) with a missing l1ChainId, rollupAddress, or schemaVersion silently fell back to the zero identity, which could route two logically different callers to the same physical store. Require the full identity and throw instead. Files: yarn-project/kv-store/src/store_identity.ts, yarn-project/kv-store/src/store_identity.test.ts, yarn-project/kv-store/src/sqlite-opfs/index.ts, yarn-project/kv-store/src/sqlite-opfs/create_store.test.ts
IdentityStoreConfig previously allowed l1ChainId and rollupAddress to be omitted, in which case the identity-partitioned store fell back to the zero identity. Make both fields required so callers can no longer open a PXE data store without a complete identity. Files: yarn-project/pxe/src/entrypoints/server/store.ts, yarn-project/pxe/src/entrypoints/server/utils.ts, yarn-project/pxe/src/entrypoints/server/store.test.ts
…tity The embedded wallet's wallet_data store held account secrets and aliases, which are not tied to any particular network, yet it was keyed by (l1ChainId, rollupAddress, schemaVersion) like the PXE data store. That meant switching networks silently swapped in a different (empty) wallet store. Key wallet_data by schema version alone (wallet_data_v1) so it stays the same store across networks. Files: yarn-project/wallets/src/embedded/wallet_db.ts, yarn-project/wallets/src/embedded/entrypoints/node.ts, yarn-project/wallets/src/embedded/entrypoints/browser.ts
…note Files: docs/docs-developers/docs/resources/migration_notes.md
…wallet_data_v1 location
… lmdb-v2 re-export The identity slug only has one consumer outside the browser backend: the pxe node-side helper, whose lmdb directory names never interoperate with browser DB names. Let the helper compose its own directory-name format inline and keep the identity module private to sqlite-opfs, returning the kv-store node entrypoint to its base state.
…ject It only existed to pick up store_identity.test.ts, which now lives in sqlite-opfs and runs in the browser project; the config is back to its base state.
mverzilli
commented
Jul 10, 2026
Migration notes are append-only, including entries under TBD that this branch does not own; the createStore guidance correction will ride the entry that documents the API change instead.
Thunkar
reviewed
Jul 10, 2026
| 'wallet_data', | ||
| WALLET_DATA_SCHEMA_VERSION, | ||
| { | ||
| dataDirectory: options.ephemeral ? undefined : (pxeConfig.dataDirectory ?? DEFAULT_WALLET_DATA_DIRECTORY), |
Collaborator
There was a problem hiding this comment.
Won't block, but don't love that undefined dataDirectory means ephemeral. It makes intuitive sense, but I'd rather be explicit
Contributor
Author
There was a problem hiding this comment.
yeah tbh I don't like it either, I'll polish it
…explicit An undefined dataDirectory silently meant ephemeral. IdentityStoreConfig now requires the directory and both call sites call openTmpStore explicitly when ephemeral, mirroring the browser entrypoint; the ephemeral node wallet no longer fetches node info it does not use.
vezenovm
reviewed
Jul 10, 2026
vezenovm
left a comment
vezenovm
left a comment
Contributor
There was a problem hiding this comment.
Much better than wiping! Do we want to update yarn-project/pxe/src/storage/backwards_compatibility_tests/pxe_db_compatibility.test.ts? I'm surprised to see that still passing as otherwise I would expect the test to fail no? We may be escaping some of our public API surface in that test then.
…dentity The wipe test drove kv-store lmdb-v2's createStore, which the pxe production path no longer uses. It now opens stores via openStore and asserts the new behavior: an old-schema row is never read by the current version (fresh store selected) and survives untouched under its own identity. The schema-bump guidance strings no longer describe DatabaseVersionManager wiping.
mverzilli
enabled auto-merge (squash)
July 10, 2026 15:39
PhilWindle
added
port-to-next
PhilWindle
pushed a commit
that referenced
this pull request
Jul 21, 2026
This was referenced Jul 21, 2026
Closed
Closed
This was referenced Jul 23, 2026
rangozd
pushed a commit
to rangozd/aztec-packages
that referenced
this pull request
Aug 5, 2026
…ecProtocol#24932) Forward-ports the **pxe / client / txe** slice of the v5-next → next backlog (work merged to `v5-next` after the ~2026-07-08 cut that reshaped `next`). ## Applied (clean cherry-picks, chronological) - fix: tweak depositToAztec gas config (AztecProtocol#24607) - refactor: cache Aztec node reads per execution (AztecProtocol#24630) - fix: prevent access to secrets not in scope (AztecProtocol#24616) - docs: fee readme improvements (AztecProtocol#24666) - fix(pxe): widen tracked sender tagging ranges with onchain discovery evidence (AztecProtocol#24655) - fix: tagging secrets not being scoped by sender (AztecProtocol#24772) ## Conflict resolutions (cherry-picked with `-x`, resolved against reshaped `next`) - fix(txe): align tagging strategy oracle with PXE (AztecProtocol#24561) — TXE oracle version bumped to 4.0 (breaking rename `setTaggingSecretStrategy` -> `setTaggingSecretStrategies`; `next` was at 3.0 with its own hash), interface hash recomputed on the merged registry. Migration note dropped: already on `next` under 5.0.0. - feat(pxe)!: Add AppTaggingSecret kinds to keys in tagging stores (AztecProtocol#24604) — `PXE_DATA_SCHEMA_VERSION` 12 -> 13 applies cleanly on `next`. Migration note dropped: already on `next` under 5.0.0. - feat: add batch is block in archive oracle (AztecProtocol#24634) — applied cleanly on top of AztecProtocol#24561; contract oracle version 30.6 -> 30.7, v5 interface hash matched the merged registry. - feat: getTxEffects oracle (AztecProtocol#24636) — applied cleanly. - ~~feat: preserve stores on schema version or rollup address change (AztecProtocol#24631)~~ — ported separately via AztecProtocol#24947 together with the rest of the sqlite/OPFS line - feat(txe): add option to authorize all utility call targets (AztecProtocol#24662) — additive on our 4.0 -> TXE oracle version 4.1 (was 3.0 -> 3.1 on v5), hash recomputed. - refactor(pxe): compute oracle interface hash from wire-structural mapping labels (AztecProtocol#24752) — TXE hash recomputed under the new wire-structural scheme; PXE hash from the pick matched. Verified locally: full `yarn build`, `check_oracle_version` + `check_txe_oracle_version`, TXE unit suite (21), pxe tagging/type-mapping/utility-oracle suites, and 29 targeted aztec-nr + onchain_delivery_test_contract TXE tests — all green. Part of the manual v5-next → next backlog sweep. ## Added after review - AztecProtocol#24627 fix(aztec.js): give waitForNode a bounded default timeout — missed by the initial sweep (merge-commit wrapper + non-`(#N)` leaf); genuinely absent from `next`.
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
4 participants
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.
Changes store management so that changes in rollup addresses and schema versions cause different stores to be used. Previously we only supported one store to be present at a time, which meant any version or rollup change wiped pre-existing stores (note this includes network changes).
An underlying design decision in this PR is to strip the kv-store package from responsibility over location on disk, knowledge about rollup addresses, etc, at least as as regards PXE and wallet storage. Other users of LMDB-v2 should not be impacted by this change.
In consonance, IndexedDB and SQLite backends drop their
createStorefunctions, which shoehorned wallet and PXE store creation to an homogeneous interface that made it hard to let them independently evolve.Since we're changing this, I decided to also include the chain id as a component of the store id, in addition to the already present schema version and rollup address. It's not clear that we'll ever work on a testnet or a different L1, but doing so is trivial and removes the need to deal with this in the future.
Closes F-809