ethershell 0.1.0-alpha.0

package/bin/cli.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview EtherShell - Interactive CLI for Ethereum smart contract development
+ * @description Main entry point for the EtherShell REPL environment that provides
+ * an interactive command-line interface for compiling, deploying, and managing
+ * Ethereum smart contracts and wallets.
+ * @module cli
+ */
+
+import repl from 'repl';
+import util from 'util';
+import { customEval } from '../src/utils/replHelper.js';
+import { 
+    updateCompiler,
+    currentCompiler,
+    compilerOptions,
+    getCompilerOptions,
+    compile
+} from '../src/services/build.js';
+import { set, get, getDefault } from '../src/services/network.js';
+import { deleteDirectory } from '../src/services/files.js';
+import {
+    addAccounts,
+    getAccounts,
+    createAccounts,
+    deleteAccount,
+    createHD,
+    getHDAccounts,
+    addHD,
+    getAllAccounts,
+    connectWallet,
+    getWalletInfo
+    } from '../src/services/wallet.js';
+
+import { deploy, add } from '../src/services/addContracts.js';
+import { getContracts } from '../src/services/contracts.js';
+
+/**
+ * REPL instance for EtherShell interactive environment
+ * @type {repl.REPLServer}
+ * @description Creates and configures the REPL server with custom evaluation
+ * and output formatting
+ */
+export const r = repl.start({
+    prompt: 'EtherShell> ',
+    ignoreUndefined: true,
+    eval: customEval,
+    writer: output => {
+        return util.inspect(output, { colors: true, depth: null });
+    }
+});
+
+// Network commands
+r.context.chain = set;
+r.context.chain = get;
+r.context.defaultChain = getDefault;
+
+// Compile commands
+r.context.compiler = currentCompiler;
+r.context.compUpdate = updateCompiler;
+r.context.compInfo = getCompilerOptions;
+r.context.compOpts = compilerOptions;
+r.context.build = compile;
+
+// Clean build folder
+r.context.clean = deleteDirectory;
+
+// Set wallet
+r.context.addWallet = addAccounts;
+r.context.addHDWallet = addHD;
+r.context.newWallet = createAccounts;
+r.context.newHDWallet = createHD;
+r.context.removeWallet = deleteAccount;
+r.context.connectWallet = connectWallet;
+
+// View wallets
+r.context.wallets = getAccounts;
+r.context.allWallets = getAllAccounts;
+r.context.hdWallets = getHDAccounts;
+r.context.walletInfo = getWalletInfo
+
+// Add contract
+r.context.deploy = deploy;
+r.context.addContract = add;
+
+// Contract
+r.context.contracts = getContracts;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "ethershell",
+  "version": "0.1.0-alpha.0",
+  "description": "Interactive JavaScript console for Ethereum smart contract management",
+  "author": "Alireza Kiakojouri (alirezaethdev@gmail.com)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AlirezaEthDev/EtherShell"
+  },
+  "bugs": {
+    "url": "https://github.com/AlirezaEthDev/EtherShell/issues"
+  },
+  "homepage": "https://github.com/AlirezaEthDev/EtherShell",
+  "type": "module",
+  "bin": {
+    "ethershell": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js",
+    "dev": "nodemon bin/cli.js",
+    "test": "echo \"No tests yet\" && exit 0",
+    "lint": "echo \"No linting configured\" && exit 0",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "ethereum",
+    "cli",
+    "smart-contracts",
+    "solidity",
+    "blockchain"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0",
+    "ethers": "^6.13.0",
+    "node-localstorage": "^3.0.5",
+    "solc": "^0.8.29",
+    "vm": "^0.1.0"
+  },
+  "preferGlobal": true,
+  "files": [
+    "bin/",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ]
+}

package/src/services/addContracts.js

