@1sat/wallet-toolbox 0.0.8 → 0.0.10

package/dist/api/payments/index.js

@@ -0,0 +1,185 @@
+/**
+ * Payments Module
+ *
+ * Skills for sending BSV payments.
+ */
+import { P2PKH, Script, Utils } from "@bsv/sdk";
+import { Inscription } from "@bopen-io/templates";
+import { FUNDING_BASKET } from "../constants";
+// ============================================================================
+// Internal helpers
+// ============================================================================
+function isPaymail(address) {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(address);
+}
+function buildInscriptionScript(address, base64Data, mimeType) {
+    const content = Utils.toArray(base64Data, "base64");
+    const inscription = Inscription.create(new Uint8Array(content), mimeType);
+    const inscriptionScript = inscription.lock();
+    const p2pkhScript = new P2PKH().lock(address);
+    const combined = new Script();
+    for (const chunk of inscriptionScript.chunks)
+        combined.chunks.push(chunk);
+    for (const chunk of p2pkhScript.chunks)
+        combined.chunks.push(chunk);
+    return combined;
+}
+/**
+ * Send BSV to one or more destinations.
+ */
+export const sendBsv = {
+    meta: {
+        name: "sendBsv",
+        description: "Send BSV to one or more destinations (addresses, scripts, or OP_RETURN)",
+        category: "payments",
+        inputSchema: {
+            type: "object",
+            properties: {
+                requests: {
+                    type: "array",
+                    description: "Array of payment requests",
+                    items: {
+                        type: "object",
+                        properties: {
+                            address: { type: "string", description: "Destination P2PKH address" },
+                            paymail: { type: "string", description: "Destination paymail address" },
+                            satoshis: { type: "integer", description: "Amount in satoshis" },
+                            script: { type: "string", description: "Custom locking script (hex)" },
+                            data: {
+                                type: "array",
+                                description: "OP_RETURN data elements",
+                                items: { type: "string" },
+                            },
+                        },
+                        required: ["satoshis"],
+                    },
+                },
+            },
+            required: ["requests"],
+        },
+    },
+    async execute(ctx, input) {
+        try {
+            const { requests } = input;
+            if (!requests || requests.length === 0) {
+                return { error: "no-requests" };
+            }
+            const outputs = [];
+            for (const req of requests) {
+                let lockingScript;
+                if (req.script) {
+                    lockingScript = Script.fromHex(req.script);
+                }
+                else if (req.address) {
+                    if (req.inscription) {
+                        lockingScript = buildInscriptionScript(req.address, req.inscription.base64Data, req.inscription.mimeType);
+                    }
+                    else {
+                        lockingScript = new P2PKH().lock(req.address);
+                    }
+                }
+                else if (req.data && req.data.length > 0) {
+                    try {
+                        lockingScript = Script.fromASM(`OP_0 OP_RETURN ${req.data.join(" ")}`);
+                    }
+                    catch {
+                        return { error: "invalid-data" };
+                    }
+                }
+                else if (req.paymail) {
+                    return { error: "paymail-not-yet-implemented" };
+                }
+                else {
+                    return { error: "invalid-request" };
+                }
+                outputs.push({
+                    lockingScript: lockingScript.toHex(),
+                    satoshis: req.satoshis,
+                    outputDescription: `Payment of ${req.satoshis} sats`,
+                });
+            }
+            const result = await ctx.wallet.createAction({
+                description: `Send ${requests.length} payment(s)`,
+                outputs,
+                options: { signAndProcess: true },
+            });
+            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" };
+        }
+    },
+};
+/**
+ * Send all BSV to a destination address.
+ */
+export const sendAllBsv = {
+    meta: {
+        name: "sendAllBsv",
+        description: "Send all BSV from wallet to a single destination address",
+        category: "payments",
+        inputSchema: {
+            type: "object",
+            properties: {
+                destination: {
+                    type: "string",
+                    description: "Destination P2PKH address to send all funds to",
+                },
+            },
+            required: ["destination"],
+        },
+    },
+    async execute(ctx, input) {
+        try {
+            const { destination } = input;
+            if (isPaymail(destination)) {
+                return { error: "paymail-not-yet-implemented" };
+            }
+            const listResult = await ctx.wallet.listOutputs({
+                basket: FUNDING_BASKET,
+                include: "locking scripts",
+                limit: 10000,
+            });
+            if (!listResult.outputs || listResult.outputs.length === 0) {
+                return { error: "no-funds" };
+            }
+            const totalSats = listResult.outputs.reduce((sum, o) => sum + o.satoshis, 0);
+            const estimatedFee = Math.ceil((listResult.outputs.length * 150 + 44) * 1);
+            const sendAmount = totalSats - estimatedFee;
+            if (sendAmount <= 0) {
+                return { error: "insufficient-funds-for-fee" };
+            }
+            const inputs = listResult.outputs.map((o) => ({
+                outpoint: o.outpoint,
+                inputDescription: "Sweep funds",
+            }));
+            const result = await ctx.wallet.createAction({
+                description: "Send all BSV",
+                inputs,
+                outputs: [
+                    {
+                        lockingScript: new P2PKH().lock(destination).toHex(),
+                        satoshis: sendAmount,
+                        outputDescription: "Sweep all funds",
+                    },
+                ],
+                options: { signAndProcess: true },
+            });
+            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" };
+        }
+    },
+};
+// ============================================================================
+// Module exports
+// ============================================================================
+/** All payment skills for registry */
+export const paymentsSkills = [sendBsv, sendAllBsv];

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

