@aztec/pxe 5.0.0-private.20260319 → 5.0.0-rc.1

package/src/storage/anchor_block_store/anchor_block_store.ts

@@ -1,6 +1,10 @@
 import type { AztecAsyncKVStore, AztecAsyncSingleton } from '@aztec/kv-store';
 import { BlockHeader } from '@aztec/stdlib/tx';
 
+/**
+ * Holds the block header that PXE's private execution is anchored to. Updated by the BlockSynchronizer as the chain
+ * advances or reorgs.
+ */
 export class AnchorBlockStore {
   #store: AztecAsyncKVStore;
   #synchronizedHeader: AztecAsyncSingleton<Buffer>;
@@ -11,23 +15,21 @@ export class AnchorBlockStore {
   }
 
   /**
-   * Sets the currently synchronized block
-   *
-   * Important: this method is only called from BlockSynchronizer, and since we need it to run atomically with other
-   * stores in the case of a reorg, it MUST NOT be wrapped in a `transactionAsync` call. Doing so would result in a
-   * deadlock when the backend is IndexedDB, because `transactionAsync` is not designed to support reentrancy.
+   * Sets the currently synchronized block header.
    *
+   * Important: only called from BlockSynchronizer, and since it must run atomically with other stores in a reorg, it
+   * MUST NOT be wrapped in `transactionAsync`: doing so deadlocks when the kv-store backend is IndexedDB (no
+   * support for reentrancy).
    */
   async setHeader(header: BlockHeader): Promise<void> {
     await this.#synchronizedHeader.set(header.toBuffer());
   }
 
   async getBlockHeader(): Promise<BlockHeader> {
-    const headerBuffer = await this.#synchronizedHeader.getAsync();
+    const headerBuffer = await this.#store.transactionAsync(() => this.#synchronizedHeader.getAsync());
     if (!headerBuffer) {
       throw new Error(`Trying to get block header with a not-yet-synchronized PXE - this should never happen`);
     }
-
     return BlockHeader.fromBuffer(headerBuffer);
   }
 }

package/src/storage/backwards_compatibility_tests/__snapshots__/AddressStore.json

@@ -0,0 +1,22 @@
+{
+  "complete_addresses": [
+    {
+      "index": 0,
+      "value": "0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea313ad6965d11a533a663d07507319f74ac3305325f6f72423c0b24aa1193268bb19e95c05f09cb86d1a6257572f9082ca15d4a02373c4d8c9cee23dc61a4c2a882f9017d51bca6616102d8a1d4dba89e4ce12881a2414576f01d2fec9492814a22a1b054e998835d166711839b515d434b1fbc207ad4fdb5b2b43d6ac6b400871019f5bb255e87523d43da83ebc9fa95169b653d4abef902e011e9eac620fc45b14a5d4bde495b8c3a9ba4aed0d4870526e46fdff22d341a2f689ac5a50d103560f124f07811eebfaaa6d31316a2cc5bf255fa118f720e8ff1f2fc0d4aa46d4960000000000000000000000000000000000000000000000000000000000000003"
+    },
+    {
+      "index": 1,
+      "value": "2cf4c6a79bcb041923c0cf1cfbb6c7407e082824e29588dbcf9cc6c1d6e8b01f17c2df1b7355bb4c4494aa4ec85d15ff8881cea1b34691f0cc558e8aef3f3f4c267e526a2e6e9adf6a026989be005bd50d1aea76d20816b9843bc95557696f9f16c3eb259ba3e3eb27b7fe3abc36e87923990bf5c265cb0d57790eda2a4432f105a5449624125d37f10cd4c68ffd57b0dc0cdaa916cb37840be1db9bf88e3c5f0e81754454e3b12035b13448a9fe3b980bf31a9808cb93e146628fb06fa1b46f14a5d4bde495b8c3a9ba4aed0d4870526e46fdff22d341a2f689ac5a50d103560f124f07811eebfaaa6d31316a2cc5bf255fa118f720e8ff1f2fc0d4aa46d4960000000000000000000000000000000000000000000000000000000000000007"
+    }
+  ],
+  "complete_address_index": [
+    {
+      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3",
+      "value": "num:0"
+    },
+    {
+      "key": "utf8:0x2cf4c6a79bcb041923c0cf1cfbb6c7407e082824e29588dbcf9cc6c1d6e8b01f",
+      "value": "num:1"
+    }
+  ]
+}

