@arkade-os/sdk 0.3.13 → 0.4.0-next.1

package/dist/cjs/contracts/handlers/delegate.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DelegateContractHandler = void 0;
+const base_1 = require("@scure/base");
+const delegate_1 = require("../../script/delegate");
+const default_1 = require("../../script/default");
+const helpers_1 = require("./helpers");
+/**
+ * Handler for delegate wallet VTXOs.
+ *
+ * Delegate contracts extend the default tapscript with an additional delegate path:
+ * - forfeit: (Alice + Server) multisig for collaborative spending
+ * - exit: (Alice) + CSV timelock for unilateral exit
+ * - delegate: (Alice + Delegate + Server) multisig for delegated renewal
+ */
+exports.DelegateContractHandler = {
+    type: "delegate",
+    createScript(params) {
+        const typed = this.deserializeParams(params);
+        return new delegate_1.DelegateVtxo.Script(typed);
+    },
+    serializeParams(params) {
+        return {
+            pubKey: base_1.hex.encode(params.pubKey),
+            serverPubKey: base_1.hex.encode(params.serverPubKey),
+            delegatePubKey: base_1.hex.encode(params.delegatePubKey),
+            csvTimelock: (0, helpers_1.timelockToSequence)(params.csvTimelock).toString(),
+        };
+    },
+    deserializeParams(params) {
+        const csvTimelock = params.csvTimelock
+            ? (0, helpers_1.sequenceToTimelock)(Number(params.csvTimelock))
+            : default_1.DefaultVtxo.Script.DEFAULT_TIMELOCK;
+        return {
+            pubKey: base_1.hex.decode(params.pubKey),
+            serverPubKey: base_1.hex.decode(params.serverPubKey),
+            delegatePubKey: base_1.hex.decode(params.delegatePubKey),
+            csvTimelock,
+        };
+    },
+    selectPath(script, contract, context) {
+        if (context.collaborative) {
+            return { leaf: script.forfeit() };
+        }
+        const sequence = contract.params.csvTimelock
+            ? Number(contract.params.csvTimelock)
+            : undefined;
+        if (!(0, helpers_1.isCsvSpendable)(context, sequence)) {
+            return null;
+        }
+        return {
+            leaf: script.exit(),
+            sequence,
+        };
+    },
+    getAllSpendingPaths(script, contract, context) {
+        const paths = [];
+        if (context.collaborative) {
+            paths.push({ leaf: script.forfeit() });
+        }
+        const exitPath = { leaf: script.exit() };
+        if (contract.params.csvTimelock) {
+            exitPath.sequence = Number(contract.params.csvTimelock);
+        }
+        paths.push(exitPath);
+        // Delegate path (Alice + Delegate + Server) — collaborative only
+        if (context.collaborative) {
+            paths.push({ leaf: script.delegate() });
+        }
+        return paths;
+    },
+    getSpendablePaths(script, contract, context) {
+        const paths = [];
+        if (context.collaborative) {
+            paths.push({ leaf: script.forfeit() });
+        }
+        const exitSequence = contract.params.csvTimelock
+            ? Number(contract.params.csvTimelock)
+            : undefined;
+        if ((0, helpers_1.isCsvSpendable)(context, exitSequence)) {
+            const exitPath = { leaf: script.exit() };
+            if (exitSequence !== undefined) {
+                exitPath.sequence = exitSequence;
+            }
+            paths.push(exitPath);
+        }
+        return paths;
+    },
+};

package/dist/cjs/contracts/handlers/helpers.js

