@aztec/foundation 0.0.1-commit.9b94fc1 → 0.0.1-commit.d3ec352c

package/dest/branded-types/block_number.d.ts

@@ -0,0 +1,53 @@
+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 declare function BlockNumber(value: number): BlockNumber;
+export declare namespace BlockNumber {
+    var fromBigInt: (value: bigint) => BlockNumber;
+}
+export declare namespace BlockNumber {
+    var fromString: (value: string) => BlockNumber;
+}
+export declare namespace BlockNumber {
+    var fromCheckpointNumber: (value: CheckpointNumber) => BlockNumber;
+}
+export declare namespace BlockNumber {
+    var isValid: (value: unknown) => value is BlockNumber;
+}
+export declare namespace BlockNumber {
+    var ZERO: BlockNumber;
+}
+/**
+ * Zod schema for parsing and validating BlockNumber values.
+ * Accepts numbers, bigints, or strings and coerces them to BlockNumber.
+ */
+export declare const BlockNumberSchema: z.ZodEffects<z.ZodPipeline<z.ZodUnion<[z.ZodNumber, z.ZodBigInt, z.ZodString]>, z.ZodNumber>, BlockNumber, string | number | bigint>;
+/**
+ * Zod schema for parsing and validating BlockNumber values that are strictly positive.
+ * Accepts numbers, bigints, or strings and coerces them to BlockNumber.
+ */
+export declare const BlockNumberPositiveSchema: z.ZodEffects<z.ZodPipeline<z.ZodUnion<[z.ZodNumber, z.ZodBigInt, z.ZodString]>, z.ZodNumber>, BlockNumber, string | number | bigint>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmxvY2tfbnVtYmVyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvYnJhbmRlZC10eXBlcy9ibG9ja19udW1iZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLENBQUMsRUFBRSxNQUFNLEtBQUssQ0FBQztBQUV4QixPQUFPLEtBQUssRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBQy9ELE9BQU8sS0FBSyxFQUFFLE9BQU8sRUFBRSxNQUFNLFlBQVksQ0FBQztBQUUxQzs7Ozs7Ozs7Ozs7Ozs7O0dBZUc7QUFDSCxNQUFNLE1BQU0sV0FBVyxHQUFHLE9BQU8sQ0FBQyxNQUFNLEVBQUUsYUFBYSxDQUFDLENBQUM7QUFFekQ7Ozs7O0dBS0c7QUFDSCx3QkFBZ0IsV0FBVyxDQUFDLEtBQUssRUFBRSxNQUFNLEdBQUcsV0FBVyxDQVF0RDs7Ozs7Ozs7Ozs7Ozs7OztBQWdFRDs7O0dBR0c7QUFDSCxlQUFPLE1BQU0saUJBQWlCLHNJQUEyQixDQUFDO0FBRTFEOzs7R0FHRztBQUNILGVBQU8sTUFBTSx5QkFBeUIsc0lBQTJCLENBQUMifQ==

package/dest/branded-types/block_number.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block_number.d.ts","sourceRoot":"","sources":["../../src/branded-types/block_number.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAEzD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAQtD;;;;;;;;;;;;;;;;AAgED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,sIAA2B,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,yBAAyB,sIAA2B,CAAC"}