package/src/storage/backwards_compatibility_tests/__snapshots__/AnchorBlockStore.json

@@ -0,0 +1,3 @@
+{
+  "header": "000000000000000000000000000000000000000000000000000000000000000200000003000000000000000000000000000000000000000000000000000000000000000500000007000000000000000000000000000000000000000000000000000000000000000b0000000d00000000000000000000000000000000000000000000000000000000000000110000001300000000000000000000000000000000000000000000000000000000000000170000001d000000000000000000000000000000000000000000000000000000000000001f000000000000000000000000000000000000000000000000000000000000002500000000000000000000000000000000000000000000000000000000000000290000002b0000002f0000000000000035000000000000000000000000000000000000003b000000000000000000000000000000000000000000000000000000000000003d00000000000000000000000000000043000000000000000000000000000000470000000000000000000000000000000000000000000000000000000000000049000000000000000000000000000000000000000000000000000000000000004f"
+}

package/src/storage/backwards_compatibility_tests/__snapshots__/CapsuleStore.json

@@ -0,0 +1,16 @@
+{
+  "capsules": [
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002:0x0000000000000000000000000000000000000000000000000000000000000003:0x0000000000000000000000000000000000000000000000000000000000000005",
+      "value": "0000000000000000000000000000000000000000000000000000000000000007000000000000000000000000000000000000000000000000000000000000000b"
+    },
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002:0x0000000000000000000000000000000000000000000000000000000000000003:0x000000000000000000000000000000000000000000000000000000000000000d",
+      "value": "0000000000000000000000000000000000000000000000000000000000000011"
+    },
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002:0x0000000000000000000000000000000000000000000000000000000000000003:0x0000000000000000000000000000000000000000000000000000000000000013",
+      "value": ""
+    }
+  ]
+}

package/src/storage/backwards_compatibility_tests/__snapshots__/ContractStore.json