@@ -0,0 +1,105 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timelockToSequence = timelockToSequence;
+exports.sequenceToTimelock = sequenceToTimelock;
+exports.resolveRole = resolveRole;
+exports.isCsvSpendable = isCsvSpendable;
+const bip68 = __importStar(require("bip68"));
+/**
+ * Convert RelativeTimelock to BIP68 sequence number.
+ */
+function timelockToSequence(timelock) {
+    return bip68.encode(timelock.type === "blocks"
+        ? { blocks: Number(timelock.value) }
+        : { seconds: Number(timelock.value) });
+}
+/**
+ * Convert BIP68 sequence number back to RelativeTimelock.
+ */
+function sequenceToTimelock(sequence) {
+    const decoded = bip68.decode(sequence);
+    if ("blocks" in decoded && decoded.blocks !== undefined) {
+        return { type: "blocks", value: BigInt(decoded.blocks) };
+    }
+    if ("seconds" in decoded && decoded.seconds !== undefined) {
+        return { type: "seconds", value: BigInt(decoded.seconds) };
+    }
+    throw new Error(`Invalid BIP68 sequence: ${sequence}`);
+}
+/**
+ * Resolve wallet's role from explicit role or by matching pubkey.
+ */
+function resolveRole(contract, context) {
+    // Explicit role takes precedence
+    if (context.role === "sender" || context.role === "receiver") {
+        return context.role;
+    }
+    // Try to match wallet pubkey against contract params
+    if (context.walletPubKey) {
+        if (context.walletPubKey === contract.params.sender) {
+            return "sender";
+        }
+        if (context.walletPubKey === contract.params.receiver) {
+            return "receiver";
+        }
+    }
+    return undefined;
+}
+/**
+ * Check if a CSV timelock is currently satisfied for the given context/VTXO.
+ */
+function isCsvSpendable(context, sequence) {
+    if (sequence === undefined)
+        return true;
+    if (!context.vtxo)
+        return false;
+    const timelock = sequenceToTimelock(sequence);
+    if (timelock.type === "blocks") {
+        if (context.blockHeight === undefined ||
+            context.vtxo.status.block_height === undefined) {
+            return false;
+        }
+        return (context.blockHeight - context.vtxo.status.block_height >=
+            Number(timelock.value));
+    }
+    if (timelock.type === "seconds") {
+        const blockTime = context.vtxo.status.block_time;
+        if (blockTime === undefined)
+            return false;
+        return context.currentTime / 1000 - blockTime >= Number(timelock.value);
+    }
+    return false;
+}

package/dist/cjs/contracts/handlers/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VHTLCContractHandler = exports.DelegateContractHandler = exports.DefaultContractHandler = exports.contractHandlers = void 0;
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "contractHandlers", { enumerable: true, get: function () { return registry_1.contractHandlers; } });
+var default_1 = require("./default");
+Object.defineProperty(exports, "DefaultContractHandler", { enumerable: true, get: function () { return default_1.DefaultContractHandler; } });
+var delegate_1 = require("./delegate");
+Object.defineProperty(exports, "DelegateContractHandler", { enumerable: true, get: function () { return delegate_1.DelegateContractHandler; } });
+var vhtlc_1 = require("./vhtlc");
+Object.defineProperty(exports, "VHTLCContractHandler", { enumerable: true, get: function () { return vhtlc_1.VHTLCContractHandler; } });
+// Register built-in handlers
+const registry_2 = require("./registry");
+const default_2 = require("./default");
+const delegate_2 = require("./delegate");
+const vhtlc_2 = require("./vhtlc");
+registry_2.contractHandlers.register(default_2.DefaultContractHandler);
+registry_2.contractHandlers.register(delegate_2.DelegateContractHandler);
+registry_2.contractHandlers.register(vhtlc_2.VHTLCContractHandler);

