feat: adds a standalone transaction-clearer bot for recovering from nonce backlogs. by md0x · Pull Request #4915 · UMAprotocol/protocol

md0x · 2025-12-19T15:26:35Z

Problem

When a transaction gets stuck (e.g., gas price too low during a spike), it blocks all subsequent transactions from the same wallet. The pending nonce can't advance until the stuck transaction is either mined or replaced.

Solution

transaction-clearer: Standalone bot that clears stuck transactions by submitting 0-value self-transactions at the stuck nonce with escalating gas fees.

Changes

Add standalone transaction-clearer bot
Shared clearing logic in bot-utils/transactionClearing.ts (reusable by other bots if needed)

Configuration (env vars)

NONCE_BACKLOG_THRESHOLD - minimum backlog to trigger clearing (default: 1)
NONCE_REPLACEMENT_BUMP_PERCENT - fee bump per attempt (default: 20%)
NONCE_REPLACEMENT_ATTEMPTS - max attempts per stuck nonce (default: 3)

Fixes UMA-3012

packages/monitor-v2/src/bot-oo/index.ts

Signed-off-by: Pablo Maldonado <pablo@umaproject.org>

Reinis-FRP · 2026-01-19T12:54:47Z

packages/monitor-v2/src/transaction-clearer/common.ts

+    feeBumpNumerator: Number(env.FEE_BUMP_NUMERATOR) || 12,
+    feeBumpDenominator: Number(env.FEE_BUMP_DENOMINATOR) || 10,
+    replacementAttempts: Number(env.REPLACEMENT_ATTEMPTS) || 3,


nit: these are named differently in bot-oo

Reinis-FRP · 2026-01-19T12:56:56Z

packages/monitor-v2/src/transaction-clearer/common.ts

