@aztec-labs/pxe 6.0.0-nightly.20260829

package/dest/storage/address_store/address_store.d.ts

@@ -0,0 +1,11 @@
+import type { AztecAsyncKVStore } from '@aztec-labs/kv-store';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { CompleteAddress } from '@aztec-labs/stdlib/contract';
+export declare class AddressStore {
+    #private;
+    constructor(store: AztecAsyncKVStore);
+    addCompleteAddress(completeAddress: CompleteAddress): Promise<boolean>;
+    getCompleteAddress(account: AztecAddress): Promise<CompleteAddress | undefined>;
+    getCompleteAddresses(): Promise<CompleteAddress[]>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYWRkcmVzc19zdG9yZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3N0b3JhZ2UvYWRkcmVzc19zdG9yZS9hZGRyZXNzX3N0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUVBLE9BQU8sS0FBSyxFQUFtQixpQkFBaUIsRUFBaUIsTUFBTSxzQkFBc0IsQ0FBQztBQUM5RixPQUFPLEtBQUssRUFBRSxZQUFZLEVBQUUsTUFBTSxrQ0FBa0MsQ0FBQztBQUNyRSxPQUFPLEVBQUUsZUFBZSxFQUFFLE1BQU0sNkJBQTZCLENBQUM7QUFFOUQscUJBQWEsWUFBWTs7SUFLdkIsWUFBWSxLQUFLLEVBQUUsaUJBQWlCLEVBS25DO0lBRUQsa0JBQWtCLENBQUMsZUFBZSxFQUFFLGVBQWUsR0FBRyxPQUFPLENBQUMsT0FBTyxDQUFDLENBMEJyRTtJQUVELGtCQUFrQixDQUFDLE9BQU8sRUFBRSxZQUFZLEdBQUcsT0FBTyxDQUFDLGVBQWUsR0FBRyxTQUFTLENBQUMsQ0FVOUU7SUFFRCxvQkFBb0IsSUFBSSxPQUFPLENBQUMsZUFBZSxFQUFFLENBQUMsQ0FNakQ7Q0FDRiJ9

package/dest/storage/address_store/address_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address_store.d.ts","sourceRoot":"","sources":["../../../src/storage/address_store/address_store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAmB,iBAAiB,EAAiB,MAAM,sBAAsB,CAAC;AAC9F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,qBAAa,YAAY;;IAKvB,YAAY,KAAK,EAAE,iBAAiB,EAKnC;IAED,kBAAkB,CAAC,eAAe,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CA0BrE;IAED,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAU9E;IAED,oBAAoB,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAMjD;CACF"}

package/dest/storage/address_store/address_store.js

@@ -0,0 +1,49 @@
+import { toArray } from '@aztec-labs/foundation/iterable';
+import { allToCompletion } from '@aztec-labs/foundation/promise';
+import { CompleteAddress } from '@aztec-labs/stdlib/contract';
+export class AddressStore {
+    #store;
+    #completeAddresses;
+    #completeAddressIndex;
+    constructor(store){
+        this.#store = store;
+        this.#completeAddresses = this.#store.openArray('complete_addresses');
+        this.#completeAddressIndex = this.#store.openMap('complete_address_index');
+    }
+    addCompleteAddress(completeAddress) {
+        return this.#store.transactionAsync(async ()=>{
+            // TODO readd this
+            // await this.#addScope(completeAddress.address);
+            const addressString = completeAddress.address.toString();
+            const buffer = completeAddress.toBuffer();
+            const existing = await this.#completeAddressIndex.getAsync(addressString);
+            if (existing === undefined) {
+                const index = await this.#completeAddresses.lengthAsync();
+                await this.#completeAddresses.push(buffer);
+                await this.#completeAddressIndex.set(addressString, index);
+                return true;
+            } else {
+                const existingBuffer = await this.#completeAddresses.atAsync(existing);
+                if (existingBuffer && Buffer.from(existingBuffer).equals(buffer)) {
+                    return false;
+                }
+                throw new Error(`Complete address with aztec address ${addressString} but different public key or partial key already exists in memory database`);
+            }
+        });
+    }
+    getCompleteAddress(account) {
+        return this.#store.transactionAsync(async ()=>{
+            const index = await this.#completeAddressIndex.getAsync(account.toString());
+            if (index === undefined) {
+                return undefined;
+            }
+            const value = await this.#completeAddresses.atAsync(index);
+            return value ? await CompleteAddress.fromBuffer(value) : undefined;
+        });
+    }
+    getCompleteAddresses() {
+        return this.#store.transactionAsync(async ()=>{
+            return await allToCompletion((await toArray(this.#completeAddresses.valuesAsync())).map((v)=>CompleteAddress.fromBuffer(v)));
+        });
+    }
+}

