Merge pull request #161 from 0xProject/feature/defaultBlock

Add a possibility to specify defaultBlock when calling const blockchain methods

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+v0.15.0 - _September 8, 2017_
+------------------------
+    * Added the ability to specify a historical `blockNumber` at which to query the blockchain's state when calling a token or exchange method (#161)
+
 v0.14.2 - _September 7, 2017_
 ------------------------
     * Fixed an issue with bignumber.js types not found (#160)

src/contract_wrappers/exchange_wrapper.ts

@@ -27,6 +27,7 @@ import {
     LogFillContractEventArgs,
     LogCancelContractEventArgs,
     LogWithDecodedArgs,
+    MethodOpts,
 } from '../types';
 import {assert} from '../utils/assert';
 import {utils} from '../utils/utils';
@@ -85,27 +86,34 @@ export class ExchangeWrapper extends ContractWrapper {
      * subtracting the unavailable amount from the total order takerAmount.
      * @param   orderHash               The hex encoded orderHash for which you would like to retrieve the
      *                                  unavailable takerAmount.
+     * @param   methodOpts              Optional arguments this method accepts.
      * @return  The amount of the order (in taker tokens) that has either been filled or canceled.
      */
-    public async getUnavailableTakerAmountAsync(orderHash: string): Promise<BigNumber.BigNumber> {
+    public async getUnavailableTakerAmountAsync(orderHash: string,
+                                                methodOpts?: MethodOpts): Promise<BigNumber.BigNumber> {
         assert.doesConformToSchema('orderHash', orderHash, schemas.orderHashSchema);
 
         const exchangeContract = await this._getExchangeContractAsync();
-        let unavailableTakerTokenAmount = await exchangeContract.getUnavailableTakerTokenAmount.callAsync(orderHash);
+        const defaultBlock = _.isUndefined(methodOpts) ? undefined : methodOpts.defaultBlock;
+        let unavailableTakerTokenAmount = await exchangeContract.getUnavailableTakerTokenAmount.callAsync(
+            orderHash, defaultBlock,
+        );
         // Wrap BigNumbers returned from web3 with our own (later) version of BigNumber
         unavailableTakerTokenAmount = new BigNumber(unavailableTakerTokenAmount);
         return unavailableTakerTokenAmount;
     }
     /**
      * Retrieve the takerAmount of an order that has already been filled.
      * @param   orderHash    The hex encoded orderHash for which you would like to retrieve the filled takerAmount.
+     * @param   methodOpts   Optional arguments this method accepts.
      * @return  The amount of the order (in taker tokens) that has already been filled.
      */
-    public async getFilledTakerAmountAsync(orderHash: string): Promise<BigNumber.BigNumber> {
+    public async getFilledTakerAmountAsync(orderHash: string, methodOpts?: MethodOpts): Promise<BigNumber.BigNumber> {
         assert.doesConformToSchema('orderHash', orderHash, schemas.orderHashSchema);
 
         const exchangeContract = await this._getExchangeContractAsync();
-        let fillAmountInBaseUnits = await exchangeContract.filled.callAsync(orderHash);
+        const defaultBlock = _.isUndefined(methodOpts) ? undefined : methodOpts.defaultBlock;
+        let fillAmountInBaseUnits = await exchangeContract.filled.callAsync(orderHash, defaultBlock);
         // Wrap BigNumbers returned from web3 with our own (later) version of BigNumber
         fillAmountInBaseUnits = new BigNumber(fillAmountInBaseUnits);
         return fillAmountInBaseUnits;
@@ -114,13 +122,15 @@ export class ExchangeWrapper extends ContractWrapper {
      * Retrieve the takerAmount of an order that has been cancelled.
      * @param   orderHash    The hex encoded orderHash for which you would like to retrieve the
      *                       cancelled takerAmount.
+     * @param   methodOpts   Optional arguments this method accepts.
      * @return  The amount of the order (in taker tokens) that has been cancelled.
      */
-    public async getCanceledTakerAmountAsync(orderHash: string): Promise<BigNumber.BigNumber> {
+    public async getCanceledTakerAmountAsync(orderHash: string, methodOpts?: MethodOpts): Promise<BigNumber.BigNumber> {
         assert.doesConformToSchema('orderHash', orderHash, schemas.orderHashSchema);
 
         const exchangeContract = await this._getExchangeContractAsync();
-        let cancelledAmountInBaseUnits = await exchangeContract.cancelled.callAsync(orderHash);
+        const defaultBlock = _.isUndefined(methodOpts) ? undefined : methodOpts.defaultBlock;
+        let cancelledAmountInBaseUnits = await exchangeContract.cancelled.callAsync(orderHash, defaultBlock);
         // Wrap BigNumbers returned from web3 with our own (later) version of BigNumber
         cancelledAmountInBaseUnits = new BigNumber(cancelledAmountInBaseUnits);
         return cancelledAmountInBaseUnits;

src/contract_wrappers/token_wrapper.ts

@@ -17,6 +17,7 @@ import {
     CreateContractEvent,
     ContractEventEmitter,
     ContractEventObj,
+    MethodOpts,
 } from '../types';
 
 const ALLOWANCE_TO_ZERO_GAS_AMOUNT = 47155;
@@ -39,14 +40,17 @@ export class TokenWrapper extends ContractWrapper {
      * Retrieves an owner's ERC20 token balance.
      * @param   tokenAddress    The hex encoded contract Ethereum address where the ERC20 token is deployed.
      * @param   ownerAddress    The hex encoded user Ethereum address whose balance you would like to check.
+     * @param   methodOpts      Optional arguments this method accepts.
      * @return  The owner's ERC20 token balance in base units.
      */
-    public async getBalanceAsync(tokenAddress: string, ownerAddress: string): Promise<BigNumber.BigNumber> {
+    public async getBalanceAsync(tokenAddress: string, ownerAddress: string,
+                                 methodOpts?: MethodOpts): Promise<BigNumber.BigNumber> {
         assert.isETHAddressHex('ownerAddress', ownerAddress);
         assert.isETHAddressHex('tokenAddress', tokenAddress);
 
         const tokenContract = await this._getTokenContractAsync(tokenAddress);
-        let balance = await tokenContract.balanceOf.callAsync(ownerAddress);
+        const defaultBlock = _.isUndefined(methodOpts) ? undefined : methodOpts.defaultBlock;
+        let balance = await tokenContract.balanceOf.callAsync(ownerAddress, defaultBlock);
         // Wrap BigNumbers returned from web3 with our own (later) version of BigNumber
         balance = new BigNumber(balance);
         return balance;
@@ -104,14 +108,16 @@ export class TokenWrapper extends ContractWrapper {
      * @param   ownerAddress    The hex encoded user Ethereum address whose allowance to spenderAddress
      *                          you would like to retrieve.
      * @param   spenderAddress  The hex encoded user Ethereum address who can spend the allowance you are fetching.
+     * @param   methodOpts      Optional arguments this method accepts.
      */
     public async getAllowanceAsync(tokenAddress: string, ownerAddress: string,
-                                   spenderAddress: string): Promise<BigNumber.BigNumber> {
+                                   spenderAddress: string, methodOpts?: MethodOpts): Promise<BigNumber.BigNumber> {
         assert.isETHAddressHex('ownerAddress', ownerAddress);
         assert.isETHAddressHex('tokenAddress', tokenAddress);
 
         const tokenContract = await this._getTokenContractAsync(tokenAddress);
-        let allowanceInBaseUnits = await tokenContract.allowance.callAsync(ownerAddress, spenderAddress);
+        const defaultBlock = _.isUndefined(methodOpts) ? undefined : methodOpts.defaultBlock;
+        let allowanceInBaseUnits = await tokenContract.allowance.callAsync(ownerAddress, spenderAddress, defaultBlock);
         // Wrap BigNumbers returned from web3 with our own (later) version of BigNumber
         allowanceInBaseUnits = new BigNumber(allowanceInBaseUnits);
         return allowanceInBaseUnits;
@@ -120,13 +126,15 @@ export class TokenWrapper extends ContractWrapper {
      * Retrieves the owner's allowance in baseUnits set to the 0x proxy contract.
      * @param   tokenAddress    The hex encoded contract Ethereum address where the ERC20 token is deployed.
      * @param   ownerAddress    The hex encoded user Ethereum address whose proxy contract allowance we are retrieving.
+     * @param   methodOpts      Optional arguments this method accepts.
      */
-    public async getProxyAllowanceAsync(tokenAddress: string, ownerAddress: string): Promise<BigNumber.BigNumber> {
+    public async getProxyAllowanceAsync(tokenAddress: string, ownerAddress: string,
+                                        methodOpts?: MethodOpts): Promise<BigNumber.BigNumber> {
         assert.isETHAddressHex('ownerAddress', ownerAddress);
         assert.isETHAddressHex('tokenAddress', tokenAddress);
 
         const proxyAddress = await this._getProxyAddressAsync();
-        const allowanceInBaseUnits = await this.getAllowanceAsync(tokenAddress, ownerAddress, proxyAddress);
+        const allowanceInBaseUnits = await this.getAllowanceAsync(tokenAddress, ownerAddress, proxyAddress, methodOpts);
         return allowanceInBaseUnits;
     }
     /**

src/index.ts

@@ -33,4 +33,5 @@ export {
     TransactionReceiptWithDecodedLogs,
     LogWithDecodedArgs,
     DecodedLogArgs,
+    MethodOpts,
 } from './types';

src/types.ts

@@ -52,7 +52,7 @@ export interface ExchangeContract extends Web3.ContractInstance {
         callAsync: () => Promise<string>;
     };
     getUnavailableTakerTokenAmount: {
-        callAsync: (orderHash: string) => Promise<BigNumber.BigNumber>;
+        callAsync: (orderHash: string, defaultBlock?: Web3.BlockParam) => Promise<BigNumber.BigNumber>;
     };
     isRoundingError: {
         callAsync: (fillTakerAmount: BigNumber.BigNumber, takerTokenAmount: BigNumber.BigNumber,
@@ -119,10 +119,10 @@ export interface ExchangeContract extends Web3.ContractInstance {
                            v: number[], r: string[], s: string[], txOpts?: TxOpts) => Promise<number>;
     };
     filled: {
-        callAsync: (orderHash: string) => Promise<BigNumber.BigNumber>;
+        callAsync: (orderHash: string, defaultBlock?: Web3.BlockParam) => Promise<BigNumber.BigNumber>;
     };
     cancelled: {
-        callAsync: (orderHash: string) => Promise<BigNumber.BigNumber>;
+        callAsync: (orderHash: string, defaultBlock?: Web3.BlockParam) => Promise<BigNumber.BigNumber>;
     };
     getOrderHash: {
         callAsync: (orderAddresses: OrderAddresses, orderValues: OrderValues) => Promise<string>;
@@ -133,10 +133,11 @@ export interface TokenContract extends Web3.ContractInstance {
     Transfer: CreateContractEvent;
     Approval: CreateContractEvent;
     balanceOf: {
-        callAsync: (address: string) => Promise<BigNumber.BigNumber>;
+        callAsync: (address: string, defaultBlock?: Web3.BlockParam) => Promise<BigNumber.BigNumber>;
     };
     allowance: {
-        callAsync: (ownerAddress: string, allowedAddress: string) => Promise<BigNumber.BigNumber>;
+        callAsync: (ownerAddress: string, allowedAddress: string,
+                    defaultBlock?: Web3.BlockParam) => Promise<BigNumber.BigNumber>;
     };
     transfer: {
         sendTransactionAsync: (toAddress: string, amountInBaseUnits: BigNumber.BigNumber,
@@ -419,3 +420,13 @@ export interface Artifact {
         address: string;
     }};
 }
+
+/*
+ * defaultBlock: The block up to which to query the blockchain state. Setting this to a historical block number
+ * let's the user query the blockchain's state at an arbitrary point in time. In order for this to work, the
+ * backing  Ethereum node must keep the entire historical state of the chain (e.g setting `--pruning=archive`
+ * flag when  running Parity).
+ */
+export interface MethodOpts {
+    defaultBlock?: Web3.BlockParam;
+}