Tracking & Lifecycle

sendTransaction() (and tx.send()) returns a TransactionTracker synchronously — the broadcast and confirmation polling run in the background. You follow the transaction either by awaiting the tracker's lifecycle promises or by subscribing to its events. The tracker also satisfies Settling<TransactionReceipt>, so it exposes settled, value, confirm(), and abort().

const tracker = evm.sendTransaction(tx);

const hash = await tracker.whenSubmitted();   // string — the broadcast id
const receipt = await tracker.whenConfirmed(); // TransactionReceipt

Events and promises

The lifecycle promises resolve once and cache their result, so awaiting one after the fact still resolves (or rejects with the real cause).

Events are subscribed with on(event, listener), which returns an unsubscribe function:

const off = tracker.on("change", (c) => {
  console.log(`${c.previous} → ${c.next}`);
});

tracker.on("confirmed", (receipt) => { /* success only */ });
tracker.on("failed", (err) => { /* err is a WativeError */ });

off(); // unsubscribe

whenConfirmed(n) and whenFinalized()

Confirmation-depth tracking is not implemented. whenConfirmed() resolves at first inclusion (one block). Asking for more is refused rather than resolved early — because a caller who got an early resolve might treat the funds as reorg-safe:

await tracker.whenConfirmed(3);
// UNSUPPORTED_OP: whenConfirmed(3): confirmation-depth tracking is not supported;
// this resolves at first inclusion (1 block). Poll receipt.blockNumber against
// the chain head for deeper confirmation.

Tracking ends at inclusion, so whenFinalized() does not always resolve. EVM receipt polling ends at confirmed; Solana polling ends at whichever of confirmed / finalized the node reports first. When tracking ends at confirmed, awaiting whenFinalized() rejects with an UNSUPPORTED_OP explaining that tracking stopped and the state will never be reached — it resolves only when the node genuinely reported finalized.

timeout vs failed — the distinction that matters

For a wallet library, the dangerous mistake is telling a caller a broadcast transaction is safe to resend when it might already be on the network. The two terminal statuses draw exactly that line.

timeout (introduced in 2.4.0 as the word for broadcast, outcome unknown) is never entered from a poll being unable to reach the node — a transient poll failure keeps polling. Its unknown-outcome messages name the signed hash so you can look the transaction up before sending another. tracker.hash is left null on an unacknowledged broadcast; the transaction's own tx.hash still carries the signed id the message references.

TransactionStatus

type TransactionStatus =
  | "draft" | "signed" | "submitted" | "pending"
  | "mined" | "confirmed" | "finalized"
  | "failed" | "dropped" | "aborted" | "timeout";

The terminal (settled) statuses are confirmed, finalized, failed, dropped, timeout, and aborted. tracker.settled is true in exactly those.

TransactionReceipt

TransactionStateChange

Each entry pushed onto tracker.history and passed to a "change" listener.

SimulationResult

Returned by simulateTransaction() / tx.simulate().

Related