destiner / ethcall

ethers.js-compatible wrapper around Multicall

ethcall

Warning

This package is not maintained and will be archived. Use viem's multicall.

Utility library to make calls to Ethereum blockchain.

Uses MakerDAO's Multicall contracts to make multiple requests in a single HTTP query. Encodes and decodes data automatically.

Powered by abi-coder and ethers.js.

npm install ethcall

This package requires ethers V6. If you use ethers V5, you need to install ethcall V5.

This package uses Import Assertions, which is supported by Vite 4+, Rollup 3+, and Node 16+.

This package is a pure ESM package. Follow this guide for more info.

API

• Contract
  • constructor(address, abi): creates Contract instance
  • CALL_FUNC_NAME: yields a call object; usage is similar to ethers Contract class
• Provider
  • constructor(chainId, provider, config): creates a Provider instance
  • all(calls): executes all calls in a single request
  • tryAll(calls): executes all calls in a single request. Ignores reverted calls and returns null value in place of return data (wrapper on top of tryAggregate method)
  • tryEach(calls, canFail): executes all calls in a single request. Ignores reverted calls and returns null value in place of return data for the calls that are allowed to fail (wrapper on top of aggregate3 method)
  • getEthBalance(address): returns account ether balance

Example

Also see examples for reference.

import { Contract, Provider } from 'ethcall';
import { InfuraProvider } from 'ethers';

import erc20Abi from './abi/erc20.json' assert { type: 'json' };

const infuraKey = 'INSERT_YOUR_KEY_HERE';
const provider = new InfuraProvider('mainnet', infuraKey);

const daiAddress = '0x6b175474e89094c44da98b954eedeac495271d0f';

async function call() {
  const ethcallProvider = new Provider(1, provider);

  const daiContract = new Contract(daiAddress, erc20Abi);

  const uniswapDaiPool = '0x2a1530c4c41db0b0b2bb646cb5eb1a67b7158667';

  const ethBalanceCall = ethcallProvider.getEthBalance(uniswapDaiPool);
  const daiBalanceCall = daiContract.balanceOf(uniswapDaiPool);

  const data = await ethcallProvider.all([ethBalanceCall, daiBalanceCall], {
    blockTag: 'latest',
  });

  const ethBalance = data[0];
  const daiBalance = data[1];

  console.log('eth balance', ethBalance.toString());
  console.log('dai balance', daiBalance.toString());
}

call();

Contributing

All Mulitcall contracts are stored in src/multicall.ts file. There are three getMulticall methods corresponding to three Multicall versions. To add a new contract, you need to know its version, address, chain id of the underlying chain, and (optionally) block at which the Multicall contract was deployed.

Deployless Multicall

If you query a chain on which Multicall is not deployed, or if you query a historical block before the deployment of the contract, the deployless version will be used instead. In short, deployless Multicall "emulates" the deployed contract and returns the exact same data. Note that you can't query ETH balance using deployless version.

You can read more about deployless Multicall here.

ethcall's Issues

Allow custom multicall addresses in Init

As of now the multicall deployment addresses must be specified in multicall.ts based on the CHAIN_ID. Which is fine as defaults.
But for example if one wants to deploy to a local blockchain (Ganache, Hardhat) or any other non public listed private blockchain it cant really be used.

Would you guys consider making this an option in the future?

Remove "using deployless version" warning

Deployless Multicall has been used for months now without any known issues. It's also documented in README.

Assuming no issues with deployless Multicall will be found, the warning will be removed in the next major release.

Switch to Pure ESM

Update module and target in tsconfig.json. Include type, exports, engines in package.json.

This requires a major bump.

Use ethers 6

Once ethers v6 becomes more stable, we should switch to it.

Move ethers packages to peer dependencies

Allow manually setting gasLimit

afik, ethcall relies on the user's wallet to infer gasLimit for rpc calls. In some cases, this gas limit cannot be deduced by the wallet (for example when you're building a list of multicall from a dynamic array, even if you know its max size). I'd like to either be able to set the gasLimit manually, or have ethcall set it to a high value since it's read-only anyway.

