Ethjs Ethereum Utility Library

Common errors

• Error: Cannot find module 'ethjs' imported from ...

  cause Attempting to import `ethjs` using ES module `import` syntax in an environment where only CommonJS `require` is supported, or when `ethjs` is not correctly installed.
  fix Change your import statement to `const Eth = require('ethjs');`. Ensure `ethjs` is listed in your `package.json` dependencies and installed (`npm install ethjs`).

• TypeError: Eth.toWei is not a function

  cause Incorrectly destructuring or accessing static methods, or calling a method on an instance when it should be called statically.
  fix Ensure `Eth` is imported as the main module (`const Eth = require('ethjs');`) and static methods like `toWei` are called directly on `Eth` (e.g., `Eth.toWei(value, unit)`). Do not attempt `const { toWei } = require('ethjs');`.

Warnings

• breaking The `ethjs` library is effectively unmaintained since its last release (v0.4.0) in 2018. It is strongly recommended to use actively maintained alternatives like `ethers.js` or packages from the `@ethereumjs` monorepo for any new development or migration of existing projects.
  Fix: Migrate your project to a modern, actively maintained Ethereum library such as `ethers.js` (e.g., `npm install ethers`) or specific `@ethereumjs` packages (e.g., `npm install @ethereumjs/tx`).
• gotcha Ethjs relies on the `BN.js` library for handling large numbers. Modern JavaScript environments and newer Ethereum libraries have largely transitioned to native `BigInt` for arbitrary-precision integers. Mixing `BN.js` objects with `BigInt` or standard JavaScript numbers can lead to unexpected behavior and errors.
  Fix: If continuing to use `ethjs`, explicitly manage conversions between `BN.js` objects and other number types. For new projects, switch to libraries that support `BigInt` natively to avoid this impedance mismatch.
• gotcha Ethjs is a CommonJS-only library, meaning it can only be imported using `require()` syntax in Node.js environments. It does not provide native ES module (ESM) support (`import`). Attempting to use `import` statements will result in module resolution errors.
  Fix: Ensure your project uses `require('ethjs')` for importing. If you need ESM compatibility, you must use a transpiler like Babel or switch to a modern Ethereum library that offers hybrid CJS/ESM builds.
• gotcha Ethjs employs a mixed asynchronous API, with some methods (like `getBlockByNumber`) using Node.js-style callbacks, while others (like contract calls) return Promises. This inconsistency can make error handling and control flow more complex.
  Fix: Standardize your async patterns. For callback-based functions, consider wrapping them in Promises (e.g., using `util.promisify`) to maintain a consistent promise-based workflow throughout your application.

Install

• npm install ethjs npm
• yarn add ethjs yarn
• pnpm add ethjs pnpm

Imports

• Eth
  wrong:

  import Eth from 'ethjs';

  correct:

  const Eth = require('ethjs');

  Ethjs is a CommonJS-only library, last published in 2018. ESM `import` statements are not supported directly.
• Eth.HttpProvider
  wrong:

  import { HttpProvider } from 'ethjs'; const provider = new HttpProvider(...);

  correct:

  const Eth = require('ethjs'); const provider = new Eth.HttpProvider('https://mainnet.infura.io');

  `HttpProvider` is a static property of the main `Eth` export. Destructuring from the package is not supported.
• Eth.toWei
  wrong:

  import { toWei } from 'ethjs'; const weiValue = toWei(...);

  correct:

  const Eth = require('ethjs'); const weiValue = Eth.toWei(1, 'ether');

  Utility functions like `toWei` are static methods on the main `Eth` export and cannot be imported directly via ES modules syntax.

Quickstart

This quickstart demonstrates initializing Ethjs with an HTTP provider, fetching blockchain data using a callback, converting units with a static utility, and interacting with a basic ERC-20 contract using a promise-based API.

const Eth = require('ethjs');
const eth = new Eth(new Eth.HttpProvider('https://ropsten.infura.io'));

// Fetch a block by number using a callback (common in older Node.js libs)
eth.getBlockByNumber(45300, true, (err, block) => {
  if (err) {
    console.error('Error fetching block:', err);
    return;
  }
  console.log('Block 45300 data:', block.number.toString(), block.hash);
});

// Convert ether to wei using Eth.toWei utility
const etherValue = Eth.toWei(72, 'ether');
console.log('72 Ether in Wei (BN.js object):', etherValue.toString());

// Interact with a contract using a promise-based API
const tokenABI = [{
  "constant": true,
  "inputs": [],
  "name": "totalSupply",
  "outputs":[{"name": "","type": "uint256"}],
  "payable": false,
  "type": "function"
}];

// This contract address is an example and may not be valid on Ropsten today
const tokenAddress = '0x6e0E0e02377Bc1d90E8a7c21f12BA385C2C35f78';
const token = eth.contract(tokenABI).at(tokenAddress);

token.totalSupply()
  .then((totalSupply) => {
    console.log(`Total supply for token at ${tokenAddress}: ${totalSupply.toString()}`);
  })
  .catch(error => {
    console.error(`Error fetching total supply for token at ${tokenAddress}:`, error);
  });