From 54aaee8e42dda50dc325451387b98c9f75bcb6ab Mon Sep 17 00:00:00 2001 From: Jacob Evans Date: Wed, 21 Nov 2018 16:34:38 +1100 Subject: chore: update documentation --- .../extensions/DutchAuction/DutchAuction.sol | 37 ++++++++++++++-------- .../contracts/test/extensions/dutch_auction.ts | 2 +- 2 files changed, 25 insertions(+), 14 deletions(-) (limited to 'packages') diff --git a/packages/contracts/contracts/extensions/DutchAuction/DutchAuction.sol b/packages/contracts/contracts/extensions/DutchAuction/DutchAuction.sol index a304184f1..225e33929 100644 --- a/packages/contracts/contracts/extensions/DutchAuction/DutchAuction.sol +++ b/packages/contracts/contracts/extensions/DutchAuction/DutchAuction.sol @@ -32,11 +32,11 @@ contract DutchAuction { IExchange internal EXCHANGE; struct AuctionDetails { - uint256 beginTimeSeconds; // Auction begin time in seconds - uint256 endTimeSeconds; // Auction end time in seconds - uint256 beginAmount; // Auction begin amount - uint256 endAmount; // Auction end amount - uint256 currentAmount; // Current auction amount at block.timestamp + uint256 beginTimeSeconds; // Auction begin time in seconds: sellOrder.makerAssetData + uint256 endTimeSeconds; // Auction end time in seconds: sellOrder.expiryTimeSeconds + uint256 beginAmount; // Auction begin amount: sellOrder.makerAssetData + uint256 endAmount; // Auction end amount: sellOrder.takerAssetAmount + uint256 currentAmount; // Calculated amount given block.timestamp uint256 currentTimeSeconds; // block.timestamp } @@ -46,14 +46,25 @@ contract DutchAuction { EXCHANGE = IExchange(_exchange); } - /// @dev Performs a match of the two orders at the amount given: the current block time, the auction - /// start time and the auction begin amount. - /// The Sellers order is a signed order at the lowest amount at the end of the auction. Excess from the match - /// is transferred to the seller. - /// @param buyOrder The Buyer's order - /// @param sellOrder The Seller's order - /// @param buySignature Proof that order was created by the left maker. - /// @param sellSignature Proof that order was created by the right maker. + /// @dev Matches the buy and sell orders at an amount given the following: the current block time, the auction + /// start time and the auction begin amount. The sell order is a an order at the lowest amount + /// at the end of the auction. Excess from the match is transferred to the seller. + /// Over time the price moves from beginAmount to endAmount given the current block.timestamp. + /// sellOrder.expiryTimeSeconds is the end time of the auction. + /// sellOrder.takerAssetAmount is the end amount of the auction (lowest possible amount). + /// sellOrder.makerAssetData is the ABI encoded Asset Proxy data with the following data appended + /// buyOrder.makerAssetData is the buyers bid on the auction, must meet the amount for the current block timestamp + /// (uint256 beginTimeSeconds, uint256 beginAmount). + /// This function reverts in the following scenarios: + /// * Auction has not started (auctionDetails.currentTimeSeconds < auctionDetails.beginTimeSeconds) + /// * Auction has expired (auctionDetails.endTimeSeconds < auctionDetails.currentTimeSeconds) + /// * Amount is invalid: Buy order amount is too low (buyOrder.makerAssetAmount < auctionDetails.currentAmount) + /// * Amount is invalid: Invalid begin amount (auctionDetails.beginAmount > auctionDetails.endAmount) + /// * Any failure in the 0x Match Orders + /// @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 buySignature Proof that order was created by the buyer. + /// @param sellSignature Proof that order was created by the seller. /// @return matchedFillResults amounts filled and fees paid by maker and taker of matched orders. function matchOrders( LibOrder.Order memory buyOrder, diff --git a/packages/contracts/test/extensions/dutch_auction.ts b/packages/contracts/test/extensions/dutch_auction.ts index dbd956c0f..207da6796 100644 --- a/packages/contracts/test/extensions/dutch_auction.ts +++ b/packages/contracts/test/extensions/dutch_auction.ts @@ -30,7 +30,7 @@ const blockchainLifecycle = new BlockchainLifecycle(web3Wrapper); const DECIMALS_DEFAULT = 18; const ZERO = Web3Wrapper.toBaseUnitAmount(new BigNumber(0), DECIMALS_DEFAULT); -describe.only(ContractName.DutchAuction, () => { +describe(ContractName.DutchAuction, () => { let makerAddress: string; let owner: string; let takerAddress: string; -- cgit v1.2.3