@mcpsovereign/sdk 0.1.0 → 0.2.1

package/dist/wallet/lightning.js

@@ -0,0 +1,267 @@
+/**
+ * Lightning Network Utilities
+ *
+ * Lightning address validation, LNURL handling, and payment helpers
+ */
+// ============================================================
+// LIGHTNING ADDRESS VALIDATION
+// ============================================================
+/**
+ * Parse and validate a Lightning address
+ * Format: username@domain.com
+ */
+export function parseLightningAddress(address) {
+    // Basic format check
+    const pattern = /^([a-zA-Z0-9._-]+)@([a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$/;
+    const match = address.trim().toLowerCase().match(pattern);
+    if (!match) {
+        return null;
+    }
+    const [, username, domain] = match;
+    return {
+        address: `${username}@${domain}`,
+        username,
+        domain,
+        valid: true,
+        lnurlPayUrl: `https://${domain}/.well-known/lnurlp/${username}`
+    };
+}
+/**
+ * Verify a Lightning address is reachable and can receive payments
+ */
+export async function verifyLightningAddress(address) {
+    const parsed = parseLightningAddress(address);
+    if (!parsed) {
+        return {
+            valid: false,
+            error: 'Invalid Lightning address format. Expected: username@domain.com'
+        };
+    }
+    try {
+        // Fetch LNURL-pay endpoint
+        const response = await fetch(parsed.lnurlPayUrl, {
+            headers: { 'Accept': 'application/json' }
+        });
+        if (!response.ok) {
+            return {
+                valid: false,
+                info: parsed,
+                error: `Lightning address not found at ${parsed.domain}`
+            };
+        }
+        const data = await response.json();
+        // Verify it's a valid LNURL-pay endpoint
+        if (data.tag !== 'payRequest' && !data.callback) {
+            return {
+                valid: false,
+                info: parsed,
+                error: 'Invalid LNURL-pay response'
+            };
+        }
+        // Parse metadata
+        let description;
+        if (data.metadata) {
+            try {
+                const meta = JSON.parse(data.metadata);
+                const textEntry = meta.find(([type]) => type === 'text/plain');
+                if (textEntry) {
+                    description = textEntry[1];
+                }
+            }
+            catch {
+                // Ignore metadata parsing errors
+            }
+        }
+        return {
+            valid: true,
+            info: {
+                ...parsed,
+                metadata: {
+                    description,
+                    minSendable: data.minSendable,
+                    maxSendable: data.maxSendable,
+                    nostrPubkey: data.nostrPubkey
+                }
+            }
+        };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            info: parsed,
+            error: `Could not reach ${parsed.domain}: ${error instanceof Error ? error.message : 'Network error'}`
+        };
+    }
+}
+// ============================================================
+// COMMON LIGHTNING ADDRESS PROVIDERS
+// ============================================================
+export const KNOWN_PROVIDERS = {
+    'getalby.com': {
+        name: 'Alby',
+        domain: 'getalby.com',
+        signupUrl: 'https://getalby.com'
+    },
+    'walletofsatoshi.com': {
+        name: 'Wallet of Satoshi',
+        domain: 'walletofsatoshi.com',
+        signupUrl: 'https://walletofsatoshi.com'
+    },
+    'ln.tips': {
+        name: 'ln.tips',
+        domain: 'ln.tips',
+        signupUrl: 'https://ln.tips'
+    },
+    'stacker.news': {
+        name: 'Stacker News',
+        domain: 'stacker.news',
+        signupUrl: 'https://stacker.news'
+    },
+    'strike.me': {
+        name: 'Strike',
+        domain: 'strike.me',
+        signupUrl: 'https://strike.me'
+    },
+    'zbd.gg': {
+        name: 'ZBD',
+        domain: 'zbd.gg',
+        signupUrl: 'https://zbd.gg'
+    }
+};
+/**
+ * Get provider info from a Lightning address
+ */
+export function getProviderFromAddress(address) {
+    const parsed = parseLightningAddress(address);
+    if (!parsed)
+        return null;
+    const known = KNOWN_PROVIDERS[parsed.domain];
+    if (known) {
+        return {
+            provider: known.name,
+            signupUrl: known.signupUrl
+        };
+    }
+    return {
+        provider: parsed.domain,
+        signupUrl: `https://${parsed.domain}`
+    };
+}
+// ============================================================
+// PAYMENT HELPERS
+// ============================================================
+/**
+ * Generate a payment request for a Lightning address
+ */
+export async function createPaymentRequest(address, amountSats, comment) {
+    const parsed = parseLightningAddress(address);
+    if (!parsed) {
+        return { success: false, error: 'Invalid Lightning address' };
+    }
+    try {
+        // Get LNURL-pay callback
+        const lnurlResponse = await fetch(parsed.lnurlPayUrl);
+        const lnurlData = await lnurlResponse.json();
+        // Convert sats to millisats
+        const amountMsats = amountSats * 1000;
+        // Check limits
+        if (amountMsats < lnurlData.minSendable) {
+            return {
+                success: false,
+                error: `Amount too small. Minimum: ${lnurlData.minSendable / 1000} sats`
+            };
+        }
+        if (amountMsats > lnurlData.maxSendable) {
+            return {
+                success: false,
+                error: `Amount too large. Maximum: ${lnurlData.maxSendable / 1000} sats`
+            };
+        }
+        // Request invoice
+        const callbackUrl = new URL(lnurlData.callback);
+        callbackUrl.searchParams.set('amount', amountMsats.toString());
+        if (comment) {
+            callbackUrl.searchParams.set('comment', comment);
+        }
+        const invoiceResponse = await fetch(callbackUrl.toString());
+        const invoiceData = await invoiceResponse.json();
+        if (!invoiceData.pr) {
+            return {
+                success: false,
+                error: invoiceData.reason || 'Failed to generate invoice'
+            };
+        }
+        // Extract payment hash from invoice (it's in the BOLT11 encoded)
+        const paymentHash = extractPaymentHash(invoiceData.pr);
+        return {
+            success: true,
+            invoice: invoiceData.pr,
+            paymentHash
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Payment request failed: ${error instanceof Error ? error.message : 'Unknown error'}`
+        };
+    }
+}
+/**
+ * Extract payment hash from BOLT11 invoice
+ * (Simplified - in production use a proper decoder)
+ */
+function extractPaymentHash(bolt11) {
+    // BOLT11 payment hash is typically in a specific position after decoding
+    // For simplicity, we'll generate a placeholder
+    // In production, use a library like bolt11 or lightningpay
+    try {
+        const hash = bolt11.substring(0, 64);
+        return hash;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ============================================================
+// CREDIT CONVERSION
+// ============================================================
+// mcpSovereign: 1,000 credits = $1 = 10,000 sats
+export const CREDITS_PER_SAT = 0.1; // 1 sat = 0.1 credits
+export const SATS_PER_CREDIT = 10; // 1 credit = 10 sats
+export function creditsToSats(credits) {
+    return Math.ceil(credits * SATS_PER_CREDIT);
+}
+export function satsToCredits(sats) {
+    return Math.floor(sats * CREDITS_PER_SAT);
+}
+export function satsToDollars(sats, btcPrice = 100000) {
+    // 1 BTC = 100,000,000 sats
+    return (sats / 100_000_000) * btcPrice;
+}
+export function dollarsToSats(dollars, btcPrice = 100000) {
+    return Math.ceil((dollars / btcPrice) * 100_000_000);
+}
+// ============================================================
+// FORMATTING
+// ============================================================
+export function formatSats(sats) {
+    if (sats >= 100_000_000) {
+        return `${(sats / 100_000_000).toFixed(2)} BTC`;
+    }
+    if (sats >= 1_000_000) {
+        return `${(sats / 1_000_000).toFixed(2)}M sats`;
+    }
+    if (sats >= 1_000) {
+        return `${(sats / 1_000).toFixed(1)}k sats`;
+    }
+    return `${sats} sats`;
+}
+export function formatCredits(credits) {
+    if (credits >= 1_000_000) {
+        return `${(credits / 1_000_000).toFixed(2)}M credits`;
+    }
+    if (credits >= 1_000) {
+        return `${(credits / 1_000).toFixed(1)}k credits`;
+    }
+    return `${credits} credits`;
+}

package/dist/wallet/lnd-setup.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Automated LND Setup for mcpSovereign
+ *
+ * This module handles:
+ * 1. Docker installation check
+ * 2. LND container deployment (Neutrino mode - no full node needed)
+ * 3. Wallet creation
+ * 4. Credential extraction
+ * 5. Configuration for SDK
+ *
+ * Based on the same setup used for mcpsovereign.com
+ */
+export interface LNDConfig {
+    containerName: string;
+    network: 'mainnet' | 'testnet' | 'regtest';
+    alias: string;
+    restPort: number;
+    grpcPort: number;
+    p2pPort: number;
+    dataDir: string;
+}
+export interface LNDCredentials {
+    tlsCert: string;
+    adminMacaroon: string;
+    restHost: string;
+    grpcHost: string;
+}
+export interface SetupResult {
+    success: boolean;
+    credentials?: LNDCredentials;
+    walletSeed?: string[];
+    error?: string;
+    logs: string[];
+}
+export declare class LNDSetup {
+    private config;
+    private logs;
+    constructor(config?: Partial<LNDConfig>);
+    private log;
+    /**
+     * Check if system is ready for LND setup
+     */
+    checkPrerequisites(): Promise<{
+        ready: boolean;
+        docker: {
+            installed: boolean;
+            running: boolean;
+            version?: string;
+        };
+        compose: boolean;
+        diskSpace: {
+            available: number;
+            required: number;
+            sufficient: boolean;
+        };
+    }>;
+    /**
+     * Install Docker if not present (Linux only)
+     */
+    installDocker(): Promise<boolean>;
+    /**
+     * Set up LND container
+     */
+    setupLND(): Promise<SetupResult>;
+    /**
+     * Wait for LND REST API to be available
+     */
+    private waitForLND;
+    /**
+     * Check if wallet already exists
+     */
+    private checkWalletExists;
+    /**
+     * Create new LND wallet
+     */
+    private createWallet;
+    /**
+     * Wait for Neutrino to sync
+     */
+    private waitForSync;
+    /**
+     * Extract LND credentials for SDK use
+     */
+    private extractCredentials;
+    /**
+     * Generate a secure random password
+     */
+    private generatePassword;
+    /**
+     * Get container status
+     */
+    getStatus(): Promise<{
+        running: boolean;
+        synced: boolean;
+        blockHeight?: number;
+        peers?: number;
+        channels?: number;
+        balance?: {
+            confirmed: number;
+            unconfirmed: number;
+        };
+    }>;
+    /**
+     * Stop LND container
+     */
+    stop(): Promise<boolean>;
+    /**
+     * Start LND container (if stopped)
+     */
+    start(): Promise<boolean>;
+    getLogs(): string[];
+}
+/**
+ * Quick setup for agents who want their own node
+ */
+export declare function quickSetupLND(alias?: string): Promise<SetupResult>;
+export default LNDSetup;