@aztec/foundation 0.0.1-commit.03f7ef2 → 0.0.1-commit.04d373f

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/bigint-buffer/index.ts

@@ -49,9 +49,14 @@ export function toBufferLE(num: bigint, width: number): Buffer {
  * @returns A big-endian buffer representation of num.
  */
 export function toBufferBE(num: bigint, width: number): Buffer {
-  if (num < BigInt(0)) {
+  if (num < 0n) {
     throw new Error(`Cannot convert negative bigint ${num.toString()} to buffer with toBufferBE.`);
   }
+  // The values serialized in the hot paths are overwhelmingly zero (field elements are mostly
+  // zero-padding in protocol structs), and the hex round-trip is wasteful for them.
+  if (num === 0n) {
+    return Buffer.alloc(width);
+  }
   const hex = num.toString(16);
   const buffer = Buffer.from(hex.padStart(width * 2, '0').slice(0, width * 2), 'hex');
   if (buffer.length > width) {

package/src/branded-types/block_number.ts

@@ -87,15 +87,38 @@ 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) {
+  const max = Number.MAX_SAFE_INTEGER;
   return z
-    .union([z.number(), z.bigint(), z.string()])
-    .pipe(z.coerce.number().int().min(minValue))
+    .union([
+      z.number().int().min(minValue).max(max),
+      z
+        .bigint()
+        .min(BigInt(minValue))
+        .max(BigInt(max))
+        .transform(v => Number(v)),
+      z
+        .string()
+        .regex(/^\d+$/, 'BlockNumber string must be a non-negative decimal integer')
+        .transform((v, ctx) => {
+          const parsed = Number(v);
+          if (!Number.isInteger(parsed) || parsed > max || parsed < minValue) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `BlockNumber out of range: ${v}` });
+            return z.NEVER;
+          }
+          return parsed;
+        }),
+    ])
     .transform(value => BlockNumber(value));
 }
 

package/src/branded-types/buffer32_hash.ts

@@ -0,0 +1,38 @@
+import type { Branded } from './types.js';
+
+/**
+ * A branded `0x`-prefixed hex string representing a checkpoint proposal payload hash.
+ *
+ * A `CheckpointProposal` and the matching `CheckpointAttestation` sign the same
+ * `ConsensusPayload`, so they share this hash type. Used by the p2p attestation
+ * pool to dedup signed payloads and detect equivocations.
+ */
+export type CheckpointProposalHash = Branded<`0x${string}`, 'CheckpointProposalHash'>;
+
+/** Brands a `0x`-prefixed hex string as a CheckpointProposalHash. */
+export function CheckpointProposalHash(s: `0x${string}`): CheckpointProposalHash {
+  return s as CheckpointProposalHash;
+}
+
+/** Constructs a CheckpointProposalHash from a raw 32-byte hash buffer. */
+CheckpointProposalHash.fromBuffer = function (buf: Buffer): CheckpointProposalHash {
+  return `0x${buf.toString('hex')}` as CheckpointProposalHash;
+};
+
+/**
+ * A branded `0x`-prefixed hex string representing a block proposal payload hash.
+ *
+ * Used by the p2p attestation pool to dedup signed payloads at a given
+ * `(slot, indexWithinCheckpoint)` and detect equivocations.
+ */
+export type BlockProposalHash = Branded<`0x${string}`, 'BlockProposalHash'>;
+
+/** Brands a `0x`-prefixed hex string as a BlockProposalHash. */
+export function BlockProposalHash(s: `0x${string}`): BlockProposalHash {
+  return s as BlockProposalHash;
+}
+
+/** Constructs a BlockProposalHash from a raw 32-byte hash buffer. */
+BlockProposalHash.fromBuffer = function (buf: Buffer): BlockProposalHash {
+  return `0x${buf.toString('hex')}` as BlockProposalHash;
+};

package/src/branded-types/checkpoint_number.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 
+import { isDefined } from '../types/index.js';
 import type { BlockNumber } from './block_number.js';
 import type { Branded } from './types.js';
 
@@ -85,16 +86,45 @@ CheckpointNumber.isValid = function (value: unknown): value is CheckpointNumber
   return typeof value === 'number' && Number.isInteger(value) && value >= 0;
 };
 