package/dest/branded-types/block_number.js

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+/**
+ * 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) {
+    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;
+}
+/**
+ * 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) {
+    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);
+};
+/**
+ * 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) {
+    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) {
+    return value;
+};
+/**
+ * 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) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+};
+/**
+ * The zero block value (genesis block).
+ */ BlockNumber.ZERO = BlockNumber(0);
+function makeBlockNumberSchema(minValue) {
+    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/dest/branded-types/checkpoint_number.d.ts

@@ -0,0 +1,46 @@
+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 declare function CheckpointNumber(value: number): CheckpointNumber;
+export declare namespace CheckpointNumber {
+    var fromBlockNumber: (value: BlockNumber) => CheckpointNumber;
+}
+export declare namespace CheckpointNumber {
+    var fromBigInt: (value: bigint) => CheckpointNumber;
+}
+export declare namespace CheckpointNumber {
+    var fromString: (value: string) => CheckpointNumber;
+}
+export declare namespace CheckpointNumber {
+    var isValid: (value: unknown) => value is CheckpointNumber;
+}
+export declare namespace CheckpointNumber {
+    var ZERO: CheckpointNumber;
+}
+/**
+ * Zod schema for parsing and validating CheckpointNumber values.
+ * Accepts numbers, bigints, or strings and coerces them to CheckpointNumber.
+ */
+export declare const CheckpointNumberSchema: z.ZodEffects<z.ZodPipeline<z.ZodUnion<[z.ZodNumber, z.ZodBigInt, z.ZodString]>, z.ZodNumber>, CheckpointNumber, string | number | bigint>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2hlY2twb2ludF9udW1iZXIuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9icmFuZGVkLXR5cGVzL2NoZWNrcG9pbnRfbnVtYmVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxDQUFDLEVBQUUsTUFBTSxLQUFLLENBQUM7QUFFeEIsT0FBTyxLQUFLLEVBQUUsV0FBVyxFQUFFLE1BQU0sbUJBQW1CLENBQUM7QUFDckQsT0FBTyxLQUFLLEVBQUUsT0FBTyxFQUFFLE1BQU0sWUFBWSxDQUFDO0FBRTFDOzs7Ozs7Ozs7Ozs7O0dBYUc7QUFDSCxNQUFNLE1BQU0sZ0JBQWdCLEdBQUcsT0FBTyxDQUFDLE1BQU0sRUFBRSxrQkFBa0IsQ0FBQyxDQUFDO0FBRW5FOzs7OztHQUtHO0FBQ0gsd0JBQWdCLGdCQUFnQixDQUFDLEtBQUssRUFBRSxNQUFNLEdBQUcsZ0JBQWdCLENBUWhFOzs7Ozs7Ozs7Ozs7Ozs7O0FBeUREOzs7R0FHRztBQUNILGVBQU8sTUFBTSxzQkFBc0IsMklBR1csQ0FBQyJ9

package/dest/branded-types/checkpoint_number.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint_number.d.ts","sourceRoot":"","sources":["../../src/branded-types/checkpoint_number.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AAEnE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAQhE;;;;;;;;;;;;;;;;AAyDD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,2IAGW,CAAC"}

package/dest/branded-types/checkpoint_number.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+/**
+ * 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) {
+    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;
+}
+/**
+ * @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) {
+    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) {
+    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);
+};
+/**
+ * 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) {
+    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) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+};
+/**
+ * The zero checkpoint value.
+ */ CheckpointNumber.ZERO = CheckpointNumber(0);
+/**
+ * Zod schema for parsing and validating CheckpointNumber values.
+ * Accepts numbers, bigints, or strings and coerces them to CheckpointNumber.
+ */ export const CheckpointNumberSchema = z.union([
+    z.number(),
+    z.bigint(),
+    z.string()
+]).pipe(z.coerce.number().int().min(0)).transform((value)=>CheckpointNumber(value));

package/dest/branded-types/index.d.ts

@@ -1,4 +1,6 @@
+export { BlockNumber, BlockNumberSchema, BlockNumberPositiveSchema } from './block_number.js';
+export { CheckpointNumber, CheckpointNumberSchema } from './checkpoint_number.js';
 export { EpochNumber, EpochNumberSchema } from './epoch.js';
 export { SlotNumber, SlotNumberSchema } from './slot.js';
 export type { Branded } from './types.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9icmFuZGVkLXR5cGVzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxXQUFXLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSxZQUFZLENBQUM7QUFDNUQsT0FBTyxFQUFFLFVBQVUsRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLFdBQVcsQ0FBQztBQUV6RCxZQUFZLEVBQUUsT0FBTyxFQUFFLE1BQU0sWUFBWSxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9icmFuZGVkLXR5cGVzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxXQUFXLEVBQUUsaUJBQWlCLEVBQUUseUJBQXlCLEVBQUUsTUFBTSxtQkFBbUIsQ0FBQztBQUM5RixPQUFPLEVBQUUsZ0JBQWdCLEVBQUUsc0JBQXNCLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQUNsRixPQUFPLEVBQUUsV0FBVyxFQUFFLGlCQUFpQixFQUFFLE1BQU0sWUFBWSxDQUFDO0FBQzVELE9BQU8sRUFBRSxVQUFVLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSxXQUFXLENBQUM7QUFFekQsWUFBWSxFQUFFLE9BQU8sRUFBRSxNQUFNLFlBQVksQ0FBQyJ9

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/branded-types/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAEzD,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/branded-types/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAC9F,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAClF,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAEzD,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}

package/dest/branded-types/index.js

@@ -1,2 +1,4 @@
+export { BlockNumber, BlockNumberSchema, BlockNumberPositiveSchema } from './block_number.js';
+export { CheckpointNumber, CheckpointNumberSchema } from './checkpoint_number.js';
 export { EpochNumber, EpochNumberSchema } from './epoch.js';
 export { SlotNumber, SlotNumberSchema } from './slot.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/foundation",
-  "version": "0.0.1-commit.9b94fc1",
+  "version": "0.0.1-commit.d3ec352c",
   "type": "module",
   "main": "./dest/index.js",
   "types": "./dest/index.d.ts",
@@ -58,8 +58,8 @@
     "./number": "./dest/number/index.js"
   },
   "scripts": {
-    "build": "yarn clean && tsgo -b",
-    "build:dev": "tsgo -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}"
@@ -105,7 +105,7 @@
     "testEnvironment": "../../foundation/src/jest/env.mjs"
   },
   "dependencies": {
-    "@aztec/bb.js": "0.0.1-commit.9b94fc1",
+    "@aztec/bb.js": "0.0.1-commit.d3ec352c",
     "@koa/cors": "^5.0.0",
     "@noble/curves": "=1.7.0",
     "@noble/hashes": "^1.6.1",

package/src/branded-types/block_number.ts

@@ -0,0 +1,112 @@
+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;
+};
+
+/**
+ * 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,100 @@
+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);
+
+/**
+ * Zod schema for parsing and validating CheckpointNumber values.
+ * Accepts numbers, bigints, or strings and coerces them to CheckpointNumber.
+ */
+export const CheckpointNumberSchema = z
+  .union([z.number(), z.bigint(), z.string()])
+  .pipe(z.coerce.number().int().min(0))
+  .transform(value => CheckpointNumber(value));

package/src/branded-types/index.ts

@@ -1,3 +1,5 @@
+export { BlockNumber, BlockNumberSchema, BlockNumberPositiveSchema } from './block_number.js';
+export { CheckpointNumber, CheckpointNumberSchema } from './checkpoint_number.js';
 export { EpochNumber, EpochNumberSchema } from './epoch.js';
 export { SlotNumber, SlotNumberSchema } from './slot.js';