@atomiqlabs/lp-lib 17.5.3 → 17.6.1

package/dist/swaps/escrow/tobtcln_abstract/ToBtcLnAbs.js

@@ -33,9 +33,10 @@ class ToBtcLnAbs extends ToBtcBaseSwapHandler_1.ToBtcBaseSwapHandler {
         this.config.minLnBaseFee = this.config.minLnBaseFee || 5n;
         this.config.exactInExpiry = this.config.exactInExpiry || 10 * 1000;
         this.config.lnSendBitcoinBlockTimeSafetyFactorPPM = this.config.lnSendBitcoinBlockTimeSafetyFactorPPM ?? (this.config.safetyFactor * 1000000n);
-        if (this.config.lnSendBitcoinBlockTimeSafetyFactorPPM <= 1100000n) {
-            throw new Error("Lightning network send block safety factor set below 1.1, this is insecure!");
+        if (this.config.lnSendBitcoinBlockTimeSafetyFactorPPM <= 1250000n) {
+            throw new Error("Lightning network send block safety factor set below 1.25, this is insecure!");
         }
+        this.cltvDeltaLowerBound = (0, Utils_1.getMinSafeBlockWindowSlow)(Number(this.config.lnSendBitcoinBlockTimeSafetyFactorPPM) / 1000000);
     }
     /**
      * Cleans up exactIn authorization that are already past their expiry
@@ -100,7 +101,8 @@ class ToBtcLnAbs extends ToBtcBaseSwapHandler_1.ToBtcBaseSwapHandler {
             }
         ]);
         for (let { obj: swap } of queriedData) {
-            await this.processPastSwap(swap);
+            await this.processPastSwap(swap)
+                .catch(e => this.swapLogger.error(swap, "processPastSwap(): Error executing watchdog function: ", e));
         }
     }
     /**
@@ -198,6 +200,10 @@ class ToBtcLnAbs extends ToBtcBaseSwapHandler_1.ToBtcBaseSwapHandler {
             this.swapLogger.info(invoiceData, "subscribeToPayment(): result callback, outcome: " + result.status + " invoice: " + invoiceData.pr);
             this.processPaymentResult(invoiceData, result).catch(e => this.swapLogger.error(invoiceData, "subscribeToPayment(): process payment result", e));
             this.activeSubscriptions.delete(paymentHash);
+        }).catch(e => {
+            this.swapLogger.error(invoiceData, "subscribeToPayment(): error while waiting for invoice payment: ", e);
+            //Delete from active subscription, the watchdog will re-subscribe later
+            this.activeSubscriptions.delete(paymentHash);
         });
         this.swapLogger.info(invoiceData, "subscribeToPayment(): subscribe to payment outcome, invoice: " + invoiceData.pr);
         this.activeSubscriptions.add(paymentHash);
@@ -224,6 +230,11 @@ class ToBtcLnAbs extends ToBtcBaseSwapHandler_1.ToBtcBaseSwapHandler {
         const maxFee = swap.quotedNetworkFee;
         const maxUsableCLTVdelta = (expiryTimestamp - currentTimestamp - this.config.gracePeriod)
             / (this.config.bitcoinBlocktime * this.config.lnSendBitcoinBlockTimeSafetyFactorPPM / 1000000n);
+        if (maxUsableCLTVdelta < this.cltvDeltaLowerBound)
+            throw {
+                code: 90008,
+                msg: "Calculated CLTV delta is too low for current safety factor!"
+            };
         //Initiate payment
         this.swapLogger.info(swap, "sendLightningPayment(): paying lightning network invoice," +
             " cltvDelta: " + maxUsableCLTVdelta.toString(10) +
@@ -311,6 +322,9 @@ class ToBtcLnAbs extends ToBtcBaseSwapHandler_1.ToBtcBaseSwapHandler {
                 else
                     throw e;
             }
+            const unlock = swap.lock(120);
+            if (unlock == null)
+                return;
             await swap.setState(ToBtcLnSwapAbs_1.ToBtcLnSwapState.COMMITED);
             await this.saveSwapData(swap);
             try {
@@ -322,13 +336,29 @@ class ToBtcLnAbs extends ToBtcBaseSwapHandler_1.ToBtcBaseSwapHandler {
                 if ((0, Utils_1.isDefinedRuntimeError)(e)) {
                     if (swap.metadata != null)
                         swap.metadata.payError = e;
-                    await swap.setState(ToBtcLnSwapAbs_1.ToBtcLnSwapState.NON_PAYABLE);
-                    await this.saveSwapData(swap);
-                    return;
+                    const payment = await this.lightning.getPayment(swap.lnPaymentHash);
+                    if (!unlock())
+                        return;
+                    if (payment == null || payment.status === "failed") {
+                        if (swap.state === ToBtcLnSwapAbs_1.ToBtcLnSwapState.COMMITED)
+                            await swap.setState(ToBtcLnSwapAbs_1.ToBtcLnSwapState.NON_PAYABLE);
+                        await this.saveSwapData(swap);
+                        return;
+                    }
+                    else if (payment.status === "confirmed") {
+                        await this.processPaymentResult(swap, payment);
+                        return;
+                    }
+                    else {
+                        //Fall-through to subscribe
+                    }
                 }
                 else
                     throw e;
             }
+            finally {
+                unlock();
+            }
             this.subscribeToPayment(swap);
             return;
         }
@@ -452,6 +482,11 @@ class ToBtcLnAbs extends ToBtcBaseSwapHandler_1.ToBtcBaseSwapHandler {
     async checkAndGetNetworkFee(amountBD, maxFee, expiryTimestamp, currentTimestamp, pr, metadata, abortSignal) {
         const maxUsableCLTV = (expiryTimestamp - currentTimestamp - this.config.gracePeriod)
             / (this.config.bitcoinBlocktime * this.config.lnSendBitcoinBlockTimeSafetyFactorPPM / 1000000n);
+        if (maxUsableCLTV < this.cltvDeltaLowerBound)
+            throw {
+                code: 20002,
+                msg: "Cannot route the payment (calculated CLTV delta too short - increase timeout)!"
+            };
         const blockHeight = await this.lightning.getBlockheight();
         abortSignal.throwIfAborted();
         metadata.times.blockheightFetched = Date.now();
@@ -658,8 +693,8 @@ class ToBtcLnAbs extends ToBtcBaseSwapHandler_1.ToBtcBaseSwapHandler {
              */
             const parsedBody = await req.paramReader.getParams({
                 pr: SchemaVerifier_1.FieldTypeEnum.String,
-                maxFee: SchemaVerifier_1.FieldTypeEnum.BigInt,
-                expiryTimestamp: SchemaVerifier_1.FieldTypeEnum.BigInt,
+                maxFee: SchemaVerifier_1.FieldTypeEnum.BigIntPositive,
+                expiryTimestamp: SchemaVerifier_1.FieldTypeEnum.BigIntPositive,
                 token: (val) => val != null &&
                     typeof (val) === "string" &&
                     this.isTokenSupported(chainIdentifier, val) ? val : null,
@@ -667,7 +702,7 @@ class ToBtcLnAbs extends ToBtcBaseSwapHandler_1.ToBtcBaseSwapHandler {
                     typeof (val) === "string" &&
                     chainInterface.isValidAddress(val, true) ? val : null,
                 exactIn: SchemaVerifier_1.FieldTypeEnum.BooleanOptional,
-                amount: SchemaVerifier_1.FieldTypeEnum.BigIntOptional
+                amount: SchemaVerifier_1.FieldTypeEnum.BigIntPositiveOptional
             });
             if (parsedBody == null) {
                 throw {
@@ -832,6 +867,16 @@ class ToBtcLnAbs extends ToBtcBaseSwapHandler_1.ToBtcBaseSwapHandler {
                         msg: "Payment expired"
                     };
                 if (data.state === ToBtcLnSwapAbs_1.ToBtcLnSwapState.NON_PAYABLE) {
+                    if (data.payInitiated) {
+                        //Check that the ln payment is indeed non-existent or failed
+                        const lnPayment = await this.lightning.getPayment(data.lnPaymentHash);
+                        if (lnPayment != null && lnPayment.status !== "failed")
+                            throw {
+                                _httpStatus: 200,
+                                code: 20008,
+                                msg: "Payment in-flight"
+                            };
+                    }
                     const refundSigData = await swapContract.getRefundSignature(signer, data.data, this.config.refundAuthorizationTimeout);
                     //Double check the state after promise result
                     if (data.state !== ToBtcLnSwapAbs_1.ToBtcLnSwapState.NON_PAYABLE)

package/dist/swaps/spv_vault_swap/SpvVaultSwapHandler.js

@@ -174,13 +174,21 @@ class SpvVaultSwapHandler extends SwapHandler_1.SwapHandler {
             const vault = await this.Vaults.getVault(swap.chainIdentifier, swap.vaultOwner, swap.vaultId);
             const foundWithdrawal = vault.pendingWithdrawals.find(val => val.btcTx.txid === swap.btcTxId);
             let tx = foundWithdrawal?.btcTx;
-            if (tx == null)
+            if (tx == null) {
                 tx = await this.bitcoinRpc.getTransaction(swap.btcTxId);
+            }
+            else {
+                tx = await (0, BitcoinUtils_1.checkTransactionReplaced)(tx.txid, tx.raw, this.bitcoinRpc);
+            }
             if (tx == null) {
                 await this.removeSwapData(swap, SpvVaultSwap_1.SpvVaultSwapState.FAILED);
+                if (foundWithdrawal != null) {
+                    vault.removeWithdrawal(foundWithdrawal);
+                    await this.Vaults.saveVault(vault);
+                }
                 return;
             }
-            else if (tx.confirmations === 0) {
+            else if (tx.confirmations == null || tx.confirmations === 0) {
                 await swap.setState(SpvVaultSwap_1.SpvVaultSwapState.SENT);
                 await this.saveSwapData(swap);
                 return;
@@ -223,7 +231,8 @@ class SpvVaultSwapHandler extends SwapHandler_1.SwapHandler {
             }
         ]);
         for (let { obj: swap } of swaps) {
-            await this.processPastSwap(swap);
+            await this.processPastSwap(swap)
+                .catch(e => this.swapLogger.error(swap, "processPastSwap(): Error executing watchdog function: ", e));
         }
     }
     getPricePrefetches(chainIdentifier, token, gasToken, abortController) {
@@ -314,11 +323,11 @@ class SpvVaultSwapHandler extends SwapHandler_1.SwapHandler {
              * frontingFeeRate: string      Fronting fee (in output token) to assign to the swap
              */
             const actualParsedBody = await req.paramReader.getParams({
-                amount: SchemaVerifier_1.FieldTypeEnum.BigInt,
-                gasAmount: SchemaVerifier_1.FieldTypeEnum.BigInt,
+                amount: SchemaVerifier_1.FieldTypeEnum.BigIntPositive,
+                gasAmount: SchemaVerifier_1.FieldTypeEnum.BigIntNotNegative,
                 exactOut: SchemaVerifier_1.FieldTypeEnum.BooleanOptional,
-                callerFeeRate: SchemaVerifier_1.FieldTypeEnum.BigInt,
-                frontingFeeRate: SchemaVerifier_1.FieldTypeEnum.BigInt,
+                callerFeeRate: SchemaVerifier_1.FieldTypeEnum.BigIntNotNegative,
+                frontingFeeRate: SchemaVerifier_1.FieldTypeEnum.BigIntNotNegative,
             });
             abortController.signal.throwIfAborted();
             if (actualParsedBody == null)
@@ -328,7 +337,7 @@ class SpvVaultSwapHandler extends SwapHandler_1.SwapHandler {
                 };
             const inputAmountAdjustments = req.paramReader.getExistingParamsOrNull({
                 amountUtxos: SchemaVerifier_1.FieldTypeEnum.AnyOptional,
-                amountFeeRate: SchemaVerifier_1.FieldTypeEnum.NumberOptional
+                amountFeeRate: SchemaVerifier_1.FieldTypeEnum.NumberPositiveOptional
             });
             if (inputAmountAdjustments == null)
                 throw {
@@ -615,14 +624,12 @@ class SpvVaultSwapHandler extends SwapHandler_1.SwapHandler {
                 };
             const pluginCheckResult = await PluginManager_1.PluginManager.onHandlePreFromBtcExecute(SwapHandler_1.SwapHandlerType.FROM_BTC_SPV, swap);
             if ((0, IPlugin_1.isQuoteThrow)(pluginCheckResult)) {
-                const error = {
+                if (swap.state === SpvVaultSwap_1.SpvVaultSwapState.CREATED)
+                    await this.removeSwapData(swap, SpvVaultSwap_1.SpvVaultSwapState.FAILED);
+                throw {
                     code: 29999,
                     msg: pluginCheckResult.message
                 };
-                if (swap.metadata != null)
-                    swap.metadata.postQuoteError = error;
-                await this.removeSwapData(swap, SpvVaultSwap_1.SpvVaultSwapState.FAILED);
-                throw error;
             }
             await this.Vaults.checkVaultReplacedTransactions(vault, true);
             if (swap.vaultUtxo !== vault.getLatestUtxo()) {
@@ -631,26 +638,36 @@ class SpvVaultSwapHandler extends SwapHandler_1.SwapHandler {
                     msg: "Vault UTXO already spent, please get another quote and try again!"
                 };
             }
+            //Double-check the state to prevent race condition
+            if (swap.state !== SpvVaultSwap_1.SpvVaultSwapState.CREATED)
+                throw {
+                    code: 20505,
+                    msg: "Invalid quote ID, not found or expired!"
+                }; //Continues here is only synchronous code until the state change to SIGNED
+            const unlock = swap.lock(120);
+            if (!unlock)
+                throw {
+                    code: 20517,
+                    msg: "Bitcoin transaction submission already in progress, please retry later!"
+                };
+            const txId = signedTx.id;
+            let swapSendingSet = false;
+            let dataSendingSet = false;
             try {
                 const btcRawTx = Buffer.from(signedTx.toBytes(true, true)).toString("hex");
-                //Double-check the state to prevent race condition
-                if (swap.state !== SpvVaultSwap_1.SpvVaultSwapState.CREATED) {
-                    throw {
-                        code: 20505,
-                        msg: "Invalid quote ID, not found or expired!"
-                    };
-                }
                 //Double check in-flight swap count
                 this.checkTooManyInflightSwaps();
-                swap.btcTxId = signedTx.id;
+                swap.btcTxId = txId;
                 swap.state = SpvVaultSwap_1.SpvVaultSwapState.SIGNED;
                 swap.sending = true;
+                swapSendingSet = true;
                 await this.saveSwapData(swap);
                 data.btcTx.raw = btcRawTx;
                 data.sending = true;
                 vault.addWithdrawal(data);
+                dataSendingSet = true;
                 await this.Vaults.saveVault(vault);
-                this.swapLogger.info(swap, "REST: /postQuote: BTC transaction signed, txId: " + swap.btcTxId);
+                this.swapLogger.info(swap, "REST: /postQuote: BTC transaction signed, txId: " + txId);
                 try {
                     await this.bitcoin.sendRawTransaction(btcRawTx);
                     await swap.setState(SpvVaultSwap_1.SpvVaultSwapState.SENT);
@@ -666,14 +683,50 @@ class SpvVaultSwapHandler extends SwapHandler_1.SwapHandler {
                 }
             }
             catch (e) {
-                data.sending = false;
-                swap.sending = false;
-                vault.removeWithdrawal(data);
-                await this.Vaults.saveVault(vault);
-                if ((0, Utils_1.isDefinedRuntimeError)(e) && swap.metadata != null)
-                    swap.metadata.postQuoteError = e;
-                await this.removeSwapData(swap, SpvVaultSwap_1.SpvVaultSwapState.FAILED);
-                throw e;
+                if (swapSendingSet)
+                    swap.sending = false;
+                if (dataSendingSet)
+                    data.sending = false;
+                //We only make the swap failed if the error happened in CREATED or SIGNED states
+                if (swap.state === SpvVaultSwap_1.SpvVaultSwapState.CREATED || swap.state === SpvVaultSwap_1.SpvVaultSwapState.SIGNED) {
+                    try {
+                        const fetchedBtcTx = await this.bitcoin.getWalletTransaction(txId);
+                        if (fetchedBtcTx == null) {
+                            if (dataSendingSet) {
+                                vault.removeWithdrawal(data);
+                                await this.Vaults.saveVault(vault);
+                            }
+                            if ((0, Utils_1.isDefinedRuntimeError)(e) && swap.metadata != null)
+                                swap.metadata.postQuoteError = e;
+                            await this.removeSwapData(swap, SpvVaultSwap_1.SpvVaultSwapState.FAILED);
+                            throw e; //This will get caught locally and throw the post quote error
+                        }
+                        else {
+                            //Transaction not-null set state to sent and fall through without throwing
+                            await swap.setState(SpvVaultSwap_1.SpvVaultSwapState.SENT);
+                        }
+                    }
+                    catch (getTxErr) {
+                        if (getTxErr === e)
+                            throw e;
+                        //Cannot determine whether the bitcoin transaction was broadcasted or not
+                        // do nothing here and let the watchdog handle this!
+                        throw {
+                            _httpStatus: 200,
+                            code: 20001,
+                            msg: "Transaction status unknown",
+                            data: {
+                                txId: swap.btcTxId
+                            }
+                        };
+                    }
+                }
+                else {
+                    throw e;
+                }
+            }
+            finally {
+                unlock();
             }
             await responseStream.writeParamsAndEnd({
                 code: 20000,

package/dist/swaps/trusted/frombtc_trusted/FromBtcTrusted.js

@@ -246,7 +246,7 @@ class FromBtcTrusted extends SwapHandler_1.SwapHandler {
             if (swap.state !== FromBtcTrustedSwap_1.FromBtcTrustedSwapState.BTC_CONFIRMED)
                 return;
             const txns = await chainInterface.txsTransfer(signer.getAddress(), swap.token, swap.adjustedOutput, swap.dstAddress);
-            let unlock = swap.lock(30 * 1000);
+            let unlock = swap.lock(30);
             if (unlock == null)
                 return;
             const pluginCheckResult = await PluginManager_1.PluginManager.onHandlePreFromBtcExecute(SwapHandler_1.SwapHandlerType.FROM_BTC_TRUSTED, swap);
@@ -341,7 +341,7 @@ class FromBtcTrusted extends SwapHandler_1.SwapHandler {
                 await this.processPastSwap(swap, txs[0]?.tx, txs[0]?.vout);
             }
             catch (e) {
-                this.swapLogger.error(swap, "processPastSwaps(): Error ocurred while processing swap: ", e);
+                this.swapLogger.error(swap, "processPastSwap(): Error executing watchdog function: ", e);
             }
         }
     }

package/dist/swaps/trusted/frombtcln_trusted/FromBtcLnTrusted.js

@@ -130,8 +130,13 @@ class FromBtcLnTrusted extends SwapHandler_1.SwapHandler {
             }
         ]);
         for (let { obj: swap } of queriedData) {
-            if (await this.processPastSwap(swap))
-                cancelInvoices.push(swap);
+            try {
+                if (await this.processPastSwap(swap))
+                    cancelInvoices.push(swap);
+            }
+            catch (e) {
+                this.swapLogger.error(swap, "processPastSwap(): Error executing watchdog function: ", e);
+            }
         }
         await this.cancelInvoices(cancelInvoices);
     }
@@ -206,13 +211,9 @@ class FromBtcLnTrusted extends SwapHandler_1.SwapHandler {
                 }
             }).catch(e => this.swapLogger.error(invoiceData, "htlcReceived(): Error sending transfer txns", e));
             if (result == null) {
-                //Cancel invoice
-                await invoiceData.setState(FromBtcLnTrustedSwap_1.FromBtcLnTrustedSwapState.REFUNDED);
-                await this.storageManager.saveData(invoice.id, null, invoiceData);
-                await this.lightning.cancelHodlInvoice(invoice.id);
-                this.unsubscribeInvoice(invoice.id);
-                await this.removeSwapData(invoiceData);
-                this.swapLogger.info(invoiceData, "htlcReceived(): transaction sending failed, refunding lightning: ", invoiceData.pr);
+                this.swapLogger.info(invoiceData, "htlcReceived(): transaction sending failed: ", invoiceData.pr);
+                //Let the swap watchdog handle this case
+                unlock();
                 throw {
                     code: 20002,
                     msg: "Transaction sending failed"
@@ -230,14 +231,7 @@ class FromBtcLnTrusted extends SwapHandler_1.SwapHandler {
             if (invoiceData.isLocked())
                 return;
             const txStatus = await chainInterface.getTxStatus(invoiceData.scRawTx);
-            if (txStatus === "not_found") {
-                //Retry
-                invoiceData.txIds = { init: null };
-                invoiceData.scRawTx = null;
-                await invoiceData.setState(FromBtcLnTrustedSwap_1.FromBtcLnTrustedSwapState.RECEIVED);
-                await this.storageManager.saveData(invoice.id, null, invoiceData);
-            }
-            if (txStatus === "reverted") {
+            if (txStatus === "reverted" || txStatus === "not_found") {
                 //Cancel invoice
                 await invoiceData.setState(FromBtcLnTrustedSwap_1.FromBtcLnTrustedSwapState.REFUNDED);
                 await this.storageManager.saveData(invoice.id, null, invoiceData);

package/dist/utils/Utils.d.ts

@@ -30,3 +30,36 @@ export declare function bigIntSorter(a: bigint, b: bigint): -1 | 0 | 1;
  */
 export declare function getAbortController(responseStream: ServerParamEncoder): AbortController;
 export declare function parsePsbt(btcTx: Transaction): BtcTx;
+/**
+ * Returns the minimum Bitcoin block window (in blocks) for which a "fast blocks" safety
+ * factor is genuinely usable: the probability that N consecutive blocks are produced
+ * with an average interval below (blocktime / safetyFactor) is less than `probability`.
+ *
+ * Model: block arrivals are a Poisson process (i.i.d. exponential intervals), so the
+ * production time of N blocks is Erlang/Gamma(shape=N). A Chernoff (Cramer) bound on
+ * the lower tail gives the per-block large-deviation rate I(S) = ln(S) + 1/S - 1, i.e.
+ *     P(N blocks faster than blocktime/S on average) <= exp(-N * I(S))
+ * which this function inverts for N. Conservative: the exact Erlang CDF already
+ * satisfies the bound ~25% earlier. Use for the fast-block tail (e.g. incoming LN
+ * HTLC expiry racing an escrow claim window).
+ *
+ * @param {number|bigint} safetyFactor Assumed max block-speed multiplier (must be > 1)
+ * @param {number} [probability=0.0001] Tolerated failure probability (default 0.01%)
+ * @returns {number} Minimum safe block window in blocks
+ */
+export declare function getMinSafeBlockWindowFast(safetyFactor: number | bigint, probability?: number): bigint;
+/**
+ * Slow-tail mirror of getMinSafeBlockWindowFast(): returns the minimum block window
+ * (in blocks) for which a "slow blocks" safety factor is genuinely usable: the
+ * probability that N consecutive blocks take LONGER than N * blocktime * safetyFactor
+ * is less than `probability`. Chernoff bound on the upper Erlang tail gives the rate
+ * I(S) = S - 1 - ln(S). Use when converting a wall-clock deadline into a block count
+ * (e.g. payout/claim timeouts that must expire before some real-world time even if
+ * blocks come slowly).
+ *
+ * @param {number|bigint} safetyFactor Assumed max block-slowness multiplier (must be > 1)
+ * @param {number} [probability=0.0001] Tolerated failure probability (default 0.01%)
+ * @returns {number} Minimum safe block window in blocks
+ */
+export declare function getMinSafeBlockWindowSlow(safetyFactor: bigint | number, probability?: number): bigint;
+export declare function bigIntMax(a: bigint, b: bigint): bigint;

package/dist/utils/Utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parsePsbt = exports.getAbortController = exports.bigIntSorter = exports.deserializeBN = exports.serializeBN = exports.HEX_REGEX = exports.expressHandlerWrapper = exports.isDefinedRuntimeError = exports.getLogger = void 0;
+exports.bigIntMax = exports.getMinSafeBlockWindowSlow = exports.getMinSafeBlockWindowFast = exports.parsePsbt = exports.getAbortController = exports.bigIntSorter = exports.deserializeBN = exports.serializeBN = exports.HEX_REGEX = exports.expressHandlerWrapper = exports.isDefinedRuntimeError = exports.getLogger = void 0;
 const crypto_1 = require("crypto");
 const btc_signer_1 = require("@scure/btc-signer");
 function getLogger(prefix) {
@@ -128,3 +128,53 @@ function parsePsbt(btcTx) {
     };
 }
 exports.parsePsbt = parsePsbt;
+/**
+ * Returns the minimum Bitcoin block window (in blocks) for which a "fast blocks" safety
+ * factor is genuinely usable: the probability that N consecutive blocks are produced
+ * with an average interval below (blocktime / safetyFactor) is less than `probability`.
+ *
+ * Model: block arrivals are a Poisson process (i.i.d. exponential intervals), so the
+ * production time of N blocks is Erlang/Gamma(shape=N). A Chernoff (Cramer) bound on
+ * the lower tail gives the per-block large-deviation rate I(S) = ln(S) + 1/S - 1, i.e.
+ *     P(N blocks faster than blocktime/S on average) <= exp(-N * I(S))
+ * which this function inverts for N. Conservative: the exact Erlang CDF already
+ * satisfies the bound ~25% earlier. Use for the fast-block tail (e.g. incoming LN
+ * HTLC expiry racing an escrow claim window).
+ *
+ * @param {number|bigint} safetyFactor Assumed max block-speed multiplier (must be > 1)
+ * @param {number} [probability=0.0001] Tolerated failure probability (default 0.01%)
+ * @returns {number} Minimum safe block window in blocks
+ */
+function getMinSafeBlockWindowFast(safetyFactor, probability = 0.0001) {
+    const S = Number(safetyFactor);
+    const rate = Math.log(S) + 1 / S - 1;
+    if (!(rate > 0))
+        throw new RangeError("safetyFactor must be > 1");
+    return BigInt(Math.ceil(Math.log(1 / probability) / rate));
+}
+exports.getMinSafeBlockWindowFast = getMinSafeBlockWindowFast;
+/**
+ * Slow-tail mirror of getMinSafeBlockWindowFast(): returns the minimum block window
+ * (in blocks) for which a "slow blocks" safety factor is genuinely usable: the
+ * probability that N consecutive blocks take LONGER than N * blocktime * safetyFactor
+ * is less than `probability`. Chernoff bound on the upper Erlang tail gives the rate
+ * I(S) = S - 1 - ln(S). Use when converting a wall-clock deadline into a block count
+ * (e.g. payout/claim timeouts that must expire before some real-world time even if
+ * blocks come slowly).
+ *
+ * @param {number|bigint} safetyFactor Assumed max block-slowness multiplier (must be > 1)
+ * @param {number} [probability=0.0001] Tolerated failure probability (default 0.01%)
+ * @returns {number} Minimum safe block window in blocks
+ */
+function getMinSafeBlockWindowSlow(safetyFactor, probability = 0.0001) {
+    const S = Number(safetyFactor);
+    const rate = S - 1 - Math.log(S);
+    if (!(rate > 0))
+        throw new RangeError("safetyFactor must be > 1");
+    return BigInt(Math.ceil(Math.log(1 / probability) / rate));
+}
+exports.getMinSafeBlockWindowSlow = getMinSafeBlockWindowSlow;
+function bigIntMax(a, b) {
+    return a > b ? a : b;
+}
+exports.bigIntMax = bigIntMax;

package/dist/utils/paramcoders/ParamDecoder.js

@@ -118,51 +118,8 @@ class ParamDecoder {
         const resultSchema = {};
         for (let fieldName in schema) {
             const val = await this.getParam(fieldName);
-            const type = schema[fieldName];
-            if (typeof (type) === "function") {
-                const result = type(val);
-                if (result == null)
-                    return null;
-                resultSchema[fieldName] = result;
-                continue;
-            }
-            if (val == null && type >= 100) {
-                resultSchema[fieldName] = null;
-                continue;
-            }
-            if (type === SchemaVerifier_1.FieldTypeEnum.Any || type === SchemaVerifier_1.FieldTypeEnum.AnyOptional) {
-                resultSchema[fieldName] = val;
-            }
-            else if (type === SchemaVerifier_1.FieldTypeEnum.Boolean || type === SchemaVerifier_1.FieldTypeEnum.BooleanOptional) {
-                if (typeof (val) !== "boolean")
-                    return null;
-                resultSchema[fieldName] = val;
-            }
-            else if (type === SchemaVerifier_1.FieldTypeEnum.Number || type === SchemaVerifier_1.FieldTypeEnum.NumberOptional) {
-                if (typeof (val) !== "number")
-                    return null;
-                if (isNaN(val))
-                    return null;
-                resultSchema[fieldName] = val;
-            }
-            else if (type === SchemaVerifier_1.FieldTypeEnum.BigInt || type === SchemaVerifier_1.FieldTypeEnum.BigIntOptional) {
-                const result = (0, SchemaVerifier_1.parseBigInt)(val);
-                if (result == null)
-                    return null;
-                resultSchema[fieldName] = result;
-            }
-            else if (type === SchemaVerifier_1.FieldTypeEnum.String || type === SchemaVerifier_1.FieldTypeEnum.StringOptional) {
-                if (typeof (val) !== "string")
-                    return null;
-                resultSchema[fieldName] = val;
-            }
-            else {
-                //Probably another request schema
-                const result = (0, SchemaVerifier_1.verifySchema)(val, type);
-                if (result == null)
-                    return null;
-                resultSchema[fieldName] = result;
-            }
+            if (!(0, SchemaVerifier_1.verifySchemaField)(val, schema[fieldName], fieldName, resultSchema))
+                return null;
         }
         return resultSchema;
     }
@@ -174,47 +131,8 @@ class ParamDecoder {
                 resultSchema[fieldName] = null;
                 continue;
             }
-            const type = schema[fieldName];
-            if (typeof (type) === "function") {
-                const result = type(val);
-                if (result == null)
-                    return null;
-                resultSchema[fieldName] = result;
-                continue;
-            }
-            if (type === SchemaVerifier_1.FieldTypeEnum.Any || type === SchemaVerifier_1.FieldTypeEnum.AnyOptional) {
-                resultSchema[fieldName] = val;
-            }
-            else if (type === SchemaVerifier_1.FieldTypeEnum.Boolean || type === SchemaVerifier_1.FieldTypeEnum.BooleanOptional) {
-                if (typeof (val) !== "boolean")
-                    return null;
-                resultSchema[fieldName] = val;
-            }
-            else if (type === SchemaVerifier_1.FieldTypeEnum.Number || type === SchemaVerifier_1.FieldTypeEnum.NumberOptional) {
-                if (typeof (val) !== "number")
-                    return null;
-                if (isNaN(val))
-                    return null;
-                resultSchema[fieldName] = val;
-            }
-            else if (type === SchemaVerifier_1.FieldTypeEnum.BigInt || type === SchemaVerifier_1.FieldTypeEnum.BigIntOptional) {
-                const result = (0, SchemaVerifier_1.parseBigInt)(val);
-                if (result == null)
-                    return null;
-                resultSchema[fieldName] = result;
-            }
-            else if (type === SchemaVerifier_1.FieldTypeEnum.String || type === SchemaVerifier_1.FieldTypeEnum.StringOptional) {
-                if (typeof (val) !== "string")
-                    return null;
-                resultSchema[fieldName] = val;
-            }
-            else {
-                //Probably another request schema
-                const result = (0, SchemaVerifier_1.verifySchema)(val, type);
-                if (result == null)
-                    return null;
-                resultSchema[fieldName] = result;
-            }
+            if (!(0, SchemaVerifier_1.verifySchemaField)(val, schema[fieldName], fieldName, resultSchema))
+                return null;
         }
         return resultSchema;
     }

package/dist/utils/paramcoders/SchemaVerifier.d.ts

@@ -5,17 +5,26 @@ export declare enum FieldTypeEnum {
     Number = 2,
     BigInt = 3,
     Any = 4,
+    BigIntPositive = 5,
+    BigIntNotNegative = 6,
+    NumberPositive = 7,
+    NumberNotNegative = 8,
     StringOptional = 100,
     BooleanOptional = 101,
     NumberOptional = 102,
     BigIntOptional = 103,
-    AnyOptional = 104
+    AnyOptional = 104,
+    BigIntPositiveOptional = 105,
+    BigIntNotNegativeOptional = 106,
+    NumberPositiveOptional = 107,
+    NumberNotNegativeOptional = 108
 }
-export type FieldType<T extends FieldTypeEnum | RequestSchema | ((val: any) => (string | boolean | number | bigint | any))> = T extends FieldTypeEnum.String ? string : T extends FieldTypeEnum.Boolean ? boolean : T extends FieldTypeEnum.Number ? number : T extends FieldTypeEnum.BigInt ? bigint : T extends FieldTypeEnum.Any ? any : T extends FieldTypeEnum.StringOptional ? string : T extends FieldTypeEnum.BooleanOptional ? boolean : T extends FieldTypeEnum.NumberOptional ? number : T extends FieldTypeEnum.BigIntOptional ? bigint : T extends FieldTypeEnum.AnyOptional ? any : T extends RequestSchema ? RequestSchemaResult<T> : T extends ((val: any) => string) ? string : T extends ((val: any) => boolean) ? boolean : T extends ((val: any) => number) ? number : T extends ((val: any) => bigint) ? bigint : T extends ((val: any) => any) ? any : never;
+export type FieldType<T extends FieldTypeEnum | RequestSchema | ((val: any) => (string | boolean | number | bigint | any))> = T extends FieldTypeEnum.String ? string : T extends FieldTypeEnum.Boolean ? boolean : T extends FieldTypeEnum.Number ? number : T extends FieldTypeEnum.NumberPositive ? number : T extends FieldTypeEnum.NumberNotNegative ? number : T extends FieldTypeEnum.BigInt ? bigint : T extends FieldTypeEnum.Any ? any : T extends FieldTypeEnum.BigIntPositive ? bigint : T extends FieldTypeEnum.BigIntNotNegative ? bigint : T extends FieldTypeEnum.StringOptional ? string : T extends FieldTypeEnum.BooleanOptional ? boolean : T extends FieldTypeEnum.NumberOptional ? number : T extends FieldTypeEnum.NumberPositiveOptional ? number : T extends FieldTypeEnum.NumberNotNegativeOptional ? number : T extends FieldTypeEnum.BigIntOptional ? bigint : T extends FieldTypeEnum.AnyOptional ? any : T extends FieldTypeEnum.BigIntPositiveOptional ? bigint : T extends FieldTypeEnum.BigIntNotNegativeOptional ? bigint : T extends RequestSchema ? RequestSchemaResult<T> : T extends ((val: any) => string) ? string : T extends ((val: any) => boolean) ? boolean : T extends ((val: any) => number) ? number : T extends ((val: any) => bigint) ? bigint : T extends ((val: any) => any) ? any : never;
 export type RequestSchemaResult<T extends RequestSchema> = {
     [key in keyof T]: FieldType<T[key]>;
 };
 export type RequestSchema = {
     [fieldName: string]: FieldTypeEnum | RequestSchema | ((val: any) => any);
 };
+export declare function verifySchemaField(val: any, type: FieldTypeEnum | RequestSchema | ((val: any) => any), fieldName: string, resultSchema: any): boolean;
 export declare function verifySchema<T extends RequestSchema>(req: any, schema: T): RequestSchemaResult<T>;