bsv-mcp 0.0.26 → 0.0.27

package/prompts/bsvSdk/transaction.ts

@@ -0,0 +1,249 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type {
+	ServerNotification,
+	ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+
+/**
+ * BSV SDK Transaction Prompt
+ *
+ * Provides detailed information about transaction building and management
+ * in the BSV SDK, including input/output handling, script integration, and transaction signing.
+ */
+export const BSV_SDK_TRANSACTION_PROMPT = `
+# BSV SDK - Transaction Module
+
+The Transaction module in the BSV SDK provides comprehensive functionality for creating, manipulating, and signing Bitcoin transactions. It gives developers fine-grained control over transaction construction while abstracting many of the complexities.
+
+## Key Components
+
+### Transaction Class
+
+The core \`Transaction\` class represents a Bitcoin transaction and provides methods for manipulating its components:
+
+\`\`\`typescript
+import { Transaction, PrivateKey, LockingScript } from "@bsv/sdk";
+
+// Create a new transaction
+const tx = new Transaction();
+
+// Set transaction properties
+tx.version = 1;
+tx.lockTime = 0;
+\`\`\`
+
+## Building Transactions
+
+### Adding Inputs
+
+\`\`\`typescript
+// Add an input by specifying the source transaction and output index
+tx.addInput({
+  sourceTXID: "previous_transaction_id_in_hex",
+  sourceOutputIndex: 0,
+  sequence: 0xffffffff // Optional, defaults to max value
+});
+
+// Add multiple inputs
+const inputs = [
+  { sourceTXID: "txid1", sourceOutputIndex: 0 },
+  { sourceTXID: "txid2", sourceOutputIndex: 1 }
+];
+inputs.forEach(input => tx.addInput(input));
+\`\`\`
+
+### Adding Outputs
+
+\`\`\`typescript
+// Add an output with a locking script and amount
+import { LockingScript } from "@bsv/sdk";
+
+// Create from a Bitcoin address
+const lockingScript = LockingScript.fromAddress("recipient_address");
+
+// Add the output to the transaction
+tx.addOutput({
+  lockingScript,
+  satoshis: 5000 // Amount in satoshis
+});
+
+// Add a data (OP_RETURN) output
+const dataScript = LockingScript.fromData(Buffer.from("Hello, Bitcoin!"));
+tx.addOutput({
+  lockingScript: dataScript,
+  satoshis: 0 // OP_RETURN outputs typically have 0 value
+});
+\`\`\`
+
+### Working with UTXOs
+
+When building transactions with existing UTXOs:
+
+\`\`\`typescript
+import { UnlockingScript } from "@bsv/sdk";
+
+// Example UTXO data
+const utxos = [
+  {
+    txid: "previous_tx_id_in_hex",
+    vout: 0,
+    satoshis: 10000,
+    scriptPubKey: "locking_script_hex"
+  }
+];
+
+// Create transaction using UTXOs
+const tx = new Transaction();
+
+// Add input from UTXO
+utxos.forEach(utxo => {
+  tx.addInput({
+    sourceTXID: utxo.txid,
+    sourceOutputIndex: utxo.vout
+  });
+});
+
+// Add output with recipient address
+tx.addOutput({
+  lockingScript: LockingScript.fromAddress("recipient_address"),
+  satoshis: 9000 // Sending 9000 satoshis (10000 - 1000 fee)
+});
+\`\`\`
+
+## Signing Transactions
+
+### Basic Transaction Signing
+
+\`\`\`typescript
+import { PrivateKey, SigningConfig, Utils } from "@bsv/sdk";
+
+// Create a private key
+const privateKey = PrivateKey.fromWif("your_private_key_wif");
+
+// Sign a specific input
+const inputIndex = 0;
+const signingConfig: SigningConfig = {
+  privateKey,
+  lockingScript: LockingScript.fromAddress(privateKey.toAddress()),
+  satoshis: 10000, // Original amount in the UTXO
+  inputIndex,
+  sigHashType: Utils.SIGHASH_ALL | Utils.SIGHASH_FORKID // Standard signing algorithm
+};
+
+// Apply the signature to the transaction
+tx.sign(signingConfig);
+\`\`\`
+
+### Signing Multiple Inputs
+
+\`\`\`typescript
+// Sign multiple inputs with different keys
+const keys = [privateKey1, privateKey2];
+const utxos = [utxo1, utxo2];
+
+utxos.forEach((utxo, index) => {
+  const signingConfig = {
+    privateKey: keys[index],
+    lockingScript: LockingScript.fromHex(utxo.scriptPubKey),
+    satoshis: utxo.satoshis,
+    inputIndex: index,
+    sigHashType: Utils.SIGHASH_ALL | Utils.SIGHASH_FORKID
+  };
+  
+  tx.sign(signingConfig);
+});
+\`\`\`
+
+## Transaction Serialization
+
+\`\`\`typescript
+// Convert transaction to binary format
+const txBinary = tx.toBinary();
+
+// Convert to hex string
+const txHex = tx.toHex();
+
+// Get transaction ID
+const txid = tx.hash("hex");
+
+// Parse an existing transaction
+const parsedTx = Transaction.fromHex("transaction_hex_string");
+\`\`\`
+
+## Fee Calculation
+
+\`\`\`typescript
+// Manual fee calculation based on transaction size
+const txSize = tx.toBinary().length;
+const feeRate = 0.5; // satoshis per byte
+const fee = Math.ceil(txSize * feeRate);
+
+// Adjust output amount to include fee
+outputAmount = inputAmount - fee;
+\`\`\`
+
+## Advanced Transaction Features
+
+### Time Locks
+
+\`\`\`typescript
+// Set absolute locktime (by block height)
+tx.lockTime = 700000; // Transaction can't be mined until block 700000
+
+// Set relative locktime using sequence number (BIP 68)
+const sequenceForBlocks = (blocks) => 0xffffffff - blocks;
+tx.inputs[0].sequence = sequenceForBlocks(10); // Locked for 10 blocks
+\`\`\`
+
+### Custom Scripts
+
+\`\`\`typescript
+import { Script, OpCodes } from "@bsv/sdk";
+
+// Create a custom script
+const customScript = new Script();
+customScript.add(OpCodes.OP_DUP);
+customScript.add(OpCodes.OP_HASH160);
+customScript.add(Buffer.from("public_key_hash", "hex"));
+customScript.add(OpCodes.OP_EQUALVERIFY);
+customScript.add(OpCodes.OP_CHECKSIG);
+
+// Create a locking script from the custom script
+const customLockingScript = LockingScript.fromScript(customScript);
+\`\`\`
+
+## Best Practices
+
+1. **Fee Management**: Calculate appropriate fees based on transaction size and network conditions
+2. **Input/Output Management**: Properly track inputs and outputs to avoid double-spending
+3. **Change Handling**: Always account for change when not spending the full UTXO amount
+4. **Testing**: Test transactions on testnet before deploying to mainnet
+5. **Error Handling**: Implement proper error handling for transaction building and signing
+
+For complete API documentation and additional transaction features, refer to the official BSV SDK documentation.
+`;
+
+/**
+ * Register the BSV SDK Transaction prompt with the MCP server
+ * @param server The MCP server instance
+ */
+export function registerTransactionPrompt(server: McpServer): void {
+	server.prompt(
+		"bitcoin_sv_sdk_transaction",
+		"Detailed information about transaction building and management in the BSV SDK, including input/output handling, script integration, and transaction signing.",
+		async (extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => {
+			return {
+				messages: [
+					{
+						role: "assistant",
+						content: {
+							type: "text",
+							text: BSV_SDK_TRANSACTION_PROMPT,
+						},
+					},
+				],
+			};
+		},
+	);
+}

package/prompts/bsvSdk/wallet.ts

@@ -0,0 +1,188 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type {
+	ServerNotification,
+	ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+
+/**
+ * BSV SDK Wallet Prompt
+ *
+ * Provides detailed information about the wallet functionality in the BSV SDK,
+ * including key management, address handling, and UTXO management.
+ */
+export const BSV_SDK_WALLET_PROMPT = `
+# BSV SDK - Wallet Module
+
+The wallet module in BSV SDK provides comprehensive functionality for managing Bitcoin keys, addresses, and UTXOs (Unspent Transaction Outputs). It forms the foundation for creating and managing Bitcoin wallets in your applications.
+
+## Key Classes and Interfaces
+
+### ProtoWallet
+
+The \`ProtoWallet\` class provides a basic implementation of the wallet interface with core functionality:
+
+\`\`\`typescript
+import { PrivateKey, ProtoWallet } from "@bsv/sdk";
+
+// Create a new wallet with a random private key
+const privateKey = PrivateKey.fromRandom();
+const wallet = new ProtoWallet(privateKey);
+\`\`\`
+
+### WalletInterface
+
+The \`WalletInterface\` defines the standard interface that wallet implementations should follow. It includes methods for:
+
+- Key management
+- Cryptographic operations
+- Transaction creation and signing
+- Output management
+- Certificate handling
+
+## Key Management
+
+### Generating Keys
+
+\`\`\`typescript
+import { PrivateKey } from "@bsv/sdk";
+
+// Generate a random private key
+const privateKey = PrivateKey.fromRandom();
+
+// Generate from a WIF (Wallet Import Format) string
+const importedKey = PrivateKey.fromWif("your-wif-string");
+
+// Generate from a seed
+const seedKey = PrivateKey.fromSeed(Buffer.from("your-seed-data"));
+
+// Get the corresponding public key
+const publicKey = privateKey.toPublicKey();
+\`\`\`
+
+### KeyDeriver & CachedKeyDeriver
+
+For HD (Hierarchical Deterministic) wallet functionality:
+
+\`\`\`typescript
+import { KeyDeriver } from "@bsv/sdk";
+
+// Create a key deriver with a seed
+const deriver = new KeyDeriver(seed);
+
+// Derive a key at a specific path
+const derivedKey = await deriver.deriveKey("m/44'/0'/0'/0/0");
+\`\`\`
+
+## Address Management
+
+\`\`\`typescript
+// Get the address for a private key
+const address = privateKey.toAddress();
+
+// Get the address for a public key
+const address = publicKey.toAddress();
+
+// Get the address string
+const addressString = address.toString();
+\`\`\`
+
+## UTXO Management
+
+Managing UTXOs (Unspent Transaction Outputs) is a critical part of wallet functionality:
+
+\`\`\`typescript
+// Example of tracking UTXOs
+class MyWallet extends ProtoWallet {
+  private utxos = [];
+  
+  async refreshUtxos(address) {
+    // Fetch UTXOs from a service or API
+    this.utxos = await fetchUtxosFromService(address);
+  }
+  
+  getAvailableUtxos() {
+    return this.utxos.filter(utxo => !utxo.spent);
+  }
+  
+  getBalance() {
+    return this.getAvailableUtxos().reduce((sum, utxo) => sum + utxo.satoshis, 0);
+  }
+}
+\`\`\`
+
+## Cryptographic Operations
+
+The wallet module provides various cryptographic operations:
+
+\`\`\`typescript
+// Signing data
+const signature = await wallet.createSignature({
+  data: [1, 2, 3, 4],  // Data to sign
+  protocolID: [1, "ecdsa"],  // Protocol to use
+  keyID: "default"  // Key identifier
+});
+
+// Verifying signatures
+const isValid = await wallet.verifySignature({
+  data: [1, 2, 3, 4],  // Original data
+  signature: signatureBytes,  // Signature to verify
+  protocolID: [1, "ecdsa"],
+  keyID: "default"
+});
+
+// Encryption and decryption
+const encrypted = await wallet.encrypt({
+  plaintext: [1, 2, 3, 4],
+  protocolID: [1, "aes256"],
+  keyID: "default"
+});
+
+const decrypted = await wallet.decrypt({
+  ciphertext: encrypted.ciphertext,
+  protocolID: [1, "aes256"],
+  keyID: "default"
+});
+\`\`\`
+
+## Best Practices
+
+1. **Key Security**: Always handle private keys securely and never expose them unnecessarily
+2. **UTXO Management**: Maintain accurate UTXO information for wallet functionality
+3. **Error Handling**: Implement proper error handling for all wallet operations
+4. **Testing**: Test wallet functionality thoroughly on testnet before deploying to mainnet
+5. **Backup**: Provide key backup and recovery mechanisms for users
+
+## Advanced Topics
+
+- **Multi-signature wallets**: Implementing wallets requiring multiple signatures
+- **HD Wallets**: Creating hierarchical deterministic wallets for key derivation
+- **Watch-only wallets**: Tracking addresses without private keys
+- **Hardware wallet integration**: Connecting to hardware security devices
+
+For complete API documentation and additional wallet features, refer to the official BSV SDK documentation.
+`;
+
+/**
+ * Register the BSV SDK Wallet prompt with the MCP server
+ * @param server The MCP server instance
+ */
+export function registerWalletPrompt(server: McpServer): void {
+	server.prompt(
+		"bitcoin_sv_sdk_wallet",
+		"Detailed information about the wallet functionality in the BSV SDK, including key management, address handling, and UTXO management.",
+		async (extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => {
+			return {
+				messages: [
+					{
+						role: "assistant",
+						content: {
+							type: "text",
+							text: BSV_SDK_WALLET_PROMPT,
+						},
+					},
+				],
+			};
+		},
+	);
+}

package/prompts/index.ts

@@ -0,0 +1,23 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerAllBsvSdkPrompts } from "./bsvSdk";
+import { registerOrdinalsPrompt } from "./ordinals";
+
+/**
+ * Register all prompts with the MCP server
+ * @param server The MCP server instance
+ */
+export function registerAllPrompts(server: McpServer): void {
+	// Register Ordinals prompt
+	registerOrdinalsPrompt(server);
+
+	// Register all BSV SDK prompts
+	registerAllBsvSdkPrompts(server);
+
+	// Add more prompts registration here as needed
+}
+
+/**
+ * Export all prompt constants
+ */
+export * from "./ordinals";
+export * from "./bsvSdk";

package/prompts/ordinals.ts

@@ -0,0 +1,103 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type {
+	ServerNotification,
+	ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+
+/**
+ * 1Sat Ordinals Prompt
+ *
+ * Provides comprehensive information about Bitcoin SV ordinals,
+ * including what they are, how they work, and how to use them.
+ */
+export const ORDINALS_PROMPT = `
+# 1Sat Ordinals - Comprehensive Guide
+
+Ordinals are a way to uniquely identify and track specific satoshis (the smallest unit of Bitcoin) 
+on the blockchain. This concept allows for "inscriptions" - embedding data directly into a satoshi, 
+effectively creating NFT-like functionality native to the Bitcoin protocol.
+
+## Key Concepts
+
+1. **Ordinal Theory**: Each satoshi has a unique position in the Bitcoin ledger, determined by the order 
+   in which they were mined.
+
+2. **Inscriptions**: Content embedded directly into a specific satoshi. Can be any valid content type.
+
+3. **On-chain Storage**: All ordinal data is stored immutably on the blockchain.
+
+## BSV Ordinals (1Sat Ordinals) vs. BTC Ordinals
+
+- 1Sat Ordinals leverage the larger block sizes and lower fees of Bitcoin SV, making them more practical
+  for storing meaningful data and media.
+  
+- 1Sat Ordinals can store much larger inscriptions compared to BTC, enabling richer media and applications.
+
+- 1Sat Ordinals typically cost a fraction of what BTC ordinals cost to create and transfer.
+
+## Creating Ordinals
+
+To create a BSV ordinal:
+
+1. Choose the content to inscribe (image, text, audio, etc.)
+2. Use a compatible wallet or service that supports ordinal creation
+3. Pay the transaction fee to inscribe your content on-chain
+4. Receive a unique ordinal ID that references your specific satoshi
+
+## Transferring Ordinals
+
+Ordinals are transferred by sending the specific satoshi that contains the inscription. Compatible wallets
+ensure that when you transfer an ordinal, the specific satoshi containing the inscription is included in
+the transaction.
+
+## Viewing Ordinals
+
+Ordinal inscriptions can be viewed through:
+
+1. Specialized ordinal explorers
+2. Compatible wallets with ordinal support
+3. Marketplaces that support BSV ordinals
+
+## Use Cases
+
+- Digital Art and Collectibles
+- Certificates of Authenticity
+- Domain Names
+- Documentation and Verification
+- Gaming Assets
+- Media Distribution
+
+## Best Practices
+
+- Verify file sizes and transaction costs before inscribing
+- Use appropriate file formats optimized for on-chain storage
+- Keep private keys secure to maintain ownership of valuable ordinals
+- Consider using a specialized wallet for managing valuable ordinal collections
+
+For technical implementation details, refer to the official documentation and BSV ordinals standards.
+`;
+
+/**
+ * Register the Ordinals prompt with the MCP server
+ * @param server The MCP server instance
+ */
+export function registerOrdinalsPrompt(server: McpServer): void {
+	server.prompt(
+		"bitcoin_sv_ordinals",
+		"Comprehensive information about Bitcoin SV ordinals, including what they are, how they work, and how to use them.",
+		async (extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => {
+			return {
+				messages: [
+					{
+						role: "assistant",
+						content: {
+							type: "text",
+							text: ORDINALS_PROMPT,
+						},
+					},
+				],
+			};
+		},
+	);
+}