@1sat/wallet-toolbox 0.0.27 → 0.0.29

package/dist/api/constants.d.ts

@@ -17,6 +17,8 @@ export declare const LOCK_PREFIX = "20d37f4de0d1c735b4d51a5572df0f3d9104d1d9e99d
 export declare const LOCK_SUFFIX = "88ac7e7601207f75a9011488";
 export declare const ONESAT_PROTOCOL: [0 | 1 | 2, string];
 export declare const MESSAGE_SIGNING_PROTOCOL: [0 | 1 | 2, string];
+export declare const BSV21_PROTOCOL: [0 | 1 | 2, string];
+export declare const BSV21_FEE_SATS = 1000;
 export declare const MAX_INSCRIPTION_BYTES = 100000;
 export declare const MIN_UNLOCK_SATS = 1500;
 export declare const EXCHANGE_RATE_CACHE_TTL: number;

package/dist/api/constants.js

@@ -24,6 +24,9 @@ export const LOCK_SUFFIX = "88ac7e7601207f75a9011488";
 // Protocol IDs
 export const ONESAT_PROTOCOL = [1, "onesat"];
 export const MESSAGE_SIGNING_PROTOCOL = [1, "message signing"];
+export const BSV21_PROTOCOL = [1, "bsv21"];
+// Fee constants
+export const BSV21_FEE_SATS = 1000;
 // Constants
 export const MAX_INSCRIPTION_BYTES = 100_000;
 export const MIN_UNLOCK_SATS = 1500;

package/dist/api/index.d.ts

@@ -6,17 +6,17 @@
  *
  * Usage:
  * ```typescript
- * import { createContext, transferOrdinal, skillRegistry } from '@1sat/wallet-toolbox/api';
+ * import { createContext, transferOrdinals, skillRegistry } from '@1sat/wallet-toolbox/api';
  *
  * // Create context with a BRC-100 compatible wallet
  * const ctx = createContext(wallet, { services, chain: 'main' });
  *
  * // Execute skills directly
- * const result = await transferOrdinal.execute(ctx, { outpoint: '...', address: '...' });
+ * const result = await transferOrdinals.execute(ctx, { transfers: [...], inputBEEF: [...] });
  *
  * // Or via registry (useful for AI agents)
- * const skill = skillRegistry.get('transferOrdinal');
- * const result = await skill.execute(ctx, { outpoint: '...', address: '...' });
+ * const skill = skillRegistry.get('transferOrdinals');
+ * const result = await skill.execute(ctx, { transfers: [...], inputBEEF: [...] });
  *
  * // Get MCP-compatible tool list
  * const tools = skillRegistry.toMcpTools();

package/dist/api/index.js

@@ -6,17 +6,17 @@
  *
  * Usage:
  * ```typescript
- * import { createContext, transferOrdinal, skillRegistry } from '@1sat/wallet-toolbox/api';
+ * import { createContext, transferOrdinals, skillRegistry } from '@1sat/wallet-toolbox/api';
  *
  * // Create context with a BRC-100 compatible wallet
  * const ctx = createContext(wallet, { services, chain: 'main' });
  *
  * // Execute skills directly
- * const result = await transferOrdinal.execute(ctx, { outpoint: '...', address: '...' });
+ * const result = await transferOrdinals.execute(ctx, { transfers: [...], inputBEEF: [...] });
  *
  * // Or via registry (useful for AI agents)
- * const skill = skillRegistry.get('transferOrdinal');
- * const result = await skill.execute(ctx, { outpoint: '...', address: '...' });
+ * const skill = skillRegistry.get('transferOrdinals');
+ * const result = await skill.execute(ctx, { transfers: [...], inputBEEF: [...] });
  *
  * // Get MCP-compatible tool list
  * const tools = skillRegistry.toMcpTools();

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

@@ -7,19 +7,25 @@
 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;
