Merge pull request #39 from jsertx/master

Add support to override blocknumber

Author: joshstevens19

README.md

@@ -219,6 +219,64 @@ console.log(results);
 }
 ```
 
+### specify call block number
+
+The multicall instance call method has an optional second argument of type [ContractCallOptions](src/models/contract-call-options.ts).
+
+One of the options is the blockNumber, so you can choose the height where you want the data from.
+
+It is compatible with both ethers and web3 providers.
+
+```ts
+import {
+  Multicall,
+  ContractCallResults,
+  ContractCallContext,
+} from 'ethereum-multicall';
+import Web3 from 'web3';
+
+const web3 = new Web3('https://some.local-or-remote.node:8546');
+
+const multicall = new Multicall({ web3Instance: web3, tryAggregate: true });
+
+const contractCallContext: ContractCallContext[] = [
+    {
+        reference: 'testContract',
+        contractAddress: '0x6795b15f3b16Cf8fB3E56499bbC07F6261e9b0C3',
+        abi: [ { name: 'foo', type: 'function', inputs: [ { name: 'example', type: 'uint256' } ], outputs: [ { name: 'amounts', type: 'uint256' }] } ],
+        calls: [{ reference: 'fooCall', methodName: 'foo', methodParameters: [42] }]
+    }
+];
+
+const results: ContractCallResults = await multicall.call(contractCallContext,{
+    blockNumber: '14571050'
+});
+console.log(results);
+
+// results: it will have the same block as requested
+{
+  results: {
+      testContract: {
+          originalContractCallContext:  {
+            reference: 'testContract',
+            contractAddress: '0x6795b15f3b16Cf8fB3E56499bbC07F6261e9b0C3',
+            abi: [ { name: 'foo', type: 'function', inputs: [ { name: 'example', type: 'uint256' } ], outputs: [ { name: 'amounts', type: 'uint256' }] } ],
+            calls: [{ reference: 'fooCall', methodName: 'foo', methodParameters: [42] }]
+          },
+          callsReturnContext: [{
+              returnValues: [{ amounts: BigNumber }],
+              decoded: true,
+              reference: 'fooCall',
+              methodName: 'foo',
+              methodParameters: [42],
+              success: true
+          }]
+      },
+  },
+  blockNumber: 14571050
+}
+```
+
 ### passing extra context to the call
 
 If you want store any context or state so you don't need to look back over arrays once you got the result back. it can be stored in `context` within `ContractCallContext`.

src/__TEST-SCRIPT__/playground.ts

@@ -60,6 +60,17 @@ const execute = async () => {
     context.results[contractCallContext.reference].callsReturnContext[0]
       .returnValues
   );
+  const latestBlock = await provider.getBlockNumber();
+  const blockNumber = `${latestBlock - 15}`;
+  const contextOnBlock: ContractCallResults = await multicall.call(
+    contractCallContext,
+    { blockNumber }
+  );
+  console.log({
+    latestBlock,
+    blockNumber,
+    resultBlock: contextOnBlock.blockNumber,
+  });
 };
 
 execute();

src/models/contract-call-options.ts

@@ -0,0 +1,3 @@
+export interface ContractCallOptions {
+  blockNumber?: string;
+}

src/models/index.ts

@@ -9,4 +9,6 @@ export { CallReturnContext } from './call-return-context';
 export { ContractCallContext } from './contract-call-context';
 export { ContractCallResults } from './contract-call-results';
 export { ContractCallReturnContext } from './contract-call-return-context';
+export { ContractCallOptions } from './contract-call-options';
+
 export * from './multicall-options';

src/multicall.ts

@@ -14,6 +14,7 @@ import {
   MulticallOptionsCustomJsonRpcProvider,
   MulticallOptionsEthers,
   MulticallOptionsWeb3,
+  ContractCallOptions,
 } from './models';
 import { Utils } from './utils';
 
@@ -134,14 +135,16 @@ export class Multicall {
    * @param calls The calls
    */
   public async call(
-    contractCallContexts: ContractCallContext[] | ContractCallContext
+    contractCallContexts: ContractCallContext[] | ContractCallContext,
+    contractCallOptions: ContractCallOptions = {}
   ): Promise<ContractCallResults> {
     if (!Array.isArray(contractCallContexts)) {
       contractCallContexts = [contractCallContexts];
     }
 
     const aggregateResponse = await this.execute(
-      this.buildAggregateCallContext(contractCallContexts)
+      this.buildAggregateCallContext(contractCallContexts),
+      contractCallOptions
     );
 
     const returnObject: ContractCallResults = {
@@ -215,7 +218,7 @@ export class Multicall {
             );
           } catch (e) {
             if (!this._options.tryAggregate) {
-              throw e
+              throw e;
             }
             returnObjectResult.callsReturnContext.push(
               Utils.deepClone<CallReturnContext>({
@@ -342,14 +345,15 @@ export class Multicall {
    * @param calls The calls
    */
   private async execute(
-    calls: AggregateCallContext[]
+    calls: AggregateCallContext[],
+    options: ContractCallOptions
   ): Promise<AggregateResponse> {
     switch (this._executionType) {
       case ExecutionType.web3:
-        return await this.executeWithWeb3(calls);
+        return await this.executeWithWeb3(calls, options);
       case ExecutionType.ethers:
       case ExecutionType.customHttp:
-        return await this.executeWithEthersOrCustom(calls);
+        return await this.executeWithEthersOrCustom(calls, options);
       default:
         throw new Error(`${this._executionType} is not defined`);
     }
@@ -360,22 +364,26 @@ export class Multicall {
    * @param calls The calls context
    */
   private async executeWithWeb3(
-    calls: AggregateCallContext[]
+    calls: AggregateCallContext[],
+    options: ContractCallOptions
   ): Promise<AggregateResponse> {
     const web3 = this.getTypedOptions<MulticallOptionsWeb3>().web3Instance;
     const networkId = await web3.eth.net.getId();
     const contract = new web3.eth.Contract(
       this.ABI,
       this.getContractBasedOnNetwork(networkId)
     );
-
+    const callParams = [];
+    if (options.blockNumber) {
+      callParams.push(options.blockNumber);
+    }
     if (this._options.tryAggregate) {
       const contractResponse = (await contract.methods
         .tryBlockAndAggregate(
           false,
           this.mapCallContextToMatchContractFormat(calls)
         )
-        .call()) as AggregateContractResponse;
+        .call(...callParams)) as AggregateContractResponse;
 
       contractResponse.blockNumber = BigNumber.from(
         contractResponse.blockNumber
@@ -385,7 +393,7 @@ export class Multicall {
     } else {
       const contractResponse = (await contract.methods
         .aggregate(this.mapCallContextToMatchContractFormat(calls))
-        .call()) as AggregateContractResponse;
+        .call(...callParams)) as AggregateContractResponse;
 
       contractResponse.blockNumber = BigNumber.from(
         contractResponse.blockNumber
@@ -400,7 +408,8 @@ export class Multicall {
    * @param calls The calls
    */
   private async executeWithEthersOrCustom(
-    calls: AggregateCallContext[]
+    calls: AggregateCallContext[],
+    options: ContractCallOptions
   ): Promise<AggregateResponse> {
     let ethersProvider = this.getTypedOptions<MulticallOptionsEthers>()
       .ethersProvider;
@@ -425,17 +434,25 @@ export class Multicall {
       this.ABI,
       ethersProvider
     );
-
+    let overrideOptions = {};
+    if (options.blockNumber) {
+      overrideOptions = {
+        ...overrideOptions,
+        blockTag: Number(options.blockNumber),
+      };
+    }
     if (this._options.tryAggregate) {
       const contractResponse = (await contract.callStatic.tryBlockAndAggregate(
         false,
-        this.mapCallContextToMatchContractFormat(calls)
+        this.mapCallContextToMatchContractFormat(calls),
+        overrideOptions
       )) as AggregateContractResponse;
 
       return this.buildUpAggregateResponse(contractResponse, calls);
     } else {
       const contractResponse = (await contract.callStatic.aggregate(
-        this.mapCallContextToMatchContractFormat(calls)
+        this.mapCallContextToMatchContractFormat(calls),
+        overrideOptions
       )) as AggregateContractResponse;
 
       return this.buildUpAggregateResponse(contractResponse, calls);