ethershell 0.1.0-alpha.0

package/src/services/network.js

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Network provider management for Ethereum connections
+ * @description Manages JSON-RPC provider connections to Ethereum networks,
+ * allowing users to switch between different networks and retrieve network information.
+ * @module network
+ */
+
+import { ethers } from 'ethers';
+import { LocalStorage } from 'node-localstorage';
+
+/**
+ * Local storage instance for persisting compiler artifacts paths
+ * @type {LocalStorage}
+ */
+const localStorage = new LocalStorage('./localStorage');
+
+/**
+ * Default JSON-RPC URL for local Ethereum node
+ * @constant {string}
+ */
+const defaultUrl = 'http://127.0.0.1:8545' ;
+
+/**
+ * Currently active network URL
+ * @type {string}
+ */
+export let currentUrl;
+
+/**
+ * Ethers.js JSON-RPC provider instance
+ * @type {ethers.JsonRpcProvider}
+ */
+export let provider 
+
+// Initialize provider with default URL
+/**
+ * The specific RPC endpoint URL saved on storage before.
+ * @type {string}
+ */
+const storedUrl = localStorage.getItem('url');
+if(storedUrl) {
+    provider = new ethers.JsonRpcProvider(storedUrl);;
+    currentUrl = storedUrl
+} else {
+    provider = new ethers.JsonRpcProvider(defaultUrl);
+    currentUrl = defaultUrl;
+}
+
+
+/**
+ * Set a new network provider
+ * @async
+ * @param {string} url - The JSON-RPC endpoint URL
+ * @returns {Promise<void>}
+ * @throws {Error} If connection to the network fails
+ * @example
+ * await set('https://mainnet.infura.io/v3/YOUR-PROJECT-ID');
+ */
+export async function set(url){
+    try{
+        provider = new ethers.JsonRpcProvider(url);
+        currentUrl = url;
+        const result = await provider.getNetwork();
+        const network = {
+            URL: currentUrl,
+            name: result.name,
+            chainId: result.chainId
+        }    
+        localStorage.setItem('url', url);
+        console.log(network);
+    }catch(err){
+        console.error(err);
+    }
+}
+
+/**
+ * Get current network information
+ * @async
+ * @returns {Promise<void>}
+ * @throws {Error} If unable to retrieve network information
+ * @example
+ * await get(); // Logs: { URL: '...', name: 'mainnet', chainId: 1n }
+ */
+export async function get(){
+    try{
+        const result = await provider.getNetwork();
+        const network = {
+            URL: currentUrl,
+            name: result.name,
+            chainId: result.chainId
+        }    
+        console.log(network);
+    }catch(err){
+        console.error(err);
+    }
+}
+
+/**
+ * Get default network URL
+ * @returns {void}
+ * @example
+ * getDefault(); // Logs: { URL: 'http://127.0.0.1:8545' }
+ */
+export function getDefault(){
+    try{
+        const result = {
+            URL: defaultUrl
+        }
+        console.log(result);
+    }catch(err){
+        console.error(err);
+    }
+}

package/src/services/wallet.js

