BatchAuctionModule

Inherits: IBatchAuction, AuctionModule

A base contract for batch auctions

State Variables

dedicatedSettlePeriod

Time period after auction conclusion where bidders cannot refund bids

uint48 public dedicatedSettlePeriod;

lotAuctionOutput

Custom auction output for each lot

Stored during settlement

mapping(uint96 => bytes) public lotAuctionOutput;

Functions

auctionType

Get the auction type

function auctionType() external pure override returns (AuctionType);

bid

Bid on an auction lot

Implements a basic bid function that:

Validates the lot and bid parameters
Calls the implementation-specific function

This function reverts if:

The lot id is invalid
The lot has not started
The lot has concluded
The lot is already settled
The caller is not an internal module

function bid(
    uint96 lotId_,
    address bidder_,
    address referrer_,
    uint256 amount_,
    bytes calldata auctionData_
) external virtual override onlyInternal 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

_bid

Implementation-specific bid logic

Auction modules should override this to perform any additional logic, such as validation and storage. The returned bidId should be a unique and persistent identifier for the bid, which can be used in subsequent calls (e.g. cancelBid() or settle()).

function _bid(
    uint96 lotId_,
    address bidder_,
    address referrer_,
    uint256 amount_,
    bytes calldata auctionData_
) internal virtual 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

Implements a basic refundBid function that:

Validates the lot and bid parameters
Calls the implementation-specific function

This function reverts if:

The lot id is invalid
The lot has not started
The lot is concluded, decrypted or settled
The bid id is invalid
caller_ is not the bid owner
The bid is claimed or refunded
The caller is not an internal module

function refundBid(
    uint96 lotId_,
    uint64 bidId_,
    uint256 index_,
    address caller_
) external virtual override onlyInternal 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

_refundBid

Implementation-specific bid refund logic

Auction modules should override this to perform any additional logic, such as validation and storage. Implementation functions should check for lot cancellation, if needed.

function _refundBid(
    uint96 lotId_,
    uint64 bidId_,
    uint256 index_,
    address caller_
) internal virtual 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

Implements a basic claimBids function that:

Validates the lot and bid parameters
Calls the implementation-specific function

This function reverts if:

The lot id is invalid
The lot is not settled
The caller is not an internal module

function claimBids(
    uint96 lotId_,
    uint64[] calldata bidIds_
)
    external
    virtual
    override
    onlyInternal
    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

_claimBids

Implementation-specific bid claim logic

Auction modules should override this to perform any additional logic, such as:

Validating the auction-specific parameters
Validating the validity and status of each bid
Updating the bid data

function _claimBids(
    uint96 lotId_,
    uint64[] calldata bidIds_
) internal virtual 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

Implements a basic settle function that:

Validates the lot and bid parameters
Calls the implementation-specific function
Updates the lot data

This function reverts if:

The lot id is invalid
The lot has not started
The lot is active
The lot has already been settled
The caller is not an internal module

function settle(
    uint96 lotId_,
    uint256 num_
)
    external
    virtual
    override
    onlyInternal
    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

_settle

Implementation-specific lot settlement logic

Auction modules should override this to perform any additional logic, such as:

Validating the auction-specific parameters
Determining the winning bids
Updating the lot data

function _settle(
    uint96 lotId_,
    uint256 num_
)
    internal
    virtual
    returns (uint256 totalIn, uint256 totalOut, bool finished, bytes memory auctionOutput);

Parameters

Name	Type	Description
`lotId_`	`uint96`	The lot ID
`num_`	`uint256`	The number of bids to settle in this pass (capped at the remaining number if more is provided)

Returns

Name	Type	Description
`totalIn`	`uint256`	The total amount of quote tokens that filled the auction
`totalOut`	`uint256`	The total amount of base tokens sold
`finished`	`bool`	Whether the settlement is finished
`auctionOutput`	`bytes`	The auction-type specific output to be used with a condenser

abort

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

Implements a basic abort function that:

Validates the lot id and state
Calls the implementation-specific function

The abort function allows anyone to abort the lot after the conclusion and settlement time has passed. This can be useful if the lot is unable to be settled, or if the seller is unwilling to settle the lot.

This function reverts if:

The lot id is invalid
The lot has not concluded
The lot is in the dedicated settle period
The lot is settled (after which it cannot be aborted)

function abort(uint96 lotId_) external virtual override onlyInternal;

Parameters

Name	Type	Description
`lotId_`	`uint96`	The lot id

_abort

Implementation-specific lot settlement logic

Auction modules should override this to perform any additional logic, such as:

Validating the auction-specific parameters
Updating auction-specific data

function _abort(uint96 lotId_) internal virtual;

Parameters

Name	Type	Description
`lotId_`	`uint96`	The lot ID

setDedicatedSettlePeriod

function setDedicatedSettlePeriod(uint48 period_) external onlyParent;

_revertIfLotSettled

Checks that the lot represented by lotId_ is not settled

Should revert if the lot is settled Inheriting contracts must override this to implement custom logic

function _revertIfLotSettled(uint96 lotId_) internal view virtual;

Parameters

Name	Type	Description
`lotId_`	`uint96`	The lot ID

_revertIfLotNotSettled

Checks that the lot represented by lotId_ is settled

Should revert if the lot is not settled Inheriting contracts must override this to implement custom logic

function _revertIfLotNotSettled(uint96 lotId_) internal view virtual;

Parameters

Name	Type	Description
`lotId_`	`uint96`	The lot ID

_revertIfBidInvalid

Checks that the lot and bid combination is valid

Should revert if the bid is invalid Inheriting contracts must override this to implement custom logic

function _revertIfBidInvalid(uint96 lotId_, uint64 bidId_) internal view virtual;

Parameters

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

_revertIfNotBidOwner

Checks that caller_ is the bid owner

Should revert if caller_ is not the bid owner Inheriting contracts must override this to implement custom logic

function _revertIfNotBidOwner(
    uint96 lotId_,
    uint64 bidId_,
    address caller_
) internal view virtual;

Parameters

Name	Type	Description
`lotId_`	`uint96`	The lot ID
`bidId_`	`uint64`	The bid ID
`caller_`	`address`	The caller

_revertIfBidClaimed

Checks that the bid is not claimed

Should revert if the bid is claimed Inheriting contracts must override this to implement custom logic

function _revertIfBidClaimed(uint96 lotId_, uint64 bidId_) internal view virtual;

Parameters

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

_revertIfDedicatedSettlePeriod

function _revertIfDedicatedSettlePeriod(uint96 lotId_) internal view;

BatchAuctionModule

State Variables​

dedicatedSettlePeriod​

lotAuctionOutput​

Functions​

auctionType​

bid​

_bid​

refundBid​

_refundBid​

claimBids​

_claimBids​

settle​

_settle​

abort​

_abort​

setDedicatedSettlePeriod​

_revertIfLotSettled​

_revertIfLotNotSettled​

_revertIfBidInvalid​

_revertIfNotBidOwner​

_revertIfBidClaimed​

_revertIfDedicatedSettlePeriod​

State Variables

dedicatedSettlePeriod

lotAuctionOutput

Functions

auctionType

bid

_bid

refundBid

_refundBid

claimBids

_claimBids

settle

_settle

abort

_abort

setDedicatedSettlePeriod

_revertIfLotSettled

_revertIfLotNotSettled

_revertIfBidInvalid

_revertIfNotBidOwner

_revertIfBidClaimed

_revertIfDedicatedSettlePeriod