# Transaction Advancer — Design Proposal ## Problem Ethereum transactions are ordered by **nonce** per sender address. If a transaction with nonce N has low gas and gets stuck, all transactions with nonce > N are blocked even if they have adequate gas. This tool detects such stuck transactions and replaces them with higher gas so they proceed to confirmation. --- ## High-Level Flow ```mermaid flowchart TD A[Node Registry<br/>sender → nodes] --> B[Detector] B --> C[Replacer] C --> D[Reporter] B[Detector<br/>eth_getTransactionCount<br/>+ txpool.content per node] C[Replacer<br/>Create replacement txs<br/>Broadcast to all nodes] D[Reporter<br/>Store report JSON / DB] ``` --- ## Components ### 1. Node Registry A mapping of `sender_address → [node_url, ...]`. Tracks which nodes a given sender has submitted transactions through. Required because mempool state is local to each node. ``` registry = { "0xabc...": ["https://node-a.infura.io/...", "https://node-b.alchemy.io/..."], "0xdef...": ["https://node-a.infura.io/..."] } ``` This can be: - A config file (YAML/JSON) - A lightweight DB table - Implicit: always query all known nodes for all senders ### 1b. Key Management The tool needs the sender's private key to sign cancellation transactions. Keys are stored as **encrypted keystore files** (standard Ethereum keystore JSON, Web3 secret storage format): ``` keystores/ UTC--2026-07-16T...--0xabc... ← keystore for 0xabc... UTC--2026-07-16T...--0xdef... ← keystore for 0xdef... ``` On each run, the user provides keystore passwords via: - CLI prompt (interactive) - `KEYSTORE_PASSWORD` env var (for scripting) The tool decrypts the keystore in-memory to sign, then discards the key. ### 2. Detector Runs periodically or on-demand. For each sender address: 1. **Get confirmed nonce** (same across all nodes — blockchain is canonical): ``` sender_nonce = eth_getTransactionCount(address, "latest") ``` Queried from any node. Returns the next expected nonce (= last mined nonce + 1). 2. **Query every node in the registry** — each node returns two values: ``` Node A: { latest: 6, pending: 7, txpool: { nonce 6 → tx } } Node B: { latest: 6, pending: 10, txpool: { nonce 8 → tx, nonce 9 → tx } } ``` 3. **Reconcile** across nodes: - `effective_latest` = the (single) latest value — same for all nodes - `effective_pending` = **max** of all per-node pending values — if any node knows about a tx at nonce 9, it exists in the wild - `unified_mempool` = **union** of all per-node `txpool.content` entries — if Node A has nonce 6 and Node B has nonces 8, 9, then: `pending nonces = {6, 8, 9}`, **nonce 7 is a gap** 4. **Analyze**: walk nonces from `effective_latest` to `effective_pending - 1`: - Nonce present in `unified_mempool` → stuck tx, details available for replacement - Nonce missing from `unified_mempool` → gap, needs 0-ETH fill - Nonce present with low gas → needs gas bump #### Fallback — txpool API unavailable Some providers (Infura free tier, certain private nodes) restrict `txpool` methods. The Detector degrades gracefully: - `eth_getTransactionCount(address, "pending")` usually **still works** — it tells us the pending range even without txpool access - Without `txpool.content`, we cannot see individual tx details (gas price, data, sender) - **Fallback**: treat every nonce from `effective_latest` to `effective_pending - 1` as a gap and fill with 0-ETH txs This is more aggressive (fills nonces that might already have adequate gas), but it's safe — the 0-ETH cancel always unblocks the nonce regardless of what was there before. #### Detection Outcomes | Scenario | Signal | Action | |----------|--------|--------| | Normal | `effective_pending == effective_latest` | Nothing to do | | Low-gas stuck | `effective_pending > effective_latest`, tx in mempool | Replace with higher gas | | Nonce gap | Nonce missing from unified_mempool between `latest` and `pending-1` | Fill gap with 0-ETH tx | | Tx evicted | `effective_pending > effective_latest`, but no mempool entries at all | All missing — fill gaps | ### 3. Replacer Since we do not persist submitted tx data, we cannot recreate the original transaction. The universal fix is **cancellation**: send a 0-ETH transaction to self at the stuck nonce with high gas. This overwrites the stuck tx in the mempool (same nonce, higher gas → miners prefer it) and unblocks subsequent nonces. | Situation | Strategy | |-----------|----------| | Stuck tx in mempool | **Cancel**: 0-ETH to self at the same nonce, high gas | | Nonce gap (tx evicted or never submitted) | **Fill gap**: 0-ETH to self at the missing nonce, high gas | Both cases use the same mechanism: 0-ETH transfer to own address. #### Gas Pricing Strategy (EIP-1559) All transactions use EIP-1559 (type 2): - `maxPriorityFeePerGas = max(current_network_tip * 1.5, old * 1.2)` - `maxFeePerGas = base_fee * 2 + maxPriorityFeePerGas` Where `old` refers to the original tx's priority fee (if available from mempool) or falls back to network estimates. Bump percentage is configurable (default: 20%). #### Broadcast Replacement/cancel txs are **broadcast to all nodes** simultaneously to: - Maximize chance of quick inclusion - Prevent stale old txs from circulating on other nodes #### Confirmation Polling After broadcasting, poll all replacement tx hashes: - Poll every 5 seconds - Stop when **all confirmed** OR **2 minutes elapsed** - Exit with a report of confirmed vs unconfirmed ``` for each replacement tx_hash, poll every 5s: result = eth_getTransactionByHash(tx_hash) if result and result.blockNumber: mark CONFIRMED after 2 minutes or all confirmed: log summary: { confirmed: [...], unconfirmed: [...] } exit code 0 if all confirmed, non-zero otherwise ``` #### Retry Re-running the CLI on the same state will: 1. Detector finds the same stuck nonces 2. Replacer bumps gas again (higher than the previous cancellation tx) 3. Poll again This keeps the tool simple — retry orchestration lives outside it (manual re-run or a shell wrapper). ### 4. Reporter Stores a report for each run with: ``` { "run_id": "uuid", "timestamp": "2026-07-16T12:00:00Z", "sender": "0xabc...", "actions": [ { "type": "replace" | "fill_gap", "nonce": 6, "old_tx_hash": "0x...", // null if fill_gap "old_gas_price": "5 gwei", // null if fill_gap "new_tx_hash": "0x...", "new_gas_price": "25 gwei", "to": "0x...", "status": "broadcast" | "confirmed" } ] } ``` Reports can be stored as: - Local JSON files (simplest) - SQLite/Postgres (for querying) --- ## Worked Example **State:** - Last confirmed nonce: 5 - Tx nonce 6 submitted via Node A (gas: 5 gwei) — stuck - Tx nonce 7 submitted via Node A (gas: 5 gwei) — stuck - Tx nonce 8 submitted via Node B (gas: 50 gwei) — blocked by nonce 6 **Detector queries:** | Query | Node A | Node B | |-------|--------|--------| | `eth_getTransactionCount("latest")` | 6 | 6 | | `eth_getTransactionCount("pending")` | 8 | 9 | | `txpool.content` nonces | 6, 7 | 8 | **Reconciliation:** - `effective_latest` = 6 - `effective_pending` = max(8, 9) = **9** ← Node B sees nonce 8 - `unified_mempool` = {6, 7, 8} ← union of both - Walk from nonce 6 to 8: all present, no gaps - **Result**: nonces 6, 7, 8 are detected as stuck **Replacer produces:** 1. Cancel nonce 6: 0-ETH to self, nonce 6, gas 5 → 25 gwei → broadcast to all nodes 2. Cancel nonce 7: 0-ETH to self, nonce 7, gas 5 → 25 gwei → broadcast to all nodes 3. Nonce 8 is no longer blocked once 6 and 7 clear, or optionally cancel it too --- ## Out of Scope (v1) - **Cross-chain** (only works on one chain at a time). - **MEV considerations** (not trying to extract value, just unblock). - **Private mempool** (Flashbots, etc.) — v1 broadcasts publicly. --- ## Decisions (Resolved) The following were open questions, now resolved: | # | Question | Decision | |---|----------|----------| | 1 | Storage for signed txs? | No storage. Use **0-ETH cancel** for all stuck txs. | | 2 | Gas strategy for gap fills? | **EIP-1559 only** — described in Gas Pricing Strategy above. | | 3 | Run mode? | **On-demand CLI** (no daemon or cron). | | 4 | Failure handling? | Poll for **2 minutes**, log confirmed vs unconfirmed, **retry** full run for unconfirmed. |