package/dist/cjs/contracts/handlers/registry.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contractHandlers = void 0;
+/**
+ * Registry for contract handlers.
+ *
+ * Each contract type ("default", "vhtlc", etc.) has a handler that knows
+ * how to create VtxoScripts, serialize params, and select spending paths.
+ *
+ * @example
+ * ```typescript
+ * // Register a custom handler
+ * contractHandlers.register(myCustomHandler);
+ *
+ * // Get handler for a type
+ * const handler = contractHandlers.get("vhtlc");
+ * const script = handler.createScript(contract.params);
+ * ```
+ */
+class ContractHandlerRegistry {
+    constructor() {
+        this.handlers = new Map();
+    }
+    /**
+     * Register a contract handler.
+     *
+     * @param handler - The handler to register
+     * @throws If a handler for this type is already registered
+     */
+    register(handler) {
+        if (this.handlers.has(handler.type)) {
+            throw new Error(`Contract handler for type '${handler.type}' is already registered`);
+        }
+        this.handlers.set(handler.type, handler);
+    }
+    /**
+     * Get a handler by type.
+     *
+     * @param type - The contract type
+     * @returns The handler, or undefined if not found
+     */
+    get(type) {
+        return this.handlers.get(type);
+    }
+    /**
+     * Get a handler by type, throwing if not found.
+     *
+     * @param type - The contract type
+     * @returns The handler
+     * @throws If no handler is registered for this type
+     */
+    getOrThrow(type) {
+        const handler = this.get(type);
+        if (!handler) {
+            throw new Error(`No contract handler registered for type '${type}'`);
+        }
+        return handler;
+    }
+    /**
+     * Check if a handler is registered.
+     *
+     * @param type - The contract type
+     */
+    has(type) {
+        return this.handlers.has(type);
+    }
+    /**
+     * Get all registered types.
+     */
+    getRegisteredTypes() {
+        return Array.from(this.handlers.keys());
+    }
+    /**
+     * Unregister a handler (mainly for testing).
+     */
+    unregister(type) {
+        return this.handlers.delete(type);
+    }
+    /**
+     * Clear all handlers (mainly for testing).
+     */
+    clear() {
+        this.handlers.clear();
+    }
+}
+/**
+ * Global registry of contract handlers.
+ */
+exports.contractHandlers = new ContractHandlerRegistry();

