EthereumJS Utilities

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` syntax in an ES module context or with an ES module library.
  fix Change `const { Name } = require('ethereumjs-util')` to `import { Name } from 'ethereumjs-util'`. Ensure your project's `package.json` has `"type": "module"` or that files using `import` have a `.mjs` extension.

• TypeError: Invalid hex string (0x<length 0>)

  cause Providing an empty string or incorrectly formatted string where a hex-prefixed hex string is expected by a utility function (e.g., `toBuffer`, `bufferToHex`).
  fix Ensure that hex string inputs are properly formatted, typically with a '0x' prefix and valid hexadecimal characters. If an empty value is intended, pass an empty Buffer or Uint8Array instead of an empty string for byte-related functions.

• Error: Invalid checksum address

  cause The provided Ethereum address does not pass the EIP-55 checksum validation.
  fix Double-check the Ethereum address for typos or incorrect casing. Ensure it matches the EIP-55 checksum standard. If you intend to work with non-checksummed addresses, use functions that do not perform checksum validation or convert to lowercase before validation if appropriate for your use case.

Warnings

• breaking Starting with version 7.0.0, `ethereumjs-util` is an ESM-only package. Direct `require()` statements will result in runtime errors. Projects must use ES module syntax (`import`) and configure their build tools accordingly.
  Fix: Migrate your codebase to use ES module `import` syntax. For Node.js, ensure your package.json specifies `"type": "module"` or use a `.mjs` extension for files importing this package.
• breaking Node.js 18 support has been deprecated across the EthereumJS monorepo, including `@ethereumjs/util`. The minimum required Node.js version is now 20.
  Fix: Upgrade your Node.js environment to version 20 or higher to maintain compatibility and receive updates.
• deprecated The `createBinaryObject` helper function within the `object` module (src/object.ts) has been marked as deprecated.
  Fix: Review your usage of `createBinaryObject` and replace it with alternative, actively supported methods for binary object creation or manipulation. The documentation in the `src/object.ts` file or API docs might provide alternatives.
• gotcha Functions originally from the `ethjs-util` package have been internalized into `ethereumjs-util` since v7.1.3. While their API remains largely the same, this internalization means that subtle behavioral changes or future deprecations might occur independently of the original `ethjs-util` library.
  Fix: Continue importing these functions (e.g., `stripHexPrefix`) directly from `ethereumjs-util`. Be aware that their underlying implementation is now managed by EthereumJS.
• breaking Recent updates in version 10.1.1 include dependency bumps for `@noble/curves` and `@noble/hashes` to v2. While these are indirect dependencies for most users, direct interaction with these libraries or reliance on their previous versions' specific behaviors could lead to breaking changes.
  Fix: If your project directly or indirectly relies on specific versions or behaviors of `@noble/curves` or `@noble/hashes`, review their v2 changelogs for potential breaking changes and update your code accordingly.

Install

• npm install ethereumjs-util npm
• yarn add ethereumjs-util yarn
• pnpm add ethereumjs-util pnpm

Imports

• isValidChecksumAddress
  wrong:

  const { isValidChecksumAddress } = require('ethereumjs-util')

  correct:

  import { isValidChecksumAddress } from 'ethereumjs-util'

  Since v7, this package is ESM-only. CommonJS 'require' syntax will not work.
• BN
  wrong:

  import BN from 'bn.js'

  correct:

  import { BN } from 'ethereumjs-util'

  BN.js is re-exported directly from ethereumjs-util for convenience. It is not the default export of BN.js itself.
• stripHexPrefix
  wrong:

  import { stripHexPrefix } from 'ethjs-util'

  correct:

  import { stripHexPrefix } from 'ethereumjs-util'

  Functionality from ethjs-util has been internalized since v7.1.3; import directly from 'ethereumjs-util'.
• rlp

  import { rlp } from 'ethereumjs-util'

  The rlp library is re-exported by ethereumjs-util for direct access.

Quickstart

This quickstart demonstrates basic usage, including Ethereum checksum address validation, byte buffer manipulation, and arbitrary-precision arithmetic using the re-exported BN.js library.

import assert from 'assert';
import { isValidChecksumAddress, unpadBuffer, BN } from 'ethereumjs-util';

// Example 1: Validate an Ethereum checksum address
const address = '0x2F015C60E0be116B1f0CD534704Db9c92118FB6A';
const isValid = isValidChecksumAddress(address);
console.log(`Address ${address} is valid: ${isValid}`);
assert.ok(isValid, 'Checksum address validation failed');

// Example 2: Unpad a Buffer
const paddedBuffer = Buffer.from('000000006600', 'hex');
const unpaddedBuffer = unpadBuffer(paddedBuffer);
console.log(`Unpadded buffer: ${unpaddedBuffer.toString('hex')}`);
assert.ok(unpaddedBuffer.equals(Buffer.from('6600', 'hex')), 'Buffer unpadding failed');

// Example 3: Perform arithmetic with BN.js
const bn1 = new BN('dead', 16); // Hexadecimal 'dead'
const bn2 = new BN('101010', 2); // Binary '101010'
const sum = bn1.add(bn2);
const expectedValue = new BN(57047); // Decimal equivalent of 'dead' (57005) + '101010' (42) = 57047
console.log(`BN sum: ${sum.toString()}`);
assert.ok(sum.eqn(expectedValue), 'BN arithmetic failed');

console.log('All quickstart assertions passed!');