Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ The life cycle of an auction is as follows:
2. Until the auction is ended, anyone can place a bid as long as their bid is strictly higher than the current winning bid and meets certain requirements which can be specified by the auctioneer. The bidder locks up their bid plus the buyer's premium and NFT royalty, and the previous bidder is refunded everything they locked up. Multiple bids can be placed in a single spend.
3. When the auction is ended, the NFT is sent to the highest bidder, the auctioneer receives the final bid amount minus the commission, and the buyer's premium, commission, and NFT royalty are paid out. If there were no bids, the NFT is sent back to the auctioneer. An auction can only be ended once, and no bids can be placed after it's ended.

If the auction has a buy now price, a bid at exactly that price wins outright, and the auction can be ended right away instead of at the end time (see [Buy Now](#buy-now)).

Until the first bid is placed, the auctioneer can also cancel the auction at any time, which sends the NFT back to them just like ending it with no bids. Once there's a bid, the auctioneer is committed and the auction can only be ended. A cancelled auction is ended, so it can't be bid on, ended, or cancelled again.

## Customization
Expand All @@ -22,6 +24,7 @@ The following parameters can be customized by the auctioneer:
- The minimum bid increment (flat or percentage)
- The minimum amount of time before the auction is ended
- The grace period after a bid is placed before the auction is ended
- An optional buy now price

These can also be customized, but they may be enforced to be certain values by the auction house and/or wallet, to ensure that they get a cut:

Expand All @@ -32,6 +35,20 @@ The auctioneer can cancel the auction before the first bid, regardless of these

Both the buyer's premium and commission are percentages, and are sent to a single address. If these need to be split between multiple addresses, you should use something external to do so such as the [royalty split](https://splitxch.com/) primitive.

## Buy Now

An auction can have a buy now price (`AuctionSettings::buy_now_price`). It's curried into the bid and end actions, where 0 means there isn't one, so it can't be changed once the auction is launched. With a buy now price:

- No bid can exceed it.
- A bid at exactly the buy now price skips the bid verifier, so the increment can't make it unreachable once there's a bid close to it. It must still be strictly higher than the winning bid, and placed before the end time (or within the grace period). So the auction can be bought until it's ended, and while the winning bid is below the buy now price.
- If the winning bid is at the buy now price, the end action skips the end time and grace period checks, since it can never be outbid. Otherwise the auction ends as usual.

To buy now, a wallet places a bid at the buy now price and ends the auction in the same spend. `AuctionExt::spend_buy_now_actions` builds both actions and unlocks the NFT to the buyer. The buyer funds and asserts the bid like any other bid, and the previous winning bid is refunded in the same spend. `AuctionInfo::available_buy_now_price` returns the price while the auction can still be bought. If a bid at the buy now price is placed on its own instead, anyone can end the auction right after it.

Buying is a bid, so it competes with pending bids in the same way (see [Competing Bids](#competing-bids)). A buyer can add their buy now after a pending bid in the same spend, which refunds the pending bidder. A pending buy now can't be outbid like this, since no bid can come after it, so the first buy now to reach the mempool wins unless a conflicting spend confirms first.

The auctioneer can still cancel an auction with a buy now price before the first bid.

## Cancelling

The cancel action asserts that the auction hasn't ended and has no bids, and has no timing restrictions. It must be authorized by a coin at the payout address, which sends the message `c` to the current auction coin with the `SENDER_PUZZLE | RECEIVER_COIN` mode (`0x17`). Since the message is sent to a specific auction coin, it can't be reused once the auction has been spent. `AuctionExt::cancel_authorization` returns the condition that coin must output, and `AuctionExt::spend_cancel_action` builds the action, which must be spent along with `AuctionExt::unlock_nft` in the same spend bundle. Like the end action, the cancel action creates the coin announcement `$`, and leaves the auction in the same state as ending it with no bids. The spend itself still reveals that it was cancelled.
Expand Down Expand Up @@ -67,6 +84,7 @@ The reserve finalizer takes the reserve coin's parent from the singleton's solut
The puzzles can't prevent every misconfiguration on their own, so `AuctionLaunch::into_auction` rejects invalid auctions. `launch_auction` runs the same checks, but not the ones that are left to wallets below, so sellers are responsible for locking the NFT and reserve correctly:

- The minimum bid and bid increment must be greater than 0.
- The buy now price, if there is one, must be greater than 0 and at least the minimum bid. Since a bid at the buy now price skips the bid verifier, a lower price would undercut the minimum bid.
- The buyer's premium, commission, and NFT royalty can't exceed 10,000 basis points.
- Addresses that receive a payment must be unique, and can't be the settlement payments puzzle or the auction's own lock address. Addresses that aren't paid (with 0 basis points) are ignored.

Expand Down
12 changes: 11 additions & 1 deletion puzzles/actions/bid_action.rue
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ fn main(
TIMINGS: Timings,
BUYERS_PREMIUM_BPS: Int,
ROYALTY_BPS: Int,
// The price at which a bid wins the auction outright, or 0 if there's no buy now price
BUY_NOW_PRICE: Int,
Truth: AuctionStateTruth,
...{ bid, grace }: Solution,
) -> Output {
Expand All @@ -30,10 +32,18 @@ fn main(
//
// Bids must strictly increase regardless of the verifier. Since the initial winning bid amount
// is 0, this also ensures that every bid is positive.
//
// Bids can't exceed the buy now price, so a bid at the buy now price can never be outbid, and
// the end action lets it end the auction right away. It skips the bid verifier, since the
// increment could otherwise make the buy now price unreachable once there's a bid close to it.
// Every bid is positive, so this never applies if there's no buy now price.
let is_buy_now = bid.amount == BUY_NOW_PRICE;

assert !Truth.state.ended
& (bid.puzzle_hash.length == 32)
& (bid.amount > Truth.state.winning_bid.amount)
& BID_VERIFIER(old_bid, bid);
& ((BUY_NOW_PRICE == 0) | !(bid.amount > BUY_NOW_PRICE))
& (is_buy_now | BID_VERIFIER(old_bid, bid));

// The premium and royalty are rounded separately so that the reserve holds exactly what the end
// action pays out. This matters for CAT reserves, since the CAT ring must balance exactly.
Expand Down
2 changes: 1 addition & 1 deletion puzzles/actions/bid_action.rue.hash
Original file line number Diff line number Diff line change
@@ -1 +1 @@
3357138553b6efb673f36202c78967ade33bbb80cc8e3683f9fe0de97e36a357
d94e4389be5a2d7f9fd692c792a78f184c8e1f70ec633873b22744f2d0233e9c
29 changes: 15 additions & 14 deletions puzzles/actions/bid_action.rue.hex
Original file line number Diff line number Diff line change
@@ -1,14 +1,15 @@
ff02ffff01ff02ffff01ff02ffff03ffff22ffff22ffff22ffff20ff8205bf80
ffff09ffff0dff0680ffff01208080ffff15ff04ff820bbf8080ffff02ff0bff
ff04ffff03ff820bbfff8207bfff8080ffff04ff02ff8080808080ffff01ff04
ffff04ff82013fffff04ffff10ff04ffff13ffff12ff04ff2f80ffff01822710
80ffff13ffff12ff04ff5f80ffff018227108080ffff04ff80ff02808080ffff
04ffff03ffff22ff8202ffffff15ff37ff808080ffff04ffff0154ffff04ff37
ff808080ffff04ffff0155ffff04ff27ff80808080ffff04ffff04ffff013cff
ff04ffff02ff05ffff04ff05ff028080ff808080ffff03ff820bbfffff04ffff
04ffff0181d6ffff04ffff0133ffff04ff820fbfffff04ff8202bfffff04ffff
04ff820fbfff8080ff808080808080ff8080ff8080808080ffff01ff088080ff
0180ffff04ffff04ffff10ff82013f80ff8201bf80ff018080ffff04ffff01ff
02ffff03ffff07ff0380ffff01ff0bffff0102ffff02ff02ffff04ff02ff0580
80ffff02ff02ffff04ff02ff07808080ffff01ff0bffff0101ff038080ff0180
ff018080
ff02ffff01ff02ffff01ff02ffff03ffff22ffff22ffff22ffff22ffff20ff82
0b7f80ffff09ffff0dff0680ffff01208080ffff15ff04ff82177f8080ffff21
ffff20ff81bf80ffff20ffff15ff04ff81bf80808080ffff21ffff09ff04ff81
bf80ffff02ff0bffff04ffff03ff82177fff820f7fff8080ffff04ff02ff8080
80808080ffff01ff04ffff04ff82027fffff04ffff10ff04ffff13ffff12ff04
ff2f80ffff0182271080ffff13ffff12ff04ff5f80ffff018227108080ffff04
ff80ff02808080ffff04ffff03ffff22ff8205ffffff15ff37ff808080ffff04
ffff0154ffff04ff37ff808080ffff04ffff0155ffff04ff27ff80808080ffff
04ffff04ffff013cffff04ffff02ff05ffff04ff05ff028080ff808080ffff03
ff82177fffff04ffff04ffff0181d6ffff04ffff0133ffff04ff821f7fffff04
ff82057fffff04ffff04ff821f7fff8080ff808080808080ff8080ff80808080
80ffff01ff088080ff0180ffff04ffff04ffff10ff82027f80ff82037f80ff01
8080ffff04ffff01ff02ffff03ffff07ff0380ffff01ff0bffff0102ffff02ff
02ffff04ff02ff058080ffff02ff02ffff04ff02ff07808080ffff01ff0bffff
0101ff038080ff0180ff018080
26 changes: 19 additions & 7 deletions puzzles/actions/end_action.rue
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ fn main(
TIMINGS: Timings,
PAYMENTS: Payments,
ROYALTY_BPS: Int,
// The price at which a bid wins the auction outright, or 0 if there's no buy now price
BUY_NOW_PRICE: Int,
// The inner puzzle hash of the settlement coin, which is wrapped by the CAT layer for CAT reserves
SETTLEMENT_PAYMENT_HASH: Bytes32,
NFT_COIN_ID: Bytes32,
Expand All @@ -31,6 +33,11 @@ fn main(
let payout = bid_amount - commission;
let unlock_conditions = UNLOCKER(Truth.state.winning_bid, ...unlocker_solution);

// The bid action never allows a bid above the buy now price, so a winning bid at the buy now
// price can't be outbid, and the auction can be ended without waiting for it to be over. With no
// buy now price, the winning bid amount is 0 if there are no bids, so it must be checked first.
let bought_now = (BUY_NOW_PRICE > 0) & (bid_amount == BUY_NOW_PRICE);

Output {
new_truth: AuctionStateTruth {
state: AuctionState {
Expand Down Expand Up @@ -101,17 +108,22 @@ fn main(
message: tree_hash((1, unlock_conditions)),
},

// We always need to make sure the auction is over
AssertSecondsAbsolute { seconds: TIMINGS.end_time },

// Announce the end of the auction
CreateCoinAnnouncement { message: "$" },

// If there is a grace period, we need to make sure it's over too
...inline if TIMINGS.grace_period > 0 {
[AssertSecondsRelative { seconds: TIMINGS.grace_period }]
} else {
// Unless the auction was bought now, we need to make sure it's over, including the grace
// period if there is one
...inline if bought_now {
nil
} else {
[
AssertSecondsAbsolute { seconds: TIMINGS.end_time },
...inline if TIMINGS.grace_period > 0 {
[AssertSecondsRelative { seconds: TIMINGS.grace_period }]
} else {
nil
},
]
},
],
}
Expand Down
2 changes: 1 addition & 1 deletion puzzles/actions/end_action.rue.hash
Original file line number Diff line number Diff line change
@@ -1 +1 @@
4cdb31b702e6f9e363035aab9e431352a901e6e2c31a76b0552d6434a6741344
5d9df3e170a0ee659f54372537dd49fd11973aaca297eb9b855b048e79b7f21b
25 changes: 13 additions & 12 deletions puzzles/actions/end_action.rue.hex
Original file line number Diff line number Diff line change
@@ -1,20 +1,21 @@
ff02ffff01ff02ffff03ff820b7fffff01ff0880ffff01ff02ffff01ff02ffff
01ff02ffff01ff04ffff04ff8213ffffff04ff80ffff04ffff0101ff827bff80
ff02ffff01ff02ffff03ff8216ffffff01ff0880ffff01ff02ffff01ff02ffff
01ff02ffff01ff04ffff04ff8227ffffff04ff80ffff04ffff0101ff82f7ff80
8080ffff04ffff03ff15ffff04ffff0181d6ffff04ffff0133ffff04ff82033f
ffff04ff15ffff04ffff04ff82033fff8080ff808080808080ffff01ff018080
ffff04ffff03ff09ffff04ffff0181d6ffff04ffff0133ffff04ff8206bfffff
04ff09ffff04ffff04ff8206bfff8080ff808080808080ffff01ff018080ffff
04ffff03ffff15ff02ff8080ffff04ffff0181d6ffff04ffff0133ffff04ff82
03bfffff04ff02ffff04ffff04ff8203bfff8080ff808080808080ffff01ff01
8080ffff04ffff03ff1dffff04ffff0181d6ffff04ffff0133ffff04ff8202ff
8080ffff04ffff03ff1dffff04ffff0181d6ffff04ffff0133ffff04ff8205ff
ffff04ff1dff8080808080ffff01ff018080ffff04ffff04ffff0142ffff04ff
ff0117ffff04ffff02ff17ffff04ff17ffff04ffff0101ffff02ff2fffff04ff
827bffff820fff8080808080ffff04ff8205ffff8080808080ffff04ffff04ff
ff0151ffff04ff819fff808080ffff04ffff01ff3cff2480ffff03ffff15ff81
dfff8080ffff04ffff04ffff0150ffff04ff81dfff808080ff8080ff80808080
808080808080ffff04ffff11ff05ff0480ff018080ffff04ffff04ffff13ffff
12ff02ff82012f80ffff0182271080ffff04ffff13ffff12ff02ff818f80ffff
0182271080ffff13ffff12ff02ff5f80ffff01822710808080ff018080ffff04
ff82177fff01808080ff0180ffff04ffff01ff02ffff03ffff07ff0380ffff01
ff0bffff0102ffff02ff02ffff04ff02ff058080ffff02ff02ffff04ff02ff07
808080ffff01ff0bffff0101ff038080ff0180ff018080
82f7ffff821fff8080808080ffff04ff820bffff8080808080ffff04ffff01ff
3cff2480ffff03ffff22ffff15ff8202ffff8080ffff09ff0bff8202ff8080ff
80ffff04ffff04ffff0151ffff04ff819fff808080ffff03ffff15ff81dfff80
80ffff04ffff04ffff0150ffff04ff81dfff808080ff8080ff80808080808080
80808080ffff04ffff11ff05ff0480ff018080ffff04ffff04ffff13ffff12ff
02ff82012f80ffff0182271080ffff04ffff13ffff12ff02ff818f80ffff0182
271080ffff13ffff12ff02ff5f80ffff01822710808080ff018080ffff04ff82
2effff01808080ff0180ffff04ffff01ff02ffff03ffff07ff0380ffff01ff0b
ffff0102ffff02ff02ffff04ff02ff058080ffff02ff02ffff04ff02ff078080
80ffff01ff0bffff0101ff038080ff0180ff018080
4 changes: 4 additions & 0 deletions src/actions/bid.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ pub struct BidActionArgs<V = NodePtr> {
pub timings: Timings,
pub buyers_premium_bps: u64,
pub royalty_bps: u64,
/// The price at which a bid wins the auction outright, or 0 if there's no buy now price.
pub buy_now_price: u64,
}

impl<V> BidActionArgs<V> {
Expand All @@ -17,12 +19,14 @@ impl<V> BidActionArgs<V> {
timings: Timings,
buyers_premium_bps: u64,
royalty_bps: u64,
buy_now_price: u64,
) -> Self {
Self {
bid_verifier,
timings,
buyers_premium_bps,
royalty_bps,
buy_now_price,
}
}
}
Expand Down
4 changes: 4 additions & 0 deletions src/actions/end.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ pub struct EndActionArgs<U = NodePtr> {
pub timings: Timings,
pub payments: Payments,
pub royalty_bps: u64,
/// The price at which a bid wins the auction outright, or 0 if there's no buy now price.
pub buy_now_price: u64,
/// The inner puzzle hash of the settlement coin created by the reserve, which is wrapped by the
/// CAT layer for CAT reserves.
pub settlement_payment_hash: Bytes32,
Expand All @@ -21,6 +23,7 @@ impl<U> EndActionArgs<U> {
timings: Timings,
payments: Payments,
royalty_bps: u64,
buy_now_price: u64,
settlement_payment_hash: Bytes32,
nft_coin_id: Bytes32,
) -> Self {
Expand All @@ -29,6 +32,7 @@ impl<U> EndActionArgs<U> {
timings,
payments,
royalty_bps,
buy_now_price,
settlement_payment_hash,
nft_coin_id,
}
Expand Down
Loading
Loading