package/dist/cjs/contracts/handlers/vhtlc.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VHTLCContractHandler = void 0;
+const base_1 = require("@scure/base");
+const vhtlc_1 = require("../../script/vhtlc");
+const helpers_1 = require("./helpers");
+/**
+ * Handler for Virtual Hash Time Lock Contract (VHTLC).
+ *
+ * VHTLC supports multiple spending paths:
+ *
+ * Collaborative paths (with server):
+ * - claim: Receiver + Server with preimage
+ * - refund: Sender + Receiver + Server
+ * - refundWithoutReceiver: Sender + Server after CLTV locktime
+ *
+ * Unilateral paths (without server):
+ * - unilateralClaim: Receiver with preimage after CSV delay
+ * - unilateralRefund: Sender + Receiver after CSV delay
+ * - unilateralRefundWithoutReceiver: Sender after CSV delay
+ */
+exports.VHTLCContractHandler = {
+    type: "vhtlc",
+    createScript(params) {
+        const typed = this.deserializeParams(params);
+        return new vhtlc_1.VHTLC.Script(typed);
+    },
+    serializeParams(params) {
+        return {
+            sender: base_1.hex.encode(params.sender),
+            receiver: base_1.hex.encode(params.receiver),
+            server: base_1.hex.encode(params.server),
+            hash: base_1.hex.encode(params.preimageHash),
+            refundLocktime: params.refundLocktime.toString(),
+            claimDelay: (0, helpers_1.timelockToSequence)(params.unilateralClaimDelay).toString(),
+            refundDelay: (0, helpers_1.timelockToSequence)(params.unilateralRefundDelay).toString(),
+            refundNoReceiverDelay: (0, helpers_1.timelockToSequence)(params.unilateralRefundWithoutReceiverDelay).toString(),
+        };
+    },
+    deserializeParams(params) {
+        return {
+            sender: base_1.hex.decode(params.sender),
+            receiver: base_1.hex.decode(params.receiver),
+            server: base_1.hex.decode(params.server),
+            preimageHash: base_1.hex.decode(params.hash),
+            refundLocktime: BigInt(params.refundLocktime),
+            unilateralClaimDelay: (0, helpers_1.sequenceToTimelock)(Number(params.claimDelay)),
+            unilateralRefundDelay: (0, helpers_1.sequenceToTimelock)(Number(params.refundDelay)),
+            unilateralRefundWithoutReceiverDelay: (0, helpers_1.sequenceToTimelock)(Number(params.refundNoReceiverDelay)),
+        };
+    },
+    /**
+     * Select spending path based on context.
+     *
+     * Role is determined from `context.role` or by matching `context.walletPubKey`
+     * against sender/receiver in contract params.
+     */
+    selectPath(script, contract, context) {
+        const role = (0, helpers_1.resolveRole)(contract, context);
+        const preimage = contract.params?.preimage;
+        const refundLocktime = BigInt(contract.params.refundLocktime);
+        const currentTimeSec = Math.floor(context.currentTime / 1000);
+        if (!role) {
+            return null;
+        }
+        if (context.collaborative) {
+            if (role === "receiver" && preimage) {
+                return {
+                    leaf: script.claim(),
+                    extraWitness: [base_1.hex.decode(preimage)],
+                };
+            }
+            if (role === "sender" && BigInt(currentTimeSec) >= refundLocktime) {
+                return {
+                    leaf: script.refundWithoutReceiver(),
+                };
+            }
+            return null;
+        }
+        // Unilateral paths
+        if (role === "receiver" && preimage) {
+            const sequence = Number(contract.params.claimDelay);
+            if (!(0, helpers_1.isCsvSpendable)(context, sequence))
+                return null;
+            return {
+                leaf: script.unilateralClaim(),
+                extraWitness: [base_1.hex.decode(preimage)],
+                sequence,
+            };
+        }
+        if (role === "sender") {
+            const sequence = Number(contract.params.refundNoReceiverDelay);
+            if (!(0, helpers_1.isCsvSpendable)(context, sequence))
+                return null;
+            return {
+                leaf: script.unilateralRefundWithoutReceiver(),
+                sequence,
+            };
+        }
+        return null;
+    },
+    /**
+     * Get all possible spending paths (no timelock checks).
+     *
+     * Role is determined from `context.role` or by matching `context.walletPubKey`
+     * against sender/receiver in contract params.
+     */
+    getAllSpendingPaths(script, contract, context) {
+        const role = (0, helpers_1.resolveRole)(contract, context);
+        const paths = [];
+        if (!role) {
+            return paths;
+        }
+        const preimage = contract.params?.preimage;
+        if (context.collaborative) {
+            // Collaborative paths (no timelock checks)
+            if (role === "receiver" && preimage) {
+                paths.push({
+                    leaf: script.claim(),
+                    extraWitness: [base_1.hex.decode(preimage)],
+                });
+            }
+            if (role === "sender") {
+                paths.push({
+                    leaf: script.refundWithoutReceiver(),
+                });
+            }
+        }
+        else {
+            // Unilateral paths (no timelock checks)
+            if (role === "receiver" && preimage) {
+                const sequence = Number(contract.params.claimDelay);
+                paths.push({
+                    leaf: script.unilateralClaim(),
+                    extraWitness: [base_1.hex.decode(preimage)],
+                    sequence,
+                });
+            }
+            if (role === "sender") {
+                const sequence = Number(contract.params.refundNoReceiverDelay);
+                paths.push({
+                    leaf: script.unilateralRefundWithoutReceiver(),
+                    sequence,
+                });
+            }
+        }
+        return paths;
+    },
+    getSpendablePaths(script, contract, context) {
+        const role = (0, helpers_1.resolveRole)(contract, context);
+        const paths = [];
+        if (!role) {
+            return paths;
+        }
+        const preimage = contract.params?.preimage;
+        const refundLocktime = BigInt(contract.params.refundLocktime);
+        const currentTimeSec = Math.floor(context.currentTime / 1000);
+        if (context.collaborative) {
+            if (role === "receiver" && preimage) {
+                paths.push({
+                    leaf: script.claim(),
+                    extraWitness: [base_1.hex.decode(preimage)],
+                });
+            }
+            if (role === "sender" && BigInt(currentTimeSec) >= refundLocktime) {
+                paths.push({
+                    leaf: script.refundWithoutReceiver(),
+                });
+            }
+            return paths;
+        }
+        if (role === "receiver" && preimage) {
+            const sequence = Number(contract.params.claimDelay);
+            if ((0, helpers_1.isCsvSpendable)(context, sequence)) {
+                paths.push({
+                    leaf: script.unilateralClaim(),
+                    extraWitness: [base_1.hex.decode(preimage)],
+                    sequence,
+                });
+            }
+        }
+        if (role === "sender") {
+            const sequence = Number(contract.params.refundNoReceiverDelay);
+            if ((0, helpers_1.isCsvSpendable)(context, sequence)) {
+                paths.push({
+                    leaf: script.unilateralRefundWithoutReceiver(),
+                    sequence,
+                });
+            }
+        }
+        return paths;
+    },
+};

