IBatchAuction

Git Source

Inherits: IAuction

Interface for batch auctions

The implementing contract should define the following additional areas:

• Any un-implemented functions
• State variables for storage and configuration

Functions

dedicatedSettlePeriod

Time period after auction conclusion where bidders cannot refund bids

function dedicatedSettlePeriod() external view returns (uint48);

lotAuctionOutput

Custom auction output for each lot

Stored during settlement

function lotAuctionOutput(uint96 lotId) external view returns (bytes memory);

Parameters

Name	Type	Description
lotId	uint96	The lot ID

bid

Bid on an auction lot

The implementing function should handle the following:

• Validate the bid parameters
• Store the bid data

function bid(
    uint96 lotId_,
    address bidder_,
    address referrer_,
    uint256 amount_,
    bytes calldata auctionData_
) external returns (uint64 bidId);

Parameters

Name	Type	Description
lotId_	uint96	The lot id
bidder_	address	The bidder of the purchased tokens
referrer_	address	The referrer of the bid
amount_	uint256	The amount of quote tokens to bid
auctionData_	bytes	The auction-specific data

Returns

Name	Type	Description
bidId	uint64	The bid id

refundBid

Refund a bid

The implementing function should handle the following:

• Validate the bid parameters
• Authorize caller_
• Update the bid data

function refundBid(
    uint96 lotId_,
    uint64 bidId_,
    uint256 index_,
    address caller_
) external returns (uint256 refund);

Parameters

Name	Type	Description
lotId_	uint96	The lot id
bidId_	uint64	The bid id
index_	uint256	The index of the bid ID in the auction's bid list
caller_	address	The caller

Returns

Name	Type	Description
refund	uint256	The amount of quote tokens to refund

claimBids

Claim multiple bids

The implementing function should handle the following:

• Validate the bid parameters
• Update the bid data

function claimBids(
    uint96 lotId_,
    uint64[] calldata bidIds_
) external returns (BidClaim[] memory bidClaims, bytes memory auctionOutput);

Parameters

Name	Type	Description
lotId_	uint96	The lot id
bidIds_	uint64[]	The bid ids

Returns

Name	Type	Description
bidClaims	BidClaim[]	The bid claim data
auctionOutput	bytes	The auction-specific output

settle

Settle a batch auction lot with on-chain storage and settlement

The implementing function should handle the following:

• Validate the lot parameters
• Determine the winning bids
• Update the lot data

function settle(
    uint96 lotId_,
    uint256 num_
)
    external
    returns (
        uint256 totalIn,
        uint256 totalOut,
        uint256 capacity,
        bool finished,
        bytes memory auctionOutput
    );

Parameters

Name	Type	Description
lotId_	uint96	The lot id
num_	uint256	The number of winning bids to settle (capped at the remaining number if more is provided)

Returns

Name	Type	Description
totalIn	uint256	Total amount of quote tokens from bids that were filled
totalOut	uint256	Total amount of base tokens paid out to winning bids
capacity	uint256	The original capacity of the lot
finished	bool	Whether the settlement is finished
auctionOutput	bytes	Custom data returned by the auction module

abort

Abort a batch auction that cannot be settled, refunding the seller and allowing bidders to claim refunds

The implementing function should handle the following:

• Validate the lot is in the correct state
• Set the auction in a state that allows bidders to claim refunds

function abort(uint96 lotId_) external;

Parameters

Name	Type	Description
lotId_	uint96	The lot id

getNumBids

Get the number of bids for a lot

function getNumBids(uint96 lotId_) external view returns (uint256 numBids);

Parameters

Name	Type	Description
lotId_	uint96	The lot ID

Returns

Name	Type	Description
numBids	uint256	The number of bids

getBidIds

Get the bid IDs from the given index

function getBidIds(
    uint96 lotId_,
    uint256 start_,
    uint256 count_
) external view returns (uint64[] memory bidIds);

Parameters

Name	Type	Description
lotId_	uint96	The lot ID
start_	uint256	The index to start retrieving bid IDs from
count_	uint256	The number of bids to retrieve

Returns

Name	Type	Description
bidIds	uint64[]	The bid IDs

getBidIdAtIndex

Get the bid ID at the given index

function getBidIdAtIndex(uint96 lotId_, uint256 index_) external view returns (uint64 bidId);

Parameters

Name	Type	Description
lotId_	uint96	The lot ID
index_	uint256	The index

Returns

Name	Type	Description
bidId	uint64	The bid ID

getBidClaim

Get the claim data for a bid

This provides information on the outcome of a bid, independent of the claim status

function getBidClaim(
    uint96 lotId_,
    uint64 bidId_
) external view returns (BidClaim memory bidClaim);

Parameters

Name	Type	Description
lotId_	uint96	The lot ID
bidId_	uint64	The bid ID

Returns

Name	Type	Description
bidClaim	BidClaim	The bid claim data

Errors

Auction_DedicatedSettlePeriod

error Auction_DedicatedSettlePeriod(uint96 lotId);

Auction_InvalidBidId

error Auction_InvalidBidId(uint96 lotId, uint96 bidId);

Auction_NotBidder

error Auction_NotBidder();

Structs

BidClaim

Contains data about a bidder's outcome from an auction

Only used in memory so doesn't need to be packed

struct BidClaim {
    address bidder;
    address referrer;
    uint256 paid;
    uint256 payout;
    uint256 refund;
}

Properties

Name	Type	Description
bidder	address	The bidder
referrer	address	The referrer
paid	uint256	The amount of quote tokens paid (including any refunded tokens)
payout	uint256	The amount of base tokens paid out
refund	uint256	The amount of quote tokens refunded