@aztec/foundation 0.0.0-test.0 → 0.0.1-commit.001888fc

package/package.json

@@ -1,20 +1,61 @@
 {
   "name": "@aztec/foundation",
-  "version": "0.0.0-test.0",
+  "version": "0.0.1-commit.001888fc",
   "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": "./.eslintrc.cjs",
-    "./eslint.docs": "./.eslintrc.docs.cjs",
+    "./eslint": "./eslint.config.js",
+    "./eslint.docs": "./eslint.config.docs.js",
     "./prettier": "./.prettierrc.json",
     "./abi": "./dest/abi/index.js",
     "./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/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",
@@ -28,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",
@@ -38,8 +80,6 @@
     "./timer": "./dest/timer/index.js",
     "./transport": "./dest/transport/index.js",
     "./trees": "./dest/trees/index.js",
-    "./wasm": "./dest/wasm/index.js",
-    "./worker": "./dest/worker/index.js",
     "./bigint-buffer": "./dest/bigint-buffer/index.js",
     "./types": "./dest/types/index.js",
     "./schemas": "./dest/schemas/index.js",
@@ -48,19 +88,19 @@
     "./noir": "./dest/noir/index.js",
     "./testing": "./dest/testing/index.js",
     "./testing/files": "./dest/testing/files/index.js",
+    "./profiler": "./dest/profiler/index.js",
     "./array": "./dest/array/index.js",
     "./validation": "./dest/validation/index.js",
     "./promise": "./dest/promise/index.js",
     "./string": "./dest/string/index.js",
-    "./message": "./dest/message/index.js"
+    "./message": "./dest/message/index.js",
+    "./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",
-    "formatting": "run -T prettier --check ./src && run -T eslint ./src",
-    "formatting:fix": "run -T eslint --fix ./src && run -T prettier -w ./src",
     "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
   },
   "inherits": [
@@ -96,74 +136,69 @@
     ],
     "testTimeout": 120000,
     "setupFilesAfterEnv": [
-      "../../foundation/src/jest/setup.mjs"
+      "../../foundation/src/jest/setupAfterEnv.mjs"
     ],
     "setupFiles": [
       "../../foundation/src/jest/setup.mjs"
-    ]
+    ],
+    "testEnvironment": "../../foundation/src/jest/env.mjs"
   },
   "dependencies": {
-    "@aztec/bb.js": "0.0.0-test.0",
+    "@aztec/bb.js": "0.0.1-commit.001888fc",
     "@koa/cors": "^5.0.0",
-    "@noble/curves": "^1.2.0",
+    "@noble/curves": "=1.7.0",
+    "@noble/hashes": "^1.6.1",
+    "@scure/bip39": "^2.0.1",
     "bn.js": "^5.2.1",
-    "c-kzg": "4.0.0-alpha.1",
     "colorette": "^2.0.20",
-    "debug": "^4.3.4",
     "detect-node": "^2.1.0",
-    "elliptic": "^6.5.4",
     "hash.js": "^1.1.7",
-    "koa": "^2.14.2",
+    "koa": "^2.16.1",
     "koa-bodyparser": "^4.4.0",
     "koa-compress": "^5.1.0",
-    "koa-router": "^12.0.0",
+    "koa-router": "^13.1.1",
     "leveldown": "^6.1.1",
-    "levelup": "^5.1.1",
     "lodash.chunk": "^4.2.0",
     "lodash.clonedeepwith": "^4.5.0",
-    "memdown": "^6.1.1",
     "pako": "^2.1.0",
     "pino": "^9.5.0",
     "pino-pretty": "^13.0.0",
     "sha3": "^2.1.4",
-    "undici": "^7.3.0",
+    "undici": "^5.28.5",
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@jest/globals": "^29.5.0",
+    "@jest/globals": "^30.0.0",
     "@libp2p/interface": "1.3.1",
-    "@types/bn.js": "^5.1.3",
-    "@types/debug": "^4.1.7",
     "@types/detect-node": "^2.0.0",
-    "@types/elliptic": "^6.4.16",
-    "@types/jest": "^29.5.0",
-    "@types/koa": "^2.13.5",
+    "@types/jest": "^30.0.0",
+    "@types/koa": "^2.15.0",
     "@types/koa-bodyparser": "^4.3.10",
     "@types/koa-compress": "^4.0.3",
     "@types/koa-router": "^7.4.4",
     "@types/koa__cors": "^4.0.0",
     "@types/leveldown": "^4.0.3",
-    "@types/levelup": "^5.1.2",
     "@types/lodash.chunk": "^4.2.9",
     "@types/lodash.clonedeepwith": "^4.5.7",
-    "@types/memdown": "^3.0.1",
-    "@types/node": "^18.7.23",
+    "@types/node": "^22.15.17",
     "@types/pako": "^2.0.0",
     "@types/supertest": "^2.0.12",
-    "@typescript-eslint/eslint-plugin": "^6.2.1",
-    "@typescript-eslint/parser": "^6.2.1",
+    "@typescript/native-preview": "7.0.0-dev.20260113.1",
     "comlink": "^4.4.1",
-    "eslint": "^8.21.0",
-    "eslint-config-prettier": "^8.5.0",
-    "eslint-plugin-jsdoc": "^40.1.0",
-    "eslint-plugin-no-only-tests": "^3.1.0",
-    "eslint-plugin-tsdoc": "^0.2.17",
-    "jest": "^29.5.0",
-    "prettier": "^2.7.1",
+    "eslint": "^9.26.0",
+    "eslint-config-prettier": "^10.1.5",
+    "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",
+    "globals": "^16.1.0",
+    "jest": "^30.0.0",
+    "prettier": "^3.5.3",
     "supertest": "^6.3.3",
     "ts-node": "^10.9.1",
-    "typescript": "^5.0.4",
-    "viem": "2.22.8"
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.32.1",
+    "viem": "npm:@aztec/viem@2.38.2"
   },
   "files": [
     "dest",
@@ -171,6 +206,6 @@
     "!*.test.*"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20.10"
   }
 }

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.
@@ -148,3 +132,16 @@ export function assertRightPadded<T>(arr: T[], isEmpty: (item: T) => boolean) {
     }
   }
 }
