bsv-mcp 0.2.14 → 0.3.0

package/tools/wallet/setupDroplit.ts

@@ -0,0 +1,157 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import {
+	createErrorResponse,
+	createSuccessResponse,
+} from "../utils/errorHandler";
+import type { IntegratedWallet } from "./integratedWallet";
+
+/**
+ * Droplit setup and faucet administration.
+ *
+ * These were one tool behind an `action` enum, which made every argument
+ * conditional on the action and left the caller to work out which combination
+ * was valid. They are three tools now, each declaring only what it needs.
+ */
+
+type DroplitClient = NonNullable<
+	ReturnType<IntegratedWallet["getDroplitClient"]>
+>;
+
+/**
+ * Every Droplit call needs a configured client and every write needs the
+ * signing key, so resolve both up front rather than failing part-way through a
+ * request with a different message depending on which tool was called.
+ */
+function requireDroplit(integratedWallet: IntegratedWallet): {
+	apiUrl: string;
+	publicKeyHex: string;
+	client: DroplitClient;
+} {
+	const client = integratedWallet.getDroplitClient();
+	if (!client) {
+		throw new Error(
+			"Droplit client is not configured. Set DROPLIT_API_URL and DROPLIT_FAUCET_NAME.",
+		);
+	}
+
+	const { apiUrl, authKey } = client.getConfig();
+	if (!authKey) {
+		throw new Error(
+			"Droplit requests must be signed, but no auth key is configured.",
+		);
+	}
+
+	return { apiUrl, publicKeyHex: authKey.toPublicKey().toString(), client };
+}
+
+async function failIfNotOk(
+	response: Response,
+	attempted: string,
+): Promise<void> {
+	if (response.ok) return;
+	throw new Error(
+		`${attempted} failed (${response.status}): ${await response.text()}`,
+	);
+}
+
+export function registerSetupDroplitTools(
+	server: McpServer,
+	integratedWallet: IntegratedWallet,
+) {
+	server.tool(
+		"wallet_registerDroplitKey",
+		"Registers this wallet's public key with the Droplit API so it can sign authenticated faucet requests. Run once before creating or operating a faucet.",
+		{},
+		async () => {
+			try {
+				const { apiUrl, publicKeyHex } = requireDroplit(integratedWallet);
+
+				const response = await fetch(`${apiUrl}/auth/register`, {
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify({ publicKey: publicKeyHex }),
+				});
+				await failIfNotOk(response, "Registering the Droplit key");
+
+				return createSuccessResponse({
+					message: "Public key registered with Droplit",
+					publicKey: publicKeyHex,
+				});
+			} catch (error) {
+				return createErrorResponse(error);
+			}
+		},
+	);
+
+	server.tool(
+		"wallet_createDroplitFaucet",
+		"Provisions a new Droplit faucet owned by this wallet. Register the wallet's public key first with wallet_registerDroplitKey.",
+		{
+			faucetName: z
+				.string()
+				.min(1)
+				.describe("Identifier for the new faucet; must be unique"),
+			fixedDropSats: z
+				.number()
+				.int()
+				.positive()
+				.optional()
+				.describe(
+					"Satoshis paid out per tap. Server default applies if unset.",
+				),
+			maxConsolidationInputs: z
+				.number()
+				.int()
+				.positive()
+				.optional()
+				.describe("Cap on inputs the faucet consolidates in one transaction"),
+		},
+		async ({ faucetName, fixedDropSats, maxConsolidationInputs }) => {
+			try {
+				const { client } = requireDroplit(integratedWallet);
+
+				// Ownership comes from the BRC-103/104 identity established by the
+				// handshake, not from the body, so the key is never sent here.
+				const body = {
+					name: faucetName,
+					...(fixedDropSats !== undefined && {
+						fixed_drop_sats: fixedDropSats,
+					}),
+					...(maxConsolidationInputs !== undefined && {
+						max_consolidation_inputs: maxConsolidationInputs,
+					}),
+				};
+
+				const response = await client.authenticatedFetch("/faucets", {
+					method: "POST",
+					body,
+				});
+				await failIfNotOk(response, "Creating the Droplit faucet");
+
+				return createSuccessResponse({
+					message: "Faucet created",
+					faucet: await response.json(),
+				});
+			} catch (error) {
+				return createErrorResponse(error);
+			}
+		},
+	);
+
+	server.tool(
+		"wallet_checkDroplitFaucetStatus",
+		"Reads the status of the configured Droplit faucet, including balance and payout settings.",
+		{},
+		async () => {
+			try {
+				const { client } = requireDroplit(integratedWallet);
+				return createSuccessResponse({
+					faucetStatus: await client.getFaucetStatus(),
+				});
+			} catch (error) {
+				return createErrorResponse(error);
+			}
+		},
+	);
+}

