@aztec/stdlib 0.77.0-testnet-ignition.17

package/src/tx/tx.ts

@@ -0,0 +1,364 @@
+import { Buffer32 } from '@aztec/foundation/buffer';
+import { arraySerializedSizeOfNonEmpty } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/fields';
+import type { ZodFor } from '@aztec/foundation/schemas';
+import { BufferReader, serializeArrayOfBufferableToVector, serializeToBuffer } from '@aztec/foundation/serialize';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { z } from 'zod';
+
+import type { GasSettings } from '../gas/gas_settings.js';
+import { siloContractClassLog } from '../hash/hash.js';
+import type { GetPublicLogsResponse } from '../interfaces/get_logs_response.js';
+import type { L2LogsSource } from '../interfaces/l2_logs_source.js';
+import type { ScopedLogHash } from '../kernel/log_hash.js';
+import { PrivateKernelTailCircuitPublicInputs } from '../kernel/private_kernel_tail_circuit_public_inputs.js';
+import { ContractClassLog } from '../logs/contract_class_log.js';
+import { PrivateLog } from '../logs/private_log.js';
+import { Gossipable } from '../p2p/gossipable.js';
+import { TopicType, createTopicString } from '../p2p/topic_type.js';
+import { ClientIvcProof } from '../proofs/client_ivc_proof.js';
+import type { TxStats } from '../stats/stats.js';
+import { PublicExecutionRequest } from './public_execution_request.js';
+import { TxHash } from './tx_hash.js';
+
+/**
+ * The interface of an L2 transaction.
+ */
+export class Tx extends Gossipable {
+  static override p2pTopic: string;
+  // For memoization
+  private txHash: TxHash | undefined;
+
+  constructor(
+    /**
+     * Output of the private kernel circuit for this tx.
+     */
+    public readonly data: PrivateKernelTailCircuitPublicInputs,
+    /**
+     * Proof from the private kernel circuit.
+     * TODO(#7368): This client IVC object currently contains various VKs that will eventually be more like static data.
+     *
+     */
+    public readonly clientIvcProof: ClientIvcProof,
+    /**
+     * Contract class logs generated by the tx.
+     */
+    public contractClassLogs: ContractClassLog[],
+    /**
+     * Enqueued public functions from the private circuit to be run by the sequencer.
+     */
+    public readonly enqueuedPublicFunctionCalls: PublicExecutionRequest[],
+    /**
+     * Public function call to be run by the sequencer as part of teardown.
+     */
+    public readonly publicTeardownFunctionCall: PublicExecutionRequest,
+  ) {
+    super();
+  }
+
+  // Gossipable method
+  static {
+    this.p2pTopic = createTopicString(TopicType.tx);
+  }
+
+  // Gossipable method
+  override async p2pMessageIdentifier(): Promise<Buffer32> {
+    return new Buffer32((await this.getTxHash()).toBuffer());
+  }
+
+  hasPublicCalls() {
+    return this.data.numberOfPublicCallRequests() > 0;
+  }
+
+  getNonRevertiblePublicExecutionRequests(): PublicExecutionRequest[] {
+    const numRevertible = this.data.numberOfRevertiblePublicCallRequests();
+    return this.enqueuedPublicFunctionCalls.slice(numRevertible);
+  }
+
+  getRevertiblePublicExecutionRequests(): PublicExecutionRequest[] {
+    const numRevertible = this.data.numberOfRevertiblePublicCallRequests();
+    return this.enqueuedPublicFunctionCalls.slice(0, numRevertible);
+  }
+
+  getPublicTeardownExecutionRequest(): PublicExecutionRequest | undefined {
+    return this.publicTeardownFunctionCall.isEmpty() ? undefined : this.publicTeardownFunctionCall;
+  }
+
+  getTotalPublicArgsCount(): number {
+    let count = this.enqueuedPublicFunctionCalls.reduce((acc, execRequest) => acc + execRequest.args.length, 0);
+    if (!this.publicTeardownFunctionCall.isEmpty()) {
+      count += this.publicTeardownFunctionCall.args.length;
+    }
+    return count;
+  }
+
+  getGasSettings(): GasSettings {
+    return this.data.constants.txContext.gasSettings;
+  }
+
+  /**
+   * Deserializes the Tx object from a Buffer.
+   * @param buffer - Buffer or BufferReader object to deserialize.
+   * @returns An instance of Tx.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader): Tx {
+    const reader = BufferReader.asReader(buffer);
+    return new Tx(
+      reader.readObject(PrivateKernelTailCircuitPublicInputs),
+      reader.readObject(ClientIvcProof),
+      reader.readVectorUint8Prefix(ContractClassLog),
+      reader.readVectorUint8Prefix(PublicExecutionRequest),
+      reader.readObject(PublicExecutionRequest),
+    );
+  }
+
+  static newWithTxData(
+    data: PrivateKernelTailCircuitPublicInputs,
+    publicTeardownExecutionRequest?: PublicExecutionRequest,
+  ) {
+    return new Tx(
+      data,
+      ClientIvcProof.empty(),
+      [],
+      [],
+      publicTeardownExecutionRequest ? publicTeardownExecutionRequest : PublicExecutionRequest.empty(),
+    );
+  }
+
+  /**
+   * Serializes the Tx object into a Buffer.
+   * @returns Buffer representation of the Tx object.
+   */
+  toBuffer() {
+    return serializeToBuffer([
+      this.data,
+      this.clientIvcProof,
+      serializeArrayOfBufferableToVector(this.contractClassLogs, 1),
+      serializeArrayOfBufferableToVector(this.enqueuedPublicFunctionCalls, 1),
+      this.publicTeardownFunctionCall,
+    ]);
+  }
+
+  static get schema(): ZodFor<Tx> {
+    return z
+      .object({
+        data: PrivateKernelTailCircuitPublicInputs.schema,
+        clientIvcProof: ClientIvcProof.schema,
+        contractClassLogs: z.array(ContractClassLog.schema),
+        enqueuedPublicFunctionCalls: z.array(PublicExecutionRequest.schema),
+        publicTeardownFunctionCall: PublicExecutionRequest.schema,
+      })
+      .transform(Tx.from);
+  }
+
+  static from(fields: FieldsOf<Tx>) {
+    return new Tx(
+      fields.data,
+      fields.clientIvcProof,
+      fields.contractClassLogs,
+      fields.enqueuedPublicFunctionCalls,
+      fields.publicTeardownFunctionCall,
+    );
+  }
+
+  /**
+   * Gets public logs emitted by this tx.
+   * @param logsSource - An instance of `L2LogsSource` which can be used to obtain the logs.
+   * @returns The requested logs.
+   */
+  public async getPublicLogs(logsSource: L2LogsSource): Promise<GetPublicLogsResponse> {
+    return logsSource.getPublicLogs({ txHash: await this.getTxHash() });
+  }
+
+  /**
+   * Gets either revertible or non revertible contract class logs emitted by this tx.
+   * @param revertible - true for revertible only logs, false for non reverible only logs.
+   * @returns The requested logs.
+   */
+  async getSplitContractClassLogs(revertible: boolean, silo: boolean = false): Promise<ContractClassLog[]> {
+    // Should only be called on txs with public calls
+    if (!this.data.forPublic) {
+      return [];
+    }
+    const contractClassLogsHashes = revertible
+      ? this.data.forPublic.revertibleAccumulatedData.contractClassLogsHashes.filter(h => !h.isEmpty())
+      : this.data.forPublic.nonRevertibleAccumulatedData.contractClassLogsHashes.filter(h => !h.isEmpty());
+    return await this.filterContractClassLogs(contractClassLogsHashes, silo);
+  }
+
+  /**
+   * Filters contract class logs emitted by this tx.
+   * @param logHashes - logs to keep represented by their hashes.
+   * @param silo - whether to silo the logs before returning them.
+   * @returns The requested logs.
+   */
+  async filterContractClassLogs(logHashes: ScopedLogHash[], silo: boolean = false): Promise<ContractClassLog[]> {
+    const contractClassLogs = [];
+    for (const log of this.contractClassLogs) {
+      const hashedLog = await log.hash();
+      const logHash = logHashes.find(hash => hash.value.equals(hashedLog));
+      if (logHash) {
+        contractClassLogs.push(silo ? await siloContractClassLog(log, logHash.contractAddress) : log);
+      }
+    }
+    return contractClassLogs;
+  }
+
+  /**
+   * Computes (if necessary) & return transaction hash.
+   * @returns The hash of the public inputs of the private kernel tail circuit.
+   */
+  async getTxHash(forceRecompute = false): Promise<TxHash> {
+    if (!this.txHash || forceRecompute) {
+      const hash = this.data.forPublic
+        ? await this.data.toPrivateToPublicKernelCircuitPublicInputs().hash()
+        : await this.data.toPrivateToRollupKernelCircuitPublicInputs().hash();
+      this.txHash = new TxHash(hash);
+    }
+    return this.txHash!;
+  }
+
+  /**
+   * Allows setting the hash of the Tx.
+   * Use this when you want to skip computing it from the original data.
+   * Don't set a Tx hash received from an untrusted source.
+   * @param hash - The hash to set.
+   */
+  setTxHash(hash: TxHash) {
+    this.txHash = hash;
+  }
+
+  /** Returns stats about this tx. */
+  async getStats(): Promise<TxStats> {
+    return {
+      txHash: (await this.getTxHash()).toString(),
+
+      noteHashCount: this.data.getNonEmptyNoteHashes().length,
+      nullifierCount: this.data.getNonEmptyNullifiers().length,
+      privateLogCount: this.data.getNonEmptyPrivateLogs().length,
+      classRegisteredCount: this.data.getNonEmptyContractClassLogsHashes().length,
+      contractClassLogSize: this.data.getNonEmptyContractClassLogsLength(),
+
+      proofSize: this.clientIvcProof.clientIvcProofBuffer.length,
+      size: this.toBuffer().length,
+
+      feePaymentMethod:
+        // needsSetup? then we pay through a fee payment contract
+        this.data.forPublic?.needsSetup
+          ? // if the first call is to `approve_public_authwit`, then it's a public payment
+            this.data.getNonRevertiblePublicCallRequests().at(-1)!.functionSelector.toField().toBigInt() === 0x43417bb1n
+            ? 'fpc_public'
+            : 'fpc_private'
+          : 'fee_juice',
+    };
+  }
+
+  getSize() {
+    return (
+      this.data.getSize() +
+      this.clientIvcProof.clientIvcProofBuffer.length +
+      arraySerializedSizeOfNonEmpty(this.contractClassLogs) +
+      arraySerializedSizeOfNonEmpty(this.enqueuedPublicFunctionCalls) +
+      arraySerializedSizeOfNonEmpty([this.publicTeardownFunctionCall])
+    );
+  }
+
+  /**
+   * Estimates the tx size based on its private effects. Note that the actual size of the tx
+   * after processing will probably be larger, as public execution would generate more data.
+   */
+  getEstimatedPrivateTxEffectsSize() {
+    return (
+      this.data.getNonEmptyNoteHashes().length * Fr.SIZE_IN_BYTES +
+      this.data.getNonEmptyNullifiers().length * Fr.SIZE_IN_BYTES +
+      this.data.getNonEmptyPrivateLogs().length * PrivateLog.SIZE_IN_BYTES +
+      this.data.getNonEmptyContractClassLogsLength() * Fr.SIZE_IN_BYTES
+    );
+  }
+
+  /**
+   * Convenience function to get a hash out of a tx or a tx-like.
+   * @param tx - Tx-like object.
+   * @returns - The hash.
+   */
+  static async getHash(tx: Tx | HasHash): Promise<TxHash> {
+    return hasHash(tx) ? tx.hash : await tx.getTxHash();
+  }
+
+  /**
+   * Convenience function to get array of hashes for an array of txs.
+   * @param txs - The txs to get the hashes from.
+   * @returns The corresponding array of hashes.
+   */
+  static async getHashes(txs: (Tx | HasHash)[]): Promise<TxHash[]> {
+    return await Promise.all(txs.map(Tx.getHash));
+  }
+
+  /**
+   * Clones a tx, making a deep copy of all fields.
+   * @param tx - The transaction to be cloned.
+   * @returns The cloned transaction.
+   */
+  static clone(tx: Tx): Tx {
+    const publicInputs = PrivateKernelTailCircuitPublicInputs.fromBuffer(tx.data.toBuffer());
+    const clientIvcProof = ClientIvcProof.fromBuffer(tx.clientIvcProof.toBuffer());
+    const contractClassLogs = tx.contractClassLogs.map(x => ContractClassLog.fromBuffer(x.toBuffer()));
+    const enqueuedPublicFunctionCalls = tx.enqueuedPublicFunctionCalls.map(x =>
+      PublicExecutionRequest.fromBuffer(x.toBuffer()),
+    );
+    const publicTeardownFunctionCall = PublicExecutionRequest.fromBuffer(tx.publicTeardownFunctionCall.toBuffer());
+    const clonedTx = new Tx(
+      publicInputs,
+      clientIvcProof,
+      contractClassLogs,
+      enqueuedPublicFunctionCalls,
+      publicTeardownFunctionCall,
+    );
+    if (tx.txHash) {
+      clonedTx.setTxHash(TxHash.fromBuffer(tx.txHash.toBuffer()));
+    }
+
+    return clonedTx;
+  }
+
+  /**
+   * Creates a random tx.
+   * @param randomProof - Whether to create a random proof - this will be random bytes of the full size.
+   * @returns A random tx.
+   */
+  static async random(randomProof = false) {
+    return new Tx(
+      PrivateKernelTailCircuitPublicInputs.emptyWithNullifier(),
+      randomProof ? ClientIvcProof.random() : ClientIvcProof.empty(),
+      [await ContractClassLog.random()],
+      [await PublicExecutionRequest.random()],
+      await PublicExecutionRequest.random(),
+    );
+  }
+
+  /**
+   * Filters out logs from functions that are not present in the provided kernel output.
+   *
+   * The purpose of this is to remove logs that got dropped due to a revert,
+   * in which case, we only have the kernel's hashes to go on, as opposed to
+   * this grouping by function maintained in this class.
+   *
+   * The logic therefore is to drop all FunctionLogs if any constituent hash
+   * does not appear in the provided hashes: it is impossible for part of a
+   * function to revert.
+   *
+   * @param logHashes the individual log hashes we want to keep
+   * @param out the output to put passing logs in, to keep this function abstract
+   */
+  public async filterRevertedLogs() {
+    this.contractClassLogs = await this.getSplitContractClassLogs(false);
+  }
+}
+
+/** Utility type for an entity that has a hash property for a txhash */
+type HasHash = { /** The tx hash */ hash: TxHash };
+
+function hasHash(tx: Tx | HasHash): tx is HasHash {
+  return (tx as HasHash).hash !== undefined;
+}

