Auction
Introduction
The Auction ADO is a smart contract that allows performing custom auctions on NFTs. NFTs can be sent to this contract with the required messages to start an auction on it. Once the auction has started, users can place bids on the token until the auction expires. The highest bid will win the auction, sending the funds to the seller and receiving the token in return.
There are multiple ways to customize this ADO:
Authorized: Only the NFT contracts sepcified at instantiation are allowed to send NFTs to this Auction ADO.
Open: This means that any NFT contract is allowed to send an NFT to this ADO to be auctioned. To have the Auction ADO be open, do not specify
authorized_token_addresses
in instantiation.
Bidding on the NFT can also be customized to work with one of the following options:
Native: By specifying the denom of the chain in the StartAuction message.
CW20: By specifying the contract address of the CW20 token to be used in the StartAuction. The CW20 tokens allowed to be set as the bidding token can be restricted by specifying
authorized_cw20_address
at instantiation. If this is not specified, then any CW20 token can be set.
Ado_type: auction
Version: 2.2.5
InstantiateMsg
pub struct InstantiateMsg {
pub authorized_token_addresses: Option<Vec<AndrAddr>>,
pub authorized_cw20_address: Option<AndrAddr>,
pub kernel_address: String,
pub owner: Option<String>,
}
authorized_token_addresses
Optional set of CW721 contract addresses to be allowed to send NFTs to the Auction ADO. If not specified, then any CW721 can send NFTs to the auction.
authorized_cw20_address
Optional CW20 address to authorize to be used as the purchasing coin for the NFTs in auction. If not specified, then any CW20 can be set as the purchasing coin.
kernel_address
String
owner
Option<String>
Optional address to specify as the owner of the ADO being created. Defaults to the sender if not specified.
ExecuteMsg
ReceiveNft
Receives a token from a SendNft
and starts an auction based on the given parameters in the StartAuction
struct.
The auction information can be modified before it has started but is immutable after that.
Only the NFT owner can send the NFT and start the auction.
This message is not called by the user on this ADO, but is the case that handles receiving NFTs from a CW721 ADO.
pub struct Cw721ReceiveMsg {
pub sender: String,
pub token_id: String,
pub msg: Binary,
}
pub enum ExecuteMsg {
ReceiveNft(Cw721ReceiveMsg)
}
In order to start an auction you need to define the message of the Cw721ReceiveMsg
as a Cw721HookMsg
.
StartAuction
Starts an auction sale on the sent NFT.
You need to get the base64 encoded representation of the JSON message and attach it as the msg
when sending.
start_time
should not be a time in the past.
pub enum Cw721HookMsg {
StartAuction {
start_time: Option<Expiry>,
end_time: Expiry,
coin_denom: Asset,
buy_now_price: Option<Uint128>,
min_bid: Option<Uint128>,
min_raise: Option<Uint128>,
whitelist: Option<Vec<Addr>>,
recipient: Option<Recipient>,
}
}
start_time
Optional start time for the sale specified in milliseconds. Defaults to immediately if not specified.
end_time
The time for the auction to end. Can be specified as a duration from the start or an absolute timestamp. Both specified in milliseconds.
coin_denom
The coin denomination to be used to bid on the NFT. Can be either a native coin ie."uandr" or a CW20 token address ie. "andr1..."
buy_now_price
Option<Uint128>
An optional price that can be set that allows users to immediately purchase the NFT if they provide the specified amount.
min_bid
Option<Uint128>
The minimum starting bid that can be placed on the auctioned token.
min_raise
Option<Uint128>
Optional amount that specifies the minimum increase in bidding for a bid to be accepted. For example, if we set it at 25 and the current bid is 100, then the next bid needs to be at least 125 to be accepted.
whitelist
Option<Vec<Addr>>
Optional list of addresses to whitelist for the auction. If None, auction is public.
recipient
An optional recipient to receive the sale funds for the sold NFT.
Receive
Receives tokens from a CW20 Send message to be used as a bid on the NFT auction.
This message is not called by the user on this ADO, but is the case that handles receiving CW20 tokens from a CW20 ADO.
pub struct Cw20ReceiveMsg {
pub sender: String,
pub amount: Uint128,
pub msg: Binary,
}
pub enum ExecuteMsg {
Receive(Cw20ReceiveMsg),
}
In order to bid on an auction using a CW20, you need to define the message of the Cw20ReceiveMsg
as a Cw721HookMsg
.
PlaceBid (CW20)
You need to get the base64 encoded representation of the JSON message and attach it as the msg
field for the CW20 Send message.
The following criteria must be met for the bid to be placed:
The NFT is currently under auction
The sender's bid is higher than the highest bid
The sender does not currently hold the highest bid
The sender is not the token owner
pub enum Cw20HookMsg {
PlaceBid {
token_id: String,
token_address: String,
},
}
token_id
String
The token id of the NFT you want to place a bid on.
token_address
String
The address of the NFT contract the NFT belongs to.
AuthorizeContract
Authorize a CW721 or CW20 contract to send tokens to this ADO.
Only available to the contract owner.
CW721 is used to send NFTs to be sold, and CW20 is used to send tokens to be used in sales.
For CW721, the action should be specified as "send_nft".
For CW20, the action should be specified as "send_cw20".
pub enum ExecuteMsg {
AuthorizeContract {
action: PermissionAction,
addr: AndrAddr,
expiration: Option<Expiry>,
},
}
action
The action to authorize the specified address to do.
addr
The contract address of the CW721 (NFT) contract to authorize.
expiration
An optional expiration for the permission.
PermissionAction
#[cw_serde]
pub enum PermissionAction {
SendCw20,
SendNft,
}
SendCw20: Used in case the ADO to authorize/deauthorize is a CW20 ADO.
SendNFT: Used in case the ADO to authorize/deauthorize is a CW721 ADO.
DeauthorizeContract
Removes authorization from a CW721 or CW20 contract to send tokens to the auction.
Only available to the contract owner.
For CW721, the action should be specified as "send_nft".
For CW20, the action should be specified as "send_cw20".
pub enum ExecuteMsg {
DeauthorizeContract {
action: PermissionAction,
addr: AndrAddr,
},
}
action
The action to deauthorize the specified address to do.
addr
The contract address of the CW721 (NFT) contract to remove authorization for.
UpdateAuction
Updates the information of an auction.
Only the owner of the auction can execute UpdateAuction
.
An auction can be updated only if it has not started yet.
pub enum ExecuteMsg {
UpdateAuction {
token_id: String,
token_address: String,
start_time: Option<Expiry>,
end_time: Expiry,
coin_denom: Asset,
min_bid: Option<Uint128>,
min_raise: Option<Uint128>,
whitelist: Option<Vec<Addr>>,
recipient: Option<Recipient>,
}
}
start_time
should not be a time in the past.
token_id
String
The Id of the NFT that is being auctioned.
token_address
String
The address of the NFT contract.
start_time
Start time in milliseconds. If not specified, then the auction will start immediately.
end_time
The time for the auction to end. Can be specified as a duration from the start or an absolute timestamp. Both specified in milliseconds.
coin_denom
The coin denomination to be used to bid on the NFT. Can be either a native coin ie."uandr" or a CW20 token address ie. "andr1..."
min_bid
Option<Uint128>
The minimum starting bid that can be placed on the auctioned token.
min_raise
Option<Uint128>
Optional amount that specifies the minimum increase in bidding for a bid to be accepted. For example, if we set it at 25 and the current bid is 100, then the next bid needs to be.
whitelist
Option<Vec<Addr>>
Optional list of addresses to whitelist for the auction. If None, auction is public.
recipient
An optional recipient to receive the sale funds for the sold NFT.
CancelAuction
Only the owner of the auction can execute CancelAuction
.
Cancels the auction of a token.
pub enum ExecuteMsg {
CancelAuction {
token_id: String,
token_address: String,
}
}
token_id
String
The Id of the NFT in the auction to be cancelled.
token_address
String
The address of the NFT contract.
PlaceBid
Places a bid for the auction for the given NFT Id. The bid must be sent as native funds along with this message. The previous largest bid gets automatically sent back to the bidder when they are outbid.
The following criteria must be met for the bid to be placed:
The NFT is currently under auction
The sender's bid is higher than the highest bid
The sender does not currently hold the highest bid
The sender is not the token owner
pub enum ExecuteMsg {
PlaceBid {
token_id: String,
token_address:String,
}
}
token_id
String
The Id of the NFT to place a bid on.
token_address
String
The address of the NFT contract.
Claim
Sends the winner of the auction the NFT and the funds to the NFT owner when the auction has finished. Anyone is allowed to execute this message.
Can only be done when the end_time
has been passed. If there were no bids placed, the original owner retains the token.
pub enum ExecuteMsg {
Claim {
token_id: String,
token_address:String,
},
}
token_id
String
The Id of the token that was auctioned.
token_address
String
The address of the NFT contract.
Base Executes
The rest of the execute messages can be found in the ADO Base section.
QueryMsg
LatestAuctionState
Queries the most recent auction for the given token (either ongoing, complete, or not started yet).
pub enum QueryMsg {
#[returns(AuctionStateResponse)]
LatestAuctionState {
token_id: String,
token_address:String,
},
}
token_id
String
The Id of the NFT that we want to query the auction of.
token_address
String
The address of the NFT contract.
AuctionStateResponse
pub struct AuctionStateResponse {
pub start_time: Expiration,
pub end_time: Expiration,
pub high_bidder_addr: String,
pub high_bidder_amount: Uint128,
pub auction_id: Uint128,
pub coin_denom: String,
pub uses_cw20: bool,
pub is_cancelled:bool,
pub min_bid: Option<Uint128>,
pub min_raise: Option<Uint128>,
pub owner: String,
pub whitelist: Option<Vec<Addr>>,
pub recipient: Option<Recipient>,
}
start_time
The start of the auction.
end_time
The end of the auction.
high_bidder_addr
String
The address of the highest bidder.
high_bidder_amount
Uint128
The amount of the highest bid.
auction_id
Uint128
The Id of the auction.
coin_denom
String
The denom the auction is in.
is_cancelled
bool
Whether or not the auction has been cancelled.
min_bid
Option<Uint128>
The minimum bid that can be placed on the auctioned token.
min_raise
Option<Uint128>
The minimum increase amount for a bid to be accepted.
whitelist
Option<Vec<Addr>>
The whitelisted addresses if they were specified at time of creation.
recipient
Option<Recipient>
Address to receive the funds of the auction.
AuctionState
Gets the auction state for a particular auction_id
.
Each Auction has an auction_id which starts at 1 and increments every new auction.
To get the auction_id of a particular token, use LatestAuctionState.
pub enum QueryMsg {
#[returns(AuctionStateResponse)]
AuctionState {
auction_id: Uint128,
},
}
auction_id
Uint128
The auction Id.
Response
See AuctionStateResponse.
Bids
Gets the bids for a given auction.
pub enum QueryMsg {
#[returns(BidsResponse)]
Bids {
auction_id: Uint128,
start_after: Option<u64>,
limit: Option<u64>,
order_by: Option<OrderBy>,
},
}
auction_id
Uint128
The auction Id.
start_after
Option<u64>
Optional parameter to specify which bid to start after. If none specified index 0
will be used.
limit
Option<u64>
Optional parameter to specify how many bids to query. If none specified a default limit of 10 is used.
order_by
Option<OrderBy>
Optional parameter to specify the order of the bids being queries. Default is Ascending.
pub enum OrderBy {
Asc,
Desc,
}
BidsResponse
pub struct BidsResponse {
pub bids: Vec<Bid>,
}
bids
The retrieved bids.
Bid
The state for a particular bid is stored in a basic struct.
pub struct Bid {
pub bidder: String,
pub amount: Uint128,
pub timestamp: Timestamp,
}
bidder
String
The address of the bidder.
amount
Uint128
The amount of funds bid.
timestamp
The time of the bid.
AuctionIds
Queries the auction Ids for a given token.
pub enum QueryMsg {
#[returns(AuctionIdsResponse)]
AuctionIds {
token_id: String,
token_address:String
}
}
token_id
String
The Id of the token/NFT.
token_address
String
The address of the NFT contract.
AuctionIdsResponse
pub struct AuctionIdsResponse {
pub auction_ids: Vec<Uint128>,
}
auction_ids
Vec<Uint128>
The auction Ids.
AuctionInfosForAddress
Gets all of the auction infos for a given token address.
pub enum ExecuteMsg {
#[returns(AuctionInfo)]
AuctionInfosForAddress {
token_address: String,
start_after: Option<String>,
limit: Option<u64>,
}
}
token_address
String
The address of the token contract
start_after
Option<String>
Optional parameter to specify which AuctionInfo
to start from. If none specified index 0
will be used.
limit
Option<u64>
Optional parameter to specify how many AuctionInfo
to query. If none specified a default limit of 10 is used. The maximum limit is 30.
AuctionInfosForAddressResponse
Returns a vector of AuctionInfo defined below.
pub struct AuctionInfo {
pub auction_ids: Vec<Uint128>,
pub token_address: String,
pub token_id: String,
}
auction_ids
Vec<Uint128>
The Ids of the auctions that use the specified token_address
token_address
String
The address of the token contract.
token_id
String
The Id of the token that was auctioned.
IsCancelled
Checks if the specified auction was cancelled.
pub enum QueryMsg {
#[returns(bool)]
IsCancelled {
token_id: String,
token_address: String,
},
}
token_id
String
The Id of the token that was auctioned.
token_address
String
The address of the token contract.
Returns a true if the auction has been cancelled and false otherwise.
IsClosed
Checks if the specified auction has been closes. Returns true only if the auction has been cancelled, the token has been claimed, or the end time has expired.
pub enum QueryMsg {
#[returns(bool)]
IsClosed {
token_id: String,
token_address: String,
}
}
token_id
String
The Id of the token that was auctioned.
token_address
String
The address of the token contract.
Returns a true if the auction has been cancelled and false otherwise.
IsClaimed
Checks if the NFT has been claimed after the auction has concluded.
pub enum QueryMsg {
#[returns(bool)]
IsClaimed {
token_id: String,
token_address: String,
}
}
token_id
String
The Id of the token that was auctioned.
token_address
String
The address of the token contract.
Returns a true if the NFT has been claimed and false otherwise.
AuthorizedAddresses
Gets all of the authorized ADO addresses for the specified action.
For CW721, the action should be specified as "send_nft".
For CW20, the action should be specified as "send_cw20".
pub enum QueryMsg {
#[returns(::andromeda_std::common::denom::AuthorizedAddressesResponse)]
AuthorizedAddresses {
action: PermissionAction,
start_after: Option<String>,
limit: Option<u32>,
order_by: Option<OrderBy>,
},
}
action
The type of authorized addresses to fetch.
start_after
Option<String>
Optional parameter to specify which address
to start from.
limit
Option<u64>
Optional parameter to specify how many addresses to return. If none specified a default limit of 25 is used. The maximum limit is 50.
order_by
Whether to return the addresses in ascending or descending order. Defaults to ascending if not specified.
OrderBy
How the returned addresses are ordered.
pub enum OrderBy {
Asc,
Desc,
}
AuthorizedAddressesResponse
#[cw_serde]
pub struct AuthorizedAddressesResponse {
pub addresses: Vec<String>,
}
addresses
Vec<String>
A vector containing the contract addresses of the authorized ADO for the specified action.
Base Queries
The rest of the query messages can be found in the ADO Base section.
Last updated
Was this helpful?