@aztec-labs/foundation 6.0.0-nightly.20260829

package/src/crypto/random/index.ts

@@ -0,0 +1,47 @@
+import { randomBytes as bbRandomBytes } from '@aztec/bb.js';
+
+import { RandomnessSingleton } from './randomness_singleton.js';
+
+export const randomBytes = (len: number) => {
+  const singleton = RandomnessSingleton.getInstance();
+
+  if (singleton.isDeterministic()) {
+    return singleton.getBytes(len);
+  }
+  return Buffer.from(bbRandomBytes(len)) as Buffer<ArrayBuffer>;
+};
+
+/**
+ * Generate a random integer less than max.
+ * @param max - The maximum value.
+ * @returns A random integer.
+ *
+ * TODO(#3949): This is insecure as it's modulo biased. Nuke or safeguard before mainnet.
+ */
+export const randomInt = (max: number) => {
+  const randomBuffer = randomBytes(6); // Generate a buffer of 6 random bytes.
+  const randomInt = parseInt(randomBuffer.toString('hex'), 16); // Convert buffer to a large integer.
+  return randomInt % max; // Use modulo to ensure the result is less than max.
+};
+
+/**
+ * Generate a random bigint less than max.
+ * @param max - The maximum value.
+ * @returns A random bigint.
+ *
+ * TODO(#3949): This is insecure as it's modulo biased. Nuke or safeguard before mainnet.
+ */
+export const randomBigInt = (max: bigint) => {
+  const randomBuffer = randomBytes(8); // Generate a buffer of 8 random bytes.
+  const randomBigInt = BigInt(`0x${randomBuffer.toString('hex')}`); // Convert buffer to a large integer.
+  return randomBigInt % max; // Use modulo to ensure the result is less than max.
+};
+
+/**
+ * Generate a random boolean value.
+ * @returns A random boolean value.
+ */
+export const randomBoolean = () => {
+  const randomByte = randomBytes(1)[0]; // Generate a single random byte.
+  return randomByte % 2 === 0; // Use modulo to determine if the byte is even or odd.
+};

package/src/crypto/random/randomness_singleton.ts

@@ -0,0 +1,64 @@
+import { type Logger, type LoggerBindings, createLogger } from '../../log/pino-logger.js';
+
+/**
+ * A number generator which is used as a source of randomness in the system. If the SEED env variable is set, the
+ * generator will be deterministic and will always produce the same sequence of numbers. Otherwise a true randomness
+ * sourced by crypto library will be used.
+ * @remarks This class was implemented so that tests can be run deterministically.
+ *
+ * TODO(#3949): This is not safe enough for production and should be made safer or removed before mainnet.
+ */
+export class RandomnessSingleton {
+  private static instance: RandomnessSingleton;
+
+  private counter = 0;
+  private log: Logger;
+
+  private constructor(
+    private readonly seed?: number,
+    bindings?: LoggerBindings,
+  ) {
+    this.log = createLogger('foundation:randomness_singleton', bindings);
+    if (seed !== undefined) {
+      this.log.debug(`Using pseudo-randomness with seed: ${seed}`);
+      this.counter = seed;
+    } else {
+      this.log.debug('Using true randomness');
+    }
+  }
+
+  public static getInstance(bindings?: LoggerBindings): RandomnessSingleton {
+    if (!RandomnessSingleton.instance) {
+      const seed = process.env.SEED ? Number(process.env.SEED) : undefined;
+      RandomnessSingleton.instance = new RandomnessSingleton(seed, bindings);
+    }
+
+    return RandomnessSingleton.instance;
+  }
+
+  /**
+   * Indicates whether the generator is deterministic (was seeded) or not.
+   * @returns Whether the generator is deterministic.
+   */
+  public isDeterministic(): boolean {
+    return this.seed !== undefined;
+  }
+
+  public getBytes(length: number): Buffer {
+    if (this.seed === undefined) {
+      // Note: It would be more natural to just have the contents of randomBytes(...) function from
+      // yarn-project/foundation/src/crypto/random/index.ts here but that would result in a larger
+      // refactor so I think prohibiting use of this func when the seed is undefined is and handling
+      // the singleton within randomBytes func is fine.
+      throw new Error('RandomnessSingleton is not implemented for non-deterministic mode');
+    }
+    const result = Buffer.alloc(length);
+    for (let i = 0; i < length; i++) {
+      // Each byte of the buffer is set to a 1 byte of this.counter's value. 0xff is 255 in decimal and it's used as
+      // a mask to get the last 8 bits of the shifted counter.
+      result[i] = (this.counter >> (i * 8)) & 0xff;
+    }
+    this.counter++;
+    return result;
+  }
+}