package/src/tx/tx_constant_data.ts

@@ -0,0 +1,93 @@
+import { TX_CONSTANT_DATA_LENGTH } from '@aztec/constants';
+import { Fr } from '@aztec/foundation/fields';
+import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { BlockHeader } from './block_header.js';
+import { TxContext } from './tx_context.js';
+
+/**
+ * Data that is constant/not modified by neither of the kernels.
+ */
+export class TxConstantData {
+  constructor(
+    /** Header of a block whose state is used during execution (not the block the transaction is included in). */
+    public historicalHeader: BlockHeader,
+    /**
+     * Context of the transaction.
+     *
+     * Note: `chainId` and `version` in txContext are not redundant to the values in
+     * self.historical_header.global_variables because they can be different in case of a protocol upgrade. In such
+     * a situation we could be using header from a block before the upgrade took place but be using the updated
+     * protocol to execute and prove the transaction.
+     */
+    public txContext: TxContext,
+    /**
+     * Root of the vk tree for the protocol circuits.
+     */
+    public vkTreeRoot: Fr,
+    /**
+     * Root of the tree for the protocol contracts.
+     */
+    public protocolContractTreeRoot: Fr,
+  ) {}
+
+  static from(fields: FieldsOf<TxConstantData>) {
+    return new TxConstantData(...TxConstantData.getFields(fields));
+  }
+
+  static getFields(fields: FieldsOf<TxConstantData>) {
+    return [fields.historicalHeader, fields.txContext, fields.vkTreeRoot, fields.protocolContractTreeRoot] as const;
+  }
+
+  static fromFields(fields: Fr[] | FieldReader): TxConstantData {
+    const reader = FieldReader.asReader(fields);
+    return new TxConstantData(
+      reader.readObject(BlockHeader),
+      reader.readObject(TxContext),
+      reader.readField(),
+      reader.readField(),
+    );
+  }
+
+  toFields(): Fr[] {
+    const fields = serializeToFields(...TxConstantData.getFields(this));
+    if (fields.length !== TX_CONSTANT_DATA_LENGTH) {
+      throw new Error(
+        `Invalid number of fields for TxConstantData. Expected ${TX_CONSTANT_DATA_LENGTH}, got ${fields.length}`,
+      );
+    }
+    return fields;
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader): TxConstantData {
+    const reader = BufferReader.asReader(buffer);
+    return new TxConstantData(
+      reader.readObject(BlockHeader),
+      reader.readObject(TxContext),
+      Fr.fromBuffer(reader),
+      Fr.fromBuffer(reader),
+    );
+  }
+
+  toBuffer() {
+    return serializeToBuffer(...TxConstantData.getFields(this));
+  }
+
+  static empty() {
+    return new TxConstantData(BlockHeader.empty(), TxContext.empty(), Fr.ZERO, Fr.ZERO);
+  }
+
+  getSize() {
+    return (
+      this.historicalHeader.getSize() +
+      this.txContext.getSize() +
+      this.vkTreeRoot.size +
+      this.protocolContractTreeRoot.size
+    );
+  }
+
+  clone(): TxConstantData {
+    return TxConstantData.fromBuffer(this.toBuffer());
+  }
+}

