pilum •

Lightweight, Modern Multicall3 Typescript Library published on npm.

Multicall3 flexibly aggregates results from multiple smart contract function calls. By allowing the caller to specify an additional parameter per call (a boolean for if the call should be required to succeed), the call results can be aggregated gracefully on a per-call basis.

Since calls are bundled as a single JSON-RPC request to the Multicall3 contract, this dramatically reduces the load on RPC servers, especially important for remote hosts like Infura and Alchemy. Additionally, packing calls in one request causes the calls to be executed in the same block, with the block number returned so potential responses from outdated RPC nodes may be ignored.

By default, the deployed Multicall3 contract is used. This can be overridden, see Custom-Multicall-Contracts. But, Multicall3 is highly recommendeded (more details below).

Multicall aggregators and executors are statically overloaded to allow for zero-config execution. Meaning, you can execute calls using Multicall with zero overhead except your calls. Although this is not recommended due to its rpc-unreliability, we demonstrate it here.

To further explore using pilum, please check out our Usage docs or dive right into our examples.

Installation

npm install pilum
# OR
yarn add pilum

Usage

Importing in ES6 Javascript / TypeScript:

import { Multicall } from 'pilum';

Since pilum makes an RPC call to a Multicall contract, we need to use a provider. It's highly recommended that you specify a provider, rather than rely on ethers's default provider (which is what pilum uses under the hood for the zero config execution).

Recommended Usage (using a custom provider)

import { ethers } from 'ethers';
import { Multicall, ContractCall } from 'pilum';

// Create a custom provider
const provider = new ethers.providers.JsonRpcProvider(
  "https://mainnet.infura.io/v3/<YOUR-INFURA-API-KEY>" // Example RPC URL
);

// Craft the Multicall Instance
const multicall = new Multicall({
  provider: provider
});

// Define our calls
const calls: ContractCall[] = [
  {
    reference: 'blockNumCall',
    contractAddress: '0xcA11bde05977b3631167028862bE2a173976CA11',
    abi: [ { name: 'getBlockNumber', type: 'function', stateMutability: 'view', inputs: [], outputs: [ { name: 'blockNumber', type: 'uint256' }] } ],
    method: 'getBlockNumber',
    params: [],
    value: 0,
  }
];

// Call the Multicall associated functions directly
const { results } = await Multicall.call(calls);

// Print the call result
console.log(results);

Zero Config Execution

Not Recommended (due to RPC unreliability).

import { Multicall, ContractCall } from 'pilum';

// Define our calls
const calls: ContractCall[] = [
  {
    reference: 'blockNumCall',
    contractAddress: '0xcA11bde05977b3631167028862bE2a173976CA11',
    abi: [ { name: 'getBlockNumber', type: 'function', stateMutability: 'view', inputs: [], outputs: [ { name: 'blockNumber', type: 'uint256' }] } ],
    method: 'getBlockNumber',
    params: [],
    value: 0,
  }
];

// Call the Multicall associated functions directly with zero overhead
const { results } = await Multicall.call(calls);

// Print the call result
console.log(results);

Multicall Options

Let's say you instantiated a multicall instance in your code, but later on want to multicall on a different network or to a different multicall address, without instantiating a new multicall instance.

pilum provides a flexible way to specify these parameters when executing a call. This is done by adding an optional options parameter to both the static (zero-config) and class-level call method.

To specify these parameters, execute a call with an additional object as the last parameter.

const { results } = await Multicall.call(calls, {
  provider: provider,
  abi: <YOUR_MULTICALL_ABI_OBJECT>,
  address: '<YOUR-MULTICALL-ADDRESS>',
  network: 5, // Any network id supported by ethers, here 5 is the Ethereum Goerli Testnet
});

Custom Multicall Contracts

By default, the deployed Multicall3 contract is used. This can be overridden by specifying the address parameter in the constructor like so:

const multicall = new Multicall({
  address: '0xcA11bde05977b3631167028862bE2a173976CA11',
});

But, Multicall3 is highly recommendeded. It's ABI is backwards compatible with Multicall and Multicall2, but it's cheaper to use (so you can fit more calls into a single request), and it adds an aggregate3 method so you can specify whether calls are allowed to fail on a per-call basis. Additionally, it's deployed on every network at the same address.

Alternate Networks

By default, pilum uses Ethereum mainnet. You can specify a different network by passing a network parameter (the chain(network) id) to the constructor like so:

const multicall = new Multicall({
  network: 4,
});

Multicall, Multicall2, and Multicall3 deployments are supported across all networks listed in the Multicall3 repository.

Examples

There are numerous examples demonstrating how to use pilum's Multicall in the examples directory.

Development

Any and all pull requests are welcome and highly appreciated!

Repository Blueprint

examples
├─ uniquery — Minimal Queries for Uniswap pool statistics
├─ compquery — Multicalled Compound Protocol Math Queries
src
├─ abis/ — Multicall Contract ABIs
├─ models/ — Multicall Class Argument and Response Types
├─ networks/ — Network Configurations and their respective Multicall Contract Deployment Addresses
├─ index.ts — "Package Re-exports"
├─ Multicall.ts — "The Multicall Contract"
tests
└─ ...

License

AGPL-3.0-only

Acknowledgements

• Multicall3
• ethereum-multicall
• Multicall.js
• 0xSequence's Multicall Library
• snapshot.js
• MakerDAO's Multicall
• Reducing NPM Package Size

Disclaimer

This library is provided as is. No guarantee, representation or warranty is being made, express or implied, as to the safety or correctness of the user interface or library code. None of the content present here has been audited and as such there can be no assurance it will work as intended, and users may experience delays, failures, errors, omissions, loss of transmitted information or loss of funds. The creators are not liable for any of the foregoing. Users should proceed with caution and use at their own risk.