@aztec/stdlib 0.0.1-commit.181e2d196 → 0.0.1-commit.189eedb3

package/src/tx/tx.ts

@@ -1,14 +1,19 @@
-import { Buffer32 } from '@aztec/foundation/buffer';
+import { DA_GAS_PER_FIELD, TX_DA_GAS_OVERHEAD } from '@aztec/constants';
+import { type BaseBuffer32, Buffer32 } from '@aztec/foundation/buffer';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import type { ZodFor } from '@aztec/foundation/schemas';
-import { BufferReader, serializeArrayOfBufferableToVector, serializeToBuffer } from '@aztec/foundation/serialize';
-import type { FieldsOf } from '@aztec/foundation/types';
+import {
+  BufferReader,
+  BufferSink,
+  serializeArrayOfBufferableToVector,
+  serializeArrayToSink,
+  serializeToSink,
+} from '@aztec/foundation/serialize';
+import { type FieldsOf, unfreeze } from '@aztec/foundation/types';
 
 import { z } from 'zod';
 
 import type { GasSettings } from '../gas/gas_settings.js';
-import type { GetPublicLogsResponse } from '../interfaces/get_logs_response.js';
-import type { L2LogsSource } from '../interfaces/l2_logs_source.js';
 import type { PublicCallRequest } from '../kernel/index.js';
 import { PrivateKernelTailCircuitPublicInputs } from '../kernel/private_kernel_tail_circuit_public_inputs.js';
 import { ContractClassLog, ContractClassLogFields } from '../logs/contract_class_log.js';
@@ -20,6 +25,14 @@ import { HashedValues } from './hashed_values.js';
 import { PublicCallRequestWithCalldata } from './public_call_request_with_calldata.js';
 import { TxHash } from './tx_hash.js';
 
+// Static presize hint for the BufferSink the no-sink Tx.toBuffer() path allocates. Empirically a
+// public-with-enqueued-calls Tx serialized by the bootstrapped bench (yarn-project/stdlib/src/tx/
+// tx_bench.test.ts) is ~129128 bytes; a private-only Tx is ~81763 bytes. 128 KiB covers both shapes
+// without a single doubling-growth `ensure()` resize on the cold path. Real-world Txs that happen to
+// exceed this still serialize correctly — the sink falls back to its standard doubling growth — just
+// with the existing cost.
+const TX_SINK_PRESIZE_BYTES = 131072;
+
 /**
  * The interface of an L2 transaction.
  */
