feat: Add flexible wallet configuration supporting private key or mnemonic phrase, centralize wallet logic, and update documentation.

Author: wayzeek

README.md

@@ -83,6 +83,7 @@ All services are exposed through a consistent interface of MCP tools, resources,
 
 ### Comprehensive Transaction Support
 
+- **Flexible Wallet Support** - Configure with Private Key or Mnemonic (BIP-39) with HD path support
 - **Native token transfers** across all supported networks
 - **Gas estimation** for transaction planning
 - **Transaction status** and receipt information
@@ -185,18 +186,40 @@ npm install
 
 The server uses the following environment variables. For write operations and ABI fetching, you must configure these variables:
 
-#### Private Key (For Write Operations)
+#### Wallet Configuration (For Write Operations)
+
+You can configure your wallet using **either** a private key or a mnemonic phrase:
+
+**Option 1: Private Key**
 
 ```bash
 export EVM_PRIVATE_KEY="0x..." # Your private key in hex format (with or without 0x prefix)
 ```
 
-This private key is used for:
+**Option 2: Mnemonic Phrase (Recommended for HD Wallets)**
+
+```bash
+export EVM_MNEMONIC="word1 word2 word3 ... word12" # Your 12 or 24 word BIP-39 mnemonic
+export EVM_ACCOUNT_INDEX="0" # Optional: Account index for HD wallet derivation (default: 0)
+```
+
+The mnemonic option supports hierarchical deterministic (HD) wallet derivation:
+- Uses BIP-39 standard mnemonic phrases (12 or 24 words)
+- Supports BIP-44 derivation path: `m/44'/60'/0'/0/{accountIndex}`
+- `EVM_ACCOUNT_INDEX` allows you to derive different accounts from the same mnemonic
+- Default account index is 0 (first account)
+
+**Wallet is used for:**
 - Transferring native tokens (`transfer_native` tool)
 - Transferring ERC20 tokens (`transfer_erc20` tool)
 - Approving token spending (`approve_token_spending` tool)
+- Writing to smart contracts (`write_contract` tool)
 
-⚠️ **Security**: Never commit your private key to version control. Use environment variables or a secure key management system.
+⚠️ **Security**: 
+- Never commit your private key or mnemonic to version control
+- Use environment variables or a secure key management system
+- Store mnemonics securely - they provide access to all derived accounts
+- Consider using different account indices for different purposes
 
 #### API Keys (For ABI Fetching)
 

src/core/services/index.ts

@@ -8,12 +8,13 @@ export * from './contracts.js';
 export * from './tokens.js';
 export * from './ens.js';
 export * from './abi.js';
+export * from './wallet.js';
 export { utils as helpers } from './utils.js';
 
 // Re-export common types for convenience