+export interface TransferItem {
+    /** The ordinal output to transfer (from listOutputs) */
+    ordinal: WalletOutput;
     /** Recipient's identity public key (preferred) */
     counterparty?: PubKeyHex;
-    /** Legacy: raw P2PKH address */
+    /** Raw P2PKH address */
     address?: string;
-    /** Paymail address */
-    paymail?: string;
+}
+export interface TransferOrdinalsRequest {
+    /** Ordinals to transfer with their destinations */
+    transfers: TransferItem[];
+    /** BEEF data from listOutputs (include: 'entire transactions') */
+    inputBEEF: number[];
 }
 export interface ListOrdinalRequest {
-    /** Outpoint of ordinal to list */
-    outpoint: string;
+    /** The ordinal output to list (from listOutputs) */
+    ordinal: WalletOutput;
+    /** BEEF data from listOutputs (include: 'entire transactions') */
+    inputBEEF: number[];
     /** Price in satoshis */
     price: number;
     /** Address that receives payment on purchase (BRC-29 receive address) */
@@ -45,10 +51,10 @@ export interface OrdinalOperationResponse {
     error?: string;
 }
 /**
- * Build CreateActionArgs for transferring an ordinal.
+ * Build CreateActionArgs for transferring one or more ordinals.
  * Does NOT execute - returns params for createAction.
  */
-export declare function buildTransferOrdinal(ctx: OneSatContext, request: TransferOrdinalRequest): Promise<CreateActionArgs | {
+export declare function buildTransferOrdinals(ctx: OneSatContext, request: TransferOrdinalsRequest): Promise<CreateActionArgs | {
     error: string;
 }>;
 /**
@@ -81,15 +87,17 @@ export declare const deriveCancelAddress: Skill<DeriveCancelAddressInput, string
 /**
  * Transfer an ordinal to a new owner.
  */
-export declare const transferOrdinal: Skill<TransferOrdinalRequest, OrdinalOperationResponse>;
+export declare const transferOrdinals: Skill<TransferOrdinalsRequest, 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;
+    /** The listing output to cancel (from listOutputs, must include lockingScript) */
+    listing: WalletOutput;
+    /** BEEF data from listOutputs (include: 'entire transactions') */
+    inputBEEF: number[];
 }
 /**
  * Cancel an ordinal listing.
@@ -100,5 +108,5 @@ export declare const cancelListing: Skill<CancelListingInput, OrdinalOperationRe
  */
 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 declare const ordinalsSkills: (Skill<ListOrdinalsInput, WalletOutput[]> | Skill<DeriveCancelAddressInput, string> | Skill<TransferOrdinalsRequest, OrdinalOperationResponse> | Skill<ListOrdinalRequest, OrdinalOperationResponse> | Skill<CancelListingInput, OrdinalOperationResponse> | Skill<PurchaseOrdinalRequest, OrdinalOperationResponse>)[];
 export {};

package/dist/api/ordinals/index.js

@@ -21,6 +21,55 @@ function extractName(customInstructions) {
         return undefined;
     }
 }
+/**
+ * Sign a P2PKH input using the wallet's key derivation.
+ * Returns the unlocking script hex for the input.
+ */
+async function signP2PKHInput(ctx, tx, inputIndex, protocolID, keyID) {
+    const txInput = tx.inputs[inputIndex];
+    const sourceLockingScript = txInput.sourceTransaction?.outputs[txInput.sourceOutputIndex]?.lockingScript;
+    if (!sourceLockingScript) {
+        return { error: `missing-source-locking-script-for-input-${inputIndex}` };
+    }
+    const sourceTXID = txInput.sourceTXID ?? txInput.sourceTransaction?.id("hex");
+    if (!sourceTXID) {
+        return { error: `missing-source-txid-for-input-${inputIndex}` };
+    }
+    const preimage = TransactionSignature.format({
+        sourceTXID,
+        sourceOutputIndex: txInput.sourceOutputIndex,
+        sourceSatoshis: 1,
+        transactionVersion: tx.version,
+        otherInputs: tx.inputs.filter((_, idx) => idx !== inputIndex).map((inp) => ({
+            sourceTXID: inp.sourceTXID ?? inp.sourceTransaction?.id("hex") ?? "",
+            sourceOutputIndex: inp.sourceOutputIndex,
+            sequence: inp.sequence ?? 0xffffffff,
+        })),
+        inputIndex,
+        outputs: tx.outputs,
+        inputSequence: txInput.sequence ?? 0xffffffff,
+        subscript: sourceLockingScript,
+        lockTime: tx.lockTime,
+        scope: TransactionSignature.SIGHASH_ALL | TransactionSignature.SIGHASH_FORKID,
+    });
+    const sighash = Hash.sha256(Hash.sha256(preimage));
+    const { signature } = await ctx.wallet.createSignature({
+        protocolID,
+        keyID,
+        counterparty: "self",
+        hashToDirectlySign: Array.from(sighash),
+    });
+    const { publicKey } = await ctx.wallet.getPublicKey({
+        protocolID,
+        keyID,
+        forSelf: true,
+    });
+    const sigWithHashtype = [...signature, TransactionSignature.SIGHASH_ALL | TransactionSignature.SIGHASH_FORKID];
+    return new UnlockingScript()
+        .writeBin(sigWithHashtype)
+        .writeBin(Utils.toArray(publicKey, "hex"))
+        .toHex();
+}
 // ============================================================================
 // Internal helpers
 // ============================================================================