@@ -63,7 +76,7 @@ export class Tx extends Gossipable {
   // docs:end:tx_class
 
   // Gossipable method
-  override generateP2PMessageIdentifier(): Promise<Buffer32> {
+  override generateP2PMessageIdentifier(): Promise<BaseBuffer32> {
     return Promise.resolve(new Buffer32(this.getTxHash().toBuffer()));
   }
 
@@ -126,14 +139,15 @@ export class Tx extends Gossipable {
    * Serializes the Tx object into a Buffer.
    * @returns Buffer representation of the Tx object.
    */
-  toBuffer() {
-    return serializeToBuffer([
-      this.txHash,
-      this.data,
-      this.chonkProof,
-      serializeArrayOfBufferableToVector(this.contractClassLogFields, 1),
-      serializeArrayOfBufferableToVector(this.publicFunctionCalldata, 1),
-    ]);
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this, TX_SINK_PRESIZE_BYTES);
+    }
+    serializeToSink(sink, this.txHash, this.data, this.chonkProof);
+    serializeArrayToSink(sink, this.contractClassLogFields, 1);
+    serializeArrayToSink(sink, this.publicFunctionCalldata, 1);
   }
 
   static get schema(): ZodFor<Tx> {
@@ -179,15 +193,6 @@ export class Tx extends Gossipable {
     return this.txHash.equals(expectedHash);
   }
 
-  /**
-   * 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 getPublicLogs(logsSource: L2LogsSource): Promise<GetPublicLogsResponse> {
-    return logsSource.getPublicLogs({ txHash: this.getTxHash() });
-  }
-
   getContractClassLogs(): ContractClassLog[] {
     const logHashes = this.data.getNonEmptyContractClassLogsHashes();
     return logHashes.map((logHash, i) =>
@@ -264,16 +269,24 @@ export class Tx extends Gossipable {
   }
 
   /**
-   * 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.
+   * Returns the number of fields this tx's effects will occupy in the blob,
+   * based on its private side effects only. Accurate for txs without public calls.
+   * For txs with public calls, the actual size will be larger due to public execution outputs.
    */
-  getEstimatedPrivateTxEffectsSize() {
-    return (
-      this.data.getNonEmptyNoteHashes().length * Fr.SIZE_IN_BYTES +
-      this.data.getNonEmptyNullifiers().length * Fr.SIZE_IN_BYTES +
-      this.data.getEmittedPrivateLogsLength() * Fr.SIZE_IN_BYTES +
-      this.data.getEmittedContractClassLogsLength() * Fr.SIZE_IN_BYTES
-    );
+  getPrivateTxEffectsSizeInFields(): number {
+    // 3 fields overhead: tx_start_marker, tx_hash, tx_fee.
+    // TX_DA_GAS_OVERHEAD is defined as N * DA_GAS_PER_FIELD, so this division is always exact.
+    const overheadFields = TX_DA_GAS_OVERHEAD / DA_GAS_PER_FIELD;
+    const noteHashes = this.data.getNonEmptyNoteHashes().length;
+    const nullifiers = this.data.getNonEmptyNullifiers().length;
+    const l2ToL1Msgs = this.data.getNonEmptyL2ToL1Msgs().length;
+    // Each private log occupies (emittedLength + 1) fields: content + length field
+    const privateLogFields = this.data.getNonEmptyPrivateLogs().reduce((acc, log) => acc + log.emittedLength + 1, 0);
+    // Each contract class log occupies (length + 1) fields: content + contract address
+    const contractClassLogFields = this.data
+      .getNonEmptyContractClassLogsHashes()
+      .reduce((acc, log) => acc + log.logHash.length + 1, 0);
+    return overheadFields + noteHashes + nullifiers + l2ToL1Msgs + privateLogFields + contractClassLogFields;
   }
 
   /**
@@ -292,6 +305,16 @@ export class Tx extends Gossipable {
     return clonedTx;
   }
 
+  /**
+   * Returns a copy of this tx with its proof stripped (replaced by an empty {@link ChonkProof}). Used when archiving
+   * txs or shipping a pending tx over RPC where the proof is not needed. Note that {@link Tx.clone} with
+   * `cloneProof = false` does not strip the proof; it shares the original.
+   * @returns A new tx with an empty proof.
+   */
+  withoutProof(): Tx {
+    return new Tx(this.txHash, this.data, ChonkProof.empty(), this.contractClassLogFields, this.publicFunctionCalldata);
+  }
+
   /**
    * Creates a random tx.
    * @param randomProof - Whether to create a random proof - this will be random bytes of the full size.
@@ -309,7 +332,7 @@ export class Tx extends Gossipable {
 
   /** Recomputes the tx hash. Used for testing purposes only when a property of the tx was mutated. */
   public async recomputeHash(): Promise<TxHash> {
-    (this as any).txHash = await Tx.computeTxHash(this);
+    unfreeze(this).txHash = await Tx.computeTxHash(this);
     return this.txHash;
   }
 
@@ -336,7 +359,12 @@ export class TxArray extends Array<Tx> {
     }
   }
 
-  public toBuffer(): Buffer {
-    return serializeArrayOfBufferableToVector(this);
+  public toBuffer(): Buffer;
+  public toBuffer(sink: BufferSink): void;
+  public toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return serializeArrayOfBufferableToVector(this);
+    }
+    serializeArrayToSink(sink, [...this]);
   }
 }

package/src/tx/tx_constant_data.ts

@@ -1,6 +1,6 @@
 import { TX_CONSTANT_DATA_LENGTH } from '@aztec/constants';
 import { Fr } from '@aztec/foundation/curves/bn254';
-import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, FieldReader, serializeToFields, serializeToSink } from '@aztec/foundation/serialize';
 import type { FieldsOf } from '@aztec/foundation/types';
 
 import { BlockHeader } from './block_header.js';
@@ -57,8 +57,13 @@ export class TxConstantData {
     );
   }
 
-  toBuffer() {
-    return serializeToBuffer(...TxConstantData.getFields(this));
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, ...TxConstantData.getFields(this));
   }
 
   static empty() {

package/src/tx/tx_context.ts

@@ -1,7 +1,7 @@
 import { TX_CONTEXT_LENGTH } from '@aztec/constants';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { schemas } from '@aztec/foundation/schemas';
-import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, FieldReader, serializeToFields, serializeToSink } from '@aztec/foundation/serialize';
 import type { FieldsOf } from '@aztec/foundation/types';
 
 import { z } from 'zod';
