@atomiqlabs/lp-lib 17.5.2 → 17.6.0

package/src/utils/Utils.ts

@@ -1,152 +1,200 @@
-import {Request, Response} from "express";
-import {ServerParamEncoder} from "./paramcoders/server/ServerParamEncoder";
-import {createHash} from "crypto";
-import {Script, Transaction} from "@scure/btc-signer";
-import {BtcTx} from "@atomiqlabs/base";
-
-export type LoggerType = {
-    debug: (msg: string, ...args: any[]) => void,
-    info: (msg: string, ...args: any[]) => void,
-    warn: (msg: string, ...args: any[]) => void,
-    error: (msg: string, ...args: any[]) => void
-};
-
-export function getLogger(prefix: string | (() => string)): LoggerType {
-    return {
-        debug: (msg, ...args) => global.atomiqLogLevel >= 3 && console.debug((typeof(prefix)==="function" ? prefix() : prefix)+msg, ...args),
-        info: (msg, ...args) => global.atomiqLogLevel >= 2 && console.info((typeof(prefix)==="function" ? prefix() : prefix)+msg, ...args),
-        warn: (msg, ...args) => (global.atomiqLogLevel==null || global.atomiqLogLevel >= 1) && console.warn((typeof(prefix)==="function" ? prefix() : prefix)+msg, ...args),
-        error: (msg, ...args) => (global.atomiqLogLevel==null || global.atomiqLogLevel >= 0) && console.error((typeof(prefix)==="function" ? prefix() : prefix)+msg, ...args)
-    };
-}
-
-export type DefinedRuntimeError = {
-    code: number;
-    msg?: string;
-    _httpStatus?: number;
-    data?: any;
-};
-
-export function isDefinedRuntimeError(obj: any): obj is DefinedRuntimeError {
-    if(obj.code!=null && typeof(obj.code)==="number") {
-        if(obj.msg!=null && typeof(obj.msg)!=="string") return false;
-        if(obj._httpStatus!=null && typeof(obj._httpStatus)!=="number") return false;
-        return true;
-    }
-    return false;
-}
-
-const expressHandlerWrapperLogger = getLogger("ExpressHandlerWrapper: ");
-
-export function expressHandlerWrapper(func: (
-    req: Request,
-    res: Response
-) => Promise<void>) : ((
-    req: Request,
-    res: Response & {responseStream: ServerParamEncoder}
-) => void) {
-    return (
-        req: Request,
-        res: Response & {responseStream: ServerParamEncoder}
-    ) => {
-        (async () => {
-            try {
-                await func(req, res);
-            } catch (e) {
-                if(!isDefinedRuntimeError(e) || e._httpStatus!==200)
-                    expressHandlerWrapperLogger.error("Error in called function "+req.path+": ", e);
-
-                let statusCode = 500;
-                const obj: {code: number, msg: string, data?: any} = {
-                    code: 0,
-                    msg: "Internal server error"
-                };
-                if(isDefinedRuntimeError(e)) {
-                    obj.msg = e.msg;
-                    obj.code = e.code;
-                    obj.data = e.data;
-                    statusCode = 400;
-                    if(e._httpStatus!=null) statusCode = e._httpStatus;
-                }
-                if(res.responseStream!=null) {
-                    if(res.responseStream.getAbortSignal().aborted) return;
-                    res.responseStream.writeParamsAndEnd(obj).catch(e => null);
-                } else {
-                    res.status(statusCode).json(obj);
-                }
-            }
-        })();
-    }
-}
-
-export const HEX_REGEX = /[0-9a-fA-F]+/;
-
-export function serializeBN(bn: bigint | null): string | null {
-    return bn==null ? null : bn.toString(10);
-}
-
-export function deserializeBN(str: string | null): bigint | null {
-    return str==null ? null : BigInt(str);
-}
-
-export function bigIntSorter(a: bigint, b: bigint): -1 | 0 | 1 {
-    if(a < b) return -1;
-    if(a > b) return 1;
-    return 0;
-}
-
-/**
- * Creates an abort controller that extends the responseStream's abort signal
- *
- * @param responseStream
- */
-export function getAbortController(responseStream: ServerParamEncoder): AbortController {
-    const abortController = new AbortController();
-    if(responseStream==null || responseStream.getAbortSignal==null) return abortController;
-    const responseStreamAbortController = responseStream.getAbortSignal();
-    responseStreamAbortController.addEventListener("abort", () => abortController.abort(responseStreamAbortController.reason));
-    return abortController;
-}
-
-export function parsePsbt(btcTx: Transaction): BtcTx {
-    const txWithoutWitness = btcTx.toBytes(true, false);
-    return {
-        locktime: btcTx.lockTime,
-        version: btcTx.version,
-        blockhash: null,
-        confirmations: 0,
-        txid: createHash("sha256").update(
-            createHash("sha256").update(
-                txWithoutWitness
-            ).digest()
-        ).digest().reverse().toString("hex"),
-        hex: Buffer.from(txWithoutWitness).toString("hex"),
-        raw: Buffer.from(btcTx.toBytes(true, true)).toString("hex"),
-        vsize: btcTx.isFinal ? btcTx.vsize : null,
-
-        outs: Array.from({length: btcTx.outputsLength}, (_, i) => i).map((index) => {
-            const output = btcTx.getOutput(index);
-            return {
-                value: Number(output.amount),
-                n: index,
-                scriptPubKey: {
-                    asm: Script.decode(output.script).map(val => typeof(val)==="object" ? Buffer.from(val).toString("hex") : val.toString()).join(" "),
-                    hex: Buffer.from(output.script).toString("hex")
-                }
-            }
-        }),
-        ins: Array.from({length: btcTx.inputsLength}, (_, i) => i).map(index => {
-            const input = btcTx.getInput(index);
-            return {
-                txid: Buffer.from(input.txid).toString("hex"),
-                vout: input.index,
-                scriptSig: {
-                    asm: Script.decode(input.finalScriptSig).map(val => typeof(val)==="object" ? Buffer.from(val).toString("hex") : val.toString()).join(" "),
-                    hex: Buffer.from(input.finalScriptSig).toString("hex")
-                },
-                sequence: input.sequence,
-                txinwitness: input.finalScriptWitness==null ? [] : input.finalScriptWitness.map(witness => Buffer.from(witness).toString("hex"))
-            }
-        })
-    };
-}
+import {Request, Response} from "express";
+import {ServerParamEncoder} from "./paramcoders/server/ServerParamEncoder";
+import {createHash} from "crypto";
+import {Script, Transaction} from "@scure/btc-signer";
+import {BtcTx} from "@atomiqlabs/base";
+
+export type LoggerType = {
+    debug: (msg: string, ...args: any[]) => void,
+    info: (msg: string, ...args: any[]) => void,
+    warn: (msg: string, ...args: any[]) => void,
+    error: (msg: string, ...args: any[]) => void
+};
+
+export function getLogger(prefix: string | (() => string)): LoggerType {
+    return {
+        debug: (msg, ...args) => global.atomiqLogLevel >= 3 && console.debug((typeof(prefix)==="function" ? prefix() : prefix)+msg, ...args),
+        info: (msg, ...args) => global.atomiqLogLevel >= 2 && console.info((typeof(prefix)==="function" ? prefix() : prefix)+msg, ...args),
+        warn: (msg, ...args) => (global.atomiqLogLevel==null || global.atomiqLogLevel >= 1) && console.warn((typeof(prefix)==="function" ? prefix() : prefix)+msg, ...args),
+        error: (msg, ...args) => (global.atomiqLogLevel==null || global.atomiqLogLevel >= 0) && console.error((typeof(prefix)==="function" ? prefix() : prefix)+msg, ...args)
+    };
+}
+
+export type DefinedRuntimeError = {
+    code: number;
+    msg?: string;
+    _httpStatus?: number;
+    data?: any;
+};
+
+export function isDefinedRuntimeError(obj: any): obj is DefinedRuntimeError {
+    if(obj.code!=null && typeof(obj.code)==="number") {
+        if(obj.msg!=null && typeof(obj.msg)!=="string") return false;
+        if(obj._httpStatus!=null && typeof(obj._httpStatus)!=="number") return false;
+        return true;
+    }
+    return false;
+}
+
+const expressHandlerWrapperLogger = getLogger("ExpressHandlerWrapper: ");
+
+export function expressHandlerWrapper(func: (
+    req: Request,
+    res: Response
+) => Promise<void>) : ((
+    req: Request,
+    res: Response & {responseStream: ServerParamEncoder}
+) => void) {
+    return (
+        req: Request,
+        res: Response & {responseStream: ServerParamEncoder}
+    ) => {
+        (async () => {
+            try {
+                await func(req, res);
+            } catch (e) {
+                if(!isDefinedRuntimeError(e) || e._httpStatus!==200)
+                    expressHandlerWrapperLogger.error("Error in called function "+req.path+": ", e);
+
+                let statusCode = 500;
+                const obj: {code: number, msg: string, data?: any} = {
+                    code: 0,
+                    msg: "Internal server error"
+                };
+                if(isDefinedRuntimeError(e)) {
+                    obj.msg = e.msg;
+                    obj.code = e.code;
+                    obj.data = e.data;
+                    statusCode = 400;
+                    if(e._httpStatus!=null) statusCode = e._httpStatus;
+                }
+                if(res.responseStream!=null) {
+                    if(res.responseStream.getAbortSignal().aborted) return;
+                    res.responseStream.writeParamsAndEnd(obj).catch(e => null);
+                } else {
+                    res.status(statusCode).json(obj);
+                }
+            }
+        })();
+    }
+}
+
+export const HEX_REGEX = /[0-9a-fA-F]+/;
+
+export function serializeBN(bn: bigint | null): string | null {
+    return bn==null ? null : bn.toString(10);
+}
+
+export function deserializeBN(str: string | null): bigint | null {
+    return str==null ? null : BigInt(str);
+}
+
+export function bigIntSorter(a: bigint, b: bigint): -1 | 0 | 1 {
+    if(a < b) return -1;
+    if(a > b) return 1;
+    return 0;
+}
+
+/**
+ * Creates an abort controller that extends the responseStream's abort signal
+ *
+ * @param responseStream
+ */
+export function getAbortController(responseStream: ServerParamEncoder): AbortController {
+    const abortController = new AbortController();
+    if(responseStream==null || responseStream.getAbortSignal==null) return abortController;
+    const responseStreamAbortController = responseStream.getAbortSignal();
+    responseStreamAbortController.addEventListener("abort", () => abortController.abort(responseStreamAbortController.reason));
+    return abortController;
+}
+
+export function parsePsbt(btcTx: Transaction): BtcTx {
+    const txWithoutWitness = btcTx.toBytes(true, false);
+    return {
+        locktime: btcTx.lockTime,
+        version: btcTx.version,
+        blockhash: null,
+        confirmations: 0,
+        txid: createHash("sha256").update(
+            createHash("sha256").update(
+                txWithoutWitness
+            ).digest()
+        ).digest().reverse().toString("hex"),
+        hex: Buffer.from(txWithoutWitness).toString("hex"),
+        raw: Buffer.from(btcTx.toBytes(true, true)).toString("hex"),
+        vsize: btcTx.isFinal ? btcTx.vsize : null,
+
+        outs: Array.from({length: btcTx.outputsLength}, (_, i) => i).map((index) => {
+            const output = btcTx.getOutput(index);
+            return {
+                value: Number(output.amount),
+                n: index,
+                scriptPubKey: {
+                    asm: Script.decode(output.script).map(val => typeof(val)==="object" ? Buffer.from(val).toString("hex") : val.toString()).join(" "),
+                    hex: Buffer.from(output.script).toString("hex")
+                }
+            }
+        }),
+        ins: Array.from({length: btcTx.inputsLength}, (_, i) => i).map(index => {
+            const input = btcTx.getInput(index);
+            return {
+                txid: Buffer.from(input.txid).toString("hex"),
+                vout: input.index,
+                scriptSig: {
+                    asm: Script.decode(input.finalScriptSig).map(val => typeof(val)==="object" ? Buffer.from(val).toString("hex") : val.toString()).join(" "),
+                    hex: Buffer.from(input.finalScriptSig).toString("hex")
+                },
+                sequence: input.sequence,
+                txinwitness: input.finalScriptWitness==null ? [] : input.finalScriptWitness.map(witness => Buffer.from(witness).toString("hex"))
+            }
+        })
+    };
+}
+
+/**
+ * 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 function getMinSafeBlockWindowFast(safetyFactor: number | bigint, probability: number = 0.0001): bigint {
+    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));
+}
+
+/**
+ * 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 function getMinSafeBlockWindowSlow(safetyFactor: bigint | number, probability: number = 0.0001): bigint {
+    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));
+}
+
+export function bigIntMax(a: bigint, b: bigint): bigint {
+    return a > b ? a : b;
+}

package/src/utils/paramcoders/IParamReader.ts

@@ -1,8 +1,8 @@
-import {RequestSchema, RequestSchemaResult} from "./SchemaVerifier";
-
-export interface IParamReader {
-
-    getParams<T extends RequestSchema>(schema: T): Promise<RequestSchemaResult<T>>;
-    getExistingParamsOrNull<T extends RequestSchema>(schema: T): RequestSchemaResult<T>;
-
+import {RequestSchema, RequestSchemaResult} from "./SchemaVerifier";
+
+export interface IParamReader {
+
+    getParams<T extends RequestSchema>(schema: T): Promise<RequestSchemaResult<T>>;
+    getExistingParamsOrNull<T extends RequestSchema>(schema: T): RequestSchemaResult<T>;
+
 }

package/src/utils/paramcoders/IParamWriter.ts

@@ -1,8 +1,8 @@
-
-export interface IParamWriter {
-
-    end(): Promise<void>;
-    writeParams(data: any): Promise<void>;
-
-}
-
+
+export interface IParamWriter {
+
+    end(): Promise<void>;
+    writeParams(data: any): Promise<void>;
+
+}
+

package/src/utils/paramcoders/LegacyParamEncoder.ts

@@ -1,28 +1,28 @@
-import {IParamWriter} from "./IParamWriter";
-
-
-export class LegacyParamEncoder implements IParamWriter {
-
-    private readonly writeFN: (data: Buffer) => Promise<void>;
-    private readonly endFN: () => Promise<void>;
-
-    private obj = {};
-
-    constructor(write: (data: Buffer) => Promise<void>, end: () => Promise<void>) {
-        this.writeFN = write;
-        this.endFN = end;
-    }
-
-    writeParams(data: any): Promise<void> {
-        for(let key in data) {
-            if(this.obj[key]==null) this.obj[key] = data[key];
-        }
-        return Promise.resolve();
-    }
-
-    async end(): Promise<void> {
-        await this.writeFN(Buffer.from(JSON.stringify(this.obj)));
-        await this.endFN();
-    }
-
+import {IParamWriter} from "./IParamWriter";
+
+
+export class LegacyParamEncoder implements IParamWriter {
+
+    private readonly writeFN: (data: Buffer) => Promise<void>;
+    private readonly endFN: () => Promise<void>;
+
+    private obj = {};
+
+    constructor(write: (data: Buffer) => Promise<void>, end: () => Promise<void>) {
+        this.writeFN = write;
+        this.endFN = end;
+    }
+
+    writeParams(data: any): Promise<void> {
+        for(let key in data) {
+            if(this.obj[key]==null) this.obj[key] = data[key];
+        }
+        return Promise.resolve();
+    }
+
+    async end(): Promise<void> {
+        await this.writeFN(Buffer.from(JSON.stringify(this.obj)));
+        await this.endFN();
+    }
+
 }