ethershell 0.1.0-alpha.0

package/src/utils/builder.js

@@ -0,0 +1,169 @@
+/**
+ * @fileoverview Solidity compiler builder utilities
+ * @description Handles Solidity compiler version loading, contract compilation,
+ * and artifact generation including ABIs, bytecode, and metadata.
+ * @module builder
+ */
+
+import path from 'path';
+import fs from 'fs';
+import solc from 'solc';
+import { check, findImports } from './dir.js';
+import { getCompilerOptions } from '../services/build.js';
+import { LocalStorage } from 'node-localstorage';
+
+/**
+ * Local storage instance for persisting compiler artifacts paths
+ * @type {LocalStorage}
+ */
+const localStorage = new LocalStorage('./localStorage');
+
+/**
+ * Load a specific version of the Solidity compiler
+ * @param {string} version - Solidity compiler version identifier
+ * @returns {Promise<Object>} Promise resolving to solc instance
+ * @throws {Error} If version loading fails
+ * @example
+ * loadSolcVersion('v0.8.20+commit.a1b79de6');
+ */
+export function loadSolcVersion(version){
+  return new Promise((resolve, reject) => {
+    solc.loadRemoteVersion(version, (err, solcInstance) => {
+      if (err) reject(err);
+      else resolve(solcInstance);
+    });
+  });
+}
+
+/**
+ * Set and load a specific Solidity compiler version
+ * @async
+ * @param {string} version - Solidity compiler version identifier
+ * @param {Object} solcInstance - Current solc instance
+ * @returns {Promise<Object>} New solc instance with the specified version
+ * @throws {Error} If version loading fails
+ * @example
+ * setVersion('v0.8.20+commit.a1b79de6', solcInstance);
+ */
+export async function setVersion(version, solcInstance){
+  solcInstance = await new Promise((resolve, reject) => {
+    solc.loadRemoteVersion(version, (err, solcSpecificVersion) => {
+      if (err) reject(err);
+      else resolve(solcSpecificVersion);
+    });
+  });
+  const newVersion = solcInstance.version();
+  console.log('Loaded solc version:', newVersion);
+  return solcInstance;
+}
+
+/**
+ * Build (compile) a Solidity contract and save artifacts
+ * @param {string} fullPath - Full path to the .sol file
+ * @param {Array<string>} [selectedContracts=[]] - Array of contract names to compile from the file
+ * @param {string} buildPath - Output directory for compilation artifacts
+ * @returns {void}
+ * @throws {Error} If compilation fails or produces errors
+ * @description Compiles Solidity contracts and saves artifacts in organized subdirectories:
+ * - artifacts/: Complete contract data
+ * - abis/: Contract ABIs
+ * - bytecode/: Contract bytecode
+ * - metadata/: Contract metadata
+ * @example
+ * build('./contracts/MyToken.sol', ['MyToken'], './build');
+ */
+export function build(fullPath, selectedContracts, buildPath){
+  if(!selectedContracts){
+    selectedContracts = [];
+  }
+
+  const compilerConfig = getCompilerOptions();
+  
+  // Get the directory containing the contract
+  const contractDir = path.dirname(fullPath);
+  const filename = path.basename(fullPath, '.sol');
+  const source = fs.readFileSync(fullPath, 'utf8');
+  
+  const input = {
+    language: 'Solidity',
+    sources: {
+      [`${filename}`]: {
+        content: source,
+      },
+    },
+    settings: {
+      outputSelection: {
+        '*': {
+          '*': ['*'],
+        },
+      },
+    }
+  };
+
+  // Apply global compiler configuration
+  if (compilerConfig.optimizer) {
+    input.settings.optimizer = {
+      enabled: true,
+      runs: compilerConfig.optimizerRuns
+    };
+  }
+  if (compilerConfig.viaIR) {
+    input.settings.viaIR = true;
+  }
+
+  // Compile with import callback
+  const output = JSON.parse(
+    solc.compile(
+      JSON.stringify(input),
+      { import: (importPath) => findImports(importPath, contractDir) }
+    )
+  );
+
+  if(output.errors) {
+    // Filter out warnings, only throw on actual errors
+    const errors = output.errors.filter(err => err.severity === 'error');
+    if(errors.length > 0) {
+      throw errors;
+    }
+  }
+
+  // Generate sub-paths of build
+  const artifacts = path.join(buildPath, 'artifacts');
+  const abis = path.join(buildPath, 'abis');
+  const bytecode = path.join(buildPath, 'bytecode');
+  const metadata = path.join(buildPath, 'metadata');
+  const subPaths = [
+      artifacts,
+      abis,
+      bytecode,
+      metadata
+  ];
+
+  // Ensure all sub-paths exist
+  subPaths.forEach(check);
+  const allContracts = Object.keys(output.contracts[`${filename}`]);
+  const contractsToSave = selectedContracts.length > 0 ? allContracts.filter(
+    (contractName) => {
+      return selectedContracts.includes(contractName);
+    }
+  ): allContracts;
+  contractsToSave.forEach((contractName) => {
+    const contractsData = output.contracts[`${filename}`][contractName];
+    // Save on artifacts
+    const artifactsPath = path.join(artifacts, `${contractName}.json`);
+    fs.writeFileSync(artifactsPath, JSON.stringify(contractsData, null, 2));
+    // Save on abis
+    const abisPath = path.join(abis, `${contractName}.abi.json`);
+    fs.writeFileSync(abisPath, JSON.stringify(contractsData.abi, null, 2));
+    // Save on bytecode
+    const bytecodePath = path.join(bytecode, `${contractName}.bin`);
+    fs.writeFileSync(bytecodePath, JSON.stringify(contractsData.evm.bytecode, null, 2));
+    // Save on metadata
+    const metadataPath = path.join(metadata, `${contractName}.metadata.json`);
+    fs.writeFileSync(metadataPath, JSON.stringify(contractsData.metadata, null, 2));
+    // Store abis and bytecode on local storage
+    localStorage.setItem(`${contractName}_abi`, abisPath);
+    localStorage.setItem(`${contractName}_bytecode`, bytecodePath);
+  });
+}
+

