mirror of
https://github.com/0glabs/0g-chain.git
synced 2024-11-10 18:15:19 +00:00
e1c11d411a
* rough auction type refactor * replace endTime type * split keeper file up * update store methods * move store methods to keeper.go * move nextAuctionID from params to genState * simplify auction type to not use pointers * add basic auction tests * update endblocker test * add payout to depositors feature * add more tests * move index updates to Get/Set for more safety * remove slightly unecessary ID type * remove unused message types * feat: add spec, update redundant type names * stop sending zero coins * use only one coins field in MsgPlaceBid * remove uncessary Auction interface methods * give auction types more accurate names * remove vuepress comments from spec * minor spec updates * update doc comments * add params validation * code cleanup, address review comments * resolve minor TODOs * sync spec with code Co-authored-by: Kevin Davis <karzak@users.noreply.github.com>
76 lines
3.0 KiB
Markdown
76 lines
3.0 KiB
Markdown
# State
|
|
|
|
## Parameters and genesis state
|
|
|
|
`Paramaters` define the rules according to which auctions are run. There is only one active parameter set at any given time. Updates to the parameter set can be made via on-chain parameter update proposals.
|
|
|
|
```go
|
|
// Params governance parameters for auction module
|
|
type Params struct {
|
|
MaxAuctionDuration time.Duration `json:"max_auction_duration" yaml:"max_auction_duration"` // max length of auction
|
|
MaxBidDuration time.Duration `json:"max_bid_duration" yaml:"max_bid_duration"` // additional time added to the auction end time after each bid, capped by the expiry.
|
|
}
|
|
```
|
|
|
|
`GenesisState` defines the state that must be persisted when the blockchain stops/restarts in order for normal function of the auction module to resume.
|
|
|
|
```go
|
|
// GenesisState - auction state that must be provided at genesis
|
|
type GenesisState struct {
|
|
NextAuctionID uint64 `json:"next_auction_id" yaml:"next_auction_id"` // auctionID that will be used for the next created auction
|
|
Params Params `json:"auction_params" yaml:"auction_params"` // auction params
|
|
Auctions Auctions `json:"genesis_auctions" yaml:"genesis_auctions"` // auctions currently in the store
|
|
}
|
|
```
|
|
|
|
## Base types
|
|
|
|
```go
|
|
// Auction is an interface to several types of auction.
|
|
type Auction interface {
|
|
GetID() uint64
|
|
WithID(uint64) Auction
|
|
GetEndTime() time.Time
|
|
}
|
|
|
|
// BaseAuction is a common type shared by all Auctions.
|
|
type BaseAuction struct {
|
|
ID uint64
|
|
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 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 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 is a type for storing some addresses and associated weights.
|
|
type WeightedAddresses struct {
|
|
Addresses []sdk.AccAddress
|
|
Weights []sdk.Int
|
|
}
|
|
|
|
// 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
|
|
}
|
|
```
|