From 27f3e76da3cb90b2f7e2024e9a61151435ec882a Mon Sep 17 00:00:00 2001 From: rhuairahrighairigh Date: Fri, 10 Jan 2020 18:57:38 +0100 Subject: [PATCH] sync spec with code --- x/auction/spec/02_state.md | 28 +++++++++++++++++----------- x/auction/spec/05_params.md | 2 +- 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/x/auction/spec/02_state.md b/x/auction/spec/02_state.md index 075cf08c..306665f9 100644 --- a/x/auction/spec/02_state.md +++ b/x/auction/spec/02_state.md @@ -33,37 +33,43 @@ type Auction interface { GetEndTime() time.Time } -// BaseAuction type shared by all Auctions +// BaseAuction is a common type shared by all Auctions. type BaseAuction struct { ID uint64 - Initiator string // Module that starts the auction. Giving away Lot (aka seller in a forward auction). Restricted to being a module account name rather than any account. - Lot sdk.Coin // Amount of coins up being given by initiator (FA - amount for sale by seller, RA - cost of good by buyer (bid)) - Bidder sdk.AccAddress // Person who bids in the auction. Receiver of Lot. (aka buyer in forward auction, seller in RA) - Bid sdk.Coin // Amount of coins being given by the bidder (FA - bid, RA - amount being sold) - EndTime time.Time // Auction closing time. Triggers at the end of the block with time ≥ endTime (bids placed in that block are valid) // TODO ensure everything is consistent with this + Initiator string // Module name that starts the auction. Pays out Lot. + Lot sdk.Coin // Coins that will paid out by Initiator to the winning bidder. + Bidder sdk.AccAddress // Latest bidder. Receiver of Lot. + Bid sdk.Coin // Coins paid into the auction the bidder. + EndTime time.Time // Current auction closing time. Triggers at the end of the block with time ≥ EndTime. MaxEndTime time.Time // Maximum closing time. Auctions can close before this but never after. } -// SurplusAuction type for forward auctions +// SurplusAuction is a forward auction that burns what it receives from bids. +// It is normally used to sell off excess pegged asset acquired by the CDP system. type SurplusAuction struct { BaseAuction } -// DebtAuction type for reverse auctions +// DebtAuction is a reverse auction that mints what it pays out. +// It is normally used to acquire pegged asset to cover the CDP system's debts that were not covered by selling collateral. type DebtAuction struct { BaseAuction } -// WeightedAddresses type for storing an address and its associated weight +// WeightedAddresses is a type for storing some addresses and associated weights. type WeightedAddresses struct { Addresses []sdk.AccAddress Weights []sdk.Int } -// CollateralAuction type for forward reverse auction +// CollateralAuction is a two phase auction. +// Initially, in forward auction phase, bids can be placed up to a max bid. +// Then it switches to a reverse auction phase, where the initial amount up for auction is bid down. +// Unsold Lot is sent to LotReturns, being divided among the addresses by weight. +// Collateral auctions are normally used to sell off collateral seized from CDPs. type CollateralAuction struct { BaseAuction MaxBid sdk.Coin - LotReturns WeightedAddresses // return addresses to pay out reductions in the lot amount to. Lot is bid down during reverse phase. + LotReturns WeightedAddresses } ``` diff --git a/x/auction/spec/05_params.md b/x/auction/spec/05_params.md index f6751bc1..9a108303 100644 --- a/x/auction/spec/05_params.md +++ b/x/auction/spec/05_params.md @@ -5,4 +5,4 @@ The auction module contains the following parameters: | Key | Type | Example | | ------------------ | ---------------------- | -----------| | MaxAuctionDuration | string (time.Duration) | "48h0m0s" | -| MaxBidDuration | string (time.Duration) | "3h0m0s" | +| BidDuration | string (time.Duration) | "3h0m0s" |