@@ -0,0 +1,28 @@
+{
+  "contract_artifacts": [
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002",
+      "value": "7b226e616d65223a22536368656d6146697874757265436f6e7472616374222c22617a74656356657273696f6e223a22736368656d612d666978747572652d76657273696f6e222c2266756e6374696f6e73223a5b7b226e616d65223a22707269766174655f666e222c2266756e6374696f6e54797065223a2270726976617465222c2269734f6e6c7953656c66223a66616c73652c226973537461746963223a66616c73652c226973496e697469616c697a6572223a747275652c22706172616d6574657273223a5b7b226e616d65223a226669727374222c2274797065223a7b226b696e64223a226669656c64227d2c227669736962696c697479223a2270726976617465227d2c7b226e616d65223a227365636f6e64222c2274797065223a7b226b696e64223a22696e7465676572222c227369676e223a22756e7369676e6564222c227769647468223a33327d2c227669736962696c697479223a227075626c6963227d5d2c2272657475726e5479706573223a5b7b226b696e64223a22626f6f6c65616e227d5d2c226572726f725479706573223a7b22736368656d615f746573745f6572726f72223a7b226572726f725f6b696e64223a22737472696e67222c22737472696e67223a22666978656420736368656d612d74657374206572726f72227d7d2c2262797465636f6465223a2241674d4642773d3d222c22646562756753796d626f6c73223a22736368656d612d666978747572652d6465627567227d5d2c226e6f6e44697370617463685075626c696346756e6374696f6e73223a5b7b226e616d65223a227075626c69635f666e222c2266756e6374696f6e54797065223a227075626c6963222c2269734f6e6c7953656c66223a747275652c226973537461746963223a747275652c226973496e697469616c697a6572223a66616c73652c22706172616d6574657273223a5b5d2c2272657475726e5479706573223a5b5d2c226572726f725479706573223a7b7d7d5d2c226f757470757473223a7b2273747275637473223a7b226d795f737472756374223a5b7b226b696e64223a226669656c64227d2c7b226b696e64223a22626f6f6c65616e227d5d7d2c22676c6f62616c73223a7b7d7d2c2273746f726167654c61796f7574223a7b226d795f6669656c64223a7b22736c6f74223a22307830303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303062227d7d2c2266696c654d6170223a7b2231223a7b22736f75726365223a22736368656d61206669787475726520736f75726365222c2270617468223a227372632f736368656d615f666978747572652e6e72222c2266756e6374696f6e5f6c6f636174696f6e73223a5b5d7d7d7d"
+    },
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000017",
+      "value": "7b226e616d65223a22536368656d6146697874757265436f6e7472616374222c22617a74656356657273696f6e223a22736368656d612d666978747572652d76657273696f6e222c2266756e6374696f6e73223a5b7b226e616d65223a22707269766174655f666e222c2266756e6374696f6e54797065223a2270726976617465222c2269734f6e6c7953656c66223a66616c73652c226973537461746963223a66616c73652c226973496e697469616c697a6572223a747275652c22706172616d6574657273223a5b7b226e616d65223a226669727374222c2274797065223a7b226b696e64223a226669656c64227d2c227669736962696c697479223a2270726976617465227d2c7b226e616d65223a227365636f6e64222c2274797065223a7b226b696e64223a22696e7465676572222c227369676e223a22756e7369676e6564222c227769647468223a33327d2c227669736962696c697479223a227075626c6963227d5d2c2272657475726e5479706573223a5b7b226b696e64223a22626f6f6c65616e227d5d2c226572726f725479706573223a7b22736368656d615f746573745f6572726f72223a7b226572726f725f6b696e64223a22737472696e67222c22737472696e67223a22666978656420736368656d612d74657374206572726f72227d7d2c2262797465636f6465223a2241674d4642773d3d222c22646562756753796d626f6c73223a22736368656d612d666978747572652d6465627567227d5d2c226e6f6e44697370617463685075626c696346756e6374696f6e73223a5b7b226e616d65223a227075626c69635f666e222c2266756e6374696f6e54797065223a227075626c6963222c2269734f6e6c7953656c66223a747275652c226973537461746963223a747275652c226973496e697469616c697a6572223a66616c73652c22706172616d6574657273223a5b5d2c2272657475726e5479706573223a5b5d2c226572726f725479706573223a7b7d7d5d2c226f757470757473223a7b2273747275637473223a7b226d795f737472756374223a5b7b226b696e64223a226669656c64227d2c7b226b696e64223a22626f6f6c65616e227d5d7d2c22676c6f62616c73223a7b7d7d2c2273746f726167654c61796f7574223a7b226d795f6669656c64223a7b22736c6f74223a22307830303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303062227d7d2c2266696c654d6170223a7b2231223a7b22736f75726365223a22736368656d61206669787475726520736f75726365222c2270617468223a227372632f736368656d615f666978747572652e6e72222c2266756e6374696f6e5f6c6f636174696f6e73223a5b5d7d7d7d"
+    }
+  ],
+  "contract_classes": [
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002",
+      "value": "010000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000000000000000000000000000000000000050000000000000000000000000000000000000000000000000000000000000007000000020000000b000000000000000000000000000000000000000000000000000000000000000d000000110000000000000000000000000000000000000000000000000000000000000013"
+    },
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000017",
+      "value": "010000000000000000000000000000000000000000000000000000000000000017000000000000000000000000000000000000000000000000000000000000001d000000000000000000000000000000000000000000000000000000000000001f000000000000000000000000000000000000000000000000000000000000002500000000"
+    }
+  ],
+  "contracts_instances": [
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000065",
+      "value": "020000000000000000000000000000000000000000000000000000000000000049000000000000000000000000000000000000000000000000000000000000004f00000000000000000000000000000000000000000000000000000000000000530000000000000000000000000000000000000000000000000000000000000059000000000000000000000000000000000000000000000000000000000000006100000000000000000000000000000000000000000000000000000000000000670000000000000000000000000000000000000000000000000000000000000029000000000000000000000000000000000000000000000000000000000000002f0000000000000000000000000000000000000000000000000000000000000035000000000000000000000000000000000000000000000000000000000000003b000000000000000000000000000000000000000000000000000000000000004300000000000000000000000000000000000000000000000000000000000000470000000000000000000000000000000000000000000000000000000000000049"
+    }
+  ]
+}

