agentvault 1.0.0 → 1.0.2

package/dist/src/wallet/key-derivation.js

@@ -0,0 +1,325 @@
+/**
+ * Key Derivation Module
+ *
+ * Implements BIP39 seed phrase derivation for wallet keys.
+ * Supports multiple derivation paths for different blockchains.
+ */
+import * as bip39 from 'bip39';
+import * as crypto from 'node:crypto';
+import { encodeAddress } from '@polkadot/util-crypto';
+import { Keypair } from '@solana/web3.js';
+import { HDNodeWallet, SigningKey, computeAddress } from 'ethers';
+/**
+ * Default derivation paths for different chains
+ */
+const DEFAULT_DERIVATION_PATHS = {
+    // Ethereum / ckETH (BIP44)
+    eth: "m/44'/60'/0'/0/0",
+    // Polkadot (Substrate)
+    polkadot: "//hard//stash",
+    // Solana (BIP44)
+    solana: "m/44'/501'/0'/0'/0'",
+    // Bitcoin
+    btc: "m/44'/0'/0'/0/0",
+};
+/**
+ * Parse derivation path string
+ *
+ * @param path - Derivation path string (e.g., "m/44'/60'/0'/0/0")
+ * @returns Parsed path components
+ */
+export function parseDerivationPath(path) {
+    const parts = path.split('/');
+    if (parts[0] !== 'm') {
+        throw new Error('Invalid derivation path: must start with "m"');
+    }
+    const components = {
+        purpose: 0,
+        coinType: 0,
+        account: 0,
+        change: 0,
+        index: 0,
+    };
+    for (let i = 1; i < parts.length; i++) {
+        const part = parts[i]?.replace(/'/g, '') || '0';
+        const num = parseInt(part, 10);
+        switch (i) {
+            case 1:
+                components.purpose = num;
+                break;
+            case 2:
+                components.coinType = num;
+                break;
+            case 3:
+                components.account = num;
+                break;
+            case 4:
+                components.change = num;
+                break;
+            case 5:
+                components.index = num;
+                break;
+        }
+    }
+    return components;
+}
+/**
+ * Build derivation path from components
+ *
+ * @param components - Path components
+ * @returns Derivation path string
+ */
+export function buildDerivationPath(components) {
+    const parts = ['m'];
+    parts.push(`${components.purpose}'`);
+    parts.push(`${components.coinType}'`);
+    parts.push(`${components.account}'`);
+    parts.push(`${components.change}`);
+    parts.push(`${components.index}`);
+    return parts.join('/');
+}
+/**
+ * Validate seed phrase (BIP39)
+ *
+ * @param seedPhrase - Seed phrase to validate
+ * @returns True if valid BIP39 phrase
+ */
+export function validateSeedPhrase(seedPhrase) {
+    return bip39.validateMnemonic(seedPhrase);
+}
+/**
+ * Generate seed from seed phrase
+ *
+ * @param seedPhrase - BIP39 seed phrase
+ * @param passphrase - Optional passphrase (default empty)
+ * @returns Seed bytes
+ */
+export function generateSeedFromMnemonic(seedPhrase, passphrase = '') {
+    return bip39.mnemonicToSeedSync(seedPhrase, passphrase);
+}
+/**
+ * Generate mnemonic from entropy
+ *
+ * @param strength - Entropy strength in bits (128, 160, 192, 224, 256)
+ * @param rng - Optional RNG function
+ * @returns BIP39 mnemonic phrase
+ */
+export function generateMnemonic(strength = 128, rng) {
+    return bip39.generateMnemonic(strength, rng);
+}
+/**
+ * Derive key from seed using HMAC-SHA512
+ *
+ * @param seed - Seed bytes
+ * @param derivationPath - Derivation path
+ * @returns Derived key (32 bytes private, 32 bytes chain code)
+ */
+function deriveKeyFromSeed(seed, derivationPath) {
+    const parts = parseDerivationPath(derivationPath);
+    let key = seed.slice(0, 32);
+    let chainCode = seed.slice(32, 64);
+    for (const part of [parts.purpose, parts.coinType, parts.account, parts.change, parts.index]) {
+        const isHardened = part >= 0x80000000;
+        const data = Buffer.concat([
+            key,
+            Buffer.from([0x00]),
+            Buffer.alloc(4),
+        ]);
+        data.writeUint32BE(isHardened ? part : part + 0x80000000, 4);
+        const hmac = crypto.createHmac('sha512', chainCode);
+        hmac.update(data);
+        const result = hmac.digest();
+        key = result.slice(0, 32);
+        chainCode = result.slice(32, 64);
+    }
+    return { privateKey: key, chainCode };
+}
+/**
+ * Derive Ethereum-compatible key
+ *
+ * @param seed - Seed bytes
+ * @param derivationPath - Derivation path (default: "m/44'/60'/0'/0/0")
+ * @returns Derived key with ETH address
+ */
+export function deriveEthKey(seed, derivationPath = DEFAULT_DERIVATION_PATHS.eth) {
+    const root = HDNodeWallet.fromSeed(seed);
+    const node = root.derivePath(derivationPath);
+    const privateKeyHex = stripHexPrefix(node.privateKey);
+    const publicKeyHex = stripHexPrefix(SigningKey.computePublicKey(node.privateKey, false));
+    const address = node.address;
+    return {
+        privateKey: privateKeyHex,
+        publicKey: publicKeyHex,
+        address,
+        derivationPath,
+    };
+}
+/**
+ * Derive Polkadot-compatible key
+ *
+ * Uses SR25519 for key derivation and SS58 for address encoding.
+ *
+ * @param seed - Seed bytes
+ * @param derivationPath - Derivation path (default: "//hard//stash")
+ * @returns Derived key with Polkadot address
+ */
+export function derivePolkadotKey(seed, derivationPath = DEFAULT_DERIVATION_PATHS.polkadot) {
+    const privateKey = seed.slice(0, 32);
+    const publicKey = derivePublicKey(privateKey);
+    const address = derivePolkadotAddress(Buffer.from(publicKey));
+    return {
+        privateKey: privateKey.toString('hex'),
+        publicKey: publicKey.toString('hex'),
+        address,
+        derivationPath,
+    };
+}
+/**
+ * Derive Solana-compatible key
+ *
+ * @param seed - Seed bytes
+ * @param derivationPath - Derivation path (default: "m/44'/501'/0'/0'/0'")
+ * @returns Derived key with Solana address
+ */
+export function deriveSolanaKey(seed, derivationPath = DEFAULT_DERIVATION_PATHS.solana) {
+    // Use BIP44 derivation for Solana
+    const derived = deriveKeyFromSeed(seed, derivationPath);
+    if (!derived || !derived.privateKey) {
+        throw new Error('Failed to derive Solana key');
+    }
+    // Solana uses Ed25519, takes first 32 bytes as seed material
+    const privateKeyBytes = derived.privateKey.subarray(0, 32);
+    // Use Solana's Keypair for proper Ed25519 key generation
+    const keypair = Keypair.fromSeed(privateKeyBytes);
+    return {
+        privateKey: Buffer.from(keypair.secretKey).toString('hex'),
+        publicKey: Buffer.from(keypair.publicKey.toBytes()).toString('hex'),
+        address: keypair.publicKey.toBase58(),
+        derivationPath,
+    };
+}
+/**
+ * Derive public key from private key (simplified)
+ *
+ * @param privateKey - Private key bytes
+ * @returns Public key bytes
+ */
+function derivePublicKey(privateKey) {
+    // Default to secp256k1 for generic key derivation paths.
+    // Chain-specific derivation functions should prefer their own primitives.
+    const privateKeyHex = `0x${privateKey.toString('hex')}`;
+    const publicKeyHex = SigningKey.computePublicKey(privateKeyHex, false);
+    return Buffer.from(stripHexPrefix(publicKeyHex), 'hex');
+}
+/**
+ * Derive Polkadot address from public key
+ *
+ * Uses proper SS58 encoding with Polkadot prefix (0).
+ *
+ * @param publicKey - Public key bytes (32 bytes for SR25519/ED25519)
+ * @returns Polkadot address (SS58 format)
+ */
+function derivePolkadotAddress(publicKey) {
+    if (publicKey.length !== 32) {
+        throw new Error(`Invalid public key length: expected 32 bytes, got ${publicKey.length}`);
+    }
+    try {
+        const address = encodeAddress(publicKey, 0);
+        return address;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        throw new Error(`Failed to derive Polkadot address: ${message}`);
+    }
+}
+/**
+ * Get default derivation path for chain
+ *
+ * @param chain - Blockchain type
+ * @returns Default derivation path
+ */
+export function getDefaultDerivationPath(chain) {
+    switch (chain.toLowerCase()) {
+        case 'cketh':
+        case 'ethereum':
+        case 'eth':
+            return DEFAULT_DERIVATION_PATHS.eth;
+        case 'polkadot':
+        case 'dot':
+            return DEFAULT_DERIVATION_PATHS.polkadot;
+        case 'solana':
+        case 'sol':
+            return DEFAULT_DERIVATION_PATHS.solana;
+        default:
+            return DEFAULT_DERIVATION_PATHS.eth;
+    }
+}
+/**
+ * Derive wallet key based on creation method
+ *
+ * @param method - Wallet creation method
+ * @param seedPhrase - Seed phrase (for 'seed' and 'mnemonic' methods)
+ * @param privateKey - Private key (for 'private-key' method)
+ * @param derivationPath - Custom derivation path
+ * @param chain - Blockchain type
+ * @returns Derived key information
+ */
+export function deriveWalletKey(method, seedPhrase, privateKey, derivationPath, chain = 'cketh') {
+    const effectiveDerivationPath = derivationPath || getDefaultDerivationPath(chain);
+    if (method === 'private-key' && privateKey) {
+        const normalizedPrivateKey = normalizePrivateKey(privateKey);
+        const privateKeyBuffer = Buffer.from(stripHexPrefix(normalizedPrivateKey), 'hex');
+        let address;
+        let publicKeyHex;
+        if (chain === 'cketh' || chain === 'ethereum') {
+            publicKeyHex = stripHexPrefix(SigningKey.computePublicKey(normalizedPrivateKey, false));
+            address = computeAddress(normalizedPrivateKey);
+        }
+        else if (chain === 'polkadot') {
+            const publicKey = derivePublicKey(privateKeyBuffer);
+            publicKeyHex = publicKey.toString('hex');
+            address = derivePolkadotAddress(publicKey);
+        }
+        else {
+            // Solana accepts either 32-byte seed or 64-byte secret key material.
+            const keypair = privateKeyBuffer.length >= 64
+                ? Keypair.fromSecretKey(privateKeyBuffer.subarray(0, 64))
+                : Keypair.fromSeed(privateKeyBuffer.subarray(0, 32));
+            publicKeyHex = Buffer.from(keypair.publicKey.toBytes()).toString('hex');
+            address = keypair.publicKey.toBase58();
+        }
+        return {
+            privateKey: stripHexPrefix(normalizedPrivateKey),
+            publicKey: publicKeyHex,
+            address,
+            derivationPath: effectiveDerivationPath,
+        };
+    }
+    if ((method === 'seed' || method === 'mnemonic') && seedPhrase) {
+        // Derive from seed phrase
+        if (!validateSeedPhrase(seedPhrase)) {
+            throw new Error('Invalid seed phrase');
+        }
+        const seed = generateSeedFromMnemonic(seedPhrase);
+        if (chain === 'cketh' || chain === 'ethereum') {
+            return deriveEthKey(seed, effectiveDerivationPath);
+        }
+        else if (chain === 'polkadot') {
+            return derivePolkadotKey(seed, effectiveDerivationPath);
+        }
+        else if (chain === 'solana') {
+            return deriveSolanaKey(seed, effectiveDerivationPath);
+        }
+        else {
+            return deriveEthKey(seed, effectiveDerivationPath);
+        }
+    }
+    throw new Error(`Invalid wallet creation method: ${method}`);
+}
+function stripHexPrefix(value) {
+    return value.startsWith('0x') ? value.slice(2) : value;
+}
+function normalizePrivateKey(value) {
+    return value.startsWith('0x') ? value : `0x${value}`;
+}
+//# sourceMappingURL=key-derivation.js.map

package/dist/src/wallet/providers/base-provider.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Base Wallet Provider
+ *
+ * Abstract base class for all blockchain wallet providers.
+ * Defines common interface for wallet operations.
+ */
+import type { ChainType, Balance, Transaction, TransactionRequest, SignedTransaction, ProviderConfig } from '../types.js';
+/**
+ * Abstract base class for wallet providers
+ */
+export declare abstract class BaseWalletProvider {
+    protected config: ProviderConfig;
+    protected connected: boolean;
+    constructor(config: ProviderConfig);
+    /**
+     * Connect to blockchain network
+     */
+    abstract connect(): Promise<void>;
+    /**
+     * Disconnect from blockchain network
+     */
+    abstract disconnect(): Promise<void>;
+    /**
+     * Get wallet balance
+     *
+     * @param address - Wallet address
+     * @returns Wallet balance
+     */
+    abstract getBalance(address: string): Promise<Balance>;
+    /**
+     * Send transaction
+     *
+     * @param from - From address
+     * @param request - Transaction request
+     * @returns Transaction result
+     */
+    abstract sendTransaction(from: string, request: TransactionRequest): Promise<Transaction>;
+    /**
+     * Sign transaction
+     *
+     * @param tx - Transaction object
+     * @param privateKey - Private key for signing
+     * @returns Signed transaction
+     */
+    abstract signTransaction(tx: any, privateKey: string): Promise<SignedTransaction>;
+    /**
+     * Get transaction history
+     *
+     * @param address - Wallet address
+     * @returns Transaction history
+     */
+    abstract getTransactionHistory(address: string): Promise<Transaction[]>;
+    /**
+     * Validate address format
+     *
+     * @param address - Address to validate
+     * @returns True if address is valid
+     */
+    abstract validateAddress(address: string): boolean;
+    /**
+     * Check connection status
+     *
+     * @returns True if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Get chain type
+     *
+     * @returns Chain type
+     */
+    getChain(): ChainType;
+    /**
+     * Get provider configuration
+     *
+     * @returns Provider configuration
+     */
+    getConfig(): ProviderConfig;
+    /**
+     * Get RPC URL
+     *
+     * @returns RPC endpoint URL
+     */
+    getRpcUrl(): string;
+    /**
+     * Check if connected to testnet
+     *
+     * @returns True if using testnet
+     */
+    isTestnet(): boolean;
+    /**
+     * Estimate transaction fee
+     *
+     * @param request - Transaction request
+     * @returns Estimated fee (as string)
+     */
+    abstract estimateFee(request: TransactionRequest): Promise<string>;
+    /**
+     * Get current block number
+     *
+     * @returns Block number
+     */
+    abstract getBlockNumber(): Promise<number>;
+    /**
+     * Get transaction by hash
+     *
+     * @param txHash - Transaction hash
+     * @returns Transaction details
+     */
+    abstract getTransaction(txHash: string): Promise<Transaction | null>;
+}
+//# sourceMappingURL=base-provider.d.ts.map

package/dist/src/wallet/providers/base-provider.js

@@ -0,0 +1,58 @@
+/**
+ * Base Wallet Provider
+ *
+ * Abstract base class for all blockchain wallet providers.
+ * Defines common interface for wallet operations.
+ */
+/**
+ * Abstract base class for wallet providers
+ */
+export class BaseWalletProvider {
+    config;
+    connected;
+    constructor(config) {
+        this.config = config;
+        this.connected = false;
+    }
+    /**
+     * Check connection status
+     *
+     * @returns True if connected
+     */
+    isConnected() {
+        return this.connected;
+    }
+    /**
+     * Get chain type
+     *
+     * @returns Chain type
+     */
+    getChain() {
+        return this.config.chain;
+    }
+    /**
+     * Get provider configuration
+     *
+     * @returns Provider configuration
+     */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Get RPC URL
+     *
+     * @returns RPC endpoint URL
+     */
+    getRpcUrl() {
+        return this.config.rpcUrl || '';
+    }
+    /**
+     * Check if connected to testnet
+     *
+     * @returns True if using testnet
+     */
+    isTestnet() {
+        return this.config.isTestnet ?? false;
+    }
+}
+//# sourceMappingURL=base-provider.js.map

package/dist/src/wallet/providers/cketh-provider.d.ts

@@ -0,0 +1,104 @@
+/**
+ * ckETH Wallet Provider
+ *
+ * Provider for Ethereum-compatible wallets on ICP ckETH.
+ * Supports balance queries, transactions, and signing.
+ */
+import type { Balance, Transaction, TransactionRequest, SignedTransaction, ProviderConfig } from '../types.js';
+import { BaseWalletProvider } from './base-provider.js';
+/**
+ * ckETH provider configuration
+ */
+interface CkEthConfig extends ProviderConfig {
+    /** Ethereum JSON-RPC endpoint */
+    rpcUrl: string;
+    /** Chain ID (1 = Mainnet, 5 = Goerli, 11155111 = Sepolia) */
+    chainId?: number;
+    /** Etherscan API key (optional, for transaction history) */
+    etherscanApiKey?: string;
+}
+/**
+ * ckETH wallet provider
+ */
+export declare class CkEthProvider extends BaseWalletProvider {
+    private provider;
+    private chainId;
+    private etherscanApiKey;
+    constructor(config: CkEthConfig);
+    /**
+     * Resolve the RPC URL to use for connections
+     *
+     * Priority:
+     * 1. Explicitly configured URL
+     * 2. Environment variable (ETHEREUM_RPC_URL or SEPOLIA_RPC_URL)
+     * 3. Infura with API key from environment
+     * 4. Public RPC endpoints (fallback, rate-limited)
+     *
+     * @returns RPC URL
+     */
+    private resolveRpcUrl;
+    /**
+     * Connect to Ethereum network via RPC
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from network
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Get wallet balance
+     */
+    getBalance(address: string): Promise<Balance>;
+    /**
+     * Send transaction
+     */
+    sendTransaction(from: string, request: TransactionRequest): Promise<Transaction>;
+    /**
+     * Sign transaction
+     */
+    signTransaction(tx: any, privateKey: string): Promise<SignedTransaction>;
+    /**
+     * Get transaction history
+     *
+     * Uses Etherscan API to fetch transaction history.
+     * Requires ETHERSCAN_API_KEY environment variable or etherscanApiKey in config.
+     *
+     * @param address - Wallet address to get history for
+     * @returns Array of transactions
+     */
+    getTransactionHistory(address: string): Promise<Transaction[]>;
+    /**
+     * Validate Ethereum address
+     */
+    validateAddress(address: string): boolean;
+    /**
+     * Estimate transaction fee
+     */
+    estimateFee(request: TransactionRequest): Promise<string>;
+    /**
+     * Get current block number
+     */
+    getBlockNumber(): Promise<number>;
+    /**
+     * Get transaction by hash
+     */
+    getTransaction(txHash: string): Promise<Transaction | null>;
+    /**
+     * Create transaction from request
+     */
+    private populateTransaction;
+    /**
+     * Get default RPC URL for chain
+     *
+     * @param isTestnet - Whether to get testnet URL
+     * @returns RPC URL from environment or public endpoint
+     * @throws Error if no RPC URL is configured
+     */
+    static getDefaultRpcUrl(isTestnet?: boolean): string;
+    /**
+     * Get chain ID
+     */
+    getChainId(): number;
+}
+export {};
+//# sourceMappingURL=cketh-provider.d.ts.map