package/tools/wallet/signBsm.ts

@@ -1,29 +1,29 @@
-import { signBsm, type OneSatContext } from '@1sat/actions'
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { z } from 'zod'
+import { type OneSatContext, signBsm } from "@1sat/actions";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
 
-export function registerSignBsmTool(
-	server: McpServer,
-	ctx?: OneSatContext,
-) {
+export function registerSignBsmTool(server: McpServer, ctx?: OneSatContext) {
 	server.tool(
-		'wallet_signBsm',
-		'Sign a message using BSM (Bitcoin Signed Message) format',
+		"wallet_signBsm",
+		"Sign a message using BSM (Bitcoin Signed Message) format",
 		{
-			message: z.string().describe('The message to sign'),
-			encoding: z.enum(['utf8', 'hex', 'base64']).optional().describe('Message encoding format'),
+			message: z.string().describe("The message to sign"),
+			encoding: z
+				.enum(["utf8", "hex", "base64"])
+				.optional()
+				.describe("Message encoding format"),
 		},
 		async (params) => {
 			try {
-				if (!ctx) throw new Error('BRC-100 wallet context not available')
-				const result = await signBsm.execute(ctx, params)
+				if (!ctx) throw new Error("BRC-100 wallet context not available");
+				const result = await signBsm.execute(ctx, params);
 				return {
-					content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-				}
+					content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+				};
 			} catch (err: unknown) {
-				const msg = err instanceof Error ? err.message : String(err)
-				return { content: [{ type: 'text', text: msg }], isError: true }
+				const msg = err instanceof Error ? err.message : String(err);
+				return { content: [{ type: "text", text: msg }], isError: true };
 			}
 		},
-	)
+	);
 }

package/tools/wallet/sweepBsv.ts

@@ -1,70 +1,91 @@
-import type { OneSatContext } from '@1sat/actions'
-import { sweepBsv } from '@1sat/actions'
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { z } from 'zod'
+import type { OneSatContext } from "@1sat/actions";
+import { sweepBsv } from "@1sat/actions";
+import { PrivateKey } from "@bsv/sdk";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { assertBroadcastAllowed } from "../../utils/broadcastGuard";
+import { redactKeyMaterial, redactUnknown } from "../../utils/redact";
 
 const sweepInputSchema = z.object({
-	outpoint: z.string().describe('Outpoint (txid_vout)'),
-	satoshis: z.number().int().describe('Satoshis in output'),
-	lockingScript: z.string().describe('Locking script hex'),
-})
+	outpoint: z.string().describe("Outpoint (txid_vout)"),
+	satoshis: z.number().int().describe("Satoshis in output"),
+	lockingScript: z.string().describe("Locking script hex"),
+});
 
 const sweepBsvSchema = z.object({
-	inputs: z.array(sweepInputSchema).describe('UTXOs to sweep (use prepareSweepInputs to build these)'),
-	wif: z.string().describe('WIF private key controlling the inputs'),
-	amount: z.number().int().optional().describe('Amount to sweep (satoshis). If omitted, sweeps all input value.'),
-})
+	inputs: z
+		.array(sweepInputSchema)
+		.describe("UTXOs to sweep (use prepareSweepInputs to build these)"),
+	wif: z.string().describe("WIF private key controlling the inputs"),
+	amount: z
+		.number()
+		.int()
+		.optional()
+		.describe(
+			"Amount to sweep (satoshis). If omitted, sweeps all input value.",
+		),
+});
 
 export function registerSweepBsvTool(
 	server: McpServer,
 	ctx: OneSatContext | undefined,
 ) {
 	server.tool(
-		'wallet_sweepBsv',
-		'Sweep BSV from an external WIF private key into the wallet',
+		"wallet_sweepBsv",
+		"Sweep BSV from an external WIF private key into the wallet",
 		{ ...sweepBsvSchema.shape },
 		async ({ inputs, wif, amount }) => {
 			if (!ctx) {
 				return {
 					content: [
 						{
-							type: 'text' as const,
-							text: 'BRC-100 wallet context not available',
+							type: "text" as const,
+							text: "BRC-100 wallet context not available",
 						},
 					],
 					isError: true,
-				}
+				};
 			}
 
 			try {
-				const result = await sweepBsv.execute(ctx, { inputs, wif, amount })
+				assertBroadcastAllowed("wallet_sweepBsv");
+				const key = PrivateKey.fromWif(wif);
+				const result = await sweepBsv.execute(ctx, {
+					inputs,
+					keys: inputs.map(() => key),
+					amount,
+				});
 
 				if (result.error) {
 					return {
-						content: [{ type: 'text' as const, text: result.error }],
+						content: [
+							{ type: "text" as const, text: redactKeyMaterial(result.error) },
+						],
 						isError: true,
-					}
+					};
 				}
 
 				return {
 					content: [
 						{
-							type: 'text' as const,
-							text: JSON.stringify(result, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2),
+							type: "text" as const,
+							text: redactUnknown(result, 2),
 						},
 					],
-				}
+				};
 			} catch (error) {
 				return {
 					content: [
 						{
-							type: 'text' as const,
-							text: error instanceof Error ? error.message : String(error),
+							type: "text" as const,
+							text: redactKeyMaterial(
+								error instanceof Error ? error.message : String(error),
+							),
 						},
 					],
 					isError: true,
-				}
+				};
 			}
 		},