package/src/storage/backwards_compatibility_tests/__snapshots__/KeyStore.json

@@ -0,0 +1,52 @@
+{
+  "key_store": [
+    {
+      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-ivpk_m",
+      "value": "19e95c05f09cb86d1a6257572f9082ca15d4a02373c4d8c9cee23dc61a4c2a882f9017d51bca6616102d8a1d4dba89e4ce12881a2414576f01d2fec9492814a2"
+    },
+    {
+      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-ivpk_m_hash",
+      "value": "1fd17152d394f6a43b527c531590888d610d1bcb9aa71a02498ce820bbf4dc62"
+    },
+    {
+      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-ivsk_m",
+      "value": "1fb01c42d1aaa2662041b899c77cb19e08192193acc5a94405f1b43c974eba7a"
+    },
+    {
+      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-nhk_m",
+      "value": "2dd30220767969b10044b1322585bb4c4df4e0c5d9b4d7b3045a879a8e3e91d2"
+    },
+    {
+      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-npk_m",
+      "value": "214c7a24ddf501afc8734c7379ee502296289eb24cd8cd03cd435e128c06be0000987721e0963b4a5bd81ee862e2740d8849fd90537569064d3d3a4640e858d2"
+    },
+    {
+      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-npk_m_hash",
+      "value": "13ad6965d11a533a663d07507319f74ac3305325f6f72423c0b24aa1193268bb"
+    },
+    {
+      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-ovpk_m",
+      "value": "2c19ff0b089b07da436e6f7be6b26cdc17b9cee504a528c071ef6a416299683d0b369479d6e50504702d0b56bb56e4e8e0e77171429896651d0c11621e82ebc3"
+    },
+    {
+      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-ovpk_m_hash",
+      "value": "2a1b054e998835d166711839b515d434b1fbc207ad4fdb5b2b43d6ac6b400871"
+    },
+    {
+      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-ovsk_m",
+      "value": "279fe6ef7dd2477b919327b1ebab7497c41b9a7ccfa9d5d52e32698e3b85293b"
+    },
+    {
+      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-tpk_m",
+      "value": "2fcdd0d194adafd753dc0ed279f5cfb54ddcce1dd581d4631cf343ba9ee6c1ab2858abca6c00da3def156b1f12a6464384e326d5fa724c2fc2ff2b7f3fc8ad5f"
+    },
+    {
+      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-tpk_m_hash",
+      "value": "019f5bb255e87523d43da83ebc9fa95169b653d4abef902e011e9eac620fc45b"
+    },
+    {
+      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-tsk_m",
+      "value": "183cb61099458d1564aa57c90c7091ac623a14092ab314150c9cfbb416810320"
+    }
+  ]
+}

package/src/storage/backwards_compatibility_tests/__snapshots__/L2TipsKVStore.json

@@ -0,0 +1,40 @@
+{
+  "pxe_l2_tips": [
+    {
+      "key": "utf8:checkpointed",
+      "value": "num:71"
+    },
+    {
+      "key": "utf8:proposed",
+      "value": "num:179"
+    },
+    {
+      "key": "utf8:proven",
+      "value": "num:79"
+    }
+  ],
+  "pxe_l2_tip_checkpoints": [
+    {
+      "key": "utf8:checkpointed",
+      "value": "{\"number\":47,\"hash\":\"0x00a21eaf943186f15f609a8a76fb0bee7ce3e78c86ef95f5466614e59546eb19\"}"
+    },
+    {
+      "key": "utf8:proven",
+      "value": "{\"number\":47,\"hash\":\"0x0000000000000000000000000000000000000000000000000000000000000059\"}"
+    }
+  ],
+  "pxe_l2_block_hashes": [
+    {
+      "key": "num:179",
+      "value": "utf8:0x10547c3c23be9d4208cc6d60355ca61c35bd612ace129984ed97a6cc4ec007f8"
+    },
+    {
+      "key": "num:71",
+      "value": "utf8:0x0000000000000000000000000000000000000000000000000000000000000049"
+    },
+    {
+      "key": "num:79",
+      "value": "utf8:0x0000000000000000000000000000000000000000000000000000000000000053"
+    }
+  ]
+}