package/src/crypto/schnorr/index.ts

@@ -0,0 +1,61 @@
+import { BarretenbergSync } from '@aztec/bb.js';
+
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { GrumpkinScalar } from '@aztec-labs/foundation/curves/grumpkin';
+import { Point } from '@aztec-labs/foundation/curves/grumpkin';
+
+import { SchnorrSignature } from './signature.js';
+
+export * from './signature.js';
+
+/**
+ * Schnorr signature construction and helper operations.
+ */
+export class Schnorr {
+  /**
+   * Computes a grumpkin public key from a private key.
+   * @param privateKey - The private key.
+   * @returns A grumpkin public key.
+   */
+  public async computePublicKey(privateKey: GrumpkinScalar): Promise<Point> {
+    await BarretenbergSync.initSingleton();
+    const api = BarretenbergSync.getSingleton();
+    const response = api.schnorrComputePublicKey({ privateKey: privateKey.toBuffer() });
+    return Point.fromBuffer(Buffer.concat([Buffer.from(response.publicKey.x), Buffer.from(response.publicKey.y)]));
+  }
+
+  /**
+   * Constructs a Schnorr signature over a 32-byte message field element.
+   * @param msg - The message hash, as a grumpkin base field element.
+   * @param privateKey - The private key of the signer.
+   * @returns A Schnorr signature of the form (s, e).
+   */
+  public async constructSignature(msg: Fr, privateKey: GrumpkinScalar) {
+    await BarretenbergSync.initSingleton();
+    const api = BarretenbergSync.getSingleton();
+    const response = api.schnorrConstructSignature({
+      messageField: msg.toBuffer(),
+      privateKey: privateKey.toBuffer(),
+    });
+    return new SchnorrSignature(Buffer.from([...response.s, ...response.e]));
+  }
+
+  /**
+   * Verifies a Schnorr signature against a Grumpkin public key.
+   * @param msg - The message hash, as a grumpkin base field element.
+   * @param pubKey - The Grumpkin public key of the signer.
+   * @param sig - The Schnorr signature.
+   * @returns True or false.
+   */
+  public async verifySignature(msg: Fr, pubKey: Point, sig: SchnorrSignature) {
+    await BarretenbergSync.initSingleton();
+    const api = BarretenbergSync.getSingleton();
+    const response = api.schnorrVerifySignature({
+      messageField: msg.toBuffer(),
+      publicKey: { x: pubKey.x.toBuffer(), y: pubKey.y.toBuffer() },
+      s: sig.s,
+      e: sig.e,
+    });
+    return response.verified;
+  }
+}

package/src/crypto/schnorr/signature.ts

