@1sat/wallet-toolbox 0.0.8 → 0.0.10

package/dist/api/locks/index.js

@@ -0,0 +1,291 @@
+/**
+ * Locks Module
+ *
+ * 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, WOC_MAINNET_URL, WOC_TESTNET_URL } from "../constants";
+// ============================================================================
+// Constants
+// ============================================================================
+const LOCK_PROTOCOL = [1, "lock"];
+const LOCK_KEY_ID = "lock";
+// ============================================================================
+// Internal helpers
+// ============================================================================
+function buildLockScript(address, until) {
+    const pkh = Utils.fromBase58Check(address).data;
+    return new Script()
+        .writeScript(Script.fromHex(LOCK_PREFIX))
+        .writeBin(pkh)
+        .writeNumber(until)
+        .writeScript(Script.fromHex(LOCK_SUFFIX));
+}
+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 {
+        const response = await fetch(`${baseUrl}/chain/info`, { headers });
+        if (!response.ok)
+            return null;
+        return await response.json();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get lock data summary.
+ */
+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;
+        const result = await ctx.wallet.listOutputs({
+            basket: LOCK_BASKET,
+            includeTags: true,
+            limit: 10000,
+        });
+        const outputs = result.outputs;
+        for (const o of outputs) {
+            const untilTag = o.tags?.find((t) => t.startsWith("until:"));
+            if (!untilTag)
+                continue;
+            const until = Number.parseInt(untilTag.slice(6), 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.
+ */
+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"],
+                    },
+                },
+            },
+            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 };
+        }
+        catch (error) {
+            return { error: error instanceof Error ? error.message : "unknown-error" };
+        }
+    },
+};
+/**
+ * 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,
+            });
+            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 },
+            });
+            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,
+            });
+            if ("error" in signResult) {
+                return { error: String(signResult.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];

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

@@ -0,0 +1,102 @@
+/**
+ * Ordinals Module
+ *
+ * Skills for managing ordinals/inscriptions.
+ * Returns WalletOutput[] directly from the SDK - no custom mapping needed.
+ */
+import { type WalletOutput, type CreateActionArgs } from "@bsv/sdk";
+import type { Skill, OneSatContext } from "../skills/types";
+type PubKeyHex = string;
+export interface TransferOrdinalRequest {
+    /** Outpoint of the ordinal to transfer (txid_vout format) */
+    outpoint: string;
+    /** Recipient's identity public key (preferred) */
+    counterparty?: PubKeyHex;
+    /** Legacy: raw P2PKH address */
+    address?: string;
+    /** Paymail address */
+    paymail?: string;
+}
+export interface ListOrdinalRequest {
+    /** Outpoint of ordinal to list */
+    outpoint: string;
+    /** Price in satoshis */
+    price: number;
+    /** Address that receives payment on purchase (BRC-29 receive address) */
+    payAddress: string;
+}
+export interface PurchaseOrdinalRequest {
+    /** Outpoint of listing to purchase */
+    outpoint: string;
+    /** Marketplace address for fees */
+    marketplaceAddress?: string;
+    /** Marketplace fee rate (0-1) */
+    marketplaceRate?: number;
+    /** Optional content type - looked up from ordfs API if not provided */
+    contentType?: string;
+    /** Optional origin outpoint - looked up from ordfs API if not provided */
+    origin?: string;
+}
+export interface OrdinalOperationResponse {
+    txid?: string;
+    rawtx?: string;
+    error?: string;
+}
+/**
+ * Build CreateActionArgs for transferring an ordinal.
+ * Does NOT execute - returns params for createAction.
+ */
+export declare function buildTransferOrdinal(ctx: OneSatContext, request: TransferOrdinalRequest): Promise<CreateActionArgs | {
+    error: string;
+}>;
+/**
+ * Build CreateActionArgs for listing an ordinal for sale.
+ * Does NOT execute - returns params for createAction.
+ */
+export declare function buildListOrdinal(ctx: OneSatContext, request: ListOrdinalRequest): Promise<CreateActionArgs | {
+    error: string;
+}>;
+/** Input for listOrdinals skill */
+export interface ListOrdinalsInput {
+    /** Max number of ordinals to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/**
+ * List ordinals from the wallet.
+ */
+export declare const listOrdinals: Skill<ListOrdinalsInput, WalletOutput[]>;
+/** Input for deriveCancelAddress skill */
+export interface DeriveCancelAddressInput {
+    /** Outpoint of the ordinal listing */
+    outpoint: string;
+}
+/**
+ * Derive a cancel address for an ordinal listing.
+ */
+export declare const deriveCancelAddress: Skill<DeriveCancelAddressInput, string>;
+/**
+ * Transfer an ordinal to a new owner.
+ */
+export declare const transferOrdinal: Skill<TransferOrdinalRequest, OrdinalOperationResponse>;
+/**
+ * List an ordinal for sale on the global orderbook.
+ */
+export declare const listOrdinal: Skill<ListOrdinalRequest, OrdinalOperationResponse>;
+/** Input for cancelListing skill */
+export interface CancelListingInput {
+    /** Outpoint of the listing to cancel */
+    outpoint: string;
+}
+/**
+ * Cancel an ordinal listing.
+ */
+export declare const cancelListing: Skill<CancelListingInput, OrdinalOperationResponse>;
+/**
+ * Purchase an ordinal from the global orderbook.
+ */
+export declare const purchaseOrdinal: Skill<PurchaseOrdinalRequest, OrdinalOperationResponse>;
+/** All ordinals skills for registry */
+export declare const ordinalsSkills: (Skill<ListOrdinalsInput, WalletOutput[]> | Skill<DeriveCancelAddressInput, string> | Skill<TransferOrdinalRequest, OrdinalOperationResponse> | Skill<ListOrdinalRequest, OrdinalOperationResponse> | Skill<PurchaseOrdinalRequest, OrdinalOperationResponse>)[];
+export {};