@@ -0,0 +1,35 @@
+/**
+ * Signing Module
+ *
+ * Skills for message signing.
+ */
+import type { Skill } from "../skills/types";
+export interface SignMessageRequest {
+    /** Message to sign */
+    message: string;
+    /** Message encoding */
+    encoding?: "utf8" | "hex" | "base64";
+    /** Derivation tag for key selection */
+    tag?: {
+        label: string;
+        id: string;
+        domain: string;
+        meta: Record<string, string>;
+    };
+}
+export interface SignedMessage {
+    address: string;
+    pubKey: string;
+    message: string;
+    sig: string;
+    derivationTag?: SignMessageRequest["tag"];
+}
+export interface SignMessageResponse extends Partial<SignedMessage> {
+    error?: string;
+}
+/**
+ * Sign a message using BSM (Bitcoin Signed Message) format.
+ */
+export declare const signMessage: Skill<SignMessageRequest, SignMessageResponse>;
+/** All signing skills for registry */
+export declare const signingSkills: Skill<SignMessageRequest, SignMessageResponse>[];

package/dist/api/signing/index.js

@@ -0,0 +1,78 @@
+/**
+ * Signing Module
+ *
+ * Skills for message signing.
+ */
+import { BigNumber, BSM, PublicKey, Signature, Utils } from "@bsv/sdk";
+import { MESSAGE_SIGNING_PROTOCOL } from "../constants";
+// ============================================================================
+// Skills
+// ============================================================================
+/**
+ * Sign a message using BSM (Bitcoin Signed Message) format.
+ */
+export const signMessage = {
+    meta: {
+        name: "signMessage",
+        description: "Sign a message using BSM (Bitcoin Signed Message) format",
+        category: "signing",
+        inputSchema: {
+            type: "object",
+            properties: {
+                message: { type: "string", description: "Message to sign" },
+                encoding: {
+                    type: "string",
+                    description: "Message encoding (utf8, hex, base64)",
+                    enum: ["utf8", "hex", "base64"],
+                },
+                tag: {
+                    type: "object",
+                    description: "Derivation tag for key selection",
+                    properties: {
+                        label: { type: "string" },
+                        id: { type: "string" },
+                        domain: { type: "string" },
+                        meta: { type: "object" },
+                    },
+                },
+            },
+            required: ["message"],
+        },
+    },
+    async execute(ctx, input) {
+        try {
+            const { message, encoding = "utf8", tag } = input;
+            const messageBytes = Utils.toArray(message, encoding);
+            const msgHash = BSM.magicHash(messageBytes);
+            const keyID = tag ? `${tag.label}:${tag.id}:${tag.domain}` : "identity";
+            const result = await ctx.wallet.createSignature({
+                protocolID: MESSAGE_SIGNING_PROTOCOL,
+                keyID,
+                hashToDirectlySign: Array.from(msgHash),
+            });
+            const pubKeyResult = await ctx.wallet.getPublicKey({
+                protocolID: MESSAGE_SIGNING_PROTOCOL,
+                keyID,
+                forSelf: true,
+            });
+            const publicKey = PublicKey.fromString(pubKeyResult.publicKey);
+            const signature = Signature.fromDER(result.signature);
+            const recovery = signature.CalculateRecoveryFactor(publicKey, new BigNumber(msgHash));
+            return {
+                address: publicKey.toAddress(),
+                pubKey: publicKey.toString(),
+                message,
+                sig: signature.toCompact(recovery, true, "base64"),
+                derivationTag: tag,
+            };
+        }
+        catch (error) {
+            return { error: error instanceof Error ? error.message : "unknown-error" };
+        }
+    },
+};
+// ============================================================================
+// Module exports
+// ============================================================================
+/** All signing skills for registry */
+export const signingSkills = [signMessage];

