@arkade-os/sdk 0.3.12 → 0.4.0-next.0

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

@@ -0,0 +1,86 @@
+import { hex } from "@scure/base";
+import { DelegateVtxo } from '../../script/delegate.js';
+import { DefaultVtxo } from '../../script/default.js';
+import { isCsvSpendable, sequenceToTimelock, timelockToSequence, } from './helpers.js';
+/**
+ * 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
+ */
+export const DelegateContractHandler = {
+    type: "delegate",
+    createScript(params) {
+        const typed = this.deserializeParams(params);
+        return new DelegateVtxo.Script(typed);
+    },
+    serializeParams(params) {
+        return {
+            pubKey: hex.encode(params.pubKey),
+            serverPubKey: hex.encode(params.serverPubKey),
+            delegatePubKey: hex.encode(params.delegatePubKey),
+            csvTimelock: timelockToSequence(params.csvTimelock).toString(),
+        };
+    },
+    deserializeParams(params) {
+        const csvTimelock = params.csvTimelock
+            ? sequenceToTimelock(Number(params.csvTimelock))
+            : DefaultVtxo.Script.DEFAULT_TIMELOCK;
+        return {
+            pubKey: hex.decode(params.pubKey),
+            serverPubKey: hex.decode(params.serverPubKey),
+            delegatePubKey: 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 (!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 (isCsvSpendable(context, exitSequence)) {
+            const exitPath = { leaf: script.exit() };
+            if (exitSequence !== undefined) {
+                exitPath.sequence = exitSequence;
+            }
+            paths.push(exitPath);
+        }
+        return paths;
+    },
+};

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

@@ -0,0 +1,66 @@
+import * as bip68 from "bip68";
+/**
+ * Convert RelativeTimelock to BIP68 sequence number.
+ */
+export function timelockToSequence(timelock) {
+    return bip68.encode(timelock.type === "blocks"
+        ? { blocks: Number(timelock.value) }
+        : { seconds: Number(timelock.value) });
+}
+/**
+ * Convert BIP68 sequence number back to RelativeTimelock.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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/esm/contracts/handlers/index.js

@@ -0,0 +1,12 @@
+export { contractHandlers } from './registry.js';
+export { DefaultContractHandler } from './default.js';
+export { DelegateContractHandler } from './delegate.js';
+export { VHTLCContractHandler } from './vhtlc.js';
+// Register built-in handlers
+import { contractHandlers } from './registry.js';
+import { DefaultContractHandler } from './default.js';
+import { DelegateContractHandler } from './delegate.js';
+import { VHTLCContractHandler } from './vhtlc.js';
+contractHandlers.register(DefaultContractHandler);
+contractHandlers.register(DelegateContractHandler);
+contractHandlers.register(VHTLCContractHandler);

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

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+export const contractHandlers = new ContractHandlerRegistry();

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

@@ -0,0 +1,190 @@
+import { hex } from "@scure/base";
+import { VHTLC } from '../../script/vhtlc.js';
+import { isCsvSpendable, resolveRole, sequenceToTimelock, timelockToSequence, } from './helpers.js';
+/**
+ * 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
+ */
+export const VHTLCContractHandler = {
+    type: "vhtlc",
+    createScript(params) {
+        const typed = this.deserializeParams(params);
+        return new VHTLC.Script(typed);
+    },
+    serializeParams(params) {
+        return {
+            sender: hex.encode(params.sender),
+            receiver: hex.encode(params.receiver),
+            server: hex.encode(params.server),
+            hash: hex.encode(params.preimageHash),
+            refundLocktime: params.refundLocktime.toString(),
+            claimDelay: timelockToSequence(params.unilateralClaimDelay).toString(),
+            refundDelay: timelockToSequence(params.unilateralRefundDelay).toString(),
+            refundNoReceiverDelay: timelockToSequence(params.unilateralRefundWithoutReceiverDelay).toString(),
+        };
+    },
+    deserializeParams(params) {
+        return {
+            sender: hex.decode(params.sender),
+            receiver: hex.decode(params.receiver),
+            server: hex.decode(params.server),
+            preimageHash: hex.decode(params.hash),
+            refundLocktime: BigInt(params.refundLocktime),
+            unilateralClaimDelay: sequenceToTimelock(Number(params.claimDelay)),
+            unilateralRefundDelay: sequenceToTimelock(Number(params.refundDelay)),
+            unilateralRefundWithoutReceiverDelay: 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 = 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: [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 (!isCsvSpendable(context, sequence))
+                return null;
+            return {
+                leaf: script.unilateralClaim(),
+                extraWitness: [hex.decode(preimage)],
+                sequence,
+            };
+        }
+        if (role === "sender") {
+            const sequence = Number(contract.params.refundNoReceiverDelay);
+            if (!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 = 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: [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: [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 = 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: [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 (isCsvSpendable(context, sequence)) {
+                paths.push({
+                    leaf: script.unilateralClaim(),
+                    extraWitness: [hex.decode(preimage)],
+                    sequence,
+                });
+            }
+        }
+        if (role === "sender") {
+            const sequence = Number(contract.params.refundNoReceiverDelay);
+            if (isCsvSpendable(context, sequence)) {
+                paths.push({
+                    leaf: script.unilateralRefundWithoutReceiver(),
+                    sequence,
+                });
+            }
+        }
+        return paths;
+    },
+};

package/dist/esm/contracts/index.js

@@ -0,0 +1,13 @@
+// Types
+export * from './types.js';
+// Contract handlers
+export { contractHandlers } from './handlers/index.js';
+export { DefaultContractHandler } from './handlers/index.js';
+export { DelegateContractHandler } from './handlers/index.js';
+export { VHTLCContractHandler } from './handlers/index.js';
+// arkcontract string codec
+export { encodeArkContract, decodeArkContract, contractFromArkContract, contractFromArkContractWithAddress, isArkContract, } from './arkcontract.js';
+// Contract watcher
+export { ContractWatcher } from './contractWatcher.js';
+// Contract manager
+export { ContractManager } from './contractManager.js';

package/dist/esm/contracts/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/db/manager.js

@@ -0,0 +1,92 @@
+export function getGlobalObject() {
+    if (typeof globalThis !== "undefined") {
+        if (typeof globalThis.self === "object" && globalThis.self !== null) {
+            return { globalObject: globalThis.self };
+        }
+        if (typeof globalThis.window === "object" &&
+            globalThis.window !== null) {
+            return { globalObject: globalThis.window };
+        }
+        return { globalObject: globalThis };
+    }
+    throw new Error("Global object not found");
+}
+// database instance cache, avoiding multiple open requests
+const dbCache = new Map();
+// track reference counts for each database to avoid closing it prematurely
+const refCounts = new Map();
+/**
+ * Opens an IndexedDB database and increments the reference count.
+ * Handles global object detection and callbacks.
+ *
+ * @param dbName The name of the database to open.
+ * @param dbVersion The database version to open.
+ * @param initDatabase A function that migrates the database schema, called on `onupgradeneeded` only.
+ *
+ * @returns A promise that resolves to the database instance.
+ */
+export async function openDatabase(dbName, dbVersion, initDatabase) {
+    const { globalObject } = getGlobalObject();
+    if (!globalObject.indexedDB) {
+        throw new Error("IndexedDB is not available in this environment");
+    }
+    // Return cached promise if available (handles concurrent calls)
+    const cached = dbCache.get(dbName);
+    if (cached) {
+        if (cached.version !== dbVersion) {
+            throw new Error(`Database "${dbName}" already opened with version ${cached.version}; requested ${dbVersion}`);
+        }
+        refCounts.set(dbName, (refCounts.get(dbName) ?? 0) + 1);
+        return cached.promise;
+    }
+    const dbPromise = new Promise((resolve, reject) => {
+        const request = globalObject.indexedDB.open(dbName, dbVersion);
+        request.onerror = () => {
+            dbCache.delete(dbName); // Clean up on failure
+            refCounts.delete(dbName);
+            reject(request.error);
+        };
+        request.onsuccess = () => {
+            resolve(request.result);
+        };
+        request.onupgradeneeded = () => {
+            const db = request.result;
+            initDatabase(db);
+        };
+        request.onblocked = () => {
+            console.warn("Database upgrade blocked - close other tabs/connections");
+        };
+    });
+    // Cache immediately before awaiting
+    dbCache.set(dbName, { version: dbVersion, promise: dbPromise });
+    refCounts.set(dbName, 1);
+    return dbPromise;
+}
+/**
+ * Decrements the reference count and closes the database when no references remain.
+ *
+ * @param dbName The name of the database to close.
+ *
+ * @returns True if the database was closed, false otherwise.
+ */
+export async function closeDatabase(dbName) {
+    const cachedEntry = dbCache.get(dbName);
+    if (!cachedEntry)
+        return false;
+    const count = (refCounts.get(dbName) ?? 1) - 1;
+    if (count > 0) {
+        refCounts.set(dbName, count);
+        return false;
+    }
+    // Last reference — actually close
+    refCounts.delete(dbName);
+    dbCache.delete(dbName);
+    try {
+        const db = await cachedEntry.promise;
+        db.close();
+    }
+    catch {
+        // DB failed to open, nothing to close
+    }
+    return true;
+}

package/dist/esm/forfeit.js

@@ -1,24 +1,27 @@
 import { Transaction } from './utils/transaction.js';
 import { P2A } from './utils/anchor.js';
 export function buildForfeitTx(inputs, forfeitPkScript, txLocktime) {
-    const tx = new 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);
+}
+export function buildForfeitTxWithOutput(inputs, output, txLocktime) {
+    const tx = new Transaction({
+        version: 3,
+        lockTime: txLocktime,
     });
-    // Add P2A output
+    for (const input of inputs) {
+        tx.addInput(input);
+    }
+    tx.addOutput(output);
     tx.addOutput(P2A);
     return tx;
 }

package/dist/esm/identity/index.js

@@ -1 +1,2 @@
 export * from './singleKey.js';
+export * from './seedIdentity.js';