package/src/storage/backwards_compatibility_tests/__snapshots__/NoteStore.json

@@ -0,0 +1,56 @@
+{
+  "notes": [
+    {
+      "key": "utf8:0x000000000000000000000000000000000000000000000000000000000000002b",
+      "value": "00000003000000000000000000000000000000000000000000000000000000000000000d0000000000000000000000000000000000000000000000000000000000000011000000000000000000000000000000000000000000000000000000000000001300000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000017000000000000000000000000000000000000000000000000000000000000001d000000000000000000000000000000000000000000000000000000000000001f00000000000000000000000000000000000000000000000000000000000000250000000000000000000000000000000000000000000000000000000000000029000000000000000000000000000000000000000000000000000000000000002b000000000000000000000000000000000000000000000000000000000000002f00000035000000000000000000000000000000000000000000000000000000000000003b0000003d00000043000000020000004230783030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303500000042307830303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303037"
+    },
+    {
+      "key": "utf8:0x000000000000000000000000000000000000000000000000000000000000006b",
+      "value": "0000000300000000000000000000000000000000000000000000000000000000000000470000000000000000000000000000000000000000000000000000000000000049000000000000000000000000000000000000000000000000000000000000004f000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000530000000000000000000000000000000000000000000000000000000000000059000000000000000000000000000000000000000000000000000000000000006100000000000000000000000000000000000000000000000000000000000000650000000000000000000000000000000000000000000000000000000000000067000000000000000000000000000000000000000000000000000000000000006b000000000000000000000000000000000000000000000000000000000000006d00000071000000000000000000000000000000000000000000000000000000000000007f00000083000000890000000100000042307830303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303035"
+    },
+    {
+      "key": "utf8:0x00000000000000000000000000000000000000000000000000000000000000b5",
+      "value": "00000003000000000000000000000000000000000000000000000000000000000000008b000000000000000000000000000000000000000000000000000000000000009500000000000000000000000000000000000000000000000000000000000000970000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000009d00000000000000000000000000000000000000000000000000000000000000a300000000000000000000000000000000000000000000000000000000000000a700000000000000000000000000000000000000000000000000000000000000ad00000000000000000000000000000000000000000000000000000000000000b300000000000000000000000000000000000000000000000000000000000000b500000000000000000000000000000000000000000000000000000000000000bf000000c100000000000000000000000000000000000000000000000000000000000000c5000000c7000000d30000000100000042307830303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303035"
+    }
+  ],
+  "note_nullifiers_by_contract": [
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002",
+      "value": "utf8:0x000000000000000000000000000000000000000000000000000000000000002b"
+    },
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002",
+      "value": "utf8:0x000000000000000000000000000000000000000000000000000000000000006b"
+    },
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000003",
+      "value": "utf8:0x00000000000000000000000000000000000000000000000000000000000000b5"
+    }
+  ],
+  "note_nullifications_by_nullifier": [
+    {
+      "key": "utf8:0x00000000000000000000000000000000000000000000000000000000000000b5",
+      "value": "num:223"
+    }
+  ],
+  "note_nullifiers_by_block": [
+    {
+      "key": "num:113",
+      "value": "utf8:0x000000000000000000000000000000000000000000000000000000000000006b"
+    },
+    {
+      "key": "num:193",
+      "value": "utf8:0x00000000000000000000000000000000000000000000000000000000000000b5"
+    },
+    {
+      "key": "num:53",
+      "value": "utf8:0x000000000000000000000000000000000000000000000000000000000000002b"
+    }
+  ],
+  "note_nullifications_by_block": [
+    {
+      "key": "num:223",
+      "value": "utf8:0x00000000000000000000000000000000000000000000000000000000000000b5"
+    }
+  ]
+}

package/src/storage/backwards_compatibility_tests/__snapshots__/PrivateEventStore.json