@@ -0,0 +1,375 @@
+/**
+ * @fileoverview Ethereum wallet management utilities
+ * @description Manages Ethereum wallets including creation, import, and deletion
+ * of both regular wallets and HD (Hierarchical Deterministic) wallets. Supports
+ * importing private keys, generating new wallets, and connecting to node-managed accounts.
+ * @module wallet
+ */
+
+import { ethers } from 'ethers';
+import { provider } from './network.js';
+import { 
+    deleteByIndex, 
+    deleteByIndexArr, 
+    getAccountInfo, 
+    detectDupWallet
+ } from '../utils/accounter.js';
+
+/**
+ * Array containing all accounts (imported, generated, HD, and node-managed)
+ * @type {Array<Object>}
+ */
+export let allAccounts = [];
+
+/**
+ * Array containing only regular accounts (imported and generated)
+ * @type {Array<Object>}
+ */
+export let accounts = [];
+
+/**
+ * Array containing only HD (Hierarchical Deterministic) accounts
+ * @type {Array<Object>}
+ */
+export let hdAccounts = [];
+
+/**
+ * Add accounts from private key(s)
+ * @param {string|Array<string>} privKeyArr - Single private key or array of private keys
+ * @throws {Error} If no private key is provided
+ * @example
+ * addAccounts('0x1234...');
+ * addAccounts(['0x1234...', '0x5678...']);
+ */
+export function addAccounts(privKeyArr) {
+    if(!privKeyArr){
+        throw `You need to add at least one private key. If you have no private key you can create new accounts by 'newAccounts()'! `;
+    }
+
+    if(!privKeyArr.length){
+        throw `You need to add at least one private key. If you have no private key you can create new accounts by 'newAccounts()'! `;
+    }
+
+    const dupWallet = detectDupWallet(privKeyArr);
+
+    if(dupWallet.status) {
+        throw `Wallets may NOT be duplicated! You are adding wallet index ${dupWallet.index} again!`
+    }
+
+    const newFrom = allAccounts.length;
+
+    if(typeof privKeyArr === 'string'){
+        const newAccount = new ethers.Wallet(privKeyArr, provider);
+        allAccounts.push({
+            index: allAccounts.length,
+            address: newAccount.address,
+            privateKey: privKeyArr,
+            type: 'user-imported',
+            contracts: []
+        });
+        accounts.push({
+            index: allAccounts.length - 1,
+            address: newAccount.address,
+            privateKey: privKeyArr,
+            type: 'user-imported',
+            contracts: []
+        });
+        console.log(allAccounts[newFrom]);
+    }
+
+    if(Array.isArray(privKeyArr)){
+        privKeyArr.map(privKey => {
+            const newAccount = new ethers.Wallet(privKey, provider);
+            allAccounts.push({
+                index: allAccounts.length,
+                address: newAccount.address,
+                privateKey: privKey,
+                contracts: []
+            });
+            accounts.push({
+                index: allAccounts.length - 1,
+                address: newAccount.address,
+                privateKey: privKey,
+                contracts: []
+            });
+        });
+
+        console.log(allAccounts.slice(newFrom));
+    }
+}
+
+/**
+ * Add HD wallets from a mnemonic phrase
+ * @param {string} phrase - BIP39 mnemonic phrase
+ * @param {number} [count=10] - Number of accounts to derive from the mnemonic
+ * @example
+ * addHD('witch collapse practice feed shame open despair creek road again ice least', 5);
+ */
+export function addHD(phrase, count = 10) {
+    const newFrom = allAccounts.length;
+    const hdNode = ethers.HDNodeWallet.fromPhrase(phrase);
+
+    const existingPhrase = allAccounts.find(wallet => wallet.phrase == phrase);
+    if(existingPhrase) {
+        throw `Error: HD wallet with this mnemonic phrase already exists at index ${existingPhrase.index}!`
+    }
+    
+    for (let i = 0; i < count; i++) {
+        const hdWallet = hdNode.derivePath(i.toString());
+        const dupHDWallet = detectDupWallet(hdWallet.privateKey);
+        if(dupHDWallet.status) {
+            throw `Error: Wallets may NOT be duplicated! You are adding wallet index ${dupHDWallet.index} again!`
+        } else {
+            allAccounts.push({
+                index: allAccounts.length,
+                address: hdWallet.address,
+                phrase: hdWallet.mnemonic.phrase,
+                privateKey: hdWallet.privateKey,
+                type: 'user-imported',
+                path: hdWallet.path,
+                depth: hdWallet.depth,
+                contracts: []
+            });
+            hdAccounts.push({
+                index: allAccounts.length - 1,
+                address: hdWallet.address,
+                phrase: hdWallet.mnemonic.phrase,
+                privateKey: hdWallet.privateKey,
+                type: 'user-imported',
+                path: hdWallet.path,
+                depth: hdWallet.depth,
+                contracts: []
+            });
+        }
+    }
+
+    console.log(`!WARNING!\n The generated accounts are NOT safe. Do NOT use them on main net!`);
+    console.log(allAccounts.slice(newFrom));
+}
+
+/**
+ * Create new random accounts
+ * @param {number} [count=1] - Number of accounts to create
+ * @example
+ * createAccounts(3);
+ */
+export function createAccounts(count = 1) {
+    const newAccounts = Array.from({length: count}, () => ethers.Wallet.createRandom());
+    const newFrom = accounts.length;
+
+    for(let i = 0; i < newAccounts.length; i++) {
+
+        allAccounts.push({
+            index: allAccounts.length,
+            address:  newAccounts[i].address,
+            privateKey: newAccounts[i].privateKey,
+            type: 'user-generated',
+            contracts: []
+        });
+        accounts.push({
+            index: allAccounts.length - 1,
+            address: newAccounts[i].address,
+            privateKey: newAccounts[i].privateKey,
+            type: 'user-generated',
+            contracts: []
+        })
+
+    }
+    console.log(`!WARNING!\n The generated accounts are NOT safe. Do NOT use them on main net!`);
+    console.log(allAccounts.slice(newFrom));
+}
+
+/**
+ * Create new HD wallet with random mnemonic
+ * @param {number} [count=10] - Number of accounts to derive
+ * @example
+ * createHD(5);
+ */
+export function createHD(count = 10) {
+    const hdNode = ethers.HDNodeWallet.createRandom();
+    const newFrom = allAccounts.length;
+    
+    for (let i = 0; i < count; i++) {
+        const hdWallet = hdNode.derivePath(i.toString());
+        allAccounts.push({
+            index: allAccounts.length,
+            address: hdWallet.address,
+            phrase: hdWallet.mnemonic.phrase,
+            privateKey: hdWallet.privateKey,
+            type: 'user-generated',
+            nonce: 0,
+            balance: 0,
+            path: hdWallet.path,
+            depth: hdWallet.depth,
+            contracts: []
+        });
+        hdAccounts.push({
+            index: allAccounts.length - 1,
+            address: hdWallet.address,
+            phrase: hdWallet.mnemonic.phrase,
+            privateKey: hdWallet.privateKey,
+            type: 'user-generated',
+            nonce: 0,
+            balance: 0,
+            path: hdWallet.path,
+            depth: hdWallet.depth,
+            contracts: []
+        });
+    }
+
+    console.log(`!WARNING!\n The generated accounts are NOT safe. Do NOT use them on main net!`);
+    console.log(allAccounts.slice(newFrom));
+}
+
+/**
+ * Get all accounts (imported, generated, HD, and node-managed)
+ * @example
+ * getAllAccounts();
+ */
+export function getAllAccounts() {
+    console.log(`!WARNING!\n The generated accounts are NOT safe. Do NOT use them on main net!`);
+    console.log(allAccounts);
+}
+
+/**
+ * Get regular accounts (imported and generated only)
+ * @example
+ * getAccounts();
+ */
+export function getAccounts() {
+    console.log(`!WARNING!\n The generated accounts are NOT safe. Do NOT use them on main net!`);
+    console.log(accounts);
+}
+
+/**
+ * Get HD accounts only
+ * @example
+ * getHDAccounts();
+ */
+export function getHDAccounts() {
+    console.log(`!WARNING!\n The generated accounts are NOT safe. Do NOT use them on main net!`);
+    console.log(hdAccounts);
+}
+
+/**
+ * Delete account(s) by various identifiers
+ * @param {number|string|Array<number>|null} accPointer - Account index, address, mnemonic phrase, or array of indices
+ * @example
+ * deleteAccount(0); // Delete by index
+ * deleteAccount('0x1234...'); // Delete by address
+ * deleteAccount([0, 2, 5]); // Delete multiple by indices
+ * deleteAccount('witch collapse...'); // Delete all accounts from mnemonic
+ * deleteAccount(); // Delete all accounts
+ */
+export function deleteAccount(accPointer) {
+    if(!accPointer) {
+        deleteByIndex(null);
+        console.log(allAccounts);
+    }
+
+    if(typeof accPointer === 'number') {
+        deleteByIndex(accPointer);
+        console.log(allAccounts);
+    }
+
+    if(ethers.isAddress(accPointer)) {
+        const index = allAccounts.findIndex(wallet => wallet.address === accPointer);
+
+        if(index !== -1) {
+            deleteByIndex(index);
+        }
+        console.log(allAccounts);
+    }
+
+    if(Array.isArray(accPointer)) {
+        deleteByIndexArr(accPointer);
+    }
+
+    if(ethers.Mnemonic.isValidMnemonic(accPointer)) {
+
+        // Find which accounts to be deleted
+        const indicesToDelete = [];
+            
+        for(let i = 0; i < allAccounts.length; i++) {
+            if(allAccounts[i].phrase === accPointer) {
+                indicesToDelete.push(allAccounts[i].index);
+            }
+        }
+
+        // Sort in descending order and delete from highest to lowest
+        indicesToDelete.sort((a, b) => b - a);
+
+        // Delete accounts
+        for(let i = 0; i < indicesToDelete.length; i++) {
+            deleteByIndex(indicesToDelete[i]);
+        }
+
+        console.log(allAccounts);
+        return;
+    }
+}
+
+/**
+ * Connect to node-managed wallets (e.g., from Hardhat node)
+ * @async
+ * @returns {Promise<void>}
+ * @example
+ * await connectWallet();
+ */
+export async function connectWallet() {
+    try {
+        const addressArr = await provider.listAccounts();
+        for (let i = 0; i < addressArr.length; i++) {
+            const accSigner = await provider.getSigner(addressArr[i].address);
+            allAccounts.push({
+                index: allAccounts.length,
+                address: addressArr[i].address,
+                type: 'node-managed', // Indicate this is managed by the node
+                signer: accSigner // Store signer reference
+            })
+            accounts.push({
+                index: allAccounts.length - 1,
+                address: addressArr[i].address,
+                type: 'node-managed', // Indicate this is managed by the node
+                signer: accSigner // Store signer reference
+            }) 
+        }
+    } catch(err) {
+        console.error(err);
+    }
+}
+
+/**
+ * Get detailed wallet information including balance and nonce
+ * @async
+ * @param {number|string|Array} accPointer - Account index, address, or array of indices
+ * @throws {Error} If input is empty or invalid
+ * @example
+ * await getWalletInfo(0); // Get info by index
+ * await getWalletInfo('0x1234...'); // Get info by address
+ * await getWalletInfo([0, 1, 2]); // Get info for multiple accounts
+ */
+export async function getWalletInfo(accPointer) {
+    try {
+        if(!accPointer && accPointer != 0) {
+            throw new Error('Error: Empty input is NOT valid!');
+        }
+
+        if(typeof accPointer === 'number') {
+            const index = allAccounts.findIndex(wallet => wallet.index == accPointer);
+            await getAccountInfo(index);
+        }
+
+        if(ethers.isAddress(accPointer)) {
+            const index = allAccounts.findIndex(wallet => wallet.address == accPointer);
+            await getAccountInfo(index);
+        }
+
+        if(Array.isArray(accPointer)) {
+            await getAccountInfo(accPointer);
+        }
+    
+    } catch(err) {
+        console.error(err);
+    }
+}