package/src/utils/contractLister.js

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Contract listing utilities
+ * @description Provides utilities to retrieve and format contract information
+ * from the contracts map, including balance information.
+ * @module contractLister
+ */
+
+import { contracts } from '../services/addContracts.js';
+
+/**
+ * Get array of all contracts with their information
+ * @async
+ * @returns {Promise<Array<Object>>} Array of contract information objects
+ * @description Retrieves all contracts from the contracts map and formats them
+ * into a simplified array with essential information including current balance
+ * @example
+ * const contractList = await getContArr();
+ * // Returns: [{ index: 0, name: 'MyToken', address: '0x...', chain: 'sepolia', ... }]
+ */
+export async function getContArr() {
+    let contractsArray = [];
+
+    for (const x of contracts.values()) {
+        let contract = {
+            index: x.index,
+            name: x.name,
+            address: x.target,
+            chain: x.chain,
+            chainId: x.chainId,
+            deployType: x.deployType,
+            balance: await x.provider.getBalance(x.target)
+        }
+        contractsArray.push(contract);
+    }
+
+    return contractsArray;
+}

package/src/utils/dir.js

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview Directory and file utilities for Solidity projects
+ * @description Provides utilities for directory management, collecting Solidity files,
+ * and resolving contract imports during compilation.
+ * @module dir
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Check if directory exists and create it if it doesn't
+ * @param {string} dir - Directory path to check/create
+ * @returns {void}
+ * @example
+ * check('./build/artifacts');
+ */
+export function check(dir){
+    if(!fs.existsSync(dir)){
+      fs.mkdirSync(dir, {recursive: true});
+    }
+}
+
+/**
+ * Recursively collect all Solidity files from a directory
+ * @param {string} dirPath - Root directory to search for .sol files
+ * @returns {Array<string>} Array of absolute paths to .sol files
+ * @example
+ * const solFiles = collectSolFiles('./contracts');
+ * // Returns: ['./contracts/Token.sol', './contracts/utils/SafeMath.sol']
+ */
+export function collectSolFiles(dirPath) {
+  let solFiles = [];
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  
+  for(const entry of entries) {
+    const entryPath = path.join(dirPath, entry.name);
+    
+    if(entry.isDirectory()) {
+      // Recursively collect from subdirectories
+      solFiles = solFiles.concat(collectSolFiles(entryPath));
+    } else if(entry.isFile() && path.extname(entry.name) === '.sol') {
+      solFiles.push(entryPath);
+    }
+  }
+  return solFiles;
+}
+
+/**
+ * Resolve Solidity import paths for the compiler
+ * @param {string} importPath - Import path from Solidity import statement
+ * @param {string} basePath - Base directory of the importing file
+ * @returns {Object} Object with 'contents' property containing file content or 'error' property
+ * @example
+ * const result = findImports('./Token.sol', './contracts');
+ * // Returns: { contents: "pragma solidity ^0.8.0;..." } or { error: "File not found" }
+ */
+export function findImports(importPath, basePath) {
+  try {
+    // Resolve relative to the current file's directory
+    const resolvedPath = path.resolve(basePath, importPath);
+    
+    if (fs.existsSync(resolvedPath)) {
+      const content = fs.readFileSync(resolvedPath, 'utf8');
+      return { contents: content };
+    }
+    
+    // If not found, try relative to contracts root
+    const contractsRoot = path.resolve('.', 'contracts');
+    const rootPath = path.resolve(contractsRoot, importPath);
+    
+    if (fs.existsSync(rootPath)) {
+      const content = fs.readFileSync(rootPath, 'utf8');
+      return { contents: content };
+    }
+    
+    return { error: 'File not found' };
+  } catch (e) {
+      return { error: e.message };
+  }
+}

package/src/utils/replHelper.js

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Custom REPL evaluation utilities
+ * @description Provides custom async evaluation function for the Node.js REPL,
+ * enabling await syntax in the interactive shell without async wrapper functions.
+ * @module replHelper
+ */
+
+import vm from 'vm';
+
+/**
+ * Custom async evaluation function for REPL
+ * @async
+ * @param {string} cmd - Command to evaluate
+ * @param {Object} context - REPL context object
+ * @param {string} filename - Filename for error reporting
+ * @param {Function} callback - Callback function(err, result)
+ * @returns {Promise<void>}
+ * @description Evaluates commands in REPL context and automatically awaits Promise results
+ * @example
+ * // Used internally by REPL to enable top-level await
+ * customEval('await provider.getBlockNumber()', context, 'repl', callback);
+ */
+export async function customEval(cmd, context, filename, callback) {
+  try {
+    // Use vm to evaluate the command
+    const script = new vm.Script(cmd, {
+      filename: filename,
+      displayErrors: false
+    });
+    
+    let result = script.runInContext(context, {
+      displayErrors: false,
+      breakOnSigint: true
+    });
+    
+    // If result is a Promise, await it
+    if (result && typeof result.then === 'function') {
+      result = await result;
+    }
+    
+    callback(null, result);
+  } catch (err) {
+    callback(err);
+  }
+}