[Rigidity]

Closes #870. Phase 1 of #867.

Adds the trusted XCHandles foundation: per-network deployment config, a typed client for the listener API, on-chain verification of every lookup, a verified mapping store, and a resolve_handle endpoint. Recipient integration (#871), address display (#912), broader endpoints (#913) and NFT metadata (#911) are separate.

Config

• Turns on chia-wallet-sdk's action-layer feature (XCHandles drivers from 0.37.1, no Git dependency).
• Adds Network.xchandles (registry launcher ID, price singleton launcher ID, precommit payout puzzle hash, relative block height, API URL). Networks pick it up through inherit.
• The constants were decoded from each registry's launcher solution on chain, and tests re-parse those solutions with the SDK to check the config matches.
• A custom network gets no deployment unless it sets one. Inheriting only works if its genesis challenge matches the built-in network's, so nothing falls back to mainnet.

Verification (crates/sage-wallet/src/xchandles/)

For every lookup:

1. Rebuild the slot coin from the returned value and lineage, and reject it unless its parent is a coin of the trusted registry singleton.
2. Confirm through a peer that the slot is confirmed and unspent.
3. Check expiry against the peak transaction block's timestamp, only once the slot is confirmed.
4. Derive the address from the resolved NFT or DID by parsing it from its parent's spend (Sage's existing ChildKind parser), following later spends if the API is behind. A singleton in a clawback is rejected.

A slot spent by neighbour activity triggers a re-fetch (up to 3 attempts) rather than a rejection. API lookups pin ?launcher_id=<registry>. A whole lookup is capped at 15 seconds, and a timeout counts as unavailable.

Store

Migration 0006_xchandles.sql adds an xchandles table keyed by (registry_launcher_id, handle). The policy is documented at the top of cache.rs:

• When the API and peers are reachable, every lookup is verified fresh.
• When they're unavailable (network errors, rate limits, server errors, unparseable responses, timeouts), a mapping verified in the last 24 hours is returned and marked cached, unless it has expired.
• A rejected answer, or a handle that is no longer registered, marks the stored row unverified, keeping its last verified values.
• CoinStateUpdate.fork_height now marks rows above the fork point stale. Failures there are logged and don't block coin processing.
• A new resolved address keeps the old one as a pending change until it is acknowledged. Database helpers for acknowledging and recording the last-sent address are in place for Resolve XCHandles safely in every recipient flow #871.
• The stored row is re-read in the same transaction as the write, so concurrent writes aren't lost.

Endpoint

resolve_handle takes a handle (with or without @) and returns a HandleRecord: address, status (verified or changed), previous_address, last_sent_address, cached, and the proof and height fields. It's wired into RPC/OpenAPI, the Tauri command list and the main-host permissions. Not-registered handles return NotFound.

There's also a VITE_DISABLE_XCHANDLES build flag in features.ts. Nothing uses it yet.

Testing

• Mocked API: the fixtures are real responses captured from the mainnet and testnet APIs. The 410 and 503 bodies are built from the documented error format.
• Peer simulator: a stand-in registry singleton creates and spends real slot coins. Tests cover:
  • a valid resolution
  • a forged slot lineage
  • a tampered slot value or expiration
  • a slot from another registry, and the wrong deployment constants
  • expiry
  • a slot recreated by a neighbour (re-verifies with no change warning)
  • an NFT that moved after indexing
  • bad resolved-singleton data
• Store: database tests cover change tracking, the offline window, which errors downgrade a row, reorg invalidation, per-registry isolation, and concurrent writes.
• RPC: invalid handles and unsupported networks are rejected.
• Live data: the slot coins for yakuhito (mainnet) and cloudwallet (testnet11) were rebuilt from the fixtures and confirmed to exist, unspent, through coinset. The yakuhito NFT parsed from its real parent spend to the owner the API reports.
• Gap: there's no end-to-end RPC success test, because the peer simulator doesn't serve block headers.

Notes for reviewers

• Testnet11's relative block height is 8, not 32. That's what its launcher solution contains.
• Failed lookups return an error, never an address.
• Single-peer trust. Verification trusts one peer (the one claiming the highest peak), as the rest of Sage does.
• Reorg coverage is partial. Invalidation only fires when the wallet's own coins change, so some reorgs are missed. This only affects the 24-hour offline window.
• Small repo-wide changes:
  • clippy.toml (doc-valid-idents = ["XCHandles", ".."])
  • SyncCommand::SwitchNetwork now carries a Box<Network>
  • bindings.ts is regenerated, which reverts a whitespace-only hand edit from Add coin_ids to send_xch, send_cat, cancel_offer and cancel_offers #895

---

Note

High Risk
Changes payment-adjacent resolution (wrong address = lost funds), persists trust decisions in SQLite, and touches sync/DID parsing; verification relies on a single peer like the rest of the wallet.

Overview
Adds XCHandles support so wallets can resolve @handle names to addresses with on-chain verification, not API trust alone.

resolve_handle is exposed through RPC/OpenAPI and Tauri. It fetches index data from the configured listener API, verifies registry slot lineage and coin state via peers, follows the resolved NFT/DID to the current owner puzzle hash, and returns a rich HandleRecord (including verified vs changed, optional cached fallback, and proof metadata). Lookups are bounded by a 15s timeout; unsupported or custom networks without a matching genesis/inherit chain reject resolution.

Per-network XchandlesConfig (mainnet/testnet11 built-ins, optional override) pins registry constants checked against on-chain launcher solutions. A new xchandles SQLite table caches verified mappings with status (verified / unverified / stale), change tracking, offline 24h reuse, and reorg invalidation when peer peaks roll back.

Sync hardening: NewPeakWallet can mark handle rows stale after forks; DID sync parsing now requires hint/clawback memos to match the actual puzzle hash.

Also adds VITE_DISABLE_XCHANDLES, sqlx query artifacts, and extensive unit/simulator tests (not wired into UI send flow yet).

^{Reviewed by Cursor Bugbot for commit d2c57de. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 283da99. Configure here.}