Learn-skills.dev relay-diagnostic

Sponsor relay health checks and nonce recovery — diagnose stuck sponsored transactions, check nonce gaps, and attempt RBF or gap-fill recovery.

install

source · Clone the upstream repo

git clone https://github.com/NeverSight/learn-skills.dev

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/aibtcdev/skills/relay-diagnostic" ~/.claude/skills/neversight-learn-skills-dev-relay-diagnostic && rm -rf "$T"

manifest: data/skills-md/aibtcdev/skills/relay-diagnostic/SKILL.md

source content

Relay Diagnostic Skill

Diagnoses and recovers stuck sponsored transactions by inspecting the sponsor relay's nonce state and optionally triggering automated recovery.

check-health — Read-only, no wallet required. Returns relay version, sponsor nonce status, detected gaps, and stuck transactions.
recover — Requires an unlocked wallet (to source the sponsor API key). Attempts RBF, gap-fill, or both.

Usage

bun run relay-diagnostic/relay-diagnostic.ts <subcommand> [options]

Subcommands

check-health

Check the sponsor relay availability and nonce status. No wallet needed.

bun run relay-diagnostic/relay-diagnostic.ts check-health

Output:

{
  "healthy": true,
  "network": "mainnet",
  "version": "1.2.0",
  "sponsorAddress": "SP1PMPPVCMVW96FSWFV30KJQ4MNBMZ8MRWR3JWQ7",
  "nonceStatus": {
    "lastExecuted": 4210,
    "lastMempool": 4215,
    "possibleNext": 4216,
    "missingNonces": [],
    "mempoolNonces": [4211, 4212, 4213, 4214, 4215],
    "hasGaps": false,
    "gapCount": 0,
    "mempoolDesync": false,
    "desyncGap": 5
  },
  "stuckTransactions": [],
  "issues": [],
  "formatted": "Relay Health Check (mainnet)\nStatus: HEALTHY\n..."
}

recover

Attempt automated recovery of stuck transactions. Requires an unlocked wallet.

bun run relay-diagnostic/relay-diagnostic.ts recover [options]

Options:

```
--action <rbf|fill-gaps|both>
```
— Recovery mode (default:
```
both
```
)
```
--txids <txid,...>
```
— Comma-separated list of specific stuck txids for RBF (omit to bump all)
```
--nonces <n,...>
```
— Comma-separated list of specific missing nonces for gap-fill (omit to fill all)

Output:

{
  "action": "both",
  "rbf": {
    "supported": true,
    "result": { "bumped": 2 }
  },
  "fillGaps": {
    "supported": true,
    "result": { "filled": 0 }
  },
  "summary": "Recovery request submitted to relay. Run check-health to verify nonce state improved."
}

Notes

Always run
```
check-health
```
before
```
recover
```
— recovery without a prior health check may bump transactions unnecessarily.
If the relay returns 404 or 501 for recovery endpoints, the tool reports
```
supported: false
```
with instructions to contact the AIBTC team.

The sponsor address for mainnet is

SP1PMPPVCMVW96FSWFV30KJQ4MNBMZ8MRWR3JWQ7

Wallet operations require an unlocked wallet (use
```
bun run wallet/wallet.ts unlock
```
first).