@@ -49,8 +49,13 @@ export class TxContext {
    * Serialize as a buffer.
    * @returns The buffer.
    */
-  toBuffer() {
-    return serializeToBuffer(...TxContext.getFields(this));
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, ...TxContext.getFields(this));
   }
 
   static fromFields(fields: Fr[] | FieldReader): TxContext {

package/src/tx/tx_hash.ts

@@ -1,5 +1,10 @@
 import { Fr } from '@aztec/foundation/curves/bn254';
-import { BufferReader, serializeArrayOfBufferableToVector } from '@aztec/foundation/serialize';
+import {
+  BufferReader,
+  type BufferSink,
+  serializeArrayOfBufferableToVector,
+  serializeArrayToSink,
+} from '@aztec/foundation/serialize';
 
 import { schemas } from '../schemas/index.js';
 
@@ -34,8 +39,13 @@ export class TxHash {
     return new TxHash(value);
   }
 
-  public toBuffer() {
-    return this.hash.toBuffer();
+  public toBuffer(): Buffer;
+  public toBuffer(sink: BufferSink): void;
+  public toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return this.hash.toBuffer();
+    }
+    this.hash.toBuffer(sink);
   }
 
   public toString() {
@@ -82,7 +92,12 @@ export class TxHashArray extends Array<TxHash> {
     }
   }
 
-  public toBuffer(): Buffer {
-    return serializeArrayOfBufferableToVector([...this]);
+  public toBuffer(): Buffer;
+  public toBuffer(sink: BufferSink): void;
+  public toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return serializeArrayOfBufferableToVector([...this]);
+    }
+    serializeArrayToSink(sink, [...this]);
   }
 }

package/src/tx/tx_receipt.ts

@@ -1,4 +1,12 @@
-import { BlockNumber, BlockNumberSchema } from '@aztec/foundation/branded-types';
+import {
+  BlockNumber,
+  BlockNumberSchema,
+  EpochNumber,
+  EpochNumberSchema,
+  SlotNumber,
+  SlotNumberSchema,
+} from '@aztec/foundation/branded-types';
+import type { DefineIfFlag, FieldsOf, PickDefined } from '@aztec/foundation/types';
 
 import { z } from 'zod';
 
@@ -6,6 +14,8 @@ import { RevertCode } from '../avm/revert_code.js';
 import { BlockHash } from '../block/block_hash.js';
 import { DebugLog } from '../logs/debug_log.js';
 import { type ZodFor, schemas } from '../schemas/schemas.js';
+import { Tx } from './tx.js';
+import { TxEffect } from './tx_effect.js';
 import { TxHash } from './tx_hash.js';
 
 /** Block inclusion/finalization status. */
@@ -15,7 +25,7 @@ export enum TxStatus {
   PROPOSED = 'proposed',
   CHECKPOINTED = 'checkpointed',
   PROVEN = 'proven',
-  FINALIZED = 'finalized', // TODO(#13569): Implement finalized status properly
+  FINALIZED = 'finalized',
 }
 
 /** Tx status sorted by finalization progress. */
@@ -28,126 +38,301 @@ export const SortedTxStatuses: TxStatus[] = [
   TxStatus.FINALIZED,
 ];
 