+
+/**
+ * Shuffles an array in-place using the Fisher-Yates algorith,
+ * @param arr - The array to shuffle
+ */
+export function shuffle<T>(arr: T[]): void {
+  for (let i = arr.length - 1; i > 0; i--) {
+    const j = (Math.random() * (i + 1)) | 0;
+    const temp = arr[i];
+    arr[i] = arr[j];
+    arr[j] = temp;
+  }
+}

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/async-pool/index.ts

@@ -29,6 +29,7 @@
 export function asyncPool<T, R>(poolLimit: number, iterable: T[], iteratorFn: (item: T, iterable: T[]) => Promise<R>) {
   let i = 0;
   const ret: Promise<R>[] = [];
+  // eslint-disable-next-line aztec-custom/no-non-primitive-in-collections
   const executing: Set<Promise<R>> = new Set();
   const enqueue = (): Promise<any> => {
     if (i === iterable.length) {

package/src/bigint/index.ts

@@ -0,0 +1,20 @@
+/** Returns minimum value across a list of bigints. */
+export function minBigint(...values: bigint[]): bigint {
+  if (values.length === 0) {
+    throw new Error('Cannot get min of empty array');
+  }
+  return values.reduce((min, value) => (value < min ? value : min), values[0]);
+}
+
+/** Returns maximim value across a list of bigints. */
+export function maxBigint(...values: bigint[]): bigint {
+  if (values.length === 0) {
+    throw new Error('Cannot get max of empty array');
+  }
+  return values.reduce((max, value) => (value > max ? value : max), values[0]);
+}
+
+/** Sums an array of bigints */
+export function sumBigint(values: bigint[]): bigint {
+  return values.reduce((sum, value) => sum + value, 0n);
+}

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);

package/src/branded-types/checkpoint_number.ts

@@ -0,0 +1,115 @@
+import { z } from 'zod';
+
+import type { BlockNumber } from './block_number.js';
+import type { Branded } from './types.js';
+
+/**
+ * A branded type representing an checkpoint number.
+ * Checkpoints are used in the Aztec protocol to group L2 blocks.
+ *
+ * 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 Slot, BlockNumber, etc.).
+ *
+ * @example
+ * ```ts
+ * const checkpoint = CheckpointNumber(5);
+ * const plainNumber: number = checkpoint; // OK - CheckpointNumber is assignable to number
+ * const checkpointFromNumber: CheckpointNumber = 5;  // ERROR - number is not assignable to CheckpointNumber
+ * ```
+ */
+export type CheckpointNumber = Branded<number, 'CheckpointNumber'>;
+
+/**
+ * Creates an CheckpointNumber from a number.
+ * @param value - The checkpoint number (must be a non-negative integer)
+ * @returns The branded CheckpointNumber value
+ * @throws If the value is negative or not an integer
+ */
+export function CheckpointNumber(value: number): CheckpointNumber {
+  if (!Number.isInteger(value)) {
+    throw new Error(`CheckpointNumber must be an integer, got ${value}`);
+  }
+  if (value < 0) {
+    throw new Error(`CheckpointNumber must be non-negative, got ${value}`);
+  }
+  return value as CheckpointNumber;
+}
+
+/**
+ * @param value - The block number
+ * @returns The branded CheckpointNumber value
+ *
+ * @deprecated Checkpoint number and block number should no longer convert to each other once we support multiple blocks
+ * per checkpoint everywhere.
+ */
+CheckpointNumber.fromBlockNumber = function (value: BlockNumber): CheckpointNumber {
+  return CheckpointNumber(value);
+};
+
+/**
+ * Creates an CheckpointNumber from a bigint.
+ * @param value - The checkpoint number as bigint (must be a non-negative integer within safe integer range)
+ * @returns The branded CheckpointNumber value
+ * @throws If the value is negative or exceeds Number.MAX_SAFE_INTEGER
+ */
+CheckpointNumber.fromBigInt = function (value: bigint): CheckpointNumber {
+  if (value < 0n) {
+    throw new Error(`CheckpointNumber must be non-negative, got ${value}`);
+  }
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error(`CheckpointNumber ${value} exceeds MAX_SAFE_INTEGER`);
+  }
+  return Number(value) as CheckpointNumber;
+};
+
+/**
+ * Creates an CheckpointNumber from a string.
+ * @param value - The checkpoint number as a string
+ * @returns The branded CheckpointNumber value
+ * @throws If the string cannot be parsed as a valid checkpoint
+ */
+CheckpointNumber.fromString = function (value: string): CheckpointNumber {
+  const parsed = parseInt(value, 10);
+  if (isNaN(parsed)) {
+    throw new Error(`Cannot parse CheckpointNumber from string: ${value}`);
+  }
+  return CheckpointNumber(parsed);
+};
+
+/**
+ * Type guard to check if a value is a valid CheckpointNumber.
+ * Note: At runtime, an CheckpointNumber is just a number, so this checks if the value
+ * is a non-negative integer.
+ */
+CheckpointNumber.isValid = function (value: unknown): value is CheckpointNumber {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+};
+
+/** The zero checkpoint value. */
+CheckpointNumber.ZERO = CheckpointNumber(0);
+
+/** Initial checkpoint. */
+CheckpointNumber.INITIAL = CheckpointNumber(1);
+
+/**
+ * Zod schema for parsing and validating CheckpointNumber values.
+ * Accepts numbers, bigints, or strings and coerces them to CheckpointNumber.
+ */
+function makeCheckpointNumberSchema(minValue: number) {
+  return z
+    .union([z.number(), z.bigint(), z.string()])
+    .pipe(z.coerce.number().int().min(minValue))
+    .transform(value => CheckpointNumber(value));
+}
+
+/**
+ * Zod schema for parsing and validating Checkpoint values.
+ * Accepts numbers, bigints, or strings and coerces them to CheckpointNumber.
+ */
+export const CheckpointNumberSchema = makeCheckpointNumberSchema(0);
+
+/**
+ * Zod schema for parsing and validating CheckpointNumber values that are strictly positive.
+ * Accepts numbers, bigints, or strings and coerces them to CheckpointNumber.
+ */
+export const CheckpointNumberPositiveSchema = makeCheckpointNumberSchema(1);