domain_logic.md

Domain Logic

In this document, we describe the terminology and models that we use in the Hydra Auction project.

Cardano terminology

In this document, we use L1 and L2 as follows:

Layer 1 (L1): the Cardano main network (mainnet) and ledger.

Layer 2 (L2): the network and ledger within a single Hydra Head.

Auction terminology

Assets:

Auction lot: the NFT asset being sold in the auction.

Voucher: the NFT asset that the winning bidder can use to buy the auction lot for the standing bid’s price.

Bidding:

Minimum bid increment: a new bid can replace the standing bid only if it exceeds it by at least this minimum increment.

Starting bid: the smallest bid that can be accepted by the auction.

Standing bid: the highest of the bids that have been submitted on or before a given time.

Deposits:

Bidder deposit: a fixed deposit that each bidder must provide (i.e. lock into the auction’s bidder deposit smart contract) to be eligible to participate in the auction. A bidder’s deposit can be claimed by the seller if the bidder wins the auction but does not buy the auction lot by the voucher expiry time.

Fees:

Auction fees: fees paid to the delegates as compensation for hosting the bidding process of the auction on L2. These fees must be paid when the winning bidder buys or the seller reclaims the auction lot, and they must be distributed equally to the delegates. If the winning bidder buys the auction lot, then the auction fees are deducted from his payment to the seller.

Roles:

Bidders: a group of people seeking to place bids to buy the auction lot.

Delegates: a group of people trusted to collectively witness new bids and track the standing bid over time.

Seller: the person seeking to sell the auction lot.

Winning bidder: the bidder whose bid is the standing bid at the bidding end time for the auction.

Auction lifecycle

The auction lifecycle is defined by the following times, declared by the seller when the auction is announced:

T0 Auction announcement time

T1 Bidding start time

T2 Bidding end time

T3 Voucher expiry time

T4 Cleanup time

For the purposes of modeling the state transitions of the auction, we partition time into periods () by the above lifecycle times:

P0 = [0, T0) Pre-auction period

P1 = [T0, T1) Pre-bidding period

P2 = [T1, T2) Bidding period

P3 = [T2, T3) Voucher active period

P4 = [T3, T4) Voucher expired period

P5 = [T4, ∞) Cleanup period

flowchart LR
    p0[Pre-auction]     --> p1
    p1[Pre-bidding]     --> p2
    p2[Bidding]         --> p3
    p3[Voucher active]  --> p4
    p4[Voucher expired] --> p5
    p5[Cleanup]

  classDef default font-size:90%, overflow:visible;

Loading

Auction state machine

An auction can be modelled by the following state machine. Here we use the UML statechart formalism, whereby each transition is labelled as input [condition]. A conjunction of multiple conditions is labelled as [condition1, condition2, ...]. We omit the outputs of each state transition.

stateDiagram-v2
  [*]               --> Announced:         AnnounceAuction [P0]
  Announced         --> BiddingOnL1:       StartBidding [P2]
  BiddingOnL1       --> BiddingOnL2:       CommitStandingBid [P2, HI]
  BiddingOnL1       --> VoucherActive:     [P3]
  BiddingOnL2       --> BiddingOnL1:       FanoutStandingBid [P2]
  BiddingOnL2       --> VoucherActive:     FanoutStandingBid [P3]
  VoucherActive     --> Concluded:         BidderBuys [P3]
  VoucherActive     --> VoucherExpired:    [P4]
  VoucherExpired    --> Concluded:         SellerReclaims [P4 ∪ P5]
  Concluded         --> [*]:               Cleanup [P5]

Loading

The state transitions are as follows:

AnnounceAuction [P0]. Before the auction announcement time T0, the seller can announce the auction via an L1 blockchain transaction that locks the auction lot into the auction escrow and specifies the terms of the auction.

StartBidding [P2]. During the bidding period (preferrably at the bidding start T1), the seller can declare the list of approved bidders for the auction and initialize the standing bid for the auction, which allows these bidders to start placing bids in the auction via L1 transactions.