package/dist/api/skills/registry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Skill registry for runtime discovery and MCP integration.
+ */
+import type { Skill, SkillCategory } from "./types";
+type AnySkill = Skill<any, any>;
+/**
+ * MCP-compatible tool definition.
+ */
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: object;
+}
+/**
+ * Registry for collecting and discovering skills at runtime.
+ */
+export declare class SkillRegistry {
+    private skills;
+    /**
+     * Register a skill.
+     */
+    register(skill: AnySkill): void;
+    /**
+     * Register multiple skills.
+     */
+    registerAll(skills: AnySkill[]): void;
+    /**
+     * Get a skill by name.
+     */
+    get(name: string): AnySkill | undefined;
+    /**
+     * Check if a skill exists.
+     */
+    has(name: string): boolean;
+    /**
+     * List all registered skills.
+     */
+    list(): Skill[];
+    /**
+     * List skills by category.
+     */
+    listByCategory(category: SkillCategory): Skill[];
+    /**
+     * Get skill names.
+     */
+    names(): string[];
+    /**
+     * Convert to MCP-compatible tool list.
+     * Prefixes names with "1sat__" for namespace isolation.
+     */
+    toMcpTools(): McpTool[];
+    /**
+     * Number of registered skills.
+     */
+    get size(): number;
+}
+/**
+ * Global skill registry singleton.
+ */
+export declare const skillRegistry: SkillRegistry;
+export {};

package/dist/api/skills/registry.js

@@ -0,0 +1,74 @@
+/**
+ * Skill registry for runtime discovery and MCP integration.
+ */
+/**
+ * Registry for collecting and discovering skills at runtime.
+ */
+export class SkillRegistry {
+    skills = new Map();
+    /**
+     * Register a skill.
+     */
+    register(skill) {
+        this.skills.set(skill.meta.name, skill);
+    }
+    /**
+     * Register multiple skills.
+     */
+    registerAll(skills) {
+        for (const skill of skills) {
+            this.register(skill);
+        }
+    }
+    /**
+     * Get a skill by name.
+     */
+    get(name) {
+        return this.skills.get(name);
+    }
+    /**
+     * Check if a skill exists.
+     */
+    has(name) {
+        return this.skills.has(name);
+    }
+    /**
+     * List all registered skills.
+     */
+    list() {
+        return Array.from(this.skills.values());
+    }
+    /**
+     * List skills by category.
+     */
+    listByCategory(category) {
+        return this.list().filter((s) => s.meta.category === category);
+    }
+    /**
+     * Get skill names.
+     */
+    names() {
+        return Array.from(this.skills.keys());
+    }
+    /**
+     * Convert to MCP-compatible tool list.
+     * Prefixes names with "1sat__" for namespace isolation.
+     */
+    toMcpTools() {
+        return this.list().map((skill) => ({
+            name: `1sat__${skill.meta.name}`,
+            description: skill.meta.description,
+            inputSchema: skill.meta.inputSchema,
+        }));
+    }
+    /**
+     * Number of registered skills.
+     */
+    get size() {
+        return this.skills.size;
+    }
+}
+/**
+ * Global skill registry singleton.
+ */
+export const skillRegistry = new SkillRegistry();