@@ -95,54 +144,47 @@ async function buildPurchaseUnlockingScript(tx, inputIndex, sourceSatoshis, lock
 // Builder functions (utilities for advanced use)
 // ============================================================================
 /**
- * Build CreateActionArgs for transferring an ordinal.
+ * Build CreateActionArgs for transferring one or more ordinals.
  * Does NOT execute - returns params for createAction.
  */
-export async function buildTransferOrdinal(ctx, request) {
-    const { outpoint, counterparty, address, paymail } = request;
-    if (!counterparty && !address && !paymail) {
-        return { error: "must-provide-counterparty-address-or-paymail" };
-    }
-    let recipientAddress;
-    if (counterparty) {
-        const { publicKey } = await ctx.wallet.getPublicKey({
-            protocolID: ONESAT_PROTOCOL,
-            keyID: outpoint,
-            counterparty,
-            forSelf: false,
-        });
-        recipientAddress = PublicKey.fromString(publicKey).toAddress();
-    }
-    else if (paymail) {
-        return { error: "paymail-not-yet-implemented" };
-    }
-    else {
-        recipientAddress = address;
-    }
-    const result = await ctx.wallet.listOutputs({
-        basket: ORDINALS_BASKET,
-        includeTags: true,
-        includeCustomInstructions: true,
-        include: "locking scripts",
-        limit: 10000,
-    });
-    const sourceOutput = result.outputs.find((o) => o.outpoint === outpoint);
-    if (!sourceOutput) {
-        return { error: "ordinal-not-found" };
+export async function buildTransferOrdinals(ctx, request) {
+    const { transfers, inputBEEF } = request;
+    if (!transfers.length) {
+        return { error: "no-transfers" };
     }
-    // Preserve important tags from source output
-    const tags = [];
-    for (const tag of sourceOutput.tags ?? []) {
-        if (tag.startsWith("type:") || tag.startsWith("origin:") || tag.startsWith("name:")) {
-            tags.push(tag);
+    const inputs = [];
+    const outputs = [];
+    for (const { ordinal, counterparty, address } of transfers) {
+        if (!counterparty && !address) {
+            return { error: "must-provide-counterparty-or-address" };
         }
-    }
-    const sourceName = extractName(sourceOutput.customInstructions);
-    return {
-        description: "Transfer ordinal",
-        inputs: [{ outpoint, inputDescription: "Ordinal to transfer" }],
-        outputs: [
-            {
+        const outpoint = ordinal.outpoint;
+        let recipientAddress;
+        if (counterparty) {
+            const { publicKey } = await ctx.wallet.getPublicKey({
+                protocolID: ONESAT_PROTOCOL,
+                keyID: outpoint,
+                counterparty,
+                forSelf: false,
+            });
+            recipientAddress = PublicKey.fromString(publicKey).toAddress();
+        }
+        else {
+            recipientAddress = address;
+        }
+        // Preserve important tags from source output
+        const tags = [];
+        for (const tag of ordinal.tags ?? []) {
+            if (tag.startsWith("type:") || tag.startsWith("origin:") || tag.startsWith("name:")) {
+                tags.push(tag);
+            }
+        }
+        const sourceName = extractName(ordinal.customInstructions);
+        inputs.push({ outpoint, inputDescription: "Ordinal to transfer", unlockingScriptLength: 108 });
+        // Only track output in wallet when transferring to a counterparty (wallet can derive keys to spend it)
+        // External address transfers are NOT tracked since the wallet cannot spend them
+        if (counterparty) {
+            outputs.push({
                 lockingScript: new P2PKH().lock(recipientAddress).toHex(),
                 satoshis: 1,
                 outputDescription: "Ordinal transfer",
@@ -153,8 +195,22 @@ export async function buildTransferOrdinal(ctx, request) {
                     keyID: outpoint,
                     ...(sourceName && { name: sourceName }),
                 }),
-            },
-        ],
+            });
+        }
+        else {
+            // External address - output is not tracked in wallet
+            outputs.push({
+                lockingScript: new P2PKH().lock(recipientAddress).toHex(),
+                satoshis: 1,
+                outputDescription: "Ordinal transfer to external address",
+            });
+        }
+    }
+    return {
+        description: transfers.length === 1 ? "Transfer ordinal" : `Transfer ${transfers.length} ordinals`,
+        inputBEEF,
+        inputs,
+        outputs,
     };
 }
 /**
@@ -162,27 +218,17 @@ export async function buildTransferOrdinal(ctx, request) {
  * Does NOT execute - returns params for createAction.
  */
 export async function buildListOrdinal(ctx, request) {
-    const { outpoint, price, payAddress } = request;
+    const { ordinal, inputBEEF, price, payAddress } = request;
     if (!payAddress)
         return { error: "missing-pay-address" };
     if (price <= 0)
         return { error: "invalid-price" };
-    const result = await ctx.wallet.listOutputs({
-        basket: ORDINALS_BASKET,
-        includeTags: true,
-        includeCustomInstructions: true,
-        include: "locking scripts",
-        limit: 10000,
-    });
-    const sourceOutput = result.outputs.find((o) => o.outpoint === outpoint);
-    if (!sourceOutput) {
-        return { error: "ordinal-not-found" };
-    }
-    const typeTag = sourceOutput.tags?.find((t) => t.startsWith("type:"));
-    const originTag = sourceOutput.tags?.find((t) => t.startsWith("origin:"));
-    const nameTag = sourceOutput.tags?.find((t) => t.startsWith("name:"));
+    const outpoint = ordinal.outpoint;
+    const typeTag = ordinal.tags?.find((t) => t.startsWith("type:"));
+    const originTag = ordinal.tags?.find((t) => t.startsWith("origin:"));
+    const nameTag = ordinal.tags?.find((t) => t.startsWith("name:"));
     const originOutpoint = originTag ? originTag.slice(7) : outpoint;
-    const sourceName = extractName(sourceOutput.customInstructions);
+    const sourceName = extractName(ordinal.customInstructions);
     const cancelAddress = await deriveCancelAddressInternal(ctx, outpoint);
     const lockingScript = buildOrdLockScript(cancelAddress, payAddress, price);
     const tags = ["ordlock", `origin:${originOutpoint}`, `price:${price}`];
@@ -192,7 +238,8 @@ export async function buildListOrdinal(ctx, request) {
         tags.push(nameTag);
     return {
         description: `List ordinal for ${price} sats`,
-        inputs: [{ outpoint, inputDescription: "Ordinal to list" }],
+        inputBEEF,
+        inputs: [{ outpoint, inputDescription: "Ordinal to list", unlockingScriptLength: 108 }],
         outputs: [
             {
                 lockingScript: lockingScript.toHex(),
@@ -259,36 +306,71 @@ export const deriveCancelAddress = {
 /**
  * Transfer an ordinal to a new owner.
  */
-export const transferOrdinal = {
+export const transferOrdinals = {
     meta: {
-        name: "transferOrdinal",
-        description: "Transfer an ordinal to a new owner via counterparty pubkey, address, or paymail",
+        name: "transferOrdinals",
+        description: "Transfer one or more ordinals to new owners",
         category: "ordinals",
         inputSchema: {
             type: "object",
             properties: {
-                outpoint: { type: "string", description: "Outpoint of the ordinal (txid_vout format)" },
-                counterparty: { type: "string", description: "Recipient identity public key (hex)" },
-                address: { type: "string", description: "Recipient P2PKH address" },
-                paymail: { type: "string", description: "Recipient paymail address" },
+                transfers: {
+                    type: "array",
+                    description: "Ordinals to transfer with destinations",
+                    items: {
+                        type: "object",
+                        properties: {
+                            ordinal: { type: "object", description: "WalletOutput from listOutputs" },
+                            counterparty: { type: "string", description: "Recipient identity public key (hex)" },
+                            address: { type: "string", description: "Recipient P2PKH address" },
+                        },
+                        required: ["ordinal"],
+                    },
+                },
+                inputBEEF: { type: "array", description: "BEEF from listOutputs with include: 'entire transactions'" },
             },
-            required: ["outpoint"],
+            required: ["transfers", "inputBEEF"],
         },
     },
     async execute(ctx, input) {
         try {
-            const params = await buildTransferOrdinal(ctx, input);
+            const params = await buildTransferOrdinals(ctx, input);
             if ("error" in params) {
                 return params;
             }
-            const result = await ctx.wallet.createAction({
+            const createResult = await ctx.wallet.createAction({
                 ...params,
-                options: { randomizeOutputs: false },
+                options: { signAndProcess: false, randomizeOutputs: false },
             });
-            if (!result.txid) {
-                return { error: "no-txid-returned" };
+            if (!createResult.signableTransaction) {
+                return { error: "no-signable-transaction" };
             }
-            return { txid: result.txid, rawtx: result.tx ? Utils.toHex(result.tx) : undefined };
+            const tx = Transaction.fromBEEF(createResult.signableTransaction.tx);
+            const spends = {};
+            for (let i = 0; i < input.transfers.length; i++) {
+                const { ordinal } = input.transfers[i];
+                console.log(`[transferOrdinals] Input ${i}: outpoint=${ordinal.outpoint}, customInstructions=${ordinal.customInstructions}`);
+                if (!ordinal.customInstructions) {
+                    return { error: `missing-custom-instructions-for-${ordinal.outpoint}` };
+                }
+                const { protocolID, keyID } = JSON.parse(ordinal.customInstructions);
+                console.log(`[transferOrdinals] Input ${i}: protocolID=${JSON.stringify(protocolID)}, keyID=${keyID}`);
+                const unlocking = await signP2PKHInput(ctx, tx, i, protocolID, keyID);
+                if (typeof unlocking !== "string")
+                    return unlocking;
+                spends[i] = { unlockingScript: unlocking };
+            }
+            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" };
@@ -306,11 +388,12 @@ export const listOrdinal = {
         inputSchema: {
             type: "object",
             properties: {
-                outpoint: { type: "string", description: "Outpoint of the ordinal to list" },
+                ordinal: { type: "object", description: "WalletOutput from listOutputs" },
+                inputBEEF: { type: "array", description: "BEEF from listOutputs with include: 'entire transactions'" },
                 price: { type: "integer", description: "Price in satoshis" },
                 payAddress: { type: "string", description: "Address to receive payment on purchase" },
             },
-            required: ["outpoint", "price", "payAddress"],
+            required: ["ordinal", "inputBEEF", "price", "payAddress"],
         },
     },
     async execute(ctx, input) {
@@ -319,14 +402,32 @@ export const listOrdinal = {
             if ("error" in params) {
                 return params;
             }
-            const result = await ctx.wallet.createAction({
+            const createResult = await ctx.wallet.createAction({
                 ...params,
-                options: { randomizeOutputs: false },
+                options: { signAndProcess: false, randomizeOutputs: false },
+            });
+            if (!createResult.signableTransaction) {
+                return { error: "no-signable-transaction" };
+            }
+            if (!input.ordinal.customInstructions) {
+                return { error: "missing-custom-instructions" };
+            }
+            const { protocolID, keyID } = JSON.parse(input.ordinal.customInstructions);
+            const tx = Transaction.fromBEEF(createResult.signableTransaction.tx);
+            const unlocking = await signP2PKHInput(ctx, tx, 0, protocolID, keyID);
+            if (typeof unlocking !== "string")
+                return unlocking;
+            const signResult = await ctx.wallet.signAction({
+                reference: createResult.signableTransaction.reference,
+                spends: { 0: { unlockingScript: unlocking } },
             });
-            if (!result.txid) {
-                return { error: "no-txid-returned" };
+            if ("error" in signResult) {
+                return { error: String(signResult.error) };
             }
-            return { txid: result.txid, rawtx: result.tx ? Utils.toHex(result.tx) : undefined };
+            return {
+                txid: signResult.txid,
+                rawtx: signResult.tx ? Utils.toHex(signResult.tx) : undefined,
+            };
         }
         catch (error) {
             return { error: error instanceof Error ? error.message : "unknown-error" };
@@ -344,25 +445,16 @@ export const cancelListing = {
         inputSchema: {
             type: "object",
             properties: {
-                outpoint: { type: "string", description: "Outpoint of the listing to cancel" },
+                listing: { type: "object", description: "WalletOutput of the listing (must include lockingScript)" },
+                inputBEEF: { type: "array", description: "BEEF from listOutputs with include: 'entire transactions'" },
             },
-            required: ["outpoint"],
+            required: ["listing", "inputBEEF"],
         },
     },
     async execute(ctx, input) {
         try {
-            const { outpoint } = input;
-            const result = await ctx.wallet.listOutputs({
-                basket: ORDINALS_BASKET,
-                includeTags: true,
-                includeCustomInstructions: true,
-                include: "locking scripts",
-                limit: 10000,
-            });
-            const listing = result.outputs.find((o) => o.outpoint === outpoint);
-            if (!listing) {
-                return { error: "listing-not-found" };
-            }
+            const { listing, inputBEEF } = input;
+            const outpoint = listing.outpoint;
             if (!listing.customInstructions) {
                 return { error: "missing-custom-instructions" };
             }
@@ -380,6 +472,7 @@ export const cancelListing = {
                 tags.push(nameTag);
             const createResult = await ctx.wallet.createAction({
                 description: "Cancel ordinal listing",
+                inputBEEF,
                 inputs: [
                     {
                         outpoint,
@@ -407,7 +500,10 @@ export const cancelListing = {
             }
             const tx = Transaction.fromBEEF(createResult.signableTransaction.tx);
             const txInput = tx.inputs[0];
-            const lockingScript = Script.fromHex(listing.lockingScript);
+            const lockingScript = txInput.sourceTransaction?.outputs[txInput.sourceOutputIndex]?.lockingScript;
+            if (!lockingScript) {
+                return { error: "missing-locking-script" };
+            }
             const sourceTXID = txInput.sourceTXID ?? txInput.sourceTransaction?.id("hex");
             if (!sourceTXID) {
                 return { error: "missing-source-txid" };
@@ -612,7 +708,7 @@ export const purchaseOrdinal = {
 export const ordinalsSkills = [
     listOrdinals,
     deriveCancelAddress,
-    transferOrdinal,
+    transferOrdinals,
     listOrdinal,
     cancelListing,
     purchaseOrdinal,

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

@@ -5,7 +5,7 @@
  */
 import type { OneSatContext, Skill } from "../skills/types";
 import type { IndexedOutput } from "../../services/types";
-import type { SweepBsvRequest, SweepBsvResponse, SweepInput, SweepOrdinalsRequest, SweepOrdinalsResponse } from "./types";
+import type { SweepBsvRequest, SweepBsvResponse, SweepInput, SweepOrdinalsRequest, SweepOrdinalsResponse, SweepBsv21Request, SweepBsv21Response } from "./types";
 export * from "./types";
 /**
  * Prepare sweep inputs from IndexedOutput objects by fetching locking scripts.
@@ -27,4 +27,11 @@ export declare const sweepBsv: Skill<SweepBsvRequest, SweepBsvResponse>;
  * transferred to a derived address using the wallet's key derivation.
  */
 export declare const sweepOrdinals: Skill<SweepOrdinalsRequest, SweepOrdinalsResponse>;
-export declare const sweepSkills: (Skill<SweepBsvRequest, SweepBsvResponse> | Skill<SweepOrdinalsRequest, SweepOrdinalsResponse>)[];
+/**
+ * Sweep BSV-21 tokens from external inputs into the destination wallet.
+ *
+ * Consolidates all token inputs into a single output. All inputs must be
+ * for the same tokenId. Creates a fee output to the overlay fund address.
+ */
+export declare const sweepBsv21: Skill<SweepBsv21Request, SweepBsv21Response>;
+export declare const sweepSkills: (Skill<SweepBsvRequest, SweepBsvResponse> | Skill<SweepOrdinalsRequest, SweepOrdinalsResponse> | Skill<SweepBsv21Request, SweepBsv21Response>)[];

package/dist/api/sweep/index.js

@@ -4,7 +4,9 @@
  * Functions for sweeping assets from external wallets into a BRC-100 wallet.
  */
 import { P2PKH, PrivateKey, PublicKey, Transaction, } from "@bsv/sdk";
-import { ONESAT_PROTOCOL } from "../constants";
+import { BSV21 } from "@bopen-io/templates";
+import { ONESAT_PROTOCOL, BSV21_PROTOCOL, BSV21_FEE_SATS, BSV21_BASKET } from "../constants";
+import { deriveFundAddress } from "../../indexers";
 export * from "./types";
 /**
  * Prepare sweep inputs from IndexedOutput objects by fetching locking scripts.
@@ -308,17 +310,19 @@ export const sweepOrdinals = {
                     tags.push(`type:${input.contentType}`);
                 if (input.origin)
                     tags.push(`origin:${input.origin}`);
+                const customInstructions = JSON.stringify({
+                    protocolID: ONESAT_PROTOCOL,
+                    keyID: input.outpoint,
+                    ...(input.name && { name: input.name.slice(0, 64) }),
+                });
+                console.log(`[sweepOrdinals] Output for ${input.outpoint}: keyID=${input.outpoint}, customInstructions=${customInstructions}`);
                 outputs.push({
                     lockingScript: lockingScript.toHex(),
                     satoshis: 1,
                     outputDescription: `Ordinal ${input.origin ?? input.outpoint}`,
                     basket: "1sat",
                     tags,
-                    customInstructions: JSON.stringify({
-                        protocolID: ONESAT_PROTOCOL,
-                        keyID: input.outpoint,
-                        ...(input.name && { name: input.name.slice(0, 64) }),
-                    }),
+                    customInstructions,
                 });
             }
             const beefData = firstBeef.toBinary();
@@ -383,5 +387,177 @@ export const sweepOrdinals = {
         }
     },
 };
+/**
+ * Sweep BSV-21 tokens from external inputs into the destination wallet.
+ *
+ * Consolidates all token inputs into a single output. All inputs must be
+ * for the same tokenId. Creates a fee output to the overlay fund address.
+ */
+export const sweepBsv21 = {
+    meta: {
+        name: "sweepBsv21",
+        description: "Sweep BSV-21 tokens from external wallet (via WIF) into the connected wallet",
+        category: "sweep",
+        requiresServices: true,
+        inputSchema: {
+            type: "object",
+            properties: {
+                inputs: {
+                    type: "array",
+                    description: "Token UTXOs to sweep (must all be same tokenId)",
+                    items: {
+                        type: "object",
+                        properties: {
+                            outpoint: { type: "string", description: "Outpoint (txid_vout)" },
+                            satoshis: { type: "integer", description: "Satoshis (should be 1)" },
+                            lockingScript: { type: "string", description: "Locking script hex" },
+                            tokenId: { type: "string", description: "Token ID (txid_vout format)" },
+                            amount: { type: "string", description: "Token amount as string" },
+                        },
+                        required: ["outpoint", "satoshis", "lockingScript", "tokenId", "amount"],
+                    },
+                },
+                wif: {
+                    type: "string",
+                    description: "WIF private key controlling the inputs",
+                },
+            },
+            required: ["inputs", "wif"],
+        },
+    },
+    async execute(ctx, request) {
+        if (!ctx.services) {
+            return { error: "services-required" };
+        }
+        try {
+            const { inputs, wif } = request;
+            if (!inputs || inputs.length === 0) {
+                return { error: "no-inputs" };
+            }
+            // Validate all inputs have the same tokenId
+            const tokenId = inputs[0].tokenId;
+            if (!inputs.every((i) => i.tokenId === tokenId)) {
+                return { error: "mixed-token-ids" };
+            }
+            // Parse WIF
+            const privateKey = PrivateKey.fromWif(wif);
+            // Sum all input amounts
+            const totalAmount = inputs.reduce((sum, i) => sum + BigInt(i.amount), 0n);
+            if (totalAmount <= 0n) {
+                return { error: "no-token-amount" };
+            }
+            // Fetch BEEF for all input transactions and merge them
+            const txids = [...new Set(inputs.map((i) => i.outpoint.split("_")[0]))];
+            console.log(`[sweepBsv21] Fetching BEEF for ${txids.length} transactions`);
+            const firstBeef = await ctx.services.getBeefForTxid(txids[0]);
+            for (let i = 1; i < txids.length; i++) {
+                const additionalBeef = await ctx.services.getBeefForTxid(txids[i]);
+                firstBeef.mergeBeef(additionalBeef);
+            }
+            console.log(`[sweepBsv21] Merged BEEF valid=${firstBeef.isValid()}, txs=${firstBeef.txs.length}`);
+            // Build input descriptors
+            const inputDescriptors = inputs.map((input) => {
+                const [txid, voutStr] = input.outpoint.split("_");
+                return {
+                    outpoint: `${txid}.${voutStr}`,
+                    inputDescription: `Token input ${input.outpoint}`,
+                    unlockingScriptLength: 108,
+                    sequenceNumber: 0xffffffff,
+                };
+            });
+            // Build outputs
+            const outputs = [];
+            // 1. Token output (1 sat) - derive key for this token
+            const keyID = `${tokenId}-${Date.now()}`;
+            const pubKeyResult = await ctx.wallet.getPublicKey({
+                protocolID: BSV21_PROTOCOL,
+                keyID,
+                forSelf: true,
+            });
+            if (!pubKeyResult.publicKey) {
+                return { error: "failed-to-derive-key" };
+            }
+            const derivedAddress = PublicKey.fromString(pubKeyResult.publicKey).toAddress();
+            const p2pkh = new P2PKH();
+            const destinationLockingScript = p2pkh.lock(derivedAddress);
+            const transferScript = BSV21.transfer(tokenId, totalAmount).lock(destinationLockingScript);
+            outputs.push({
+                lockingScript: transferScript.toHex(),
+                satoshis: 1,
+                outputDescription: `Sweep ${totalAmount} tokens`,
+                basket: BSV21_BASKET,
+                tags: [`id:${tokenId}`, `amt:${totalAmount}`],
+                customInstructions: JSON.stringify({
+                    protocolID: BSV21_PROTOCOL,
+                    keyID,
+                }),
+            });
+            // 2. Fee output (1000 sats) to overlay fund address
+            const fundAddress = deriveFundAddress(tokenId);
+            outputs.push({
+                lockingScript: p2pkh.lock(fundAddress).toHex(),
+                satoshis: BSV21_FEE_SATS,
+                outputDescription: "Overlay processing fee",
+            });
+            const beefData = firstBeef.toBinary();
+            // Create action to get signable transaction
+            const createResult = await ctx.wallet.createAction({
+                description: `Sweep ${inputs.length} token UTXO${inputs.length !== 1 ? "s" : ""}`,
+                inputBEEF: beefData,
+                inputs: inputDescriptors,
+                outputs,
+                options: { signAndProcess: false, randomizeOutputs: false },
+            });
+            if ("error" in createResult && createResult.error) {
+                return { error: String(createResult.error) };
+            }
+            if (!createResult.signableTransaction) {
+                return { error: "no-signable-transaction" };
+            }
+            // Sign each input with our external key
+            const tx = Transaction.fromBEEF(createResult.signableTransaction.tx);
+            // Build a set of outpoints we control
+            const ourOutpoints = new Set(inputs.map((input) => {
+                const [txid, vout] = input.outpoint.split("_");
+                return `${txid}.${vout}`;
+            }));
+            // Set up P2PKH unlocker on each input we control
+            for (let i = 0; i < tx.inputs.length; i++) {
+                const txInput = tx.inputs[i];
+                const inputOutpoint = `${txInput.sourceTXID}.${txInput.sourceOutputIndex}`;
+                if (ourOutpoints.has(inputOutpoint)) {
+                    txInput.unlockingScriptTemplate = p2pkh.unlock(privateKey, "all", true);
+                }
+            }
+            await tx.sign();
+            // Extract unlocking scripts for signAction
+            const spends = {};
+            for (let i = 0; i < tx.inputs.length; i++) {
+                const txInput = tx.inputs[i];
+                const inputOutpoint = `${txInput.sourceTXID}.${txInput.sourceOutputIndex}`;
+                if (ourOutpoints.has(inputOutpoint)) {
+                    spends[i] = { unlockingScript: txInput.unlockingScript?.toHex() ?? "" };
+                }
+            }
+            // Complete the action with our signatures
+            const signResult = await ctx.wallet.signAction({
+                reference: createResult.signableTransaction.reference,
+                spends,
+            });
+            if ("error" in signResult) {
+                return { error: String(signResult.error) };
+            }
+            return {
+                txid: signResult.txid,
+                beef: signResult.tx ? Array.from(signResult.tx) : undefined,
+            };
+        }
+        catch (error) {
+            return {
+                error: error instanceof Error ? error.message : "unknown-error",
+            };
+        }
+    },
+};
 // Export skills array for registry
-export const sweepSkills = [sweepBsv, sweepOrdinals];
+export const sweepSkills = [sweepBsv, sweepOrdinals, sweepBsv21];

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

@@ -53,3 +53,26 @@ export interface SweepOrdinalsResponse {
     /** Error message if failed */
     error?: string;
 }
+/** Input for BSV-21 token sweep operations */
+export interface SweepBsv21Input extends SweepInput {
+    /** Token ID (txid_vout format) */
+    tokenId: string;
+    /** Token amount as string (bigint serialization) */
+    amount: string;
+}
+/** Request to sweep BSV-21 tokens */
+export interface SweepBsv21Request {
+    /** Token UTXOs to sweep (must all be same tokenId) */
+    inputs: SweepBsv21Input[];
+    /** WIF private key controlling the inputs */
+    wif: string;
+}
+/** Response from BSV-21 token sweep operation */
+export interface SweepBsv21Response {
+    /** Transaction ID if successful */
+    txid?: string;
+    /** BEEF (transaction with validity proof) */
+    beef?: number[];
+    /** Error message if failed */
+    error?: string;
+}

package/dist/api/tokens/index.js

@@ -5,11 +5,8 @@
  */
 import { BigNumber, LockingScript, OP, P2PKH, PublicKey, Transaction, TransactionSignature, UnlockingScript, Utils, } from "@bsv/sdk";
 import { BSV21, OrdLock } from "@bopen-io/templates";
-import { BSV21_BASKET } from "../constants";
-// ============================================================================
-// Constants
-// ============================================================================
-const BSV21_PROTOCOL = [1, "bsv21"];
+import { BSV21_BASKET, BSV21_PROTOCOL, BSV21_FEE_SATS } from "../constants";
+import { deriveFundAddress } from "../../indexers";
 // ============================================================================
 // Internal helpers
 // ============================================================================
@@ -256,6 +253,13 @@ export const sendBsv21 = {
                 satoshis: 1,
                 outputDescription: `Send ${amount} tokens`,
             });
+            // Fee output to overlay fund address
+            const fundAddress = deriveFundAddress(tokenId);
+            outputs.push({
+                lockingScript: p2pkh.lock(fundAddress).toHex(),
+                satoshis: BSV21_FEE_SATS,
+                outputDescription: "Overlay processing fee",
+            });
             const change = totalIn - amount;
             if (change > 0n) {
                 const changeKeyID = `${tokenId}-${Date.now()}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1sat/wallet-toolbox",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "description": "BSV wallet library extending @bsv/wallet-toolbox with 1Sat Ordinals protocol support",
   "author": "1Sat Team",
   "license": "MIT",