@aztec/foundation 0.0.1-commit.b655e406 → 0.0.1-commit.c0b82b2

package/dest/trees/unbalanced_merkle_tree_root.js

@@ -0,0 +1,84 @@
+import { computeBalancedMerkleTreeRoot, computeBalancedMerkleTreeRootAsync } from './balanced_merkle_tree_root.js';
+import { poseidonMerkleHash, shaMerkleHash } from './hasher.js';
+import { UnbalancedMerkleTreeCalculator } from './unbalanced_merkle_tree_calculator.js';
+export const computeUnbalancedShaRoot = (leaves)=>computeUnbalancedMerkleTreeRoot(leaves, shaMerkleHash);
+export const computeUnbalancedPoseidonRoot = async (leaves)=>await computeUnbalancedMerkleTreeRootAsync(leaves, poseidonMerkleHash);
+export const computeWonkyShaRoot = (leaves)=>computeWonkyMerkleTreeRoot(leaves);
+/**
+ * Computes the Merkle root of an unbalanced tree.
+ *
+ * Unlike a balanced Merkle tree, which requires the number of leaves to be a power of two, an unbalanced tree can have
+ * any number of leaves.
+ *
+ * The tree is constructed by iteratively extracting the smallest power-of-two-sized subtrees from **right to left**.
+ * For each such subtree, it computes the subtree root and then combines all subtree roots (again from right to left)
+ * into a single root using the provided hash function.
+ *
+ * Note: We need the final tree to be as shallow as possible, to minimize the size of the sibling path required to prove
+ * membership of a leaf. Therefor, the computation proceeds from right to left - smaller subtrees must always be
+ * combined before being merged with a larger sibling on their left.
+ *
+ * For example, consider an unbalanced tree made of three subtrees of sizes 2, 4, and 8. If we combine the size-2 and
+ * size-4 subtrees first (producing a subtree of depth 3), and then merge it with the size-8 subtree (also depth 3), the
+ * resulting tree has a maximum depth of 4.
+ *
+ * But if we instead combine the size-4 and size-8 subtrees first (depth 4), and then merge with the size-2 subtree
+ * (depth 1), the final tree has a depth of 5.
+ */ export function computeUnbalancedMerkleTreeRoot(leaves, hasher = shaMerkleHash, emptyRoot = Buffer.alloc(32)) {
+    if (!leaves.length) {
+        return emptyRoot;
+    }
+    if (leaves.length === 1) {
+        return leaves[0];
+    }
+    let numRemainingLeaves = leaves.length;
+    let subtreeSize = 1;
+    let root;
+    while(numRemainingLeaves > 1){
+        if ((numRemainingLeaves & subtreeSize) !== 0) {
+            const subtreeLeaves = leaves.slice(numRemainingLeaves - subtreeSize, numRemainingLeaves);
+            const subtreeRoot = computeBalancedMerkleTreeRoot(subtreeLeaves, hasher);
+            if (!root) {
+                root = subtreeRoot;
+            } else {
+                root = hasher(subtreeRoot, root);
+            }
+            numRemainingLeaves -= subtreeSize;
+        }
+        subtreeSize *= 2;
+    }
+    return root;
+}
+export async function computeUnbalancedMerkleTreeRootAsync(leaves, hasher = poseidonMerkleHash, emptyRoot = Buffer.alloc(32)) {
+    if (!leaves.length) {
+        return emptyRoot;
+    }
+    if (leaves.length === 1) {
+        return leaves[0];
+    }
+    let numRemainingLeaves = leaves.length;
+    let subtreeSize = 1;
+    let root;
+    while(numRemainingLeaves > 1){
+        if ((numRemainingLeaves & subtreeSize) !== 0) {
+            const subtreeLeaves = leaves.slice(numRemainingLeaves - subtreeSize, numRemainingLeaves);
+            const subtreeRoot = await computeBalancedMerkleTreeRootAsync(subtreeLeaves, hasher);
+            if (!root) {
+                root = subtreeRoot;
+            } else {
+                root = await hasher(subtreeRoot, root);
+            }
+            numRemainingLeaves -= subtreeSize;
+        }
+        subtreeSize *= 2;
+    }
+    return root;
+}
+// A **wonky** tree is a "compressed" unbalanced Merkle tree.
+// It is constructed in the same way as an unbalanced tree: by first creating the largest possible left subtree, with
+// the remaining leaves forming a right subtree that follows the same process recursively.
+// During construction, leaves equal to `valueToCompress` are skipped (compressed) and do not contribute to the tree.
+export function computeWonkyMerkleTreeRoot(leaves, valueToCompress = Buffer.alloc(32), emptyRoot = Buffer.alloc(32), hasher = shaMerkleHash) {
+    const calculator = UnbalancedMerkleTreeCalculator.create(leaves, valueToCompress, emptyRoot, hasher);
+    return calculator.getRoot();
+}

package/dest/trees/unbalanced_tree_store.d.ts

@@ -17,4 +17,8 @@ export declare class UnbalancedTreeStore<T> {
     getSibling(location: TreeNodeLocation): T | undefined;
     getChildren(location: TreeNodeLocation): [T | undefined, T | undefined];
 }