edit: I was probably doing something wrong somewhere else in my code.

package.json has wrong exports

package.json exports should be a relative path (https://webpack.js.org/guides/package-exports/).

"exports": "dist/index.js",

should be

"exports": "./dist/index.js",

This leads to compilations errors when included in jest testing.

Multicall1 address on 1337

Hello!

While playing with getEthBalance, I noticed that this function is using the multicall1 contract (even with tryAll) which is set to address 0x77dCa2C955b15e9dE4dbBCf1246B4B85b651e50e on the multicall addresses file.

This contract is not deployed on mainnet but only on testsnets.
Wondering if this should be moved to 0xeefba1e63905ef1d7acba5a8513c70307c1ce441 (mainnet multicall1) or if getEthBalance should respect all, tryAll or tryEach!

Thank you for your work!

[Clarification] Signed / write transactions

Hi.
I'd like to send multiple signed (write) transactions using ethcall. Is that something possible or is this library focused on read contract information and not mutating txs ?

Thanks

The result returned is un-named

For example, when calling Pair.getReserves() in uniswap.
The typechain result is

getReserves(
    overrides?: CallOverrides
  ): Promise<
    [BigNumber, BigNumber, number] & {
      reserve0: BigNumber;
      reserve1: BigNumber;
      blockTimestampLast: number;
    }
  >;

However the returned object form this library is just [BigNumber, BigNumber, number], the named object is missing

Use v3 for "all"/"tryAll" when possible

Currently, Multicall V1 is used for all calls, V2 is used for tryAll, and V3 is used for tryEach. However, V3 brings some gas optimisations, and it makes sense to use it for all calls.

One gotcha to keep in mind is that V3 may be not available for a given chain (not deployed) or a given block (block < multicall3DeploymentBlock). In those cases, we need to fallback to V1/V2.

Issue w/ ethcall when using a JsonRpcProvider

Having this error on ethers 5.6.7 when using ethcall with a JsonRpcProvider:
Argument of type 'JsonRpcProvider' is not assignable to parameter of type 'BaseProvider'.

Add arbitrum testnet 421611

I would like to add a multicall config for Arbitrum testnet:
chainId: 421611
Contract: 0x96DB1F8055074aB62161B6Ad66Ab6B8679513DeF

I tried to do a fork and tried to compile on my project but had problems building
If someone could try and merge, would be awesome !

If needed i can do a pull request but i don't know if it only needs to be added in multicall.ts

Thanks !

Don't override "from" value by default

Currently, it uses Multicall address as call from value. It should be empty by default.

Test fetching against local node

API: provide call overrides (block, from, etc) as object

Use (..., {block, from}) instead of (..., block, from). All overrides are optional.

Set up test matrix

Should be tested in node (14, 16, 18) and browser.

Add example directory

Create a directory with usage samples covering most use cases (eth balance, token balance, multiple token balance, fetch AMM pools, fetch lending rates).

Multicall2 support

Makerdao has updated their multicall repo with a newer version of multicall contract called Multicall2
https://github.com/makerdao/multicall/blob/master/src/Multicall2.sol

The newer multicall contract adds various new functions but the most important feature is that there is a tryAggregate function which allows ignoring any reverted calls.

Ideally, ethcall should move towards supporting the new contract without changing any of the user facing functions. I've kicked off the PR to do so here. #5

Upgrade addresses to include multicall3

https://github.com/mds1/multicall v3 just released

Allow to use different networks like Sepolia.

Need to refresh the list of multicall contracts to keep it up to date.

Also would be nice to have some API to add more contracts an runtime, would also make testing easier and allow users to use custom contracts.

provider.setMultiCall3({
  address: "",
  block: 0
})

Feature request: add support for 'pending' blockTag

Current multicall calls accept a block number as optional parameter, otherwise they use the default 'latest' block number.
The issue is that metamask has a 20 seconds cache on 'latest' block, so for fast EVM blockchains it's sometimes useful to be able to make calls with 'pending' block number to bypass the metamask cache and get up-to-date results.

Doesn't work with Web3 provider in browser

I'm getting this error:

Unhandled Rejection (Error): call revert exception (method="aggregate((address,bytes)[])", errorSignature=null, errorArgs=[null], reason=null, code=CALL_EXCEPTION, version=abi/5.1.0)

Clarification

nvm :)