@@ -0,0 +1,44 @@
+{
+  "private_event_logs": [
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000017",
+      "value": "000000000000000000000000000000000000000000000000000000000000001d00000003000000000000000000000000000000000000000000000000000000000000001f0000000000000000000000000000000000000000000000000000000000000025000000000000000000000000000000000000000000000000000000000000002900000011000000000000000000000000000000000000000000000000000000000000002f000000000000000000000000000000000000000000000000000000000000002b000000350000003b000000000000000000000000000000000000000000000000000000000000000200000005000000020000004230783030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030306200000042307830303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303064"
+    },
+    {
+      "key": "utf8:0x000000000000000000000000000000000000000000000000000000000000004f",
+      "value": "000000000000000000000000000000000000000000000000000000000000003d00000003000000000000000000000000000000000000000000000000000000000000004300000000000000000000000000000000000000000000000000000000000000470000000000000000000000000000000000000000000000000000000000000049000000110000000000000000000000000000000000000000000000000000000000000059000000000000000000000000000000000000000000000000000000000000005300000061000000650000000000000000000000000000000000000000000000000000000000000002000000050000000100000042307830303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303062"
+    },
+    {
+      "key": "utf8:0x000000000000000000000000000000000000000000000000000000000000007f",
+      "value": "000000000000000000000000000000000000000000000000000000000000006700000003000000000000000000000000000000000000000000000000000000000000006b000000000000000000000000000000000000000000000000000000000000006d000000000000000000000000000000000000000000000000000000000000007100000013000000000000000000000000000000000000000000000000000000000000008900000000000000000000000000000000000000000000000000000000000000830000008b000000950000000000000000000000000000000000000000000000000000000000000003000000070000000100000042307830303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303062"
+    }
+  ],
+  "events_by_contract_selector": [
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002_0x00000005",
+      "value": "utf8:0x0000000000000000000000000000000000000000000000000000000000000017"
+    },
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002_0x00000005",
+      "value": "utf8:0x000000000000000000000000000000000000000000000000000000000000004f"
+    },
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000003_0x00000007",
+      "value": "utf8:0x000000000000000000000000000000000000000000000000000000000000007f"
+    }
+  ],
+  "events_by_block_number": [
+    {
+      "key": "num:17",
+      "value": "utf8:0x0000000000000000000000000000000000000000000000000000000000000017"
+    },
+    {
+      "key": "num:17",
+      "value": "utf8:0x000000000000000000000000000000000000000000000000000000000000004f"
+    },
+    {
+      "key": "num:19",
+      "value": "utf8:0x000000000000000000000000000000000000000000000000000000000000007f"
+    }
+  ]
+}

package/src/storage/backwards_compatibility_tests/__snapshots__/RecipientTaggingStore.json

@@ -0,0 +1,18 @@
+{
+  "highest_aged_index": [
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002:0x0000000000000000000000000000000000000000000000000000000000000003",
+      "value": "num:13"
+    }
+  ],
+  "highest_finalized_index": [
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002:0x0000000000000000000000000000000000000000000000000000000000000003",
+      "value": "num:11"
+    },
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000005:0x0000000000000000000000000000000000000000000000000000000000000007",
+      "value": "num:17"
+    }
+  ]
+}

package/src/storage/backwards_compatibility_tests/__snapshots__/SenderAddressBookStore.json

@@ -0,0 +1,16 @@
+{
+  "address_book": [
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002",
+      "value": "true"
+    },
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000003",
+      "value": "true"
+    },
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000005",
+      "value": "true"
+    }
+  ]
+}

package/src/storage/backwards_compatibility_tests/__snapshots__/SenderTaggingStore.json

@@ -0,0 +1,22 @@
+{
+  "pending_indexes": [
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002:0x0000000000000000000000000000000000000000000000000000000000000003",
+      "value": "[{\"lowestIndex\":4,\"highestIndex\":7,\"txHash\":\"0x0000000000000000000000000000000000000000000000000000000000000013\"},{\"lowestIndex\":8,\"highestIndex\":11,\"txHash\":\"0x0000000000000000000000000000000000000000000000000000000000000017\"}]"
+    },
+    {
+      "key": "utf8:0x000000000000000000000000000000000000000000000000000000000000000b:0x000000000000000000000000000000000000000000000000000000000000000d",
+      "value": "[{\"lowestIndex\":1,\"highestIndex\":9,\"txHash\":\"0x000000000000000000000000000000000000000000000000000000000000001d\"}]"
+    }
+  ],
+  "last_finalized_indexes": [
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002:0x0000000000000000000000000000000000000000000000000000000000000003",
+      "value": "num:3"
+    },
+    {
+      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000005:0x0000000000000000000000000000000000000000000000000000000000000007",
+      "value": "num:5"
+    }
+  ]
+}