+/** The four statuses a mined transaction can hold, ordered by finalization progress. */
+export const MinedTxStatuses = [TxStatus.PROPOSED, TxStatus.CHECKPOINTED, TxStatus.PROVEN, TxStatus.FINALIZED] as const;
+
+/** Block finalization status of a mined transaction. */
+export type MinedTxStatus = (typeof MinedTxStatuses)[number];
+
 /** 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',
-  BOTH_REVERTED = 'both_reverted',
+  REVERTED = 'reverted',
+}
+
+/** Returned from a `getTxReceipt` call to the node RPC API. */
+export interface TxReceiptInterface {
+  /** The transaction's block finalization status. */
+  status: TxStatus;
+  /** The execution result of the transaction, only set when the tx is in a block. */
+  executionResult?: TxExecutionResult;
+  /** Description of the transaction error, if any. */
+  error?: string;
+  /** The transaction fee paid for the transaction. */
+  transactionFee?: bigint;
+  /** The hash of the block containing the transaction. */
+  blockHash?: BlockHash;
+  /** The block number in which the transaction was included. */
+  blockNumber?: BlockNumber;
+  /** The slot number in which the transaction's block was built. */
+  slotNumber?: SlotNumber;
+  /** The epoch number in which the transaction was included. */
+  epochNumber?: EpochNumber;
+  /** The index of the transaction within its block. */
+  txIndexInBlock?: number;
+  /** The full transaction effect, attached when requested via `includeTxEffect`. */
+  txEffect?: TxEffect;
+  /** The pending transaction, attached when requested via `includePendingTx`. */
+  tx?: Tx;
+  /**
+   * 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).
+   */
+  debugLogs?: DebugLog[];
+
+  /** Returns true (and narrows) if the transaction has been included in a block. */
+  isMined(): this is MinedTxReceipt;
+
+  /** Returns true (and narrows) if the transaction is pending. */
+  isPending(): this is PendingTxReceipt;
+
+  /** Returns true (and narrows) if the transaction was dropped. */
+  isDropped(): this is DroppedTxReceipt;
+
+  /** Returns true if the transaction was executed successfully. */
+  hasExecutionSucceeded(): boolean;
+
+  /** Returns true if the transaction execution reverted. */
+  hasExecutionReverted(): boolean;
 }
 
 /**
- * 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.
+ * Common surface shared by every transaction receipt variant ({@link PendingTxReceipt}, {@link DroppedTxReceipt},
+ * {@link MinedTxReceipt}).
+ *
+ * Every cross-variant field is declared once here, optional except for `txHash` (always present) and `status`
+ * (abstract, narrowed by each subclass). Declaring the fields optional on the base lets callers read a bare
+ * {@link TxReceipt} union (without first narrowing) and keep compiling. Use the `is*` guards to narrow to the strong
+ * variant type and gain access to its required fields.
  */
