Add the trustless Ark->Lightning swap bridge

A third-party swap provider built on the proposed VtxoPolicy::Htlc: users pay
bolt11 invoices from their Ark balance without the ASP being the counterparty
and without trusting the bridge with custody.

Scope is deliberately one-directional. An ASP's lightning *receive* is already
free (0 base / 0 ppm on mainnet); the expensive leg is *send*, with a 20 sat
floor that eats 80% of a 25 sat zap. Only that leg is worth undercutting.

- bridge/server.js: /info, /quote, /swap, /refund over Bun.serve. Validates
  the user's HTLC fully (policy, hash, amount, expiry margin, full vtxo chain)
  before spending anything on Lightning, pays, then claims with the preimage.
  Crash-safe: state is written atomically and every step re-checks reality
  (listpays before paying, so a resumed bridge never double-pays).
- bridge/ln.js: minimal CLN backend (unix socket or docker exec), named
  params, maxfee-capped pay, pending/paid introspection.
- /refund is safe to expose publicly: the ASP only cosigns a preimage-less
  HTLC spend when every output pays the refunder, so it cannot be redirected.

tools/ark/bridge-e2e-test.js drives the real HTTP API against the patched
regtest ASP: a 25 sat zap costs 1 sat, the far-end invoice really settles, the
preimage checks out, resubmission is idempotent, an unroutable invoice reports
refundable rather than done, and the refund lands every sat back.

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

1 files changed, 12 insertions, 0 deletions

diff --git a/bridge/config.example.json b/bridge/config.example.json
new file mode 100644
index 0000000..fee8ad7
--- /dev/null
+++ b/bridge/config.example.json
@@ -0,0 +1,12 @@
+{
+  "port": 8790,
+  "network": "regtest",
+  "ark": "http://127.0.0.1:3535",
+  "esplora": "http://127.0.0.1:30002",
+  "mnemonic": "REPLACE with a 12/24-word mnemonic — this wallet holds bridge float",
+  "stateFile": "./data/bridge.json",
+  "ln": { "kind": "docker", "container": "clc", "network": "regtest" },
+  "fee": { "baseSat": 0, "ppm": 1000, "minSat": 1 },
+  "limits": { "minSat": 1, "maxSat": 1000000, "htlcBlocks": 144 },
+  "tokens": []
+}