CommitStandingBid [P2, HI]. During the bidding period, if the Hydra Head that will host the auction is still initializing (HI), then the standing bid can be moved to the Hydra Head, allowing bidders to place bids in the auction via L2 transactions (but no longer via L1).

FanoutStandingBid [P2]. During the bidding period, the standing bid can be moved back to L1 via fanout from the Hydra Head, allowing bidders to place bids in the auction via L1 transactions (but no longer via L2). This transition is undesirable because bidding on L1 is less convenient than on L2.

[P3]. During the voucher active period, bidders can no longer submit any new bids (neither via L1 nor L2).

FanoutStandingBid [P3]. During the voucher active period (preferrably at the bidding end time T2), the standing bid can be moved back to L1 via fanout from the Hydra Head, after which bidders can no longer submit any new bids (neither via L1 nor L2).

BidderBuys [P3]. During the voucher active period, the bidder can buy the auction lot, paying the winning bid amount to the seller and depositing the total auction fees in the fee escrow.

[P4]. During the voucher expiry period, the winning bidder can no longer buy the auction lot.

SellerReclaims [P4 ∪ P5]. During the voucher expired period and during the cleanup period, if the winning bidder (if any) did not buy the auction lot, then the seller may reclaim the auction lot, depositing the total auction fees in the fee escrow.

Cleanup [P5]. During the cleanup period, the seller can spend the standing bid utxo, recovering the min 2 ADA inside it.

Bidder deposit state machine

We use a separate state machine to represent a bidder deposit, because the auction does not interact with bidder deposits directly. Instead, the state of the auction can be referenced to enable certain state transitions in the bidder deposit state machine.

Conversely, while the seller may observe which bidders have created deposits for the auction to decide on the list of approved bidders at bidding start, this is not enforced by on-chain code so we represent this as an arbitrary decision by the seller in the auction state machine.

stateDiagram-v2
  [*]        --> Announced:  AnnounceAuction [P0]
  Announced  --> Deposited:  CreateDeposit   [P1]
  Deposited  --> [*]:        BidderBuys      [W, P3]
  Deposited  --> [*]:        SellerClaims    [W, P4]
  Deposited  --> [*]:        RefundDeposit   [¬W, P3 ∪ P4]
  Deposited  --> [*]:        RefundDeposit   [P5]

Loading

The state transitions are as follows:

AnnounceAuction [P0]. Bidder deposits should not be created before the auction is announced.

CreateDeposit [P1]. During the pre-bidding period, a bidder can create a deposit for an auction in order to be considered by the seller of the auction for inclusion in the auction's list of approved bidders.

BidderBuys [W, P3]. During the voucher active period, the bidder can claim the deposit (if available) while buying the auction lot, to use some of the ADA in the deposit in the payment of the winning bid amount to the seller.

SellerClaims [W, P4]. During the voucher expired period, the seller can claim the winning bidder's deposit (if available), by referencing on-chain auction state that proves that the winning bidder did not buy the auction lot.

RefundDeposit [¬W, P3 ∪ P4]. During the voucher active period and during the voucher expiry period, the bidder can reclaim his deposit (if available) by referencing on-chain auction state that proves that the bidder did not win the auction.

RefundDeposit [P5]. During the cleanup period, the bidder can reclaim his deposit (if available) unconditionally.

Fee escrow state machine

We use a separate state machine for the fee escrow because, while it gets initialized during a state transition of the auction, its further evolution proceeds independently from the auction.

stateDiagram-v2
  [*]           --> FeesDeposited:  BidderBuys     [P3]
  [*]           --> FeesDeposited:  SellerReclaims [P4 ∪ P5]
  FeesDeposited --> [*]:            DistributeFees

Loading

The state transitions are as follows:

BidderBuys [P3]. During the voucher active period, the total auction fees are deposited in the fee escrow if the bidder buys the auction lot.

SellerReclaims [P4 ∪ P5]. During the voucher expired period and during the cleanup period, the total auction fees are deposited in the fee escrow if the seller reclaims the auction lot.

DistributeFees. Once the total auction fees are deposited into the fee escrow, they can be distributed equally to the delegates of the Hydra Head that hosted the auction on L2.