@aztec/stdlib 0.0.0-test.1 → 0.0.1-commit.001888fc

package/src/tx/tx_hash.ts

@@ -1,10 +1,11 @@
-import { Fr } from '@aztec/foundation/fields';
-import { BufferReader } from '@aztec/foundation/serialize';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { BufferReader, serializeArrayOfBufferableToVector } from '@aztec/foundation/serialize';
 
 import { schemas } from '../schemas/index.js';
 
 /**
  * A class representing hash of Aztec transaction.
+ * @dev Computed by hashing the public inputs of the private kernel tail circuit (see Tx::getTxHash function).
  */
 export class TxHash {
   constructor(
@@ -12,10 +13,6 @@ export class TxHash {
     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());
   }
@@ -33,6 +30,10 @@ export class TxHash {
     return new TxHash(new Fr(value));
   }
 
+  static fromField(value: Fr) {
+    return new TxHash(value);
+  }
+
   public toBuffer() {
     return this.hash.toBuffer();
   }
@@ -65,3 +66,23 @@ export class TxHash {
     return Fr.SIZE_IN_BYTES;
   }
 }
+
+/**
+ * Helper class to handle Serialization and Deserialization of TxHashes array.
+ **/
+export class TxHashArray extends Array<TxHash> {
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    try {
+      const reader = BufferReader.asReader(buffer);
+      const hashes = reader.readVector(TxHash);
+
+      return new TxHashArray(...hashes);
+    } catch {
+      return new TxHashArray();
+    }
+  }
+
+  public toBuffer(): Buffer {
+    return serializeArrayOfBufferableToVector([...this]);
+  }
+}

package/src/tx/tx_receipt.ts

@@ -1,20 +1,35 @@
-import type { Fr } from '@aztec/foundation/fields';
-import type { FieldsOf } from '@aztec/foundation/types';
+import { BlockNumber, BlockNumberSchema, EpochNumber, EpochNumberSchema } from '@aztec/foundation/branded-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 { BlockHash } from '../block/block_hash.js';
+import { DebugLog } from '../logs/debug_log.js';
 import { type ZodFor, schemas } from '../schemas/schemas.js';
 import { TxHash } from './tx_hash.js';
 
