pwc-sdk-wallet 0.6.3

package/dist/crypto/EncryptionService.js

@@ -0,0 +1,178 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EncryptionService = void 0;
+const CryptoJS = __importStar(require("crypto-js"));
+const bip39 = __importStar(require("bip39"));
+const bip32_1 = require("bip32");
+const ecc = __importStar(require("@bitcoinerlab/secp256k1"));
+const buffer_1 = require("buffer");
+const chains_1 = require("../config/chains");
+const constants_1 = require("../config/constants");
+const bip32 = (0, bip32_1.BIP32Factory)(ecc);
+const SALT_LENGTH = constants_1.SECURITY_CONFIG.SALT_LENGTH;
+const KEY_LENGTH = constants_1.SECURITY_CONFIG.AES_KEY_SIZE / 8; // Convert bits to bytes
+const IV_LENGTH = constants_1.SECURITY_CONFIG.IV_LENGTH;
+/**
+ * Service providing cryptographic operations including mnemonic generation,
+ * encryption/decryption, and key derivation for the wallet SDK.
+ */
+class EncryptionService {
+    /**
+     * Generates a cryptographically secure mnemonic phrase.
+     * @returns A 24-word mnemonic phrase following BIP-39 standard
+     */
+    static generateMnemonic() {
+        return bip39.generateMnemonic(256);
+    }
+    /**
+     * Validates a mnemonic phrase to ensure it's properly formatted and contains valid words.
+     * @param mnemonic - The mnemonic phrase to validate (12, 15, 18, 21, or 24 words)
+     * @returns True if the mnemonic is valid, false otherwise
+     */
+    static validateMnemonic(mnemonic) {
+        return bip39.validateMnemonic(mnemonic);
+    }
+    /**
+     * Encrypts data using AES-256-CBC with PBKDF2 key derivation.
+     * @param data - The plaintext data to encrypt
+     * @param password - The password to use for key derivation
+     * @returns Promise resolving to the encrypted data structure
+     * @throws Error if encryption fails
+     */
+    static async encrypt(data, password) {
+        const salt = CryptoJS.lib.WordArray.random(SALT_LENGTH);
+        const iv = CryptoJS.lib.WordArray.random(IV_LENGTH);
+        const key = CryptoJS.PBKDF2(password, salt, {
+            keySize: KEY_LENGTH,
+            iterations: (0, constants_1.getPBKDF2Iterations)(),
+            hasher: CryptoJS.algo.SHA256,
+        });
+        const encrypted = CryptoJS.AES.encrypt(data, key, {
+            iv: iv,
+            mode: CryptoJS.mode.CBC,
+            padding: CryptoJS.pad.Pkcs7,
+        });
+        return {
+            encryptedData: encrypted.toString(),
+            iv: CryptoJS.enc.Base64.stringify(iv),
+            salt: CryptoJS.enc.Base64.stringify(salt),
+        };
+    }
+    /**
+     * Decrypts data that was encrypted using the encrypt method.
+     * @param encryptedData - The encrypted data structure containing data, iv, and salt
+     * @param password - The password used for the original encryption
+     * @returns Promise resolving to the decrypted plaintext data
+     * @throws Error if decryption fails due to incorrect password or corrupted data
+     */
+    static async decrypt(encryptedData, password) {
+        const salt = CryptoJS.enc.Base64.parse(encryptedData.salt);
+        const iv = CryptoJS.enc.Base64.parse(encryptedData.iv);
+        const key = CryptoJS.PBKDF2(password, salt, {
+            keySize: KEY_LENGTH,
+            iterations: (0, constants_1.getPBKDF2Iterations)(),
+            hasher: CryptoJS.algo.SHA256,
+        });
+        const decrypted = CryptoJS.AES.decrypt(encryptedData.encryptedData, key, {
+            iv: iv,
+            mode: CryptoJS.mode.CBC,
+            padding: CryptoJS.pad.Pkcs7,
+        });
+        const decryptedText = decrypted.toString(CryptoJS.enc.Utf8);
+        if (!decryptedText) {
+            throw new Error("Decryption failed. Invalid password or corrupted data.");
+        }
+        return decryptedText;
+    }
+    /**
+     * Converts a mnemonic phrase to a seed buffer using PBKDF2.
+     * @param mnemonic - The mnemonic phrase to convert
+     * @returns Promise resolving to the seed buffer
+     */
+    static async mnemonicToSeed(mnemonic) {
+        return bip39.mnemonicToSeed(mnemonic);
+    }
+    /**
+     * Derives a private key from a seed using BIP-32 derivation.
+     * @param seed - The seed buffer to derive from
+     * @param path - The derivation path to use (defaults to EVM path)
+     * @returns Promise resolving to the derived private key buffer
+     * @throws Error if private key derivation fails
+     */
+    static async derivePrivateKey(seed, path = chains_1.DERIVATION_PATHS.EVM) {
+        const root = bip32.fromSeed(seed);
+        const child = root.derivePath(path);
+        if (!child.privateKey) {
+            throw new Error('Could not derive private key.');
+        }
+        return buffer_1.Buffer.from(child.privateKey);
+    }
+    /**
+     * Attempts to clear sensitive data from memory.
+     * Note: JavaScript doesn't guarantee memory clearing, but this helps reduce exposure.
+     * @param data - The sensitive data to clear (string or buffer)
+     */
+    static clearSensitiveData(data) {
+        if (typeof data === 'string') {
+            // For strings, we can't directly clear memory, but we can help GC
+            // by removing references and using setTimeout to delay cleanup
+            setTimeout(() => {
+                // This helps reduce the time sensitive data stays in memory
+            }, 0);
+        }
+        else if (buffer_1.Buffer.isBuffer(data)) {
+            // For buffers, we can fill with zeros
+            data.fill(0);
+        }
+    }
+    /**
+     * Creates a temporary copy of sensitive data that gets cleared after use.
+     * This is a security measure to minimize the time sensitive data stays in memory.
+     * @param data - The sensitive data to use temporarily
+     * @param callback - Function to execute with the temporary data
+     * @returns The result of the callback function
+     */
+    static withTemporaryData(data, callback) {
+        try {
+            const result = callback(data);
+            return result;
+        }
+        finally {
+            this.clearSensitiveData(data);
+        }
+    }
+}
+exports.EncryptionService = EncryptionService;

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export { Vault, type VaultConfig } from './Vault';
+export type { Account } from './Vault';
+export type { ChainId, ChainConfig } from './config/chains';
+export type { EncryptedData } from './crypto/EncryptionService';
+export type { Token } from './chain/ChainService';
+export type { Recipient, MultiTransferOptions, MultiTransferResult, BatchResult, ValidationResult } from './types/multiTransfer';
+export type { QRCodeData, WalletImportData, TransactionData } from './services/QRCodeService';
+export { SUPPORTED_CHAINS, DERIVATION_PATHS, registerCustomChain, overrideChain, overrideChains, getChainConfig, setupChainConfigs, getAllAvailableChains, clearCustomChains, clearOverrides, clearOverride, getCustomChains, getOverrides, setGlobalRPCConfig, setGlobalExplorerConfig, clearGlobalConfigs } from './config/chains';
+export { GAS_CONFIG, NETWORK_GAS_CONFIG, getNetworkGasConfig, calculateOptimalGasPrice, setGlobalGasConfig, setGlobalNetworkGasConfig, getGasConfig, clearGlobalGasConfigs } from './config/gas';
+export { VANITY_WALLET_CONFIG, SECURITY_CONFIG, NETWORK_CONFIG, CACHE_CONFIG, VALIDATION_CONFIG } from './config/constants';
+export { getEnvironmentConfig, validateEnvironmentConfig, getEnvVar, getEnvVarNumber, getEnvVarBigInt, getEnvVarBoolean } from './config/environment';
+export { HDKeyring } from './keyrings/HDKeyring';
+export { SimpleKeyring } from './keyrings/SimpleKeyring';
+export { SolanaKeyring } from './keyrings/SolanaKeyring';
+export { ChainService } from './chain/ChainService';
+export { SolanaChainService } from './chain/SolanaChainService';
+export { EncryptionService } from './crypto/EncryptionService';
+export { MultiTransferService } from './services/MultiTransferService';
+export { BatchProcessor } from './services/BatchProcessor';
+export { QRCodeService } from './services/QRCodeService';
+export * from './services/TokenUtils';
+export * from './services/nft/NFTService';

