relay-diagnostic

Relay Diagnostic Skill

スポンサーリレーの nonce 状態を調査し、必要に応じて自動復旧を実行することで、停滞したスポンサー付きトランザクションを診断して復旧します。

これはオペレーターによる診断専用です。呼び出し元に表示する x402 の支払い状態は、リレーの健全性に関するヒューリスティックではなく、paymentId による正規の支払いステータスのポーリングから取得してください。

• check-health — 読み取り専用で、ウォレットは不要です。リレーのバージョン、スポンサー nonce の状態、検出されたギャップ、停滞したトランザクションを返します。
• recover — アンロック済みのウォレットが必要です（スポンサー API キーの取得に使用します）。RBF、ギャップの埋め合わせ、またはその両方を試みます。

使用方法

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

サブコマンド

check-health

スポンサーリレーの可用性と nonce の状態を確認します。ウォレットは不要です。

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

出力：

{
  "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

停滞したトランザクションの自動復旧を試みます。アンロック済みのウォレットが必要です。

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

オプション：

• --action <rbf|fill-gaps|both> — 復旧モード（デフォルト：both）
• --txids <txid,...> — RBF 対象として指定する、停滞した txid のカンマ区切りリスト（省略するとすべてを手数料引き上げの対象にします）
• --nonces <n,...> — ギャップ埋めの対象として指定する、欠落した nonce のカンマ区切りリスト（省略するとすべてのギャップを埋めます）

出力：

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

注意事項

• recover の前に必ず check-health を実行してください。事前に健全性を確認せずに復旧すると、不要なトランザクションの手数料引き上げが発生する可能性があります。
• リレーが復旧エンドポイントに対して 404 または 501 を返した場合、このツールは supported: false を、AIBTC チームへの問い合わせを促す手順とともに報告します。
• mainnet のスポンサーアドレスは SP1PMPPVCMVW96FSWFV30KJQ4MNBMZ8MRWR3JWQ7 です。
• ウォレット操作にはアンロック済みのウォレットが必要です（まず bun run wallet/wallet.ts unlock を実行してください）。