package/src/utils/accounter.js

@@ -0,0 +1,213 @@
+/**
+ * @fileoverview Account management utilities
+ * @description Internal utilities for managing account arrays, including deletion
+ * and information retrieval. Handles synchronization across multiple account arrays.
+ * @module accounter
+ */
+
+import { allAccounts, accounts, hdAccounts } from '../services/wallet.js';
+import { provider } from '../services/network.js';
+
+/**
+ * Delete account(s) by index
+ * @param {number|Array<number>|null} index - Account index, array of indices, or null to delete all
+ * @returns {void}
+ * @example
+ * deleteByIndex(0); // Delete account at index 0
+ * deleteByIndex([1, 3, 5]); // Delete multiple accounts
+ * deleteByIndex(null); // Delete all accounts
+ */
+export function deleteByIndex(index) {
+    if (Array.isArray(index)) {
+        deleteByIndexArr(index);
+    } else if (typeof index === 'number') {
+        _deleteBySingIndex(index);
+    }
+}
+
+/**
+ * Delete multiple accounts by array of indices
+ * @param {Array<number>} indices - Array of account indices to delete
+ * @returns {void}
+ * @example
+ * deleteByIndexArr([0, 2, 4]);
+ */
+export function deleteByIndexArr(indices) {
+    if (!indices || !indices.length) {
+        console.error('Error: Empty input is NOT valid!');
+        return;
+    }
+    
+    // Sort indices in descending order to avoid shifting issues
+    const sortedIndices = [...indices].sort((a, b) => b - a);
+    
+    // Delete each index from highest to lowest
+    for (const index of sortedIndices) {
+        _deleteBySingIndex(index);
+    }
+}
+
+/**
+ * Get account information including balance and nonce
+ * @async
+ * @param {number|Array<number>} index - Account index or array of indices
+ * @returns {Promise<void>}
+ * @example
+ * await getAccountInfo(0);
+ * await getAccountInfo([0, 1, 2]);
+ */
+export async function getAccountInfo(index) {
+    if (Array.isArray(index)) {
+        await _getAccArrInfo(index);
+    } else if (typeof index === 'number') {
+        await _getAccountInfo(index);
+    }
+}
+
+/**
+ * Checks if an imported wallet added before or not.
+ * @param {string|Array<string>} privKeyArr - Account private key or array of private keys
+ * @returns {Object}
+ * @example
+ * detectDupWallet('0x12cb...');
+ * detectDupWallet(['0x12cb...','0x34cd...', ...]);
+ */
+export function detectDupWallet(privKeyArr) {
+    if(typeof privKeyArr === 'string') {
+        return _findDupWalletByKey(privKeyArr);
+    }
+
+    if(Array.isArray(privKeyArr)) {
+       return  _findDupWalletByArr(privKeyArr);
+    }
+}
+
+/**
+ * Get information for multiple accounts (internal)
+ * @private
+ * @async
+ * @param {Array<number>} _indices - Array of account indices
+ * @returns {Promise<void>}
+ */
+async function _getAccArrInfo(_indices) {
+    if (!_indices || !_indices.length) {
+        console.error('Error: Empty input is NOT valid!');
+        return;
+    }
+
+    // Sort indices in descending order to avoid shifting issues
+    const sortedIndices = [..._indices].sort((a, b) => b - a);
+    
+    // Delete each index from highest to lowest
+    for (const index of sortedIndices) {
+        await _getAccountInfo(index);
+    }
+}
+
+/**
+ * Get information for a single account (internal)
+ * @private
+ * @async
+ * @param {number} _index - Account index
+ * @returns {Promise<void>}
+ */
+async function _getAccountInfo(_index) {
+    const accInfo = allAccounts[_index];
+    
+    accInfo.nonce = await provider.getTransactionCount(accInfo.address);
+    accInfo.balance = await provider.getBalance(accInfo.address);
+
+    console.log(accInfo);
+}
+
+/**
+ * Delete a single account by index (internal implementation)
+ * @private
+ * @param {number|null} _index - Account index or null to clear all
+ * @returns {void}
+ */
+function _deleteBySingIndex(_index) {
+    if (_index === null || _index === undefined) {
+        // Clear all arrays
+        allAccounts.splice(0);
+        accounts.splice(0);
+        hdAccounts.splice(0);
+        return;
+    }
+
+    // Find and remove from allAccounts
+    const accountIndex = allAccounts.findIndex(acc => acc.index === _index);
+    if (accountIndex !== -1) {
+        allAccounts.splice(accountIndex, 1);
+        
+        // Update indices in allAccounts
+        for (let i = accountIndex; i < allAccounts.length; i++) {
+            allAccounts[i].index = i;
+        }
+        
+        // Remove from accounts array if it exists there
+        const regularIndex = accounts.findIndex(acc => acc.index === _index);
+        if (regularIndex !== -1) {
+            accounts.splice(regularIndex, 1);
+            // Update indices in accounts
+            for (let i = regularIndex; i < accounts.length; i++) {
+                accounts[i].index = _index;
+                _index++;
+            }
+        }
+        
+        // Remove from hdAccounts array if it exists there
+        const hdIndex = hdAccounts.findIndex(acc => acc.index === _index);
+        if (hdIndex !== -1) {
+            hdAccounts.splice(hdIndex, 1);
+            // Update indices in hdAccounts
+            for (let i = hdIndex; i < hdAccounts.length; i++) {
+                hdAccounts[i].index = _index;
+                _index++;
+            }
+        }
+    }
+}
+
+/**
+ * Find a duplicated wallet using passed private key
+ * @private
+ * @param {string} privKey - Account private key
+ * @returns {Object}
+ */
+function _findDupWalletByKey(privKey) {
+    const foundWallet = allAccounts.find(wallet => wallet.privateKey == privKey);
+    if(foundWallet) {
+        return {
+            status: true,
+            privateKey: privKey,
+            index: foundWallet.index
+        }
+    } else {
+        return {
+            status: false
+        }
+    }
+}
+
+/**
+ * Find a duplicated wallet using passed private key array
+ * @private
+ * @param {Array<string>} privKeyArr - Account private key array
+ * @returns {Object}
+ */
+function _findDupWalletByArr(privKeyArr) {
+        for(let i = 0; i < privKeyArr.length; i++) {
+            const foundWallet = allAccounts.find(wallet => wallet.privateKey == privKeyArr[i]);
+            if(foundWallet) {
+                return {
+                    status: true,
+                    privateKey: privKeyArr[i],
+                    index: foundWallet.index
+                }
+            }
+        }
+        return {
+            status: false
+        }
+}