-	)
+	);
 }

package/tools/wallet/sweepBsv21.ts

@@ -1,71 +1,85 @@
-import type { OneSatContext } from '@1sat/actions'
-import { sweepBsv21 } from '@1sat/actions'
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { z } from 'zod'
+import type { OneSatContext } from "@1sat/actions";
+import { sweepBsv21 } from "@1sat/actions";
+import { PrivateKey } from "@bsv/sdk";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { assertBroadcastAllowed } from "../../utils/broadcastGuard";
+import { redactKeyMaterial, redactUnknown } from "../../utils/redact";
 
 const sweepBsv21InputSchema = z.object({
-	outpoint: z.string().describe('Outpoint (txid_vout)'),
-	satoshis: z.number().int().describe('Satoshis (should be 1)'),
-	lockingScript: z.string().describe('Locking script hex'),
-	tokenId: z.string().describe('Token ID (txid_vout format)'),
-	amount: z.string().describe('Token amount as string'),
-})
+	outpoint: z.string().describe("Outpoint (txid_vout)"),
+	satoshis: z.number().int().describe("Satoshis (should be 1)"),
+	lockingScript: z.string().describe("Locking script hex"),
+	tokenId: z.string().describe("Token ID (txid_vout format)"),
+	amount: z.string().describe("Token amount as string"),
+});
 
 const sweepBsv21Schema = z.object({
-	inputs: z.array(sweepBsv21InputSchema).describe('Token UTXOs to sweep (must all be same tokenId)'),
-	wif: z.string().describe('WIF private key controlling the inputs'),
-})
+	inputs: z
+		.array(sweepBsv21InputSchema)
+		.describe("Token UTXOs to sweep (must all be same tokenId)"),
+	wif: z.string().describe("WIF private key controlling the inputs"),
+});
 
 export function registerSweepBsv21Tool(
 	server: McpServer,
 	ctx: OneSatContext | undefined,
 ) {
 	server.tool(
-		'wallet_sweepBsv21',
-		'Sweep BSV21 tokens from an external WIF private key into the wallet',
+		"wallet_sweepBsv21",
+		"Sweep BSV21 tokens from an external WIF private key into the wallet",
 		{ ...sweepBsv21Schema.shape },
 		async ({ inputs, wif }) => {
 			if (!ctx) {
 				return {
 					content: [
 						{
-							type: 'text' as const,
-							text: 'BRC-100 wallet context not available',
+							type: "text" as const,
+							text: "BRC-100 wallet context not available",
 						},
 					],
 					isError: true,
-				}
+				};
 			}
 
 			try {
-				const result = await sweepBsv21.execute(ctx, { inputs, wif })
+				assertBroadcastAllowed("wallet_sweepBsv21");
+				const key = PrivateKey.fromWif(wif);
+				const result = await sweepBsv21.execute(ctx, {
+					inputs,
+					keys: inputs.map(() => key),
+				});
 
 				if (result.error) {
 					return {
-						content: [{ type: 'text' as const, text: result.error }],
+						content: [
+							{ type: "text" as const, text: redactKeyMaterial(result.error) },
+						],
 						isError: true,
-					}
+					};
 				}
 
 				return {
 					content: [
 						{
-							type: 'text' as const,
-							text: JSON.stringify(result, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2),
+							type: "text" as const,
+							text: redactUnknown(result, 2),
 						},
 					],
-				}
+				};
 			} catch (error) {
 				return {
 					content: [
 						{
-							type: 'text' as const,
-							text: error instanceof Error ? error.message : String(error),
+							type: "text" as const,
+							text: redactKeyMaterial(
+								error instanceof Error ? error.message : String(error),
+							),
 						},
 					],
 					isError: true,
-				}
+				};
 			}
 		},