-/**
- * The zero checkpoint value.
- */
+/** Increments a CheckpointNumber by a given value. */
+CheckpointNumber.add = function (n: CheckpointNumber, increment: number): CheckpointNumber {
+  return CheckpointNumber(n + increment);
+};
+
+/** Computes max of a set of checkpoint numbers, ignoring undefined values. */
+CheckpointNumber.max = function (...values: (CheckpointNumber | undefined)[]): CheckpointNumber | undefined {
+  const filtered = values.filter(isDefined);
+  if (filtered.length === 0) {
+    return undefined;
+  }
+  return CheckpointNumber(Math.max(...filtered));
+};
+
+/** 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.
  */
-export const CheckpointNumberSchema = z
-  .union([z.number(), z.bigint(), z.string()])
-  .pipe(z.coerce.number().int().min(0))
-  .transform(value => CheckpointNumber(value));
+function makeCheckpointNumberSchema(minValue: number) {
+  return z
+    .union([z.number(), z.bigint(), z.string()])
+    .pipe(z.coerce.number<string | number | bigint>().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);

package/src/branded-types/epoch.ts

@@ -84,5 +84,5 @@ EpochNumber.ZERO = EpochNumber(0);
  */
 export const EpochNumberSchema = z
   .union([z.number(), z.bigint(), z.string()])
-  .pipe(z.coerce.number().int().min(0))
+  .pipe(z.coerce.number<string | number | bigint>().int().min(0))
   .transform(value => EpochNumber(value));

package/src/branded-types/index.ts

@@ -1,6 +1,8 @@
 export { BlockNumber, BlockNumberSchema, BlockNumberPositiveSchema } from './block_number.js';
-export { CheckpointNumber, CheckpointNumberSchema } from './checkpoint_number.js';
+export { BlockProposalHash, CheckpointProposalHash } from './buffer32_hash.js';
+export { CheckpointNumber, CheckpointNumberSchema, CheckpointNumberPositiveSchema } from './checkpoint_number.js';
 export { EpochNumber, EpochNumberSchema } from './epoch.js';
+export { IndexWithinCheckpoint, IndexWithinCheckpointSchema } from './index_within_checkpoint.js';
 export { SlotNumber, SlotNumberSchema } from './slot.js';
 
 export type { Branded } from './types.js';

package/src/branded-types/index_within_checkpoint.ts

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+
+import type { Branded } from './types.js';
+
+/**
+ * A branded type representing the index of a block within a checkpoint.
+ * The first block in a checkpoint has index 0, the second has index 1, etc.
+ *
+ * This is a nominal type backed by a number, but TypeScript will treat it as
+ * incompatible with plain numbers and other branded numeric types.
+ *
+ * @example
+ * ```ts
+ * const index = IndexWithinCheckpoint(0);
+ * const plainNumber: number = index; // OK - IndexWithinCheckpoint is assignable to number
+ * const indexFromNumber: IndexWithinCheckpoint = 0;  // ERROR - number is not assignable to IndexWithinCheckpoint
+ * ```
+ */
+export type IndexWithinCheckpoint = Branded<number, 'IndexWithinCheckpoint'>;
+
+/**
+ * Creates an IndexWithinCheckpoint from a number.
+ * @param value - The index (must be a non-negative integer)
+ * @returns The branded IndexWithinCheckpoint value
+ * @throws If the value is negative or not an integer
+ */
+export function IndexWithinCheckpoint(value: number): IndexWithinCheckpoint {
+  if (!Number.isInteger(value)) {
+    throw new Error(`IndexWithinCheckpoint must be an integer, got ${value}`);
+  }
+  if (value < 0) {
+    throw new Error(`IndexWithinCheckpoint must be non-negative, got ${value}`);
+  }
+  return value as IndexWithinCheckpoint;
+}
+
+/**
+ * Creates an IndexWithinCheckpoint from a bigint.
+ * @param value - The index as bigint (must be a non-negative integer within safe integer range)
+ * @returns The branded IndexWithinCheckpoint value
+ * @throws If the value is negative or exceeds Number.MAX_SAFE_INTEGER
+ */
+IndexWithinCheckpoint.fromBigInt = function (value: bigint): IndexWithinCheckpoint {
+  if (value < 0n) {
+    throw new Error(`IndexWithinCheckpoint must be non-negative, got ${value}`);
+  }
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error(`IndexWithinCheckpoint ${value} exceeds MAX_SAFE_INTEGER`);
+  }
+  return Number(value) as IndexWithinCheckpoint;
+};
+
+/**
+ * Creates an IndexWithinCheckpoint from a string.
+ * @param value - The index as a string
+ * @returns The branded IndexWithinCheckpoint value
+ * @throws If the string cannot be parsed as a valid index
+ */
+IndexWithinCheckpoint.fromString = function (value: string): IndexWithinCheckpoint {
+  const parsed = parseInt(value, 10);
+  if (isNaN(parsed)) {
+    throw new Error(`Cannot parse IndexWithinCheckpoint from string: ${value}`);
+  }
+  return IndexWithinCheckpoint(parsed);
+};
+
+/**
+ * Type guard to check if a value is a valid IndexWithinCheckpoint.
+ * Note: At runtime, an IndexWithinCheckpoint is just a number, so this checks if the value
+ * is a non-negative integer.
+ */
+IndexWithinCheckpoint.isValid = function (value: unknown): value is IndexWithinCheckpoint {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+};
+
+/**
+ * The zero index value (first block in checkpoint).
+ */
+IndexWithinCheckpoint.ZERO = IndexWithinCheckpoint(0);
+
+/**
+ * Zod schema for parsing and validating IndexWithinCheckpoint values.
+ * Accepts numbers, bigints, or strings and coerces them to IndexWithinCheckpoint.
+ */
+export const IndexWithinCheckpointSchema = z
+  .union([z.number(), z.bigint(), z.string()])
+  .pipe(z.coerce.number<string | number | bigint>().int().min(0))
+  .transform(value => IndexWithinCheckpoint(value));