package/dist/api/skills/types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Core types for the skill/action pattern.
+ */
+import type { WalletInterface } from "@bsv/sdk";
+import type { OneSatServices } from "../../services/OneSatServices";
+/**
+ * Context passed to all skills.
+ * Contains the wallet and optional services for backend operations.
+ */
+export interface OneSatContext {
+    /** BRC-100 compatible wallet interface */
+    wallet: WalletInterface;
+    /** Optional services for operations requiring backend (purchases, lookups) */
+    services?: OneSatServices;
+    /** Network chain */
+    chain: "main" | "test";
+    /** Optional WhatsOnChain API key */
+    wocApiKey?: string;
+}
+/**
+ * JSON Schema property definition for skill input schemas.
+ */
+export interface JsonSchemaProperty {
+    type: "string" | "number" | "integer" | "boolean" | "object" | "array";
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+    items?: JsonSchemaProperty;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+/**
+ * Skill category for grouping related operations.
+ */
+export type SkillCategory = "balance" | "payments" | "ordinals" | "tokens" | "inscriptions" | "locks" | "signing" | "broadcast";
+/**
+ * Metadata describing a skill for AI agents and tooling.
+ */
+export interface SkillMetadata<TInput = unknown> {
+    /** Unique skill name */
+    name: string;
+    /** Human-readable description of what the skill does */
+    description: string;
+    /** Category for grouping */
+    category: SkillCategory;
+    /** JSON Schema for the input parameters (MCP-compatible) */
+    inputSchema: {
+        type: "object";
+        properties: Record<string, JsonSchemaProperty>;
+        required?: string[];
+    };
+    /** Whether this skill requires OneSatServices to be provided in context */
+    requiresServices?: boolean;
+}
+/**
+ * A skill is a self-describing action that can be executed with a context.
+ */
+export interface Skill<TInput = unknown, TOutput = unknown> {
+    /** Metadata describing the skill */
+    meta: SkillMetadata<TInput>;
+    /** Execute the skill with context and input */
+    execute: (ctx: OneSatContext, input: TInput) => Promise<TOutput>;
+}
+/**
+ * Helper to create a context object from a wallet and options.
+ */
+export declare function createContext(wallet: WalletInterface, options?: {
+    services?: OneSatServices;
+    chain?: "main" | "test";
+    wocApiKey?: string;
+}): OneSatContext;

package/dist/api/skills/types.js

@@ -0,0 +1,14 @@
+/**
+ * Core types for the skill/action pattern.
+ */
+/**
+ * Helper to create a context object from a wallet and options.
+ */
+export function createContext(wallet, options) {
+    return {
+        wallet,
+        services: options?.services,
+        chain: options?.chain ?? "main",
+        wocApiKey: options?.wocApiKey,
+    };
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Tokens Module
+ *
+ * Skills for managing BSV21 tokens.
+ */
+import { type WalletOutput } from "@bsv/sdk";
+import type { Skill } from "../skills/types";
+type PubKeyHex = string;
+export interface Bsv21Balance {
+    /** Token protocol (bsv-20) */
+    p: string;
+    /** Token ID (outpoint for BSV21, tick for BSV20) */
+    id: string;
+    /** Token symbol */
+    sym?: string;
+    /** Token icon URL */
+    icon?: string;
+    /** Decimal places */
+    dec: number;
+    /** Total amount (confirmed + pending) */
+    amt: string;
+    /** Breakdown of confirmed vs pending */
+    all: {
+        confirmed: bigint;
+        pending: bigint;
+    };
+    /** Listed amounts (if applicable) */
+    listed: {
+        confirmed: bigint;
+        pending: bigint;
+    };
+}
+export interface SendBsv21Request {
+    /** Token ID (txid_vout format) */
+    tokenId: string;
+    /** Amount to send (as bigint or string) */
+    amount: bigint | string;
+    /** Recipient's identity public key (preferred) */
+    counterparty?: PubKeyHex;
+    /** Legacy: raw P2PKH address */
+    address?: string;
+    /** Paymail address */
+    paymail?: string;
+}
+export interface PurchaseBsv21Request {
+    /** Token ID (txid_vout format of the deploy transaction) */
+    tokenId: string;
+    /** Outpoint of listed token UTXO (OrdLock containing BSV21) */
+    outpoint: string;
+    /** Amount of tokens in the listing */
+    amount: bigint | string;
+    /** Optional marketplace fee address */
+    marketplaceAddress?: string;
+    /** Optional marketplace fee rate (0-1) */
+    marketplaceRate?: number;
+}
+export interface TokenOperationResponse {
+    txid?: string;
+    rawtx?: string;
+    error?: string;
+}
+/** Input for listTokens skill */
+export interface ListTokensInput {
+    /** Max number of tokens to return */
+    limit?: number;
+}
+/**
+ * List BSV21 token outputs from the wallet.
+ */
+export declare const listTokens: Skill<ListTokensInput, WalletOutput[]>;
+/** Input for getBsv21Balances skill (no required params) */
+export type GetBsv21BalancesInput = Record<string, never>;
+/**
+ * Get aggregated BSV21 token balances.
+ */
+export declare const getBsv21Balances: Skill<GetBsv21BalancesInput, Bsv21Balance[]>;
+/**
+ * Send BSV21 tokens to an address.
+ */
+export declare const sendBsv21: Skill<SendBsv21Request, TokenOperationResponse>;
+/**
+ * Purchase BSV21 tokens from marketplace.
+ */
+export declare const purchaseBsv21: Skill<PurchaseBsv21Request, TokenOperationResponse>;
+/** All token skills for registry */
+export declare const tokensSkills: (Skill<ListTokensInput, WalletOutput[]> | Skill<GetBsv21BalancesInput, Bsv21Balance[]> | Skill<SendBsv21Request, TokenOperationResponse> | Skill<PurchaseBsv21Request, TokenOperationResponse>)[];
+export {};