Client support for third-party HTLC vtxos (trustless swap bridges)

Speaks the proposed VtxoPolicy::Htlc (type byte 0x08): policy encode/decode,
two-leaf taproot (claimer-with-preimage / refunder-after-expiry), preimage
field on the arkoor cosign request, and GetHtlcPreimage.

ArkManager gains the swap primitives: htlcLock (lock funds claimable only
against a payment hash, refundable by us after expiry), htlcClaim (reveal the
preimage), htlcCosignRefund (hand an unclaimable HTLC back — the server
constrains the outputs to the refunder, so this is safe to expose publicly)
and acceptHtlcRefund.

tools/ark/htlc-bridge-test.js drives a full submarine swap between two
independent wallets against a patched captaind, and asserts the ASP rejects
both a wrong-preimage claim and a preimage-less spend to the bridge itself.

Co-Authored-By: Claude Fable 5 <[email protected]>

1 files changed, 6 insertions, 0 deletions

diff --git a/src/ark/proto.js b/src/ark/proto.js
index bb8918d..6729465 100644
--- a/src/ark/proto.js
+++ b/src/ark/proto.js
@@ -316,6 +316,12 @@ function decodePolicy(r) {
     type: 'serverHtlcRecv', userPubkey: hex.encode(r.bytes(33)),
     paymentHash: hex.encode(r.bytes(32)), htlcExpiry: r.u32(), htlcExpiryDelta: r.u16(),
   };
+  // third-party HTLC (claim/refund between two users) — see the upstream
+  // proposal in docs/third-party-htlc.md
+  if (type === 0x08) return {
+    type: 'htlc', claimPubkey: hex.encode(r.bytes(33)), refundPubkey: hex.encode(r.bytes(33)),
+    paymentHash: hex.encode(r.bytes(32)), htlcExpiry: r.u32(),
+  };
   throw new Error('unknown vtxo policy type ' + type);
 }