+export const initMonitoringParams = async (env: NodeJS.ProcessEnv): Promise<MonitoringParams> => {
+  const base = await initBaseMonitoringParams(env);
+
+  const nonceBacklogConfig: NonceBacklogConfig = {


bot-oo has some additional parsing checks that would be worth also using here and could reuse parsePositiveInt logic

Reinis-FRP · 2026-01-19T13:03:43Z

packages/monitor-v2/src/transaction-clearer/TransactionClearer.ts

+  return { latestNonce, pendingNonce };
+}
+
+export async function clearStuckTransactions(


might be more maintainable in the future if we have a single tx clearing module here and bot-oo would just reuse it

- Revert bot-oo/index.ts to master (nonce handling moved to transaction-clearer) - Replace feeBumpNumerator/Denominator with simpler feeBumpPercent (default 20%) - Add parsePositiveInt that throws on invalid values instead of silently using defaults Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Move clearStuckTransactions and related helpers to bot-utils/transactionClearing.ts so both transaction-clearer and bot-oo can reuse the same logic. Signed-off-by: Pablo Maldonado <pablo@umaproject.org>

Signed-off-by: Pablo Maldonado <pablo@umaproject.org>

linear · 2026-01-19T13:59:18Z

UMA-3012 Add transaction-clearer bot to recover from stuck transactions

Reinis-FRP · 2026-01-21T17:02:25Z

packages/monitor-v2/src/bot-utils/transactionClearing.ts

+      }
+    }
+
+    if (!cleared) {


Is it worth continuing with clearing next nonces if this one failed all attempts? Or we shall better reevaluate current state of pending-latest as some earlier tx might have been mined or another bot instance submits new tx.

good point. Now re-evaluates nonce state after failed attempts before continuing so it handles cases where the stuck tx got mined elsewhere or new txs were submitted.

Reinis-FRP · 2026-01-21T17:04:55Z

packages/monitor-v2/src/bot-utils/transactionClearing.ts

+  const { latestNonce: finalLatestNonce, pendingNonce: finalPendingNonce } = await getNonces(provider, botAddress);
+  const finalBacklog = finalPendingNonce - finalLatestNonce;
+
+  if (finalBacklog < nonceBacklogConfig.nonceBacklogThreshold) {


shouldn't the threshold be used just to decide if we need to start tx clearing? but once we are clearing, shouldn't we clear all pending ones?

You're right! Changed to check finalBacklog === 0. Threshold now only gates when to start clearing.

…acklog - After failing to clear a nonce, re-fetch the nonce state before continuing to handle cases where the tx was cleared by another source - Change final success check from threshold comparison to zero backlog, since threshold should only gate when to start clearing

Reinis-FRP · 2026-02-02T16:08:00Z

packages/monitor-v2/src/bot-utils/transactionClearing.ts

+    }
+
+    if (!cleared) {
+      logger.error({


this could end up paging indefinitely if clearing transactions end up underpriced and we are not updating baseFeeData.

Fixed! Now refreshing baseFeeData for each nonce iteration to handle rising gas prices.

Reinis-FRP · 2026-02-02T16:12:13Z

packages/monitor-v2/src/bot-utils/transactionClearing.ts

+      const refreshed = await getNonces(provider, botAddress);
+      currentLatestNonce = refreshed.latestNonce;
+      currentPendingNonce = refreshed.pendingNonce;


shouldn't this exit the loop after nonceBacklogConfig.replacementAttempts if there are other reasons for clearing tx to fail (e.g. underpriced or bot is just out of funds) if latestNonce did not change?

Good catch! Added a check - if latestNonce hasn't advanced after failed clearing attempts, we now exit the loop to prevent infinite iteration. Will retry on next bot cycle with fresh gas prices.

- Refresh baseFeeData for each nonce to handle rising gas prices - Exit loop if latestNonce doesn't advance after failed clearing attempts (e.g., underpriced txs, bot out of funds) Addresses review feedback from Reinis-FRP. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

feat(bot-oo): detect nonce backlog and attempt self-tx cancellation

fa2773f

md0x marked this pull request as ready for review December 19, 2025 15:26

md0x requested review from Reinis-FRP, chrismaree and mrice32 as code owners December 19, 2025 15:26

Reinis-FRP reviewed Jan 6, 2026

View reviewed changes

packages/monitor-v2/src/bot-oo/index.ts Outdated Show resolved Hide resolved

packages/monitor-v2/src/bot-oo/index.ts Outdated Show resolved Hide resolved

md0x added 2 commits January 19, 2026 12:37

feat: standalone script

e448f44

Signed-off-by: Pablo Maldonado <pablo@umaproject.org>

fix: review

e7077cc

Reinis-FRP reviewed Jan 19, 2026

View reviewed changes

md0x and others added 3 commits January 19, 2026 13:14

fix: use consistent NONCE_ prefix for env vars

dd0c8b7

refactor: extract transaction clearing to shared bot-utils module

8744689

Move clearStuckTransactions and related helpers to bot-utils/transactionClearing.ts so both transaction-clearer and bot-oo can reuse the same logic. Signed-off-by: Pablo Maldonado <pablo@umaproject.org>

md0x force-pushed the pablo/nonce-backlog-handling branch from 828aa01 to 8744689 Compare January 19, 2026 13:45

md0x changed the title ~~feat(bot-oo): detect nonce backlog and attempt self-tx cancellation~~ feat: adds a standalone transaction-clearer bot for recovering from nonce backlogs. Jan 19, 2026

chore: add comment to transaction-clearer

e706178

Signed-off-by: Pablo Maldonado <pablo@umaproject.org>

md0x requested a review from Reinis-FRP January 19, 2026 14:02

Reinis-FRP reviewed Jan 21, 2026

View reviewed changes

md0x requested a review from Reinis-FRP January 29, 2026 11:24

Reinis-FRP reviewed Feb 2, 2026

View reviewed changes

Conversation

md0x commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Changes

Configuration (env vars)

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

linear bot commented Jan 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

md0x commented Dec 19, 2025 •

edited

Loading