docs: update x402-sponsor-relay reference for nonce dispatch changes (PRs 247/248)

[whoabuddy]

Summary

The x402-sponsor-relay landed two significant nonce handling PRs (#247, #248) that change how downstream consumers interact with the relay. The skills repo documentation and code need updates to reflect these changes.

What Changed in the Relay

PR 247 — Nonce Pool Hardening

• New MALFORMED_PAYLOAD (400) rejection with IP-based rate limiting (429 after 3 bad payloads in 10 min)
• Agent queue management endpoints: GET /queue/:senderAddress, DELETE /queue/:senderAddress/:walletIndex/:sponsorNonce
• New SIP-018 actions: queue-read, queue-cancel
• Full stuck-tx auto-recovery (dispatch queue + replay buffer)

PR 248 — Sequence-Aware Nonce Dispatch

• POST /relay can now return HTTP 202 (transaction held) when sender nonce is out of order
  • Response includes QueueInfo with missingNonces[], Retry-After header
• POST /sponsor returns 400 SENDER_NONCE_GAP with missingNonces[] when nonce would create a gap
• POST /settle returns 200 with errorReason: "transaction_held" and QueueInfo
• Held transactions expire after 5 minutes with recentlyExpired feedback on next submission

Files to Update

Documentation

• aibtc-services/x402-sponsor-relay/README.md — Add 202 held response, queue endpoints, malformed payload rejection, SENDER_NONCE_GAP error, new error codes (MALFORMED_PAYLOAD, SENDER_NONCE_GAP, TRANSACTION_HELD, QUEUE_NOT_FOUND, QUEUE_ACCESS_DENIED)

Code

• src/lib/transactions/sponsor-builder.ts — Handle SENDER_NONCE_GAP (400) from /sponsor with missingNonces[] in error response. Currently only handles generic errors.

Skill

• relay-diagnostic/SKILL.md / relay-diagnostic.ts — Consider adding queue inspection (GET /queue/:address) as a diagnostic subcommand

New Error Codes to Document

Code	HTTP	Endpoint	Meaning
MALFORMED_PAYLOAD	400	/relay, /sponsor, /settle	Pre-flight validation failed (bad hex, wrong version/auth byte)
SENDER_NONCE_GAP	400	/sponsor	Sender nonce would create gap; submit missingNonces first
TRANSACTION_HELD	202	/relay	Transaction accepted but held pending missing nonces
QUEUE_NOT_FOUND	404	/queue/:addr	No queued entries for sender
QUEUE_ACCESS_DENIED	403	/queue/:addr	SIP-018 signature doesn't match sender