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, 15 insertions, 0 deletions

diff --git a/src/ark/lightning.js b/src/ark/lightning.js
index c9d3ce1..bbfe958 100644
--- a/src/ark/lightning.js
+++ b/src/ark/lightning.js
@@ -222,3 +222,18 @@ export async function cancelLightningReceive(ark, paymentHash) {
   w.bytesField(1, paymentHash);
   await grpcCall(ark, 'bark_server.ArkService/CancelLightningReceive', w.finish());
 }
+
+// ---------------------------------------------------------------------------
+// third-party HTLCs (proposed VtxoPolicy::Htlc — see docs/third-party-htlc.md)
+// ---------------------------------------------------------------------------
+
+// The preimage revealed by a cosigned claim of an HTLC-policy vtxo, or null
+// until it has been revealed. This is how a swap provider learns the preimage
+// for the invoice it is holding.
+export async function getHtlcPreimage(ark, paymentHash) {
+  const w = pbWriter();
+  w.bytesField(1, paymentHash);
+  const data = await grpcCall(ark, 'bark_server.ArkService/GetHtlcPreimage', w.finish());
+  for (const { field, value } of pbFields(data)) if (field === 1) return hex.encode(value);
+  return null;
+}