@kadi.build/deploy-ability 0.0.1

package/dist/targets/akash/wallet-manager.js

@@ -0,0 +1,953 @@
+/**
+ * Akash Network Wallet Connection Module
+ *
+ * Provides a clean, step-by-step API for connecting to Keplr wallet via WalletConnect.
+ * This is a LIBRARY - no QR code display, no prompts, just pure wallet operations.
+ *
+ * Key Improvements from kadi-deploy:
+ * - ✅ ZERO CLI dependencies (no QRCode, chalk, enquirer)
+ * - ✅ ZERO `any` types (was 5 any types)
+ * - ✅ Split into 4 clear steps for composability
+ * - ✅ Result types for all operations
+ * - ✅ Natural, intuitive API design
+ *
+ * Architecture:
+ * ```
+ * Step 1: initWalletConnect()     → Create SignClient
+ *    ↓
+ * Step 2: generateConnectionUri() → Get URI for QR code
+ *    ↓
+ * Step 3: waitForApproval()       → Poll for user approval
+ *    ↓
+ * Step 4: createWalletContext()   → Get ready-to-use wallet
+ * ```
+ *
+ * Design Philosophy:
+ * Each step is independent and composable. Callers can:
+ * - Display QR codes however they want (terminal, web, mobile)
+ * - Add their own timeout logic
+ * - Implement custom retry mechanisms
+ * - Show progress however they prefer
+ *
+ * @module targets/akash/wallet
+ */
+import { SignClient } from '@walletconnect/sign-client';
+import { KeplrWalletConnectV2 } from '@keplr-wallet/wc-client';
+import { fromHex } from '@cosmjs/encoding';
+import { StargateClient } from '@cosmjs/stargate';
+import { WalletError, WalletErrorCodes } from '../../errors/index.js';
+import { getNetworkConfig } from './environment.js';
+/**
+ * Step 1: Initialize WalletConnect client
+ *
+ * Creates a WalletConnect SignClient with proper configuration.
+ * This is a one-time setup that can be reused for multiple connections.
+ *
+ * @param projectId - WalletConnect Cloud project ID
+ * @param metadata - Optional app metadata (defaults to KADI Deploy)
+ * @returns Result with WalletConnect client or error
+ *
+ * @example
+ * ```typescript
+ * // Initialize with your project ID
+ * const clientResult = await initWalletConnect('your-project-id-here');
+ *
+ * if (!clientResult.success) {
+ *   console.error('Failed to initialize:', clientResult.error);
+ *   return;
+ * }
+ *
+ * const wcClient = clientResult.data;
+ * console.log('WalletConnect ready!');
+ * ```
+ */
+export async function initWalletConnect(projectId, metadata) {
+    try {
+        // Step 1: Validate project ID
+        if (!projectId || projectId.trim().length === 0) {
+            return {
+                success: false,
+                error: new WalletError('WalletConnect project ID is required', WalletErrorCodes.MISSING_PROJECT_ID, { projectId })
+            };
+        }
+        // Step 2: Prepare metadata (use defaults if not provided)
+        const appMetadata = metadata || {
+            name: 'KADI Deploy',
+            description: 'Deploy to Akash Network',
+            url: 'https://kadi.build',
+            icons: ['https://kadi.build/icon.png']
+        };
+        // Step 3: Initialize SignClient
+        // This creates the WalletConnect client that manages all connections
+        const client = await SignClient.init({
+            projectId,
+            metadata: appMetadata
+        });
+        // Step 4: Return initialized client
+        return {
+            success: true,
+            data: {
+                client,
+                metadata: appMetadata
+            }
+        };
+    }
+    catch (error) {
+        // Step 5: Handle initialization errors
+        return {
+            success: false,
+            error: new WalletError(`Failed to initialize WalletConnect: ${error}`, WalletErrorCodes.INIT_FAILED, { error: String(error) })
+        };
+    }
+}
+/**
+ * Step 2: Generate connection URI for QR code display
+ *
+ * Creates a new pairing and generates the WalletConnect URI.
+ * The caller is responsible for displaying this URI as a QR code.
+ *
+ * @param wcClient - Initialized WalletConnect client from step 1
+ * @param network - Akash network to connect to
+ * @returns Result with URI and pairing info or error
+ *
+ * @example
+ * ```typescript
+ * // Generate URI for QR code
+ * const uriResult = await generateConnectionUri(wcClient, 'mainnet');
+ *
+ * if (!uriResult.success) {
+ *   console.error('Failed to generate URI:', uriResult.error);
+ *   return;
+ * }
+ *
+ * const { uri, pairingTopic, approval } = uriResult.data;
+ *
+ * // Caller displays QR code however they want:
+ * // - Terminal: QRCode.generate(uri)
+ * // - Web: <QRCode value={uri} />
+ * // - Or just show as text: console.log(uri)
+ * console.log('Scan this QR code:', uri);
+ * ```
+ */
+export async function generateConnectionUri(wcClient, network) {
+    try {
+        // Step 1: Get network configuration
+        const networkConfig = getNetworkConfig(network);
+        const chainId = `cosmos:${networkConfig.chainId}`;
+        // Step 2: Define optional namespaces for Akash
+        // This tells the wallet what permissions we need
+        // Using optionalNamespaces (new API) instead of deprecated requiredNamespaces
+        const optionalNamespaces = {
+            cosmos: {
+                chains: [chainId],
+                methods: [
+                    'cosmos_signDirect', // For transaction signing
+                    'cosmos_signAmino', // Legacy signing support
+                    'cosmos_getAccounts' // To get wallet address
+                ],
+                events: []
+            }
+        };
+        // Step 3: Create connection request
+        // This generates the URI and starts waiting for approval
+        const { uri, approval } = await wcClient.client.connect({
+            optionalNamespaces
+        });
+        // Step 4: Validate URI was generated
+        if (!uri) {
+            return {
+                success: false,
+                error: new WalletError('Failed to generate connection URI', WalletErrorCodes.URI_GENERATION_FAILED, { network })
+            };
+        }
+        // Step 5: Return URI and approval promise
+        // This matches the original kadi-deploy behavior
+        return {
+            success: true,
+            data: {
+                uri,
+                approval
+            }
+        };
+    }
+    catch (error) {
+        // Step 7: Handle connection errors
+        return {
+            success: false,
+            error: new WalletError(`Failed to generate connection URI: ${error}`, WalletErrorCodes.CONNECTION_FAILED, { error: String(error) })
+        };
+    }
+}
+/**
+ * Step 3: Wait for user to approve connection
+ *
+ * Polls for wallet approval with configurable timeout.
+ * Returns immediately when user approves or rejects.
+ *
+ * @param approval - Approval promise from step 2
+ * @param timeoutMs - Maximum wait time in milliseconds (default: 5 minutes)
+ * @returns Result with approved session or error
+ *
+ * @example
+ * ```typescript
+ * // Wait for user to scan QR and approve
+ * console.log('Waiting for approval...');
+ *
+ * const approvalResult = await waitForApproval(
+ *   approval,
+ *   60000 // 60 second timeout
+ * );
+ *
+ * if (!approvalResult.success) {
+ *   if (approvalResult.error.code === 'APPROVAL_TIMEOUT') {
+ *     console.log('User did not approve in time');
+ *   } else if (approvalResult.error.code === 'APPROVAL_REJECTED') {
+ *     console.log('User rejected connection');
+ *   }
+ *   return;
+ * }
+ *
+ * const { session, address } = approvalResult.data;
+ * console.log(`Connected to ${address}!`);
+ * ```
+ */
+export async function waitForApproval(approval, timeoutMs = 300000 // 5 minutes default
+) {
+    try {
+        // Step 1: Create timeout promise
+        // This races against the approval to implement timeout
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new Error('Connection timeout'));
+            }, timeoutMs);
+        });
+        // Step 2: Race approval against timeout
+        // Whichever resolves first wins
+        const session = await Promise.race([
+            approval(),
+            timeoutPromise
+        ]);
+        // Step 3: Extract account info from session
+        // The session contains the connected accounts
+        const accounts = session.namespaces.cosmos?.accounts || [];
+        if (accounts.length === 0) {
+            return {
+                success: false,
+                error: new WalletError('No accounts found in session', WalletErrorCodes.NO_ACCOUNTS, { session })
+            };
+        }
+        // Step 4: Parse account address and chain
+        // Format: "cosmos:chainid:address"
+        const [_namespace, chainId, address] = accounts[0].split(':');
+        // Validate parsed values
+        if (!chainId || !address) {
+            return {
+                success: false,
+                error: new WalletError('Invalid account format in session', WalletErrorCodes.ACCOUNT_NOT_FOUND, { account: accounts[0] })
+            };
+        }
+        // Step 5: Return approval result
+        return {
+            success: true,
+            data: {
+                session,
+                address,
+                chainId
+            }
+        };
+    }
+    catch (error) {
+        // Step 6: Handle timeout or rejection
+        const errorMessage = String(error);
+        if (errorMessage.includes('timeout')) {
+            return {
+                success: false,
+                error: new WalletError('Connection approval timed out', WalletErrorCodes.APPROVAL_TIMEOUT, { timeoutMs })
+            };
+        }
+        if (errorMessage.includes('rejected') || errorMessage.includes('cancelled')) {
+            return {
+                success: false,
+                error: new WalletError('User rejected connection', WalletErrorCodes.APPROVAL_REJECTED, {})
+            };
+        }
+        // Step 7: Handle other errors
+        return {
+            success: false,
+            error: new WalletError(`Approval failed: ${error}`, WalletErrorCodes.APPROVAL_FAILED, { error: errorMessage })
+        };
+    }
+}
+/**
+ * Step 4: Create complete wallet context for Akash operations
+ *
+ * Finalizes the connection by creating signers and querying account data.
+ * Returns a ready-to-use WalletContext for all Akash operations.
+ *
+ * @param wcClient - WalletConnect client from step 1
+ * @param approvalResult - Approval result from step 3
+ * @param network - Akash network being used
+ * @returns Result with complete wallet context or error
+ *
+ * @example
+ * ```typescript
+ * // Create final wallet context
+ * const walletResult = await createWalletContext(
+ *   wcClient,
+ *   approvalResult.data,
+ *   'mainnet'
+ * );
+ *
+ * if (!walletResult.success) {
+ *   console.error('Failed to create wallet:', walletResult.error);
+ *   return;
+ * }
+ *
+ * const wallet = walletResult.data;
+ * console.log('Wallet ready!');
+ * console.log('Address:', wallet.address);
+ * console.log('Chain:', wallet.chainId);
+ *
+ * // Now ready for Akash operations
+ * const deployment = await deployToAkash({ wallet, ... });
+ * ```
+ */
+export async function createWalletContext(wcClient, approvalResult, network) {
+    try {
+        // Step 1: Get network configuration
+        const networkConfig = getNetworkConfig(network);
+        const chainId = networkConfig.chainId;
+        // Step 2: Create Keplr wallet instance via WalletConnect
+        // This wraps the WalletConnect session in a Keplr-compatible interface
+        const keplr = new KeplrWalletConnectV2(wcClient.client, approvalResult.session);
+        // Step 3: Get offline signer for transaction signing
+        // This is the main interface for signing transactions
+        // Note: There's a known type incompatibility between @keplr-wallet/types and @cosmjs/proto-signing
+        // (SignDoc.accountNumber: Long vs bigint). The runtime objects work fine - this is TypeScript only.
+        // We use 'as unknown as' to force the cast since TS knows the types are incompatible.
+        const offlineSigner = keplr.getOfflineSigner(chainId);
+        // Step 4: Get accounts from signer
+        // This should match the approved account
+        const accounts = await offlineSigner.getAccounts();
+        if (accounts.length === 0) {
+            return {
+                success: false,
+                error: new WalletError('No accounts available from signer', WalletErrorCodes.NO_SIGNER_ACCOUNTS, { chainId })
+            };
+        }
+        // Step 5: Connect to blockchain to get account details
+        // We need account number and sequence for transactions
+        const stargateClient = await StargateClient.connect(networkConfig.rpc);
+        let accountData;
+        try {
+            const account = await stargateClient.getAccount(accounts[0].address);
+            if (account) {
+                accountData = {
+                    address: account.address,
+                    pubkey: account.pubkey ? fromHex(account.pubkey.value) : null,
+                    accountNumber: account.accountNumber,
+                    sequence: account.sequence
+                };
+            }
+        }
+        catch (error) {
+            // Account might not exist on chain yet (new account)
+            // This is OK - account will be created with first transaction
+            accountData = undefined;
+        }
+        finally {
+            // Step 6: Always disconnect Stargate client
+            stargateClient.disconnect();
+        }
+        // Step 7: Create complete wallet context
+        const walletContext = {
+            address: accounts[0].address,
+            signer: offlineSigner,
+            offlineSigner: offlineSigner,
+            signClient: wcClient.client,
+            session: approvalResult.session,
+            chainId: chainId,
+            account: accountData
+        };
+        // Step 8: Return ready-to-use wallet
+        return {
+            success: true,
+            data: walletContext
+        };
+    }
+    catch (error) {
+        // Step 9: Handle creation errors
+        return {
+            success: false,
+            error: new WalletError(`Failed to create wallet context: ${error}`, WalletErrorCodes.CONTEXT_CREATION_FAILED, { error: String(error) })
+        };
+    }
+}
+/**
+ * Create wallet context from any offline signer
+ *
+ * Use this for **automated deployments** where you have direct access to a signer
+ * (e.g., agent wallet, CI/CD, hardware wallet, KMS) instead of interactive wallet
+ * connection via browser or WalletConnect.
+ *
+ * **Security Model:**
+ * This function accepts a **signer interface**, NOT a private key or mnemonic!
+ * The signer can sign transactions without exposing the underlying key.
+ *
+ * **Common Use Cases:**
+ * - Self-deploying agents (signer from encrypted storage)
+ * - CI/CD pipelines (signer from secrets manager)
+ * - Hardware wallets (Ledger - key never leaves device)
+ * - Cloud KMS (AWS/GCP - key stays in cloud)
+ * - Multi-signature wallets (threshold signing)
+ *
+ * @param signer - Any offline signer (must implement OfflineAminoSigner & OfflineDirectSigner)
+ * @param network - Akash network to connect to
+ * @returns Result with wallet context ready for deployments
+ *
+ * @example Agent with encrypted wallet
+ * ```typescript
+ * import { DirectSecp256k1Wallet } from '@cosmjs/proto-signing';
+ * import { createWalletContextFromSigner } from 'deploy-ability/akash';
+ *
+ * // Agent loads signer from secure storage (mnemonic never exposed to caller)
+ * const agentSigner = await myAgent.wallet.getSigner();
+ *
+ * // Create wallet context
+ * const walletCtx = await createWalletContextFromSigner(agentSigner, 'mainnet');
+ *
+ * if (walletCtx.success) {
+ *   // Ready to deploy - signer will handle signing internally
+ *   await deployToAkash({
+ *     wallet: walletCtx.data,
+ *     certificate: cert,
+ *     projectRoot: './',
+ *     profile: 'prod'
+ *   });
+ * }
+ * ```
+ *
+ * @example CI/CD with secrets manager
+ * ```typescript
+ * // Load signer from AWS Secrets Manager / GitHub Secrets
+ * const mnemonic = await loadFromSecretsManager('deploy-wallet-key');
+ * const signer = await DirectSecp256k1Wallet.fromMnemonic(mnemonic, {
+ *   prefix: 'akash'
+ * });
+ *
+ * const walletCtx = await createWalletContextFromSigner(signer, 'testnet');
+ * // Now deploy without any user interaction
+ * ```
+ *
+ * @example Hardware wallet (Ledger)
+ * ```typescript
+ * import Ledger from '@cosmjs/ledger-amino';
+ *
+ * // Connect to Ledger - key never leaves device
+ * const transport = await TransportWebUSB.create();
+ * const ledgerSigner = new Ledger(transport, {
+ *   hdPaths: [makeCosmoshubPath(0)],
+ *   prefix: 'akash'
+ * });
+ *
+ * const walletCtx = await createWalletContextFromSigner(ledgerSigner, 'mainnet');
+ * // Ledger will prompt for approval when signing
+ * ```
+ *
+ * @example Cloud KMS
+ * ```typescript
+ * // Custom signer using AWS KMS / GCP KMS
+ * class KmsSigner implements OfflineSigner {
+ *   constructor(private keyId: string) {}
+ *
+ *   async signDirect(address: string, signDoc: SignDoc) {
+ *     // Sign using KMS - key never leaves cloud
+ *     return await kms.sign(this.keyId, signDoc);
+ *   }
+ * }
+ *
+ * const kmsSigner = new KmsSigner('arn:aws:kms:...');
+ * const walletCtx = await createWalletContextFromSigner(kmsSigner, 'mainnet');
+ * ```
+ */
+export async function createWalletContextFromSigner(signer, network) {
+    try {
+        // Step 1: Get network configuration
+        const networkConfig = getNetworkConfig(network);
+        // Step 2: Get accounts from signer
+        // The signer provides accounts without exposing private keys
+        const accounts = await signer.getAccounts();
+        if (accounts.length === 0) {
+            return {
+                success: false,
+                error: new WalletError('No accounts available from signer', WalletErrorCodes.NO_SIGNER_ACCOUNTS, { network }),
+            };
+        }
+        const address = accounts[0].address;
+        // Step 3: Connect to blockchain to get account details
+        // We need account number and sequence for transactions
+        const stargateClient = await StargateClient.connect(networkConfig.rpc);
+        let accountData;
+        try {
+            const account = await stargateClient.getAccount(address);
+            if (account) {
+                accountData = {
+                    address: account.address,
+                    pubkey: account.pubkey ? fromHex(Buffer.from(account.pubkey.value).toString('hex')) : null,
+                    accountNumber: account.accountNumber,
+                    sequence: account.sequence,
+                };
+            }
+        }
+        finally {
+            // Always disconnect the query client
+            stargateClient.disconnect();
+        }
+        // Step 4: Create wallet context
+        // Note: No WalletConnect client or session - this is for direct signer usage
+        const walletContext = {
+            address,
+            signer,
+            offlineSigner: signer,
+            chainId: networkConfig.chainId,
+            account: accountData,
+            // signClient and session are undefined - only used for WalletConnect
+        };
+        return {
+            success: true,
+            data: walletContext,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: new WalletError(`Failed to create wallet context from signer: ${error}`, WalletErrorCodes.CONTEXT_CREATION_FAILED, { error: String(error), network }),
+        };
+    }
+}
+/**
+ * Disconnect an active WalletConnect session
+ *
+ * Cleanly disconnects from the wallet, clearing the session and cleaning up
+ * all internal resources (relay transport, heartbeat, event listeners).
+ *
+ * This ensures the Node.js event loop can exit by releasing all timers and
+ * connections. Without this cleanup, the WalletConnect client keeps the
+ * process alive indefinitely.
+ *
+ * Always call this when done with wallet operations to prevent hanging.
+ *
+ * Note: This only applies to WalletConnect sessions. Wallets created
+ * with `createWalletContextFromSigner()` don't need disconnection.
+ *
+ * @param wallet - Wallet context to disconnect
+ * @returns Result indicating success or error
+ *
+ * @example
+ * ```typescript
+ * // Disconnect when done
+ * const result = await disconnectWallet(wallet);
+ *
+ * if (result.success) {
+ *   console.log('Wallet disconnected');
+ * } else {
+ *   console.warn('Disconnect failed:', result.error);
+ * }
+ * ```
+ */
+export async function disconnectWallet(wallet) {
+    try {
+        // Step 1: Check if WalletConnect session exists
+        if (!wallet.signClient || !wallet.session) {
+            // Not a WalletConnect wallet (maybe browser extension)
+            return { success: true, data: undefined };
+        }
+        try {
+            // Step 2: Disconnect the session
+            await wallet.signClient.disconnect({
+                topic: wallet.session.topic,
+                reason: {
+                    code: 1,
+                    message: 'User disconnected'
+                }
+            });
+        }
+        finally {
+            // Step 3: Clean up internal WalletConnect resources
+            // This is critical to allow Node.js event loop to exit
+            try {
+                // Close relay WebSocket transport
+                await wallet.signClient.core.relayer.transportClose();
+            }
+            catch (err) {
+                // Ignore transport close errors
+            }
+            try {
+                // Stop heartbeat timer
+                wallet.signClient.core.heartbeat?.stop();
+            }
+            catch (err) {
+                // Ignore heartbeat stop errors
+            }
+            try {
+                // Remove all event listeners to prevent memory leaks
+                // Pass undefined to remove all listeners for all events
+                if (wallet.signClient.core.events.removeAllListeners) {
+                    wallet.signClient.core.events.removeAllListeners(undefined);
+                }
+                if (wallet.signClient.removeAllListeners) {
+                    wallet.signClient.removeAllListeners(undefined);
+                }
+            }
+            catch (err) {
+                // Ignore listener removal errors
+            }
+            try {
+                // ================================================================
+                // STORAGE CLEANUP - THE RUSSIAN DOLL PROBLEM
+                // ================================================================
+                //
+                // WHY IS THIS NECESSARY?
+                // WalletConnect persists session data to disk using the "unstorage" library.
+                // Unstorage uses a filesystem driver that creates a "chokidar" file watcher
+                // to monitor the storage files for changes. File watchers keep Node.js alive
+                // indefinitely - the process will NEVER exit until they're explicitly closed.
+                //
+                // WHY THE WEIRD NESTING?
+                // WalletConnect uses a "wrapper pattern" (like Russian dolls 🪆):
+                //
+                //   Layer 1: storage (wrapper with high-level API)
+                //     └─ Has methods: getItem(), setItem(), initialize()
+                //     └─ DOES NOT have cleanup methods!
+                //
+                //   Layer 2: storage.database (queue manager)
+                //     └─ Manages write operations with a queue
+                //     └─ Still DOES NOT have cleanup methods!
+                //
+                //   Layer 3: storage.database.database (ACTUAL DRIVER)
+                //     └─ This is the real filesystem driver (unstorage/fs)
+                //     └─ THIS is where unwatch() and dispose() live!
+                //     └─ THIS is where the chokidar file watcher exists!
+                //
+                // WHY DESIGN IT THIS WAY?
+                // Each wrapper adds functionality:
+                // - Outer wrapper: Simple API for WalletConnect to use
+                // - Middle wrapper: Batches writes for better performance
+                // - Inner driver: Actually talks to the filesystem
+                //
+                // It's like a restaurant:
+                // - Customer (WalletConnect) → talks to waiter (storage wrapper)
+                // - Waiter → gives orders to kitchen manager (database queue)
+                // - Kitchen manager → tells chef (actual fs driver) to cook
+                //
+                // To turn off the stove (file watcher), you need to tell the chef directly,
+                // not the waiter! That's why we must drill down to the innermost layer.
+                //
+                // ================================================================
+                const storage = wallet.signClient.core?.storage;
+                // DRILL DOWN: storage → database → database (innermost layer)
+                // This is where the actual filesystem driver lives with the file watcher
+                const innerDb = storage?.database?.database;
+                if (innerDb) {
+                    // Call unwatch() to stop the chokidar file watcher
+                    // Without this, the file watcher keeps Node.js event loop alive forever!
+                    if (typeof innerDb.unwatch === 'function') {
+                        await innerDb.unwatch().catch(() => { });
+                    }
+                    // Call dispose() to clean up any other resources (file handles, caches, etc.)
+                    if (typeof innerDb.dispose === 'function') {
+                        await innerDb.dispose().catch(() => { });
+                    }
+                }
+            }
+            catch (err) {
+                // Silently ignore storage cleanup errors during shutdown
+            }
+        }
+        // Step 4: Return success
+        return { success: true, data: undefined };
+    }
+    catch (error) {
+        // Step 5: Handle disconnect errors (non-fatal)
+        return {
+            success: false,
+            error: new WalletError(`Failed to disconnect wallet: ${error}`, WalletErrorCodes.DISCONNECT_FAILED, { error: String(error) })
+        };
+    }
+}
+/**
+ * Complete wallet connection flow (convenience function)
+ *
+ * Combines all 4 steps into a single function for simple use cases.
+ * For more control, use the individual step functions.
+ *
+ * @param projectId - WalletConnect project ID
+ * @param network - Akash network to connect to
+ * @param options - Optional configuration
+ * @returns Result with wallet context or error
+ *
+ * @example
+ * ```typescript
+ * // Simple one-call connection
+ * const walletResult = await connectWallet(
+ *   'your-project-id',
+ *   'mainnet',
+ *   {
+ *     onUriGenerated: (uri) => {
+ *       // Display QR code
+ *       QRCode.generate(uri);
+ *       console.log('Scan QR code with Keplr');
+ *     },
+ *     timeoutMs: 60000
+ *   }
+ * );
+ *
+ * if (!walletResult.success) {
+ *   console.error('Connection failed:', walletResult.error);
+ *   return;
+ * }
+ *
+ * const wallet = walletResult.data;
+ * console.log('Connected to:', wallet.address);
+ * ```
+ */
+export async function connectWallet(projectId, network, options) {
+    // Step 1: Initialize WalletConnect
+    const clientResult = await initWalletConnect(projectId, options?.metadata);
+    if (!clientResult.success) {
+        return clientResult;
+    }
+    // Step 2: Generate connection URI
+    const uriResult = await generateConnectionUri(clientResult.data, network);
+    if (!uriResult.success) {
+        return uriResult;
+    }
+    // Step 3: Notify caller of URI (for QR display)
+    if (options?.onUriGenerated) {
+        options.onUriGenerated(uriResult.data.uri);
+    }
+    // Step 4: Wait for approval
+    const approvalResult = await waitForApproval(uriResult.data.approval, options?.timeoutMs);
+    if (!approvalResult.success) {
+        return approvalResult;
+    }
+    // Step 5: Create wallet context
+    return createWalletContext(clientResult.data, approvalResult.data, network);
+}
+/**
+ * Create wallet context from mnemonic (for agent-controlled wallets)
+ *
+ * ⚠️ **CRITICAL SECURITY WARNING** ⚠️
+ *
+ * This function is ONLY for scenarios where YOU control the mnemonic:
+ * - ✅ Your own automation (CI/CD, personal scripts)
+ * - ✅ Your own agent (running on infrastructure you control)
+ * - ✅ Custodial services YOU operate (creating wallets for your users)
+ *
+ * **NEVER use this if:**
+ * - ❌ Someone else's agent asks for your mnemonic
+ * - ❌ Third-party service requests your mnemonic
+ * - ❌ You don't fully control where the mnemonic is stored/used
+ *
+ * **For third-party agents/services:**
+ * Use `connectWallet()` with WalletConnect instead! This lets you approve
+ * transactions on YOUR device without exposing your mnemonic.
+ *
+ * **Security Model:**
+ * ```
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │ WHO CONTROLS THE AGENT?                                      │
+ * ├─────────────────────────────────────────────────────────────┤
+ * │                                                              │
+ * │  YOU control it:                                            │
+ * │  ✅ createWalletFromMnemonic() - You trust your own code    │
+ * │                                                              │
+ * │  SOMEONE ELSE controls it:                                  │
+ * │  ✅ connectWallet() - WalletConnect for approval           │
+ * │  ❌ createWalletFromMnemonic() - NEVER share mnemonic!      │
+ * │                                                              │
+ * └─────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * **Common Use Cases:**
+ *
+ * @example 1. Your own CI/CD pipeline
+ * ```typescript
+ * // Mnemonic stored in GitHub Secrets / GitLab CI Variables
+ * const mnemonic = process.env.DEPLOYMENT_WALLET_MNEMONIC!;
+ * const wallet = await createWalletFromMnemonic(mnemonic, 'mainnet');
+ *
+ * if (wallet.success) {
+ *   // Automated deployment from CI/CD
+ *   await deployToAkash({
+ *     wallet: wallet.data,
+ *     projectRoot: './',
+ *     profile: 'production'
+ *   });
+ * }
+ * ```
+ *
+ * @example 2. Your own agent with encrypted storage
+ * ```typescript
+ * // Agent loads its OWN mnemonic (not user's!)
+ * class DeploymentAgent {
+ *   async deploy(projectConfig: Config) {
+ *     // Agent uses its own wallet to pay for deployments
+ *     const mnemonic = await this.secrets.getEncryptedMnemonic();
+ *     const wallet = await createWalletFromMnemonic(mnemonic, 'mainnet');
+ *
+ *     if (wallet.success) {
+ *       // Agent deploys using its own funds
+ *       return deployToAkash({
+ *         wallet: wallet.data,
+ *         ...projectConfig
+ *       });
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example 3. Custodial wallet service (you operate the service)
+ * ```typescript
+ * // Service creates and manages wallets FOR users
+ * class CustodialWalletService {
+ *   async createUserWallet(userId: string) {
+ *     // Generate new wallet for user
+ *     const { DirectSecp256k1HdWallet } = await import('@cosmjs/proto-signing');
+ *     const newWallet = await DirectSecp256k1HdWallet.generate(24);
+ *     const mnemonic = newWallet.mnemonic;
+ *
+ *     // Store encrypted mnemonic in your secure database
+ *     await this.db.storeEncryptedMnemonic(userId, mnemonic);
+ *
+ *     return { userId, address: (await newWallet.getAccounts())[0].address };
+ *   }
+ *
+ *   async deployForUser(userId: string, projectConfig: Config) {
+ *     // Load user's mnemonic from secure storage
+ *     const mnemonic = await this.db.getDecryptedMnemonic(userId);
+ *     const wallet = await createWalletFromMnemonic(mnemonic, 'mainnet');
+ *
+ *     if (wallet.success) {
+ *       // Deploy on user's behalf
+ *       return deployToAkash({
+ *         wallet: wallet.data,
+ *         ...projectConfig
+ *       });
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example 4. WRONG - Never do this!
+ * ```typescript
+ * // ❌ DANGEROUS - Third-party agent asking for your mnemonic!
+ * const thirdPartyAgent = new SomeoneElsesAgent();
+ *
+ * // ❌ DO NOT DO THIS!
+ * await thirdPartyAgent.deploy({
+ *   mnemonic: myMnemonic,  // ❌ Now they can steal all your funds!
+ *   project: './my-app'
+ * });
+ *
+ * // ✅ DO THIS INSTEAD - Use WalletConnect!
+ * const wallet = await connectWallet(projectId, 'mainnet', {
+ *   onUriGenerated: (uri) => {
+ *     console.log('Scan QR code to approve');
+ *     // You approve on YOUR device, agent never gets mnemonic
+ *   }
+ * });
+ * await thirdPartyAgent.deploy({ wallet: wallet.data, ... });
+ * ```
+ *
+ * **Implementation Notes for Future:**
+ *
+ * This function should:
+ * 1. Import DirectSecp256k1HdWallet from @cosmjs/proto-signing
+ * 2. Create signer with proper network prefix:
+ *    - mainnet/testnet → 'akash'
+ *    - sandbox → 'akash'
+ * 3. Call createWalletContextFromSigner() with the signer
+ * 4. Return Result<WalletContext, WalletError>
+ *
+ * Dependencies needed:
+ * - @cosmjs/proto-signing (DirectSecp256k1HdWallet)
+ *
+ * Error handling:
+ * - Invalid mnemonic format
+ * - Network configuration issues
+ * - Account fetch failures
+ *
+ * @param mnemonic - BIP39 mnemonic phrase (12 or 24 words)
+ * @param network - Akash network to connect to
+ * @returns Result with wallet context or error
+ */
+export async function createWalletFromMnemonic(_mnemonic, network) {
+    // TODO: Implement mnemonic → wallet conversion
+    //
+    // Implementation plan:
+    //
+    // 1. Validate mnemonic format (should be 12 or 24 words)
+    //    - Split by whitespace and count words
+    //    - Return error if invalid length
+    //
+    // 2. Import DirectSecp256k1HdWallet from @cosmjs/proto-signing
+    //    - This is the standard CosmJS wallet for Cosmos chains
+    //    - Handles BIP39 mnemonic → keypair derivation
+    //
+    // 3. Create signer with Akash address prefix
+    //    const signer = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic, {
+    //      prefix: 'akash'  // All Akash networks use 'akash' prefix
+    //    });
+    //
+    // 4. Delegate to existing createWalletContextFromSigner()
+    //    return createWalletContextFromSigner(signer, network);
+    //
+    // Error cases to handle:
+    // - Invalid mnemonic (wrong word count, invalid words)
+    // - Network configuration issues (passed through from createWalletContextFromSigner)
+    // - Account fetch failures (passed through from createWalletContextFromSigner)
+    //
+    // Example implementation:
+    //
+    // try {
+    //   // Validate mnemonic word count
+    //   const words = mnemonic.trim().split(/\s+/);
+    //   if (![12, 15, 18, 21, 24].includes(words.length)) {
+    //     return {
+    //       success: false,
+    //       error: new WalletError(
+    //         `Invalid mnemonic: expected 12, 15, 18, 21, or 24 words, got ${words.length}`,
+    //         WalletErrorCodes.INVALID_MNEMONIC,
+    //         { wordCount: words.length }
+    //       ),
+    //     };
+    //   }
+    //
+    //   // Import CosmJS wallet
+    //   const { DirectSecp256k1HdWallet } = await import('@cosmjs/proto-signing');
+    //
+    //   // Create signer from mnemonic
+    //   const signer = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic, {
+    //     prefix: 'akash'
+    //   });
+    //
+    //   // Delegate to existing function
+    //   return createWalletContextFromSigner(signer, network);
+    // } catch (error) {
+    //   return {
+    //     success: false,
+    //     error: new WalletError(
+    //       `Failed to create wallet from mnemonic: ${error}`,
+    //       WalletErrorCodes.MNEMONIC_CREATION_FAILED,
+    //       { error: String(error), network }
+    //     ),
+    //   };
+    // }
+    // Temporary implementation - will be replaced with above
+    return {
+        success: false,
+        error: new WalletError('createWalletFromMnemonic() not yet implemented - see TODO in function body', WalletErrorCodes.NOT_IMPLEMENTED, { network }),
+    };
+}
+//# sourceMappingURL=wallet-manager.js.map