package/src/storage/backwards_compatibility_tests/__snapshots__/opened_stores.json

@@ -0,0 +1,101 @@
+{
+  "schemaVersion": 8,
+  "stores": [
+    {
+      "name": "address_book",
+      "kind": "map"
+    },
+    {
+      "name": "capsules",
+      "kind": "map"
+    },
+    {
+      "name": "complete_address_index",
+      "kind": "map"
+    },
+    {
+      "name": "complete_addresses",
+      "kind": "array"
+    },
+    {
+      "name": "contract_artifacts",
+      "kind": "map"
+    },
+    {
+      "name": "contract_classes",
+      "kind": "map"
+    },
+    {
+      "name": "contracts_instances",
+      "kind": "map"
+    },
+    {
+      "name": "events_by_block_number",
+      "kind": "multimap"
+    },
+    {
+      "name": "events_by_contract_selector",
+      "kind": "multimap"
+    },
+    {
+      "name": "header",
+      "kind": "singleton"
+    },
+    {
+      "name": "highest_aged_index",
+      "kind": "map"
+    },
+    {
+      "name": "highest_finalized_index",
+      "kind": "map"
+    },
+    {
+      "name": "key_store",
+      "kind": "map"
+    },
+    {
+      "name": "last_finalized_indexes",
+      "kind": "map"
+    },
+    {
+      "name": "note_nullifications_by_block",
+      "kind": "multimap"
+    },
+    {
+      "name": "note_nullifications_by_nullifier",
+      "kind": "map"
+    },
+    {
+      "name": "note_nullifiers_by_block",
+      "kind": "multimap"
+    },
+    {
+      "name": "note_nullifiers_by_contract",
+      "kind": "multimap"
+    },
+    {
+      "name": "notes",
+      "kind": "map"
+    },
+    {
+      "name": "pending_indexes",
+      "kind": "map"
+    },
+    {
+      "name": "private_event_logs",
+      "kind": "map"
+    },
+    {
+      "name": "pxe_l2_block_hashes",
+      "kind": "map"
+    },
+    {
+      "name": "pxe_l2_tip_checkpoints",
+      "kind": "map"
+    },
+    {
+      "name": "pxe_l2_tips",
+      "kind": "map"
+    }
+  ]
+}

package/src/storage/backwards_compatibility_tests/kv_store_snapshot.ts