Cannot find package

I'm getting the following error when I try to import the "ethcall" library:

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '/path/to/my/project/node_modules/ethcall/' imported from /path/to/my/project/index.js

Steps to replicate

1. npm install ethcall
2. Add import { Contract, Provider } from "ethcall"; to the top of an index.js file.
3. Try running node index.js

Document public methods

Add JSDoc for each public method so that tooling can provide inline documentation.

Can the callStatic contract method be supported?

Dependency Dashboard

This issue provides visibility into Renovate updates and their statuses. Learn more

Other Branches

These updates are pending. To force PRs open, click the checkbox below.

• Update dependency minimist to 1.2.6 [SECURITY]

---

• Check this box to trigger a request for Renovate to run again on this repository

Remove init step

Currently, init is required before making any calls. The reason behind init is to get chain id from the passed provider.
Instead, ask for provider and chain id in constructor and remove the need for init.

queryFilter on Multicall

It would be nice if there is queryFilter on contract class like etherjs contract.queryFilter

Encountering RejectCallerWithCode error when using Anvil

Forked mainnet using anvil 0.1.0 (28312e7 2022-10-13T00:10:13.586314Z)

Turned on the logs by setting RUST_LOG env variable

RUST_LOG=backend,api anvil -f $RPC_URL

Then using latest ethcall and ethers.js, create a Provider() and call all() or tryAll()

Emits error like below

2022-10-13T02:20:01.419714Z TRACE backendhandler: received request basic address=0xca11bde05977b3631167028862be2a173976ca11
2022-10-13T02:20:01.419745Z TRACE backend: call return RejectCallerWithCode out: None gas 0 on block 15736119

This is probably due to overriding the from to the multicall address

https://github.com/Destiner/ethcall/blob/master/src/call.ts#L63

Since some EVM implementations have limitations like this, I think from should be changed to a non-contract address.
https://eips.ethereum.org/EIPS/eip-3607

Error: invalid signer or provider

Hello!

I've tried to run the example and a custom code of mine but in both cases I got an Error: invalid signer or provider. The provider works fine by itself though, I was able to query data, like the block number for example.

Supporting ethers human-readable ABIs

Hello. Great work on this library. It's very simple and easy to use.

I'm currently in the process of switching one of the projects I work on to using ethers' Human Readable ABI format, as opposed to the standard ABI format, particularly because of the readability, as well as the (minimal) bundle size savings we can get from doing that (we have a lot of ABI's in the frontend code). However, since ethcall (to my understanding) does not support this, we still have to keep the regular ABIs around for the contracts we use ethcall on.

I was wondering if adding support for this was on the roadmap. If so, I would love to open a PR that does this.

That said, I completely understand if you would like to keep this library as-is, and not introduce more complexity.

getting importAssertions error

As ethcall is using assert keyword inside lib/call.js and lib/calls.js to import ABI's. Using ethcall in typescript project giving importAssertions error. It's a CRA which is customized using react-app-rewired

The solution is suggested in the error itself, which is adding a Babel plugin called @babel/plugin-syntax-import-assertions

Or are there any other solutions for this?

getEthBalance(address) function is stale

The implementation of the getEthBalance(address) function seems stale, it supports only multicall1 (and checks for provider that is not needed anymore): https://github.com/Destiner/ethcall/blob/master/src/provider.ts#L47-L55

It's possible to use directly the same call exported by the calls API as a workaround, but I guess the one in the provider should work as well.