package/dist/index.js

@@ -0,0 +1,96 @@
+"use strict";
+// --- Main SDK Exports ---
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QRCodeService = exports.BatchProcessor = exports.MultiTransferService = exports.EncryptionService = exports.SolanaChainService = exports.ChainService = exports.SolanaKeyring = exports.SimpleKeyring = exports.HDKeyring = exports.getEnvVarBoolean = exports.getEnvVarBigInt = exports.getEnvVarNumber = exports.getEnvVar = exports.validateEnvironmentConfig = exports.getEnvironmentConfig = exports.VALIDATION_CONFIG = exports.CACHE_CONFIG = exports.NETWORK_CONFIG = exports.SECURITY_CONFIG = exports.VANITY_WALLET_CONFIG = exports.clearGlobalGasConfigs = exports.getGasConfig = exports.setGlobalNetworkGasConfig = exports.setGlobalGasConfig = exports.calculateOptimalGasPrice = exports.getNetworkGasConfig = exports.NETWORK_GAS_CONFIG = exports.GAS_CONFIG = exports.clearGlobalConfigs = exports.setGlobalExplorerConfig = exports.setGlobalRPCConfig = exports.getOverrides = exports.getCustomChains = exports.clearOverride = exports.clearOverrides = exports.clearCustomChains = exports.getAllAvailableChains = exports.setupChainConfigs = exports.getChainConfig = exports.overrideChains = exports.overrideChain = exports.registerCustomChain = exports.DERIVATION_PATHS = exports.SUPPORTED_CHAINS = exports.Vault = void 0;
+// The primary `Vault` class is the main entry point for interacting with the SDK.
+var Vault_1 = require("./Vault");
+Object.defineProperty(exports, "Vault", { enumerable: true, get: function () { return Vault_1.Vault; } });
+// --- Configuration ---
+// Chain configuration exports
+var chains_1 = require("./config/chains");
+Object.defineProperty(exports, "SUPPORTED_CHAINS", { enumerable: true, get: function () { return chains_1.SUPPORTED_CHAINS; } });
+Object.defineProperty(exports, "DERIVATION_PATHS", { enumerable: true, get: function () { return chains_1.DERIVATION_PATHS; } });
+Object.defineProperty(exports, "registerCustomChain", { enumerable: true, get: function () { return chains_1.registerCustomChain; } });
+Object.defineProperty(exports, "overrideChain", { enumerable: true, get: function () { return chains_1.overrideChain; } });
+Object.defineProperty(exports, "overrideChains", { enumerable: true, get: function () { return chains_1.overrideChains; } });
+Object.defineProperty(exports, "getChainConfig", { enumerable: true, get: function () { return chains_1.getChainConfig; } });
+Object.defineProperty(exports, "setupChainConfigs", { enumerable: true, get: function () { return chains_1.setupChainConfigs; } });
+Object.defineProperty(exports, "getAllAvailableChains", { enumerable: true, get: function () { return chains_1.getAllAvailableChains; } });
+Object.defineProperty(exports, "clearCustomChains", { enumerable: true, get: function () { return chains_1.clearCustomChains; } });
+Object.defineProperty(exports, "clearOverrides", { enumerable: true, get: function () { return chains_1.clearOverrides; } });
+Object.defineProperty(exports, "clearOverride", { enumerable: true, get: function () { return chains_1.clearOverride; } });
+Object.defineProperty(exports, "getCustomChains", { enumerable: true, get: function () { return chains_1.getCustomChains; } });
+Object.defineProperty(exports, "getOverrides", { enumerable: true, get: function () { return chains_1.getOverrides; } });
+Object.defineProperty(exports, "setGlobalRPCConfig", { enumerable: true, get: function () { return chains_1.setGlobalRPCConfig; } });
+Object.defineProperty(exports, "setGlobalExplorerConfig", { enumerable: true, get: function () { return chains_1.setGlobalExplorerConfig; } });
+Object.defineProperty(exports, "clearGlobalConfigs", { enumerable: true, get: function () { return chains_1.clearGlobalConfigs; } });
+// Gas configuration exports
+var gas_1 = require("./config/gas");
+Object.defineProperty(exports, "GAS_CONFIG", { enumerable: true, get: function () { return gas_1.GAS_CONFIG; } });
+Object.defineProperty(exports, "NETWORK_GAS_CONFIG", { enumerable: true, get: function () { return gas_1.NETWORK_GAS_CONFIG; } });
+Object.defineProperty(exports, "getNetworkGasConfig", { enumerable: true, get: function () { return gas_1.getNetworkGasConfig; } });
+Object.defineProperty(exports, "calculateOptimalGasPrice", { enumerable: true, get: function () { return gas_1.calculateOptimalGasPrice; } });
+Object.defineProperty(exports, "setGlobalGasConfig", { enumerable: true, get: function () { return gas_1.setGlobalGasConfig; } });
+Object.defineProperty(exports, "setGlobalNetworkGasConfig", { enumerable: true, get: function () { return gas_1.setGlobalNetworkGasConfig; } });
+Object.defineProperty(exports, "getGasConfig", { enumerable: true, get: function () { return gas_1.getGasConfig; } });
+Object.defineProperty(exports, "clearGlobalGasConfigs", { enumerable: true, get: function () { return gas_1.clearGlobalGasConfigs; } });
+// Constants exports
+var constants_1 = require("./config/constants");
+Object.defineProperty(exports, "VANITY_WALLET_CONFIG", { enumerable: true, get: function () { return constants_1.VANITY_WALLET_CONFIG; } });
+Object.defineProperty(exports, "SECURITY_CONFIG", { enumerable: true, get: function () { return constants_1.SECURITY_CONFIG; } });
+Object.defineProperty(exports, "NETWORK_CONFIG", { enumerable: true, get: function () { return constants_1.NETWORK_CONFIG; } });
+Object.defineProperty(exports, "CACHE_CONFIG", { enumerable: true, get: function () { return constants_1.CACHE_CONFIG; } });
+Object.defineProperty(exports, "VALIDATION_CONFIG", { enumerable: true, get: function () { return constants_1.VALIDATION_CONFIG; } });
+// Environment configuration exports
+var environment_1 = require("./config/environment");
+Object.defineProperty(exports, "getEnvironmentConfig", { enumerable: true, get: function () { return environment_1.getEnvironmentConfig; } });
+Object.defineProperty(exports, "validateEnvironmentConfig", { enumerable: true, get: function () { return environment_1.validateEnvironmentConfig; } });
+Object.defineProperty(exports, "getEnvVar", { enumerable: true, get: function () { return environment_1.getEnvVar; } });
+Object.defineProperty(exports, "getEnvVarNumber", { enumerable: true, get: function () { return environment_1.getEnvVarNumber; } });
+Object.defineProperty(exports, "getEnvVarBigInt", { enumerable: true, get: function () { return environment_1.getEnvVarBigInt; } });
+Object.defineProperty(exports, "getEnvVarBoolean", { enumerable: true, get: function () { return environment_1.getEnvVarBoolean; } });
+// --- Lower-level Services (for advanced use cases) ---
+// Note: Exposing these is optional. We expose them to allow for more flexibility.
+// Keyring implementations
+var HDKeyring_1 = require("./keyrings/HDKeyring");
+Object.defineProperty(exports, "HDKeyring", { enumerable: true, get: function () { return HDKeyring_1.HDKeyring; } });
+var SimpleKeyring_1 = require("./keyrings/SimpleKeyring");
+Object.defineProperty(exports, "SimpleKeyring", { enumerable: true, get: function () { return SimpleKeyring_1.SimpleKeyring; } });
+var SolanaKeyring_1 = require("./keyrings/SolanaKeyring");
+Object.defineProperty(exports, "SolanaKeyring", { enumerable: true, get: function () { return SolanaKeyring_1.SolanaKeyring; } });
+// Chain services
+var ChainService_1 = require("./chain/ChainService");
+Object.defineProperty(exports, "ChainService", { enumerable: true, get: function () { return ChainService_1.ChainService; } });
+var SolanaChainService_1 = require("./chain/SolanaChainService");
+Object.defineProperty(exports, "SolanaChainService", { enumerable: true, get: function () { return SolanaChainService_1.SolanaChainService; } });
+// `EncryptionService` provides access to the underlying encryption/decryption methods.
+var EncryptionService_1 = require("./crypto/EncryptionService");
+Object.defineProperty(exports, "EncryptionService", { enumerable: true, get: function () { return EncryptionService_1.EncryptionService; } });
+// Multi-transfer services
+var MultiTransferService_1 = require("./services/MultiTransferService");
+Object.defineProperty(exports, "MultiTransferService", { enumerable: true, get: function () { return MultiTransferService_1.MultiTransferService; } });
+var BatchProcessor_1 = require("./services/BatchProcessor");
+Object.defineProperty(exports, "BatchProcessor", { enumerable: true, get: function () { return BatchProcessor_1.BatchProcessor; } });
+// QR code service
+var QRCodeService_1 = require("./services/QRCodeService");
+Object.defineProperty(exports, "QRCodeService", { enumerable: true, get: function () { return QRCodeService_1.QRCodeService; } });
+__exportStar(require("./services/TokenUtils"), exports);
+__exportStar(require("./services/nft/NFTService"), exports);
+// --- React Native Components ---
+// QR code components for React Native (uncomment when components are created)
+// export { QRCodeDisplay } from './components/QRCodeDisplay';
+// export { QRCodeScanner } from './components/QRCodeScanner';

