Transaction Lifecycle Manager

Build a utility that sends a prepared Ethereum transaction, reports its hash immediately, and then waits for on-chain confirmations with clear timeout handling.

Capabilities

Emits pending hash

• When a transaction is broadcast successfully, surface the pending transaction hash right away and invoke the status callback with that hash. @test

Waits for confirmations

• Continue polling the network until the transaction has at least the requested number of confirmations, then resolve with the full receipt and confirmation count. @test

Receipt timeout handling

• If a receipt is not observed before the configurable receipt timeout elapses, reject with a timeout error that clearly indicates waiting for the receipt/confirmations expired. @test

Send timeout handling

• If the transaction is not accepted by the node within the configurable send timeout, reject with a distinct timeout error indicating the send step failed to complete in time. @test

Implementation

@generates

API

export interface LifecycleOptions {
  confirmations?: number;
  pollIntervalMs?: number;
  sendTimeoutMs?: number;
  receiptTimeoutMs?: number;
}

export type StatusUpdate =
  | { status: "pending"; transactionHash: string }
  | { status: "confirmed"; transactionHash: string; receipt: object; confirmations: number };

export async function executeWithLifecycle(
  txRequest: object,
  options?: LifecycleOptions,
  emitStatus?: (update: StatusUpdate) => void
): Promise<StatusUpdate>;

Dependencies { .dependencies }

web3-eth { .dependency }

Provides transaction sending, polling, and confirmation lifecycle controls.