feat(connect): PSBT signing, NFT mint/swap flows, and error callbacks

[cdonnachie]

Summary

Extends the photonic-connect deep-link protocol with five new request types built on top of the existing sign-request handshake, so a dApp (e.g. realm.rxd) can drive real wallet actions, not just message signing:

• psbt-sign-request — sign a Radiant PSBT. New BIP-174-profile module (packages/lib/src/psbt), byte-compatible with Radiant Core (bare CTxOut under key 0x00, legacy-serialized unsigned tx, FORKID sighash via radiantjs's Sighash.sign). Returns the (possibly partial) signed PSBT, or finalizes/broadcasts and returns a txid when the request opts in with broadcast: true.
• mint-request — mint an NFT from dApp-supplied metadata + content (embedded or remote), self-funded from the wallet's own UTXOs (never dApp-specified inputs), with a broadcast: false dry-run mode to inspect the built commit/reveal hex before anything is sent.
• swap-offer-request / swap-accept-request / swap-cancel-request — list, buy, and cancel NFT-for-RXD offers on top of the existing raw-tx-hex "PSRT" swap primitive, including an optional marketplace platform fee (feeRxd/feeAddress) that sits alongside — but distinct from — creator royalty.
• A generic error callback (#error=<code>&message=...), distinct from both success and explicit user-reject, fired from every request type's failure path so a dApp can tell "wallet-side failure" (locked, insufficient funds, not found, already spent) apart from "user declined" instead of just hanging until its own timeout.

Also:

• The swap-accept approval screen now resolves and shows the actual NFT being purchased (thumbnail + name), not just the price, by looking up the PSRT's reserved prevout — previously it only ever showed price.
• signPsbt/finalizePsbt now cryptographically verify an existing partial signature (via Sighash.verify) before trusting it, rather than a pubkey-hash match alone — closes a gap where a malformed/malicious PSBT could get finalized as "complete" without a valid signature.
• Post-broadcast bookkeeping in the swap-offer and mint flows is now best-effort: a failure after the irreversible on-chain broadcast no longer surfaces as a false "error" to the dApp.

See docs/psbt.md, docs/mint-request.md, and docs/swap-request.md for the full wire-format writeups, including the naming disambiguation between the new BIP-174 PSBT container, the pre-existing "PSRT" swap convention, and the unrelated DeployMethod: "psbt" mint-reveal helper.

Test plan

• pnpm --filter @photonic/lib test — 942 passed / 22 intentionally-skipped regtest
• pnpm --filter @photonic/app test — 504 passed
• tsc --noEmit clean in both packages/lib and packages/app
• Manual: exercise each new connect request type end-to-end against a running dApp (mint, list, buy, cancel) and confirm callback/error-callback behavior

[TheArtofSatoshi]

Code review

Verdict: high-quality, security-conscious work — LGTM with a few non-blocking suggestions. I found no exploitable flaw in the trust boundary. Everything below is hardening/UX, not a bug that loses funds.

Verification (run against this PR's head in an isolated worktree)

• @photonic/lib: 942 passed / 22 skipped — matches the PR description exactly; tsc --noEmit clean.
• @photonic/app: 493 passed, 1 suite failed to load — the failure is src/predict/odds.test.ts, which imports radiantswap (a link:../../../RadiantSwap sibling dependency absent from an isolated worktree). Same cause for the app tsc errors, all confined to predict/*. Environmental, unrelated to this PR — consistent with the 504 count in a checkout that has the sibling repo.

Security analysis

The trust boundary is handled well:

• Callback discipline. Callbacks are origin-bound at parse time (cleanCallback requires url.origin === declared origin, strips credentials and fragments), results ride in the URL fragment (never the query, so never in server access logs), and oversized URLs fall back to manual copy/paste rather than truncating.
• Signing policy. FORKID mandatory, SIGHASH_NONE refused, token-bearing inputs refused outright (prevents co-signing a token burn), and only the wallet's own P2PKH-script inputs get signed. broadcast: true requires the literal boolean.
• The declared-prevout gap is closed correctly. A PSBT's utxo field is attacker-controlled, but enrichPsbt cross-checks every input against db.txo and hard-blocks on script/value mismatch — and Radiant's FORKID sighash commits to the spent script and value anyway, so a lie only ever yields an unusable signature.
• Both known radiantjs traps are avoided. Output-script decoding goes through the strict anchored parseP2pkhScript, never Script.toAddress() (which has the input-classification fallback spoof), and Sighash.verify — which throws on malformed input — is wrapped in try/catch inside isValidPartialSig.
• The partial-signature verification fix is real. Garbage bytes claiming the wallet's own pubkey can no longer be finalized as "complete"; both signPsbt and finalizePsbt verify cryptographically before trusting, and there's a test covering exactly that.
• Mint self-funding. dApps never specify inputs; content is MIME-allow-listed and SVG passes through the existing sanitizer. A dApp-supplied feeRate is bounded because mintToken builds via buildTx, whose feeCheck caps at ~2.4x min-relay — so the worst a hostile feeRate achieves is modest overpayment, not a drain.
• Double-broadcast defense. The Unlock.tsx fix (clearing onCloseCallback after use) plus the synchronous approveInFlightRef guard in Connect.tsx is a correct belt-and-suspenders pair.
• Post-broadcast "best-effort bookkeeping" — not reporting an error to the dApp after an irreversible broadcast already succeeded — is the right call, and it's applied consistently in both the mint and swap-offer flows.

Suggestions (non-blocking, roughly in priority order)

1. The swap-accept approval screen omits the enforced creator royalty. acceptSwapOffer adds royalty outputs when royalty.enforced, so the taker's real debit is price + royalty + marketplace fee + network fee, but the panel shows only price and fee. This matches existing SwapLoad.tsx behavior, so it isn't a regression — but a dApp-initiated flow raises the bar for showing total cost. previewSwapAccept already resolves the glyph, so extending it to call getTokenRoyalty and render a royalty line would close this.
2. The mint panel doesn't show a dApp-supplied feeRate override. Bounded by feeCheck as noted, but the approval screen should display something like "Fee rate: N photons/byte (app-requested)" when req.feeRate is present, so a bumped fee isn't silent.
3. The mint preview renders pre-sanitization SVG bytes. ContentPreview uses raw request.main.data while the minted payload is sanitizeSvgBytes(...) output. There's no script-execution risk in an <img> context, but what the user approves should be byte-identical to what gets minted — render the sanitized bytes.
4. Misleading blocker on a fully-signed-but-unfinalized PSBT. signableCount excludes own inputs that already carry a valid partial signature, so a PSBT whose wallet inputs are all signed but not yet finalized trips the "None of this transaction's inputs belong to your wallet" blocker. Safe refusal, wrong message — and it blocks a legitimate finalize-only use.
5. feeAddress is validated charset-only at parse time. An invalid base58check address only fails later inside p2pkhScript (which does throw cleanly, so no silent burn). Validating base58check and network at parse time would fail faster with a better error code.
6. Minor. The six near-identical build*CallbackUrl functions could collapse into one generic buildCallbackFragmentUrl(callback, params) helper. Also, the error callback forwards raw Error.message strings to the dApp — currently harmless since txids are public, but a note at the throw sites that messages must stay leak-free would guard against regression.

Code quality

Consistently strong. The PSBT module is defensive in the ways that matter: canonical varint enforcement, duplicate-key rejection, trailing-data checks, bigint value plumbing past 2^53, and unknown-field preservation for byte-identical round-trips. Commentary explains why at every non-obvious decision, the error taxonomy is typed rather than string-matched, and test coverage is dense and adversarial (123 protocol tests, fabricated-signature and non-canonical-varint cases, a buildTx-interchangeability proof). Wire-format docs for all three new surfaces are included. classifyConnectError's string matching is self-admittedly approximate, which is fine as long as it stays labeled a hint — as the docstring already does.

Reviewed with Claude Code