@@ -0,0 +1,221 @@
+/**
+ * @fileoverview Smart contract deployment and management
+ * @description Provides functions to deploy new smart contracts and add existing
+ * contracts to the EtherShell environment. Manages contract instances and integrates
+ * them with the REPL context.
+ * @module addContracts
+ */
+
+import { ethers } from 'ethers';
+import fs from 'fs';
+import { provider } from './network.js';
+import { allAccounts, accounts, hdAccounts } from './wallet.js';
+import { LocalStorage } from 'node-localstorage';
+import { r } from '../../bin/cli.js';
+
+/**
+ * Local storage instance for persisting contract metadata
+ * @type {LocalStorage}
+ */
+const localStorage = new LocalStorage('./localStorage');
+
+/**
+ * Map of all deployed and added contracts
+ * @type {Map<string, ethers.Contract>}
+ */
+export const contracts = new Map();
+
+/**
+ * Deploy a new smart contract to the blockchain
+ * @async
+ * @param {string} contractName - Name of the contract to deploy
+ * @param {Array} [args=[]] - Constructor arguments for the contract
+ * @param {number} [accIndex=0] - Index of the account to deploy from
+ * @param {string} [chain] - Optional custom chain URL
+ * @param {string} [abiLoc] - Optional custom ABI file location
+ * @param {string} [bytecodeLoc] - Optional custom bytecode file location
+ * @returns {Promise<void>}
+ * @throws {Error} If contract name is empty, account index is out of range, or deployment fails
+ * @example
+ * deploy('MyToken', [1000000], 0);
+ */
+export async function deploy(contractName, args, accIndex, chain, abiLoc, bytecodeLoc) {
+    try {
+        let currentProvider;
+        let connectedChain;
+
+        if(!contractName) {
+            throw new Error('Contract name is empty');
+        }
+
+        const contractArgs = args || [];
+
+        if(accIndex > allAccounts.length - 1) {
+            throw new Error('Wallet index is out of range');
+        }
+
+        if(!accIndex) {
+            accIndex = 0;
+        }
+
+        if(chain) {
+            currentProvider = new ethers.JsonRpcProvider(chain);
+        } else {
+            currentProvider = provider;
+        }
+
+        let wallet = new ethers.Wallet(allAccounts[accIndex].privateKey, currentProvider);
+        connectedChain = await currentProvider.getNetwork();
+
+        const abiPath = abiLoc || localStorage.getItem(`${contractName}_abi`);
+        const bytecodePath = bytecodeLoc || localStorage.getItem(`${contractName}_bytecode`);
+
+        const abi  = JSON.parse(fs.readFileSync(abiPath, 'utf8'));
+        const bytecode = JSON.parse(fs.readFileSync(bytecodePath, 'utf8'));
+
+        const factory = new ethers.ContractFactory(abi, bytecode, wallet);
+        const deployTx = await factory.deploy(...contractArgs);
+        await deployTx.waitForDeployment();
+
+        // Update deployer contract list
+        const contSpec = {
+            address: deployTx.target,
+            deployedOn: connectedChain.name,
+            chainId: connectedChain.chainId
+        }
+
+        allAccounts[accIndex].contracts.push(contSpec);
+        
+        const accountsIndex = accounts.findIndex(wallet => wallet.index == accIndex);
+        if(accountsIndex >= 0) {
+            accounts[accountsIndex].contracts.push(contSpec);
+        }
+
+        const hdIndex = hdAccounts.findIndex(wallet => wallet.index == accIndex);
+        if(hdIndex >= 0) {
+            hdAccounts[hdIndex].contracts.push(contSpec);
+        }
+
+        // Extend contract object
+        deployTx.index = Array.from(contracts.values()).length;
+        deployTx.name = contractName;
+        deployTx.chain = connectedChain.name;
+        deployTx.chainId = connectedChain.chainId;
+        deployTx.deployType = 'ethershell-deployed',
+        deployTx.provider = currentProvider;
+
+        // Add to contract list
+        contracts.set(contractName, deployTx);
+
+        // Add to REPL context
+        r.context[contractName] = deployTx;
+
+        const deployHash = deployTx.deploymentTransaction().hash;
+        const tx = await provider.getTransaction(deployHash);
+        delete tx.data;
+
+        // Extend transaction object
+        tx.ethershellIndex = deployTx.index;
+        tx.address = deployTx.target;
+        tx.name = deployTx.name;
+        tx.chain = deployTx.chain;
+        tx.deployType = deployTx.deployType;
+        
+        console.log(tx);
+    } catch(err) {
+        console.error(err);
+    }
+}
+
+/**
+ * Add an existing deployed contract to EtherShell
+ * @async
+ * @param {string} contractName - Name to assign to the contract
+ * @param {string} contractAddr - Address of the deployed contract
+ * @param {number} [accIndex=0] - Index of the account to interact with the contract
+ * @param {string} abiLoc - Path to the contract ABI file
+ * @param {string} [chain] - Optional custom chain URL
+ * @returns {Promise<void>}
+ * @throws {Error} If contract address or ABI location is null/undefined
+ * @example
+ * add('USDT', '0xdac17f958d2ee523a2206206994597c13d831ec7', 0, './abis/USDT.json');
+ */
+export async function add(contractName, contractAddr, accIndex, abiLoc, chain) {
+    try {
+        let currentProvider;
+        let connectedChain;
+
+        if(!contractAddr) {
+            throw new Error('Contract address may not be null or undefined!');
+        }
+
+        if(!accIndex) {
+            accIndex = 0;
+        }
+
+        if(chain) {
+            currentProvider = new ethers.JsonRpcProvider(chain);
+        } else {
+            currentProvider = provider;
+        }
+
+        let wallet = new ethers.Wallet(allAccounts[accIndex].privateKey, currentProvider);
+        connectedChain = await currentProvider.getNetwork();
+
+        if(!abiLoc) {
+            throw new Error('ABI path may not be null or undefined!');
+        }
+
+        const abi  = JSON.parse(fs.readFileSync(abiLoc, 'utf8'));
+
+        const newContract = new ethers.Contract(contractAddr, abi, wallet);
+
+        // Update deployer contract list
+        const contSpec = {
+            address: newContract.target,
+            deployedOn: connectedChain.name,
+            chainId: connectedChain.chainId
+        }
+
+        allAccounts[accIndex].contracts.push(contSpec);
+        
+        const accountsIndex = accounts.findIndex(wallet => wallet.index == accIndex);
+        if(accountsIndex >= 0) {
+            accounts[accountsIndex].contracts.push(contSpec);
+        }
+
+        const hdIndex = hdAccounts.findIndex(wallet => wallet.index == accIndex);
+        if(hdIndex >= 0) {
+            hdAccounts[hdIndex].contracts.push(contSpec);
+        }
+
+        // Extend contract object
+        newContract.index = Array.from(contracts.values()).length;
+        newContract.name = contractName;
+        newContract.chain = connectedChain.name;
+        newContract.chainId = connectedChain.chainId;
+        newContract.deployType = 'pre-deployed',
+        newContract.provider = currentProvider;
+
+        // Add to contract list
+        contracts.set(contractName, newContract);
+
+        // Add to REPL context
+        r.context[contractName] = newContract;
+
+        // Add result
+        const result = {
+            index: newContract.index,
+            name: newContract.name,
+            address: newContract.target,
+            chain: newContract.chain,
+            chainId: newContract.chainId,
+            deployType: newContract.deployType,
+            provider: newContract.provider
+        }
+
+        console.log(result);
+    } catch(err) {
+        console.error(err);
+    }
+}

