Webhook icon
Schedule icon
If icon
Fail icon
Request icon
Query icon
SlackIncomingWebhook icon
Pause icon
Loop icon
Sequential icon
LoopUntil icon
Exit icon

Unblock Stuck EVM Transactions from Your Hot Wallets

Find hot-wallet transactions stuck in the mempool or behind a nonce gap, and replace them safely after on-call approval.

Categories
BusinessInfrastructure

Every transaction from an Ethereum account has a nonce, and the network processes them strictly in order. When fees rise after a payout was sent with a low max fee, or when a nonce is skipped because a service crashed between reserving and sending it, that one transaction blocks every later one. Withdrawals pile up and nothing confirms until someone notices and sends a replacement with the right nonce and higher fees. This blueprint watches your hot wallets, spots the blocking nonce, and turns the fix into a one-click decision for on-call.

How it works

  1. payout_stalled (Webhook) runs a check when your payout service sees a transaction that has not confirmed in time. periodic_check (Schedule) runs it regularly.
  2. read_state reads, in one JSON-RPC batch:
    • the chain id
    • the current base fee and the node's suggested tip
    • the mempool (txpool_content)
    • each wallet's confirmed nonce
  3. analyze (Postgres) looks at each wallet's next nonce and classifies it:
    • fee-stuck: the transaction at that nonce cannot pay the base fee
    • nonce gap: later transactions are waiting but the nonce itself was never sent
    • ok It also computes replacement fees: the old fees raised by fee_bump_percent, at least twice the base fee plus the tip, and never above max_fee_gwei. It tracks each problem between runs.
  4. report alerts once when a wallet has been blocked for stuck_after_minutes, and again when it moves.
  5. propose asks on-call to choose Speed up, Cancel, or Leave (Pause, 1 hour, no answer means Leave).
  6. act re-reads the chain, then replace (Loop) sends each replacement through your signer with the same nonce. It waits until either the replacement or the original has a receipt, and reports which one was mined.

Error handling

  • Decisions never act on stale data:
    • the chain is read again after the approval;
    • a wallet that was unblocked in the meantime, for example by someone using "speed up" in their wallet app, is skipped with "confirmed on its own while waiting";
    • fees are recomputed from the fresh base fee.
  • Your fee cap is respected. A replacement above max_fee_gwei is not proposed; Slack says what it would cost so you can decide manually.
  • Races are reported correctly. If the original transaction wins after all, the summary says so instead of claiming the replacement worked.
  • One failure does not block the others. Each replacement runs in its own block with allowFailure. A wallet the signer cannot sign for is reported as "NOT sent, the node or signer refused: unknown account", and the run ends as WARNING.
  • No alert storms. A blocked wallet is reported once and proposed again only after ask_again_minutes.
  • Clear failures:
    • malformed addresses are rejected before any RPC call;
    • a node without the txpool API fails with instructions;
    • RPC calls retry with backoff, and the errors alert names the task and cause.

What this blueprint teaches about Kestra

  • Flow variables holding a templated JSON-RPC batch, rendered with render() and reused before and after the approval.
  • Decision then re-check: a Pause followed by a fresh read, so human approval is applied to the current state.
  • LoopUntil to wait for an on-chain outcome where either of two transactions can win.
  • Per-item isolation in a Loop with Sequential + allowFailure, summarized through loop outputs.

Prerequisites

  • An RPC endpoint with the txpool API: your own geth, reth, Nethermind, or Erigon node, or a provider plan that exposes it.
  • A signer that accepts eth_sendTransaction for the hot wallets, such as Web3Signer or a KMS-backed relayer, on a private network. Kestra never holds the keys.
  • A Postgres database and a Slack incoming webhook.

Secrets

  • EVM_RPC_URL: JSON-RPC endpoint with the txpool API.
  • EVM_SIGNER_URL: signer endpoint for the hot wallets.
  • POSTGRES_URL, POSTGRES_USER, POSTGRES_PASSWORD: state database.
  • SLACK_WEBHOOK_URL: Slack incoming webhook.

Inputs

  • wallets (ARRAY): hot wallets to watch. Replace the placeholder.
  • stuck_after_minutes (INT, default 10), ask_again_minutes (INT, default 30).
  • min_priority_fee_gwei (FLOAT, default 2), fee_bump_percent (INT, default 15), max_fee_gwei (FLOAT, default 200).
  • explorer_url, kestra_url (STRING): links in Slack.

Outputs

  • wallets (JSON): each blocked wallet with its nonce, waiting time, queued transactions, and proposed fees.

Quick start

  1. Add the secrets and set wallets and max_fee_gwei.
  2. Run the flow once to create the stuck_tx_watch table.
  3. Enable periodic_check, and call payout_stalled from your payout service when a transaction is late.
  4. Rehearse on a testnet: send a transaction with a max fee below the base fee and approve a speed-up.

How to extend

  • Skip the approval for small amounts by sending replacements directly when the stuck value is below a threshold.
  • Page through PagerDuty when a wallet is blocked and above the fee cap.
  • Feed the confirmed replacement hash back to your payout service through a webhook, so it records the right transaction.

Links

See How

New to Kestra?

Use blueprints to kickstart your first workflows.