package/dest/storage/address_store/index.d.ts

@@ -0,0 +1,2 @@
+export { AddressStore } from './address_store.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9zdG9yYWdlL2FkZHJlc3Nfc3RvcmUvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLG9CQUFvQixDQUFDIn0=

package/dest/storage/address_store/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/address_store/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dest/storage/address_store/index.js

@@ -0,0 +1 @@
+export { AddressStore } from './address_store.js';

package/dest/storage/allowed_scopes.d.ts

@@ -0,0 +1,6 @@
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+/**
+ * Asserts that `scope` is one of `allowedScopes`, throwing otherwise.
+ */
+export declare function assertAllowedScope(scope: AztecAddress, allowedScopes: AztecAddress[]): void;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYWxsb3dlZF9zY29wZXMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9zdG9yYWdlL2FsbG93ZWRfc2NvcGVzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSxrQ0FBa0MsQ0FBQztBQUVoRTs7R0FFRztBQUNILHdCQUFnQixrQkFBa0IsQ0FBQyxLQUFLLEVBQUUsWUFBWSxFQUFFLGFBQWEsRUFBRSxZQUFZLEVBQUUsR0FBRyxJQUFJLENBUTNGIn0=

package/dest/storage/allowed_scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowed_scopes.d.ts","sourceRoot":"","sources":["../../src/storage/allowed_scopes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAEhE;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,GAAG,IAAI,CAQ3F"}

package/dest/storage/allowed_scopes.js

@@ -0,0 +1,7 @@
+/**
+ * Asserts that `scope` is one of `allowedScopes`, throwing otherwise.
+ */ export function assertAllowedScope(scope, allowedScopes) {
+    if (!allowedScopes.some((allowed)=>allowed.equals(scope))) {
+        throw new Error(`Scope ${scope.toString()} is not in the allowed scopes list: [${allowedScopes.map((s)=>s.toString()).join(', ')}]. See https://docs.aztec.network/errors/10`);
+    }
+}

package/dest/storage/anchor_block_store/anchor_block_store.d.ts

@@ -0,0 +1,20 @@
+import type { AztecAsyncKVStore } from '@aztec-labs/kv-store';
+import { BlockHeader } from '@aztec-labs/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 declare class AnchorBlockStore {
+    #private;
+    constructor(store: AztecAsyncKVStore);
+    /**
+     * 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).
+     */
+    setHeader(header: BlockHeader): Promise<void>;
+    getBlockHeader(): Promise<BlockHeader>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYW5jaG9yX2Jsb2NrX3N0b3JlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvc3RvcmFnZS9hbmNob3JfYmxvY2tfc3RvcmUvYW5jaG9yX2Jsb2NrX3N0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLGlCQUFpQixFQUF1QixNQUFNLHNCQUFzQixDQUFDO0FBQ25GLE9BQU8sRUFBRSxXQUFXLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUVwRDs7O0dBR0c7QUFDSCxxQkFBYSxnQkFBZ0I7O0lBSTNCLFlBQVksS0FBSyxFQUFFLGlCQUFpQixFQUduQztJQUVEOzs7Ozs7T0FNRztJQUNHLFNBQVMsQ0FBQyxNQUFNLEVBQUUsV0FBVyxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FFbEQ7SUFFSyxjQUFjLElBQUksT0FBTyxDQUFDLFdBQVcsQ0FBQyxDQU0zQztDQUNGIn0=

