Merge pull request #127 from 0xProject/shouldThrowOnInsufficientBalanceOrAllowance

Fix the docs for shouldThrowOnInsufficientBalanceOrAllowance

6 files changed, 49 insertions, 42 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a830106f6..9cdda5785 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,8 +1,9 @@
 # CHANGELOG
 
-v0.9.4 - _Aug 22, 2017_
+v0.9.4 - _TBD_
 ------------------------
     * Add clear error message when checksummed address is passed to a public method (#124)
+    * Fixes the description of `shouldThrowOnInsufficientBalanceOrAllowance` in docs (#127)
 
 v0.9.3 - _Aug 22, 2017_
 ------------------------
diff --git a/src/contract_wrappers/exchange_wrapper.ts b/src/contract_wrappers/exchange_wrapper.ts
index a324b8554..d5e272c12 100644
--- a/src/contract_wrappers/exchange_wrapper.ts
+++ b/src/contract_wrappers/exchange_wrapper.ts
@@ -137,8 +137,9 @@ export class ExchangeWrapper extends ContractWrapper {
      * Fills a signed order with an amount denominated in baseUnits of the taker token.
      * Since the order in which transactions are included in the next block is indeterminate, race-conditions
      * could arise where a users balance or allowance changes before the fillOrder executes. Because of this,
-     * we allow you to specify `shouldCheckTransfer`. If true, the smart contract will not throw if the parties
-     * do not have sufficient balances/allowances, preserving gas costs. Setting it to false forgoes this check
+     * we allow you to specify `shouldThrowOnInsufficientBalanceOrAllowance`.
+     * If false, the smart contract will not throw if the parties
+     * do not have sufficient balances/allowances, preserving gas costs. Setting it to true forgoes this check
      * and causes the smart contract to throw (using all the gas supplied) instead.
      * @param   signedOrder                                 An object that conforms to the SignedOrder interface.
      * @param   fillTakerTokenAmount                        The amount of the order (in taker tokens baseUnits) that
@@ -282,8 +283,9 @@ export class ExchangeWrapper extends ContractWrapper {
     /**
      * Batch version of fillOrderAsync.
      * Executes multiple fills atomically in a single transaction.
-     * If shouldCheckTransfer is set to true, it will continue filling subsequent orders even when earlier ones fail.
-     * When shouldCheckTransfer is set to false, if any fill fails, the entire batch fails.
+     * If shouldThrowOnInsufficientBalanceOrAllowance is set to true, it will continue filling subsequent orders even
+     * when earlier ones fail.
+     * When shouldThrowOnInsufficientBalanceOrAllowance is set to false, if any fill fails, the entire batch fails.
      * @param   orderFillRequests                               An array of objects that conform to the
      *                                                          OrderFillRequest interface.
      * @param   shouldThrowOnInsufficientBalanceOrAllowance     Whether or not you wish for the contract call to throw
diff --git a/test/exchange_wrapper_test.ts b/test/exchange_wrapper_test.ts
index 2f1b09ad2..a9c237d0e 100644
--- a/test/exchange_wrapper_test.ts
+++ b/test/exchange_wrapper_test.ts
@@ -165,7 +165,7 @@ describe('ExchangeWrapper', () => {
         let feeRecipient: string;
         const fillableAmount = new BigNumber(5);
         const fillTakerAmount = new BigNumber(5);
-        const shouldCheckTransfer = false;
+        const shouldThrowOnInsufficientBalanceOrAllowance = true;
         before(async () => {
             [coinbase, makerAddress, takerAddress, feeRecipient] = userAddresses;
             tokens = await zeroEx.tokenRegistry.getTokensAsync();
@@ -181,7 +181,7 @@ describe('ExchangeWrapper', () => {
                     );
                     const zeroFillAmount = new BigNumber(0);
                     return expect(zeroEx.exchange.fillOrderAsync(
-                        signedOrder, zeroFillAmount, shouldCheckTransfer, takerAddress,
+                        signedOrder, zeroFillAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                     )).to.be.rejectedWith(ExchangeContractErrs.OrderRemainingFillAmountZero);
                 });
                 it('should throw when sender is not a taker', async () => {
@@ -190,7 +190,7 @@ describe('ExchangeWrapper', () => {
                     );
                     const nonTakerAddress = userAddresses[6];
                     return expect(zeroEx.exchange.fillOrderAsync(
-                        signedOrder, fillTakerAmount, shouldCheckTransfer, nonTakerAddress,
+                        signedOrder, fillTakerAmount, shouldThrowOnInsufficientBalanceOrAllowance, nonTakerAddress,
                     )).to.be.rejectedWith(ExchangeContractErrs.TransactionSenderIsNotFillOrderTaker);
                 });
                 it('should throw when order is expired', async () => {
@@ -200,7 +200,7 @@ describe('ExchangeWrapper', () => {
                         fillableAmount, expirationInPast,
                     );
                     return expect(zeroEx.exchange.fillOrderAsync(
-                        signedOrder, fillTakerAmount, shouldCheckTransfer, takerAddress,
+                        signedOrder, fillTakerAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                     )).to.be.rejectedWith(ExchangeContractErrs.OrderFillExpired);
                 });
                 it('should throw when there a rounding error would have occurred', async () => {
@@ -212,7 +212,8 @@ describe('ExchangeWrapper', () => {
                     );
                     const fillTakerAmountThatCausesRoundingError = new BigNumber(3);
                     return expect(zeroEx.exchange.fillOrderAsync(
-                        signedOrder, fillTakerAmountThatCausesRoundingError, shouldCheckTransfer, takerAddress,
+                        signedOrder, fillTakerAmountThatCausesRoundingError,
+                        shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                     )).to.be.rejectedWith(ExchangeContractErrs.OrderFillRoundingError);
                 });
             });
@@ -230,7 +231,7 @@ describe('ExchangeWrapper', () => {
                     expect(await zeroEx.token.getBalanceAsync(takerTokenAddress, takerAddress))
                         .to.be.bignumber.equal(fillableAmount);
                     await zeroEx.exchange.fillOrderAsync(
-                        signedOrder, fillTakerAmount, shouldCheckTransfer, takerAddress);
+                        signedOrder, fillTakerAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress);
                     expect(await zeroEx.token.getBalanceAsync(makerTokenAddress, makerAddress))
                         .to.be.bignumber.equal(fillableAmount.minus(fillTakerAmount));
                     expect(await zeroEx.token.getBalanceAsync(takerTokenAddress, makerAddress))
@@ -246,7 +247,7 @@ describe('ExchangeWrapper', () => {
                     );
                     const partialFillAmount = new BigNumber(3);
                     await zeroEx.exchange.fillOrderAsync(
-                        signedOrder, partialFillAmount, shouldCheckTransfer, takerAddress);
+                        signedOrder, partialFillAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress);
                     expect(await zeroEx.token.getBalanceAsync(makerTokenAddress, makerAddress))
                         .to.be.bignumber.equal(fillableAmount.minus(partialFillAmount));
                     expect(await zeroEx.token.getBalanceAsync(takerTokenAddress, makerAddress))
@@ -262,7 +263,7 @@ describe('ExchangeWrapper', () => {
                     );
                     const partialFillAmount = new BigNumber(3);
                     const filledAmount = await zeroEx.exchange.fillOrderAsync(
-                        signedOrder, partialFillAmount, shouldCheckTransfer, takerAddress);
+                        signedOrder, partialFillAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress);
                     expect(filledAmount).to.be.bignumber.equal(partialFillAmount);
                 });
                 it('should return the partially filled amount \
@@ -272,7 +273,7 @@ describe('ExchangeWrapper', () => {
                     );
                     const partialFillAmount = new BigNumber(3);
                     await zeroEx.exchange.fillOrderAsync(
-                        signedOrder, partialFillAmount, shouldCheckTransfer, takerAddress);
+                        signedOrder, partialFillAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress);
                     const missingBalance = new BigNumber(1);
                     const totalBalance = partialFillAmount.plus(missingBalance);
                     await zeroEx.token.transferAsync(takerTokenAddress, coinbase, takerAddress, missingBalance);
@@ -281,7 +282,7 @@ describe('ExchangeWrapper', () => {
                     await zeroEx.token.setProxyAllowanceAsync(makerTokenAddress, makerAddress, totalBalance);
                     const remainingFillAmount = fillableAmount.minus(partialFillAmount);
                     const filledAmount = await zeroEx.exchange.fillOrderAsync(
-                        signedOrder, partialFillAmount, shouldCheckTransfer, takerAddress);
+                        signedOrder, partialFillAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress);
                     expect(filledAmount).to.be.bignumber.equal(remainingFillAmount);
                 });
                 it('should fill the valid orders with fees', async () => {
@@ -292,7 +293,7 @@ describe('ExchangeWrapper', () => {
                         makerAddress, takerAddress, fillableAmount, feeRecipient,
                     );
                     await zeroEx.exchange.fillOrderAsync(
-                        signedOrder, fillTakerAmount, shouldCheckTransfer, takerAddress);
+                        signedOrder, fillTakerAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress);
                     expect(await zeroEx.token.getBalanceAsync(zrxTokenAddress, feeRecipient))
                         .to.be.bignumber.equal(makerFee.plus(takerFee));
                 });
@@ -326,10 +327,12 @@ describe('ExchangeWrapper', () => {
             });
             describe('successful batch fills', () => {
                 it('should no-op for an empty batch', async () => {
-                    await zeroEx.exchange.batchFillOrdersAsync([], shouldCheckTransfer, takerAddress);
+                    await zeroEx.exchange.batchFillOrdersAsync(
+                        [], shouldThrowOnInsufficientBalanceOrAllowance, takerAddress);
                 });
                 it('should successfully fill multiple orders', async () => {
-                    await zeroEx.exchange.batchFillOrdersAsync(orderFillBatch, shouldCheckTransfer, takerAddress);
+                    await zeroEx.exchange.batchFillOrdersAsync(
+                        orderFillBatch, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress);
                     const filledAmount = await zeroEx.exchange.getFilledTakerAmountAsync(signedOrderHashHex);
                     const anotherFilledAmount = await zeroEx.exchange.getFilledTakerAmountAsync(anotherOrderHashHex);
                     expect(filledAmount).to.be.bignumber.equal(fillTakerAmount);
@@ -357,11 +360,12 @@ describe('ExchangeWrapper', () => {
             });
             describe('successful batch fills', () => {
                 it('should no-op for an empty batch', async () => {
-                    await zeroEx.exchange.fillOrdersUpToAsync([], fillUpToAmount, shouldCheckTransfer, takerAddress);
+                    await zeroEx.exchange.fillOrdersUpToAsync(
+                        [], fillUpToAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress);
                 });
                 it('should successfully fill up to specified amount', async () => {
                     await zeroEx.exchange.fillOrdersUpToAsync(
-                        signedOrders, fillUpToAmount, shouldCheckTransfer, takerAddress,
+                        signedOrders, fillUpToAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                     );
                     const filledAmount = await zeroEx.exchange.getFilledTakerAmountAsync(signedOrderHashHex);
                     const anotherFilledAmount = await zeroEx.exchange.getFilledTakerAmountAsync(anotherOrderHashHex);
@@ -371,7 +375,7 @@ describe('ExchangeWrapper', () => {
                 });
                 it('should return filled amount', async () => {
                     const filledTakerTokenAmount = await zeroEx.exchange.fillOrdersUpToAsync(
-                        signedOrders, fillUpToAmount, shouldCheckTransfer, takerAddress,
+                        signedOrders, fillUpToAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                     );
                     expect(filledTakerTokenAmount).to.be.bignumber.equal(fillUpToAmount);
                 });
@@ -554,7 +558,7 @@ describe('ExchangeWrapper', () => {
     });
     describe('#subscribeAsync', () => {
         const indexFilterValues = {};
-        const shouldCheckTransfer = false;
+        const shouldThrowOnInsufficientBalanceOrAllowance = true;
         let makerTokenAddress: string;
         let takerTokenAddress: string;
         let coinbase: string;
@@ -600,7 +604,7 @@ describe('ExchangeWrapper', () => {
                     done();
                 });
                 await zeroEx.exchange.fillOrderAsync(
-                    signedOrder, fillTakerAmountInBaseUnits, shouldCheckTransfer, takerAddress,
+                    signedOrder, fillTakerAmountInBaseUnits, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                 );
             })().catch(done);
         });
@@ -640,7 +644,7 @@ describe('ExchangeWrapper', () => {
                     done();
                 });
                 await zeroEx.exchange.fillOrderAsync(
-                    signedOrder, fillTakerAmountInBaseUnits, shouldCheckTransfer, takerAddress,
+                    signedOrder, fillTakerAmountInBaseUnits, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                 );
             })().catch(done);
         });
@@ -654,7 +658,7 @@ describe('ExchangeWrapper', () => {
                 });
                 await eventSubscriptionToBeStopped.stopWatchingAsync();
                 await zeroEx.exchange.fillOrderAsync(
-                    signedOrder, fillTakerAmountInBaseUnits, shouldCheckTransfer, takerAddress,
+                    signedOrder, fillTakerAmountInBaseUnits, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                 );
                 done();
             })().catch(done);
@@ -673,7 +677,7 @@ describe('ExchangeWrapper', () => {
                     done();
                 });
                 await zeroEx.exchange.fillOrderAsync(
-                    signedOrder, fillTakerAmountInBaseUnits, shouldCheckTransfer, takerAddress,
+                    signedOrder, fillTakerAmountInBaseUnits, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                 );
             })().catch(done);
         });
diff --git a/test/order_validation_test.ts b/test/order_validation_test.ts
index 773a23aa7..826b44077 100644
--- a/test/order_validation_test.ts
+++ b/test/order_validation_test.ts
@@ -30,7 +30,7 @@ describe('OrderValidationUtils', () => {
     let feeRecipient: string;
     const fillableAmount = new BigNumber(5);
     const fillTakerAmount = new BigNumber(5);
-    const shouldCheckTransfer = true;
+    const shouldThrowOnInsufficientBalanceOrAllowance = false;
     before(async () => {
         web3 = web3Factory.create();
         zeroEx = new ZeroEx(web3.currentProvider);
@@ -66,7 +66,7 @@ describe('OrderValidationUtils', () => {
                     takerTokenAddress, takerAddress, coinbase, balanceToSubtractFromMaker,
                 );
                 return expect(zeroEx.exchange.fillOrderAsync(
-                    signedOrder, fillTakerAmount, shouldCheckTransfer, takerAddress,
+                    signedOrder, fillTakerAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                 )).to.be.rejectedWith(ExchangeContractErrs.InsufficientTakerBalance);
             });
             it('should throw when taker allowance is less than fill amount', async () => {
@@ -74,7 +74,7 @@ describe('OrderValidationUtils', () => {
                 await zeroEx.token.setProxyAllowanceAsync(takerTokenAddress, takerAddress,
                     newAllowanceWhichIsLessThanFillAmount);
                 return expect(zeroEx.exchange.fillOrderAsync(
-                    signedOrder, fillTakerAmount, shouldCheckTransfer, takerAddress,
+                    signedOrder, fillTakerAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                 )).to.be.rejectedWith(ExchangeContractErrs.InsufficientTakerAllowance);
             });
             it('should throw when maker balance is less than maker fill amount', async () => {
@@ -82,7 +82,7 @@ describe('OrderValidationUtils', () => {
                     makerTokenAddress, makerAddress, coinbase, balanceToSubtractFromMaker,
                 );
                 return expect(zeroEx.exchange.fillOrderAsync(
-                    signedOrder, fillTakerAmount, shouldCheckTransfer, takerAddress,
+                    signedOrder, fillTakerAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                 )).to.be.rejectedWith(ExchangeContractErrs.InsufficientMakerBalance);
             });
             it('should throw when maker allowance is less than maker fill amount', async () => {
@@ -90,7 +90,7 @@ describe('OrderValidationUtils', () => {
                 await zeroEx.token.setProxyAllowanceAsync(makerTokenAddress, makerAddress,
                     newAllowanceWhichIsLessThanFillAmount);
                 return expect(zeroEx.exchange.fillOrderAsync(
-                    signedOrder, fillTakerAmount, shouldCheckTransfer, takerAddress,
+                    signedOrder, fillTakerAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                 )).to.be.rejectedWith(ExchangeContractErrs.InsufficientMakerAllowance);
             });
         });
@@ -110,7 +110,7 @@ describe('OrderValidationUtils', () => {
                     zrxTokenAddress, makerAddress, coinbase, balanceToSubtractFromMaker,
                 );
                 return expect(zeroEx.exchange.fillOrderAsync(
-                    signedOrder, fillTakerAmount, shouldCheckTransfer, takerAddress,
+                    signedOrder, fillTakerAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                 )).to.be.rejectedWith(ExchangeContractErrs.InsufficientMakerFeeBalance);
             });
             it('should throw when maker doesn\'t have enough allowance to pay fees', async () => {
@@ -118,7 +118,7 @@ describe('OrderValidationUtils', () => {
                 await zeroEx.token.setProxyAllowanceAsync(zrxTokenAddress, makerAddress,
                     newAllowanceWhichIsLessThanFees);
                 return expect(zeroEx.exchange.fillOrderAsync(
-                    signedOrder, fillTakerAmount, shouldCheckTransfer, takerAddress,
+                    signedOrder, fillTakerAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                 )).to.be.rejectedWith(ExchangeContractErrs.InsufficientMakerFeeAllowance);
             });
             it('should throw when taker doesn\'t have enough balance to pay fees', async () => {
@@ -127,7 +127,7 @@ describe('OrderValidationUtils', () => {
                     zrxTokenAddress, takerAddress, coinbase, balanceToSubtractFromTaker,
                 );
                 return expect(zeroEx.exchange.fillOrderAsync(
-                    signedOrder, fillTakerAmount, shouldCheckTransfer, takerAddress,
+                    signedOrder, fillTakerAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                 )).to.be.rejectedWith(ExchangeContractErrs.InsufficientTakerFeeBalance);
             });
             it('should throw when taker doesn\'t have enough allowance to pay fees', async () => {
@@ -135,7 +135,7 @@ describe('OrderValidationUtils', () => {
                 await zeroEx.token.setProxyAllowanceAsync(zrxTokenAddress, takerAddress,
                     newAllowanceWhichIsLessThanFees);
                 return expect(zeroEx.exchange.fillOrderAsync(
-                    signedOrder, fillTakerAmount, shouldCheckTransfer, takerAddress,
+                    signedOrder, fillTakerAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                 )).to.be.rejectedWith(ExchangeContractErrs.InsufficientTakerFeeAllowance);
             });
         });
@@ -156,7 +156,7 @@ describe('OrderValidationUtils', () => {
                     zrxTokenAddress, makerAddress, coinbase, balanceToSubtractFromMaker,
                 );
                 return expect(zeroEx.exchange.fillOrderAsync(
-                    signedOrder, fillTakerAmount, shouldCheckTransfer, takerAddress,
+                    signedOrder, fillTakerAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                 )).to.be.rejectedWith(ExchangeContractErrs.InsufficientMakerBalance);
             });
             it('should throw on insufficient allowance when makerToken is ZRX', async () => {
@@ -165,7 +165,7 @@ describe('OrderValidationUtils', () => {
                 await zeroEx.token.setProxyAllowanceAsync(
                     zrxTokenAddress, makerAddress, newAllowanceWhichIsInsufficient);
                 return expect(zeroEx.exchange.fillOrderAsync(
-                    signedOrder, fillTakerAmount, shouldCheckTransfer, takerAddress,
+                    signedOrder, fillTakerAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                 )).to.be.rejectedWith(ExchangeContractErrs.InsufficientMakerAllowance);
             });
         });
@@ -186,7 +186,7 @@ describe('OrderValidationUtils', () => {
                     zrxTokenAddress, takerAddress, coinbase, balanceToSubtractFromTaker,
                 );
                 return expect(zeroEx.exchange.fillOrderAsync(
-                    signedOrder, fillTakerAmount, shouldCheckTransfer, takerAddress,
+                    signedOrder, fillTakerAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                 )).to.be.rejectedWith(ExchangeContractErrs.InsufficientTakerBalance);
             });
             it('should throw on insufficient allowance when takerToken is ZRX', async () => {
@@ -195,7 +195,7 @@ describe('OrderValidationUtils', () => {
                 await zeroEx.token.setProxyAllowanceAsync(
                     zrxTokenAddress, takerAddress, newAllowanceWhichIsInsufficient);
                 return expect(zeroEx.exchange.fillOrderAsync(
-                    signedOrder, fillTakerAmount, shouldCheckTransfer, takerAddress,
+                    signedOrder, fillTakerAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress,
                 )).to.be.rejectedWith(ExchangeContractErrs.InsufficientTakerAllowance);
             });
         });
diff --git a/test/token_wrapper_test.ts b/test/token_wrapper_test.ts
index 8c680b754..8adaa6351 100644
--- a/test/token_wrapper_test.ts
+++ b/test/token_wrapper_test.ts
@@ -284,7 +284,7 @@ describe('TokenWrapper', () => {
     });
     describe('#subscribeAsync', () => {
         const indexFilterValues = {};
-        const shouldCheckTransfer = false;
+        const shouldThrowOnInsufficientBalanceOrAllowance = true;
         let tokenAddress: string;
         const subscriptionOpts: SubscriptionOpts = {
             fromBlock: 0,
diff --git a/test/utils/fill_scenarios.ts b/test/utils/fill_scenarios.ts
index bebf82fd8..563415a48 100644
--- a/test/utils/fill_scenarios.ts
+++ b/test/utils/fill_scenarios.ts
@@ -61,8 +61,8 @@ export class FillScenarios {
             makerTokenAddress, takerTokenAddress, makerAddress, takerAddress,
             fillableAmount, fillableAmount,
         );
-        const shouldCheckTransfer = false;
-        await this.zeroEx.exchange.fillOrderAsync(signedOrder, partialFillAmount, shouldCheckTransfer, takerAddress);
+        const shouldThrowOnInsufficientBalanceOrAllowance = false;
+        await this.zeroEx.exchange.fillOrderAsync(signedOrder, partialFillAmount, shouldThrowOnInsufficientBalanceOrAllowance, takerAddress);
         return signedOrder;
     }
     private async createAsymmetricFillableSignedOrderWithFeesAsync(