package/dist/cjs/contracts/index.js

@@ -0,0 +1,41 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContractManager = exports.ContractWatcher = exports.isArkContract = exports.contractFromArkContractWithAddress = exports.contractFromArkContract = exports.decodeArkContract = exports.encodeArkContract = exports.VHTLCContractHandler = exports.DelegateContractHandler = exports.DefaultContractHandler = exports.contractHandlers = void 0;
+// Types
+__exportStar(require("./types"), exports);
+// Contract handlers
+var handlers_1 = require("./handlers");
+Object.defineProperty(exports, "contractHandlers", { enumerable: true, get: function () { return handlers_1.contractHandlers; } });
+var handlers_2 = require("./handlers");
+Object.defineProperty(exports, "DefaultContractHandler", { enumerable: true, get: function () { return handlers_2.DefaultContractHandler; } });
+var handlers_3 = require("./handlers");
+Object.defineProperty(exports, "DelegateContractHandler", { enumerable: true, get: function () { return handlers_3.DelegateContractHandler; } });
+var handlers_4 = require("./handlers");
+Object.defineProperty(exports, "VHTLCContractHandler", { enumerable: true, get: function () { return handlers_4.VHTLCContractHandler; } });
+// arkcontract string codec
+var arkcontract_1 = require("./arkcontract");
+Object.defineProperty(exports, "encodeArkContract", { enumerable: true, get: function () { return arkcontract_1.encodeArkContract; } });
+Object.defineProperty(exports, "decodeArkContract", { enumerable: true, get: function () { return arkcontract_1.decodeArkContract; } });
+Object.defineProperty(exports, "contractFromArkContract", { enumerable: true, get: function () { return arkcontract_1.contractFromArkContract; } });
+Object.defineProperty(exports, "contractFromArkContractWithAddress", { enumerable: true, get: function () { return arkcontract_1.contractFromArkContractWithAddress; } });
+Object.defineProperty(exports, "isArkContract", { enumerable: true, get: function () { return arkcontract_1.isArkContract; } });
+// Contract watcher
+var contractWatcher_1 = require("./contractWatcher");
+Object.defineProperty(exports, "ContractWatcher", { enumerable: true, get: function () { return contractWatcher_1.ContractWatcher; } });
+// Contract manager
+var contractManager_1 = require("./contractManager");
+Object.defineProperty(exports, "ContractManager", { enumerable: true, get: function () { return contractManager_1.ContractManager; } });

package/dist/cjs/contracts/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/forfeit.js

@@ -1,27 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildForfeitTx = buildForfeitTx;
+exports.buildForfeitTxWithOutput = buildForfeitTxWithOutput;
 const transaction_1 = require("./utils/transaction");
 const anchor_1 = require("./utils/anchor");
 function buildForfeitTx(inputs, forfeitPkScript, txLocktime) {
-    const tx = new transaction_1.Transaction({
-        version: 3,
-        lockTime: txLocktime,
-    });
     let amount = 0n;
     for (const input of inputs) {
         if (!input.witnessUtxo) {
             throw new Error("input needs witness utxo");
         }
         amount += input.witnessUtxo.amount;
-        tx.addInput(input);
     }
-    // Add main output to server
-    tx.addOutput({
+    return buildForfeitTxWithOutput(inputs, {
         script: forfeitPkScript,
         amount,
+    }, txLocktime);
+}
+function buildForfeitTxWithOutput(inputs, output, txLocktime) {
+    const tx = new transaction_1.Transaction({
+        version: 3,
+        lockTime: txLocktime,
     });
-    // Add P2A output
+    for (const input of inputs) {
+        tx.addInput(input);
+    }
+    tx.addOutput(output);
     tx.addOutput(anchor_1.P2A);
     return tx;
 }

package/dist/cjs/identity/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./singleKey"), exports);
+__exportStar(require("./seedIdentity"), exports);