package/dist/keyrings/HDKeyring.d.ts

@@ -0,0 +1,72 @@
+/**
+ * HD (Hierarchical Deterministic) keyring for managing multiple accounts
+ * derived from a single mnemonic phrase using BIP-44 derivation paths.
+ * Supports EVM-compatible chains.
+ */
+export declare class HDKeyring {
+    readonly type = "HD";
+    private mnemonic;
+    private seed;
+    private static seedCache;
+    accounts: string[];
+    /**
+     * Creates a new HDKeyring instance from a mnemonic phrase.
+     * @param mnemonic - The mnemonic phrase (12, 15, 18, 21, or 24 words)
+     * @throws Error if the mnemonic is invalid
+     */
+    constructor(mnemonic: string);
+    /**
+     * Initializes the keyring by generating the seed and creating the first account.
+     * This method must be called before using the keyring.
+     * @returns Promise that resolves when initialization is complete
+     * @throws Error if seed generation or account derivation fails
+     */
+    initialize(): Promise<void>;
+    /**
+     * Derives an account at a specific index using BIP-44 derivation.
+     * @param index - The account index to derive (0-based)
+     * @returns Promise resolving to an object containing the derived address and private key
+     * @throws Error if the keyring is not initialized or derivation fails
+     */
+    private deriveAccount;
+    /**
+     * Adds a new account derived from the mnemonic at the next available index.
+     * @returns Promise resolving to the address of the newly created account
+     * @throws Error if account derivation fails or duplicate address is generated
+     */
+    addNewAccount(): Promise<string>;
+    /**
+     * Gets the private key for a given address managed by this keyring.
+     * @param address - The account address to get the private key for
+     * @returns Promise resolving to the private key as a hex string
+     * @throws Error if the address is not found in this keyring
+     */
+    getPrivateKeyForAddress(address: string): Promise<string>;
+    /**
+     * Returns the mnemonic phrase. USE WITH CAUTION - this exposes sensitive data.
+     * @returns The mnemonic phrase as a string
+     */
+    getMnemonic(): string;
+    /**
+     * Serializes the keyring data for encryption and storage.
+     * @returns An object containing the keyring type, mnemonic, and account addresses
+     */
+    serialize(): any;
+    /**
+     * Deserializes data into an HDKeyring instance.
+     * @param data - The serialized keyring data
+     * @returns Promise resolving to a new HDKeyring instance
+     * @throws Error if the data is invalid or missing required fields
+     */
+    static deserialize(data: any): Promise<HDKeyring>;
+    /**
+     * Clears the seed cache to free up memory.
+     * Call this when you want to clear sensitive data from memory.
+     */
+    static clearSeedCache(): void;
+    /**
+     * Gets the cache size for debugging purposes.
+     * @returns Number of cached seeds
+     */
+    static getSeedCacheSize(): number;
+}

