beignet 0.15.1 → 0.17.0

package/README.md

@@ -497,23 +497,35 @@ node can run for others, each an explicit opt-in switched on with an exact
 The SSE stream carries `ffor:state`, `ffor:settled`, `ffor:delegated-failed`,
 `ffor:enforce` and the witness and issuer events.
 
-### Reverse swaps (Lightning to on-chain)
+### Swaps (Lightning to on-chain, and on-chain to Lightning)
 
-A beignet node can serve reverse swaps to any Lightning peer (issue #737): the
-peer pays a hold invoice, this node funds a P2WSH contract the peer claims on
-chain with its preimage, and the claim settles the hold. The role is an
-explicit opt-in switched on with an exact `true`, because it locks this node's
-own coins in contracts for peers:
+A beignet node can serve swaps to any Lightning peer in both directions.
+Reverse (issue #737): the peer pays a hold invoice, this node funds a P2WSH
+contract the peer claims on chain with its preimage, and the claim settles
+the hold. Submarine (issue #743): the peer locks coins in a P2WSH contract,
+this node pays the peer's own invoice under an absolute HTLC expiry ceiling,
+and the preimage that payment reveals claims the coins. Each direction is an
+explicit opt-in switched on with an exact `true`, because it puts this node's
+own funds at risk for peers:
 
 | Env | Role |
 |---|---|
 | `BEIGNET_SWAPS` | Serve reverse swaps. `BEIGNET_SWAP_FLAT_FEE_SAT` and `BEIGNET_SWAP_FEE_PPM` price them; `BEIGNET_SWAP_MIN_SAT`, `BEIGNET_SWAP_MAX_SAT`, `BEIGNET_SWAP_MAX_EXPOSURE_SAT` and `BEIGNET_SWAP_MAX_CONCURRENT` cap what is at risk; `BEIGNET_SWAP_REFUND_DELTA_BLOCKS`, `BEIGNET_SWAP_FUNDING_CONFS` and `BEIGNET_SWAP_RESOLUTION_CONFS` set the timing. `GET /swaps/status`, `GET /swaps`, `POST /swaps/cancel`. |
-
-The provider funds only against the complete committed MPP set of the hold
-invoice, settles the hold the moment a claim reveals the preimage (mempool
-included), and cancels the hold only after its own refund has confirmed to
-policy depth; never because the refund height passed. The SSE stream carries
-`swap:created` through `swap:settled`, `swap:refunded` and `swap:exposed`.
+| `BEIGNET_SWAP_SUBMARINE` | With `BEIGNET_SWAPS`, also serve submarine swaps (on-chain to Lightning): a peer locks coins in a contract, this node pays the peer's invoice under an absolute HTLC expiry ceiling and claims the coins with the preimage. `BEIGNET_SWAP_CLAIM_SAFETY_BLOCKS`, `BEIGNET_SWAP_PAYMENT_MAX_FEE_PPM`, `BEIGNET_SWAP_CLAIM_BUMP_INTERVAL_BLOCKS` and `BEIGNET_SWAP_SUBMARINE_REFUND_DELTA_BLOCKS` set the direction's margins; the fee and exposure caps above apply to both. |
+
+The reverse provider funds only against the complete committed MPP set of
+the hold invoice, settles the hold the moment a claim reveals the preimage
+(mempool included), and cancels the hold only after its own refund has
+confirmed to policy depth; never because the refund height passed. The
+submarine provider pays only once the peer's funding has confirmed to policy
+depth and been re-verified unspent immediately before the dispatch, binds
+every HTLC of the payment to `refundHeight` minus its claim margins, judges
+the payment by the node's own HTLC view (never by a wall clock or a failed
+record while an HTLC is out), and persists its claim before broadcasting it.
+The SSE stream carries `swap:created` through `swap:settled`, `swap:refunded`
+and `swap:exposed` for the reverse direction and `swap:funding-seen`,
+`swap:paying`, `swap:preimage`, `swap:claim-broadcast`,
+`swap:claim-confirmed` and `swap:payment-failed` for the submarine one.
 
 ## Protocol layer (advanced)
 
@@ -616,7 +628,7 @@ LightningNode              High-level API (EventEmitter)
 | `recovery/` | Safety transition layer: atomic persistence, the durable outbound-message outbox, the opt-in hash-chained recovery journal, and the peer_storage Recovery Capsule |
 | `liquidity/` | JIT channel receive (LSP role): intercept SCIDs, held HTLCs, zero-conf open or splice, then forward; the opening fee is skimmed off the delivery for wallets that accept it, or charged to the sender through the invoice hint (hop mode) for wallets that cannot settle a short HTLC |
 | `direct-funding/` | Third-party direct funding: the signed payment request envelope, sealed frames, protocol messages, outstanding-request store, the transport registry with its direct-peer, onion and blind-relay lanes, the receiver engine that turns a payer's offered UTXO into channel funding, and the payer engine that verifies and signs it |
-| `swaps/` | Swaps: the P2WSH HTLC contract, claim/refund transactions, preimage extraction, admission policies, the durable swap ledger, the chain resolver, the wire protocol, and the reverse swap provider engine (Lightning to on-chain) |
+| `swaps/` | Swaps: the P2WSH HTLC contract, claim/refund transactions, preimage extraction, admission policies, the durable swap ledger, the chain resolver, the wire protocol, and the swap provider engines (reverse: Lightning to on-chain; submarine: on-chain to Lightning) |
 | `l402/` | L402 (Lightning HTTP 402) client: challenge parsing, macaroon reading, paid credentials |
 | `node/` | LightningNode orchestrator, the main protocol-layer entry point |
 | `wallet/` | WalletFundingProvider, adapts the on-chain Wallet for auto-funded opens |

package/dist/cli/beignet-node.js

@@ -977,6 +977,29 @@ class BeignetNode extends events_1.EventEmitter {
                                 refundDeltaBlocks: opts.swaps.refundDeltaBlocks
                             }
                         }
+                        : {}),
+                    ...(opts.swaps.submarine === true
+                        ? {
+                            submarine: {
+                                enabled: true,
+                                ...(opts.swaps.claimSafetyBlocks !== undefined
+                                    ? { claimSafetyBlocks: opts.swaps.claimSafetyBlocks }
+                                    : {}),
+                                ...(opts.swaps.paymentMaxFeePpm !== undefined
+                                    ? { paymentMaxFeePpm: opts.swaps.paymentMaxFeePpm }
+                                    : {}),
+                                ...(opts.swaps.claimBumpIntervalBlocks !== undefined
+                                    ? {
+                                        claimBumpIntervalBlocks: opts.swaps.claimBumpIntervalBlocks
+                                    }
+                                    : {}),
+                                ...(opts.swaps.submarineRefundDeltaBlocks !== undefined
+                                    ? {
+                                        refundDeltaBlocks: opts.swaps.submarineRefundDeltaBlocks
+                                    }
+                                    : {})
+                            }
+                        }
                         : {})
                 }
                 : undefined,