package/src/tx/tx_context.ts

@@ -0,0 +1,104 @@
+import { TX_CONTEXT_LENGTH } from '@aztec/constants';
+import { Fr } from '@aztec/foundation/fields';
+import { schemas } from '@aztec/foundation/schemas';
+import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { z } from 'zod';
+
+import { GasSettings } from '../gas/gas_settings.js';
+
+/**
+ * Transaction context.
+ */
+export class TxContext {
+  public chainId: Fr;
+  public version: Fr;
+
+  constructor(
+    /** Chain ID of the transaction. Here for replay protection. */
+    chainId: Fr | number | bigint,
+    /** Version of the transaction. Here for replay protection. */
+    version: Fr | number | bigint,
+    /** Gas limits for this transaction. */
+    public gasSettings: GasSettings,
+  ) {
+    this.chainId = new Fr(chainId);
+    this.version = new Fr(version);
+  }
+
+  static get schema() {
+    return z
+      .object({
+        chainId: schemas.Fr,
+        version: schemas.Fr,
+        gasSettings: GasSettings.schema,
+      })
+      .transform(TxContext.from);
+  }
+
+  getSize() {
+    return this.chainId.size + this.version.size + this.gasSettings.getSize();
+  }
+
+  clone() {
+    return new TxContext(this.chainId, this.version, this.gasSettings.clone());
+  }
+
+  /**
+   * Serialize as a buffer.
+   * @returns The buffer.
+   */
+  toBuffer() {
+    return serializeToBuffer(...TxContext.getFields(this));
+  }
+
+  static fromFields(fields: Fr[] | FieldReader): TxContext {
+    const reader = FieldReader.asReader(fields);
+    return new TxContext(reader.readField(), reader.readField(), reader.readObject(GasSettings));
+  }
+
+  toFields(): Fr[] {
+    const fields = serializeToFields(...TxContext.getFields(this));
+    if (fields.length !== TX_CONTEXT_LENGTH) {
+      throw new Error(`Invalid number of fields for TxContext. Expected ${TX_CONTEXT_LENGTH}, got ${fields.length}`);
+    }
+    return fields;
+  }
+
+  /**
+   * Deserializes TxContext from a buffer or reader.
+   * @param buffer - Buffer to read from.
+   * @returns The TxContext.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader): TxContext {
+    const reader = BufferReader.asReader(buffer);
+    return new TxContext(Fr.fromBuffer(reader), Fr.fromBuffer(reader), reader.readObject(GasSettings));
+  }
+
+  static empty(chainId: Fr | number = 0, version: Fr | number = 0) {
+    return new TxContext(new Fr(chainId), new Fr(version), GasSettings.empty());
+  }
+
+  isEmpty(): boolean {
+    return this.chainId.isZero() && this.version.isZero() && this.gasSettings.isEmpty();
+  }
+
+  /**
+   * Create a new instance from a fields dictionary.
+   * @param fields - The dictionary.
+   * @returns A new instance.
+   */
+  static from(fields: FieldsOf<TxContext>): TxContext {
+    return new TxContext(...TxContext.getFields(fields));
+  }
+
+  /**
+   * Serialize into a field array. Low-level utility.
+   * @param fields - Object with fields.
+   * @returns The array.
+   */
+  static getFields(fields: FieldsOf<TxContext>) {
+    return [fields.chainId, fields.version, fields.gasSettings] as const;
+  }
+}