Validate redemption wallet UTXOs

[mswilkison]

Summary

• validate redemption-wallet API candidates against current Bridge wallet state
• skip API candidates that are not Live or whose on-chain public key disagrees
• re-resolve stale API main UTXOs from Bitcoin history before requesting redemption
• cap spendable balance to min(API balance, current main UTXO minus Bridge pending redemptions)
• point the SDK redemption-wallet lookup at https://api.threshold.network and keep the old TBTC_EXPLORER enum member as a deprecated compatibility alias
• update TypeScript API docs and add regression coverage for stale UTXO, unresolvable stale UTXO, API balance capping, over-reserved pending redemptions, non-Live wallets, and public-key mismatch

Behavioral note

• Callers may now receive "Could not find a wallet with enough funds." when the API returns stale or invalid candidates that would previously reach requestRedemption and likely revert on-chain.
• The replacement /tbtc/redemption-wallet backend endpoint lives in tlabs-xyz/threshold-api#17, superseding the backend-services-era work from tlabs-xyz/tbtc#396.

Verification

• ./node_modules/.bin/tsc --project tsconfig.build.json --noEmit
• ./node_modules/.bin/eslint src/services/redemptions/redemptions-service.ts test/services/redemptions.test.ts
• /Users/maclane/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node ./node_modules/mocha/bin/mocha --exit test/services/redemptions.test.ts
• ./node_modules/.bin/typedoc --options typedoc.json
• ./node_modules/.bin/prettier --check src/services/redemptions/redemptions-service.ts test/services/redemptions.test.ts api-reference/classes/RedemptionsService.md
• ./node_modules/.bin/eslint src/lib/utils/api.ts src/services/redemptions/redemptions-service.ts
• ./node_modules/.bin/prettier --check src/lib/utils/api.ts src/services/redemptions/redemptions-service.ts api-reference/enums/ApiUrl.md api-reference/enums/endpointUrl.md
• rg -n "api.tbtcscan.com" .
• git diff --check

[piotr-roslaniec]

Status update — the consumer endpoint is now live in prod, so the merge-order constraint for this PR is lifted.

api.threshold.network/tbtc/redemption-wallet is live (Worker threshold-api version 40286f74-1279-4c7f-9b7c-2cd93cdeb360, deployed 2026-05-20 from tlabs-xyz/threshold-api#17 squash-merge 6412182).

$ curl -s https://api.threshold.network/tbtc/redemption-wallet | jq '.data.candidateResults | length'
8

Cross-PR contract validated end-to-end (Tier-A integration smoke against mainnet, prior to deploy):

• RedemptionsService.fetchWalletsForRedemption() decodes the Worker's response cleanly — 8 candidates, all conformant to SerializableWallet.
• determineValidRedemptionWallet(100_000 sat) selected a Live wallet and the result cross-checked against bridge.wallets(pubKeyHash) (state=1, pubkey match, utxo value 498_946_018 sat).
• Smoke harness: protected methods exposed via test subclass; StubBitcoinClient rejects every Electrum call except getNetwork(), so any unintended stale-UTXO re-resolution would have surfaced. It did not — all API UTXOs matched Bridge state at sample time.

Coverage notes for reviewers:

• Stale-UTXO re-resolution branch in determineWalletMainUtxo was not exercised by the live smoke (no stale UTXOs on chain). Coverage relies on the test additions in test/services/redemptions.test.ts.
• requestRedemption write path not exercised (read+validate surface is what this PR changes).
• Cross-chain redemption path not exercised.

Happy to walk anyone through the smoke setup. Ready to merge from my side once an approver signs off.