-export class TxReceipt {
+abstract class TxReceiptBase {
+  /** The transaction's block finalization status. */
+  public abstract readonly status: TxStatus;
+  /** Description of the transaction error, if any. */
+  public readonly error?: string;
+
   constructor(
     /** A unique identifier for a transaction. */
-    public txHash: TxHash,
-    /** 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 | undefined,
-    /** The transaction fee paid for the transaction. */
-    public transactionFee?: bigint,
-    /** The hash of the block containing the transaction. */
-    public blockHash?: BlockHash,
-    /** The block number in which the transaction was included. */
-    public blockNumber?: BlockNumber,
-    /**
-     * 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[],
+    public readonly txHash: TxHash,
   ) {}
 
+  /** Returns true (and narrows) if the transaction has been included in a block. */
+  public isMined(): this is MinedTxReceipt {
+    return this instanceof MinedTxReceipt;
+  }
+
+  /** Returns true (and narrows) if the transaction is pending. */
+  public isPending(): this is PendingTxReceipt {
+    return this instanceof PendingTxReceipt;
+  }
+
+  /** Returns true (and narrows) if the transaction was dropped. */
+  public isDropped(): this is DroppedTxReceipt {
+    return this instanceof DroppedTxReceipt;
+  }
+
   /** Returns true if the transaction was executed successfully. */
-  hasExecutionSucceeded(): boolean {
-    return this.executionResult === TxExecutionResult.SUCCESS;
+  public hasExecutionSucceeded(): boolean {
+    return false;
   }
 
   /** Returns true if the transaction execution reverted. */
-  hasExecutionReverted(): boolean {
-    return this.executionResult !== undefined && this.executionResult !== TxExecutionResult.SUCCESS;
+  public hasExecutionReverted(): boolean {
+    return false;
   }
+}
 
-  /** 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
-    );
+abstract class UnminedTxReceipt extends TxReceiptBase {
+  public readonly executionResult: undefined = undefined;
+  public readonly transactionFee: undefined = undefined;
+  public readonly blockHash: undefined = undefined;
+  public readonly blockNumber: undefined = undefined;
+  public readonly slotNumber: undefined = undefined;
+  public readonly txIndexInBlock: undefined = undefined;
+  public readonly epochNumber: undefined = undefined;
+  public readonly txEffect: undefined = undefined;
+}
+
+/**
+ * Receipt for a transaction that is in the mempool but not yet included in a block.
+ */
+export class PendingTxReceipt<Opts extends GetTxReceiptOptions = GetTxReceiptOptions>
+  extends UnminedTxReceipt
+  implements TxReceiptInterface
+{
+  public override readonly status = TxStatus.PENDING;
+
+  constructor(
+    txHash: TxHash,
+    /** The pending transaction, attached when requested via `includePendingTx`. */
+    public readonly tx: DefineIfFlag<Opts, 'includePendingTx', Tx>,
+  ) {
+    super(txHash);
+  }
+
+  static empty(): PendingTxReceipt {
+    return new PendingTxReceipt(TxHash.zero(), undefined);
+  }
+
+  static from(fields: PickDefined<FieldsOf<PendingTxReceipt>>): PendingTxReceipt {
+    return new PendingTxReceipt(fields.txHash, fields.tx);
+  }
+
+  static get schema(): ZodFor<PendingTxReceipt> {
+    return z
+      .object({
+        txHash: TxHash.schema,
+        status: z.literal(TxStatus.PENDING),
+        tx: Tx.schema.optional(),
+      })
+      .transform(fields => PendingTxReceipt.from({ tx: undefined, ...fields }));
   }
+}
+
+/**
+ * Receipt for a transaction that was dropped from the mempool without being mined.
+ */
+export class DroppedTxReceipt extends UnminedTxReceipt implements TxReceiptInterface {
+  public override readonly status = TxStatus.DROPPED;
+
+  public tx: undefined = undefined;
 
-  /** Returns true if the transaction is pending. */
-  isPending(): boolean {
-    return this.status === TxStatus.PENDING;
+  constructor(
+    txHash: TxHash,
+    public override readonly error?: string,
+  ) {
+    super(txHash);
   }
 
-  /** Returns true if the transaction was dropped. */
-  isDropped(): boolean {
-    return this.status === TxStatus.DROPPED;
+  static empty(): DroppedTxReceipt {
+    return new DroppedTxReceipt(TxHash.zero());
   }
 
-  static empty() {
-    return new TxReceipt(TxHash.zero(), TxStatus.DROPPED, undefined, undefined);
+  static from(fields: PickDefined<FieldsOf<DroppedTxReceipt>>): DroppedTxReceipt {
+    return new DroppedTxReceipt(fields.txHash, fields.error);
   }
 
-  static get schema(): ZodFor<TxReceipt> {
+  static get schema(): ZodFor<DroppedTxReceipt> {
     return z
       .object({
         txHash: TxHash.schema,
-        status: z.nativeEnum(TxStatus),
-        executionResult: z.nativeEnum(TxExecutionResult).optional(),
+        status: z.literal(TxStatus.DROPPED),
         error: z.string().optional(),
-        blockHash: BlockHash.schema.optional(),
-        blockNumber: BlockNumberSchema.optional(),
-        transactionFee: schemas.BigInt.optional(),
-        debugLogs: z.array(DebugLog.schema).optional(),
       })
-      .transform(fields => TxReceipt.from(fields));
-  }
-
-  static from(fields: {
-    txHash: TxHash;
-    status: TxStatus;
-    executionResult?: TxExecutionResult;
-    error?: string;
-    transactionFee?: bigint;
-    blockHash?: BlockHash;
-    blockNumber?: BlockNumber;
-    debugLogs?: DebugLog[];
-  }) {
-    return new TxReceipt(
+      .transform(DroppedTxReceipt.from);
+  }
+}
+
+/**
+ * Receipt for a transaction that has been included in a block (proposed, checkpointed, proven, or finalized).
+ * All block-related fields are required for this variant.
+ */
+export class MinedTxReceipt<Opts extends GetTxReceiptOptions = GetTxReceiptOptions>
+  extends TxReceiptBase
+  implements TxReceiptInterface
+{
+  public override readonly status: MinedTxStatus;
+
+  public readonly tx = undefined;
+
+  constructor(
+    txHash: TxHash,
+    status: MinedTxStatus,
+    public readonly executionResult: TxExecutionResult,
+    public readonly transactionFee: bigint,
+    public readonly blockHash: BlockHash,
+    public readonly blockNumber: BlockNumber,
+    public readonly slotNumber: SlotNumber,
+    public readonly txIndexInBlock: number,
+    public readonly epochNumber: EpochNumber,
+    public readonly txEffect: DefineIfFlag<Opts, 'includeTxEffect', TxEffect>,
+    public debugLogs?: DebugLog[],
+  ) {
+    super(txHash);
+    this.status = status;
+  }
+
+  public override hasExecutionSucceeded(): boolean {
+    return this.executionResult === TxExecutionResult.SUCCESS;
+  }
+
+  public override hasExecutionReverted(): boolean {
+    return this.executionResult !== TxExecutionResult.SUCCESS;
+  }
+
+  static from(fields: PickDefined<FieldsOf<MinedTxReceipt>>): MinedTxReceipt {
+    return new MinedTxReceipt(
       fields.txHash,
       fields.status,
       fields.executionResult,
-      fields.error,
       fields.transactionFee,
       fields.blockHash,
       fields.blockNumber,
+      fields.slotNumber,
+      fields.txIndexInBlock,
+      fields.epochNumber,
+      fields.txEffect,
       fields.debugLogs,
     );
   }
 
+  static get schema(): ZodFor<MinedTxReceipt> {
+    return z
+      .object({
+        txHash: TxHash.schema,
+        status: z.enum([TxStatus.PROPOSED, TxStatus.CHECKPOINTED, TxStatus.PROVEN, TxStatus.FINALIZED]),
+        executionResult: z.nativeEnum(TxExecutionResult),
+        transactionFee: schemas.BigInt,
+        blockHash: BlockHash.schema,
+        blockNumber: BlockNumberSchema,
+        slotNumber: SlotNumberSchema,
+        txIndexInBlock: schemas.Integer,
+        epochNumber: EpochNumberSchema,
+        txEffect: TxEffect.schema.optional(),
+        debugLogs: z.array(DebugLog.schema).optional(),
+      })
+      .transform(fields => MinedTxReceipt.from({ txEffect: undefined, ...fields }));
+  }
+
   public static executionResultFromRevertCode(revertCode: RevertCode): TxExecutionResult {
-    if (revertCode.equals(RevertCode.OK)) {
-      return TxExecutionResult.SUCCESS;
-    } else if (revertCode.equals(RevertCode.APP_LOGIC_REVERTED)) {
-      return TxExecutionResult.APP_LOGIC_REVERTED;
-    } else if (revertCode.equals(RevertCode.TEARDOWN_REVERTED)) {
-      return TxExecutionResult.TEARDOWN_REVERTED;
-    } else if (revertCode.equals(RevertCode.BOTH_REVERTED)) {
-      return TxExecutionResult.BOTH_REVERTED;
-    } else {
-      throw new Error(`Unknown revert code: ${revertCode.getCode()}`);
-    }
+    return revertCode.isOK() ? TxExecutionResult.SUCCESS : TxExecutionResult.REVERTED;
   }
 }
+
+/**
+ * A transaction receipt summarizing the lifecycle of a transaction in the Aztec network. Discriminated over the
+ * transaction's status: {@link PendingTxReceipt} while in the mempool, {@link DroppedTxReceipt} once dropped, and
+ * {@link MinedTxReceipt} once included in a block.
+ */
+export type TxReceipt<Opts extends GetTxReceiptOptions = GetTxReceiptOptions> =
+  | PendingTxReceipt<Opts>
+  | DroppedTxReceipt
+  | MinedTxReceipt<Opts>;
+
+/**
+ * Zod schema for {@link TxReceipt}. Each member constrains its `status` field so the union routes
+ * unambiguously, giving a deterministic serialization round-trip.
+ */
+export const TxReceiptSchema: ZodFor<TxReceipt> = z.union([
+  PendingTxReceipt.schema,
+  DroppedTxReceipt.schema,
+  MinedTxReceipt.schema,
+]) as ZodFor<TxReceipt>;
+
+/** Options controlling which optional data is attached to a {@link TxReceipt}. */
+export type GetTxReceiptOptions = {
+  /** Attach the full {@link TxEffect} (mined txs only). */
+  includeTxEffect?: boolean;
+  /** Attach the pending {@link Tx} (pending txs only). */
+  includePendingTx?: boolean;
+  /** Keep the proof on the attached pending {@link Tx}; only meaningful alongside `includePendingTx`. */
+  includeProof?: boolean;
+};
+
+/** Zod schema for {@link GetTxReceiptOptions}. */
+export const GetTxReceiptOptionsSchema: ZodFor<GetTxReceiptOptions> = z.object({
+  includeTxEffect: z.boolean().optional(),
+  includePendingTx: z.boolean().optional(),
+  includeProof: z.boolean().optional(),
+});