@@ -0,0 +1,87 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { mapTuple } from '@aztec-labs/foundation/serialize';
+
+import type { Signature } from '../signature/index.js';
+
+/**
+ * Schnorr signature used for transactions.
+ * @see cpp/barretenberg/cpp/src/barretenberg/crypto/schnorr/schnorr.hpp
+ */
+export class SchnorrSignature implements Signature {
+  /**
+   * The size of the signature in bytes.
+   */
+  public static SIZE = 64;
+
+  constructor(private buffer: Buffer) {
+    if (buffer.length !== SchnorrSignature.SIZE) {
+      throw new Error(`Invalid signature buffer of length ${buffer.length}.`);
+    }
+  }
+
+  /**
+   * Returns the 's' component of the signature.
+   * @returns A buffer containing the signature's 's' component.
+   */
+  get s() {
+    return this.buffer.subarray(0, 32);
+  }
+
+  /**
+   * Returns the 'e' component of the signature.
+   * @returns A buffer containing the signature's 'e' component.
+   */
+  get e() {
+    return this.buffer.subarray(32);
+  }
+
+  /**
+   * Returns the full signature as a buffer.
+   * @returns A buffer containing the signature.
+   */
+  toBuffer() {
+    return this.buffer;
+  }
+
+  /**
+   * Returns the full signature as a hex string.
+   * @returns A string containing the signature in hex format.
+   */
+  toString() {
+    return `0x${this.buffer.toString('hex')}`;
+  }
+
+  /**
+   * Converts the signature to an array of three fields.
+   * @returns The signature components as an array of three fields
+   */
+  toFields(): Fr[] {
+    const sig = this.toBuffer();
+
+    const buf1 = Buffer.alloc(32);
+    const buf2 = Buffer.alloc(32);
+    const buf3 = Buffer.alloc(32);
+
+    sig.copy(buf1, 1, 0, 31);
+    sig.copy(buf2, 1, 31, 62);
+    sig.copy(buf3, 1, 62, 64);
+
+    return mapTuple([buf1, buf2, buf3], Fr.fromBuffer);
+  }
+
+  /**
+   * Splits the signature into the four 128-bit limbs that Noir's `EmbeddedCurveScalar` consumes:
+   * `[s.lo, s.hi, e.lo, e.hi]`, where each component scalar is encoded as `lo + hi * 2^128`.
+   *
+   * Each 32-byte big-endian component is sliced into its top 16 bytes (`hi`) and bottom 16 bytes
+   * (`lo`); each half is zero-padded into a 32-byte buffer and decoded as `Fr` (big-endian).
+   */
+  toLimbFields(): [Fr, Fr, Fr, Fr] {
+    const limb = (start: number) => {
+      const buf = Buffer.alloc(32);
+      this.buffer.copy(buf, 16, start, start + 16);
+      return Fr.fromBuffer(buf);
+    };
+    return [limb(16), limb(0), limb(48), limb(32)];
+  }
+}

package/src/crypto/secp256k1/index.ts

@@ -0,0 +1,61 @@
+import { BarretenbergSync } from '@aztec/bb.js';
+
+/**
+ * Secp256k1 elliptic curve operations.
+ */
+export class Secp256k1 {
+  // prettier-ignore
+  static generator = Buffer.from([
+    0x79, 0xbe, 0x66, 0x7e, 0xf9, 0xdc, 0xbb, 0xac, 0x55, 0xa0, 0x62, 0x95, 0xce, 0x87, 0x0b, 0x07,
+    0x02, 0x9b, 0xfc, 0xdb, 0x2d, 0xce, 0x28, 0xd9, 0x59, 0xf2, 0x81, 0x5b, 0x16, 0xf8, 0x17, 0x98,
+    0x48, 0x3a, 0xda, 0x77, 0x26, 0xa3, 0xc4, 0x65, 0x5d, 0xa4, 0xfb, 0xfc, 0x0e, 0x11, 0x08, 0xa8,
+    0xfd, 0x17, 0xb4, 0x48, 0xa6, 0x85, 0x54, 0x19, 0x9c, 0x47, 0xd0, 0x8f, 0xfb, 0x10, 0xd4, 0xb8,
+  ]);
+
+  /**
+   * Point generator
+   * @returns The generator for the curve.
+   */
+  public generator(): Buffer {
+    return Secp256k1.generator;
+  }
+
+  /**
+   * Multiplies a point by a scalar (adds the point `scalar` amount of time).
+   * @param point - Point to multiply.
+   * @param scalar - Scalar to multiply by.
+   * @returns Result of the multiplication.
+   */
+  public async mul(point: Uint8Array, scalar: Uint8Array) {
+    await BarretenbergSync.initSingleton();
+    const api = BarretenbergSync.getSingleton();
+    const response = api.secp256k1Mul({
+      point: { x: point.subarray(0, 32), y: point.subarray(32, 64) },
+      scalar,
+    });
+    return Buffer.concat([Buffer.from(response.point.x), Buffer.from(response.point.y)]);
+  }
+
+  /**
+   * Gets a random field element.
+   * @returns Random field element.
+   */
+  public async getRandomFr() {
+    await BarretenbergSync.initSingleton();
+    const api = BarretenbergSync.getSingleton();
+    const response = api.secp256k1GetRandomFr({ dummy: 0 });
+    return Buffer.from(response.value);
+  }
+
+  /**
+   * Converts a 512 bits long buffer to a field.
+   * @param uint512Buf - The buffer to convert.
+   * @returns Buffer representation of the field element.
+   */
+  public async reduce512BufferToFr(uint512Buf: Buffer) {
+    await BarretenbergSync.initSingleton();
+    const api = BarretenbergSync.getSingleton();
+    const response = api.secp256k1Reduce512({ input: uint512Buf });
+    return Buffer.from(response.value);
+  }
+}