-	)
+	);
 }

package/tools/wallet/sweepOrdinals.ts

@@ -1,69 +1,81 @@
-import type { OneSatContext } from '@1sat/actions'
-import { sweepOrdinals } from '@1sat/actions'
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { z } from 'zod'
+import type { OneSatContext } from "@1sat/actions";
+import { sweepOrdinals } from "@1sat/actions";
+import { PrivateKey } from "@bsv/sdk";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { assertBroadcastAllowed } from "../../utils/broadcastGuard";
+import { redactKeyMaterial, redactUnknown } from "../../utils/redact";
 
 const sweepInputSchema = z.object({
-	outpoint: z.string().describe('Outpoint (txid_vout)'),
-	satoshis: z.number().int().describe('Satoshis (should be 1)'),
-	lockingScript: z.string().describe('Locking script hex'),
-})
+	outpoint: z.string().describe("Outpoint (txid_vout)"),
+	satoshis: z.number().int().describe("Satoshis (should be 1)"),
+	lockingScript: z.string().describe("Locking script hex"),
+});
 
 const sweepOrdinalsSchema = z.object({
-	inputs: z.array(sweepInputSchema).describe('Ordinal UTXOs to sweep'),
-	wif: z.string().describe('WIF private key controlling the inputs'),
-})
+	inputs: z.array(sweepInputSchema).describe("Ordinal UTXOs to sweep"),
+	wif: z.string().describe("WIF private key controlling the inputs"),
+});
 
 export function registerSweepOrdinalsTool(
 	server: McpServer,
 	ctx: OneSatContext | undefined,
 ) {
 	server.tool(
-		'wallet_sweepOrdinals',
-		'Sweep ordinals from an external WIF private key into the wallet',
+		"wallet_sweepOrdinals",
+		"Sweep ordinals from an external WIF private key into the wallet",
 		{ ...sweepOrdinalsSchema.shape },
 		async ({ inputs, wif }) => {
 			if (!ctx) {
 				return {
 					content: [
 						{
-							type: 'text' as const,
-							text: 'BRC-100 wallet context not available',
+							type: "text" as const,
+							text: "BRC-100 wallet context not available",
 						},
 					],
 					isError: true,
-				}
+				};
 			}
 
 			try {
-				const result = await sweepOrdinals.execute(ctx, { inputs, wif })
+				assertBroadcastAllowed("wallet_sweepOrdinals");
+				const key = PrivateKey.fromWif(wif);
+				const result = await sweepOrdinals.execute(ctx, {
+					inputs,
+					keys: inputs.map(() => key),
+				});
 
 				if (result.error) {
 					return {
-						content: [{ type: 'text' as const, text: result.error }],
+						content: [
+							{ type: "text" as const, text: redactKeyMaterial(result.error) },
+						],
 						isError: true,
-					}
+					};
 				}
 
 				return {
 					content: [
 						{
-							type: 'text' as const,
-							text: JSON.stringify(result, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2),
+							type: "text" as const,
+							text: redactUnknown(result, 2),
 						},
 					],
-				}
+				};
 			} catch (error) {
 				return {
 					content: [
 						{
-							type: 'text' as const,
-							text: error instanceof Error ? error.message : String(error),
+							type: "text" as const,
+							text: redactKeyMaterial(
+								error instanceof Error ? error.message : String(error),
+							),
 						},
 					],
 					isError: true,
-				}
+				};
 			}
 		},
-	)
+	);
 }

package/tools/wallet/tools.ts

@@ -3,6 +3,7 @@ import type { PrivateKey } from "@bsv/sdk";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerA2bPublishMcpTool } from "./a2bPublishMcp";
 import { registerBrc100Tools } from "./brc100";
+import { registerCancelListingTool } from "./cancelListing";
 import { registerCreateOrdinalsTool } from "./createOrdinals";
 import { registerGatherCollectionInfoTool } from "./gatherCollectionInfo";
 import { registerGetAddressTool } from "./getAddress";