package/dest/storage/anchor_block_store/anchor_block_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor_block_store.d.ts","sourceRoot":"","sources":["../../../src/storage/anchor_block_store/anchor_block_store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAuB,MAAM,sBAAsB,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpD;;;GAGG;AACH,qBAAa,gBAAgB;;IAI3B,YAAY,KAAK,EAAE,iBAAiB,EAGnC;IAED;;;;;;OAMG;IACG,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAElD;IAEK,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAM3C;CACF"}

package/dest/storage/anchor_block_store/anchor_block_store.js

@@ -0,0 +1,28 @@
+import { BlockHeader } from '@aztec-labs/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;
+    #synchronizedHeader;
+    constructor(store){
+        this.#store = store;
+        this.#synchronizedHeader = this.#store.openSingleton('header');
+    }
+    /**
+   * 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) {
+        await this.#synchronizedHeader.set(header.toBuffer());
+    }
+    async getBlockHeader() {
+        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/dest/storage/anchor_block_store/index.d.ts

@@ -0,0 +1,2 @@
+export { AnchorBlockStore } from './anchor_block_store.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9zdG9yYWdlL2FuY2hvcl9ibG9ja19zdG9yZS9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQyJ9

package/dest/storage/anchor_block_store/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/anchor_block_store/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dest/storage/anchor_block_store/index.js

@@ -0,0 +1 @@
+export { AnchorBlockStore } from './anchor_block_store.js';

package/dest/storage/backwards_compatibility_tests/kv_store_snapshot.d.ts

@@ -0,0 +1,42 @@
+import type { AztecAsyncArray, AztecAsyncMap, AztecAsyncSingleton, Key } from '@aztec-labs/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 declare function snapshotMap<K extends Key, V>(map: AztecAsyncMap<K, V>): Promise<MapEntry[]>;
+/**
+ * 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 declare function snapshotArray<V>(array: AztecAsyncArray<V>): Promise<ArrayEntry[]>;
+/** Returns the singleton's value rendered as a string, or `null` if unset. */
+export declare function snapshotSingleton<V>(singleton: AztecAsyncSingleton<V>): Promise<string | null>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoia3Zfc3RvcmVfc25hcHNob3QuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9zdG9yYWdlL2JhY2t3YXJkc19jb21wYXRpYmlsaXR5X3Rlc3RzL2t2X3N0b3JlX3NuYXBzaG90LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLGVBQWUsRUFBRSxhQUFhLEVBQUUsbUJBQW1CLEVBQUUsR0FBRyxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFFckc7Ozs7Ozs7Ozs7Ozs7OztHQWVHO0FBRUgsZ0ZBQWdGO0FBQ2hGLE1BQU0sTUFBTSxRQUFRLEdBQUc7SUFBRSxHQUFHLEVBQUUsTUFBTSxDQUFDO0lBQUMsS0FBSyxFQUFFLE1BQU0sQ0FBQTtDQUFFLENBQUM7QUFFdEQsMEVBQTBFO0FBQzFFLE1BQU0sTUFBTSxVQUFVLEdBQUc7SUFBRSxLQUFLLEVBQUUsTUFBTSxDQUFDO0lBQUMsS0FBSyxFQUFFLE1BQU0sQ0FBQTtDQUFFLENBQUM7QUFFMUQ7OztHQUdHO0FBQ0gsd0JBQXNCLFdBQVcsQ0FBQyxDQUFDLFNBQVMsR0FBRyxFQUFFLENBQUMsRUFBRSxHQUFHLEVBQUUsYUFBYSxDQUFDLENBQUMsRUFBRSxDQUFDLENBQUMsR0FBRyxPQUFPLENBQUMsUUFBUSxFQUFFLENBQUMsQ0FNakc7QUFFRDs7Ozs7R0FLRztBQUNILHdCQUFzQixhQUFhLENBQUMsQ0FBQyxFQUFFLEtBQUssRUFBRSxlQUFlLENBQUMsQ0FBQyxDQUFDLEdBQUcsT0FBTyxDQUFDLFVBQVUsRUFBRSxDQUFDLENBT3ZGO0FBRUQsOEVBQThFO0FBQzlFLHdCQUFzQixpQkFBaUIsQ0FBQyxDQUFDLEVBQUUsU0FBUyxFQUFFLG1CQUFtQixDQUFDLENBQUMsQ0FBQyxHQUFHLE9BQU8sQ0FBQyxNQUFNLEdBQUcsSUFBSSxDQUFDLENBR3BHIn0=