package/src/crypto/secp256k1-signer/index.ts

@@ -0,0 +1,2 @@
+export * from './secp256k1_signer.js';
+export * from './utils.js';

package/src/crypto/secp256k1-signer/secp256k1_signer.ts

@@ -0,0 +1,38 @@
+import { Buffer32 } from '@aztec-labs/foundation/buffer';
+import type { EthAddress } from '@aztec-labs/foundation/eth-address';
+import type { Signature } from '@aztec-labs/foundation/eth-signature';
+
+import { addressFromPrivateKey, makeEthSignDigest, signMessage } from './utils.js';
+
+/**
+ * Secp256k1Signer
+ *
+ * A class for signing messages using a secp256k1 private key.
+ * - This is a slim drop in replacement for an Ethereum signer, so it can be used in the same way.
+ * - See `utils.ts` for functions that enable recovering addresses and public keys from signatures.
+ */
+export class Secp256k1Signer {
+  public readonly address: EthAddress;
+
+  constructor(private privateKey: Buffer32) {
+    this.address = addressFromPrivateKey(privateKey.buffer);
+  }
+
+  sign(message: Buffer32): Signature {
+    return signMessage(message, this.privateKey.buffer);
+  }
+
+  /**
+   * Sign a message using the same method as eth_sign
+   * @param message - The message to sign.
+   * @returns The signature.
+   */
+  signMessage(message: Buffer32): Signature {
+    const digest = makeEthSignDigest(message);
+    return this.sign(digest);
+  }
+
+  static random(): Secp256k1Signer {
+    return new Secp256k1Signer(Buffer32.random());
+  }
+}

package/src/crypto/secp256k1-signer/utils.ts

