fix(bridge): recover stuck approvals safely

[Vasanthdev2004]

Why

Follow-up to #49 after an Arc USDC approval stayed on "Approval submitted" without a receipt. The original transaction used nonce 2 while the source RPC still reported confirmed nonce 0. That exposed gaps in queue detection, status explanations, and recovery after a wallet speed-up.

This does not establish where the original nonce/fee came from, and it does not repair an already-submitted wallet transaction automatically.

Changes

• Check source-wallet pending/latest nonce counts before a new approval or deposit. A visible queue or inconsistent result stops submission before journaling and the approval/deposit signature request; no nonce is overridden.
• Explain approvals missing from the queried node, earlier-nonce queues, fee caps below the current base fee, delayed confirmations, and RPC failures. Missing data is never treated as proof of failure or permission to resubmit.
• Allow a user-supplied mined replacement approval hash. Recovery verifies chain, transaction/receipt hash, recent block time, exact owner/token/spender/amount or canonical USDC event, and current allowance. Verification sends nothing; bridging still needs a fresh reviewed quote and separate confirmation.
• Prevent a delayed missing-receipt poll from reverting a confirmed recovery to pending, and replace stale diagnostics when RPC reads fail.
• Add regression coverage, development-only visual scenarios, and recovery documentation.

Verification

• Full suite: 645 passed, 10 opt-in live tests skipped, 0 failures.
• Pre-publication focused suite: 49/49 passed.
• TypeScript and changed-file ESLint passed.
• Production build passed; the three existing imageStore tracing warnings remain.
• Browser checked the queued/missing approval states and replacement-hash form at the development-only /ui-review-bridge route.
• Separate code review found no remaining blockers in this recovery scope.

No wallet transactions were signed, replaced, cancelled, or sent during verification. Real-wallet settlement of this recovery flow still needs a maintainer-controlled check. The nonce guard can only see the selected RPC node's queue, not every private or wallet-only pending transaction.

No contracts, approval limits, fee calculation, dependencies, or deployment configuration changed. Unrelated local lockfile and design metadata are excluded.

Summary by CodeRabbit

• New Features

  • Added clearer approval status guidance for queued, delayed, missing, low-fee, and unavailable transactions.
  • Added recovery for confirmed replacement transactions after validating transaction and allowance details.
  • Added safeguards that prevent bridge approvals or deposits when the wallet has pending or inconsistent transactions.
  • Added protection against outdated status updates overwriting newer recovery or submission results.

• Documentation

  • Documented approval recovery, wallet queue handling, and transaction submission safety.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Essentials

Run ID: 993c1ca2-bf60-46e6-9acc-86e8ecafa4a8

📥 Commits

Reviewing files that changed from the base of the PR and between c6fcf07 and 92172b7.

📒 Files selected for processing (11)

• app/src/app/ui-review-bridge/BridgeReview.tsx
• app/src/components/bridge/BridgeDialog.tsx
• app/src/components/bridge/bridge-ui.test.ts
• app/src/components/bridge/useBridge.ts
• app/src/lib/bridge/approval-health.test.ts
• app/src/lib/bridge/approval-health.ts
• app/src/lib/bridge/approval.test.ts
• app/src/lib/bridge/approval.ts
• app/src/lib/bridge/transaction-preflight.test.ts
• app/src/lib/bridge/transaction-preflight.ts
• docs/bridge.md

Included review availability: 4 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.

---

📝 Walkthrough

Walkthrough

The bridge now diagnoses pending approvals, validates replacement evidence, blocks submissions when wallet queues are not clear, and exposes health-specific approval states in the UI and review scenarios.

Changes

Approval safety flow

Layer / File(s)	Summary
Approval health diagnostics app/src/lib/bridge/approval-health.ts, app/src/lib/bridge/approval-health.test.ts	Adds approval-health classification for queued, missing, delayed, fee-limited, nonce-passed, waiting, and unavailable states.
Polling and approval recovery app/src/lib/bridge/approval.ts, app/src/components/bridge/useBridge.ts, app/src/lib/bridge/approval.test.ts	Restricts stale polling and validates transaction, receipt, chain, timing, calldata, and allowance evidence during recovery.
Wallet queue preflight app/src/lib/bridge/transaction-preflight.ts, app/src/components/bridge/useBridge.ts, app/src/lib/bridge/transaction-preflight.test.ts	Checks pending and latest nonce counts before approval or deposit submission.
Approval UI and bridge scenarios app/src/components/bridge/BridgeDialog.tsx, app/src/app/ui-review-bridge/BridgeReview.tsx, app/src/components/bridge/bridge-ui.test.ts, docs/bridge.md	Displays health-specific approval messaging, supports recovery for blocking approvals, adds review scenarios, and documents queue and recovery behavior.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix

Suggested reviewers: kevincodex1

Merge Risk: ⚪ Minimal · up to 92172

No concrete merge-blocking risk is established for the bridge approval recovery and queue-safety changes.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 38.89% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 18 functions across 10 files. (1 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: safer recovery of stuck bridge approvals.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 38.89% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 18 functions across 10 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/bridge-approval-recovery

---

_{Comment @coderabbitai help to get the list of available commands.}

[Vasanthdev2004]

@kevincodex1 Hey Kevin, this is the focused follow-up to the stuck Arc approval after #49.

It adds a visible-wallet-queue check before approval/deposit signatures, clearer pending-transaction guidance, and verified recovery for a wallet speed-up's replacement hash. It also fixes a race where a slow status check could put an already-confirmed recovery back into pending. Exact approval limits and the separate bridge confirmation stay unchanged.

645 tests passed, the focused recheck is 49/49, and TypeScript, lint and the production build passed. No real transactions were sent for this verification. This improves detection/recovery; it does not automatically unblock the existing wallet queue or prove where the original nonce/fee came from.

Could you review this and, once CI/review is green and you're happy with the recovery flow, merge it? Thanks!

[kevincodex1]

lgtm