@aztec/stdlib 0.77.0-testnet-ignition.17

package/src/tx/tx_hash.ts

@@ -0,0 +1,67 @@
+import { Fr } from '@aztec/foundation/fields';
+import { BufferReader } from '@aztec/foundation/serialize';
+
+import { schemas } from '../schemas/index.js';
+
+/**
+ * A class representing hash of Aztec transaction.
+ */
+export class TxHash {
+  constructor(
+    /** A field representing the tx hash (tx hash is an output of poseidon hash hence it's a field). */
+    public readonly hash: Fr,
+  ) {}
+
+  /*
+   * TxHashes are generated from the first nullifier of a transaction, which is a Fr.
+   * @returns A random TxHash.
+   */
+  static random() {
+    return new TxHash(Fr.random());
+  }
+
+  static fromBuffer(buffer: Uint8Array | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new this(reader.readObject(Fr));
+  }
+
+  static fromString(str: string) {
+    return new TxHash(Fr.fromString(str));
+  }
+
+  static fromBigInt(value: bigint) {
+    return new TxHash(new Fr(value));
+  }
+
+  public toBuffer() {
+    return this.hash.toBuffer();
+  }
+
+  public toString() {
+    return this.hash.toString();
+  }
+
+  public toBigInt() {
+    return this.hash.toBigInt();
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  public equals(other: TxHash) {
+    return this.hash.equals(other.hash);
+  }
+
+  static get schema() {
+    return schemas.BufferHex.transform(value => new TxHash(Fr.fromBuffer(value)));
+  }
+
+  static zero() {
+    return new TxHash(Fr.ZERO);
+  }
+
+  static get SIZE() {
+    return Fr.SIZE_IN_BYTES;
+  }
+}

package/src/tx/tx_receipt.ts

@@ -0,0 +1,121 @@
+import type { Fr } from '@aztec/foundation/fields';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { z } from 'zod';
+
+import { PublicDataWrite } from '../avm/public_data_write.js';
+import { RevertCode } from '../avm/revert_code.js';
+import { L2BlockHash } from '../block/block_hash.js';
+import { type ZodFor, schemas } from '../schemas/schemas.js';
+import { TxHash } from './tx_hash.js';
+
+/**
+ * Possible status of a transaction.
+ */
+export enum TxStatus {
+  DROPPED = 'dropped',
+  PENDING = 'pending',
+  SUCCESS = 'success',
+  APP_LOGIC_REVERTED = 'app_logic_reverted',
+  TEARDOWN_REVERTED = 'teardown_reverted',
+  BOTH_REVERTED = 'both_reverted',
+}
+
+/**
+ * Represents a transaction receipt in the Aztec network.
+ * Contains essential information about the transaction including its status, origin, and associated addresses.
+ * REFACTOR: TxReceipt should be returned only once the tx is mined, and all its fields should be required.
+ * We should not be using a TxReceipt to answer a query for a pending or dropped tx.
+ */
+export class TxReceipt {
+  constructor(
+    /** A unique identifier for a transaction. */
+    public txHash: TxHash,
+    /** The transaction's status. */
+    public status: TxStatus,
+    /** Description of transaction error, if any. */
+    public error: string,
+    /** The transaction fee paid for the transaction. */
+    public transactionFee?: bigint,
+    /** The hash of the block containing the transaction. */
+    public blockHash?: L2BlockHash,
+    /** The block number in which the transaction was included. */
+    public blockNumber?: number,
+    /** Information useful for testing/debugging, set when test flag is set to true in `waitOpts`. */
+    public debugInfo?: DebugInfo,
+  ) {}
+
+  static empty() {
+    return new TxReceipt(TxHash.zero(), TxStatus.DROPPED, '');
+  }
+
+  static get schema(): ZodFor<TxReceipt> {
+    return z
+      .object({
+        txHash: TxHash.schema,
+        status: z.nativeEnum(TxStatus),
+        error: z.string(),
+        blockHash: L2BlockHash.schema.optional(),
+        blockNumber: z.number().optional(),
+        transactionFee: schemas.BigInt.optional(),
+        debugInfo: DebugInfoSchema.optional(),
+      })
+      .transform(TxReceipt.from);
+  }
+
+  static from(fields: FieldsOf<TxReceipt>) {
+    return new TxReceipt(
+      fields.txHash,
+      fields.status,
+      fields.error,
+      fields.transactionFee,
+      fields.blockHash,
+      fields.blockNumber,
+      fields.debugInfo,
+    );
+  }
+
+  public static statusFromRevertCode(revertCode: RevertCode) {
+    if (revertCode.equals(RevertCode.OK)) {
+      return TxStatus.SUCCESS;
+    } else if (revertCode.equals(RevertCode.APP_LOGIC_REVERTED)) {
+      return TxStatus.APP_LOGIC_REVERTED;
+    } else if (revertCode.equals(RevertCode.TEARDOWN_REVERTED)) {
+      return TxStatus.TEARDOWN_REVERTED;
+    } else if (revertCode.equals(RevertCode.BOTH_REVERTED)) {
+      return TxStatus.BOTH_REVERTED;
+    } else {
+      throw new Error(`Unknown revert code: ${revertCode}`);
+    }
+  }
+}
+
+/**
+ * Information useful for debugging/testing purposes included in the receipt when the debug flag is set to true
+ * in `WaitOpts`.
+ */
+interface DebugInfo {
+  /**
+   * New note hashes created by the transaction.
+   */
+  noteHashes: Fr[];
+  /**
+   * New nullifiers created by the transaction.
+   */
+  nullifiers: Fr[];
+  /**
+   * New public data writes created by the transaction.
+   */
+  publicDataWrites: PublicDataWrite[];
+  /**
+   * New L2 to L1 messages created by the transaction.
+   */
+  l2ToL1Msgs: Fr[];
+}
+
+const DebugInfoSchema = z.object({
+  noteHashes: z.array(schemas.Fr),
+  nullifiers: z.array(schemas.Fr),
+  publicDataWrites: z.array(PublicDataWrite.schema),
+  l2ToL1Msgs: z.array(schemas.Fr),
+});

package/src/tx/tx_request.ts

@@ -0,0 +1,77 @@
+import { GeneratorIndex, TX_REQUEST_LENGTH } from '@aztec/constants';
+import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto';
+import { Fr } from '@aztec/foundation/fields';
+import { BufferReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { AztecAddress } from '../aztec-address/index.js';
+import { FunctionData } from './function_data.js';
+import { TxContext } from './tx_context.js';
+
+/**
+ * Transaction request.
+ */
+export class TxRequest {
+  // docs:start:constructor
+  constructor(
+    /** Sender. */
+    public origin: AztecAddress,
+    /** Function data representing the function to call. */
+    public functionData: FunctionData,
+    /** Pedersen hash of function arguments. */
+    public argsHash: Fr,
+    /** Transaction context. */
+    public txContext: TxContext,
+  ) {}
+  // docs:end:constructor
+  static getFields(fields: FieldsOf<TxRequest>) {
+    return [fields.origin, fields.functionData, fields.argsHash, fields.txContext] as const;
+  }
+
+  static from(fields: FieldsOf<TxRequest>): TxRequest {
+    return new TxRequest(...TxRequest.getFields(fields));
+  }
+
+  /**
+   * Serialize as a buffer.
+   * @returns The buffer.
+   */
+  toBuffer() {
+    return serializeToBuffer([...TxRequest.getFields(this)]);
+  }
+
+  toFields(): Fr[] {
+    const fields = serializeToFields(...TxRequest.getFields(this));
+    if (fields.length !== TX_REQUEST_LENGTH) {
+      throw new Error(`Invalid number of fields for TxRequest. Expected ${TX_REQUEST_LENGTH}, got ${fields.length}`);
+    }
+    return fields;
+  }
+
+  /**
+   * Deserializes from a buffer or reader, corresponding to a write in cpp.
+   * @param buffer - Buffer to read from.
+   * @returns The deserialized TxRequest object.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader): TxRequest {
+    const reader = BufferReader.asReader(buffer);
+    return new TxRequest(
+      reader.readObject(AztecAddress),
+      reader.readObject(FunctionData),
+      Fr.fromBuffer(reader),
+      reader.readObject(TxContext),
+    );
+  }
+
+  hash() {
+    return poseidon2HashWithSeparator(this.toFields(), GeneratorIndex.TX_REQUEST);
+  }
+
+  static empty() {
+    return new TxRequest(AztecAddress.ZERO, FunctionData.empty(), Fr.zero(), TxContext.empty());
+  }
+
+  isEmpty() {
+    return this.origin.isZero() && this.functionData.isEmpty() && this.argsHash.isZero() && this.txContext.isEmpty();
+  }
+}

package/src/tx/validator/empty_validator.ts

@@ -0,0 +1,7 @@
+import type { AnyTx, TxValidationResult, TxValidator } from './tx_validator.js';
+
+export class EmptyTxValidator<T extends AnyTx = AnyTx> implements TxValidator<T> {
+  public validateTx(_tx: T): Promise<TxValidationResult> {
+    return Promise.resolve({ result: 'valid' });
+  }
+}

package/src/tx/validator/tx_validator.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+
+import type { ZodFor } from '../../schemas/schemas.js';
+import type { ProcessedTx } from '../processed_tx.js';
+import type { Tx } from '../tx.js';
+
+export type AnyTx = Tx | ProcessedTx;
+
+export function hasPublicCalls(tx: AnyTx): boolean {
+  return tx.data.numberOfPublicCallRequests() > 0;
+}
+
+export type TxValidationResult =
+  | { result: 'valid' }
+  | { result: 'invalid'; reason: string[] }
+  | { result: 'skipped'; reason: string[] };
+
+export interface TxValidator<T extends AnyTx = AnyTx> {
+  validateTx(tx: T): Promise<TxValidationResult>;
+}
+
+export const TxValidationResultSchema = z.discriminatedUnion('result', [
+  z.object({ result: z.literal('valid'), reason: z.array(z.string()).optional() }),
+  z.object({ result: z.literal('invalid'), reason: z.array(z.string()) }),
+  z.object({ result: z.literal('skipped'), reason: z.array(z.string()) }),
+]) satisfies ZodFor<TxValidationResult>;

package/src/types/index.ts

@@ -0,0 +1 @@
+export * from './shared.js';

package/src/types/shared.ts

@@ -0,0 +1,45 @@
+import { type Bufferable, serializeToBuffer } from '@aztec/foundation/serialize';
+
+/**
+ * Implementation of a vector. Matches how we are serializing and deserializing vectors in cpp (length in the first position, followed by the items).
+ */
+export class Vector<T extends Bufferable> {
+  constructor(
+    /**
+     * Items in the vector.
+     */
+    public items: T[],
+  ) {}
+
+  toBuffer() {
+    return serializeToBuffer(this.items.length, this.items);
+  }
+
+  toFriendlyJSON() {
+    return this.items;
+  }
+}
+
+/**
+ * A type alias for a 32-bit unsigned integer.
+ */
+export type UInt32 = number;
+
+/**
+ * CircuitType replaces ComposerType for now. When using Plonk, CircuitType is equivalent to the information of the proving system that will be used
+ * to construct a proof. In the future Aztec zk stack, more information must be specified (e.g., the curve over which circuits are  constructed;
+ * Plonk vs Honk; zk-SNARK or just SNARK; etc).
+ */
+export enum CircuitType {
+  STANDARD = 0,
+  ULTRA = 1,
+}
+
+/**
+ * Rollup types.
+ */
+export enum RollupTypes {
+  Base = 0,
+  Merge = 1,
+  Root = 2,
+}

package/src/versioning/index.ts

@@ -0,0 +1 @@
+export * from './versioning.js';

package/src/versioning/versioning.ts

@@ -0,0 +1,153 @@
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { Fr } from '@aztec/foundation/fields';
+import { jsonStringify } from '@aztec/foundation/json-rpc';
+
+import type Koa from 'koa';
+
+import type { ChainConfig } from '../config/config.js';
+
+// REFACTOR: This file is not a circuit-type, but at the moment we don't have any other
+// package common to all components that we can use for this shared code.
+
+/** Fields that identify a version of the Aztec protocol. Any mismatch between these fields should signal an incompatibility between nodes. */
+export type ComponentsVersions = {
+  l1ChainId: number;
+  // TODO: Consider using governance address instead to support migrations.
+  // Note that we are using the rollup address as identifier in multiple places
+  // such as the keystore, we need to change it so we can handle updates.
+  l1RollupAddress: EthAddress;
+  l2ChainVersion: number;
+  l2ProtocolContractsTreeRoot: string;
+  l2CircuitsVkTreeRoot: string;
+};
+
+/** Returns components versions from chain config. */
+export function getComponentsVersionsFromConfig(
+  config: ChainConfig,
+  l2ProtocolContractsTreeRoot: string | Fr,
+  l2CircuitsVkTreeRoot: string | Fr,
+): ComponentsVersions {
+  return {
+    l1ChainId: config.l1ChainId,
+    l1RollupAddress: config.l1Contracts?.rollupAddress, // This should not be undefined, but sometimes the config lies to us and it is...
+    l2ChainVersion: config.version,
+    l2ProtocolContractsTreeRoot: l2ProtocolContractsTreeRoot.toString(),
+    l2CircuitsVkTreeRoot: l2CircuitsVkTreeRoot.toString(),
+  };
+}
+
+/** Returns a compressed string representation of the version (around 32 chars). Used in p2p ENRs. */
+export function compressComponentVersions(versions: ComponentsVersions): string {
+  if (
+    versions.l1RollupAddress === undefined ||
+    versions.l2ProtocolContractsTreeRoot === undefined ||
+    versions.l2CircuitsVkTreeRoot === undefined
+  ) {
+    throw new Error(`Component versions are not set: ${jsonStringify(versions)}`);
+  }
+
+  return [
+    '00',
+    versions.l1ChainId,
+    versions.l1RollupAddress.toString().slice(2, 10),
+    versions.l2ChainVersion,
+    versions.l2ProtocolContractsTreeRoot.toString().slice(2, 10),
+    versions.l2CircuitsVkTreeRoot.toString().slice(2, 10),
+  ].join('-');
+}
+
+export class ComponentsVersionsError extends Error {
+  constructor(key: string, expected: string, value: string) {
+    super(`Expected component version ${key} to be ${expected} but received ${value}`);
+    this.name = 'ComponentsVersionsError';
+  }
+}
+
+/** Checks if the compressed string matches against the expected versions. Throws on mismatch. */
+export function checkCompressedComponentVersion(compressed: string, expected: ComponentsVersions) {
+  const [
+    versionVersion,
+    l1ChainId,
+    l1RollupAddress,
+    l2ChainVersion,
+    l2ProtocolContractsTreeRoot,
+    l2CircuitsVkTreeRoot,
+  ] = compressed.split('-');
+  if (versionVersion !== '00') {
+    throw new ComponentsVersionsError('version', '00', versionVersion);
+  }
+  if (l1ChainId !== expected.l1ChainId.toString()) {
+    throw new ComponentsVersionsError(`L1 chain ID`, expected.l1ChainId.toString(), l1ChainId);
+  }
+  if (l1RollupAddress !== expected.l1RollupAddress.toString().slice(2, 10)) {
+    throw new ComponentsVersionsError(`L1 address`, expected.l1RollupAddress.toString(), l1RollupAddress);
+  }
+  if (l2ChainVersion !== expected.l2ChainVersion.toString()) {
+    throw new ComponentsVersionsError('L2 chain version', expected.l2ChainVersion.toString(), l2ChainVersion);
+  }
+  if (l2ProtocolContractsTreeRoot !== expected.l2ProtocolContractsTreeRoot.toString().slice(2, 10)) {
+    throw new ComponentsVersionsError(
+      `L2 protocol contracts vk tree root`,
+      expected.l2ProtocolContractsTreeRoot.toString(),
+      l2ProtocolContractsTreeRoot,
+    );
+  }
+  if (l2CircuitsVkTreeRoot !== expected.l2CircuitsVkTreeRoot.toString().slice(2, 10)) {
+    throw new ComponentsVersionsError(
+      'L2 circuits vk tree root',
+      expected.l2CircuitsVkTreeRoot.toString(),
+      l2CircuitsVkTreeRoot,
+    );
+  }
+}
+
+/** Checks that two component versions match. Undefined fields are ignored. */
+export function validatePartialComponentVersionsMatch(
+  expected: Partial<ComponentsVersions>,
+  actual: Partial<ComponentsVersions>,
+) {
+  for (const key of [
+    'l1RollupAddress',
+    'l2ProtocolContractsTreeRoot',
+    'l2CircuitsVkTreeRoot',
+    'l1ChainId',
+    'l2ChainVersion',
+  ] as const) {
+    const actualValue = actual[key];
+    const expectedValue = expected[key];
+    if (expectedValue !== undefined && actualValue !== undefined) {
+      if (typeof actualValue === 'object' ? !actualValue.equals(expectedValue as any) : actualValue !== expectedValue) {
+        throw new Error(`Expected ${key} to be ${expectedValue} but received ${actualValue}`);
+      }
+    }
+  }
+}
+
+/** Returns a Koa middleware that injects the versioning info as headers. */
+export function getVersioningMiddleware(versions: Partial<ComponentsVersions>) {
+  return async (ctx: Koa.Context, next: () => Promise<void>) => {
+    await next();
+    for (const key in versions) {
+      const value = versions[key as keyof ComponentsVersions];
+      if (value !== undefined) {
+        ctx.set(`x-aztec-${key}`, value.toString());
+      }
+    }
+  };
+}
+
+/** Returns a json rpc client handler that rejects responses with mismatching versions. */
+export function getVersioningResponseHandler(versions: Partial<ComponentsVersions>) {
+  return ({ headers }: { headers: { get: (header: string) => string | null | undefined } }) => {
+    for (const key in versions) {
+      const value = versions[key as keyof ComponentsVersions];
+      if (value !== undefined) {
+        const headerValue = headers.get(`x-aztec-${key}`);
+        if (headerValue !== undefined && headerValue !== null && headerValue !== value.toString()) {
+          throw new ComponentsVersionsError(key, value.toString(), headerValue);
+        }
+      }
+    }
+    return Promise.resolve();
+  };
+}

package/src/vks/index.ts

@@ -0,0 +1,2 @@
+export * from './verification_key.js';
+export * from './vk_witness_data.js';