Minor documentation updates to dutch auction wrapper

2 files changed, 26 insertions, 19 deletions

diff --git a/packages/contract-wrappers/test/dutch_auction_wrapper_test.ts b/packages/contract-wrappers/test/dutch_auction_wrapper_test.ts
index 4e6ad44e9..fb4eb10b4 100644
--- a/packages/contract-wrappers/test/dutch_auction_wrapper_test.ts
+++ b/packages/contract-wrappers/test/dutch_auction_wrapper_test.ts
@@ -21,7 +21,9 @@ const blockchainLifecycle = new BlockchainLifecycle(web3Wrapper);
 
 // tslint:disable:custom-no-magic-numbers
 describe('DutchAuctionWrapper', () => {
-    const fillableAmount = new BigNumber(2);
+    const makerAssetAmount = new BigNumber(5);
+    const auctionEndTakerAmount = new BigNumber(10);
+    const auctionBeginTakerAmount = auctionEndTakerAmount.times(2);
     const tenMinutesInSeconds = 10 * 60;
     let contractWrappers: ContractWrappers;
     let exchangeContractAddress: string;
@@ -35,9 +37,7 @@ describe('DutchAuctionWrapper', () => {
     let makerTokenAssetData: string;
     let takerTokenAssetData: string;
     let auctionBeginTimeSeconds: BigNumber;
-    let auctionBeginAmount: BigNumber;
     let auctionEndTimeSeconds: BigNumber;
-    let auctionEndAmount: BigNumber;
     before(async () => {
         // setup contract wrappers & addresses
         const contractAddresses = await migrateOnceAsync();
@@ -58,8 +58,6 @@ describe('DutchAuctionWrapper', () => {
             assetDataUtils.encodeERC20AssetData(takerTokenAddress),
         ];
         // setup auction details in maker asset data
-        auctionEndAmount = fillableAmount;
-        auctionBeginAmount = auctionEndAmount.times(2);
         const currentBlockTimestamp: number = await getLatestBlockTimestampAsync();
         auctionBeginTimeSeconds = new BigNumber(currentBlockTimestamp - tenMinutesInSeconds);
         auctionEndTimeSeconds = new BigNumber(currentBlockTimestamp + tenMinutesInSeconds);
@@ -73,14 +71,14 @@ describe('DutchAuctionWrapper', () => {
         );
         sellOrder = await dutchAuctionUtils.createSignedSellOrderAsync(
             auctionBeginTimeSeconds,
-            auctionBeginAmount,
-            auctionEndAmount,
             auctionEndTimeSeconds,
+            auctionBeginTakerAmount,
+            auctionEndTakerAmount,
+            makerAssetAmount,
             makerTokenAssetData,
             takerTokenAssetData,
             makerAddress,
             constants.NULL_ADDRESS,
-            auctionEndAmount,
         );
         buyOrder = await dutchAuctionUtils.createSignedBuyOrderAsync(sellOrder, takerAddress);
     });
@@ -119,7 +117,7 @@ describe('DutchAuctionWrapper', () => {
             expect(auctionDetails.beginTimeSeconds, 'auctionDetails.beginTimeSeconds').to.be.bignumber.equal(
                 auctionBeginTimeSeconds,
             );
-            expect(auctionDetails.beginAmount, 'auctionDetails.beginAmount').to.be.bignumber.equal(auctionBeginAmount);
+            expect(auctionDetails.beginAmount, 'auctionDetails.beginAmount').to.be.bignumber.equal(auctionBeginTakerAmount);
             expect(auctionDetails.endTimeSeconds, 'auctionDetails.endTimeSeconds').to.be.bignumber.equal(
                 auctionEndTimeSeconds,
             );
diff --git a/packages/contract-wrappers/test/utils/dutch_auction_utils.ts b/packages/contract-wrappers/test/utils/dutch_auction_utils.ts
index 766fc373a..380d0588c 100644
--- a/packages/contract-wrappers/test/utils/dutch_auction_utils.ts
+++ b/packages/contract-wrappers/test/utils/dutch_auction_utils.ts
@@ -24,31 +24,34 @@ export class DutchAuctionUtils {
     }
     public async createSignedSellOrderAsync(
         auctionBeginTimeSections: BigNumber,
-        auctionBeginAmount: BigNumber,
-        auctionEndAmount: BigNumber,
-        acutionEndTime: BigNumber,
+        acutionEndTimeSeconds: BigNumber,
+        auctionBeginTakerAssetAmount: BigNumber,
+        auctionEndTakerAssetAmount: BigNumber,
+        makerAssetAmount: BigNumber,
         makerAssetData: string,
         takerAssetData: string,
         makerAddress: string,
         takerAddress: string,
-        takerFillableAmount: BigNumber,
         senderAddress?: string,
         makerFee?: BigNumber,
         takerFee?: BigNumber,
         feeRecipientAddress?: string,
     ): Promise<SignedOrder> {
-        const makerAssetAmount = auctionEndAmount;
+        // Notes on sell order:
+        // - The `takerAssetAmount` is set to the `auctionEndTakerAssetAmount`, which is the lowest amount the 
+        //   the seller can expect to receive
+        // - The `makerAssetData` is overloaded to include the auction begin time and begin taker asset amount
         const makerAssetDataWithAuctionDetails = DutchAuctionWrapper.encodeDutchAuctionAssetData(
             makerAssetData,
             auctionBeginTimeSections,
-            auctionBeginAmount,
+            auctionBeginTakerAssetAmount,
         );
         const signedOrder = await orderFactory.createSignedOrderAsync(
             this._web3Wrapper.getProvider(),
             makerAddress,
             makerAssetAmount,
             makerAssetDataWithAuctionDetails,
-            takerFillableAmount,
+            auctionEndTakerAssetAmount,
             takerAssetData,
             this._exchangeAddress,
             {
@@ -57,7 +60,7 @@ export class DutchAuctionUtils {
                 makerFee,
                 takerFee,
                 feeRecipientAddress,
-                expirationTimeSeconds: acutionEndTime,
+                expirationTimeSeconds: acutionEndTimeSeconds,
             },
         );
         const erc20AssetData = assetDataUtils.decodeERC20AssetData(makerAssetData);
@@ -71,8 +74,15 @@ export class DutchAuctionUtils {
         makerFee?: BigNumber,
         takerFee?: BigNumber,
         feeRecipientAddress?: string,
+        expirationTimeSeconds?: BigNumber,
     ): Promise<SignedOrder> {
         const dutchAuctionData = DutchAuctionWrapper.decodeDutchAuctionData(sellOrder.makerAssetData);
+        // Notes on buy order:
+        // - The `makerAssetAmount` is set to `dutchAuctionData.beginAmount`, which is 
+        //   the highest amount the buyer would have to pay out at any point during the auction.
+        // - The `takerAssetAmount` is set to the seller's `makerAssetAmount`, as the buyer
+        //   receives the entire amount being sold by the seller.
+        // - The `makerAssetData`/`takerAssetData` are reversed from the sell order
         const signedOrder = await orderFactory.createSignedOrderAsync(
             this._web3Wrapper.getProvider(),
             buyerAddress,
@@ -86,7 +96,7 @@ export class DutchAuctionUtils {
                 makerFee,
                 takerFee,
                 feeRecipientAddress,
-                expirationTimeSeconds: sellOrder.expirationTimeSeconds,
+                expirationTimeSeconds,
             },
         );
         const buyerERC20AssetData = assetDataUtils.decodeERC20AssetData(sellOrder.takerAssetData);
@@ -135,7 +145,6 @@ export class DutchAuctionUtils {
         );
         const oldMakerAllowance = await erc20Token.allowance.callAsync(address, this._erc20ProxyAddress);
         const newMakerAllowance = oldMakerAllowance.plus(amount);
-
         const txHash = await erc20Token.approve.sendTransactionAsync(this._erc20ProxyAddress, newMakerAllowance, {
             from: address,
         });