@mcpsovereign/sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { AgentRuntime, createRuntime } from './runtime.js';
 export type { RuntimeConfig, RuntimeOptions } from './runtime.js';
+export * from './wallet/index.js';
+export { WalletSetupWizard } from './wallet/wizard.js';
+export { LNDSetup, quickSetupLND } from './wallet/lnd-setup.js';
 export * from './onboarding/types.js';
 export { OnboardingWizard } from './onboarding/wizard.js';
 export { AgentHelperMCP, HELPER_TOOLS } from './mcp-helper/index.js';
@@ -427,5 +430,57 @@ export declare class SovereignClient {
      * Show available badges
      */
     showBadges(): Promise<void>;
+    /**
+     * Run the wallet setup wizard
+     * This must be completed before buying/selling
+     */
+    setupWallet(options?: {
+        outputHandler?: (message: string) => void;
+        inputHandler?: (prompt: string, options?: string[]) => Promise<string>;
+    }): Promise<{
+        configured: boolean;
+        lightningAddress?: string;
+        skipped: boolean;
+    }>;
+    /**
+     * Check if wallet is configured
+     */
+    isWalletConfigured(): Promise<boolean>;
+    /**
+     * Get the configured Lightning address
+     */
+    getLightningAddress(): Promise<string | null>;
+    /**
+     * Check if agent can transact (buy/sell)
+     */
+    canTransact(): Promise<{
+        allowed: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Set up a self-hosted LND node
+     * Requires Docker. Uses Neutrino mode (no full Bitcoin node needed).
+     */
+    setupSelfHostedNode(options?: {
+        alias?: string;
+        network?: 'mainnet' | 'testnet';
+    }): Promise<{
+        success: boolean;
+        seed?: string[];
+        restHost?: string;
+        error?: string;
+    }>;
+    /**
+     * Get self-hosted node status
+     */
+    getNodeStatus(): Promise<{
+        running: boolean;
+        synced: boolean;
+        blockHeight?: number;
+        balance?: {
+            confirmed: number;
+            unconfirmed: number;
+        };
+    }>;
 }
 export default SovereignClient;

package/dist/index.js

@@ -2,8 +2,13 @@
 // mcpSovereign SDK - Local-First Store Management
 // =============================================================================
 // Agents build their store locally (free), sync to marketplace (costs credits)
+// Wallet required to buy/sell, but browsing is always free
 // Re-export runtime module (portable identity management)
 export { AgentRuntime, createRuntime } from './runtime.js';
+// Re-export wallet module (Lightning-first payments)
+export * from './wallet/index.js';
+export { WalletSetupWizard } from './wallet/wizard.js';
+export { LNDSetup, quickSetupLND } from './wallet/lnd-setup.js';
 // Re-export onboarding module
 export * from './onboarding/types.js';
 export { OnboardingWizard } from './onboarding/wizard.js';
@@ -498,6 +503,85 @@ export class SovereignClient {
         const wizard = new OnboardingWizard();
         wizard.showBadges();
     }
+    // ---------------------------------------------------------------------------
+    // Wallet (Lightning Network Integration)
+    // ---------------------------------------------------------------------------
+    /**
+     * Run the wallet setup wizard
+     * This must be completed before buying/selling
+     */
+    async setupWallet(options = {}) {
+        const { WalletSetupWizard, saveWalletConfig } = await import('./wallet/index.js');
+        const wizard = new WalletSetupWizard(options.outputHandler || console.log, options.inputHandler);
+        const result = await wizard.run();
+        if (result.config) {
+            saveWalletConfig(result.config);
+        }
+        return {
+            configured: result.config !== null,
+            lightningAddress: result.config?.lightningAddress,
+            skipped: result.skipped
+        };
+    }
+    /**
+     * Check if wallet is configured
+     */
+    async isWalletConfigured() {
+        const { isWalletConfigured } = await import('./wallet/index.js');
+        return isWalletConfigured();
+    }
+    /**
+     * Get the configured Lightning address
+     */
+    async getLightningAddress() {
+        const { getLightningAddress } = await import('./wallet/index.js');
+        return getLightningAddress();
+    }
+    /**
+     * Check if agent can transact (buy/sell)
+     */
+    async canTransact() {
+        const { canTransact } = await import('./wallet/index.js');
+        return canTransact();
+    }
+    /**
+     * Set up a self-hosted LND node
+     * Requires Docker. Uses Neutrino mode (no full Bitcoin node needed).
+     */
+    async setupSelfHostedNode(options = {}) {
+        const { LNDSetup } = await import('./wallet/lnd-setup.js');
+        const setup = new LNDSetup({
+            alias: options.alias || `SovereignAgent_${Date.now().toString(36)}`,
+            network: options.network || 'mainnet'
+        });
+        const result = await setup.setupLND();
+        if (result.success && result.credentials) {
+            // Save to wallet config
+            const { saveWalletConfig } = await import('./wallet/index.js');
+            saveWalletConfig({
+                provider: 'zeus',
+                nodeUri: result.credentials.restHost,
+                setupComplete: true,
+                verified: true,
+                verifiedAt: new Date().toISOString(),
+                createdAt: new Date().toISOString()
+            });
+        }
+        return {
+            success: result.success,
+            seed: result.walletSeed,
+            restHost: result.credentials?.restHost,
+            error: result.error
+        };
+    }
+    /**
+     * Get self-hosted node status
+     */
+    async getNodeStatus() {
+        const { LNDSetup } = await import('./wallet/lnd-setup.js');
+        const setup = new LNDSetup();
+        return setup.getStatus();
+    }
 }
 // Default export
 export default SovereignClient;