@@ -1280,7 +1303,27 @@ class BeignetNode extends events_1.EventEmitter {
             'ffor:witness-recorded',
             'ffor:witness-released',
             'ffor:issuer-provisioned',
-            'ffor:issuer-issued'
+            'ffor:issuer-issued',
+            'swap:created',
+            'swap:held',
+            'swap:funding',
+            'swap:funded',
+            'swap:claimed',
+            'swap:settled',
+            'swap:refund-broadcast',
+            'swap:refunded',
+            'swap:hold-cancelled',
+            'swap:exposed',
+            'swap:failed',
+            'swap:funding-seen',
+            'swap:funding-lost',
+            'swap:paying',
+            'swap:payment-unresolved',
+            'swap:preimage',
+            'swap:claim-broadcast',
+            'swap:claim-confirmed',
+            'swap:payment-failed',
+            'swap:cancelled'
         ]) {
             this.node.on(evt, (data) => {
                 this.emit(evt, jsonSafeEvent(data));
@@ -4247,7 +4290,26 @@ class BeignetNode extends events_1.EventEmitter {
             timeouts: status.timeouts,
             counts: status.counts,
             exposedSat: Number(status.exposedSat),
-            exposedCount: status.exposedCount
+            exposedCount: status.exposedCount,
+            submarine: status.submarine.enabled
+                ? {
+                    enabled: true,
+                    fee: {
+                        flatFeeSat: Number(status.submarine.fee.flatFeeSat),
+                        feePpm: status.submarine.fee.feePpm
+                    },
+                    limits: {
+                        minSwapSat: Number(status.submarine.limits.minSwapSat),
+                        maxSwapSat: Number(status.submarine.limits.maxSwapSat),
+                        maxTotalExposureSat: Number(status.submarine.limits.maxTotalExposureSat),
+                        maxConcurrentSwaps: status.submarine.limits.maxConcurrentSwaps
+                    },
+                    timeouts: status.submarine.timeouts,
+                    counts: status.submarine.counts,
+                    exposedSat: Number(status.submarine.exposedSat),
+                    exposedCount: status.submarine.exposedCount
+                }
+                : { enabled: false }
         };
     }
     listSwaps(id) {
@@ -4937,7 +4999,19 @@ class BeignetNode extends events_1.EventEmitter {
         }
         return { status, summary, checks, invoice };
     }
-    async payInvoice(bolt11, timeoutMs = 60000, maxFeeSats, amountSats, metadata) {
+    _cltvCeiling(cltvLimit) {
+        if (cltvLimit === undefined)
+            return undefined;
+        if (!Number.isSafeInteger(cltvLimit) || cltvLimit < 1) {
+            throw new errors_1.BeignetError('INVALID_PARAMS', 'cltvLimit must be a positive integer number of blocks');
+        }
+        const height = this.node.getCurrentBlockHeight();
+        if (!(height > 0)) {
+            throw new errors_1.BeignetError('CHAIN_NOT_SYNCED', 'cltvLimit needs the current block height, which is not known yet');
+        }
+        return height + cltvLimit;
+    }
+    async payInvoice(bolt11, timeoutMs = 60000, maxFeeSats, amountSats, metadata, cltvLimit) {
         this._checkDraining();
         const decoded = decodeInvoiceInput(bolt11);
         const paymentHashHex = decoded.paymentHash.toString('hex');
@@ -4950,6 +5024,7 @@ class BeignetNode extends events_1.EventEmitter {
             ? BigInt(requireNonNegativeSafeInteger(amountSats, 'amountSats')) *
                 1000n
             : undefined;
+        const maxCltvExpiryHeight = this._cltvCeiling(cltvLimit);
         if (spendAmountSats > 0) {
             this._checkMaxPayment(spendAmountSats);
             this._checkSpendLimit(spendAmountSats);
@@ -5015,7 +5090,7 @@ class BeignetNode extends events_1.EventEmitter {
             this.node.on('payment:sent', onSent);
             this.node.on('payment:failed', onFailed);
             try {
-                this.node.sendPayment(bolt11, undefined, maxFeeMsat, amountMsat);
+                this.node.sendPayment(bolt11, undefined, maxFeeMsat, amountMsat, maxCltvExpiryHeight);
             }
             catch (err) {
                 cleanup();
@@ -5029,6 +5104,7 @@ class BeignetNode extends events_1.EventEmitter {
                         DUPLICATE_PAYMENT: 'DUPLICATE_PAYMENT',
                         NO_CHANNEL_TO_HOP: 'PEER_NOT_CONNECTED',
                         FEE_EXCEEDS_MAX: 'PAYMENT_FAILED',
+                        CLTV_EXCEEDS_MAX: 'CLTV_EXCEEDS_MAX',
                         MISSING_AMOUNT: 'INVALID_PARAMS',
                         INVALID_INVOICE: 'INVALID_PARAMS',
                         INVOICE_EXPIRED: 'INVOICE_EXPIRED'
@@ -5048,9 +5124,9 @@ class BeignetNode extends events_1.EventEmitter {
             }
         });
     }
-    async payInvoiceSafe(bolt11, timeoutMs = 60000, maxFeeSats, amountSats, metadata) {
+    async payInvoiceSafe(bolt11, timeoutMs = 60000, maxFeeSats, amountSats, metadata, cltvLimit) {
         try {
-            return await this.payInvoice(bolt11, timeoutMs, maxFeeSats, amountSats, metadata);
+            return await this.payInvoice(bolt11, timeoutMs, maxFeeSats, amountSats, metadata, cltvLimit);
         }
         catch (err) {
             let hashHex = 'unknown';
@@ -5090,7 +5166,7 @@ class BeignetNode extends events_1.EventEmitter {
         let lastError;
         for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
             try {
-                const result = await this.payInvoice(bolt11, 60000, opts.maxFeeSats, opts.amountSats, opts.metadata);
+                const result = await this.payInvoice(bolt11, 60000, opts.maxFeeSats, opts.amountSats, opts.metadata, opts.cltvLimit);
                 return { ...result, attempts: attempt };
             }
             catch (err) {
@@ -5180,7 +5256,7 @@ class BeignetNode extends events_1.EventEmitter {
             attempts: maxRetries + 1
         };
     }
-    sendPaymentAsync(bolt11, maxFeeSats, amountSats, metadata) {
+    sendPaymentAsync(bolt11, maxFeeSats, amountSats, metadata, cltvLimit) {
         this._checkDraining();
         const decoded = decodeInvoiceInput(bolt11);
         const paymentHashHex = decoded.paymentHash.toString('hex');
@@ -5193,6 +5269,7 @@ class BeignetNode extends events_1.EventEmitter {
             ? BigInt(requireNonNegativeSafeInteger(amountSats, 'amountSats')) *
                 1000n
             : undefined;
+        const maxCltvExpiryHeight = this._cltvCeiling(cltvLimit);
         let claim;
         if (spendAmountSats > 0) {
             this._checkMaxPayment(spendAmountSats);
@@ -5204,11 +5281,15 @@ class BeignetNode extends events_1.EventEmitter {
             if (metadata) {
                 this.node.setPaymentMetadata(decoded.paymentHash, metadata);
             }
-            result = this.node.sendPayment(bolt11, undefined, maxFeeMsat, amountMsat);
+            result = this.node.sendPayment(bolt11, undefined, maxFeeMsat, amountMsat, maxCltvExpiryHeight);
         }
         catch (err) {
             if (claim)
                 this._closeAsyncSpendClaim(paymentHashHex, claim);
+            if (err instanceof Error &&
+                err.code === 'CLTV_EXCEEDS_MAX') {
+                throw new errors_1.BeignetError('CLTV_EXCEEDS_MAX', err.message);
+            }
             throw err;
         }
         if (claim && result.status === 'FAILED') {