update doc comments

This commit is contained in:
rhuairahrighairigh 2020-01-09 17:25:16 +00:00
parent fecfee5077
commit 2537928ee7
14 changed files with 75 additions and 81 deletions

View File

@ -4,7 +4,7 @@ import (
sdk "github.com/cosmos/cosmos-sdk/types"
)
// InitGenesis - initializes the store state from genesis data
// InitGenesis initializes the store state from genesis data.
func InitGenesis(ctx sdk.Context, keeper Keeper, data GenesisState) {
keeper.SetNextAuctionID(ctx, data.NextAuctionID)

View File

@ -9,7 +9,7 @@ import (
"github.com/kava-labs/kava/x/auction/types"
)
// StartSurplusAuction starts a normal auction that mints the sold coins.
// StartSurplusAuction starts a new surplus (forward) auction.
func (k Keeper) StartSurplusAuction(ctx sdk.Context, seller string, lot sdk.Coin, bidDenom string) (uint64, sdk.Error) {
// create auction
auction := types.NewSurplusAuction(seller, lot, bidDenom, ctx.BlockTime().Add(types.DefaultMaxAuctionDuration))
@ -27,7 +27,7 @@ func (k Keeper) StartSurplusAuction(ctx sdk.Context, seller string, lot sdk.Coin
return auctionID, nil
}
// StartDebtAuction starts an auction where sellers compete by offering decreasing prices.
// StartDebtAuction starts a new debt (reverse) auction.
func (k Keeper) StartDebtAuction(ctx sdk.Context, buyer string, bid sdk.Coin, initialLot sdk.Coin) (uint64, sdk.Error) {
// create auction
auction := types.NewDebtAuction(buyer, bid, initialLot, ctx.BlockTime().Add(types.DefaultMaxAuctionDuration))
@ -45,7 +45,7 @@ func (k Keeper) StartDebtAuction(ctx sdk.Context, buyer string, bid sdk.Coin, in
return auctionID, nil
}
// StartCollateralAuction starts an auction where bidders bid up to a maxBid, then switch to bidding down on price.
// StartCollateralAuction starts a new collateral (2-phase) auction where bidders bid up to a maxBid, then switch to bidding down on the Lot.
func (k Keeper) StartCollateralAuction(ctx sdk.Context, seller string, lot sdk.Coin, maxBid sdk.Coin, lotReturnAddrs []sdk.AccAddress, lotReturnWeights []sdk.Int) (uint64, sdk.Error) {
// create auction
weightedAddresses, err := types.NewWeightedAddresses(lotReturnAddrs, lotReturnWeights)
@ -111,6 +111,7 @@ func (k Keeper) PlaceBid(ctx sdk.Context, auctionID uint64, bidder sdk.AccAddres
return nil
}
// PlaceBidSurplus places a forward bid on a surplus auction, moving coins and returning the updated auction.
func (k Keeper) PlaceBidSurplus(ctx sdk.Context, a types.SurplusAuction, bidder sdk.AccAddress, bid sdk.Coin) (types.SurplusAuction, sdk.Error) {
// Validate New Bid
if bid.Denom != a.Bid.Denom {
@ -151,6 +152,7 @@ func (k Keeper) PlaceBidSurplus(ctx sdk.Context, a types.SurplusAuction, bidder
return a, nil
}
// PlaceForwardBidCollateral places a forward bid on a collateral auction, moving coins and returning the updated auction.
func (k Keeper) PlaceForwardBidCollateral(ctx sdk.Context, a types.CollateralAuction, bidder sdk.AccAddress, bid sdk.Coin) (types.CollateralAuction, sdk.Error) {
// Validate new bid
if bid.Denom != a.Bid.Denom {
@ -192,6 +194,7 @@ func (k Keeper) PlaceForwardBidCollateral(ctx sdk.Context, a types.CollateralAuc
return a, nil
}
// PlaceReverseBidCollateral places a reverse bid on a collateral auction, moving coins and returning the updated auction.
func (k Keeper) PlaceReverseBidCollateral(ctx sdk.Context, a types.CollateralAuction, bidder sdk.AccAddress, lot sdk.Coin) (types.CollateralAuction, sdk.Error) {
// Validate bid
if lot.Denom != a.Lot.Denom {
@ -239,6 +242,7 @@ func (k Keeper) PlaceReverseBidCollateral(ctx sdk.Context, a types.CollateralAuc
return a, nil
}
// PlaceBidDebt places a reverse bid on a debt auction, moving coins and returning the updated auction.
func (k Keeper) PlaceBidDebt(ctx sdk.Context, a types.DebtAuction, bidder sdk.AccAddress, lot sdk.Coin) (types.DebtAuction, sdk.Error) {
// Validate New Bid
if lot.Denom != a.Lot.Denom {
@ -307,6 +311,7 @@ func (k Keeper) CloseAuction(ctx sdk.Context, auctionID uint64) sdk.Error {
return nil
}
// PayoutDebtAuction pays out the proceeds for a debt auction, first minting the coins.
func (k Keeper) PayoutDebtAuction(ctx sdk.Context, a types.DebtAuction) sdk.Error {
err := k.supplyKeeper.MintCoins(ctx, a.Initiator, sdk.NewCoins(a.Lot))
if err != nil {
@ -319,6 +324,7 @@ func (k Keeper) PayoutDebtAuction(ctx sdk.Context, a types.DebtAuction) sdk.Erro
return nil
}
// PayoutSurplusAuction pays out the proceeds for a surplus auction.
func (k Keeper) PayoutSurplusAuction(ctx sdk.Context, a types.SurplusAuction) sdk.Error {
err := k.supplyKeeper.SendCoinsFromModuleToAccount(ctx, types.ModuleName, a.Bidder, sdk.NewCoins(a.Lot))
if err != nil {
@ -327,6 +333,7 @@ func (k Keeper) PayoutSurplusAuction(ctx sdk.Context, a types.SurplusAuction) sd
return nil
}
// PayoutCollateralAuction pays out the proceeds for a collateral auction.
func (k Keeper) PayoutCollateralAuction(ctx sdk.Context, a types.CollateralAuction) sdk.Error {
err := k.supplyKeeper.SendCoinsFromModuleToAccount(ctx, types.ModuleName, a.Bidder, sdk.NewCoins(a.Lot))
if err != nil {
@ -344,6 +351,7 @@ func earliestTime(t1, t2 time.Time) time.Time {
}
}
// splitCoinIntoWeightedBuckets divides up some amount of coins according to some weights.
func splitCoinIntoWeightedBuckets(coin sdk.Coin, buckets []sdk.Int) ([]sdk.Coin, sdk.Error) {
for _, bucket := range buckets {
if bucket.IsNegative() {

View File

@ -47,7 +47,7 @@ func (k Keeper) GetNextAuctionID(ctx sdk.Context) (uint64, sdk.Error) {
return types.Uint64FromBytes(bz), nil
}
// incrementNextAuctionID increments the global ID in the store by 1
// IncrementNextAuctionID increments the next auction ID in the store by 1.
func (k Keeper) IncrementNextAuctionID(ctx sdk.Context) sdk.Error {
id, err := k.GetNextAuctionID(ctx)
if err != nil {
@ -74,13 +74,12 @@ func (k Keeper) StoreNewAuction(ctx sdk.Context, auction types.Auction) (uint64,
return newAuctionID, nil
}
// SetAuction puts the auction into the database and adds it to the queue
// it overwrites any pre-existing auction with same ID
// SetAuction puts the auction into the store, and updates any indexes.
func (k Keeper) SetAuction(ctx sdk.Context, auction types.Auction) {
// remove the auction from the byTime index if it is already in there
existingAuction, found := k.GetAuction(ctx, auction.GetID())
if found {
k.RemoveFromIndex(ctx, existingAuction.GetEndTime(), existingAuction.GetID())
k.removeFromIndex(ctx, existingAuction.GetEndTime(), existingAuction.GetID())
}
// store auction
@ -89,10 +88,10 @@ func (k Keeper) SetAuction(ctx sdk.Context, auction types.Auction) {
store.Set(types.GetAuctionKey(auction.GetID()), bz)
// add to index
k.InsertIntoIndex(ctx, auction.GetEndTime(), auction.GetID())
k.insertIntoIndex(ctx, auction.GetEndTime(), auction.GetID())
}
// getAuction gets an auction from the store by auctionID
// GetAuction gets an auction from the store.
func (k Keeper) GetAuction(ctx sdk.Context, auctionID uint64) (types.Auction, bool) {
var auction types.Auction
@ -106,12 +105,12 @@ func (k Keeper) GetAuction(ctx sdk.Context, auctionID uint64) (types.Auction, bo
return auction, true
}
// DeleteAuction removes an auction from the store without any validation
// DeleteAuction removes an auction from the store, and any indexes.
func (k Keeper) DeleteAuction(ctx sdk.Context, auctionID uint64) {
// remove from index
auction, found := k.GetAuction(ctx, auctionID)
if found {
k.RemoveFromIndex(ctx, auction.GetEndTime(), auctionID)
k.removeFromIndex(ctx, auction.GetEndTime(), auctionID)
}
// delete auction
@ -119,14 +118,14 @@ func (k Keeper) DeleteAuction(ctx sdk.Context, auctionID uint64) {
store.Delete(types.GetAuctionKey(auctionID))
}
// InsertIntoIndex adds an auction ID and end time into the byTime index
func (k Keeper) InsertIntoIndex(ctx sdk.Context, endTime time.Time, auctionID uint64) {
// insertIntoIndex adds an auction ID and end time into the byTime index.
func (k Keeper) insertIntoIndex(ctx sdk.Context, endTime time.Time, auctionID uint64) {
store := prefix.NewStore(ctx.KVStore(k.storeKey), types.AuctionByTimeKeyPrefix)
store.Set(types.GetAuctionByTimeKey(endTime, auctionID), types.Uint64ToBytes(auctionID)) // TODO
store.Set(types.GetAuctionByTimeKey(endTime, auctionID), types.Uint64ToBytes(auctionID))
}
// RemoveFromIndex removes an auction ID and end time from the byTime index
func (k Keeper) RemoveFromIndex(ctx sdk.Context, endTime time.Time, auctionID uint64) {
// removeFromIndex removes an auction ID and end time from the byTime index.
func (k Keeper) removeFromIndex(ctx sdk.Context, endTime time.Time, auctionID uint64) {
store := prefix.NewStore(ctx.KVStore(k.storeKey), types.AuctionByTimeKeyPrefix)
store.Delete(types.GetAuctionByTimeKey(endTime, auctionID))
}
@ -143,7 +142,7 @@ func (k Keeper) IterateAuctionsByTime(ctx sdk.Context, inclusiveCutoffTime time.
defer iterator.Close()
for ; iterator.Valid(); iterator.Next() {
// TODO get the auction ID - either read from store, or extract from key
auctionID := types.Uint64FromBytes(iterator.Value())
if cb(auctionID) {

View File

@ -5,12 +5,10 @@ import (
"github.com/kava-labs/kava/x/auction/types"
)
// SetParams sets the auth module's parameters.
func (k Keeper) SetParams(ctx sdk.Context, params types.Params) {
k.paramSubspace.SetParamSet(ctx, &params)
}
// GetParams gets the auth module's parameters.
func (k Keeper) GetParams(ctx sdk.Context) (params types.Params) {
k.paramSubspace.GetParamSet(ctx, &params)
return

View File

@ -21,20 +21,20 @@ var (
_ module.AppModuleBasic = AppModuleBasic{}
)
// AppModuleBasic app module basics object
// AppModuleBasic implements the sdk.AppModuleBasic interface.
type AppModuleBasic struct{}
// Name get module name
// Name returns the module name.
func (AppModuleBasic) Name() string {
return ModuleName
}
// RegisterCodec register module codec
// RegisterCodec registers the module codec.
func (AppModuleBasic) RegisterCodec(cdc *codec.Codec) {
RegisterCodec(cdc)
}
// DefaultGenesis default genesis state
// DefaultGenesis returns the default genesis state.
func (AppModuleBasic) DefaultGenesis() json.RawMessage {
return ModuleCdc.MustMarshalJSON(DefaultGenesisState())
}
@ -64,7 +64,7 @@ func (AppModuleBasic) GetQueryCmd(cdc *codec.Codec) *cobra.Command {
return cli.GetQueryCmd(StoreKey, cdc)
}
// AppModule app module type
// AppModule implements the sdk.AppModule interface.
type AppModule struct {
AppModuleBasic
keeper Keeper
@ -78,11 +78,6 @@ func NewAppModule(keeper Keeper) AppModule {
}
}
// Name module name
func (AppModule) Name() string {
return ModuleName
}
// RegisterInvariants performs a no-op.
func (AppModule) RegisterInvariants(_ sdk.InvariantRegistry) {}

View File

@ -8,28 +8,28 @@ import (
"github.com/cosmos/cosmos-sdk/x/supply"
)
// Auction is an interface to several types of auction.
// Auction is an interface for handling common actions on auctions.
type Auction interface {
GetID() uint64
WithID(uint64) Auction
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.
}
// GetID getter for auction ID
// GetID is a getter for auction ID.
func (a BaseAuction) GetID() uint64 { return a.ID }
// GetEndTime getter for auction end time
// GetEndTime is a getter for auction end time.
func (a BaseAuction) GetEndTime() time.Time { return a.EndTime }
func (a BaseAuction) String() string {
@ -46,15 +46,15 @@ func (a BaseAuction) String() string {
)
}
// SurplusAuction type for forward auctions
// SurplusAuction is a forward auction that burns what it receives as bids.
type SurplusAuction struct {
BaseAuction
}
// WithID returns an auction with the ID set
// WithID returns an auction with the ID set.
func (a SurplusAuction) WithID(id uint64) Auction { a.ID = id; return a }
// NewSurplusAuction creates a new forward auction
// NewSurplusAuction returns a new surplus auction.
func NewSurplusAuction(seller string, lot sdk.Coin, bidDenom string, endTime time.Time) SurplusAuction {
auction := SurplusAuction{BaseAuction{
// no ID
@ -68,15 +68,15 @@ func NewSurplusAuction(seller string, lot sdk.Coin, bidDenom string, endTime tim
return auction
}
// DebtAuction type for reverse auctions
// DebtAuction is a reverse auction that mints what it pays out.
type DebtAuction struct {
BaseAuction
}
// WithID returns an auction with the ID set
// WithID returns an auction with the ID set.
func (a DebtAuction) WithID(id uint64) Auction { a.ID = id; return a }
// NewDebtAuction creates a new reverse auction
// NewDebtAuction returns a new debt auction.
func NewDebtAuction(buyerModAccName string, bid sdk.Coin, initialLot sdk.Coin, EndTime time.Time) DebtAuction {
// Note: Bidder is set to the initiator's module account address instead of module name. (when the first bid is placed, it is paid out to the initiator)
// Setting to the module account address bypasses calling supply.SendCoinsFromModuleToModule, instead calls SendCoinsFromModuleToAccount.
@ -93,16 +93,21 @@ func NewDebtAuction(buyerModAccName string, bid sdk.Coin, initialLot sdk.Coin, E
return auction
}
// 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 bidded down.
// Unsold Lot is sent to LotReturns, being divided among the addresses by weight.
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
}
// WithID returns an auction with the ID set
// WithID returns an auction with the ID set.
func (a CollateralAuction) WithID(id uint64) Auction { a.ID = id; return a }
// IsReversePhase returns whether the auction has switched over to reverse phase or not.
// Auction initially start in forward phase.
func (a CollateralAuction) IsReversePhase() bool {
return a.Bid.IsEqual(a.MaxBid)
}
@ -123,7 +128,7 @@ func (a CollateralAuction) String() string {
)
}
// NewCollateralAuction creates a new forward reverse auction
// NewCollateralAuction returns a new collateral auction.
func NewCollateralAuction(seller string, lot sdk.Coin, EndTime time.Time, maxBid sdk.Coin, lotReturns WeightedAddresses) CollateralAuction {
auction := CollateralAuction{
BaseAuction: BaseAuction{
@ -140,12 +145,13 @@ func NewCollateralAuction(seller string, lot sdk.Coin, EndTime time.Time, maxBid
return auction
}
// 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
}
// NewWeightedAddresses returns a new list addresses with weights.
func NewWeightedAddresses(addrs []sdk.AccAddress, weights []sdk.Int) (WeightedAddresses, sdk.Error) {
if len(addrs) != len(weights) {
return WeightedAddresses{}, sdk.ErrInternal("number of addresses doesn't match number of weights")

View File

@ -15,7 +15,6 @@ func init() {
func RegisterCodec(cdc *codec.Codec) {
cdc.RegisterConcrete(MsgPlaceBid{}, "auction/MsgPlaceBid", nil)
// Register the Auction interface and concrete types
cdc.RegisterInterface((*Auction)(nil), nil)
cdc.RegisterConcrete(SurplusAuction{}, "auction/SurplusAuction", nil)
cdc.RegisterConcrete(DebtAuction{}, "auction/DebtAuction", nil)

View File

@ -7,9 +7,6 @@ import (
// SupplyKeeper defines the expected supply Keeper
type SupplyKeeper interface {
//GetSupply(ctx sdk.Context) supplyexported.SupplyI
//GetModuleAddress(name string) sdk.AccAddress
GetModuleAccount(ctx sdk.Context, moduleName string) supplyexported.ModuleAccountI
SendCoinsFromModuleToModule(ctx sdk.Context, sender, recipient string, amt sdk.Coins) sdk.Error

View File

@ -4,17 +4,17 @@ import (
"bytes"
)
// Auctions type for an array of auctions
// Auctions is a slice of auctions.
type Auctions []Auction
// GenesisState - auction state that must be provided at genesis
// GenesisState is auction state that must be provided at chain genesis.
type GenesisState struct {
NextAuctionID uint64 `json:"next_auction_id" yaml:"next_auction_id"`
Params Params `json:"auction_params" yaml:"auction_params"`
NextAuctionID uint64 `json:"next_auction_id" yaml:"next_auction_id"`
Params Params `json:"auction_params" yaml:"auction_params"`
Auctions Auctions `json:"genesis_auctions" yaml:"genesis_auctions"`
}
// NewGenesisState returns a new genesis state object for auctions module
// NewGenesisState returns a new genesis state object for auctions module.
func NewGenesisState(nextID uint64, ap Params, ga Auctions) GenesisState {
return GenesisState{
NextAuctionID: nextID,
@ -23,24 +23,24 @@ func NewGenesisState(nextID uint64, ap Params, ga Auctions) GenesisState {
}
}
// DefaultGenesisState defines default genesis state for auction module
// DefaultGenesisState returns the default genesis state for auction module.
func DefaultGenesisState() GenesisState {
return NewGenesisState(0, DefaultParams(), Auctions{})
}
// Equal checks whether two GenesisState structs are equivalent
// Equal checks whether two GenesisState structs are equivalent.
func (data GenesisState) Equal(data2 GenesisState) bool {
b1 := ModuleCdc.MustMarshalBinaryBare(data)
b2 := ModuleCdc.MustMarshalBinaryBare(data2)
return bytes.Equal(b1, b2)
}
// IsEmpty returns true if a GenesisState is empty
// IsEmpty returns true if a GenesisState is empty.
func (data GenesisState) IsEmpty() bool {
return data.Equal(GenesisState{})
}
// ValidateGenesis validates genesis inputs. Returns error if validation of any input fails.
// ValidateGenesis validates genesis inputs. It returns error if validation of any input fails.
func ValidateGenesis(data GenesisState) error {
if err := data.Params.Validate(); err != nil {
return err

View File

@ -26,7 +26,7 @@ var (
AuctionKeyPrefix = []byte{0x00} // prefix for keys that store auctions
AuctionByTimeKeyPrefix = []byte{0x01} // prefix for keys that are part of the auctionsByTime index
NextAuctionIDKey = []byte{0x02}
NextAuctionIDKey = []byte{0x02} // key for the next auction id
)
func GetAuctionKey(auctionID uint64) []byte {
@ -37,12 +37,14 @@ func GetAuctionByTimeKey(endTime time.Time, auctionID uint64) []byte {
return append(sdk.FormatTimeBytes(endTime), Uint64ToBytes(auctionID)...)
}
// Uint64FromBytes converts some fixed length bytes back into a uint64.
func Uint64FromBytes(bz []byte) uint64 {
return binary.BigEndian.Uint64(bz)
}
// Uint64ToBytes converts a uint64 into fixed length bytes for use in store keys.
func Uint64ToBytes(id uint64) []byte {
bz := make([]byte, 8)
binary.BigEndian.PutUint64(bz, uint64(id))
return bz
}
}

View File

@ -8,8 +8,8 @@ var _ sdk.Msg = &MsgPlaceBid{}
// MsgPlaceBid is the message type used to place a bid on any type of auction.
type MsgPlaceBid struct {
AuctionID uint64
Bidder sdk.AccAddress // This can be a buyer (who increments bid), or a seller (who decrements lot) TODO rename to be clearer?
Amount sdk.Coin // The new bid or lot to set on the auction
Bidder sdk.AccAddress
Amount sdk.Coin // The new bid or lot to be set on the auction.
}
// NewMsgPlaceBid returns a new MsgPlaceBid.

View File

@ -25,13 +25,13 @@ var (
var _ subspace.ParamSet = &Params{}
// Params governance parameters for auction module
// Params is the governance parameters for the 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.
}
// NewParams creates a new Params object
// NewParams returns a new Params object.
func NewParams(maxAuctionDuration time.Duration, bidDuration time.Duration) Params {
return Params{
MaxAuctionDuration: maxAuctionDuration,
@ -39,7 +39,7 @@ func NewParams(maxAuctionDuration time.Duration, bidDuration time.Duration) Para
}
}
// DefaultParams default parameters for auctions
// DefaultParams returns the default parameters for auctions.
func DefaultParams() Params {
return NewParams(
DefaultMaxAuctionDuration,
@ -52,8 +52,7 @@ func ParamKeyTable() subspace.KeyTable {
return subspace.NewKeyTable().RegisterParamSet(&Params{})
}
// ParamSetPairs implements the ParamSet interface and returns all the key/value pairs
// pairs of auth module's parameters.
// ParamSetPairs implements the ParamSet interface and returns all the key/value pairs.
// nolint
func (ap *Params) ParamSetPairs() subspace.ParamSetPairs {
return subspace.ParamSetPairs{

View File

@ -1,9 +0,0 @@
package types
// Go doesn't have a built in min function for integers :(
func min(a, b int64) int64 {
if a < b {
return a
}
return b
}