-export type { 
-  Address, 
-  Hash, 
+export type {
+  Address,
+  Hash,
   Hex,
   Block,
   TransactionReceipt,

src/core/services/wallet.ts

@@ -0,0 +1,62 @@
+import { type Address, type Hex } from 'viem';
+import { privateKeyToAccount, mnemonicToAccount } from 'viem/accounts';
+
+/**
+ * Get the configured account from environment (private key or mnemonic)
+ * 
+ * Configuration options:
+ * - EVM_PRIVATE_KEY: Hex private key (with or without 0x prefix)
+ * - EVM_MNEMONIC: BIP-39 mnemonic phrase (12 or 24 words)
+ * - EVM_ACCOUNT_INDEX: Optional account index for HD wallet derivation (default: 0)
+ */
+export const getConfiguredAccount = () => {
+    const privateKey = process.env.EVM_PRIVATE_KEY;
+    const mnemonic = process.env.EVM_MNEMONIC;
+    const accountIndex = parseInt(process.env.EVM_ACCOUNT_INDEX || '0');
+
+    if (privateKey) {
+        // Use private key if provided
+        const key = (privateKey.startsWith('0x') ? privateKey : `0x${privateKey}`) as Hex;
+        return privateKeyToAccount(key);
+    } else if (mnemonic) {
+        // Use mnemonic if provided
+        return mnemonicToAccount(mnemonic, { accountIndex });
+    } else {
+        throw new Error(
+            "Neither EVM_PRIVATE_KEY nor EVM_MNEMONIC environment variable is set. " +
+            "Configure one of them to enable write operations.\n" +
+            "- EVM_PRIVATE_KEY: Your private key in hex format\n" +
+            "- EVM_MNEMONIC: Your 12 or 24 word mnemonic phrase\n" +
+            "- EVM_ACCOUNT_INDEX: (Optional) Account index for HD wallet (default: 0)"
+        );
+    }
+};
+
+/**
+ * Helper to get the configured private key (for services that need it)
+ */
+export const getConfiguredPrivateKey = (): Hex => {
+    const account = getConfiguredAccount();
+    // For mnemonic-based accounts, we need to extract the private key
+    // Viem accounts have a privateKey property but it's not always in the type definition
+    const accountWithKey = account as any;
+    if (!accountWithKey.privateKey) {
+        throw new Error("Unable to extract private key from account");
+    }
+    return accountWithKey.privateKey;
+};
+
+/**
+ * Helper to get wallet address
+ */
+export const getWalletAddressFromKey = (): Address => {
+    const account = getConfiguredAccount();
+    return account.address;
+};
+
+/**
+ * Helper to get configured wallet object
+ */
+export const getConfiguredWallet = (): { address: Address } => {
+    return { address: getWalletAddressFromKey() };
+};

src/core/tools.ts

@@ -3,43 +3,28 @@ import { z } from "zod";
 import { getSupportedNetworks, getRpcUrl } from "./chains.js";
 import * as services from "./services/index.js";
 import { type Address, type Hex, type Hash } from 'viem';
-import { privateKeyToAccount } from 'viem/accounts';
 import { normalize } from 'viem/ens';
 
 /**
  * Register all EVM-related tools with the MCP server
  *
- * SECURITY: The EVM_PRIVATE_KEY environment variable must be set for write operations.
- * Private keys are never passed as tool arguments for security reasons.
+ * SECURITY: Either EVM_PRIVATE_KEY or EVM_MNEMONIC environment variable must be set for write operations.
+ * Private keys and mnemonics are never passed as tool arguments for security reasons.
  * Tools will use the configured wallet for all transactions.
  *
+ * Configuration options:
+ * - EVM_PRIVATE_KEY: Hex private key (with or without 0x prefix)
+ * - EVM_MNEMONIC: BIP-39 mnemonic phrase (12 or 24 words)
+ * - EVM_ACCOUNT_INDEX: Optional account index for HD wallet derivation (default: 0)
+ *
  * All tools that accept addresses also support ENS names (e.g., 'vitalik.eth').
  * ENS names are automatically resolved to addresses using the Ethereum Name Service.
  *
  * @param server The MCP server instance
  */
 export function registerEVMTools(server: McpServer) {
-  // Helper to get the configured private key from environment
-  const getConfiguredPrivateKey = (): Hex => {
-    const privateKey = process.env.EVM_PRIVATE_KEY;
-    if (!privateKey) {
-      throw new Error("EVM_PRIVATE_KEY environment variable is not set. Configure it to enable write operations.");
-    }
-    // Ensure 0x prefix
-    return (privateKey.startsWith('0x') ? privateKey : `0x${privateKey}`) as Hex;
-  };
-
-  // Helper to get wallet address from private key
-  const getWalletAddressFromKey = (): Address => {
-    const privateKey = getConfiguredPrivateKey();
-    const account = privateKeyToAccount(privateKey);
-    return account.address;
-  };
-
-  // Helper to get configured wallet object
-  const getConfiguredWallet = (): { address: Address } => {
-    return { address: getWalletAddressFromKey() };
-  };
+  // Helpers are now imported from services/wallet.ts
+  const { getConfiguredPrivateKey, getWalletAddressFromKey, getConfiguredWallet } = services;
 
   // ============================================================================
   // WALLET INFORMATION TOOLS (Read-only)
@@ -768,7 +753,7 @@ export function registerEVMTools(server: McpServer) {
   server.registerTool(
     "write_contract",
     {
-      description: "Execute state-changing functions on a smart contract. Automatically fetches ABI from block explorer if not provided (requires ETHERSCAN_API_KEY). Use this to call any write function on verified contracts. Requires EVM_PRIVATE_KEY to be configured.",
+      description: "Execute state-changing functions on a smart contract. Automatically fetches ABI from block explorer if not provided (requires ETHERSCAN_API_KEY). Use this to call any write function on verified contracts. Requires wallet to be configured (via private key or mnemonic).",
       inputSchema: {
         contractAddress: z.string().describe("The contract address"),
         functionName: z.string().describe("Function name to call (e.g., 'mint', 'swap', 'stake', 'approve')"),