Track 6 · dApps & frontend · lesson 5

Waiting, and failing well

11 min

A transaction has four possible fates after you send it, and a dApp that only handles the happy one lies to its users.

After broadcast, a transaction can be: pending (waiting), included then succeeded, included then reverted, or replaced/dropped (the user sped it up, cancelled, or it fell out of the mempool).

Only the second is success. Showing "Done!" the moment the wallet closes claims success for all four — and users act on that claim.

Wait for the receipt

import { useWaitForTransactionReceipt } from "wagmi";

const { data: hash } = useWriteContract(/* ... */);
const { isLoading, isSuccess, isError } =
  useWaitForTransactionReceipt({ hash });

The receipt is the truth. It arrives only once the transaction is mined, and its status field says whether the execution succeeded or reverted.

// Claims success the instant the wallet closes.
async function onMint() {
await writeContract({ /* ... */ });
toast("Minted!");          // a lie — it's only pending
refetchBalance();          // reads the OLD balance, too early
}

Toasting on broadcast claims success for a transaction that might revert, and refetching immediately reads stale state before the change lands.

Three states, three messages

A write button really has three UI states, not two:

Predict

Your dApp refetches a balance the instant writeContract resolves. What does the user see?

Choose one answer

Check

Where do you learn whether an included transaction succeeded or reverted?

Choose one answer

Worth remembering

  • A sent transaction can be pending, succeed, revert, or be replaced/dropped — only one is success.
  • `useWaitForTransactionReceipt` gives the authoritative outcome once mined.
  • Refetch state on the receipt, never on the write resolving, or you read stale data.
  • A write button has three states: confirming in wallet, sending on chain, settled.
  • Report reverts honestly — the user needs to know nothing changed.