-//# sourceMappingURL=unbalanced_tree_store.d.ts.map
+export declare function findLeafLevelAndIndex(numLeaves: number, leafIndex: number): {
+    level: number;
+    indexAtLevel: number;
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidW5iYWxhbmNlZF90cmVlX3N0b3JlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdHJlZXMvdW5iYWxhbmNlZF90cmVlX3N0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE1BQU0sV0FBVyxnQkFBZ0I7SUFDL0IsS0FBSyxFQUFFLE1BQU0sQ0FBQztJQUNkLEtBQUssRUFBRSxNQUFNLENBQUM7Q0FDZjtBQU9ELHFCQUFhLG1CQUFtQixDQUFDLENBQUM7O0lBSWhDLFlBQVksU0FBUyxFQUFFLE1BQU0sRUFFNUI7SUFFRCxPQUFPLENBQUMsU0FBUyxFQUFFLE1BQU0sRUFBRSxLQUFLLEVBQUUsQ0FBQyxHQUFHLGdCQUFnQixDQWVyRDtJQUVELE9BQU8sQ0FBQyxFQUFFLEtBQUssRUFBRSxLQUFLLEVBQUUsRUFBRSxnQkFBZ0IsRUFBRSxLQUFLLEVBQUUsQ0FBQyxRQVNuRDtJQUVELGlCQUFpQixDQUFDLEVBQUUsS0FBSyxFQUFFLEtBQUssRUFBRSxFQUFFLGdCQUFnQixHQUFHLGdCQUFnQixDQU10RTtJQUVELGtCQUFrQixDQUFDLEVBQUUsS0FBSyxFQUFFLEtBQUssRUFBRSxFQUFFLGdCQUFnQixHQUFHLGdCQUFnQixDQU12RTtJQUVELGlCQUFpQixDQUFDLEVBQUUsS0FBSyxFQUFFLEtBQUssRUFBRSxFQUFFLGdCQUFnQixHQUFHLENBQUMsZ0JBQWdCLEVBQUUsZ0JBQWdCLENBQUMsQ0FJMUY7SUFFRCxPQUFPLENBQUMsU0FBUyxFQUFFLE1BQU0sR0FBRyxDQUFDLEdBQUcsU0FBUyxDQU94QztJQUVELE9BQU8sQ0FBQyxRQUFRLEVBQUUsZ0JBQWdCLEdBQUcsQ0FBQyxHQUFHLFNBQVMsQ0FFakQ7SUFFRCxPQUFPLElBQUksQ0FBQyxHQUFHLFNBQVMsQ0FFdkI7SUFFRCxTQUFTLENBQUMsUUFBUSxFQUFFLGdCQUFnQixHQUFHLENBQUMsR0FBRyxTQUFTLENBR25EO0lBRUQsVUFBVSxDQUFDLFFBQVEsRUFBRSxnQkFBZ0IsR0FBRyxDQUFDLEdBQUcsU0FBUyxDQUdwRDtJQUVELFdBQVcsQ0FBQyxRQUFRLEVBQUUsZ0JBQWdCLEdBQUcsQ0FBQyxDQUFDLEdBQUcsU0FBUyxFQUFFLENBQUMsR0FBRyxTQUFTLENBQUMsQ0FHdEU7Q0FLRjtBQXNERCx3QkFBZ0IscUJBQXFCLENBQUMsU0FBUyxFQUFFLE1BQU0sRUFBRSxTQUFTLEVBQUUsTUFBTTs7O0VBR3pFIn0=

package/dest/trees/unbalanced_tree_store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unbalanced_tree_store.d.ts","sourceRoot":"","sources":["../../src/trees/unbalanced_tree_store.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAOD,qBAAa,mBAAmB,CAAC,CAAC;;gBAIpB,SAAS,EAAE,MAAM;IAI7B,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,gBAAgB;IAiBtD,OAAO,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC;IAWpD,iBAAiB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,gBAAgB,GAAG,gBAAgB;IAQvE,kBAAkB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,gBAAgB,GAAG,gBAAgB;IAQxE,iBAAiB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,gBAAgB,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAM3F,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IASzC,OAAO,CAAC,QAAQ,EAAE,gBAAgB,GAAG,CAAC,GAAG,SAAS;IAIlD,OAAO,IAAI,CAAC,GAAG,SAAS;IAIxB,SAAS,CAAC,QAAQ,EAAE,gBAAgB,GAAG,CAAC,GAAG,SAAS;IAKpD,UAAU,CAAC,QAAQ,EAAE,gBAAgB,GAAG,CAAC,GAAG,SAAS;IAKrD,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,CAAC,CAAC,GAAG,SAAS,EAAE,CAAC,GAAG,SAAS,CAAC;CAQxE"}
+{"version":3,"file":"unbalanced_tree_store.d.ts","sourceRoot":"","sources":["../../src/trees/unbalanced_tree_store.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAOD,qBAAa,mBAAmB,CAAC,CAAC;;IAIhC,YAAY,SAAS,EAAE,MAAM,EAE5B;IAED,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,gBAAgB,CAerD;IAED,OAAO,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC,QASnD;IAED,iBAAiB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,gBAAgB,GAAG,gBAAgB,CAMtE;IAED,kBAAkB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,gBAAgB,GAAG,gBAAgB,CAMvE;IAED,iBAAiB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,gBAAgB,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAI1F;IAED,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAOxC;IAED,OAAO,CAAC,QAAQ,EAAE,gBAAgB,GAAG,CAAC,GAAG,SAAS,CAEjD;IAED,OAAO,IAAI,CAAC,GAAG,SAAS,CAEvB;IAED,SAAS,CAAC,QAAQ,EAAE,gBAAgB,GAAG,CAAC,GAAG,SAAS,CAGnD;IAED,UAAU,CAAC,QAAQ,EAAE,gBAAgB,GAAG,CAAC,GAAG,SAAS,CAGpD;IAED,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,CAAC,CAAC,GAAG,SAAS,EAAE,CAAC,GAAG,SAAS,CAAC,CAGtE;CAKF;AAsDD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;;;EAGzE"}

package/dest/trees/unbalanced_tree_store.js

@@ -1,4 +1,3 @@
-import { findLeafLevelAndIndex } from './unbalanced_merkle_tree.js';
 export class UnbalancedTreeStore {
     #nodeMapping = new Map();
     #numLeaves;
@@ -98,3 +97,52 @@ export class UnbalancedTreeStore {
         return `${location.level}-${location.index}`;
     }
 }
+/// Get the depth of the maximum balanced tree that can be created with the given number of leaves. The subtree will be
+/// the left most subtree of the unbalanced tree with a total of `numLeaves` leaves.
+///
+/// Note: All the leaves may not be used to form the tree. For example, if there are 5 leaves, the maximum depth is 2,
+/// only 4 leaves are used to form a balanced tree.
+function getMaxBalancedSubtreeDepth(numLeaves) {
+    return Math.floor(Math.log2(numLeaves));
+}
+/// Get the maximum depth of an unbalanced tree that can be created with the given number of leaves.
+function getMaxUnbalancedTreeDepth(numLeaves) {
+    return Math.ceil(Math.log2(numLeaves));
+}
+function findPosition(rootLevel, leafLevel, numLeaves, indexOffset, targetIndex) {
+    if (numLeaves <= 1) {
+        // Single leaf.
+        return {
+            level: rootLevel,
+            indexAtLevel: indexOffset
+        };
+    }
+    // The largest balanced tree that can be created with the given number of leaves.
+    const maxBalancedTreeDepth = getMaxBalancedSubtreeDepth(numLeaves);
+    const numBalancedLeaves = 2 ** maxBalancedTreeDepth;
+    const numRemainingLeaves = numLeaves - numBalancedLeaves;
+    if (targetIndex < numBalancedLeaves) {
+        // Target is in the balanced tree.
+        // - If numRemainingLeaves is 0: this balanced tree is grown from the current root.
+        // - If numRemainingLeaves is not 0: the remaining leaves will form another tree, which will become the right child of the root.
+        //   And the balanced tree will be the left child of the root.
+        //   There will be an extra level between the root of the balanced tree and the current root.
+        const extraLevel = numRemainingLeaves ? 1 : 0;
+        return {
+            level: rootLevel + maxBalancedTreeDepth + extraLevel,
+            indexAtLevel: indexOffset + targetIndex
+        };
+    } else {
+        // Target is in the right branch.
+        const rightBranchMaxLevel = getMaxUnbalancedTreeDepth(numRemainingLeaves);
+        const shiftedUp = leafLevel - rootLevel - rightBranchMaxLevel - 1;
+        const nextLeafLevel = leafLevel - shiftedUp;
+        const newIndexOffset = indexOffset + numBalancedLeaves >> shiftedUp;
+        const shiftedTargetIndex = targetIndex - numBalancedLeaves;
+        return findPosition(rootLevel + 1, nextLeafLevel, numRemainingLeaves, newIndexOffset, shiftedTargetIndex);
+    }
+}
+export function findLeafLevelAndIndex(numLeaves, leafIndex) {
+    const maxLevel = getMaxUnbalancedTreeDepth(numLeaves);
+    return findPosition(0, maxLevel, numLeaves, 0, leafIndex);
+}

package/dest/types/index.d.ts

@@ -14,6 +14,10 @@ export type Writeable<T> = {
 };
 /** Removes readonly modifiers for an object. */
 export declare function unfreeze<T>(obj: T): Writeable<T>;
+/** Is defined type guard */
+export declare function isDefined<T>(value: T | undefined): value is T;
+/** Type guard for error classes */
+export declare function isErrorClass<T extends Error>(value: unknown, errorClass: new (...args: any[]) => T): value is T;
 /** Resolves a record-like type. Lifted from viem. */
 export type Prettify<T> = {
     [K in keyof T]: T[K];
@@ -22,7 +26,7 @@ export type Prettify<T> = {
  * Type-safe Event Emitter type
  * @example
  * export type ArchiverEmitter = TypedEventEmitter<{
- *  [L2BlockSourceEvents.L2PruneDetected]: (args: L2BlockSourceEvent) => void;
+ *  [L2BlockSourceEvents.L2PruneUnproven]: (args: L2BlockSourceEvent) => void;
  *  [L2BlockSourceEvents.L2BlockProven]: (args: L2BlockSourceEvent) => void;
  * }>;
  * class Archiver extends (EventEmitter as new () => ArchiverEmitter) {
@@ -39,4 +43,4 @@ export interface TypedEventEmitter<TEventMap extends {
     removeListener<K extends keyof TEventMap>(event: K, listener: TEventMap[K]): this;
     removeAllListeners<K extends keyof TEventMap>(event: K): this;
 }
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy90eXBlcy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxnQ0FBZ0M7QUFDaEMsTUFBTSxNQUFNLFFBQVEsQ0FBQyxDQUFDLElBQUk7S0FDdkIsQ0FBQyxJQUFJLE1BQU0sQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDLENBQUMsU0FBUyxRQUFRLEdBQUcsS0FBSyxHQUFHLENBQUMsR0FBRyxDQUFDLENBQUMsQ0FBQyxDQUFDO0NBQzFELENBQUM7QUFFRixrQ0FBa0M7QUFDbEMsTUFBTSxNQUFNLFdBQVcsQ0FBQyxDQUFDLElBQUk7S0FDMUIsQ0FBQyxJQUFJLE1BQU0sQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDLENBQUMsU0FBUyxRQUFRLEdBQUcsQ0FBQyxHQUFHLEtBQUssR0FBRyxDQUFDLENBQUMsQ0FBQyxDQUFDO0NBQzFELENBQUM7QUFFRix1REFBdUQ7QUFDdkQsTUFBTSxNQUFNLFNBQVMsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxTQUFTLE1BQU0sQ0FBQyxJQUFJLElBQUksQ0FBQyxDQUFDLEVBQUUsQ0FBQyxDQUFDLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFDLEVBQUUsQ0FBQyxDQUFDLENBQUMsQ0FBQztBQUUvRSw2Q0FBNkM7QUFDN0MsTUFBTSxNQUFNLFNBQVMsQ0FBQyxDQUFDLElBQUk7SUFBRSxDQUFDLFVBQVUsQ0FBQyxJQUFJLE1BQU0sQ0FBQyxHQUFHLENBQUMsQ0FBQyxDQUFDLENBQUM7Q0FBRSxDQUFDO0FBRTlELGdEQUFnRDtBQUNoRCx3QkFBZ0IsUUFBUSxDQUFDLENBQUMsRUFBRSxHQUFHLEVBQUUsQ0FBQyxHQUFHLFNBQVMsQ0FBQyxDQUFDLENBQUMsQ0FFaEQ7QUFFRCw0QkFBNEI7QUFDNUIsd0JBQWdCLFNBQVMsQ0FBQyxDQUFDLEVBQUUsS0FBSyxFQUFFLENBQUMsR0FBRyxTQUFTLEdBQUcsS0FBSyxJQUFJLENBQUMsQ0FFN0Q7QUFFRCxtQ0FBbUM7QUFDbkMsd0JBQWdCLFlBQVksQ0FBQyxDQUFDLFNBQVMsS0FBSyxFQUFFLEtBQUssRUFBRSxPQUFPLEVBQUUsVUFBVSxFQUFFLEtBQUssR0FBRyxJQUFJLEVBQUUsR0FBRyxFQUFFLEtBQUssQ0FBQyxHQUFHLEtBQUssSUFBSSxDQUFDLENBRS9HO0FBRUQscURBQXFEO0FBQ3JELE1BQU0sTUFBTSxRQUFRLENBQUMsQ0FBQyxJQUFJO0tBQ3ZCLENBQUMsSUFBSSxNQUFNLENBQUMsR0FBRyxDQUFDLENBQUMsQ0FBQyxDQUFDO0NBQ3JCLEdBQUcsRUFBRSxDQUFDO0FBRVA7Ozs7Ozs7Ozs7R0FVRztBQUNILE1BQU0sV0FBVyxpQkFBaUIsQ0FBQyxTQUFTLFNBQVM7S0FBRyxHQUFHLElBQUksTUFBTSxTQUFTLEdBQUcsQ0FBQyxHQUFHLElBQUksRUFBRSxHQUFHLEVBQUUsS0FBSyxJQUFJO0NBQUU7SUFDekcsSUFBSSxDQUFDLENBQUMsU0FBUyxNQUFNLFNBQVMsRUFBRSxLQUFLLEVBQUUsQ0FBQyxFQUFFLFFBQVEsRUFBRSxTQUFTLENBQUMsQ0FBQyxDQUFDLEdBQUcsSUFBSSxDQUFDO0lBQ3hFLEVBQUUsQ0FBQyxDQUFDLFNBQVMsTUFBTSxTQUFTLEVBQUUsS0FBSyxFQUFFLENBQUMsRUFBRSxRQUFRLEVBQUUsU0FBUyxDQUFDLENBQUMsQ0FBQyxHQUFHLElBQUksQ0FBQztJQUN0RSxHQUFHLENBQUMsQ0FBQyxTQUFTLE1BQU0sU0FBUyxFQUFFLEtBQUssRUFBRSxDQUFDLEVBQUUsUUFBUSxFQUFFLFNBQVMsQ0FBQyxDQUFDLENBQUMsR0FBRyxJQUFJLENBQUM7SUFDdkUsSUFBSSxDQUFDLENBQUMsU0FBUyxNQUFNLFNBQVMsRUFBRSxLQUFLLEVBQUUsQ0FBQyxFQUFFLEdBQUcsSUFBSSxFQUFFLFVBQVUsQ0FBQyxTQUFTLENBQUMsQ0FBQyxDQUFDLENBQUMsR0FBRyxPQUFPLENBQUM7SUFDdEYsY0FBYyxDQUFDLENBQUMsU0FBUyxNQUFNLFNBQVMsRUFBRSxLQUFLLEVBQUUsQ0FBQyxFQUFFLFFBQVEsRUFBRSxTQUFTLENBQUMsQ0FBQyxDQUFDLEdBQUcsSUFBSSxDQUFDO0lBQ2xGLGtCQUFrQixDQUFDLENBQUMsU0FBUyxNQUFNLFNBQVMsRUFBRSxLQUFLLEVBQUUsQ0FBQyxHQUFHLElBQUksQ0FBQztDQUUvRCJ9

package/dest/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KACvB,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,QAAQ,GAAG,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAC1D,CAAC;AAEF,kCAAkC;AAClC,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;KAC1B,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,QAAQ,GAAG,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;CAC1D,CAAC;AAEF,uDAAuD;AACvD,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAE/E,6CAA6C;AAC7C,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IAAE,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAE9D,gDAAgD;AAChD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAEhD;AAED,qDAAqD;AACrD,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KACvB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACrB,GAAG,EAAE,CAAC;AAEP;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB,CAAC,SAAS,SAAS;KAAG,GAAG,IAAI,MAAM,SAAS,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI;CAAE;IACzG,IAAI,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACxE,EAAE,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACtE,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACvE,IAAI,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IACtF,cAAc,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAClF,kBAAkB,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CAE/D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KACvB,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,QAAQ,GAAG,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAC1D,CAAC;AAEF,kCAAkC;AAClC,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;KAC1B,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,QAAQ,GAAG,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;CAC1D,CAAC;AAEF,uDAAuD;AACvD,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAE/E,6CAA6C;AAC7C,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IAAE,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAE9D,gDAAgD;AAChD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAEhD;AAED,4BAA4B;AAC5B,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,GAAG,KAAK,IAAI,CAAC,CAE7D;AAED,mCAAmC;AACnC,wBAAgB,YAAY,CAAC,CAAC,SAAS,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,CAE/G;AAED,qDAAqD;AACrD,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KACvB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACrB,GAAG,EAAE,CAAC;AAEP;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB,CAAC,SAAS,SAAS;KAAG,GAAG,IAAI,MAAM,SAAS,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI;CAAE;IACzG,IAAI,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACxE,EAAE,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACtE,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACvE,IAAI,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IACtF,cAAc,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAClF,kBAAkB,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CAE/D"}

package/dest/types/index.js

@@ -1,3 +1,9 @@
 /** Strips methods of a type. */ /** Removes readonly modifiers for an object. */ export function unfreeze(obj) {
     return obj;
 }
+/** Is defined type guard */ export function isDefined(value) {
+    return value !== undefined;
+}
+/** Type guard for error classes */ export function isErrorClass(value, errorClass) {
+    return value instanceof errorClass || value instanceof Error && value.name === errorClass.name;
+}

package/dest/url/index.d.ts

@@ -6,4 +6,4 @@
  * @api public
  */
 export declare function fileURLToPath(uri: string): string;
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy91cmwvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBbUJBOzs7Ozs7R0FNRztBQUVILHdCQUFnQixhQUFhLENBQUMsR0FBRyxFQUFFLE1BQU0sR0FBRyxNQUFNLENBNENqRCJ9

package/dest/validation/index.d.ts

@@ -6,4 +6,4 @@ export declare function required<T>(value: T | undefined, errMsg?: string): T;
  * @param err - Error message to throw if x isn't met.
  */
 export declare function assert(x: any, err: string): asserts x;
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy92YWxpZGF0aW9uL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLHlFQUF5RTtBQUN6RSx3QkFBZ0IsUUFBUSxDQUFDLENBQUMsRUFBRSxLQUFLLEVBQUUsQ0FBQyxHQUFHLFNBQVMsRUFBRSxNQUFNLENBQUMsRUFBRSxNQUFNLEdBQUcsQ0FBQyxDQUtwRTtBQUVEOzs7O0dBSUc7QUFDSCx3QkFBZ0IsTUFBTSxDQUFDLENBQUMsRUFBRSxHQUFHLEVBQUUsR0FBRyxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsQ0FBQyxDQUlyRCJ9

package/package.json

@@ -1,9 +1,29 @@
 {
   "name": "@aztec/foundation",
-  "version": "0.0.1-commit.b655e406",
+  "version": "0.0.1-commit.c0b82b2",
   "type": "module",
   "main": "./dest/index.js",
   "types": "./dest/index.d.ts",
+  "typedocOptions": {
+    "entryPoints": [
+      "./src/buffer/index.ts",
+      "./src/collection/index.ts",
+      "./src/config/index.ts",
+      "./src/crypto/random/index.ts",
+      "./src/error/index.ts",
+      "./src/eth-address/index.ts",
+      "./src/json-rpc/index.ts",
+      "./src/log/index.ts",
+      "./src/retry/index.ts",
+      "./src/schemas/index.ts",
+      "./src/serialize/index.ts",
+      "./src/sleep/index.ts",
+      "./src/timer/index.ts",
+      "./src/types/index.ts"
+    ],
+    "name": "Foundation",
+    "tsconfig": "./tsconfig.json"
+  },
   "exports": {
     "./eslint": "./eslint.config.js",
     "./eslint.docs": "./eslint.config.docs.js",
@@ -12,11 +32,30 @@
     "./async-map": "./dest/async-map/index.js",
     "./async-pool": "./dest/async-pool/index.js",
     "./bigint": "./dest/bigint/index.js",
+    "./branded-types": "./dest/branded-types/index.js",
     "./collection": "./dest/collection/index.js",
     "./config": "./dest/config/index.js",
-    "./crypto": "./dest/crypto/index.js",
-    "./crypto/sync": "./dest/crypto/sync/index.js",
+    "./crypto/aes128": "./dest/crypto/aes128/index.js",
+    "./crypto/bls": "./dest/crypto/bls/index.js",
     "./crypto/bls/bn254_keystore": "./dest/crypto/bls/bn254_keystore.js",
+    "./crypto/bn254": "./dest/crypto/bn254/index.js",
+    "./crypto/ecdsa": "./dest/crypto/ecdsa/index.js",
+    "./crypto/grumpkin": "./dest/crypto/grumpkin/index.js",
+    "./crypto/keccak": "./dest/crypto/keccak/index.js",
+    "./crypto/keys": "./dest/crypto/keys/index.js",
+    "./crypto/pedersen": "./dest/crypto/pedersen/index.js",
+    "./crypto/poseidon": "./dest/crypto/poseidon/index.js",
+    "./crypto/random": "./dest/crypto/random/index.js",
+    "./crypto/schnorr": "./dest/crypto/schnorr/index.js",
+    "./crypto/secp256k1": "./dest/crypto/secp256k1/index.js",
+    "./crypto/secp256k1-signer": "./dest/crypto/secp256k1-signer/index.js",
+    "./crypto/sha256": "./dest/crypto/sha256/index.js",
+    "./crypto/sha512": "./dest/crypto/sha512/index.js",
+    "./crypto/signature": "./dest/crypto/signature/index.js",
+    "./crypto/sync": "./dest/crypto/sync/index.js",
+    "./curves/bn254": "./dest/curves/bn254/index.js",
+    "./curves/grumpkin": "./dest/curves/grumpkin/index.js",
+    "./curves/bls12": "./dest/curves/bls12/index.js",
     "./decorators": "./dest/decorators/index.js",
     "./error": "./dest/error/index.js",
     "./eth-address": "./dest/eth-address/index.js",
@@ -30,9 +69,10 @@
     "./json-rpc/undici": "./dest/json-rpc/client/undici.js",
     "./json-rpc/test": "./dest/json-rpc/test/index.js",
     "./iterable": "./dest/iterable/index.js",
+    "./iterator": "./dest/iterator/index.js",
     "./log": "./dest/log/index.js",
+    "./log/server": "./dest/log/pino-logger-server.js",
     "./mutex": "./dest/mutex/index.js",
-    "./fields": "./dest/fields/index.js",
     "./retry": "./dest/retry/index.js",
     "./running-promise": "./dest/running-promise/index.js",
     "./serialize": "./dest/serialize/index.js",
@@ -57,8 +97,8 @@
     "./number": "./dest/number/index.js"
   },
   "scripts": {
-    "build": "yarn clean && tsc -b",
-    "build:dev": "tsc -b --watch",
+    "build": "yarn clean && ../scripts/tsc.sh",
+    "build:dev": "../scripts/tsc.sh --watch",
     "clean": "rm -rf ./dest .tsbuildinfo",
     "generate": "true",
     "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
@@ -104,7 +144,7 @@
     "testEnvironment": "../../foundation/src/jest/env.mjs"
   },
   "dependencies": {
-    "@aztec/bb.js": "0.0.1-commit.b655e406",
+    "@aztec/bb.js": "0.0.1-commit.c0b82b2",
     "@koa/cors": "^5.0.0",
     "@noble/curves": "=1.7.0",
     "@noble/hashes": "^1.6.1",
@@ -143,10 +183,11 @@
     "@types/node": "^22.15.17",
     "@types/pako": "^2.0.0",
     "@types/supertest": "^2.0.12",
+    "@typescript/native-preview": "7.0.0-dev.20260113.1",
     "comlink": "^4.4.1",
     "eslint": "^9.26.0",
     "eslint-config-prettier": "^10.1.5",
-    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-import-x": "^4.6.1",
     "eslint-plugin-jsdoc": "^50.6.14",
     "eslint-plugin-no-only-tests": "^3.3.0",
     "eslint-plugin-tsdoc": "^0.4.0",
@@ -157,7 +198,7 @@
     "ts-node": "^10.9.1",
     "typescript": "^5.3.3",
     "typescript-eslint": "^8.32.1",
-    "viem": "npm:@spalladino/viem@2.38.2-eip7594.0"
+    "viem": "npm:@aztec/viem@2.38.2"
   },
   "files": [
     "dest",

package/src/array/array.ts

@@ -42,22 +42,6 @@ export async function makeTupleAsync<T, N extends number>(length: N, fn: (i: num
   )) as Tuple<T, N>;
 }
 
-/**
- * Create an array over an integer range, filled with a function 'fn'. However, the latter half of the array are set to zeros.
- * see `makeTuple` above.
- * @param n - The number of integers.
- * @param fn - The generator function.
- * @returns The array of numbers.
- */
-export function makeHalfFullTuple<T, N extends number>(
-  length: N,
-  fn: (i: number) => T,
-  offset = 0,
-  makeEmpty: () => T,
-) {
-  return Array.from({ length }, (_: any, i: number) => (i < length / 2 ? fn(i + offset) : makeEmpty())) as Tuple<T, N>;
-}
-
 /**
  * Assert a member of an object is a certain length.
  * @param obj - An object.

package/src/array/index.ts

@@ -1 +1,2 @@
 export * from './array.js';
+export * from './sorted_array.js';

package/src/array/sorted_array.ts

@@ -0,0 +1,138 @@
+type Cmp<T> = (a: T, b: T) => -1 | 0 | 1;
+
+export function dedupeSortedArray<T>(arr: T[], cmp: Cmp<T>): void {
+  for (let i = 0; i < arr.length; i++) {
+    let j = i + 1;
+    for (; j < arr.length; j++) {
+      const res = cmp(arr[i], arr[j]);
+      if (res === 0) {
+        continue;
+      } else if (res < 0) {
+        break;
+      } else {
+        throw new Error('Array not sorted');
+      }
+    }
+
+    if (j - i > 1) {
+      arr.splice(i + 1, j - i - 1);
+    }
+  }
+}
+
+export function insertIntoSortedArray<T>(arr: T[], item: T, cmp: Cmp<T>, allowDuplicates = true): boolean {
+  const index = findInsertionIndexInSortedArray(arr, item, cmp);
+
+  if (!allowDuplicates) {
+    // Check element before insertion point (upper bound returns index after equal elements)
+    if (index > 0 && cmp(arr[index - 1], item) === 0) {
+      return false;
+    }
+  }
+
+  arr.splice(index, 0, item);
+  return true;
+}
+
+/**
+ * Finds the index where needle would be inserted to maintain sorted order.
+ * Returns the count of elements less than or equal to needle.
+ */
+export function findInsertionIndexInSortedArray<T, N>(values: T[], needle: N, cmp: (a: T, b: N) => number): number {
+  let start = 0;
+  let end = values.length;
+
+  while (start < end) {
+    const mid = start + (((end - start) / 2) | 0);
+    const comparison = cmp(values[mid], needle);
+
+    if (comparison <= 0) {
+      start = mid + 1;
+    } else {
+      end = mid;
+    }
+  }
+
+  return start;
+}
+
+export function findIndexInSortedArray<T, N>(values: T[], needle: N, cmp: (a: T, b: N) => number): number {
+  let start = 0;
+  let end = values.length - 1;
+
+  while (start <= end) {
+    const mid = start + (((end - start) / 2) | 0);
+    const comparison = cmp(values[mid], needle);
+
+    if (comparison === 0) {
+      return mid;
+    }
+
+    if (comparison > 0) {
+      end = mid - 1;
+    } else {
+      start = mid + 1;
+    }
+  }
+
+  return -1;
+}
+
+export function findInSortedArray<T, N>(values: T[], needle: N, cmp: (a: T, b: N) => number): T | undefined {
+  const idx = findIndexInSortedArray(values, needle, cmp);
+  return idx > -1 ? values[idx] : undefined;
+}
+
+export function removeAnyOf<T, N>(arr: T[], vals: N[], cmp: (a: T, b: N) => -1 | 0 | 1): void {
+  let writeIdx = 0;
+  let readIdx = 0;
+  let valIdx = 0;
+
+  while (readIdx < arr.length && valIdx < vals.length) {
+    const comparison = cmp(arr[readIdx], vals[valIdx]);
+
+    if (comparison < 0) {
+      arr[writeIdx++] = arr[readIdx++];
+    } else if (comparison > 0) {
+      valIdx++;
+    } else {
+      readIdx++;
+    }
+  }
+
+  while (readIdx < arr.length) {
+    arr[writeIdx++] = arr[readIdx++];
+  }
+
+  arr.length = writeIdx;
+}
+
+export function removeFromSortedArray<T, N>(arr: T[], val: N, cmp: (a: T, b: N) => -1 | 0 | 1) {
+  const idx = findIndexInSortedArray(arr, val, cmp);
+  if (idx > -1) {
+    arr.splice(idx, 1);
+  }
+}
+
+export function merge<T>(arr: T[], toInsert: T[], cmp: (a: T, b: T) => -1 | 0 | 1): void {
+  const result = new Array<T>(arr.length + toInsert.length);
+  let i = 0,
+    j = 0,
+    k = 0;
+
+  while (i < arr.length && j < toInsert.length) {
+    result[k++] = cmp(arr[i], toInsert[j]) <= 0 ? arr[i++] : toInsert[j++];
+  }
+
+  while (i < arr.length) {
+    result[k++] = arr[i++];
+  }
+  while (j < toInsert.length) {
+    result[k++] = toInsert[j++];
+  }
+
+  for (i = 0; i < result.length; i++) {
+    arr[i] = result[i];
+  }
+  arr.length = result.length;
+}

package/src/branded-types/block_number.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+
+import type { CheckpointNumber } from './checkpoint_number.js';
+import type { Branded } from './types.js';
+
+/**
+ * A branded type representing an Aztec (L2) block number.
+ * Block numbers are sequential identifiers for blocks in the Aztec rollup chain.
+ *
+ * This is a nominal type backed by a number, but TypeScript will treat it as
+ * incompatible with plain numbers and other branded numeric types (like EpochNumber, SlotNumber, etc.).
+ *
+ * Note: This type should ONLY be used for Aztec L2 block numbers, NOT for Ethereum L1 block numbers.
+ *
+ * @example
+ * ```ts
+ * const blockNumber = BlockNumber(100);
+ * const plainNumber: number = blockNumber; // OK - BlockNumber is assignable to number
+ * const blockFromNumber: BlockNumber = 100;  // ERROR - number is not assignable to BlockNumber
+ * ```
+ */
+export type BlockNumber = Branded<number, 'BlockNumber'>;
+
+/**
+ * Creates a BlockNumber from a number.
+ * @param value - The block number (must be a non-negative integer)
+ * @returns The branded BlockNumber value
+ * @throws If the value is negative or not an integer
+ */
+export function BlockNumber(value: number): BlockNumber {
+  if (!Number.isInteger(value)) {
+    throw new Error(`BlockNumber must be an integer, got ${value}`);
+  }
+  if (value < 0) {
+    throw new Error(`BlockNumber must be non-negative, got ${value}`);
+  }
+  return value as BlockNumber;
+}
+
+/**
+ * Creates a BlockNumber from a bigint.
+ * @param value - The block number as bigint (must be a non-negative integer within safe integer range)
+ * @returns The branded BlockNumber value
+ * @throws If the value is negative or exceeds Number.MAX_SAFE_INTEGER
+ */
+BlockNumber.fromBigInt = function (value: bigint): BlockNumber {
+  if (value < 0n) {
+    throw new Error(`BlockNumber must be non-negative, got ${value}`);
+  }
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error(`BlockNumber ${value} exceeds MAX_SAFE_INTEGER`);
+  }
+  return Number(value) as BlockNumber;
+};
+
+/**
+ * Creates a BlockNumber from a string.
+ * @param value - The block number as a string
+ * @returns The branded BlockNumber value
+ * @throws If the string cannot be parsed as a valid block number
+ */
+BlockNumber.fromString = function (value: string): BlockNumber {
+  const parsed = parseInt(value, 10);
+  if (isNaN(parsed)) {
+    throw new Error(`Cannot parse BlockNumber from string: ${value}`);
+  }
+  return BlockNumber(parsed);
+};
+
+/**
+ * Converts a CheckpointNumber to a BlockNumber.
+ * This is used in checkpoint-based systems where checkpoint numbers align with block numbers.
+ * WARNING: This should only be used when you know the checkpoint number corresponds to a block number.
+ * @param value - The checkpoint number to convert
+ * @returns The corresponding BlockNumber
+ */
+BlockNumber.fromCheckpointNumber = function (value: CheckpointNumber): BlockNumber {
+  return value as unknown as BlockNumber;
+};
+
+/**
+ * Type guard to check if a value is a valid BlockNumber.
+ * Note: At runtime, a BlockNumber is just a number, so this checks if the value
+ * is a non-negative integer.
+ */
+BlockNumber.isValid = function (value: unknown): value is BlockNumber {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+};
+
+/** Increments a BlockNumber by a given value. */
+BlockNumber.add = function (bn: BlockNumber, increment: number): BlockNumber {
+  return BlockNumber(bn + increment);
+};
+
+/**
+ * The zero block value (genesis block).
+ */
+BlockNumber.ZERO = BlockNumber(0);
+
+function makeBlockNumberSchema(minValue: number) {
+  return z
+    .union([z.number(), z.bigint(), z.string()])
+    .pipe(z.coerce.number().int().min(minValue))
+    .transform(value => BlockNumber(value));
+}
+
+/**
+ * Zod schema for parsing and validating BlockNumber values.
+ * Accepts numbers, bigints, or strings and coerces them to BlockNumber.
+ */
+export const BlockNumberSchema = makeBlockNumberSchema(0);
+
+/**
+ * Zod schema for parsing and validating BlockNumber values that are strictly positive.
+ * Accepts numbers, bigints, or strings and coerces them to BlockNumber.
+ */
+export const BlockNumberPositiveSchema = makeBlockNumberSchema(1);