T14 · Web3 Frontend

A Real-World Problem

A user clicks “Swap.”

The wallet opens, they confirm, the pop-up closes, and the page shows a spinner labeled “Processing.”

Then come fifteen seconds. For someone used to apps, that is a long time: enough to wonder whether it is stuck, switch away and back, or click the button again.

During those seconds, your interface may know very little:

• Did the user sign? They may have rejected the wallet request while the page keeps spinning.
• The transaction was broadcast, but did it enter the mempool? Could a low fee leave it stuck?
• Did it enter a block? Does that mean it succeeded?
• The user clicked “Speed up” in the wallet. Is the hash you are tracking still useful?

Answer any of these incorrectly and the interface contradicts reality. The costliest mistake is showing success when the transaction failed.

This is more than a UI detail. A Web2 request typically succeeds or fails within milliseconds. An onchain transaction has several outcomes, intermediate states lasting seconds or minutes, and can even move backward between states. A conventional Web2 page model gets this wrong.

Thought Experiment

Treat a transaction as registered mail, not an HTTP request.

You drop a letter in the mailbox. From then on:

• You have a tracking number. Without it, you cannot look anything up.
• The letter waits at a sorting center. Higher postage moves it ahead; too little may leave it waiting for days.
• The letter is loaded on a vehicle. The vehicle is still traveling and may be delayed or turned back.
• The vehicle arrives. Only then do you learn the result: delivered, or delivery failed and it was returned.

The last point is critical and counterintuitive: arriving at the destination is not the same as successful delivery.

Onchain, inclusion in a block means miners or validators executed the transaction, not that execution succeeded. A transaction that errors during execution is still included and still consumes a fee. Its receipt records failure.

T1 introduced this once. It deserves repetition because it causes one of the most common frontend bugs:

To know whether a transaction succeeded, inspect the receipt’s status, not merely whether it appeared in a block.

There is one thing registered mail cannot do: replace the letter while keeping its number. Onchain, only one transaction with a given nonce can ultimately land. “Speed up” and “Cancel” send a new transaction with the same nonce. The old hash may never produce a receipt.

An interface that waits only for that hash can spin forever.

Your Decision

How do you design the interface for this wait?

What Happens

The distinction is simple: the first three options draw screens; the fourth defines a model.

With screens alone, each new exception adds another if statement. After a few exceptions, no one can describe all possible outcomes. A state machine gives every exceptional situation a defined place.

Lay out the six transaction states and outcomes:

Two easily missed rules follow:

User rejection is not failure. Return quietly to idle, without a red error. Treating refusal as a mistake makes users feel wrong for changing their minds.

“Success” can move backward. Chain heads can reorganize (the final example in T1). If you show success before enough confirmations, a reorg can make that success false. Success is not truly terminal until your confirmation threshold is met.

Build a Model

The happy path is linear:

Write the states as types. The language matters less than the fact that different states carry different data. That is why a union works better than boolean flags:

type TxState =
  | { kind: 'idle' }
  | { kind: 'awaitingSignature'; intent: TxIntent }
  | { kind: 'broadcast';  hash: string; nonce: number; submittedAt: number }
  | { kind: 'pending';    hash: string; nonce: number; blockNumber: number; confirmations: number }
  | { kind: 'confirmed';  hash: string; blockNumber: number; confirmations: number }
  | { kind: 'failed';     hash?: string; reason: FailureReason }
  | { kind: 'replaced';   originalHash: string; replacementHash: string; by: 'speedup' | 'cancel' | 'unknown' };

type FailureReason =
  | 'userRejected'        // Rejected by the user in the wallet; strictly speaking, not a failure
  | 'insufficientFunds'   // Not enough funds for the fee or transfer
  | 'reverted'            // Included onchain, but execution reverted
  | 'slippage'            // Quote expired or tolerance exceeded; one kind of revert
  | 'nonceConflict'       // Another transaction used this nonce
  | 'dropped'             // Mempool dropped it before inclusion
  | 'unknown';

With isLoading, isSuccess, and isError booleans, impossible combinations such as isLoading && isSuccess remain type-valid and will eventually appear. A union makes invalid states unrepresentable. It also gives a broadcast state a hash without forcing idle to carry an optional hash.

Transition Table

Each transition can be a separate test:

The last two rows justify this table: the state machine must allow backward moves. A forward-only machine cannot correct a false success after a reorg.

Three Easy Mistakes

First, track primarily by nonce, secondarily by hash. The hash changes when users speed up or cancel; the nonce does not. If an address’s confirmed nonce has passed your transaction’s nonce but the hash has no receipt, it was replaced. Find the actual transaction at that nonce and continue tracking it.

Second, tracking must survive interruption. Users refresh, close tabs, and change devices. Persist unfinished transactions locally and resume tracking on page load. An in-memory state machine loses everything on refresh.

Third, disable the button while awaiting signature, not only after broadcast. There can be seconds between these states, when repeated clicks create multiple wallet prompts. Duplicate submission is the predictable result of this gap.

Error Translation Table

Map raw errors to “plain-language explanation plus action.” The third column matters most:

Two hard copy rules:

• Do not say “success” before a receipt. “Submitted,” “broadcast,” and “confirming” are accurate; “successful” is not.
• Do not say only “failed; retry.” Without a cause, users may repeat the same failed transaction and pay another fee.

What It Is Called

Hands-on

AI Lab

Step one:
List every failure a transaction can meet between construction and confirmation.
For each, give its trigger, what users observe, and the exact field that identifies it.
Include rejection, insufficient fee balance, revert, slippage, nonce conflict,
dropped transactions, and replacement by another transaction with the same nonce.

Step two:
Write a short plain-language message for each failure, no more than 20 words.
Explain what happened and one action users can take now. Then review each message:
could users mistakenly think the transaction succeeded, funds arrived, funds were spent,
or the transaction can still be canceled?

Real-World Case

Change One Variable

Takeaway Questions

Chapter Check