@cfxdevkit/services 0.1.0

package/dist/services/index.d.ts

@@ -0,0 +1,566 @@
+import { Address } from 'viem';
+
+/**
+ * Encryption service using AES-256-GCM
+ *
+ * Security specifications:
+ * - Algorithm: AES-256-GCM (authenticated encryption)
+ * - Key derivation: PBKDF2-SHA256 with 100,000 iterations
+ * - Salt: 32 bytes (random, stored in keystore)
+ * - IV: 12 bytes (random per encryption, prepended to ciphertext)
+ * - Format: base64(IV + EncryptedData + AuthTag)
+ */
+declare class EncryptionService {
+    private constructor();
+    private static readonly ITERATIONS;
+    private static readonly KEY_LENGTH;
+    private static readonly SALT_LENGTH;
+    private static readonly IV_LENGTH;
+    /**
+     * Generate a random salt for key derivation
+     */
+    static generateSalt(): Buffer;
+    /**
+     * Derive encryption key from password using PBKDF2
+     */
+    static deriveKey(password: string, salt: Buffer): Promise<CryptoKey>;
+    /**
+     * Encrypt plaintext with password
+     *
+     * @param plaintext - String to encrypt
+     * @param password - Encryption password
+     * @param salt - Salt for key derivation
+     * @returns Base64-encoded ciphertext with prepended IV
+     */
+    static encrypt(plaintext: string, password: string, salt: Buffer): Promise<string>;
+    /**
+     * Decrypt ciphertext with password
+     *
+     * @param ciphertext - Base64-encoded ciphertext with prepended IV
+     * @param password - Encryption password
+     * @param salt - Salt for key derivation
+     * @returns Decrypted plaintext
+     * @throws Error if decryption fails (wrong password or corrupted data)
+     */
+    static decrypt(ciphertext: string, password: string, salt: Buffer): Promise<string>;
+    /**
+     * Encrypt an object (serializes to JSON first)
+     */
+    static encryptObject<T>(obj: T, password: string, salt: Buffer): Promise<string>;
+    /**
+     * Decrypt to an object (parses JSON after decryption)
+     */
+    static decryptObject<T>(ciphertext: string, password: string, salt: Buffer): Promise<T>;
+    /**
+     * Hash a string with SHA-256 (for config integrity checks)
+     */
+    static hash(data: string): Promise<string>;
+    /**
+     * Verify password strength (basic validation)
+     */
+    static validatePasswordStrength(password: string): {
+        valid: boolean;
+        errors: string[];
+    };
+}
+
+/**
+ * Keystore Version 2 Schema
+ *
+ * Breaking changes from v1:
+ * - adminPrivateKey removed (admins identified by wallet address only)
+ * - Multiple admin addresses supported
+ * - Per-mnemonic node configuration
+ * - Derived keys cached and encrypted
+ * - Immutable node configuration
+ */
+/**
+ * Main keystore file structure
+ */
+interface KeystoreV2 {
+    version: 2;
+    setupCompleted: boolean;
+    setupCompletedAt?: string;
+    adminAddresses: string[];
+    encryptionEnabled: boolean;
+    encryptionSalt?: string;
+    mnemonics: MnemonicEntry[];
+    activeIndex: number;
+}
+/**
+ * Individual mnemonic entry with node configuration
+ */
+interface MnemonicEntry {
+    id: string;
+    label: string;
+    type: 'plaintext' | 'encrypted';
+    mnemonic: string;
+    createdAt: string;
+    nodeConfig: NodeConfig;
+    derivedKeys: DerivedKeys;
+}
+/**
+ * Node configuration bound to a mnemonic
+ * Immutable once blockchain data exists
+ */
+interface NodeConfig {
+    accountsCount: number;
+    chainId: number;
+    evmChainId: number;
+    miningAuthor: 'auto' | string;
+    immutable: boolean;
+    configHash: string;
+    createdAt: string;
+}
+/**
+ * Derived account keys (genesis + faucet)
+ * Encrypted if keystore encryption enabled
+ */
+interface DerivedKeys {
+    type: 'plaintext' | 'encrypted';
+    genesisAccounts: DerivedAccount[] | string;
+    faucetAccount: DerivedAccount | string;
+}
+/**
+ * Single derived account with addresses and private keys for both chains
+ */
+interface DerivedAccount {
+    index: number;
+    core: string;
+    evm: string;
+    privateKey: string;
+    evmPrivateKey: string;
+    address?: string;
+    path?: string;
+    network?: 'core' | 'espace';
+}
+/**
+ * Summary of a mnemonic (without sensitive data)
+ */
+interface MnemonicSummary {
+    id: string;
+    label: string;
+    type: 'plaintext' | 'encrypted';
+    isActive: boolean;
+    createdAt: string;
+    nodeConfig: NodeConfig;
+    dataDir: string;
+    dataSize: string;
+}
+/**
+ * Setup data for initial configuration
+ */
+interface SetupData {
+    adminAddress: string;
+    mnemonic: string;
+    mnemonicLabel: string;
+    nodeConfig: {
+        accountsCount: number;
+        chainId: number;
+        evmChainId: number;
+        miningAuthor?: string;
+    };
+    encryption?: {
+        enabled: boolean;
+        password?: string;
+    };
+}
+/**
+ * Data for adding a new mnemonic
+ */
+interface AddMnemonicData {
+    mnemonic: string;
+    label: string;
+    nodeConfig: {
+        accountsCount: number;
+        chainId: number;
+        evmChainId: number;
+        miningAuthor?: string;
+    };
+    setAsActive?: boolean;
+}
+/**
+ * Validation result
+ */
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings?: string[];
+}
+/**
+ * Node configuration modification check result
+ */
+interface ConfigModificationCheck {
+    canModify: boolean;
+    reason?: string;
+    dataDir?: string;
+    lockFile?: string;
+}
+
+declare class KeystoreLockedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * KeystoreService V2
+ */
+declare class KeystoreService {
+    private keystorePath;
+    private keystore;
+    private currentPassword;
+    constructor(keystorePath?: string);
+    private requireKeystore;
+    private requireEncryptionSalt;
+    private requirePassword;
+    /**
+     * Initialize keystore (load from disk or create empty)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Load keystore from disk
+     */
+    private loadKeystore;
+    /**
+     * Save keystore to disk
+     */
+    private saveKeystore;
+    /**
+     * Check if initial setup is completed
+     */
+    isSetupCompleted(): Promise<boolean>;
+    /**
+     * Complete initial setup
+     */
+    completeSetup(data: SetupData): Promise<void>;
+    /**
+     * Get all admin addresses
+     */
+    getAdminAddresses(): Promise<string[]>;
+    /**
+     * Add admin address
+     */
+    addAdminAddress(address: string): Promise<void>;
+    /**
+     * Remove admin address
+     */
+    removeAdminAddress(address: string, currentAdmin: string): Promise<void>;
+    /**
+     * Check if address is admin
+     */
+    isAdmin(address: string): boolean;
+    /**
+     * Get active mnemonic entry
+     */
+    getActiveMnemonic(): Promise<MnemonicEntry>;
+    /**
+     * Get mnemonic by ID
+     */
+    getMnemonic(id: string): Promise<MnemonicEntry>;
+    /**
+     * List all mnemonics (summary only)
+     */
+    listMnemonics(): Promise<MnemonicSummary[]>;
+    /**
+     * Add new mnemonic
+     */
+    addMnemonic(data: AddMnemonicData): Promise<MnemonicEntry>;
+    /**
+     * Update mnemonic label
+     */
+    updateMnemonicLabel(id: string, label: string): Promise<void>;
+    /**
+     * Switch active mnemonic
+     */
+    switchActiveMnemonic(id: string): Promise<void>;
+    /**
+     * Delete mnemonic and its data
+     */
+    deleteMnemonic(id: string, deleteData?: boolean): Promise<void>;
+    /**
+     * Get node configuration for a mnemonic
+     */
+    getNodeConfig(mnemonicId: string): Promise<NodeConfig>;
+    /**
+     * Check if node configuration can be modified
+     */
+    canModifyNodeConfig(mnemonicId: string): Promise<ConfigModificationCheck>;
+    /**
+     * Update node configuration
+     */
+    updateNodeConfig(mnemonicId: string, config: Partial<NodeConfig>): Promise<void>;
+    /**
+     * Delete blockchain data directory
+     */
+    deleteNodeData(mnemonicId: string): Promise<{
+        deletedDir: string;
+        dataSize: string;
+    }>;
+    /**
+     * Check if keystore is locked
+     */
+    isLocked(): boolean;
+    /**
+     * Check if encryption is enabled for the keystore
+     */
+    isEncryptionEnabled(): boolean;
+    /**
+     * Unlock keystore with password
+     */
+    unlockKeystore(password: string): Promise<void>;
+    /**
+     * Lock keystore (clear password from memory)
+     */
+    lockKeystore(): Promise<void>;
+    /**
+     * Get decrypted mnemonic
+     */
+    getDecryptedMnemonic(mnemonicId: string): Promise<string>;
+    /**
+     * Get genesis accounts for a mnemonic
+     */
+    deriveGenesisAccounts(mnemonicId: string): Promise<DerivedAccount[]>;
+    /**
+     * Get faucet account for a mnemonic
+     */
+    deriveFaucetAccount(mnemonicId: string): Promise<DerivedAccount>;
+    /**
+     * Derive accounts from mnemonic (HD wallet derivation)
+     * Returns accounts with both Core and eSpace private keys
+     * Uses @cfxdevkit/core/wallet for derivation
+     */
+    deriveAccountsFromMnemonic(mnemonic: string, _network: 'core' | 'espace', // Kept for API compatibility, both keys are always derived
+    count: number, startIndex?: number, chainIdOverride?: number): Promise<DerivedAccount[]>;
+    /**
+     * Get data directory for active mnemonic
+     */
+    getDataDir(): Promise<string>;
+    /**
+     * Get data directory for specific mnemonic
+     */
+    private getDataDirForMnemonic;
+    /**
+     * Get mnemonic hash (for display)
+     */
+    getMnemonicHash(): Promise<string>;
+    /**
+     * Get active mnemonic label
+     */
+    getActiveLabel(): string;
+    /**
+     * Get active mnemonic index
+     */
+    getActiveIndex(): number;
+    /**
+     * Generate new BIP-39 mnemonic
+     * Uses @cfxdevkit/core/wallet for generation
+     */
+    generateMnemonic(): string;
+    /**
+     * Validate mnemonic format
+     * Uses @cfxdevkit/core/wallet for validation
+     */
+    validateMnemonic(mnemonic: string): boolean;
+    /**
+     * Ensure keystore is loaded
+     */
+    private ensureKeystoreLoaded;
+    /**
+     * Create a mnemonic entry with node config and derived keys
+     */
+    private createMnemonicEntry;
+    /**
+     * Calculate config hash for integrity check
+     */
+    private calculateConfigHash;
+    /**
+     * Get data directory size (human-readable)
+     */
+    private getDataDirSize;
+}
+/**
+ * Get singleton KeystoreService instance
+ */
+declare function getKeystoreService(): KeystoreService;
+
+interface SwapQuoteParams {
+    tokenIn: Address;
+    tokenOut: Address;
+    amountIn: string;
+    slippage?: number;
+    network?: 'testnet' | 'mainnet';
+}
+interface SwapExecuteParams extends SwapQuoteParams {
+    account: number;
+    deadline?: number;
+}
+interface SwapQuote {
+    amountIn: string;
+    amountOut: string;
+    amountOutMin: string;
+    path: Address[];
+    priceImpact: string;
+    slippage: number;
+}
+interface SwapResult {
+    hash: string;
+    amountIn: string;
+    amountOut: string;
+    path: Address[];
+}
+/**
+ * Minimal interface for the devkit dependency used by SwapService.
+ * Only the methods actually consumed by this service are listed.
+ */
+interface SwapDevKit {
+    getAccounts(): Record<number, {
+        privateKey: string;
+        evmAddress: string;
+    }>;
+}
+declare class SwapService {
+    private devkit;
+    constructor(devkit: SwapDevKit);
+    /**
+     * Get swap contracts for network
+     */
+    private getContracts;
+    /**
+     * Get token info
+     */
+    getToken(symbol: string, network?: 'testnet' | 'mainnet'): {
+        readonly address: Address;
+        readonly symbol: "WCFX";
+        readonly name: "Wrapped CFX";
+        readonly decimals: 18;
+    } | {
+        readonly address: Address;
+        readonly symbol: "USDT";
+        readonly name: "Tether USD";
+        readonly decimals: 18;
+    } | {
+        readonly address: Address;
+        readonly symbol: "USDC";
+        readonly name: "USD Coin";
+        readonly decimals: 18;
+    };
+    /**
+     * List available tokens
+     */
+    listTokens(network?: 'testnet' | 'mainnet'): ({
+        readonly address: Address;
+        readonly symbol: "WCFX";
+        readonly name: "Wrapped CFX";
+        readonly decimals: 18;
+    } | {
+        readonly address: Address;
+        readonly symbol: "USDT";
+        readonly name: "Tether USD";
+        readonly decimals: 18;
+    } | {
+        readonly address: Address;
+        readonly symbol: "USDC";
+        readonly name: "USD Coin";
+        readonly decimals: 18;
+    })[];
+    /**
+     * Get swap quote
+     */
+    getQuote(params: SwapQuoteParams): Promise<SwapQuote>;
+    /**
+     * Execute swap
+     */
+    executeSwap(params: SwapExecuteParams): Promise<SwapResult>;
+    /**
+     * Get Swappi router ABI
+     */
+    getRouterABI(): readonly [{
+        readonly inputs: readonly [{
+            readonly name: "amountIn";
+            readonly type: "uint256";
+        }, {
+            readonly name: "amountOutMin";
+            readonly type: "uint256";
+        }, {
+            readonly name: "path";
+            readonly type: "address[]";
+        }, {
+            readonly name: "to";
+            readonly type: "address";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+        readonly name: "swapExactTokensForTokens";
+        readonly outputs: readonly [{
+            readonly name: "amounts";
+            readonly type: "uint256[]";
+        }];
+        readonly stateMutability: "nonpayable";
+        readonly type: "function";
+    }, {
+        readonly inputs: readonly [{
+            readonly name: "amountOut";
+            readonly type: "uint256";
+        }, {
+            readonly name: "amountInMax";
+            readonly type: "uint256";
+        }, {
+            readonly name: "path";
+            readonly type: "address[]";
+        }, {
+            readonly name: "to";
+            readonly type: "address";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+        readonly name: "swapTokensForExactTokens";
+        readonly outputs: readonly [{
+            readonly name: "amounts";
+            readonly type: "uint256[]";
+        }];
+        readonly stateMutability: "nonpayable";
+        readonly type: "function";
+    }, {
+        readonly inputs: readonly [{
+            readonly name: "amountIn";
+            readonly type: "uint256";
+        }, {
+            readonly name: "path";
+            readonly type: "address[]";
+        }];
+        readonly name: "getAmountsOut";
+        readonly outputs: readonly [{
+            readonly name: "amounts";
+            readonly type: "uint256[]";
+        }];
+        readonly stateMutability: "view";
+        readonly type: "function";
+    }, {
+        readonly inputs: readonly [{
+            readonly name: "amountOut";
+            readonly type: "uint256";
+        }, {
+            readonly name: "path";
+            readonly type: "address[]";
+        }];
+        readonly name: "getAmountsIn";
+        readonly outputs: readonly [{
+            readonly name: "amounts";
+            readonly type: "uint256[]";
+        }];
+        readonly stateMutability: "view";
+        readonly type: "function";
+    }];
+    /**
+     * Get Swappi contract addresses
+     */
+    getContractAddresses(network?: 'testnet' | 'mainnet'): {
+        readonly FACTORY: Address;
+        readonly ROUTER: Address;
+    } | {
+        readonly FACTORY: Address;
+        readonly ROUTER: Address;
+    };
+}
+
+export { type AddMnemonicData, type ConfigModificationCheck, type DerivedAccount, type DerivedKeys, EncryptionService, KeystoreLockedError, KeystoreService, type KeystoreV2, type MnemonicEntry, type MnemonicSummary, type NodeConfig, type SetupData, type SwapExecuteParams, type SwapQuote, type SwapQuoteParams, type SwapResult, SwapService, type ValidationResult, getKeystoreService };