package/dist/setup.js

@@ -16,6 +16,8 @@ import * as path from 'path';
 import * as readline from 'readline';
 import { SovereignClient } from './index.js';
 import { OnboardingWizard } from './onboarding/wizard.js';
+import { WalletSetupWizard } from './wallet/wizard.js';
+import { isWalletConfigured, saveWalletConfig, loadWalletConfig } from './wallet/index.js';
 import { STARTER_CREDITS, PLATFORM_CREDENTIALS } from './onboarding/starter-kit.js';
 // ============================================================
 // CONFIG PATHS
@@ -221,7 +223,51 @@ async function runSetup() {
         saveConfig(config);
         console.log('📝 Created new configuration');
     }
-    // Step 3: Connect to server
+    // ===========================================================================
+    // STEP 3: WALLET SETUP (RUNS FIRST - GATED)
+    // ===========================================================================
+    // Wallet is required to buy/sell, but browsing is free
+    const walletConfigured = isWalletConfigured();
+    if (!walletConfigured) {
+        console.log('\n');
+        console.log('╔═══════════════════════════════════════════════════════════════════╗');
+        console.log('║                                                                   ║');
+        console.log('║         ⚡ LIGHTNING WALLET SETUP REQUIRED ⚡                     ║');
+        console.log('║                                                                   ║');
+        console.log('║   mcpSovereign runs on Bitcoin Lightning Network                  ║');
+        console.log('║   You need a wallet to buy credits and sell products              ║');
+        console.log('║                                                                   ║');
+        console.log('║   🆓 Browsing the marketplace is always FREE                      ║');
+        console.log('║                                                                   ║');
+        console.log('╚═══════════════════════════════════════════════════════════════════╝');
+        console.log('\n');
+        const walletWizard = new WalletSetupWizard(console.log, async (prompt, options) => {
+            return await question(rl, prompt + ' ');
+        });
+        const walletResult = await walletWizard.run();
+        if (walletResult.config) {
+            saveWalletConfig(walletResult.config);
+            config.wallet_address = walletResult.config.lightningAddress || walletResult.config.nodeUri || null;
+            console.log('\n✅ Wallet setup complete!\n');
+        }
+        else if (walletResult.skipped) {
+            console.log('\n⏭️  Wallet setup skipped. You can set it up later with:');
+            console.log('   npx @mcpsovereign/sdk setup-wallet\n');
+        }
+        saveConfig(config);
+    }
+    else {
+        const existingWallet = loadWalletConfig();
+        console.log('\n✅ Wallet already configured');
+        if (existingWallet?.lightningAddress) {
+            console.log(`   Lightning Address: ${existingWallet.lightningAddress}`);
+        }
+        else if (existingWallet?.nodeUri) {
+            console.log(`   Self-hosted node: ${existingWallet.nodeUri}`);
+        }
+        console.log('');
+    }
+    // Step 4: Connect to server
     await showLoadingBar('🌐 Connecting to server', 1500);
     const { client, connected } = await connectToServer(config);
     if (connected) {
@@ -231,14 +277,16 @@ async function runSetup() {
         console.log('\n⚠️  Could not connect to server. Running in offline mode.');
         console.log('   You can still build products locally!\n');
     }
-    // Step 4: First-time setup
+    // Step 5: First-time setup (authentication)
     if (isFirstRun || !config.setup_complete) {
         console.log('\n🎮 First time setup detected!\n');
-        // Ask for wallet address
-        const walletInput = await question(rl, '🔑 Enter your wallet address (or press Enter for demo mode): ');
-        config.wallet_address = walletInput || `demo-agent-${Date.now()}`;
+        // Use wallet address if we have it, otherwise demo mode
+        if (!config.wallet_address) {
+            const walletInput = await question(rl, '🔑 Enter your wallet address (or press Enter for demo mode): ');
+            config.wallet_address = walletInput || `demo-agent-${Date.now()}`;
+        }
         // Try to authenticate
-        if (connected) {
+        if (connected && config.wallet_address) {
             await showLoadingBar('🔐 Authenticating', 1000);
             const authResult = await client.authenticate(config.wallet_address);
             if (authResult.success && authResult.data) {
@@ -254,10 +302,10 @@ async function runSetup() {
         config.setup_complete = true;
         saveConfig(config);
     }
-    // Step 5: Update MCP config
+    // Step 6: Update MCP config
     console.log('\n📋 Configuring MCP integration...');
     updateMCPConfig();
-    // Step 6: Run onboarding wizard if not complete
+    // Step 7: Run onboarding wizard if not complete
     if (!config.onboarding_complete) {
         console.log('\n');
         const runOnboarding = await question(rl, '🎓 Run the onboarding wizard? (Y/n): ');
@@ -273,11 +321,11 @@ async function runSetup() {
             saveConfig(config);
         }
     }
-    // Step 7: Save local store
+    // Step 8: Save local store
     await client.localStore.save();
-    // Step 8: Show completion
+    // Step 9: Show completion
     console.log(SETUP_COMPLETE_BANNER);
-    // Step 9: Show quick reference
+    // Step 10: Show quick reference
     console.log('\n📚 Quick Reference:');
     console.log('─'.repeat(50));
     console.log('');
@@ -292,7 +340,8 @@ async function runSetup() {
     console.log('SDK Usage (in your code):');
     console.log('  import { SovereignClient } from "@mcpsovereign/sdk";');
     console.log('  const client = new SovereignClient();');
-    console.log('  await client.onboard();  // Interactive setup');
+    console.log('  await client.setupWallet();  // Wallet setup');
+    console.log('  await client.onboard();      // Store onboarding');
     console.log('');
     console.log('Config Location: ' + CONFIG_DIR);
     console.log('');
@@ -328,10 +377,18 @@ Usage:
   npx @mcpsovereign/sdk <command>
 
 Commands:
-  setup     Run the setup wizard
-  status    Show current configuration
-  reset     Reset configuration and start fresh
-  help      Show this help message
+  setup         Run the full setup wizard (wallet + onboarding)
+  setup-wallet  Run only the wallet setup wizard
+  setup-lnd     Set up a self-hosted Lightning node (Docker)
+  wallet        Show wallet status or manage wallet
+  status        Show current configuration
+  reset         Reset configuration and start fresh
+  help          Show this help message
+
+Wallet Commands:
+  wallet status   - Show wallet configuration
+  wallet verify   - Verify Lightning address is reachable
+  wallet reset    - Reset wallet configuration
 
 After setup, use the sovereign_* MCP tools in Claude!
 `);
@@ -348,6 +405,92 @@ async function resetConfig() {
 // ============================================================
 // MAIN ENTRY
 // ============================================================
+async function runWalletSetup() {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    const questionAsync = (prompt) => new Promise((resolve) => {
+        rl.question(prompt, resolve);
+    });
+    const wizard = new WalletSetupWizard(console.log, async (prompt, options) => {
+        return await questionAsync(prompt + ' ');
+    });
+    const result = await wizard.run();
+    if (result.config) {
+        saveWalletConfig(result.config);
+        console.log('\n✅ Wallet configuration saved!\n');
+    }
+    rl.close();
+}
+async function runLNDSetup() {
+    const { LNDSetup } = await import('./wallet/lnd-setup.js');
+    console.log('\n🖥️  Self-Hosted Lightning Node Setup\n');
+    console.log('This will set up an LND node using Docker with Neutrino mode.');
+    console.log('No full Bitcoin node required - syncs in minutes!\n');
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    const alias = await new Promise((resolve) => {
+        rl.question('Node alias (press Enter for auto-generated): ', resolve);
+    });
+    rl.close();
+    const setup = new LNDSetup({
+        alias: alias || `SovereignAgent_${Date.now().toString(36)}`
+    });
+    // Check prerequisites
+    const prereqs = await setup.checkPrerequisites();
+    if (!prereqs.ready) {
+        console.log('\n❌ Prerequisites not met:\n');
+        if (!prereqs.docker.installed) {
+            console.log('  • Docker is not installed');
+            console.log('    Install from: https://docs.docker.com/get-docker/\n');
+        }
+        else if (!prereqs.docker.running) {
+            console.log('  • Docker is installed but not running');
+            console.log('    Start Docker and try again\n');
+        }
+        if (!prereqs.compose) {
+            console.log('  • Docker Compose is not available\n');
+        }
+        if (!prereqs.diskSpace.sufficient) {
+            console.log(`  • Insufficient disk space (need 5GB, have ${Math.round(prereqs.diskSpace.available / 1024 / 1024 / 1024)}GB)\n`);
+        }
+        return;
+    }
+    console.log('\n✅ Prerequisites met. Starting setup...\n');
+    const result = await setup.setupLND();
+    if (result.success) {
+        console.log('\n✅ LND node setup complete!\n');
+        if (result.walletSeed) {
+            console.log('⚠️  IMPORTANT: Your wallet seed has been saved to:');
+            console.log(`   ~/.sovereign-lnd/BACKUP_SEED_DELETE_AFTER_BACKUP.txt`);
+            console.log('   Back it up and DELETE the file!\n');
+        }
+        if (result.credentials) {
+            // Save wallet config
+            saveWalletConfig({
+                provider: 'zeus',
+                nodeUri: result.credentials.restHost,
+                setupComplete: true,
+                verified: true,
+                verifiedAt: new Date().toISOString(),
+                createdAt: new Date().toISOString()
+            });
+            console.log('✅ Wallet configuration saved!\n');
+        }
+    }
+    else {
+        console.log(`\n❌ Setup failed: ${result.error}\n`);
+        console.log('Logs:');
+        result.logs.slice(-10).forEach(log => console.log(`  ${log}`));
+    }
+}
+async function walletCommand(args) {
+    const { walletCLI } = await import('./wallet/index.js');
+    await walletCLI(args);
+}
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0] || 'setup';
@@ -355,6 +498,15 @@ async function main() {
         case 'setup':
             await runSetup();
             break;
+        case 'setup-wallet':
+            await runWalletSetup();
+            break;
+        case 'setup-lnd':
+            await runLNDSetup();
+            break;
+        case 'wallet':
+            await walletCommand(args.slice(1));
+            break;
         case 'status':
             await showStatus();
             break;

package/dist/wallet/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * mcpSovereign Wallet Module
+ *
+ * Lightning-first wallet setup and management for AI agents
+ *
+ * Features:
+ * - Guided wallet setup wizard
+ * - Lightning address validation
+ * - Self-hosted LND setup (Docker + Neutrino)
+ * - Payment helpers
+ */
+export * from './types.js';
+export { parseLightningAddress, verifyLightningAddress, getProviderFromAddress, createPaymentRequest, creditsToSats, satsToCredits, satsToDollars, dollarsToSats, formatSats, formatCredits, KNOWN_PROVIDERS, CREDITS_PER_SAT, SATS_PER_CREDIT } from './lightning.js';
+export { LNDSetup, quickSetupLND } from './lnd-setup.js';
+export type { LNDConfig, LNDCredentials, SetupResult } from './lnd-setup.js';
+export { WalletSetupWizard } from './wizard.js';
+import { WalletConfig } from './types.js';
+/**
+ * Load saved wallet configuration
+ */
+export declare function loadWalletConfig(): WalletConfig | null;
+/**
+ * Save wallet configuration
+ */
+export declare function saveWalletConfig(config: WalletConfig): void;
+/**
+ * Check if wallet is set up
+ */
+export declare function isWalletConfigured(): boolean;
+/**
+ * Check if wallet is verified
+ */
+export declare function isWalletVerified(): boolean;
+/**
+ * Run the wallet setup wizard
+ */
+export declare function runWalletSetup(options?: {
+    outputHandler?: (message: string) => void;
+    inputHandler?: (prompt: string, options?: string[]) => Promise<string>;
+}): Promise<WalletConfig | null>;
+/**
+ * Get the current Lightning address (if configured)
+ */
+export declare function getLightningAddress(): string | null;
+/**
+ * Quick check: can the agent buy/sell?
+ */
+export declare function canTransact(): {
+    allowed: boolean;
+    reason?: string;
+};
+/**
+ * CLI entry point for wallet setup
+ */
+export declare function walletCLI(args: string[]): Promise<void>;

package/dist/wallet/index.js

@@ -0,0 +1,189 @@
+/**
+ * mcpSovereign Wallet Module
+ *
+ * Lightning-first wallet setup and management for AI agents
+ *
+ * Features:
+ * - Guided wallet setup wizard
+ * - Lightning address validation
+ * - Self-hosted LND setup (Docker + Neutrino)
+ * - Payment helpers
+ */
+// Types
+export * from './types.js';
+// Lightning utilities
+export { parseLightningAddress, verifyLightningAddress, getProviderFromAddress, createPaymentRequest, creditsToSats, satsToCredits, satsToDollars, dollarsToSats, formatSats, formatCredits, KNOWN_PROVIDERS, CREDITS_PER_SAT, SATS_PER_CREDIT } from './lightning.js';
+// LND Setup
+export { LNDSetup, quickSetupLND } from './lnd-setup.js';
+// Wallet Setup Wizard
+export { WalletSetupWizard } from './wizard.js';
+// ============================================================
+// CONVENIENCE FUNCTIONS
+// ============================================================
+import { WalletSetupWizard } from './wizard.js';
+import * as fs from 'fs';
+import * as path from 'path';
+const CONFIG_DIR = path.join(process.env.HOME || '.', '.mcpsovereign');
+const WALLET_CONFIG_FILE = path.join(CONFIG_DIR, 'wallet.json');
+/**
+ * Load saved wallet configuration
+ */
+export function loadWalletConfig() {
+    try {
+        if (fs.existsSync(WALLET_CONFIG_FILE)) {
+            return JSON.parse(fs.readFileSync(WALLET_CONFIG_FILE, 'utf-8'));
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+    return null;
+}
+/**
+ * Save wallet configuration
+ */
+export function saveWalletConfig(config) {
+    try {
+        if (!fs.existsSync(CONFIG_DIR)) {
+            fs.mkdirSync(CONFIG_DIR, { recursive: true });
+        }
+        fs.writeFileSync(WALLET_CONFIG_FILE, JSON.stringify(config, null, 2));
+    }
+    catch (error) {
+        console.error('Failed to save wallet config:', error);
+    }
+}
+/**
+ * Check if wallet is set up
+ */
+export function isWalletConfigured() {
+    const config = loadWalletConfig();
+    return config !== null && config.setupComplete;
+}
+/**
+ * Check if wallet is verified
+ */
+export function isWalletVerified() {
+    const config = loadWalletConfig();
+    return config !== null && config.verified;
+}
+/**
+ * Run the wallet setup wizard
+ */
+export async function runWalletSetup(options = {}) {
+    const wizard = new WalletSetupWizard(options.outputHandler || console.log, options.inputHandler);
+    const result = await wizard.run();
+    if (result.config) {
+        saveWalletConfig(result.config);
+    }
+    return result.config;
+}
+/**
+ * Get the current Lightning address (if configured)
+ */
+export function getLightningAddress() {
+    const config = loadWalletConfig();
+    return config?.lightningAddress || null;
+}
+/**
+ * Quick check: can the agent buy/sell?
+ */
+export function canTransact() {
+    const config = loadWalletConfig();
+    if (!config) {
+        return {
+            allowed: false,
+            reason: 'No wallet configured. Run: npx @mcpsovereign/sdk setup-wallet'
+        };
+    }
+    if (!config.setupComplete) {
+        return {
+            allowed: false,
+            reason: 'Wallet setup incomplete. Run: npx @mcpsovereign/sdk setup-wallet'
+        };
+    }
+    if (!config.lightningAddress && !config.nodeUri) {
+        return {
+            allowed: false,
+            reason: 'No Lightning address or node configured.'
+        };
+    }
+    return { allowed: true };
+}
+// ============================================================
+// CLI COMMANDS
+// ============================================================
+/**
+ * CLI entry point for wallet setup
+ */
+export async function walletCLI(args) {
+    const command = args[0] || 'status';
+    switch (command) {
+        case 'setup':
+            await runWalletSetup();
+            break;
+        case 'status': {
+            const config = loadWalletConfig();
+            if (!config) {
+                console.log('\n❌ No wallet configured');
+                console.log('   Run: npx @mcpsovereign/sdk setup-wallet\n');
+                return;
+            }
+            console.log('\n💳 Wallet Status\n');
+            console.log('═'.repeat(50));
+            console.log(`Provider: ${config.provider}`);
+            if (config.lightningAddress) {
+                console.log(`Address: ${config.lightningAddress}`);
+            }
+            if (config.nodeUri) {
+                console.log(`Node: ${config.nodeUri}`);
+            }
+            console.log(`Verified: ${config.verified ? '✅ Yes' : '❌ No'}`);
+            console.log(`Setup Complete: ${config.setupComplete ? '✅ Yes' : '❌ No'}`);
+            console.log('');
+            break;
+        }
+        case 'verify': {
+            const config = loadWalletConfig();
+            if (!config?.lightningAddress) {
+                console.log('\n❌ No Lightning address configured\n');
+                return;
+            }
+            const { verifyLightningAddress } = await import('./lightning.js');
+            console.log(`\nVerifying ${config.lightningAddress}...`);
+            const result = await verifyLightningAddress(config.lightningAddress);
+            if (result.valid) {
+                console.log('✅ Wallet is reachable and can receive payments\n');
+                config.verified = true;
+                config.verifiedAt = new Date().toISOString();
+                saveWalletConfig(config);
+            }
+            else {
+                console.log(`❌ Verification failed: ${result.error}\n`);
+            }
+            break;
+        }
+        case 'reset': {
+            if (fs.existsSync(WALLET_CONFIG_FILE)) {
+                fs.unlinkSync(WALLET_CONFIG_FILE);
+                console.log('\n✅ Wallet configuration reset\n');
+            }
+            else {
+                console.log('\nNothing to reset\n');
+            }
+            break;
+        }
+        default:
+            console.log(`
+mcpSovereign Wallet CLI
+
+Usage: npx @mcpsovereign/sdk wallet <command>
+
+Commands:
+  setup   - Run the wallet setup wizard
+  status  - Show current wallet configuration
+  verify  - Verify your Lightning address
+  reset   - Reset wallet configuration
+`);
+    }
+}