-/**
- * Possible status of a transaction.
- */
+/** Block inclusion/finalization status. */
 export enum TxStatus {
   DROPPED = 'dropped',
   PENDING = 'pending',
+  PROPOSED = 'proposed',
+  CHECKPOINTED = 'checkpointed',
+  PROVEN = 'proven',
+  FINALIZED = 'finalized',
+}
+
+/** Tx status sorted by finalization progress. */
+export const SortedTxStatuses: TxStatus[] = [
+  TxStatus.DROPPED,
+  TxStatus.PENDING,
+  TxStatus.PROPOSED,
+  TxStatus.CHECKPOINTED,
+  TxStatus.PROVEN,
+  TxStatus.FINALIZED,
+];
+
+/** Execution result - only set when tx is in a block. */
+export enum TxExecutionResult {
   SUCCESS = 'success',
   APP_LOGIC_REVERTED = 'app_logic_reverted',
   TEARDOWN_REVERTED = 'teardown_reverted',
@@ -31,22 +46,60 @@ export class TxReceipt {
   constructor(
     /** A unique identifier for a transaction. */
     public txHash: TxHash,
-    /** The transaction's status. */
+    /** The transaction's block finalization status. */
     public status: TxStatus,
+    /** The execution result of the transaction, only set when tx is in a block. */
+    public executionResult: TxExecutionResult | undefined,
     /** Description of transaction error, if any. */
-    public error: string,
+    public error: string | undefined,
     /** The transaction fee paid for the transaction. */
     public transactionFee?: bigint,
     /** The hash of the block containing the transaction. */
-    public blockHash?: L2BlockHash,
+    public blockHash?: BlockHash,
     /** 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,
+    public blockNumber?: BlockNumber,
+    /** The epoch number in which the transaction was included. */
+    public epochNumber?: EpochNumber,
+    /**
+     * Debug logs collected during public function execution. Served only when the node is in test mode and placed on
+     * the receipt only because it's a convenient place for it (the logs are printed out by the wallet when a mined
+     * tx receipt is obtained).
+     */
+    public debugLogs?: DebugLog[],
   ) {}
 
+  /** Returns true if the transaction was executed successfully. */
+  hasExecutionSucceeded(): boolean {
+    return this.executionResult === TxExecutionResult.SUCCESS;
+  }
+
+  /** Returns true if the transaction execution reverted. */
+  hasExecutionReverted(): boolean {
+    return this.executionResult !== undefined && this.executionResult !== TxExecutionResult.SUCCESS;
+  }
+
+  /** Returns true if the transaction has been included in a block (proposed, checkpointed, proven, or finalized). */
+  isMined(): boolean {
+    return (
+      this.status === TxStatus.PROPOSED ||
+      this.status === TxStatus.CHECKPOINTED ||
+      this.status === TxStatus.PROVEN ||
+      this.status === TxStatus.FINALIZED
+    );
+  }
+
+  /** Returns true if the transaction is pending. */
+  isPending(): boolean {
+    return this.status === TxStatus.PENDING;
+  }
+
+  /** Returns true if the transaction was dropped. */
+  isDropped(): boolean {
+    return this.status === TxStatus.DROPPED;
+  }
+
   static empty() {
-    return new TxReceipt(TxHash.zero(), TxStatus.DROPPED, '');
+    return new TxReceipt(TxHash.zero(), TxStatus.DROPPED, undefined, undefined);
   }
 
   static get schema(): ZodFor<TxReceipt> {
@@ -54,68 +107,52 @@ export class TxReceipt {
       .object({
         txHash: TxHash.schema,
         status: z.nativeEnum(TxStatus),
-        error: z.string(),
-        blockHash: L2BlockHash.schema.optional(),
-        blockNumber: z.number().int().nonnegative().optional(),
+        executionResult: z.nativeEnum(TxExecutionResult).optional(),
+        error: z.string().optional(),
+        blockHash: BlockHash.schema.optional(),
+        blockNumber: BlockNumberSchema.optional(),
+        epochNumber: EpochNumberSchema.optional(),
         transactionFee: schemas.BigInt.optional(),
-        debugInfo: DebugInfoSchema.optional(),
+        debugLogs: z.array(DebugLog.schema).optional(),
       })
-      .transform(TxReceipt.from);
+      .transform(fields => TxReceipt.from(fields));
   }
 
-  static from(fields: FieldsOf<TxReceipt>) {
+  static from(fields: {
+    txHash: TxHash;
+    status: TxStatus;
+    executionResult?: TxExecutionResult;
+    error?: string;
+    transactionFee?: bigint;
+    blockHash?: BlockHash;
+    blockNumber?: BlockNumber;
+    epochNumber?: EpochNumber;
+    debugLogs?: DebugLog[];
+  }) {
     return new TxReceipt(
       fields.txHash,
       fields.status,
+      fields.executionResult,
       fields.error,
       fields.transactionFee,
       fields.blockHash,
       fields.blockNumber,
-      fields.debugInfo,
+      fields.epochNumber,
+      fields.debugLogs,
     );
   }
 
-  public static statusFromRevertCode(revertCode: RevertCode) {
+  public static executionResultFromRevertCode(revertCode: RevertCode): TxExecutionResult {
     if (revertCode.equals(RevertCode.OK)) {
-      return TxStatus.SUCCESS;
+      return TxExecutionResult.SUCCESS;
     } else if (revertCode.equals(RevertCode.APP_LOGIC_REVERTED)) {
-      return TxStatus.APP_LOGIC_REVERTED;
+      return TxExecutionResult.APP_LOGIC_REVERTED;
     } else if (revertCode.equals(RevertCode.TEARDOWN_REVERTED)) {
-      return TxStatus.TEARDOWN_REVERTED;
+      return TxExecutionResult.TEARDOWN_REVERTED;
     } else if (revertCode.equals(RevertCode.BOTH_REVERTED)) {
-      return TxStatus.BOTH_REVERTED;
+      return TxExecutionResult.BOTH_REVERTED;
     } else {
-      throw new Error(`Unknown revert code: ${revertCode}`);
+      throw new Error(`Unknown revert code: ${revertCode.getCode()}`);
     }
   }
 }
-
-/**
- * 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

@@ -1,6 +1,6 @@
-import { GeneratorIndex, TX_REQUEST_LENGTH } from '@aztec/constants';
-import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto';
-import { Fr } from '@aztec/foundation/fields';
+import { DomainSeparator, TX_REQUEST_LENGTH } from '@aztec/constants';
+import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto/poseidon';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { BufferReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
 import type { FieldsOf } from '@aztec/foundation/types';
 
@@ -16,16 +16,19 @@ export class TxRequest {
   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,
+    /** Function data representing the function to call. */
+    public functionData: FunctionData,
+    /** A salt to make the hash difficult to predict. The hash is used as the first nullifier if there is no nullifier emitted throughout the tx. */
+    public salt: Fr,
   ) {}
   // docs:end:constructor
+
   static getFields(fields: FieldsOf<TxRequest>) {
-    return [fields.origin, fields.functionData, fields.argsHash, fields.txContext] as const;
+    return [fields.origin, fields.argsHash, fields.txContext, fields.functionData, fields.salt] as const;
   }
 
   static from(fields: FieldsOf<TxRequest>): TxRequest {
@@ -57,21 +60,28 @@ export class TxRequest {
     const reader = BufferReader.asReader(buffer);
     return new TxRequest(
       reader.readObject(AztecAddress),
-      reader.readObject(FunctionData),
       Fr.fromBuffer(reader),
       reader.readObject(TxContext),
+      reader.readObject(FunctionData),
+      Fr.fromBuffer(reader),
     );
   }
 
   hash() {
-    return poseidon2HashWithSeparator(this.toFields(), GeneratorIndex.TX_REQUEST);
+    return poseidon2HashWithSeparator(this.toFields(), DomainSeparator.TX_REQUEST);
   }
 
   static empty() {
-    return new TxRequest(AztecAddress.ZERO, FunctionData.empty(), Fr.zero(), TxContext.empty());
+    return new TxRequest(AztecAddress.ZERO, Fr.zero(), TxContext.empty(), FunctionData.empty(), Fr.zero());
   }
 
   isEmpty() {
-    return this.origin.isZero() && this.functionData.isEmpty() && this.argsHash.isZero() && this.txContext.isEmpty();
+    return (
+      this.origin.isZero() &&
+      this.argsHash.isZero() &&
+      this.txContext.isEmpty() &&
+      this.functionData.isEmpty() &&
+      this.salt.isZero()
+    );
   }
 }

package/src/tx/validator/empty_validator.ts

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

package/src/tx/validator/error_texts.ts

@@ -0,0 +1,45 @@
+// Gas and fees
+export const TX_ERROR_INSUFFICIENT_FEE_PER_GAS = 'Insufficient fee per gas';
+export const TX_ERROR_INSUFFICIENT_FEE_PAYER_BALANCE = 'Insufficient fee payer balance';
+export const TX_ERROR_INSUFFICIENT_GAS_LIMIT = 'Gas limit is below the minimum fixed cost';
+export const TX_ERROR_GAS_LIMIT_TOO_HIGH = 'Gas limit is higher than the amount of gas that the AVM can process';
+
+// Phases
+export const TX_ERROR_SETUP_FUNCTION_NOT_ALLOWED = 'Setup function not on allow list';
+export const TX_ERROR_SETUP_FUNCTION_UNKNOWN_CONTRACT = 'Setup function targets unknown contract';
+export const TX_ERROR_SETUP_ONLY_SELF_WRONG_SENDER = 'Setup only_self function called with incorrect msg_sender';
+export const TX_ERROR_SETUP_NULL_MSG_SENDER = 'Setup function called with null msg sender';
+export const TX_ERROR_SETUP_WRONG_CALLDATA_LENGTH = 'Setup function called with wrong calldata length';
+
+// Nullifiers
+export const TX_ERROR_DUPLICATE_NULLIFIER_IN_TX = 'Duplicate nullifier in tx';
+export const TX_ERROR_EXISTING_NULLIFIER = 'Existing nullifier';
+
+// Metadata
+export const TX_ERROR_INVALID_EXPIRATION_TIMESTAMP = 'Invalid expiration timestamp';
+export const TX_ERROR_INCORRECT_L1_CHAIN_ID = 'Incorrect L1 chain id';
+export const TX_ERROR_INCORRECT_ROLLUP_VERSION = 'Incorrect rollup version';
+export const TX_ERROR_INCORRECT_VK_TREE_ROOT = 'Incorrect verification keys tree root';
+export const TX_ERROR_INCORRECT_PROTOCOL_CONTRACTS_HASH = 'Incorrect protocol contracts hash';
+
+// Proof
+export const TX_ERROR_INVALID_PROOF = 'Invalid proof';
+
+//Data
+export const TX_ERROR_INCORRECT_CALLDATA = 'Incorrect calldata for public call';
+export const TX_ERROR_CALLDATA_COUNT_MISMATCH = 'Wrong number of calldata for public calls';
+export const TX_ERROR_CALLDATA_COUNT_TOO_LARGE = 'Total calldata too large for enqueued public calls';
+export const TX_ERROR_CONTRACT_CLASS_LOG_COUNT = 'Mismatched number of contract class logs';
+export const TX_ERROR_CONTRACT_CLASS_LOG_LENGTH = 'Incorrect contract class logs length';
+export const TX_ERROR_CONTRACT_CLASS_LOGS = 'Mismatched contract class logs';
+export const TX_ERROR_CONTRACT_CLASS_LOG_SORTING = 'Incorrectly sorted contract class logs';
+export const TX_ERROR_INCORRECT_HASH = 'Incorrect tx hash';
+
+// Size
+export const TX_ERROR_SIZE_ABOVE_LIMIT = 'Transaction size above size limit';
+
+// Block header
+export const TX_ERROR_BLOCK_HEADER = 'Block header not found';
+
+// General
+export const TX_ERROR_DURING_VALIDATION = 'Unexpected error during validation';

package/src/tx/validator/tx_validator.ts

@@ -1,11 +1,16 @@
 import { z } from 'zod';
 
-import type { ZodFor } from '../../schemas/schemas.js';
+import { zodFor } from '../../schemas/schemas.js';
 import type { ProcessedTx } from '../processed_tx.js';
 import type { Tx } from '../tx.js';
+import type { TxHash } from '../tx_hash.js';
 
 export type AnyTx = Tx | ProcessedTx;
 
+export function getTxHash(tx: AnyTx): TxHash {
+  return 'txHash' in tx ? tx.txHash : tx.hash;
+}
+
 export function hasPublicCalls(tx: AnyTx): boolean {
   return tx.data.numberOfPublicCallRequests() > 0;
 }
@@ -15,12 +20,14 @@ export type TxValidationResult =
   | { result: 'invalid'; reason: string[] }
   | { result: 'skipped'; reason: string[] };
 
-export interface TxValidator<T extends AnyTx = AnyTx> {
+export interface TxValidator<T = 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>;
+export const TxValidationResultSchema = zodFor<TxValidationResult>()(
+  z.discriminatedUnion('result', [
+    z.object({ result: z.literal('valid') }),
+    z.object({ result: z.literal('invalid'), reason: z.array(z.string()) }),
+    z.object({ result: z.literal('skipped'), reason: z.array(z.string()) }),
+  ]),
+);

package/src/types/shared.ts

@@ -25,6 +25,16 @@ export class Vector<T extends Bufferable> {
  */
 export type UInt32 = number;
 
+/**
+ * A type alias for a 64-bit unsigned integer.
+ */
+export type UInt64 = bigint;
+
+/**
+ * A type alias for a 128-bit unsigned integer.
+ */
+export type UInt128 = bigint;
+
 /**
  * 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;
@@ -34,12 +44,3 @@ export enum CircuitType {
   STANDARD = 0,
   ULTRA = 1,
 }
-
-/**
- * Rollup types.
- */
-export enum RollupTypes {
-  Base = 0,
-  Merge = 1,
-  Root = 2,
-}

package/src/update-checker/index.ts

@@ -0,0 +1,2 @@
+export * from './package_version.js';
+export * from './version_checker.js';

package/src/update-checker/package_version.ts

@@ -0,0 +1,30 @@
+import { fileURLToPath } from '@aztec/foundation/url';
+
+import { readFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+
+/** Returns the package version from the release-please manifest or the package.json, or undefined if not found. */
+export function getPackageVersion(): string | undefined {
+  const dir = dirname(fileURLToPath(import.meta.url));
+
+  // Try the release-please manifest first (works in dev/repo checkout).
+  try {
+    const releasePleaseManifestPath = resolve(dir, '../../../../.release-please-manifest.json');
+    return JSON.parse(readFileSync(releasePleaseManifestPath).toString())['.'];
+  } catch {
+    // Not in a repo checkout, fall through.
+  }
+
+  // Fall back to the stdlib package.json version (works in npm-installed packages).
+  try {
+    const packageJsonPath = resolve(dir, '../../package.json');
+    const version = JSON.parse(readFileSync(packageJsonPath).toString()).version;
+    if (version && version !== '0.1.0') {
+      return version;
+    }
+  } catch {
+    // No package.json found either.
+  }
+
+  return undefined;
+}

package/src/update-checker/version_checker.ts

@@ -0,0 +1,65 @@
+import { createLogger } from '@aztec/foundation/log';
+import { RunningPromise } from '@aztec/foundation/promise';
+
+import { EventEmitter } from 'node:events';
+
+export type EventMap = {
+  newVersion: [{ name: string; currentVersion: string; latestVersion: string }];
+};
+
+export type VersionCheck = {
+  name: string;
+  currentVersion: string;
+  getLatestVersion: () => Promise<string | undefined>;
+};
+
+export class VersionChecker extends EventEmitter<EventMap> {
+  private runningPromise: RunningPromise;
+  constructor(
+    private checks: Array<VersionCheck>,
+    intervalCheckMs = 60_000,
+    private logger = createLogger('version_checker'),
+  ) {
+    super();
+    this.runningPromise = new RunningPromise(this.run, logger, intervalCheckMs);
+  }
+
+  public start(): void {
+    if (this.runningPromise.isRunning()) {
+      this.logger.warn('VersionChecker is already running');
+      return;
+    }
+
+    this.runningPromise.start();
+    this.logger.info('Version check started');
+  }
+
+  public trigger(): Promise<void> {
+    return this.runningPromise.trigger();
+  }
+
+  public async stop(): Promise<void> {
+    if (!this.runningPromise.isRunning()) {
+      this.logger.warn('VersionChecker is not running');
+      return;
+    }
+
+    await this.runningPromise.stop();
+    this.logger.info('Version checker stopped');
+  }
+
+  private run = async () => {
+    await Promise.allSettled(this.checks.map(check => this.checkVersion(check)));
+  };
+
+  private async checkVersion({ name, currentVersion, getLatestVersion }: VersionCheck): Promise<void> {
+    try {
+      const latestVersion = await getLatestVersion();
+      if (latestVersion && latestVersion !== currentVersion) {
+        this.emit('newVersion', { name, latestVersion, currentVersion });
+      }
+    } catch (err) {
+      this.logger.warn(`Error checking for new ${name} versions: ${err}`, { err });
+    }
+  }
+}

package/src/validators/errors.ts

@@ -0,0 +1,67 @@
+import type { SlotNumber } from '@aztec/foundation/branded-types';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { TxHash } from '@aztec/stdlib/tx';
+
+export class ValidatorError extends Error {
+  constructor(message: string) {
+    super(`Validator Error: ${message}`);
+  }
+}
+
+export class InvalidValidatorPrivateKeyError extends ValidatorError {
+  constructor() {
+    super('Invalid validator private key provided');
+  }
+}
+
+export class AttestationTimeoutError extends ValidatorError {
+  constructor(
+    public readonly collectedCount: number,
+    public readonly requiredCount: number,
+    public readonly slot: SlotNumber,
+  ) {
+    super(`Timeout collecting attestations for slot ${slot}: ${collectedCount}/${requiredCount}`);
+  }
+}
+
+export class TransactionsNotAvailableError extends ValidatorError {
+  constructor(txHashes: TxHash[]) {
+    super(`Transactions not available: ${txHashes.join(', ')}`);
+  }
+}
+
+export class FailedToReExecuteTransactionsError extends ValidatorError {
+  constructor(txHashes: TxHash[]) {
+    super(`Failed to re-execute transactions: ${txHashes.join(', ')}`);
+  }
+}
+
+export class ReExInitialStateMismatchError extends ValidatorError {
+  constructor(
+    public readonly expectedArchiveRoot: Fr,
+    public readonly actualArchiveRoot: Fr,
+  ) {
+    super('Re-execution initial state mismatch');
+  }
+}
+
+export class ReExStateMismatchError extends ValidatorError {
+  constructor(
+    public readonly expectedArchiveRoot: Fr,
+    public readonly actualArchiveRoot: Fr,
+  ) {
+    super('Re-execution state mismatch');
+  }
+}
+
+export class ReExFailedTxsError extends ValidatorError {
+  constructor(numFailedTxs: number) {
+    super(`Re-execution failed to process ${numFailedTxs} txs`);
+  }
+}
+
+export class ReExTimeoutError extends ValidatorError {
+  constructor() {
+    super('Re-execution timed out or failed to process all txs in the proposal');
+  }
+}

package/src/validators/index.ts

@@ -0,0 +1,3 @@
+export * from './errors.js';
+export * from './schemas.js';
+export type * from './types.js';