@1sat/wallet-toolbox 0.0.9 → 0.0.10

package/dist/api/locks/index.d.ts

@@ -1,9 +1,9 @@
 /**
  * Locks Module
  *
- * Functions for time-locking BSV.
+ * Skills for time-locking BSV.
  */
-import { type WalletInterface, type WalletOutput } from "@bsv/sdk";
+import type { Skill } from "../skills/types";
 export interface LockBsvRequest {
     /** Amount in satoshis to lock */
     satoshis: number;
@@ -23,22 +23,25 @@ export interface LockOperationResponse {
     rawtx?: string;
     error?: string;
 }
-/**
- * List locked outputs from the lock basket.
- * Returns WalletOutput[] directly - use tags for metadata (lock:until:).
- */
-export declare function listLocks(cwi: WalletInterface, limit?: number): Promise<WalletOutput[]>;
+/** Input for getLockData skill (no required params) */
+export type GetLockDataInput = Record<string, never>;
 /**
  * Get lock data summary.
  */
-export declare function getLockData(cwi: WalletInterface, chain?: "main" | "test", wocApiKey?: string): Promise<LockData>;
+export declare const getLockData: Skill<GetLockDataInput, LockData>;
+/** Input for lockBsv skill */
+export interface LockBsvInput {
+    requests: LockBsvRequest[];
+}
 /**
  * Lock BSV until a block height.
- * Derives lock address using hardcoded keyID.
  */
-export declare function lockBsv(cwi: WalletInterface, requests: LockBsvRequest[]): Promise<LockOperationResponse>;
+export declare const lockBsv: Skill<LockBsvInput, LockOperationResponse>;
+/** Input for unlockBsv skill (no required params) */
+export type UnlockBsvInput = Record<string, never>;
 /**
  * Unlock matured BSV locks.
- * Uses createSignature with stored keyID to sign unlock transactions.
  */
-export declare function unlockBsv(cwi: WalletInterface, chain?: "main" | "test", wocApiKey?: string): Promise<LockOperationResponse>;
+export declare const unlockBsv: Skill<UnlockBsvInput, LockOperationResponse>;
+/** All lock skills for registry */
+export declare const locksSkills: (Skill<GetLockDataInput, LockData> | Skill<LockBsvInput, LockOperationResponse> | Skill<UnlockBsvInput, LockOperationResponse>)[];

package/dist/api/locks/index.js

@@ -1,16 +1,18 @@
 /**
  * Locks Module
  *
- * Functions for time-locking BSV.
+ * Skills for time-locking BSV.
  */
 import { Hash, PublicKey, Script, Transaction, TransactionSignature, Utils, } from "@bsv/sdk";
-import { LOCK_BASKET, LOCK_PREFIX, LOCK_SUFFIX, MIN_UNLOCK_SATS } from "../constants";
-import { getChainInfo } from "../balance";
-// Hardcoded keyID for all locks - deterministic derivation
+import { LOCK_BASKET, LOCK_PREFIX, LOCK_SUFFIX, MIN_UNLOCK_SATS, WOC_MAINNET_URL, WOC_TESTNET_URL } from "../constants";
+// ============================================================================
+// Constants
+// ============================================================================
+const LOCK_PROTOCOL = [1, "lock"];
 const LOCK_KEY_ID = "lock";
-/**
- * Build lock script for time-locked BSV.
- */
+// ============================================================================
+// Internal helpers
+// ============================================================================
 function buildLockScript(address, until) {
     const pkh = Utils.fromBase58Check(address).data;
     return new Script()
@@ -19,215 +21,271 @@ function buildLockScript(address, until) {
         .writeNumber(until)
         .writeScript(Script.fromHex(LOCK_SUFFIX));
 }
-/**
- * List locked outputs from the lock basket.
- * Returns WalletOutput[] directly - use tags for metadata (lock:until:).
- */
-export async function listLocks(cwi, limit = 10000) {
-    const result = await cwi.listOutputs({
-        basket: LOCK_BASKET,
-        includeTags: true,
-        limit,
-    });
-    return result.outputs;
-}
-/**
- * Get lock data summary.
- */
-export async function getLockData(cwi, chain = "main", wocApiKey) {
-    const lockData = { totalLocked: 0, unlockable: 0, nextUnlock: 0 };
-    const chainInfo = await getChainInfo(chain, wocApiKey);
-    const currentHeight = chainInfo?.blocks || 0;
-    const outputs = await listLocks(cwi);
-    for (const o of outputs) {
-        const lockTag = o.tags?.find((t) => t.startsWith("lock:until:"));
-        if (!lockTag)
-            continue;
-        const until = parseInt(lockTag.slice(11), 10);
-        lockData.totalLocked += o.satoshis;
-        if (until <= currentHeight) {
-            lockData.unlockable += o.satoshis;
-        }
-        else if (!lockData.nextUnlock || until < lockData.nextUnlock) {
-            lockData.nextUnlock = until;
-        }
-    }
-    if (lockData.unlockable < MIN_UNLOCK_SATS * outputs.length) {
-        lockData.unlockable = 0;
-    }
-    return lockData;
-}
-/**
- * Lock BSV until a block height.
- * Derives lock address using hardcoded keyID.
- */
-export async function lockBsv(cwi, requests) {
+async function getChainInfoInternal(chain, wocApiKey) {
+    const baseUrl = chain === "main" ? WOC_MAINNET_URL : WOC_TESTNET_URL;
+    const headers = {};
+    if (wocApiKey)
+        headers["woc-api-key"] = wocApiKey;
     try {
-        if (!requests || requests.length === 0) {
-            return { error: "no-lock-requests" };
-        }
-        // Derive lock address once (same for all locks)
-        const { publicKey } = await cwi.getPublicKey({
-            protocolID: [1, "lock"],
-            keyID: LOCK_KEY_ID,
-            counterparty: "self",
-            forSelf: true,
-        });
-        const lockAddress = PublicKey.fromString(publicKey).toAddress();
-        const outputs = [];
-        for (const req of requests) {
-            if (req.satoshis <= 0)
-                return { error: "invalid-satoshis" };
-            if (req.until <= 0)
-                return { error: "invalid-block-height" };
-            const lockingScript = buildLockScript(lockAddress, req.until);
-            outputs.push({
-                lockingScript: lockingScript.toHex(),
-                satoshis: req.satoshis,
-                outputDescription: `Lock ${req.satoshis} sats until block ${req.until}`,
-                basket: LOCK_BASKET,
-                tags: [`lock:until:${req.until}`],
-            });
-        }
-        const result = await cwi.createAction({
-            description: `Lock BSV in ${requests.length} output(s)`,
-            outputs,
-        });
-        if (!result.txid) {
-            return { error: "no-txid-returned" };
-        }
-        return { txid: result.txid, rawtx: result.tx ? Utils.toHex(result.tx) : undefined };
+        const response = await fetch(`${baseUrl}/chain/info`, { headers });
+        if (!response.ok)
+            return null;
+        return await response.json();
     }
-    catch (error) {
-        return { error: error instanceof Error ? error.message : "unknown-error" };
+    catch {
+        return null;
     }
 }
 /**
- * Unlock matured BSV locks.
- * Uses createSignature with stored keyID to sign unlock transactions.
+ * Get lock data summary.
  */
-export async function unlockBsv(cwi, chain = "main", wocApiKey) {
-    try {
-        // Get current block height
-        const chainInfo = await getChainInfo(chain, wocApiKey);
+export const getLockData = {
+    meta: {
+        name: "getLockData",
+        description: "Get summary of time-locked BSV (total, unlockable, next unlock height)",
+        category: "locks",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    async execute(ctx) {
+        const lockData = { totalLocked: 0, unlockable: 0, nextUnlock: 0 };
+        const chainInfo = await getChainInfoInternal(ctx.chain, ctx.wocApiKey);
         const currentHeight = chainInfo?.blocks || 0;
-        if (currentHeight === 0) {
-            return { error: "could-not-get-block-height" };
-        }
-        // Get lock outputs from basket
-        const result = await cwi.listOutputs({
+        const result = await ctx.wallet.listOutputs({
             basket: LOCK_BASKET,
             includeTags: true,
-            include: "locking scripts",
             limit: 10000,
         });
-        // Filter for matured locks
-        const maturedLocks = [];
-        for (const o of result.outputs) {
-            const untilTag = o.tags?.find((t) => t.startsWith("lock:until:"));
+        const outputs = result.outputs;
+        for (const o of outputs) {
+            const untilTag = o.tags?.find((t) => t.startsWith("until:"));
             if (!untilTag)
                 continue;
-            const until = parseInt(untilTag.slice(11), 10);
+            const until = Number.parseInt(untilTag.slice(6), 10);
+            lockData.totalLocked += o.satoshis;
             if (until <= currentHeight) {
-                maturedLocks.push({ output: o, until });
+                lockData.unlockable += o.satoshis;
+            }
+            else if (!lockData.nextUnlock || until < lockData.nextUnlock) {
+                lockData.nextUnlock = until;
             }
         }
-        if (maturedLocks.length === 0) {
-            return { error: "no-matured-locks" };
-        }
-        // Check minimum unlock amount
-        const totalSats = maturedLocks.reduce((sum, l) => sum + l.output.satoshis, 0);
-        if (totalSats < MIN_UNLOCK_SATS * maturedLocks.length) {
-            return { error: "insufficient-unlock-amount" };
+        if (lockData.unlockable < MIN_UNLOCK_SATS * outputs.length) {
+            lockData.unlockable = 0;
         }
-        // Find max until value for lockTime
-        const maxUntil = Math.max(...maturedLocks.map((l) => l.until));
-        // Build createAction args
-        const createResult = await cwi.createAction({
-            description: `Unlock ${maturedLocks.length} lock(s)`,
-            inputs: maturedLocks.map((l) => ({
-                outpoint: l.output.outpoint,
-                inputDescription: "Locked BSV",
-                unlockingScriptLength: 180, // sig + pubkey + preimage estimate
-                sequenceNumber: 0, // Must be < 0xffffffff for nLockTime
-            })),
-            outputs: [
-                {
-                    lockingScript: "", // Will be filled by wallet as change
-                    satoshis: 0, // Will be calculated by wallet
-                    outputDescription: "Unlocked BSV",
+        return lockData;
+    },
+};
+/**
+ * Lock BSV until a block height.
+ */
+export const lockBsv = {
+    meta: {
+        name: "lockBsv",
+        description: "Lock BSV until a specific block height",
+        category: "locks",
+        inputSchema: {
+            type: "object",
+            properties: {
+                requests: {
+                    type: "array",
+                    description: "Array of lock requests",
+                    items: {
+                        type: "object",
+                        properties: {
+                            satoshis: { type: "integer", description: "Amount in satoshis to lock" },
+                            until: { type: "integer", description: "Block height until which to lock" },
+                        },
+                        required: ["satoshis", "until"],
+                    },
                 },
-            ],
-            lockTime: maxUntil,
-            options: { signAndProcess: false },
-        });
-        if ("error" in createResult && createResult.error) {
-            return { error: String(createResult.error) };
+            },
+            required: ["requests"],
+        },
+    },
+    async execute(ctx, input) {
+        try {
+            const { requests } = input;
+            if (!requests || requests.length === 0) {
+                return { error: "no-lock-requests" };
+            }
+            const { publicKey } = await ctx.wallet.getPublicKey({
+                protocolID: LOCK_PROTOCOL,
+                keyID: LOCK_KEY_ID,
+                counterparty: "self",
+                forSelf: true,
+            });
+            const lockAddress = PublicKey.fromString(publicKey).toAddress();
+            const outputs = [];
+            for (const req of requests) {
+                if (req.satoshis <= 0)
+                    return { error: "invalid-satoshis" };
+                if (req.until <= 0)
+                    return { error: "invalid-block-height" };
+                const lockingScript = buildLockScript(lockAddress, req.until);
+                outputs.push({
+                    lockingScript: lockingScript.toHex(),
+                    satoshis: req.satoshis,
+                    outputDescription: `Lock ${req.satoshis} sats until block ${req.until}`,
+                    basket: LOCK_BASKET,
+                    tags: [`until:${req.until}`],
+                    customInstructions: JSON.stringify({
+                        protocolID: LOCK_PROTOCOL,
+                        keyID: LOCK_KEY_ID,
+                    }),
+                });
+            }
+            const result = await ctx.wallet.createAction({
+                description: `Lock BSV in ${requests.length} output(s)`,
+                outputs,
+            });
+            if (!result.txid) {
+                return { error: "no-txid-returned" };
+            }
+            return { txid: result.txid, rawtx: result.tx ? Utils.toHex(result.tx) : undefined };
         }
-        if (!createResult.signableTransaction) {
-            return { error: "no-signable-transaction" };
+        catch (error) {
+            return { error: error instanceof Error ? error.message : "unknown-error" };
         }
-        // Parse transaction from BEEF
-        const tx = Transaction.fromBEEF(createResult.signableTransaction.tx);
-        // Build unlocking scripts for each input
-        const spends = {};
-        for (let i = 0; i < maturedLocks.length; i++) {
-            const lock = maturedLocks[i];
-            const input = tx.inputs[i];
-            const lockingScript = Script.fromHex(lock.output.lockingScript);
-            // Build preimage for signature
-            const preimage = TransactionSignature.format({
-                sourceTXID: input.sourceTXID,
-                sourceOutputIndex: input.sourceOutputIndex,
-                sourceSatoshis: lock.output.satoshis,
-                transactionVersion: tx.version,
-                otherInputs: tx.inputs.filter((_, idx) => idx !== i),
-                outputs: tx.outputs,
-                inputIndex: i,
-                subscript: lockingScript,
-                inputSequence: 0,
-                lockTime: tx.lockTime,
-                scope: TransactionSignature.SIGHASH_ALL |
-                    TransactionSignature.SIGHASH_ANYONECANPAY |
-                    TransactionSignature.SIGHASH_FORKID,
+    },
+};
+/**
+ * Unlock matured BSV locks.
+ */
+export const unlockBsv = {
+    meta: {
+        name: "unlockBsv",
+        description: "Unlock all matured time-locked BSV",
+        category: "locks",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    async execute(ctx) {
+        try {
+            const chainInfo = await getChainInfoInternal(ctx.chain, ctx.wocApiKey);
+            const currentHeight = chainInfo?.blocks || 0;
+            if (currentHeight === 0) {
+                return { error: "could-not-get-block-height" };
+            }
+            const result = await ctx.wallet.listOutputs({
+                basket: LOCK_BASKET,
+                includeTags: true,
+                includeCustomInstructions: true,
+                include: "locking scripts",
+                limit: 10000,
             });
-            // Hash preimage for signing
-            const sighash = Hash.sha256(Hash.sha256(preimage));
-            // Get signature via createSignature using hardcoded keyID
-            const { signature } = await cwi.createSignature({
-                protocolID: [1, "lock"],
-                keyID: LOCK_KEY_ID,
-                counterparty: "self",
-                hashToDirectlySign: Array.from(sighash),
+            const maturedLocks = [];
+            for (const o of result.outputs) {
+                const untilTag = o.tags?.find((t) => t.startsWith("until:"));
+                if (!untilTag)
+                    continue;
+                const until = Number.parseInt(untilTag.slice(6), 10);
+                let protocolID = LOCK_PROTOCOL;
+                let keyID = LOCK_KEY_ID;
+                if (o.customInstructions) {
+                    const instructions = JSON.parse(o.customInstructions);
+                    protocolID = instructions.protocolID ?? LOCK_PROTOCOL;
+                    keyID = instructions.keyID ?? LOCK_KEY_ID;
+                }
+                if (until <= currentHeight) {
+                    maturedLocks.push({ output: o, until, protocolID, keyID });
+                }
+            }
+            if (maturedLocks.length === 0) {
+                return { error: "no-matured-locks" };
+            }
+            const totalSats = maturedLocks.reduce((sum, l) => sum + l.output.satoshis, 0);
+            if (totalSats < MIN_UNLOCK_SATS * maturedLocks.length) {
+                return { error: "insufficient-unlock-amount" };
+            }
+            const maxUntil = Math.max(...maturedLocks.map((l) => l.until));
+            const createResult = await ctx.wallet.createAction({
+                description: `Unlock ${maturedLocks.length} lock(s)`,
+                inputs: maturedLocks.map((l) => ({
+                    outpoint: l.output.outpoint,
+                    inputDescription: "Locked BSV",
+                    unlockingScriptLength: 180,
+                    sequenceNumber: 0,
+                })),
+                outputs: [
+                    {
+                        lockingScript: "",
+                        satoshis: 0,
+                        outputDescription: "Unlocked BSV",
+                    },
+                ],
+                lockTime: maxUntil,
+                options: { signAndProcess: false },
             });
-            // Get public key
-            const { publicKey } = await cwi.getPublicKey({
-                protocolID: [1, "lock"],
-                keyID: LOCK_KEY_ID,
-                counterparty: "self",
-                forSelf: true,
+            if ("error" in createResult && createResult.error) {
+                return { error: String(createResult.error) };
+            }
+            if (!createResult.signableTransaction) {
+                return { error: "no-signable-transaction" };
+            }
+            const tx = Transaction.fromBEEF(createResult.signableTransaction.tx);
+            const spends = {};
+            for (let i = 0; i < maturedLocks.length; i++) {
+                const lock = maturedLocks[i];
+                const input = tx.inputs[i];
+                const lockingScript = Script.fromHex(lock.output.lockingScript);
+                const preimage = TransactionSignature.format({
+                    sourceTXID: input.sourceTXID,
+                    sourceOutputIndex: input.sourceOutputIndex,
+                    sourceSatoshis: lock.output.satoshis,
+                    transactionVersion: tx.version,
+                    otherInputs: tx.inputs.filter((_, idx) => idx !== i),
+                    outputs: tx.outputs,
+                    inputIndex: i,
+                    subscript: lockingScript,
+                    inputSequence: 0,
+                    lockTime: tx.lockTime,
+                    scope: TransactionSignature.SIGHASH_ALL |
+                        TransactionSignature.SIGHASH_ANYONECANPAY |
+                        TransactionSignature.SIGHASH_FORKID,
+                });
+                const sighash = Hash.sha256(Hash.sha256(preimage));
+                const { signature } = await ctx.wallet.createSignature({
+                    protocolID: lock.protocolID,
+                    keyID: lock.keyID,
+                    counterparty: "self",
+                    hashToDirectlySign: Array.from(sighash),
+                });
+                const { publicKey } = await ctx.wallet.getPublicKey({
+                    protocolID: lock.protocolID,
+                    keyID: lock.keyID,
+                    counterparty: "self",
+                    forSelf: true,
+                });
+                const unlockingScript = new Script()
+                    .writeBin(signature)
+                    .writeBin(Utils.toArray(publicKey, "hex"))
+                    .writeBin(Array.from(preimage));
+                spends[i] = { unlockingScript: unlockingScript.toHex() };
+            }
+            const signResult = await ctx.wallet.signAction({
+                reference: createResult.signableTransaction.reference,
+                spends,
             });
-            // Build unlocking script: <sig> <pubkey> <preimage>
-            const unlockingScript = new Script()
-                .writeBin(signature)
-                .writeBin(Utils.toArray(publicKey, "hex"))
-                .writeBin(Array.from(preimage));
-            spends[i] = { unlockingScript: unlockingScript.toHex() };
+            if ("error" in signResult) {
+                return { error: String(signResult.error) };
+            }
+            return {
+                txid: signResult.txid,
+                rawtx: signResult.tx ? Utils.toHex(signResult.tx) : undefined,
+            };
         }
-        // Sign and broadcast
-        const signResult = await cwi.signAction({
-            reference: createResult.signableTransaction.reference,
-            spends,
-        });
-        if ("error" in signResult) {
-            return { error: String(signResult.error) };
+        catch (error) {
+            return { error: error instanceof Error ? error.message : "unknown-error" };
         }
-        return {
-            txid: signResult.txid,
-            rawtx: signResult.tx ? Utils.toHex(signResult.tx) : undefined,
-        };
-    }
-    catch (error) {
-        return { error: error instanceof Error ? error.message : "unknown-error" };
-    }
-}
+    },
+};
+// ============================================================================
+// Module exports
+// ============================================================================
+/** All lock skills for registry */
+export const locksSkills = [getLockData, lockBsv, unlockBsv];