@@ -0,0 +1,122 @@
+import type { AztecAsyncArray, AztecAsyncMap, AztecAsyncSingleton, Key } from '@aztec/kv-store';
+
+/**
+ * This file contains helpers that produce stable, snapshot-friendly text representations of our kv-stores'
+ * contents (map / multimap / array / singleton). Used by the backwards compatibility tests in this directory to
+ * fingerprint the bytes PXE persists.
+ *
+ * Each backwards compatibility schema scenario test follows the same shape:
+ *
+ * 1. drive the production write path through the store class's public API.
+ * 2. re-open the underlying kv-store by name, bypassing the store abstraction layer (eg:
+ * `kvStore.openMap<K, Buffer>('foo')`) and snapshot it via the helpers below.
+ * 3. compare fresh snapshots with committed ones.
+ *
+ * Why text rather than buffers: Jest snapshots are stored as JS literals; `Buffer` instances render as the verbose
+ * `Buffer <01 02 03>` form, which clutters `.snap` files and resists clean diffs. Each collection's contents are
+ * normalized into strings before being fed to `toMatchSnapshot()`.
+ */
+
+/** A single map/multimap entry, rendered as strings for stable snapshotting. */
+export type MapEntry = { key: string; value: string };
+
+/** A single array entry, rendered as a string for stable snapshotting. */
+export type ArrayEntry = { index: number; value: string };
+
+/**
+ * Returns every entry of the given map (or multimap), with both keys and values rendered as strings, sorted by key
+ * with value as a tiebreaker.
+ */
+export async function snapshotMap<K extends Key, V>(map: AztecAsyncMap<K, V>): Promise<MapEntry[]> {
+  const entries: MapEntry[] = [];
+  for await (const [k, v] of map.entriesAsync()) {
+    entries.push({ key: keyToString(k), value: valueToString(v) });
+  }
+  return entries.sort(compareMapEntries);
+}
+
+/**
+ * Returns the contents of `array` paired with their numeric indices, in insertion order.
+ *
+ * Unlike {@link snapshotMap}, no sort: arrays are inherently ordered by index and that order *is* part of the schema.
+ * The `index` field is preserved on each entry so any unintended reorder shows up in the diff.
+ */
+export async function snapshotArray<V>(array: AztecAsyncArray<V>): Promise<ArrayEntry[]> {
+  const entries: ArrayEntry[] = [];
+  let index = 0;
+  for await (const v of array.valuesAsync()) {
+    entries.push({ index: index++, value: valueToString(v) });
+  }
+  return entries;
+}
+
+/** Returns the singleton's value rendered as a string, or `null` if unset. */
+export async function snapshotSingleton<V>(singleton: AztecAsyncSingleton<V>): Promise<string | null> {
+  const value = await singleton.getAsync();
+  return value === undefined ? null : valueToString(value);
+}
+
+function compareMapEntries(a: MapEntry, b: MapEntry): number {
+  return a.key === b.key ? a.value.localeCompare(b.value) : a.key.localeCompare(b.key);
+}
+
+/**
+ * Renders a key as a stable string. Buffers and `Uint8Array`s become `0x`-prefixed hex (matching the canonical byte
+ * form used by `Fr.toString()`, `AztecAddress.toString()`, etc. elsewhere in the codebase); primitives carry a type
+ * prefix (`utf8:`, `num:`) so that different runtime types can't alias to the same string in a snapshot. Without the
+ * prefix, a future change that swapped a `number` key for a `string` of the same digits would be invisible in the
+ * diff.
+ */
+function keyToString(k: unknown): string {
+  if (typeof k === 'string') {
+    return `utf8:${k}`;
+  }
+  if (typeof k === 'number') {
+    return `num:${k}`;
+  }
+  if (Buffer.isBuffer(k)) {
+    return `0x${k.toString('hex')}`;
+  }
+  if (k instanceof Uint8Array) {
+    return `0x${Buffer.from(k).toString('hex')}`;
+  }
+  if (Array.isArray(k)) {
+    return `[${k.map(keyToString).join(',')}]`;
+  }
+  return JSON.stringify(k);
+}
+
+/**
+ * Renders a value for snapshotting. Same type-prefix discipline as {@link keyToString} so primitives can't
+ * accidentally render identically to buffers carrying the same bytes.
+ *
+ * Resolution order:
+ *   1. `Buffer` / `Uint8Array` -> hex. This is the on-disk byte view; the kv-store layer treats these as opaque, so
+ *      what we see here is exactly what's persisted.
+ *   2. Tagged primitives (`num:`, `big:`, `utf8:`).
+ *   3. `Bufferable` fallback: any object with a `.toBuffer()` method renders as `value.toBuffer().toString('hex')`.
+ *      Covers stdlib domain types stored without pre-serialization. The canonical byte form is what we want to
+ *      fingerprint.
+ *   4. `JSON.stringify` for plain objects, matching how the kv-store layer encodes arbitrary structures on disk.
+ */
+function valueToString(v: unknown): string {
+  if (Buffer.isBuffer(v)) {
+    return v.toString('hex');
+  }
+  if (v instanceof Uint8Array) {
+    return Buffer.from(v).toString('hex');
+  }
+  if (typeof v === 'number') {
+    return `num:${v}`;
+  }
+  if (typeof v === 'bigint') {
+    return `big:${v.toString()}`;
+  }
+  if (typeof v === 'string') {
+    return `utf8:${v}`;
+  }
+  if (v && typeof (v as { toBuffer?: unknown }).toBuffer === 'function') {
+    return (v as { toBuffer: () => Buffer }).toBuffer().toString('hex');
+  }
+  return JSON.stringify(v);
+}