@@ -10,23 +11,22 @@ import { registerWalletGetBalanceTool } from "./getBalance";
 import { registerGetBsv21BalancesTool } from "./getBsv21Balances";
 import { registerGetLockDataTool } from "./getLockData";
 import { registerGetOrdinalsTool } from "./getOrdinals";
+import { registerListOrdinalTool } from "./listOrdinal";
 import { registerListTokensTool } from "./listTokens";
+import { registerLockBsvTool } from "./lockBsv";
 import { registerMintCollectionTool } from "./mintCollection";
+import { registerOpnsDeregisterTool } from "./opnsDeregister";
+import { registerOpnsRegisterTool } from "./opnsRegister";
 import { registerPurchaseListingTool } from "./purchaseListing";
 import { registerRefreshUtxosTool } from "./refreshUtxos";
-import { registerSendToAddressTool } from "./sendToAddress";
-import { registerSignBsmTool } from "./signBsm";
-import { registerTransferOrdTokenTool } from "./transferOrdToken";
-import { registerListOrdinalTool } from "./listOrdinal";
-import { registerCancelListingTool } from "./cancelListing";
 import { registerSendAllBsvTool } from "./sendAllBsv";
-import { registerLockBsvTool } from "./lockBsv";
-import { registerUnlockBsvTool } from "./unlockBsv";
-import { registerOpnsRegisterTool } from "./opnsRegister";
-import { registerOpnsDeregisterTool } from "./opnsDeregister";
+import { registerSendBsvTool } from "./sendBsv";
+import { registerSignBsmTool } from "./signBsm";
 import { registerSweepBsvTool } from "./sweepBsv";
-import { registerSweepOrdinalsTool } from "./sweepOrdinals";
 import { registerSweepBsv21Tool } from "./sweepBsv21";
+import { registerSweepOrdinalsTool } from "./sweepOrdinals";
+import { registerTransferOrdTokenTool } from "./transferOrdToken";
+import { registerUnlockBsvTool } from "./unlockBsv";
 import type { Wallet } from "./wallet";
 
 export function registerWalletTools(
@@ -39,8 +39,7 @@ export function registerWalletTools(
 		ctx?: OneSatContext;
 	},
 ): void {
-	// Register the wallet_sendToAddress tool
-	registerSendToAddressTool(server, config.ctx);
+	registerSendBsvTool(server, config.ctx);
 
 	// Register the wallet_getAddress tool
 	registerGetAddressTool(server, config.ctx);
@@ -95,5 +94,4 @@ export function registerWalletTools(
 	registerSweepBsvTool(server, config.ctx);
 	registerSweepOrdinalsTool(server, config.ctx);
 	registerSweepBsv21Tool(server, config.ctx);
-
 }

package/tools/wallet/transactionHelper.ts

@@ -50,14 +50,16 @@ export async function executeTransaction<TArgs>(
 			throw new Error("Could not get wallet address");
 		}
 
-		// Parse identity key if provided
+		// Absent means "do not use identity features". Present but unparseable
+		// means the caller meant to sign and the key is wrong, so proceeding
+		// would silently produce an unsigned transaction.
 		let identityKey: PrivateKey | undefined;
 		if (identityKeyWif) {
 			try {
 				identityKey = PrivateKey.fromWif(identityKeyWif);
 			} catch (e) {
-				console.warn(
-					"Invalid IDENTITY_KEY_WIF provided, skipping identity features",
+				throw new Error(
+					`An identity key was supplied but is not a valid WIF: ${formatError(e)}`,
 				);
 			}
 		}
@@ -96,8 +98,14 @@ export function getIdentityKeyFromEnv(): PrivateKey | undefined {
 	try {
 		return PrivateKey.fromWif(identityKeyWif);
 	} catch (e) {
-		console.warn("Invalid IDENTITY_KEY_WIF in environment:", formatError(e));
-		return undefined;
+		// Unset means "do not sign" and is a valid configuration. Set but
+		// unparseable means the operator intended to sign and the key is wrong,
+		// so returning undefined here would silently publish unsigned data under
+		// no identity. Fail instead. The parse error carries no key material --
+		// @bsv/sdk reports "Invalid checksum" without echoing its input.
+		throw new Error(
+			`IDENTITY_KEY_WIF is set but is not a valid WIF: ${formatError(e)}`,
+		);
 	}
 }