@@ -0,0 +1,244 @@
+import { secp256k1 } from '@noble/curves/secp256k1';
+
+import { Buffer32 } from '../../buffer/buffer32.js';
+import { EthAddress } from '../../eth-address/index.js';
+import { Signature } from '../../eth-signature/eth_signature.js';
+import { keccak256 } from '../keccak/index.js';
+
+const ETH_SIGN_PREFIX = '\x19Ethereum Signed Message:\n32';
+
+/** Signature recovery options */
+type RecoveryOpts = {
+  /**
+   * Whether to allow s-values in the high half of the curve (s >= CURVE.n/2).
+   * These are discouraged by EIP2 to prevent signature malleability, and outright
+   * rejected in OpenZeppelin's ECDSA recover, which we use in our Rollup contract.
+   */
+  allowMalleable?: boolean;
+  /**
+   * Whether to allow an y-parity 0-1 bit instead of the standard v value 27-28.
+   */
+  allowYParityAsV?: boolean;
+};
+
+export class Secp256k1Error extends Error {
+  constructor(message: string, opts?: { cause: unknown }) {
+    super(message, opts);
+    this.name = 'Secp256k1Error';
+  }
+}
+
+// We just hash the message to make it easier to work with in the smart contract.
+export function makeEthSignDigest(message: Buffer32): Buffer32 {
+  const prefix = Buffer.from(ETH_SIGN_PREFIX);
+  return Buffer32.fromBuffer(keccak256(Buffer.concat([prefix, message.buffer])));
+}
+
+/**
+ * Converts a public key to an address.
+ * @param publicKey - The public key to convert.
+ * @returns The address.
+ */
+function publicKeyToAddress(publicKey: Buffer): EthAddress {
+  const hash = keccak256(publicKey.subarray(1));
+  return new EthAddress(hash.subarray(12));
+}
+
+/**
+ * Converts a private key to a public key.
+ * @param privateKey - The private key to convert.
+ * @returns The public key.
+ */
+export function publicKeyFromPrivateKey(privateKey: Buffer): Buffer {
+  return Buffer.from(secp256k1.getPublicKey(privateKey, false));
+}
+
+/**
+ * Converts a private key to an address.
+ * @param privateKey - The private key to convert.
+ * @returns The address.
+ */
+export function addressFromPrivateKey(privateKey: Buffer): EthAddress {
+  const publicKey = publicKeyFromPrivateKey(privateKey);
+  return publicKeyToAddress(publicKey);
+}
+
+/**
+ * Recovers an address from a hash and a signature.
+ * @param hash - The hash to recover the address from.
+ * @param signature - The signature to recover the address from.
+ * @param opts - Recovery options.
+ * @returns The address.
+ * @throws Error if signature recovery fails or if signature is malleable and allowMalleable is false.
+ */
+export function recoverAddress(hash: Buffer32, signature: Signature, opts?: RecoveryOpts): EthAddress {
+  try {
+    const publicKey = recoverPublicKey(hash, signature, opts);
+    return publicKeyToAddress(publicKey);
+  } catch (err: unknown) {
+    throw new Secp256k1Error(
+      `Error recovering Ethereum address from hash ${hash.toString()} and signature ${signature.toString()}`,
+      { cause: err },
+    );
+  }
+}
+
+/**
+ * Safely attempts to recover an address from a hash and a signature.
+ * @param hash - The hash to recover the address from.
+ * @param signature - The signature to recover the address from.
+ * @param opts - Recovery options.
+ * @returns The address if recovery succeeds, undefined otherwise.
+ */
+export function tryRecoverAddress(hash: Buffer32, signature: Signature, opts?: RecoveryOpts): EthAddress | undefined {
+  try {
+    const publicKey = recoverPublicKey(hash, signature, opts);
+    return publicKeyToAddress(publicKey);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * @attribution - viem
+ * Converts a yParityOrV value to a recovery bit.
+ * @param yParityOrV - The yParityOrV value to convert.
+ * @returns The recovery bit.
+ */
+export function toRecoveryBit(yParityOrV: number) {
+  if (yParityOrV === 0 || yParityOrV === 1) {
+    return yParityOrV;
+  }
+  if (yParityOrV === 27) {
+    return 0;
+  }
+  if (yParityOrV === 28) {
+    return 1;
+  }
+  throw new Secp256k1Error(`Invalid yParityOrV value ${yParityOrV}`);
+}
+
+/**
+ * Signs a message using ecdsa over the secp256k1 curve.
+ * @param message - The message to sign.
+ * @param privateKey - The private key to sign the message with.
+ * @returns The signature.
+ */
+export function signMessage(message: Buffer32, privateKey: Buffer) {
+  const { r, s, recovery } = secp256k1.sign(message.buffer, privateKey);
+  return new Signature(Buffer32.fromBigInt(r), Buffer32.fromBigInt(s), recovery ? 28 : 27);
+}
+
+/**
+ * Flips an ECDSA signature.
+ * If the signature has a low s-value (s < CURVE.n/2), it flips it to high s-value (CURVE.n - s) and vice versa.
+ * Also flips the v value accordingly (27 <-> 28, or 0 <-> 1).
+ * This is useful for testing signature malleability handling.
+ * @param signature - The signature to flip.
+ * @returns A new signature with flipped s-value and v-value.
+ */
+export function flipSignature(signature: Signature): Signature {
+  const { r, s, v } = signature;
+  const sig = new secp256k1.Signature(r.toBigInt(), s.toBigInt());
+  const flippedS = secp256k1.CURVE.n - sig.s;
+
+  return new Signature(r, Buffer32.fromBigInt(flippedS), flipV(v));
+}
+
+/**
+ * Normalizes an ECDSA signature.
+ * If the signature has a high s-value (s >= CURVE.n/2), it flips it to low s-value (CURVE.n - s), and flips v accordingly.
+ * If the signature uses a recovery bit of 0/1, it is converted to a v-value 27/28 for ecrecover.
+ * @remarks This does not handle post EIP155 tx signatures which embed the chain id in v. Use it only for feeding into ECRECOVER precompiles.
+ * @param signature - The signature to normalize.
+ */
+export function normalizeSignature(signature: Signature): Signature {
+  const { r, s, v } = signature;
+  const sig = new secp256k1.Signature(r.toBigInt(), s.toBigInt());
+  if (sig.hasHighS()) {
+    const newV = flipV(v);
+    const newS = sig.normalizeS().s;
+    return new Signature(r, Buffer32.fromBigInt(newS), toVFromYParityOrV(newV));
+  }
+
+  return new Signature(r, s, toVFromYParityOrV(v));
+}
+
+/** Converts a yParityOrV value to a pre-EIP155 v-value 27-28. */
+function toVFromYParityOrV(yParityOrV: number): number {
+  if (yParityOrV === 0 || yParityOrV === 1) {
+    return yParityOrV + 27;
+  } else if (yParityOrV === 27 || yParityOrV === 28) {
+    return yParityOrV;
+  } else {
+    throw new Secp256k1Error(`Invalid yParityOrV value ${yParityOrV}`);
+  }
+}
+
+/** Flips the recovery bit or v-value */
+function flipV(v: number): number {
+  switch (v) {
+    case 27:
+      return 28;
+    case 28:
+      return 27;
+    case 0:
+      return 1;
+    case 1:
+      return 0;
+    default:
+      throw new Secp256k1Error(`Invalid v value ${v}`);
+  }
+}
+
+/**
+ * Recovers a public key from a hash and a signature.
+ * @param hash - The hash to recover the public key from.
+ * @param signature - The signature to recover the public key from.
+ * @returns The public key.
+ */
+export function recoverPublicKey(hash: Buffer32, signature: Signature, opts: RecoveryOpts = {}): Buffer {
+  const { r, s, v } = signature;
+  if (!opts.allowYParityAsV && v !== 27 && v !== 28) {
+    throw new Secp256k1Error(`Invalid v value ${v} (expected 27 or 28)`);
+  }
+  const recoveryBit = toRecoveryBit(v);
+  const sig = new secp256k1.Signature(r.toBigInt(), s.toBigInt()).addRecoveryBit(recoveryBit);
+  if (!opts.allowMalleable && sig.hasHighS()) {
+    throw new Secp256k1Error('Signature has high s-value (malleable signature)');
+  }
+  const publicKey = sig.recoverPublicKey(hash.buffer).toHex(false);
+  return Buffer.from(publicKey, 'hex');
+}
+
+/** Arbitrary hash used for testing signature recoverability. */
+const PROBE_HASH = Buffer32.fromBuffer(keccak256(Buffer.from('signature-recoverability-probe')));
+
+/**
+ * Generates a random valid ECDSA signature that is recoverable to some address.
+ * Since Signature.random() produces real signatures via secp256k1 signing, the result is always
+ * recoverable, but we verify defensively by checking tryRecoverAddress.
+ */
+export function generateRecoverableSignature(): Signature {
+  for (let i = 0; i < 100; i++) {
+    const sig = Signature.random();
+    if (tryRecoverAddress(PROBE_HASH, sig) !== undefined) {
+      return sig;
+    }
+  }
+  throw new Secp256k1Error('Failed to generate a recoverable signature after 100 attempts');
+}
+
+/**
+ * Generates a random signature where ECDSA address recovery fails.
+ * Uses random r/s values (not from real signing) so that r is unlikely to be a valid secp256k1 x-coordinate.
+ */
+export function generateUnrecoverableSignature(): Signature {
+  for (let i = 0; i < 100; i++) {
+    const sig = new Signature(Buffer32.random(), Buffer32.random(), 27);
+    if (tryRecoverAddress(PROBE_HASH, sig) === undefined) {
+      return sig;
+    }
+  }
+  throw new Secp256k1Error('Failed to generate an unrecoverable signature after 100 attempts');
+}