Why you should replace Ethers.js and web3

Bundle Size Comparison (ESM, minified)

Measured with esbuild. Smaller is better.

| What you import | [email protected] | [email protected] | [email protected] | [email protected] | [email protected] | | ---------------------------------------- | :-----------------: | :-----------: | :---------: | :---------: | :------------: | | Full library | 43.1 kB 🏆 | 394.0 kB | 348.3 kB | 495.8 kB | 612.8 kB | | Provider (getBalance, getBlock, etc) | 30.8 kB | 260.0 kB | 269.5 kB | 454.5 kB | 10.9 kB 🏆 | | Contract (read-only calls) | 24.8 kB 🏆 | 86.6 kB | 179.8 kB | 264.9 kB | 49.9 kB | | Conversions (wei, gwei, ether) | 1.2 kB 🏆 | 10.4 kB | 2.7 kB | 454.5 kB | 3.7 kB |

essential-eth is 8x smaller than the nearest alternative for full-library usage.

• 🐜️ tiny
• 🔐 Strongly written TypeScript
• 🧪 Matches both ethers and web3
  • ⚡️ Near-identical API to ethers
  • ⚡️ Similar but improved API to web3
• 🙌 Works for all EVM chains
  • 💎 Ethereum
  • 🟣 Polygon
  • 🔴 Optimism
  • 🔵 Arbitrum
  • Many more
• 🧪 Strongly tested
• 🌲 Tree-shaking and no side-effects
• 🙌 All common JS versions (CommonJS, ESM, & UMD)
  • ✅ Node 24, 22, 20, & 18
  • ✅ Web

Who Is This For?

Essential-eth is built for developers where size and speed matter. Check out dedicated guides for your use case:

• Chrome Extension Developers — Service worker size budgets are brutal. 39.9 kB vs ethers' 394 kB makes a real difference.
• Serverless & Edge Functions — Cold starts cost money. Get sub-10ms startup instead of 200ms+.
• React Native Apps — Every KB impacts app store download times. Essential-eth adds 12 kB, ethers adds 104 kB.
• Telegram/Discord Bots — Minimal memory footprint, instant response times. 2 MB vs 45 MB for ethers.

Table of Contents

• Why you should replace Ethers.js and web3
  • Bundle Size Comparison (ESM, minified)
• Who Is This For?
• Install
• 🛠 Utils
  • arrayify
  • computeAddress
  • computePublicKey
  • concat
  • decodeBytes32String
  • decodeEventLog
  • decodeFunctionResult
  • encodeBytes32String
  • encodeFunctionData
  • etherToGwei
  • etherToWei
  • formatUnits
  • getAddress
  • getEventSignature
  • getEventTopic
  • gweiToEther
  • hashMessage
  • hexConcat
  • hexDataLength
  • hexDataSlice
  • hexStripZeros
  • hexValue
  • hexZeroPad
  • hexlify
  • id
  • isAddress
  • isBytes
  • isBytesLike
  • isHexString
  • jsonRpcProvider
  • keccak256
  • namehash
  • pack
  • parseUnits
  • solidityKeccak256
  • splitSignature
  • stripZeros
  • toChecksumAddress
  • toUtf8Bytes
  • toUtf8String
  • weiToEther
  • zeroPad
• Providers
  • call
  • estimateGas
  • getBalance
  • getBlock
  • getBlockNumber
  • getCode
  • getFeeData
  • getGasPrice
  • getLogs
  • getNetwork
  • getTransaction
  • getTransactionCount
  • getTransactionReceipt
  • resolveName
• Contract
  • contractFunctionName(args)