package/dest/storage/backwards_compatibility_tests/kv_store_snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv_store_snapshot.d.ts","sourceRoot":"","sources":["../../../src/storage/backwards_compatibility_tests/kv_store_snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAErG;;;;;;;;;;;;;;;GAeG;AAEH,gFAAgF;AAChF,MAAM,MAAM,QAAQ,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D;;;GAGG;AACH,wBAAsB,WAAW,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAMjG;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAOvF;AAED,8EAA8E;AAC9E,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,SAAS,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGpG"}

package/dest/storage/backwards_compatibility_tests/kv_store_snapshot.js

@@ -0,0 +1,93 @@
+/**
+ * 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(map) {
+    const entries = [];
+    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(array) {
+    const entries = [];
+    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(singleton) {
+    const value = await singleton.getAsync();
+    return value === undefined ? null : valueToString(value);
+}
+function compareMapEntries(a, b) {
+    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) {
+    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) {
+    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.toBuffer === 'function') {
+        return v.toBuffer().toString('hex');
+    }
+    return JSON.stringify(v);
+}

package/dest/storage/backwards_compatibility_tests/schema_tests.d.ts

@@ -0,0 +1,15 @@
+import type { AztecAsyncKVStore } from '@aztec-labs/kv-store';
+/**
+ * Template of a specific store's backwards compatibility checks.
+ *
+ * 1. `name` is the store's name (`AddressStore`, `NoteStore`, etc).
+ * 2. `writeToStore` drives writes through each store's own production API (`addNote`, `setCapsule`, etc).
+ * 3. `snapshotStore` re-opens the underlying kv-stores by name (raw) and renders them as snapshots.
+ */
+export type SchemaTest = {
+    name: string;
+    writeToStore: (kvStore: AztecAsyncKVStore) => Promise<void>;
+    snapshotStore: (kvStore: AztecAsyncKVStore) => Promise<Record<string, unknown>>;
+};
+export declare const SCHEMA_TESTS: readonly SchemaTest[];
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2NoZW1hX3Rlc3RzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvc3RvcmFnZS9iYWNrd2FyZHNfY29tcGF0aWJpbGl0eV90ZXN0cy9zY2hlbWFfdGVzdHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBUUEsT0FBTyxLQUFLLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQTBDOUQ7Ozs7OztHQU1HO0FBQ0gsTUFBTSxNQUFNLFVBQVUsR0FBRztJQUN2QixJQUFJLEVBQUUsTUFBTSxDQUFDO0lBQ2IsWUFBWSxFQUFFLENBQUMsT0FBTyxFQUFFLGlCQUFpQixLQUFLLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUM1RCxhQUFhLEVBQUUsQ0FBQyxPQUFPLEVBQUUsaUJBQWlCLEtBQUssT0FBTyxDQUFDLE1BQU0sQ0FBQyxNQUFNLEVBQUUsT0FBTyxDQUFDLENBQUMsQ0FBQztDQUNqRixDQUFDO0FBRUYsZUFBTyxNQUFNLFlBQVksRUFBRSxTQUFTLFVBQVUsRUFxbUI3QyxDQUFDIn0=

package/dest/storage/backwards_compatibility_tests/schema_tests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema_tests.d.ts","sourceRoot":"","sources":["../../../src/storage/backwards_compatibility_tests/schema_tests.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AA0C9D;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,aAAa,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACjF,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAqmB7C,CAAC"}