package/dist/keyrings/HDKeyring.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HDKeyring = void 0;
+const EncryptionService_1 = require("../crypto/EncryptionService");
+const chains_1 = require("../config/chains");
+const ChainService_1 = require("../chain/ChainService");
+/**
+ * HD (Hierarchical Deterministic) keyring for managing multiple accounts
+ * derived from a single mnemonic phrase using BIP-44 derivation paths.
+ * Supports EVM-compatible chains.
+ */
+class HDKeyring {
+    /**
+     * Creates a new HDKeyring instance from a mnemonic phrase.
+     * @param mnemonic - The mnemonic phrase (12, 15, 18, 21, or 24 words)
+     * @throws Error if the mnemonic is invalid
+     */
+    constructor(mnemonic) {
+        this.type = 'HD';
+        this.seed = null;
+        // For now, we manage one account, but this can be extended.
+        this.accounts = [];
+        if (!EncryptionService_1.EncryptionService.validateMnemonic(mnemonic)) {
+            throw new Error('Invalid mnemonic');
+        }
+        this.mnemonic = mnemonic;
+    }
+    /**
+     * Initializes the keyring by generating the seed and creating the first account.
+     * This method must be called before using the keyring.
+     * @returns Promise that resolves when initialization is complete
+     * @throws Error if seed generation or account derivation fails
+     */
+    async initialize() {
+        // Check cache first
+        if (HDKeyring.seedCache.has(this.mnemonic)) {
+            this.seed = HDKeyring.seedCache.get(this.mnemonic);
+        }
+        else {
+            this.seed = await EncryptionService_1.EncryptionService.mnemonicToSeed(this.mnemonic);
+            // Cache the seed
+            HDKeyring.seedCache.set(this.mnemonic, this.seed);
+        }
+        const firstAccount = await this.deriveAccount(0);
+        this.accounts.push(firstAccount.address);
+    }
+    /**
+     * Derives an account at a specific index using BIP-44 derivation.
+     * @param index - The account index to derive (0-based)
+     * @returns Promise resolving to an object containing the derived address and private key
+     * @throws Error if the keyring is not initialized or derivation fails
+     */
+    async deriveAccount(index) {
+        if (!this.seed) {
+            throw new Error('Keyring not initialized. Call initialize() first.');
+        }
+        // This can be extended to support custom paths per index.
+        const path = `${chains_1.DERIVATION_PATHS.EVM.slice(0, -1)}${index}`;
+        const privateKeyBuffer = await EncryptionService_1.EncryptionService.derivePrivateKey(this.seed, path);
+        const privateKeyHex = privateKeyBuffer.toString('hex');
+        const address = ChainService_1.ChainService.getAddress(privateKeyHex);
+        return { address, privateKey: privateKeyHex };
+    }
+    /**
+     * Adds a new account derived from the mnemonic at the next available index.
+     * @returns Promise resolving to the address of the newly created account
+     * @throws Error if account derivation fails or duplicate address is generated
+     */
+    async addNewAccount() {
+        const newIndex = this.accounts.length;
+        const newAccount = await this.deriveAccount(newIndex);
+        if (this.accounts.includes(newAccount.address)) {
+            throw new Error('Duplicate account derived. Please check derivation path logic.');
+        }
+        this.accounts.push(newAccount.address);
+        return newAccount.address;
+    }
+    /**
+     * Gets the private key for a given address managed by this keyring.
+     * @param address - The account address to get the private key for
+     * @returns Promise resolving to the private key as a hex string
+     * @throws Error if the address is not found in this keyring
+     */
+    async getPrivateKeyForAddress(address) {
+        const index = this.accounts.indexOf(address);
+        if (index === -1) {
+            throw new Error('Address not found in this keyring.');
+        }
+        const account = await this.deriveAccount(index);
+        return account.privateKey;
+    }
+    /**
+     * Returns the mnemonic phrase. USE WITH CAUTION - this exposes sensitive data.
+     * @returns The mnemonic phrase as a string
+     */
+    getMnemonic() {
+        return this.mnemonic;
+    }
+    /**
+     * Serializes the keyring data for encryption and storage.
+     * @returns An object containing the keyring type, mnemonic, and account addresses
+     */
+    serialize() {
+        return {
+            type: this.type,
+            mnemonic: this.mnemonic,
+            accounts: this.accounts
+        };
+    }
+    /**
+     * Deserializes data into an HDKeyring instance.
+     * @param data - The serialized keyring data
+     * @returns Promise resolving to a new HDKeyring instance
+     * @throws Error if the data is invalid or missing required fields
+     */
+    static async deserialize(data) {
+        if (data.type !== 'HD' || !data.mnemonic) {
+            throw new Error('Invalid data for HDKeyring deserialization.');
+        }
+        const keyring = new HDKeyring(data.mnemonic);
+        // If accounts were persisted, restore them. Otherwise, initialize fresh.
+        if (data.accounts && data.accounts.length > 0) {
+            keyring.accounts = data.accounts;
+            // Cache the seed to avoid regenerating it on every load
+            if (HDKeyring.seedCache.has(keyring.mnemonic)) {
+                keyring.seed = HDKeyring.seedCache.get(keyring.mnemonic);
+            }
+            else {
+                keyring.seed = await EncryptionService_1.EncryptionService.mnemonicToSeed(keyring.mnemonic);
+                // Cache the seed
+                HDKeyring.seedCache.set(keyring.mnemonic, keyring.seed);
+            }
+        }
+        else {
+            await keyring.initialize();
+        }
+        return keyring;
+    }
+    /**
+     * Clears the seed cache to free up memory.
+     * Call this when you want to clear sensitive data from memory.
+     */
+    static clearSeedCache() {
+        HDKeyring.seedCache.clear();
+    }
+    /**
+     * Gets the cache size for debugging purposes.
+     * @returns Number of cached seeds
+     */
+    static getSeedCacheSize() {
+        return HDKeyring.seedCache.size;
+    }
+}
+exports.HDKeyring = HDKeyring;
+// Cache để tránh tạo lại seed
+HDKeyring.seedCache = new Map();