• More Info
  • Identical vs Similar vs Dissimilar {#isd}
  • Miscellaneous
• Contributing and GitPOAP

Install

npm install --save essential-eth # TypeScript included

# or yarn
yarn add essential-eth # TypeScript included

Browsers:

<!-- index.html -->
<script src="https://unpkg.com/[email protected]"></script>

🛠 Utils

import { etherToWei } from 'essential-eth';

// or in a non-import environment
const { etherToWei } = require('essential-eth');

arrayify

arrayify(value: number | bigint | BytesLike | Hexable, options: DataOptions): Uint8Array

import { arrayify } from 'essential-eth';

arrayify(1);
// Uint8Array(1) [ 1 ]

arrayify(0x1234);
// Uint8Array(2) [ 18, 52 ]

arrayify('0x1', { hexPad: 'right' });
// Uint8Array(1) [ 16 ]

computeAddress

computeAddress(key: string): string

import { computeAddress } from 'essential-eth';

computeAddress('0x0458eb591f407aef12936bd2989ca699cf5061de9c4964dd6eb6005fd8f580c407434447e813969a1be6e9954b002cad84dfc67a69e032b273e4695e7d0db2d952'); // public key
// '0xA2902059a7BF992f1450BACD7357CCAa5cC8336a'

computeAddress('0x2f2c419acf4a1da8c1ebea75bb3fcfbd3ec2aa3bf0162901ccdc2f38b8f92427'); // private key
// '0xA2902059a7BF992f1450BACD7357CCAa5cC8336a'

computePublicKey

computePublicKey(privKey: BytesLike): string

import { computePublicKey } from 'essential-eth';

computePublicKey('0xb27cc8dea0177d910110e8d3ec5480d56c723abf433529f4063f261ffdb9297c');
// '0x045cd0032015eecfde49f82f4e149d804e8ac6e3a0bface32e37c72a71ceac864fe84da7e8df84342f7b11dfb753c4d158f636142b46b29cf7f0f171ae0aa4fb87'

computePublicKey([50,102,50,99,52,49,57,97,99,102,52,97,49,100,97,56,99,49,101,98,101,97,55,53,98,98,51,102,99,102,98,100]);
// '0x04a9cea77eca949df84f661cee153426fb51f2294b9364b4fac240df57360b9b0ac9c99e4d7966491ab4c81f8c82e0cd24ec5759832ad4ab736d22c7d90b806ee8'

concat

concat(arrayOfBytesLike: Array<BytesLikeWithNumber>): Uint8Array

import { concat } from 'essential-eth';

concat([0, 1]);
// Uint8Array(2) [ 0, 1 ]

decodeBytes32String

decodeBytes32String(bytes32: string): string

import { decodeBytes32String } from 'essential-eth';

decodeBytes32String('0x657373656e7469616c2d657468000000000000000000000000000000000000')
// 'essential-eth'

decodeEventLog

decodeEventLog(abi: JSONABI, log: undefined): undefined

import { decodeEventLog } from 'essential-eth';

const result = decodeEventLog(erc20ABI, {
topics: [
  '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
  '0x000000000000000000000000abc0000000000000000000000000000000000001',
  '0x000000000000000000000000abc0000000000000000000000000000000000002',
],
data: '0x0000000000000000000000000000000000000000000000000000000000000064',
});
// { eventName: 'Transfer', args: { from: '0xABC0...0001', to: '0xaBc0...0002', value: 100n } }

decodeFunctionResult

decodeFunctionResult(abi: JSONABI, functionName: string, data: string): any

import { decodeFunctionResult } from 'essential-eth';

import { decodeFunctionResult } from 'essential-eth';

const abi = [
{
  name: 'balanceOf',
  type: 'function',
  inputs: [{ name: 'owner', type: 'address' }],
  outputs: [{ name: 'balance', type: 'uint256' }],
},
];

const result = decodeFunctionResult(abi, 'balanceOf', '0x000...0001');
// result === 1n

encodeBytes32String

encodeBytes32String(text: string): string

import { encodeBytes32String } from 'essential-eth';

encodeBytes32String('essential-eth')
// '0x657373656e7469616c2d657468000000000000000000000000000000000000'

encodeFunctionData

encodeFunctionData(abi: JSONABI, functionName: string, args?: undefined): string

import { encodeFunctionData } from 'essential-eth';

import { encodeFunctionData } from 'essential-eth';

const abi = [
{
  name: 'balanceOf',
  type: 'function',
  inputs: [{ name: 'owner', type: 'address' }],
  outputs: [{ name: 'balance', type: 'uint256' }],
},
];

const data = encodeFunctionData(abi, 'balanceOf', [
'0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
]);

etherToGwei

etherToGwei(etherQuantity: string | number | bigint): bigint

import { etherToGwei } from 'essential-eth';

etherToGwei('1000').toString()
// '1000000000000'
etherToGwei(1000).toString()
// '1000000000000'

etherToWei

etherToWei(etherQuantity: string | number | bigint): bigint

import { etherToWei } from 'essential-eth';

etherToWei('1000').toString()
// '1000000000000000000000'
etherToWei(1000).toString()
// '1000000000000000000000'

formatUnits

formatUnits(value: string | number | bigint, decimals?: number): string

import { formatUnits } from 'essential-eth';

formatUnits(1000000n, 6)
// '1'

formatUnits('1000000000000000000', 18)
// '1'

formatUnits(1500000n, 6)
// '1.5'

getAddress

getAddress(address: string): string

import { getAddress } from 'essential-eth';

getAddress('0xfb6916095ca1df60bb79ce92ce3ea74c37c5d359')
// '0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359'

getEventSignature

getEventSignature(abi: JSONABI, eventName: string): string

import { getEventSignature } from 'essential-eth';

const abi = [
{
  type: 'event',
  name: 'Transfer',
  inputs: [
    { name: 'from', type: 'address', indexed: true },
    { name: 'to', type: 'address', indexed: true },
    { name: 'value', type: 'uint256', indexed: false },
  ],
},
];
getEventSignature(abi, 'Transfer');
// '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'

getEventTopic

getEventTopic(eventSignature: string): string

import { getEventTopic } from 'essential-eth';

getEventTopic('Transfer(address,address,uint256)');
// '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'

gweiToEther

gweiToEther(gweiQuantity: string | number | bigint): string

import { gweiToEther } from 'essential-eth';

gweiToEther('1000000000000')
// '1000'
gweiToEther(1000000000000)
// '1000'

hashMessage

hashMessage(message: string | Bytes): string

import { hashMessage } from 'essential-eth';

hashMessage("Hello World");
// '0xa1de988600a42c4b4ab089b619297c17d53cffae5d5120d82d8a92d0bb3b78f2'

hexConcat

hexConcat(items: Array<BytesLike>): string

import { hexConcat } from 'essential-eth';

hexConcat([[2, 4, 0, 1], 9, '0x2934', '0x3947']);
// '0x020400010929343947'

hexDataLength

hexDataLength(data: BytesLike): undefined

import { hexDataLength } from 'essential-eth';

hexDataLength([2, 4, 0, 1]);
// 4

hexDataLength('0x3925');
// 2

hexDataSlice

hexDataSlice(data: BytesLikeWithNumber, offset: number, endOffset: number): string

import { hexDataSlice } from 'essential-eth';

hexDataSlice([20, 6, 48], 0, 2);
// '0x1406'

hexStripZeros

hexStripZeros(value: BytesLike): string

import { hexStripZeros } from 'essential-eth';

hexStripZeros([0,0,0,48]);
// '0x30'

hexValue

hexValue(value: number | bigint | BytesLike | Hexable): string

import { hexValue } from 'essential-eth';

hexValue(39);
// '0x27'

hexValue([9, 4, 19, 4]);
// '0x9041304'

hexZeroPad

hexZeroPad(value: BytesLikeWithNumber, length: number): string

import { hexZeroPad } from 'essential-eth';

hexZeroPad('0x60', 2);
// '0x0060'

hexZeroPad(0x60, 3);
// '0x000060'

hexZeroPad('12345', 1);
// Throws

hexlify

hexlify(value: number | bigint | BytesLike | Hexable, options: DataOptions): string

import { hexlify } from 'essential-eth';

hexlify(4);
// '0x04'

hexlify(14);
// '0x0e'

id

id(text: string): string

import { id } from 'essential-eth';

id('Transfer(address,address,uint256)')
// '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'

// Get a function selector (first 4 bytes)
id('balanceOf(address)').slice(0, 10)
// '0x70a08231'

isAddress

isAddress(address: string): boolean

import { isAddress } from 'essential-eth';

isAddress('0xc0deaf6bd3f0c6574a6a625ef2f22f62a5150eab');
// true

isAddress('bad');
// false

// Does NOT support ENS.
isAddress('vitalik.eth');
// false

isBytes

isBytes(value: any): value

import { isBytes } from 'essential-eth';

isBytes([1,2,3]);
// true

isBytes(false);
// false

isBytes(new Uint8Array(1));
// true

isBytesLike

isBytesLike(value: any): value

import { isBytesLike } from 'essential-eth';

isBytesLike([1,2,3]);
// true

isBytesLike(false);
// false

isBytesLike(new Uint8Array(1));
// true

isHexString

isHexString(value: any, length: number): boolean

import { isHexString } from 'essential-eth';

isHexString('0x4924');
// true

isHexString('0x4924', 4);
// false
// length of 4 in bytes would mean a hex string with 8 characters

jsonRpcProvider

jsonRpcProvider(rpcUrl: string): JsonRpcProvider

import { jsonRpcProvider } from 'essential-eth';

jsonRpcProvider().getBlock('latest').then(block => {
console.log(block.number);
})
// 14530496

keccak256

keccak256(data: BytesLike): string

import { keccak256 } from 'essential-eth';

keccak256('essential-eth');
// '0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470'

keccak256('0x123');
// '0x5fa2358263196dbbf23d1ca7a509451f7a2f64c15837bfbb81298b1e3e24e4fa'

namehash

namehash(name: string): string

import { namehash } from 'essential-eth';

namehash('');
// '0x0000000000000000000000000000000000000000000000000000000000000000'

namehash('eth');
// '0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f04690a0bcc88a93fc4ae'

namehash('vitalik.eth');
// '0xee6c4522aab0003e8d14cd40a6af439055fd2577951148c14b6cea9a53475835'

pack

pack(types: Array<string>, values: Array<any>): string

import { pack } from 'essential-eth';

const types = ['bool', 'string', 'uint64'];
const values = [true, 'text', 30];
pack(types, values);
// '0x0174657874000000000000001e'

parseUnits

parseUnits(value: string, decimals?: number): bigint

import { parseUnits } from 'essential-eth';

parseUnits('1', 6)
// 1000000n

parseUnits('1.5', 6)
// 1500000n

parseUnits('1', 18)
// 1000000000000000000n

solidityKeccak256

solidityKeccak256(types: Array<string>, values: Array<any>): string

import { solidityKeccak256 } from 'essential-eth';

const types = ['string', 'bool', 'uint32'];
const values = ['essential-eth is great', true, 14];
solidityKeccak256(types, values);
// '0xe4d4c8e809faac09d58f468f0aeab9474fe8965d554c6c0f868c433c3fd6acab'

const types = ['bytes4', 'uint32[5]'];
const values = [[116, 101, 115, 116], [5, 3, 4, 9, 18]];
solidityKeccak256(types, values);
// '0x038707a887f09355dc545412b058e7ba8f3c74047050c7c5e5e52eec608053d9'

splitSignature

splitSignature(signature: SignatureLike): Signature

import { splitSignature } from 'essential-eth';

const signature = '0x60bc4ed91f2021aefe7045f3f77bd12f87eb733aee24bd1965343b3c27b3971647252185b7d2abb411b01b5d1ac4ab41ea486df1e9b396758c1aec6c1b6eee331b';
splitSignature(signature);
{
 r: "0x60bc4ed91f2021aefe7045f3f77bd12f87eb733aee24bd1965343b3c27b39716",
 s: "0x47252185b7d2abb411b01b5d1ac4ab41ea486df1e9b396758c1aec6c1b6eee33",
 _vs: "0x47252185b7d2abb411b01b5d1ac4ab41ea486df1e9b396758c1aec6c1b6eee33",
 recoveryParam: 0,
 v: 27,
 yParityAndS: "0x47252185b7d2abb411b01b5d1ac4ab41ea486df1e9b396758c1aec6c1b6eee33",
 compact: "0x60bc4ed91f2021aefe7045f3f77bd12f87eb733aee24bd1965343b3c27b3971647252185b7d2abb411b01b5d1ac4ab41ea486df1e9b396758c1aec6c1b6eee33"
}

stripZeros

stripZeros(value: BytesLike): Uint8Array

import { stripZeros } from 'essential-eth';

stripZeros('0x00002834');
// Uint8Array { [Iterator]  0: 40, 1: 52 }
// Equivalent to '0x2834'

toChecksumAddress

toChecksumAddress(address: string): string

import { toChecksumAddress } from 'essential-eth';

toChecksumAddress('0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359');
// '0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359'

Similar to "getAddress" in ethers.js

Similar to "toChecksumAddress" in web3.js

toUtf8Bytes

toUtf8Bytes(data: string): Uint8Array

import { toUtf8Bytes } from 'essential-eth';

toUtf8Bytes('essential-eth');
// Uint8Array { [Iterator] 0: 101, 1: 115, 2: 115, 3: 101, 4: 110, 5: 116, 6: 105, 7: 97, 8: 108, 9: 45, 10: 101, 11: 116, 12: 104 }

toUtf8Bytes('ethereum');
// Uint8Array { [Iterator]  0: 101, 1: 116, 2: 104, 3: 101, 4: 114, 5: 101, 6: 117, 7: 109 }

toUtf8String

toUtf8String(bytes: BytesLike): string

import { toUtf8String } from 'essential-eth';

toUtf8String(new Uint8Array([101, 116, 104]))
// 'eth'

toUtf8String('0x657468')
// 'eth'

weiToEther

weiToEther(weiQuantity: string | number | bigint): string

import { weiToEther } from 'essential-eth';

weiToEther('1000000000000000000000')
// '1000'
weiToEther(1000000000000000000000)
// '1000'

zeroPad

zeroPad(value: BytesLike, length: number): Uint8Array

import { zeroPad } from 'essential-eth';

zeroPad('0x039284');
// Uint8Array { [Iterator]  0: 0, 1: 0, 2: 0, 3: 3, 4: 146, 5: 132 }
// Equivalent to 0x000000039284

zeroPad([39, 25, 103, 45], 5);
// Uint8Array { [Iterator]  0: 0, 1: 39, 2: 25, 3: 103, 4: 45 }

• The return-type TinyBig is just Big but expands scientific notation on toNumber() and toString()

Providers

import { JsonRpcProvider } from 'essential-eth';
const provider = new JsonRpcProvider('RPC URL HERE' /* Try POKT or Infura */);
// OR for very quick testing (limited to 10,000 requests)
const provider = new JsonRpcProvider();

import { FallthroughProvider } from 'essential-eth';

// The FallthroughProvider handles falling through to the next valid URL.
// It's dynamic to never trust one URL again when it fails * until it has tried all other provided URLs
// The default timeout for a request is 8 seconds after which it moves to the next URL
const provider = new FallthroughProvider([
  'https://bad.com',
  'https://free-eth-node.com/api/eth',
]);
provider.getGasPrice().toNumber();
/*
39695942769
*/

call

provider.call(transaction: TransactionRequest, blockTag?: BlockTag): Promise<string>

import { JsonRpcProvider } from 'essential-eth';
const provider = new JsonRpcProvider('RPC URL HERE' /* Try Infura or POKT */);

await provider.call({
  to: '0x6b175474e89094c44da98b954eedeac495271d0f',
  data: '0x70a082310000000000000000000000006E0d01A76C3Cf4288372a29124A26D4353EE51BE',
});
// '0x0000000000000000000000000000000000000000000000000858898f93629000'

estimateGas

provider.estimateGas(transaction: TransactionRequest): Promise<TinyBig>

import { JsonRpcProvider } from 'essential-eth';
const provider = new JsonRpcProvider('RPC URL HERE' /* Try Infura or POKT */);

await provider.estimateGas({
  // Wrapped ETH address
  to: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
  data: '0xd0e30db0',
  value: etherToWei('1.0').toHexString(),
});
// { TinyBig: "27938" }

getBalance

provider.getBalance(address: string, blockTag?: BlockTag): Promise<TinyBig>

import { JsonRpcProvider } from 'essential-eth';
const provider = new JsonRpcProvider('RPC URL HERE' /* Try Infura or POKT */);

await provider.getBalance('0x7cB57B5A97eAbe94205C07890BE4c1aD31E486A8');
// 28798127851528138

getBlock

provider.getBlock(timeFrame?: BlockTag, returnTransactionObjects?: boolean): Promise<BlockResponse>

import { JsonRpcProvider } from 'essential-eth';
const provider = new JsonRpcProvider('RPC URL HERE' /* Try Infura or POKT */);

await provider.getBlock(14879862);
// {
//   baseFeePerGas: { TinyBig: 39095728776 },
//   difficulty: { TinyBig: 14321294455359973 },
//   extraData: "0x486976656f6e2073672d6865617679",
//   gasLimit: { TinyBig: 29970620 },
//   gasUsed: { TinyBig: 20951384 },
//   hash: "0x563b458ec3c4f87393b53f70bdddc0058497109b784d8cacd9247ddf267049ab",
//   logsBloom:
//     "0x9f38794fe80b521794df6efad8b0d2e9582f9ec3959a3f9384bda0fa371cfa5fac5af9d515c6bdf1ec325f5b5f7ebdd6a3a9fae17b38a86d4dc4b0971afc68d8086640550f4c156e6f923f4a1bb94fb0bed6cdcc474c5c64bfeff7a4a906f72b9a7b94004ee58efc53d63ac66961acd3a431b2d896cc9fd75f6072960bced45f770587caf130f57504decfcb63c6ca8fbc5bdbd749edd5a99a7375d2b81872289adb775fb3c928259f4be39c6d3f4d5b6217822979bb88c1f1fb62429b1b6d41cf4e3f77f9e1db3f5723108f1e5b1255dd734ad8cdb11e7ea22487c788e67c83777b6f395e504ca59c64f52245ee6de3804cf809e5caa4f0ea6a9aa9eb6ed801",
//   miner: "0x1aD91ee08f21bE3dE0BA2ba6918E714dA6B45836",
//   mixHash: "0x73cc9419bfb89c9d41c3a8c34ce56b5ebe468bdcf870258d2e77262275d580ec",
//   nonce: "0x976f3f5d596ffb08",
//   number: 14879862,
//   parentHash: "0x95986ae14a71face8d9a6a379edd875b2e8bc73e4de0d9d460e7752bddb0f579",
//   receiptsRoot: "0x8e6ba2fd9bee602b653dae6e3132f16538c2c5df24f1df8c000392053f73defa",
//   sha3Uncles: "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
//   size: { TinyBig: 134483 },
//   stateRoot: "0xbf2bb67bd1c741f3d00904b8451d7c2cf4e3a2726f5a5884792ede2074747b85",
//   timestamp: { TinyBig: 1654016186 },
//   totalDifficulty: { TinyBig: 50478104614257705213748 },
//   transactions: [
//     "0xb3326a9149809603a2c28545e50e4f7d16e194bf5ee9764e0544603854c4a8d2",
//     "0x8b42095f8d335404a4896b2817b8e5e3d86a5a87cb434a8eec295d5280a7f48e",
//     "0x882f78fcb73f0f7ad0700bb0424a8b4beb366aaa93b88a3562c49a8d0ce4dcff",
//     ...
//   ],
//   transactionsRoot: "0x5934902f3dcc263ec34f24318179bf6301f53f4834685792066026f3a4849d72",
//   uncles: [],
// }

getBlockNumber

provider.getBlockNumber(): Promise<number>

import { JsonRpcProvider } from 'essential-eth';
const provider = new JsonRpcProvider('RPC URL HERE' /* Try Infura or POKT */);

await provider.getBlockNumber();
// 1053312

getCode

provider.getCode(address: string, blockTag?: BlockTag): Promise<string>

import { JsonRpcProvider } from 'essential-eth';
const provider = new JsonRpcProvider('RPC URL HERE' /* Try Infura or POKT */);

await jsonRpcProvider().getCode(
  '0xaC6095720221C79C6E7C638d260A2eFBC5D8d880',
  'latest',
);
// '0x608060405234801561001057600080fd5b506004361061...'

getFeeData

provider.getFeeData(): Promise<FeeData>

import { JsonRpcProvider } from 'essential-eth';
const provider = new JsonRpcProvider('RPC URL HERE' /* Try Infura or POKT */);

await provider.getFeeData();
// {
//   gasPrice: { TinyBig: "14184772639" },
//   lastBaseFeePerGas: { TinyBig: "14038523098" },
//   maxFeePerGas: { TinyBig: "29577046196" },
//   maxPriorityFeePerGas: { TinyBig: "1500000000" }
// }

getGasPrice

provider.getGasPrice(): Promise<TinyBig>

import { JsonRpcProvider } from 'essential-eth';
const provider = new JsonRpcProvider('RPC URL HERE' /* Try Infura or POKT */);

await provider.getGasPrice();
// 52493941856

getLogs

provider.getLogs(filter: Filter | FilterByBlockHash): Promise<Array<Log>>

import { JsonRpcProvider } from 'essential-eth';
const provider = new JsonRpcProvider('RPC URL HERE' /* Try Infura or POKT */);

provider.getLogs({
  address: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
  topics: [
    '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
    '0x00000000000000000000000021b8065d10f73ee2e260e5b47d3344d3ced7596e',
  ],
  fromBlock: 14825027,
  toBlock: 14825039,
});

[
  {
    address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
    blockHash:
      '0x8e0dfac2f704851960f866c8708b3bef2f66c0fee0329cf25ff0261b264ca6bc',
    blockNumber: 14825029,
    data: '0x000000000000000000000000000000000000000000000000005f862ee352a38a',
    logIndex: 384,
    removed: false,
    topics: [
      '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
      '0x00000000000000000000000021b8065d10f73ee2e260e5b47d3344d3ced7596e',
      '0x00000000000000000000000068b3465833fb72a70ecdf485e0e4c7bd8665fc45',
    ],
    transactionHash:
      '0xbd49031be16f8fd1775f4e0fe79b408ffd8ae9c65b2827ee47e3238e3f51f4c0',
    transactionIndex: 226,
  },
];

getNetwork

provider.getNetwork(): Promise<Network>

import { JsonRpcProvider } from 'essential-eth';
const provider = new JsonRpcProvider('RPC URL HERE' /* Try Infura or POKT */);

jsonRpcProvider('https://free-eth-node.com/api/eth').getNetwork();
// { chainId: 1, name: 'eth', ensAddress: '0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e' }

jsonRpcProvider('https://free-eth-node.com/api/MATIC').getNetwork();
// { chainId: 137, name: 'MATIC', ensAddress: null }

getTransaction

provider.getTransaction(transactionHash: string): Promise<TransactionResponse>

import { JsonRpcProvider } from 'essential-eth';
const provider = new JsonRpcProvider('RPC URL HERE' /* Try Infura or POKT */);

await provider.getTransaction(
  '0x9014ae6ef92464338355a79e5150e542ff9a83e2323318b21f40d6a3e65b4789',
);
// {
//   accessList: [],
//   blockHash: "0x876810a013dbcd140f6fd6048c1dc33abbb901f1f96b394c2fa63aef3cb40b5d",
//   blockNumber: 14578286,
//   chainId: 1,
//   from: "0xdfD9dE5f6FA60BD70636c0900752E93a6144AEd4",
//   gas: { TinyBig: 112163 },
//   gasPrice: { TinyBig: 48592426858 },
//   hash: "0x9014ae6ef92464338355a79e5150e542ff9a83e2323318b21f40d6a3e65b4789",
//   input: "0x83259f17000000000000000000000000000000000000000000...",
//   maxFeePerGas: { TinyBig: 67681261618 },
//   maxPriorityFeePerGas: { TinyBig: 1500000000 },
//   nonce: { TinyBig: 129 },
//   r: "0x59a7c15b12c18cd68d6c440963d959bff3e73831ffc938e75ecad07f7ee43fbc",
//   s: "0x1ebaf05f0d9273b16c2a7748b150a79d22533a8cd74552611cbe620fee3dcf1c",
//   to: "0x39B72d136ba3e4ceF35F48CD09587ffaB754DD8B",
//   transactionIndex: 29,
//   type: 2,
//   v: 0,
//   value: { TinyBig: 0 },
//   confirmations: 298140,
// }

getTransactionCount

provider.getTransactionCount(address: string, blockTag?: BlockTag): Promise<number>

import { JsonRpcProvider } from 'essential-eth';
const provider = new JsonRpcProvider('RPC URL HERE' /* Try Infura or POKT */);

await provider.getTransactionCount(
  '0x71660c4005ba85c37ccec55d0c4493e66fe775d3',
);
// 1060000

await provider.getTransactionCount(
  '0x71660c4005ba85c37ccec55d0c4493e66fe775d3',
  'latest',
);
// 1060000

await provider.getTransactionCount(
  '0x71660c4005ba85c37ccec55d0c4493e66fe775d3',
  14649390,
);
// 1053312

getTransactionReceipt

provider.getTransactionReceipt(transactionHash: string): Promise<TransactionReceipt>

import { JsonRpcProvider } from 'essential-eth';
const provider = new JsonRpcProvider('RPC URL HERE' /* Try Infura or POKT */);

await provider.getTransactionReceipt(
  '0x9014ae6ef92464338355a79e5150e542ff9a83e2323318b21f40d6a3e65b4789',
);
// {
//   blockHash: "0x876810a013dbcd140f6fd6048c1dc33abbb901f1f96b394c2fa63aef3cb40b5d",
//   blockNumber: 14578286,
//   contractAddress: null,
//   cumulativeGasUsed: { TinyBig: 3067973 },
//   effectiveGasPrice: { TinyBig: 48592426858 },
//   from: "0xdfD9dE5f6FA60BD70636c0900752E93a6144AEd4",
//   gasUsed: { TinyBig: 112163 },
//   logs: [
//     {
//       address: "0x0eDF9bc41Bbc1354c70e2107F80C42caE7FBBcA8",
//       blockHash: "0x876810a013dbcd140f6fd6048c1dc33abbb901f1f96b394c2fa63aef3cb40b5d",
//       blockNumber: 14578286,
//       data: "0x0000000000000000000000000000000000000000000003a12ec797b5484968c1",
//       logIndex: 42,
//       topics: [
//         "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
//         "0x00000000000000000000000039b72d136ba3e4cef35f48cd09587ffab754dd8b",
//         "0x000000000000000000000000dfd9de5f6fa60bd70636c0900752e93a6144aed4",
//       ],
//       transactionHash: "0x9014ae6ef92464338355a79e5150e542ff9a83e2323318b21f40d6a3e65b4789",
//       transactionIndex: 29,
//     },
//     {
//       address: "0x39B72d136ba3e4ceF35F48CD09587ffaB754DD8B",
//       blockHash: "0x876810a013dbcd140f6fd6048c1dc33abbb901f1f96b394c2fa63aef3cb40b5d",
//       blockNumber: 14578286,
//       data: "0x0000000000000000000000000000000000000000000003a12ec797b5484968c1",
//       logIndex: 43,
//       topics: [
//         "0x34fcbac0073d7c3d388e51312faf357774904998eeb8fca628b9e6f65ee1cbf7",
//         "0x000000000000000000000000dfd9de5f6fa60bd70636c0900752e93a6144aed4",
//         "0x0000000000000000000000000000000000000000000000000000000000000003",
//       ],
//       transactionHash: "0x9014ae6ef92464338355a79e5150e542ff9a83e2323318b21f40d6a3e65b4789",
//       transactionIndex: 29,
//     },
//   ],
//   logsBloom: "0x00000000000000000000000000000...",
//   status: 1,
//   to: "0x39B72d136ba3e4ceF35F48CD09587ffaB754DD8B",
//   transactionHash: "0x9014ae6ef92464338355a79e5150e542ff9a83e2323318b21f40d6a3e65b4789",
//   transactionIndex: 29,
//   type: 2,
//   byzantium: true,
//   confirmations: 298171,
// }

resolveName

provider.resolveName(name: string): Promise<string | null>

Resolves an ENS name to an Ethereum address. Returns null if the name has no resolver or no address set.

Similar to "resolveName" in ethers.js

import { JsonRpcProvider } from 'essential-eth';
const provider = new JsonRpcProvider('RPC URL HERE' /* Try Infura or POKT */);

await provider.resolveName('vitalik.eth');
// '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'

await provider.resolveName('daws.eth');
// '0x5C389...' (resolved address)

await provider.resolveName('thisdoesnotexist12345.eth');
// null

Contract

⚠️ Only read functions are currently supported. ⚠️

• 🧪 Contract support is experimental, do not use this in production yet. (even though earni.fi does)

Encoding support:

• bool
• bytes
• address

Decoding support:

• bool
• address
• uint256
• bytes32
• uint8
• string (only if there is one string output, not multiple yet)

Assume all types outside the above types will break for now

import { Contract, jsonRpcProvider, JSONABI } from 'essential-eth';
// UNI airdrop contract
const contractAddress = '0x090D4613473dEE047c3f2706764f49E0821D256e';
const provider = jsonRpcProvider(/* RPC URL optional */);

const abi: JSONABI = [
  {
    inputs: [
      {
        internalType: 'uint256',
        name: 'index',
        type: 'uint256',
      },
    ],
    name: 'isClaimed',
    outputs: [
      {
        internalType: 'bool',
        name: '',
        type: 'bool',
      },
    ],
    stateMutability: 'view',
    type: 'function',
  },
];

const contract = new Contract(contractAddress, abi, provider);

(async () => {
  // prints boolean as to whether index 0 has claimed airdrop or not
  console.log(await contract.isClaimed(0));
})();

contractFunctionName(args)

Any function on a contract. Returns are the same as ethers.js, except that instead of BigNumber, essential-eth always returns a TinyBig

More Info

🧪 This repo is under active development. The API is less-fully featured than web3 and ethers. More functions added often!

👨🏻‍💻 Breaking changes will exist between minor versions until 1.0.0 (Versions go major.minor.patch)

Identical vs Similar vs Dissimilar {#isd}

Throughout the documentation for essential-eth, you may notice that some functions are compared to ethers.js and web3.js. The keywords identical, similar, and dissimilar are used to help you migrate to essential-eth. Here's a guide on what these keywords mean:

• Identical -- should behave exactly like the library you're already using, except the types might be different (TinyBig vs Bn.js).
• Similar -- can probably be used as a replacement to the library you're currently using, except there are some differences. Read the notes next to this keyword to see why these aren't considered identical.
• Dissimilar -- should not be used in place of the function you're currently using. Read the notes next to this keyword to see why these functions aren't considered similar, and potentially learn how to alter your implementation to make essential-eth work for you.

Note: In web3.js, almost every method or function can be passed a callback. essential-eth, like ethers.js, does not include this functionality and trusts that users will rely on the much more modern promise and async/await patterns.

Miscellaneous

• 📓 View full docs
• 📓 View changelog (by looking at releases diff)
• 📋 View our project board

Contributing and GitPOAP

We welcome and appreciate all contributions to Essential Eth! If you're interested in helping us improve this library, please read our Contributing Guidelines to understand the types of contributions we're looking for and the process of making them.

In partnership with GitPOAP, Essential ETH wants to recognize all contributors for their contributions toward the growth of this library. More information about GitPOAP can be found on the Contributing Guidelines.