package/src/services/build.js

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview Solidity compiler management and contract compilation
+ * @description Manages Solidity compiler versions, compilation settings, and
+ * provides functions to compile smart contracts with customizable options.
+ * @module build
+ */
+
+import path from 'path';
+import solc from 'solc';
+import { check, collectSolFiles } from '../utils/dir.js';
+import { setVersion, build } from '../utils/builder.js';
+
+/**
+ * Current Solidity compiler instance
+ * @type {Object}
+ */
+let currentSolcInstance = solc; // default local compiler
+
+/**
+ * Global compiler configuration state
+ * @type {Object}
+ * @property {boolean} optimizer - Whether gas optimizer is enabled
+ * @property {number} optimizerRuns - Number of optimizer runs
+ * @property {boolean} viaIR - Whether to use IR-based code generation
+ */
+let compilerConfig = {
+  optimizer: false,
+  optimizerRuns: 200,
+  viaIR: false
+};
+
+/**
+ * Update the Solidity compiler to a specific version
+ * @async
+ * @param {string} version - Solidity version (e.g., 'v0.8.20+commit.a1b79de6')
+ * @returns {Promise<void>}
+ * @throws {Error} If the specified version cannot be loaded
+ * @example
+ * await updateCompiler('v0.8.20+commit.a1b79de6');
+ */
+export async function updateCompiler(version){
+  try{
+    currentSolcInstance = await setVersion(version, currentSolcInstance);
+  } catch(err) {
+    console.error(err);
+  }
+}
+
+/**
+ * Get the current compiler version
+ * @returns {string} Current Solidity compiler version string
+ * @example
+ * const version = currentCompiler(); // Returns: "0.8.20+commit.a1b79de6.Emscripten.clang"
+ */
+export function currentCompiler(){
+  return currentSolcInstance.version();
+}
+
+/**
+ * Configure compiler optimization options
+ * @param {boolean} gasOptimizer - Enable or disable gas optimization
+ * @param {boolean} viaIR - Enable or disable IR-based code generation
+ * @param {number} [optimizerRuns=200] - Number of times the optimizer should run
+ * @returns {Object|null} Updated compiler configuration or null on error
+ * @throws {Error} If parameters are invalid
+ * @example
+ * compilerOptions(true, false, 1000);
+ */
+export function compilerOptions(gasOptimizer, viaIR, optimizerRuns = 200) {
+  try {
+    // Validate input parameters
+    if (typeof gasOptimizer !== 'boolean') {
+        throw new Error('Gas optimizer parameter must be a boolean');
+    }
+    if (typeof viaIR !== 'boolean') {
+        throw new Error('ViaIR parameter must be a boolean');
+    }
+    if (typeof optimizerRuns !== 'number' || optimizerRuns < 1) {
+        throw new Error('Optimizer runs must be a positive number');
+    }
+
+    // Update global configuration
+    compilerConfig.optimizer = gasOptimizer;
+    compilerConfig.viaIR = viaIR;
+    compilerConfig.optimizerRuns = optimizerRuns;
+
+    // Provide user feedback
+    console.log('✓ Compiler options updated:');
+    console.log(`  Gas Optimizer: ${compilerConfig.optimizer ? 'Enabled' : 'Disabled'}`);
+    if (compilerConfig.optimizer) {
+        console.log(`  Optimizer Runs: ${compilerConfig.optimizerRuns}`);
+    }
+    console.log(`  ViaIR: ${compilerConfig.viaIR ? 'Enabled' : 'Disabled'}`);
+    
+    return compilerConfig;
+  } catch (error) {
+      console.error('Error setting compiler options:', error.message);
+      return null;
+  }
+}
+
+/**
+ * Get current compiler options
+ * @returns {Object} Copy of current compiler configuration
+ * @example
+ * const opts = getCompilerOptions();
+ */
+export function getCompilerOptions() {
+  return { ...compilerConfig };
+}
+
+/**
+ * Compile Solidity smart contract(s)
+ * @param {string} [fullPath] - Path to contract file or directory. Defaults to './contracts'
+ * @param {Array<string>} [selectedContracts] - Array of specific contract names to compile
+ * @param {string} [buildPath] - Output directory for compiled artifacts. Defaults to './build'
+ * @returns {void}
+ * @throws {Error} If no contracts found or compilation fails
+ * @example
+ * compile(); // Compile all contracts in './contracts'
+ * compile('./contracts/MyToken.sol'); // Compile specific file
+ * compile('./contracts', ['MyToken'], './output'); // Compile specific contracts to custom path
+ */
+export function compile(fullPath, selectedContracts, buildPath){
+  try{
+    // Set default path if buildPath is undefined
+    if(!buildPath){
+      buildPath = path.resolve('.', 'build');
+      [buildPath].forEach(check);
+    }
+
+    let fileExt;
+    if(!fullPath) {
+      fullPath = path.resolve('.', 'contracts');
+    } else {
+      fileExt = path.extname(fullPath);
+    }
+
+    if(!fileExt){
+      const solFiles = collectSolFiles(fullPath);
+      
+      if(!solFiles.length){
+        throw 'There is no smart contract in the directory!';
+      } else {
+        for(let i = 0; i < solFiles.length; i++){
+          build(solFiles[i], selectedContracts, buildPath);
+        }
+        console.log(`Contracts compiled into ${path.resolve(buildPath)}`);
+      }
+    } else {
+      build(fullPath, selectedContracts, buildPath);
+      console.log(`Contract compiled into ${path.resolve(buildPath)}`);
+    }
+  } catch(err){
+      console.error(err);
+  }
+}

