@cryptforge/blockchain-evm 0.1.0

package/README.md

@@ -0,0 +1,230 @@
+# @cryptforge/blockchain-evm
+
+EVM-compatible blockchain adapter for the CryptForge SDK. This package provides key derivation and wallet operations for all EVM-compatible blockchains (Ethereum, Sonic, Polygon, BSC, Arbitrum, etc.) using the ethers.js library.
+
+## Installation
+
+```bash
+npm install @cryptforge/blockchain-evm
+# or
+pnpm add @cryptforge/blockchain-evm
+# or
+yarn add @cryptforge/blockchain-evm
+```
+
+## Usage
+
+### Pre-configured Chains (Simple)
+
+For common EVM chains, use the pre-configured adapters:
+
+#### With Electron
+
+```javascript
+import { setupCryptForgeHandlers } from '@cryptforge/transport-electron/main';
+import { EthereumAdapter, SonicAdapter } from '@cryptforge/blockchain-evm';
+
+setupCryptForgeHandlers({
+  blockchainAdapters: {
+    Ethereum: EthereumAdapter,
+    Sonic: SonicAdapter,
+  },
+});
+```
+
+### Network Management
+
+Pre-configured adapters include both mainnet and testnet configurations:
+
+```javascript
+import { SonicAdapter } from '@cryptforge/blockchain-evm';
+
+// Get current network (defaults to mainnet)
+const network = SonicAdapter.getNetwork();
+console.log(network?.rpcUrl);    // "https://rpc.sonic.soniclabs.com"
+console.log(network?.chainId);   // 146
+
+// Switch to testnet
+SonicAdapter.setNetwork('testnet');
+const testnet = SonicAdapter.getNetwork();
+console.log(testnet?.rpcUrl);    // "https://rpc.blaze.soniclabs.com"
+console.log(testnet?.chainId);   // 57054
+
+// Check available networks
+const networks = SonicAdapter.getAvailableNetworks();
+console.log(networks); // ['mainnet', 'testnet']
+
+// Get current network key
+console.log(SonicAdapter.getCurrentNetworkKey()); // 'testnet'
+```
+
+### Custom EVM Chains (Advanced)
+
+For custom or unlisted EVM chains, use the configurable `EVMAdapter`:
+
+```javascript
+import { EVMAdapter } from '@cryptforge/blockchain-evm';
+
+const PolygonAdapter = new EVMAdapter({
+  chainData: {
+    name: "Polygon",
+    symbol: "MATIC",
+    cmc_id: 3890
+  },
+  coinType: 60,
+  standardDecimals: 18,
+  networks: {
+    mainnet: {
+      name: "Polygon Mainnet",
+      rpcUrl: "https://polygon-rpc.com",
+      explorerUrl: "https://polygonscan.com",
+      chainId: 137,
+    },
+    testnet: {
+      name: "Polygon Amoy Testnet",
+      rpcUrl: "https://rpc-amoy.polygon.technology",
+      explorerUrl: "https://amoy.polygonscan.com",
+      chainId: 80002,
+    },
+  },
+  defaultNetwork: 'mainnet',
+});
+```
+
+#### Custom RPC URLs
+
+Override RPC URLs for Ethereum with your own provider:
+
+```javascript
+import { EVMAdapter } from '@cryptforge/blockchain-evm';
+
+const CustomEthereum = new EVMAdapter({
+  chainData: {
+    name: "Ethereum",
+    symbol: "ETH",
+    cmc_id: 1027
+  },
+  coinType: 60,
+  standardDecimals: 18,
+  networks: {
+    mainnet: {
+      name: "Ethereum Mainnet",
+      rpcUrl: `https://mainnet.infura.io/v3/${process.env.INFURA_API_KEY}`,
+      explorerUrl: "https://etherscan.io",
+      chainId: 1,
+    },
+    testnet: {
+      name: "Ethereum Sepolia",
+      rpcUrl: `https://sepolia.infura.io/v3/${process.env.INFURA_API_KEY}`,
+      explorerUrl: "https://sepolia.etherscan.io",
+      chainId: 11155111,
+    },
+  },
+});
+```
+
+## Features
+
+- **Universal EVM Support**: Works with all EVM-compatible blockchains
+- **Pre-configured Chains**: Ready-to-use adapters for Ethereum and Sonic
+- **Network Management**: Built-in mainnet/testnet support with easy switching
+- **Configurable**: Easily create custom adapters for any EVM chain
+- **Custom RPC URLs**: Override default RPC providers with your own
+- **BIP44 Standard**: Uses standard derivation paths (default: `m/44'/60'/0'/0/0`)
+- **ethers.js**: Built on the battle-tested ethers.js v6 library
+- **Type Safe**: Full TypeScript support with type definitions
+- **Checksummed Addresses**: Returns EIP-55 checksummed addresses
+
+## API
+
+### Pre-configured Adapters
+
+#### `EthereumAdapter`
+Pre-configured adapter for Ethereum.
+- **Chain**: Ethereum
+- **Symbol**: ETH
+- **Path**: `m/44'/60'/0'/0/0`
+- **Networks**: Mainnet (Chain ID: 1), Sepolia Testnet (Chain ID: 11155111)
+- **Note**: Replace `YOUR_INFURA_API_KEY` in RPC URLs with your actual Infura API key
+
+#### `SonicAdapter`
+Pre-configured adapter for Sonic (EVM Layer 2).
+- **Chain**: Sonic
+- **Symbol**: S
+- **Path**: `m/44'/60'/0'/0/0`
+- **Networks**: Mainnet (Chain ID: 146), Testnet (Chain ID: 57054)
+
+### EVMAdapter (Configurable)
+
+Create custom EVM chain adapters.
+
+#### Constructor
+
+```typescript
+new EVMAdapter(config: EVMAdapterConfig)
+```
+
+#### EVMAdapterConfig
+
+```typescript
+interface NetworkConfig {
+  name: string;           // Network name (e.g., "Ethereum Mainnet")
+  rpcUrl: string;         // RPC endpoint URL
+  explorerUrl?: string;   // Block explorer URL (optional)
+  chainId: number;        // Chain ID for the network
+}
+
+interface EVMAdapterConfig {
+  chainData: {
+    name: string;         // Chain name (e.g., "Polygon")
+    symbol: string;       // Token symbol (e.g., "MATIC")
+    cmc_id: number;       // CoinMarketCap ID
+  };
+  coinType?: number;      // BIP44 coin type (default: 60)
+  standardDecimals?: number;  // Token decimals (default: 18)
+  networks?: {            // Network configurations
+    mainnet?: NetworkConfig;
+    testnet?: NetworkConfig;
+    [key: string]: NetworkConfig | undefined;
+  };
+  defaultNetwork?: string;    // Default network key (default: 'mainnet')
+  account?: number;           // BIP44 account (default: 0)
+  change?: number;            // BIP44 change (default: 0)
+  addressIndex?: number;      // BIP44 address index (default: 0)
+}
+```
+
+#### Methods
+
+##### Key Derivation
+- `deriveKeys(mnemonic: string): Promise<KeyData>`: Derives keys from a BIP39 mnemonic phrase
+
+##### Network Management
+- `getNetwork(): NetworkConfig | undefined`: Get current network configuration
+- `getCurrentNetworkKey(): string`: Get current network key (e.g., 'mainnet', 'testnet')
+- `setNetwork(networkKey: string): void`: Switch to a different network
+- `getAvailableNetworks(): string[]`: Get list of configured network keys
+- `hasNetwork(networkKey: string): boolean`: Check if a network is configured
+
+##### Properties
+- `chainData: ChainData`: Chain metadata (name, symbol, CMC ID)
+- `standardDecimals: number`: Standard decimals for the chain's native token
+
+## Supported Chains
+
+### Pre-configured
+- ✅ Ethereum
+- ✅ Sonic
+
+### Compatible (use `EVMAdapter`)
+- Polygon (MATIC)
+- Binance Smart Chain (BNB)
+- Arbitrum (ARB)
+- Optimism (OP)
+- Avalanche C-Chain (AVAX)
+- Fantom (FTM)
+- Any other EVM-compatible chain
+
+## License
+
+ISC