package/dist/keyrings/SimpleKeyring.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Simple keyring for managing a single account from a private key.
+ * Used for importing existing accounts that are not derived from a mnemonic.
+ */
+export declare class SimpleKeyring {
+    readonly type = "Simple";
+    private privateKey;
+    address: string;
+    /**
+     * Creates a new SimpleKeyring instance from a private key.
+     * @param privateKey - The private key to import (hex string without '0x' prefix)
+     */
+    constructor(privateKey: string);
+    /**
+     * Returns the private key. This should be used with extreme caution.
+     * @returns The private key as a hex string
+     */
+    getPrivateKey(): string;
+    /**
+     * Serializes the keyring into a plain object for encryption and storage.
+     * @returns An object containing the keyring type and private key
+     */
+    serialize(): any;
+    /**
+     * Deserializes a plain object back into a SimpleKeyring instance.
+     * @param data - The serialized keyring data
+     * @returns A new SimpleKeyring instance
+     * @throws Error if the data is invalid or missing required fields
+     */
+    static deserialize(data: any): SimpleKeyring;
+}

package/dist/keyrings/SimpleKeyring.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimpleKeyring = void 0;
+const ChainService_1 = require("../chain/ChainService");
+/**
+ * Simple keyring for managing a single account from a private key.
+ * Used for importing existing accounts that are not derived from a mnemonic.
+ */
+class SimpleKeyring {
+    /**
+     * Creates a new SimpleKeyring instance from a private key.
+     * @param privateKey - The private key to import (hex string without '0x' prefix)
+     */
+    constructor(privateKey) {
+        this.type = 'Simple';
+        this.privateKey = privateKey;
+        this.address = ChainService_1.ChainService.getAddress(privateKey);
+    }
+    /**
+     * Returns the private key. This should be used with extreme caution.
+     * @returns The private key as a hex string
+     */
+    getPrivateKey() {
+        return this.privateKey;
+    }
+    /**
+     * Serializes the keyring into a plain object for encryption and storage.
+     * @returns An object containing the keyring type and private key
+     */
+    serialize() {
+        return {
+            type: this.type,
+            privateKey: this.privateKey,
+        };
+    }
+    /**
+     * Deserializes a plain object back into a SimpleKeyring instance.
+     * @param data - The serialized keyring data
+     * @returns A new SimpleKeyring instance
+     * @throws Error if the data is invalid or missing required fields
+     */
+    static deserialize(data) {
+        if (data.type !== 'Simple' || !data.privateKey) {
+            throw new Error('Invalid data for SimpleKeyring deserialization.');
+        }
+        return new SimpleKeyring(data.privateKey);
+    }
+}
+exports.SimpleKeyring = SimpleKeyring;