Minor documentation updates to dutch auction wrapper

packages/contract-addresses/CHANGELOG.json

@@ -3,7 +3,7 @@
         "version": "2.1.0",
         "changes": [
             {
-                "note": "Added entries for Dutch Auction contract",
+                "note": "Added testnet entries for Dutch Auction contract (kovan,rinkeby,ropsten)",
                 "pr": 1465
             }
         ]

packages/contract-wrappers/src/contract_wrappers/dutch_auction_wrapper.ts

@@ -47,9 +47,9 @@ export class DutchAuctionWrapper extends ContractWrapper {
         return dutchAuctionData;
     }
     /**
-     * Dutch auction details are encoded with the asset data for a 0x order. This function produces a hex
+     * Dutch auction details are encoded with the asset data for a 0x order. This function decodes a hex
      * encoded assetData string, containing information both about the asset being traded and the
-     * dutch auction; which is usable in the makerAssetData or takerAssetData fields in a 0x order.
+     * dutch auction.
      * @param dutchAuctionData Hex encoded assetData string for the asset being auctioned.
      * @return An object containing the auction asset, auction begin time and auction begin amount.
      */
@@ -97,8 +97,9 @@ export class DutchAuctionWrapper extends ContractWrapper {
      * Over time the price moves from beginAmount to endAmount given the current block.timestamp.
      * @param buyOrder      The Buyer's order. This order is for the current expected price of the auction.
      * @param sellOrder     The Seller's order. This order is for the lowest amount (at the end of the auction).
-     * @param from Address the transaction is being sent from.
+     * @param takerAddress  The user Ethereum address who would like to fill this order. Must be available via the supplied
-     * @return Transaction receipt with decoded logs.
+     *                      Provider provided at instantiation.
+     * @return              Transaction hash.
      */
     public async matchOrdersAsync(
         buyOrder: SignedOrder,
@@ -152,7 +153,7 @@ export class DutchAuctionWrapper extends ContractWrapper {
         return txHash;
     }
     /**
-     * Calculates the Auction Details for the given order
+     * Fetches the Auction Details for the given order
      * @param sellOrder The Seller's order. This order is for the lowest amount (at the end of the auction).
      * @return The dutch auction details.
      */

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,
             );

packages/contract-wrappers/test/utils/dutch_auction_utils.ts

@@ -24,31 +24,34 @@ export class DutchAuctionUtils {
     }
     public async createSignedSellOrderAsync(
         auctionBeginTimeSections: BigNumber,
-        auctionBeginAmount: BigNumber,
+        acutionEndTimeSeconds: BigNumber,
-        auctionEndAmount: BigNumber,
+        auctionBeginTakerAssetAmount: BigNumber,
-        acutionEndTime: 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,
         });