@arkade-os/sdk 0.4.27 → 0.4.28

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

@@ -1,87 +0,0 @@
-import { hex } from "@scure/base";
-import { DelegateVtxo } from "../../script/delegate.js";
-import { DefaultVtxo } from "../../script/default.js";
-import { isCsvSpendable } from "./helpers.js";
-import { sequenceToTimelock, timelockToSequence } from "../../utils/timelock.js";
-/**
- * Handler for delegate wallet virtual outputs.
- *
- * 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

@@ -1,110 +0,0 @@
-import { sequenceToTimelock } from "../../utils/timelock.js";
-import { isDescriptor, extractPubKey } from "../../identity/descriptor.js";
-/**
- * Extract raw hex pubkey from a value that may be a descriptor or raw hex.
- * Returns undefined for HD descriptors or unparseable values so role
- * resolution stays best-effort and never throws.
- */
-function extractRawPubKey(value) {
-    if (!isDescriptor(value)) {
-        return value.toLowerCase();
-    }
-    try {
-        return extractPubKey(value).toLowerCase();
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * Resolve wallet's role from explicit role or by matching descriptor/pubkey.
- */
-export function resolveRole(contract, context) {
-    // Explicit role takes precedence
-    if (context.role === "sender" || context.role === "receiver") {
-        return context.role;
-    }
-    const senderKey = contract.params.sender
-        ? extractRawPubKey(contract.params.sender)
-        : undefined;
-    const receiverKey = contract.params.receiver
-        ? extractRawPubKey(contract.params.receiver)
-        : undefined;
-    const matchRole = (rawWalletKey) => {
-        if (!rawWalletKey)
-            return undefined;
-        if (senderKey && rawWalletKey === senderKey) {
-            return "sender";
-        }
-        if (receiverKey && rawWalletKey === receiverKey) {
-            return "receiver";
-        }
-        return undefined;
-    };
-    // Try the preferred descriptor first. If it cannot be resolved
-    // (for example an HD descriptor without derivation support), fall back
-    // to walletPubKey for backward compatibility.
-    if (context.walletDescriptor) {
-        const walletDescriptorKey = extractRawPubKey(context.walletDescriptor);
-        const matchedRole = matchRole(walletDescriptorKey);
-        if (matchedRole) {
-            return matchedRole;
-        }
-        if (!walletDescriptorKey && context.walletPubKey) {
-            return matchRole(extractRawPubKey(context.walletPubKey));
-        }
-        return undefined;
-    }
-    if (context.walletPubKey) {
-        return matchRole(extractRawPubKey(context.walletPubKey));
-    }
-    return undefined;
-}
-/**
- * BIP65 threshold: locktime values below this are interpreted as block heights,
- * values at or above are interpreted as Unix timestamps (seconds).
- */
-const CLTV_HEIGHT_THRESHOLD = 500000000n;
-/**
- * Check if an absolute (CLTV) locktime is currently satisfied.
- *
- * Following the BIP65 convention:
- * - locktime < 500_000_000  → interpreted as a block height; compared against `context.blockHeight`
- * - locktime >= 500_000_000 → interpreted as a Unix timestamp (seconds); compared against `context.currentTime`
- *
- * Returns false if the relevant context field is missing.
- */
-export function isCltvSatisfied(context, locktime) {
-    if (locktime < CLTV_HEIGHT_THRESHOLD) {
-        if (context.blockHeight === undefined)
-            return false;
-        return BigInt(context.blockHeight) >= locktime;
-    }
-    const currentTimeSec = BigInt(Math.floor(context.currentTime / 1000));
-    return currentTimeSec >= locktime;
-}
-/**
- * Check if a CSV timelock is currently satisfied for the given context/virtual output.
- */
-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

@@ -1,12 +0,0 @@
-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

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

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

@@ -1,191 +0,0 @@
-import { hex } from "@scure/base";
-import { VHTLC } from "../../script/vhtlc.js";
-import { isCltvSatisfied, isCsvSpendable, resolveRole } from "./helpers.js";
-import { sequenceToTimelock, timelockToSequence } from "../../utils/timelock.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.walletDescriptor` (preferred) / `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);
-        if (!role) {
-            return null;
-        }
-        if (context.collaborative) {
-            if (role === "receiver" && preimage) {
-                return {
-                    leaf: script.claim(),
-                    extraWitness: [hex.decode(preimage)],
-                };
-            }
-            if (role === "sender" && isCltvSatisfied(context, 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.walletDescriptor` (preferred) / `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);
-        if (context.collaborative) {
-            if (role === "receiver" && preimage) {
-                paths.push({
-                    leaf: script.claim(),
-                    extraWitness: [hex.decode(preimage)],
-                });
-            }
-            if (role === "sender" && isCltvSatisfied(context, 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

@@ -1,13 +0,0 @@
-// 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

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

package/dist/esm/contracts/vtxoOwnership.js

@@ -1,69 +0,0 @@
-/**
- * Tier 1 helpers that enforce VTXO ownership at call sites that already know
- * the intended contract script. Address-keyed repositories may still hand back
- * legacy duplicate rows under the wrong bucket; these helpers gate reads and
- * writes so a wrong-script row never wins.
- *
- * `script` is the authoritative ownership key. Equality is strict: a missing
- * or empty `vtxo.script` never matches.
- */
-export function vtxoOutpoint(vtxo) {
-    return `${vtxo.txid}:${vtxo.vout}`;
-}
-export function isVtxoForScript(vtxo, script) {
-    return !!vtxo.script && vtxo.script === script;
-}
-export function filterVtxosForScript(vtxos, script) {
-    return vtxos.filter((v) => isVtxoForScript(v, script));
-}
-/**
- * Background/indexer sync flavour: drop wrong-script rows and log enough
- * context to identify each rejection. Returns only matching rows so the
- * caller can keep going.
- */
-export function warnAndFilterVtxosForScript(vtxos, script, context) {
-    const matches = [];
-    const rejected = [];
-    for (const v of vtxos) {
-        if (isVtxoForScript(v, script)) {
-            matches.push(v);
-        }
-        else {
-            rejected.push(`${vtxoOutpoint(v)}(script=${v.script ?? ""})`);
-        }
-    }
-    if (rejected.length > 0) {
-        console.warn(`${context}: dropped ${rejected.length} wrong-script VTXO(s) for script ${script}: ${rejected.join(", ")}`);
-    }
-    return matches;
-}
-/**
- * User-initiated transaction/signing flavour: throw before persisting or
- * signing inconsistent ownership state. Silently skipping here would hide a
- * serious bug in the wallet's spend path.
- */
-export function validateVtxosForScript(vtxos, script, context) {
-    const mismatches = vtxos.filter((v) => !isVtxoForScript(v, script));
-    if (mismatches.length === 0)
-        return;
-    const detail = mismatches
-        .map((v) => `${vtxoOutpoint(v)}(script=${v.script ?? ""})`)
-        .join(", ");
-    throw new Error(`${context}: refusing to persist ${mismatches.length} VTXO(s) whose script does not match ${script}: ${detail}`);
-}
-/**
- * Tier 2 dispatch helpers: route to script-scoped repository methods when
- * available, falling back to Tier 1 address-based filtering otherwise.
- */
-export async function getVtxosForContract(repo, contract) {
-    return repo.getVtxosForScript
-        ? repo.getVtxosForScript(contract.script)
-        : filterVtxosForScript(await repo.getVtxos(contract.address), contract.script);
-}
-export async function saveVtxosForContract(repo, contract, vtxos) {
-    if (repo.saveVtxosForScript) {
-        return repo.saveVtxosForScript({ script: contract.script, address: contract.address }, vtxos);
-    }
-    validateVtxosForScript(vtxos, contract.script, "saveVtxosForContract");
-    return repo.saveVtxos(contract.address, vtxos);
-}