package/src/services/contracts.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Contract retrieval and management
+ * @description Provides functions to retrieve contract information from the
+ * contract registry by various identifiers (index, address, or name).
+ * @module contracts
+ */
+
+import { ethers } from 'ethers';
+import { getContArr } from '../utils/contractLister.js';
+
+/**
+ * Get contract(s) information
+ * @async
+ * @param {number|string|null} [contPointer] - Contract identifier (index, address, or name).
+ *                                              If omitted, returns all contracts.
+ * @returns {Promise<void>}
+ * @throws {Error} If the input is not valid
+ * @example
+ * await getContracts(); // Get all contracts
+ * await getContracts(0); // Get contract by index
+ * await getContracts('0x1234...'); // Get contract by address
+ * await getContracts('MyToken'); // Get contract by name
+ */
+export async function getContracts(contPointer) {
+    const contArray = await getContArr();
+    let result;
+
+    if(!contPointer && contPointer != 0) {
+        result = contArray;
+    } else if(typeof contPointer === 'number') {
+        result = contArray[contPointer];
+    } else if(ethers.isAddress(contPointer)) {
+        const index = contArray.findIndex(contract => contract.address == contPointer);
+        result = contArray[index];
+    } else if(typeof contPointer === 'string') {
+        const index = contArray.findIndex(contract => contract.name == contPointer);
+        result = contArray[index];
+    } else {
+        throw new Error('Input is NOT valid!');
+    }
+
+    console.log(result);
+}

package/src/services/files.js

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview File system utilities for directory management
+ * @description Provides utilities for deleting directories recursively,
+ * primarily used for cleaning build directories.
+ * @module files
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Delete a directory recursively
+ * @param {string} [dirPath] - Path to the directory to delete. Defaults to './build'
+ * @returns {void}
+ * @example
+ * deleteDirectory('../build');
+ * deleteDirectory(); // Deletes default './build' directory
+ */
+export function deleteDirectory(dirPath){
+  try {
+    if(!dirPath){    
+      dirPath = path.resolve('..', 'build');
+    }
+    // Check if the directory exists
+    if(!fs.existsSync(dirPath)){
+      console.log('Path is not a directory');
+      return;    }
+
+    // For Node.js 14.14.0+ (recommended)
+    fs.rmSync(dirPath, { recursive: true, force: true });
+
+    console.log('Directory deleted successfully');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      console.log('Directory does not exist');
+    } else {
+      console.error('Error deleting directory:', err);
+    }
+  }
+}