@cfxdevkit/core 0.1.0

package/dist/wallet/index.d.ts

@@ -0,0 +1,726 @@
+import { C as ChainType } from '../config-BMtaWM0X.js';
+
+/**
+ * Session Key Types
+ */
+interface SessionKeyPermissions {
+    /** Maximum value per transaction (in wei) */
+    maxValue?: bigint;
+    /** Whitelisted contract addresses */
+    contracts?: string[];
+    /** Allowed operations/function signatures */
+    operations?: string[];
+    /** Allowed chains */
+    chains?: ChainType[];
+}
+interface SessionKey {
+    /** Unique identifier for this session key */
+    id: string;
+    /** The session key's private key */
+    privateKey: string;
+    /** The session key's address */
+    address: string;
+    /** Parent wallet address */
+    parentAddress: string;
+    /** Time-to-live in seconds */
+    ttl: number;
+    /** Expiration timestamp */
+    expiresAt: Date;
+    /** Session key permissions */
+    permissions: SessionKeyPermissions;
+    /** Creation timestamp */
+    createdAt: Date;
+    /** Whether the session key is active */
+    isActive: boolean;
+    /** Chain type */
+    chain: ChainType;
+}
+interface SessionKeyOptions {
+    /** Time-to-live in seconds (default: 3600) */
+    ttl?: number;
+    /** Session key permissions */
+    permissions?: SessionKeyPermissions;
+    /** Chain type */
+    chain: ChainType;
+}
+/**
+ * Transaction Batching Types
+ */
+interface BatchTransaction {
+    /** Unique identifier */
+    id: string;
+    /** Target address */
+    to: string;
+    /** Value to send (in wei) */
+    value?: bigint;
+    /** Transaction data */
+    data?: string;
+    /** Gas limit */
+    gasLimit?: bigint;
+    /** Chain type */
+    chain: ChainType;
+    /** Added timestamp */
+    addedAt: Date;
+}
+interface BatchResult {
+    /** Batch identifier */
+    batchId: string;
+    /** Transaction hashes */
+    transactionHashes: string[];
+    /** Number of successful transactions */
+    successCount: number;
+    /** Number of failed transactions */
+    failureCount: number;
+    /** Execution timestamp */
+    executedAt: Date;
+    /** Total gas used */
+    totalGasUsed: bigint;
+    /** Chain type */
+    chain: ChainType;
+}
+interface BatcherOptions {
+    /** Maximum batch size */
+    maxBatchSize?: number;
+    /** Auto-execute batch after timeout (ms) */
+    autoExecuteTimeout?: number;
+    /** Minimum gas price (in wei) */
+    minGasPrice?: bigint;
+}
+/**
+ * Embedded Wallet Types
+ */
+interface EmbeddedWallet {
+    /** User identifier */
+    userId: string;
+    /** Wallet address (Core Space) */
+    coreAddress: string;
+    /** Wallet address (eSpace) */
+    evmAddress: string;
+    /** Encrypted private key */
+    encryptedPrivateKey: string;
+    /** Encryption metadata */
+    encryption: {
+        algorithm: string;
+        iv: string;
+        salt: string;
+    };
+    /** Creation timestamp */
+    createdAt: Date;
+    /** Last accessed timestamp */
+    lastAccessedAt: Date;
+    /** Whether the wallet is active */
+    isActive: boolean;
+}
+interface WalletExport {
+    /** User identifier */
+    userId: string;
+    /** Encrypted wallet data */
+    encryptedData: string;
+    /** Encryption metadata */
+    encryption: {
+        algorithm: string;
+        iv: string;
+        salt: string;
+    };
+    /** Export timestamp */
+    exportedAt: Date;
+}
+interface EmbeddedWalletOptions {
+    /** Encryption algorithm (default: 'aes-256-gcm') */
+    algorithm?: string;
+    /** Key derivation iterations (default: 100000) */
+    iterations?: number;
+    /** Whether to auto-create wallets for new users */
+    autoCreate?: boolean;
+}
+/**
+ * Transaction Signing Types
+ */
+interface SignTransactionRequest {
+    /** Transaction to sign */
+    to: string;
+    value?: bigint;
+    data?: string;
+    gasLimit?: bigint;
+    gasPrice?: bigint;
+    nonce?: number;
+    /** Chain type */
+    chain: ChainType;
+}
+interface SignedTransaction {
+    /** Raw signed transaction */
+    rawTransaction: string;
+    /** Transaction hash */
+    hash: string;
+    /** Signer address */
+    from: string;
+    /** Chain type */
+    chain: ChainType;
+}
+/**
+ * Wallet Manager Types
+ */
+interface WalletManagerOptions {
+    /** Session key options */
+    sessionKeys?: SessionKeyOptions;
+    /** Batcher options */
+    batcher?: BatcherOptions;
+    /** Embedded wallet options */
+    embedded?: EmbeddedWalletOptions;
+}
+/**
+ * Error Types
+ */
+declare class WalletError extends Error {
+    code: string;
+    context?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, context?: Record<string, unknown> | undefined);
+}
+declare class SessionKeyError extends WalletError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+declare class BatcherError extends WalletError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+declare class EmbeddedWalletError extends WalletError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+
+/**
+ * Transaction Batcher
+ *
+ * Batches multiple transactions for efficient execution.
+ * Reduces gas costs and network congestion by grouping related operations.
+ *
+ * Use Cases:
+ * - Batch NFT minting
+ * - Multi-send operations
+ * - Batch token approvals
+ * - Gas optimization for high-frequency operations
+ *
+ * @example
+ * ```typescript
+ * const batcher = new TransactionBatcher({
+ *   maxBatchSize: 10,
+ *   autoExecuteTimeout: 5000
+ * });
+ *
+ * // Add transactions to batch
+ * batcher.addTransaction({
+ *   to: '0xRecipient1...',
+ *   value: parseEther('1.0'),
+ *   chain: 'evm'
+ * });
+ *
+ * batcher.addTransaction({
+ *   to: '0xRecipient2...',
+ *   value: parseEther('2.0'),
+ *   chain: 'evm'
+ * });
+ *
+ * // Execute batch
+ * const result = await batcher.executeBatch('evm', signer);
+ * console.log(`Executed ${result.successCount} transactions`);
+ * ```
+ */
+declare class TransactionBatcher {
+    private coreBatch;
+    private evmBatch;
+    private autoExecuteTimer;
+    private options;
+    constructor(options?: BatcherOptions);
+    /**
+     * Add transaction to batch
+     *
+     * @param tx - Transaction to add
+     * @returns Transaction ID
+     */
+    addTransaction(tx: Omit<BatchTransaction, 'id' | 'addedAt'>): string;
+    /**
+     * Remove transaction from batch
+     *
+     * @param transactionId - Transaction ID
+     * @param chain - Chain type
+     * @returns true if removed, false if not found
+     */
+    removeTransaction(transactionId: string, chain: ChainType): boolean;
+    /**
+     * Get pending transactions for a chain
+     *
+     * @param chain - Chain type
+     * @returns Array of pending transactions
+     */
+    getPendingTransactions(chain: ChainType): BatchTransaction[];
+    /**
+     * Get batch statistics
+     *
+     * @param chain - Chain type
+     * @returns Batch statistics
+     */
+    getBatchStats(chain: ChainType): {
+        count: number;
+        totalValue: bigint;
+        avgGasLimit: bigint;
+        oldestTransaction: Date;
+    };
+    /**
+     * Execute batch of transactions
+     *
+     * Note: This is a simplified implementation. In production, you would:
+     * - Use multicall contracts for actual batching
+     * - Handle gas estimation
+     * - Implement retry logic
+     * - Support different batching strategies (sequential, parallel, etc.)
+     *
+     * @param chain - Chain to execute on
+     * @param signer - Function to sign and send transactions
+     * @returns Batch execution result
+     */
+    executeBatch(chain: ChainType, signer?: (tx: BatchTransaction) => Promise<string>): Promise<BatchResult>;
+    /**
+     * Clear all pending transactions
+     *
+     * @param chain - Chain to clear, or undefined to clear both
+     */
+    clearBatch(chain?: ChainType): void;
+    /**
+     * Start auto-execute timer
+     */
+    private startAutoExecuteTimer;
+    /**
+     * Stop auto-execute timer
+     */
+    private stopAutoExecuteTimer;
+    /**
+     * Get batcher configuration
+     */
+    getOptions(): Required<BatcherOptions>;
+    /**
+     * Update batcher configuration
+     */
+    updateOptions(options: Partial<BatcherOptions>): void;
+}
+
+/**
+ * Wallet Types for HD Derivation
+ *
+ * Provides unified types for BIP32/BIP39 HD wallet derivation
+ * supporting both Conflux Core Space and eSpace (EVM).
+ */
+/**
+ * Derived account with dual-chain support.
+ * Uses separate derivation paths for Core Space (coin type 503)
+ * and eSpace (coin type 60).
+ */
+interface DerivedAccount {
+    /** Account index in derivation sequence */
+    index: number;
+    /** Core Space address (cfx:...) */
+    coreAddress: string;
+    /** eSpace address (0x...) */
+    evmAddress: string;
+    /** Core Space private key from m/44'/503'/accountType'/0/index */
+    corePrivateKey: `0x${string}`;
+    /** eSpace private key from m/44'/60'/accountType'/0/index */
+    evmPrivateKey: `0x${string}`;
+    /** Derivation paths used */
+    paths: {
+        /** Core Space derivation path */
+        core: string;
+        /** eSpace derivation path */
+        evm: string;
+    };
+}
+/**
+ * Options for deriving accounts from a mnemonic
+ */
+interface DerivationOptions {
+    /** Number of accounts to derive */
+    count: number;
+    /** Starting index (default: 0) */
+    startIndex?: number;
+    /** Core Space network ID for address encoding (default: 2029 for local) */
+    coreNetworkId?: number;
+    /**
+     * Account type determines the derivation path:
+     * - 'standard' (default): m/44'/{coin}'/0'/0/{index} - Regular user accounts
+     * - 'mining': m/44'/{coin}'/1'/0/{index} - Mining/faucet accounts
+     */
+    accountType?: 'standard' | 'mining';
+}
+/**
+ * Result of mnemonic validation
+ */
+interface MnemonicValidation {
+    /** Whether the mnemonic is valid */
+    valid: boolean;
+    /** Number of words in the mnemonic */
+    wordCount: number;
+    /** Error message if invalid */
+    error?: string;
+}
+/**
+ * Coin type constants for BIP44 derivation paths
+ */
+declare const COIN_TYPES: {
+    /** Conflux Core Space - registered coin type 503 */
+    readonly CONFLUX: 503;
+    /** Ethereum/eSpace - standard coin type 60 */
+    readonly ETHEREUM: 60;
+};
+/**
+ * Network IDs for Conflux Core Space address encoding
+ */
+declare const CORE_NETWORK_IDS: {
+    /** Local development network */
+    readonly LOCAL: 2029;
+    /** Testnet */
+    readonly TESTNET: 1;
+    /** Mainnet */
+    readonly MAINNET: 1029;
+};
+
+/**
+ * Generate a new BIP-39 mnemonic phrase
+ *
+ * @param strength - 128 for 12 words (default) or 256 for 24 words
+ * @returns A valid BIP-39 mnemonic phrase
+ *
+ * @example
+ * ```typescript
+ * const mnemonic = generateMnemonic(); // 12 words
+ * const mnemonic24 = generateMnemonic(256); // 24 words
+ * ```
+ */
+declare function generateMnemonic(strength?: 128 | 256): string;
+/**
+ * Validate a mnemonic phrase
+ *
+ * Checks that the mnemonic has a valid word count (12 or 24)
+ * and passes BIP-39 checksum validation.
+ *
+ * @param mnemonic - The mnemonic phrase to validate
+ * @returns Validation result with details
+ *
+ * @example
+ * ```typescript
+ * const result = validateMnemonic('abandon abandon ...');
+ * if (result.valid) {
+ *   console.log(`Valid ${result.wordCount}-word mnemonic`);
+ * } else {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
+declare function validateMnemonic(mnemonic: string): MnemonicValidation;
+/**
+ * Derive multiple accounts from a mnemonic phrase
+ *
+ * Derives accounts for both Conflux Core Space and eSpace using
+ * BIP-44 standard derivation paths:
+ * - Core Space: m/44'/503'/{accountType}'/0/{index}
+ * - eSpace: m/44'/60'/{accountType}'/0/{index}
+ *
+ * @param mnemonic - BIP-39 mnemonic phrase
+ * @param options - Derivation options
+ * @returns Array of derived accounts
+ * @throws Error if mnemonic is invalid
+ *
+ * @example
+ * ```typescript
+ * const accounts = deriveAccounts(mnemonic, {
+ *   count: 10,
+ *   coreNetworkId: 2029, // Local network
+ * });
+ * console.log(accounts[0].coreAddress); // cfx:...
+ * console.log(accounts[0].evmAddress);  // 0x...
+ * ```
+ */
+declare function deriveAccounts(mnemonic: string, options: DerivationOptions): DerivedAccount[];
+/**
+ * Derive a single account at a specific index
+ *
+ * Convenience function for deriving just one account.
+ *
+ * @param mnemonic - BIP-39 mnemonic phrase
+ * @param index - Account index to derive
+ * @param coreNetworkId - Core Space network ID (default: 2029 for local)
+ * @param accountType - 'standard' or 'mining' (default: 'standard')
+ * @returns The derived account
+ *
+ * @example
+ * ```typescript
+ * const account = deriveAccount(mnemonic, 5);
+ * console.log(account.index); // 5
+ * ```
+ */
+declare function deriveAccount(mnemonic: string, index: number, coreNetworkId?: number, accountType?: 'standard' | 'mining'): DerivedAccount;
+/**
+ * Derive the faucet/mining account
+ *
+ * The faucet account uses a separate derivation path (mining type)
+ * at index 0. This is used for the mining rewards recipient and
+ * as the source for faucet operations.
+ *
+ * @param mnemonic - BIP-39 mnemonic phrase
+ * @param coreNetworkId - Core Space network ID (default: 2029 for local)
+ * @returns The faucet account
+ *
+ * @example
+ * ```typescript
+ * const faucet = deriveFaucetAccount(mnemonic);
+ * // Uses paths: m/44'/503'/1'/0/0 and m/44'/60'/1'/0/0
+ * ```
+ */
+declare function deriveFaucetAccount(mnemonic: string, coreNetworkId?: number): DerivedAccount;
+/**
+ * Get the derivation path for an account
+ *
+ * Utility function to generate standard derivation paths.
+ *
+ * @param coinType - Coin type (503 for Conflux, 60 for Ethereum)
+ * @param index - Account index
+ * @param accountType - 'standard' (0') or 'mining' (1')
+ * @returns The BIP-44 derivation path
+ */
+declare function getDerivationPath(coinType: number, index: number, accountType?: 'standard' | 'mining'): string;
+
+/**
+ * Embedded Wallet Manager
+ *
+ * Manages server-side custody wallets for users.
+ * Provides secure wallet creation, storage, and transaction signing.
+ *
+ * SECURITY WARNING:
+ * This is a simplified implementation for development and testing.
+ * Production use requires:
+ * - Hardware Security Modules (HSM)
+ * - Proper key management infrastructure
+ * - Multi-signature schemes
+ * - Audit logging
+ * - Compliance with custody regulations
+ *
+ * Use Cases:
+ * - Social login wallets (Privy, Magic, Web3Auth)
+ * - Custodial game wallets
+ * - Enterprise treasury management
+ * - Automated service accounts
+ *
+ * @example
+ * ```typescript
+ * const manager = new EmbeddedWalletManager();
+ *
+ * // Create wallet for user
+ * const wallet = await manager.createWallet('user123', 'secure-password');
+ *
+ * // Sign transaction
+ * const signed = await manager.signTransaction('user123', 'secure-password', {
+ *   to: '0xRecipient...',
+ *   value: parseEther('1.0'),
+ *   chain: 'evm'
+ * });
+ *
+ * // Export wallet for user
+ * const exportData = await manager.exportWallet('user123', 'secure-password');
+ * ```
+ */
+declare class EmbeddedWalletManager {
+    private wallets;
+    private options;
+    constructor(options?: EmbeddedWalletOptions);
+    /**
+     * Create a new embedded wallet for a user
+     *
+     * @param userId - User identifier
+     * @param password - Encryption password
+     * @returns Created wallet (without private key)
+     */
+    createWallet(userId: string, password: string): Promise<Omit<EmbeddedWallet, 'encryptedPrivateKey'>>;
+    /**
+     * Get wallet info (without private key)
+     *
+     * @param userId - User identifier
+     * @returns Wallet info or undefined
+     */
+    getWallet(userId: string): Omit<EmbeddedWallet, 'encryptedPrivateKey'> | undefined;
+    /**
+     * Check if user has a wallet
+     *
+     * @param userId - User identifier
+     * @returns true if wallet exists
+     */
+    hasWallet(userId: string): boolean;
+    /**
+     * Sign transaction with user's embedded wallet
+     *
+     * @param userId - User identifier
+     * @param password - Decryption password
+     * @param request - Transaction request
+     * @returns Signed transaction
+     */
+    signTransaction(userId: string, password: string, request: SignTransactionRequest): Promise<SignedTransaction>;
+    /**
+     * Export wallet for user backup
+     *
+     * @param userId - User identifier
+     * @param password - Encryption password
+     * @returns Encrypted wallet export
+     */
+    exportWallet(userId: string, password: string): Promise<WalletExport>;
+    /**
+     * Deactivate wallet
+     *
+     * @param userId - User identifier
+     */
+    deactivateWallet(userId: string): void;
+    /**
+     * Delete wallet permanently
+     *
+     * WARNING: This operation cannot be undone
+     *
+     * @param userId - User identifier
+     * @returns true if deleted, false if not found
+     */
+    deleteWallet(userId: string): boolean;
+    /**
+     * List all wallets (without private keys)
+     *
+     * @returns Array of wallet info
+     */
+    listWallets(): Array<Omit<EmbeddedWallet, 'encryptedPrivateKey'>>;
+    /**
+     * Get wallet statistics
+     *
+     * @returns Wallet statistics
+     */
+    getStats(): {
+        total: number;
+        active: number;
+        inactive: number;
+    };
+    /**
+     * Encrypt private key
+     *
+     * NOTE: Simplified implementation for demonstration
+     * Production should use proper encryption (node:crypto, @noble/ciphers, etc.)
+     */
+    private encryptPrivateKey;
+    /**
+     * Decrypt private key
+     *
+     * NOTE: Simplified implementation for demonstration
+     */
+    private decryptPrivateKey;
+}
+
+/**
+ * Session Key Manager
+ *
+ * Manages temporary session keys for delegated transaction signing.
+ * Session keys allow applications to sign transactions on behalf of users
+ * with time-limited and permission-scoped access.
+ *
+ * Use Cases:
+ * - Gaming: Allow game to make in-game purchases without repeated wallet prompts
+ * - Trading: Enable automated trading bots with spending limits
+ * - DeFi: Permit auto-compounding or rebalancing with constraints
+ *
+ * @example
+ * ```typescript
+ * const manager = new SessionKeyManager();
+ *
+ * // Create session key with 1 hour TTL and spending limit
+ * const sessionKey = manager.generateSessionKey(
+ *   '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+ *   {
+ *     ttl: 3600,
+ *     permissions: {
+ *       maxValue: parseEther('1.0'),
+ *       contracts: ['0xGameContract...']
+ *     },
+ *     chain: 'evm'
+ *   }
+ * );
+ *
+ * // Use session key to sign transactions
+ * const signedTx = await manager.signWithSessionKey(sessionKey.id, {
+ *   to: '0xGameContract...',
+ *   data: '0x...',
+ *   chain: 'evm'
+ * });
+ * ```
+ */
+declare class SessionKeyManager {
+    private sessionKeys;
+    /**
+     * Generate a new session key
+     *
+     * @param parentAddress - Parent wallet address
+     * @param options - Session key configuration
+     * @returns Created session key
+     */
+    generateSessionKey(parentAddress: string, options: SessionKeyOptions): SessionKey;
+    /**
+     * Get session key by ID
+     *
+     * @param sessionKeyId - Session key identifier
+     * @returns Session key or undefined
+     */
+    getSessionKey(sessionKeyId: string): SessionKey | undefined;
+    /**
+     * Revoke a session key
+     *
+     * @param sessionKeyId - Session key identifier
+     */
+    revokeSessionKey(sessionKeyId: string): void;
+    /**
+     * List all session keys for a parent address
+     *
+     * @param parentAddress - Parent wallet address
+     * @returns Array of session keys
+     */
+    listSessionKeys(parentAddress: string): SessionKey[];
+    /**
+     * List active session keys for a parent address
+     *
+     * @param parentAddress - Parent wallet address
+     * @returns Array of active session keys
+     */
+    listActiveSessionKeys(parentAddress: string): SessionKey[];
+    /**
+     * Validate transaction against session key permissions
+     *
+     * @param sessionKey - Session key
+     * @param request - Transaction request
+     * @throws SessionKeyError if validation fails
+     */
+    private validateTransaction;
+    /**
+     * Sign transaction with session key
+     *
+     * @param sessionKeyId - Session key identifier
+     * @param request - Transaction request
+     * @returns Signed transaction
+     * @throws SessionKeyError if session key is invalid or transaction violates permissions
+     */
+    signWithSessionKey(sessionKeyId: string, request: SignTransactionRequest): Promise<SignedTransaction>;
+    /**
+     * Clean up expired session keys
+     *
+     * @returns Number of removed session keys
+     */
+    cleanupExpired(): number;
+    /**
+     * Get session key statistics
+     *
+     * @returns Statistics about session keys
+     */
+    getStats(): {
+        total: number;
+        active: number;
+        expired: number;
+        inactive: number;
+    };
+}
+
+export { type BatchResult, type BatchTransaction, BatcherError, type BatcherOptions, COIN_TYPES, CORE_NETWORK_IDS, type DerivationOptions, type DerivedAccount, type EmbeddedWallet, EmbeddedWalletError, EmbeddedWalletManager, type EmbeddedWalletOptions, type MnemonicValidation, type SessionKey, SessionKeyError, SessionKeyManager, type SessionKeyOptions, type SessionKeyPermissions, type SignTransactionRequest, type SignedTransaction, TransactionBatcher, WalletError, type WalletExport, type WalletManagerOptions, deriveAccount, deriveAccounts, deriveFaucetAccount, generateMnemonic, getDerivationPath, validateMnemonic };