package/src/branded-types/slot.ts

@@ -73,6 +73,11 @@ SlotNumber.isValid = function (value: unknown): value is SlotNumber {
   return typeof value === 'number' && Number.isInteger(value) && value >= 0;
 };
 
+/** Increments a SlotNumber by a given value. */
+SlotNumber.add = function (sn: SlotNumber, increment: number): SlotNumber {
+  return SlotNumber(sn + increment);
+};
+
 /**
  * The zero slot value.
  */
@@ -84,5 +89,5 @@ SlotNumber.ZERO = SlotNumber(0);
  */
 export const SlotNumberSchema = z
   .union([z.number(), z.bigint(), z.string()])
-  .pipe(z.coerce.number().int().min(0))
+  .pipe(z.coerce.number<string | number | bigint>().int().min(0))
   .transform(value => SlotNumber(value));

package/src/buffer/buffer16.ts

@@ -10,6 +10,9 @@ import { bufferToHex } from '../string/index.js';
  * A class representing a 16 byte Buffer.
  */
 export class Buffer16 {
+  /** Branding for nominal typing. */
+  declare private readonly _branding: 'Buffer16';
+
   /**
    * The size of the hash in bytes.
    */

package/src/buffer/buffer32.ts

@@ -7,69 +7,39 @@ import { inspect } from 'util';
 import { bufferToHex } from '../string/index.js';
 
 /**
- * A class representing a 32 byte Buffer.
+ * Abstract unbranded base class for 32-byte buffers.
+ * Extend this instead of Buffer32 when defining a branded subtype
+ * to avoid inheriting Buffer32's `_branding`.
  */
-export class Buffer32 {
-  /**
-   * The size of the hash in bytes.
-   */
+export abstract class BaseBuffer32 {
+  /** The size of the buffer in bytes. */
   public static SIZE = 32;
 
-  /**
-   * Buffer32 with value zero.
-   */
-  public static ZERO = new Buffer32(Buffer.alloc(Buffer32.SIZE));
-
   constructor(
-    /**
-     * The buffer containing the hash.
-     */
+    /** The buffer containing the data. */
     public buffer: Buffer,
   ) {
-    if (buffer.length !== Buffer32.SIZE) {
-      throw new Error(`Expected buffer to have length ${Buffer32.SIZE} but was ${buffer.length}`);
+    if (buffer.length !== BaseBuffer32.SIZE) {
+      throw new Error(`Expected buffer to have length ${BaseBuffer32.SIZE} but was ${buffer.length}`);
     }
   }
 
-  /**
-   * Returns the raw buffer of the hash.
-   * @returns The buffer containing the hash.
-   */
+  /** Returns the raw buffer. */
   public toBuffer() {
     return this.buffer;
   }
 
-  /**
-   * Creates a Buffer32 from a buffer.
-   * @param buffer - The buffer to create from.
-   * @returns A new Buffer32 object.
-   */
-  public static fromBuffer(buffer: Buffer | BufferReader) {
-    const reader = BufferReader.asReader(buffer);
-    return new Buffer32(reader.readBytes(Buffer32.SIZE));
-  }
-
-  /**
-   * Checks if this hash and another hash are equal.
-   * @param hash - A hash to compare with.
-   * @returns True if the hashes are equal, false otherwise.
-   */
-  public equals(hash: Buffer32): boolean {
+  /** Checks if this and another buffer are equal. */
+  public equals(hash: BaseBuffer32): boolean {
     return this.buffer.equals(hash.buffer);
   }
 
-  /**
-   * Returns true if this hash is zero.
-   * @returns True if this hash is zero.
-   */
+  /** Returns true if all bytes are zero. */
   public isZero(): boolean {
     return this.buffer.equals(Buffer.alloc(32, 0));
   }
 
-  /**
-   * Convert this hash to a hex string.
-   * @returns The hex string.
-   */
+  /** Convert to a hex string. */
   public toString() {
     return bufferToHex(this.buffer);
   }
@@ -82,16 +52,27 @@ export class Buffer32 {
     return this.toString();
   }
 
-  /**
-   * Convert this hash to a big int.
-   * @returns The big int.
-   */
+  /** Convert to a big int. */
   public toBigInt() {
-    return deserializeBigInt(this.buffer, 0, Buffer32.SIZE).elem;
+    return deserializeBigInt(this.buffer, 0, BaseBuffer32.SIZE).elem;
   }
-  /**
-   * Creates a Buffer32 from a bigint.
-   */
+}
+
+/** A branded 32-byte buffer. */
+export class Buffer32 extends BaseBuffer32 {
+  /** Branding for nominal typing. */
+  declare private readonly _branding: 'Buffer32';
+
+  /** Buffer32 with value zero. */
+  public static ZERO = new Buffer32(Buffer.alloc(Buffer32.SIZE));
+
+  /** Creates a Buffer32 from a buffer. */
+  public static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new Buffer32(reader.readBytes(Buffer32.SIZE));
+  }
+
+  /** Creates a Buffer32 from a bigint. */
   public static fromBigInt(hash: bigint) {
     return new Buffer32(serializeBigInt(hash, Buffer32.SIZE));
   }
@@ -101,8 +82,7 @@ export class Buffer32 {
   }
 
   /**
-   * Converts this hash from a buffer of 28 bytes.
-   * Verifies the input is 28 bytes.
+   * Converts from a buffer of 28 bytes.
    * @param buffer - The 28 byte buffer to construct from.
    * @returns A Buffer32 created from the input buffer with 4 bytes 0 padding at the front.
    */
@@ -110,36 +90,27 @@ export class Buffer32 {
     if (buffer.length != 28) {
       throw new Error(`Expected Buffer32 input buffer to be 28 bytes`);
     }
-    const padded = Buffer.concat([Buffer.alloc(this.SIZE - 28), buffer]);
+    const padded = Buffer.concat([Buffer.alloc(Buffer32.SIZE - 28), buffer]);
     return new Buffer32(padded);
   }
 
-  /**
-   * Converts a string into a Buffer32 object.
-   */
+  /** Converts a string into a Buffer32 object. */
   public static fromString(str: string): Buffer32 {
     if (str.startsWith('0x')) {
       str = str.slice(2);
     }
-    if (str.length !== this.SIZE * 2) {
-      throw new Error(`Expected string to be ${this.SIZE * 2} characters long, but was ${str.length}`);
+    if (str.length !== Buffer32.SIZE * 2) {
+      throw new Error(`Expected string to be ${Buffer32.SIZE * 2} characters long, but was ${str.length}`);
     }
     return new Buffer32(Buffer.from(str, 'hex'));
   }
 
-  /**
-   * Converts a number into a Buffer32 object.
-   * @param num - The number to convert.
-   * @returns A new Buffer32 object.
-   */
+  /** Converts a number into a Buffer32 object. */
   public static fromNumber(num: number): Buffer32 {
     return new Buffer32(serializeBigInt(BigInt(num), Buffer32.SIZE));
   }
 
-  /**
-   * Generates a random Buffer32.
-   * @returns A new Buffer32 object.
-   */
+  /** Generates a random Buffer32. */
   public static random(): Buffer32 {
     return new Buffer32(Buffer.from(randomBytes(Buffer32.SIZE)));
   }

package/src/buffer/index.ts

@@ -1,2 +1,3 @@
 export * from './buffer32.js';
 export * from './buffer16.js';
+export * from './utils.js';

package/src/buffer/utils.ts

@@ -0,0 +1,8 @@
+/** Returns the number of bytes in the buffer, excluding any trailing zero bytes. */
+export function trimmedBytesLength(buf: Uint8Array): number {
+  let end = buf.length;
+  while (end > 0 && buf[end - 1] === 0) {
+    end--;
+  }
+  return end;
+}