EncryptedMarginalPrice

Inherits: BatchAuctionModule, IEncryptedMarginalPrice

Encrypted Marginal Price

This batch auction module allows for bids to be encrypted off-chain, then stored, decrypted and settled on-chain. Note that the maximum bid amount is bounded by uint96.

State Variables

auctionData

Auction-specific data for a lot

Access via getAuctionData()

mapping(uint96 lotId => AuctionData) public auctionData;

_lotPartialFill

Partial fill data for a lot

Each EMPA can have at most one partial fill Access via getPartialFill()

mapping(uint96 lotId => PartialFill) internal _lotPartialFill;

_lotPartialSettlement

Partial settlement data stored between settlement batches

Only used internally, does not need a public accessor

mapping(uint96 lotId => PartialSettlement) internal _lotPartialSettlement;

bids

General information about bids on a lot

Access via getBid()

mapping(uint96 lotId => mapping(uint64 bidId => Bid)) public bids;

encryptedBids

Data for encryption information for a specific bid

Access via getBid()

mapping(uint96 lotId => mapping(uint64 bidId => EncryptedBid)) public encryptedBids;

decryptedBids

Queue of decrypted bids for a lot (populated on decryption)

Access elements via getNextInQueue()

mapping(uint96 lotId => Queue) public decryptedBids;

Functions

constructor

constructor(address auctionHouse_) AuctionModule(auctionHouse_);

VEECODE

7 byte, versioned identifier for the module. 2 characters from 0-9 that signify the version and 3-5 characters from A-Z.

function VEECODE() public pure override returns (Veecode);

_auction

Implementation-specific auction creation logic

This function assumes:

The lot ID has been validated
The start and duration of the lot have been validated

This function performs the following:

Validates the auction parameters
Stores the auction data
Initializes the decrypted bids queue

This function reverts if:

The parameters cannot be decoded into the correct format
The minimum price is zero
The minimum fill percent is greater than 100%
The minimum bid size is zero or greater than the max uint96 value
The public key is not valid

function _auction(uint96 lotId_, Lot memory lot_, bytes memory params_) internal override;

Parameters

Name	Type	Description
`lotId_`	`uint96`	The lot ID
`lot_`	`Lot`	The lot data
`params_`	`bytes`	ABI-encoded data of type `IEncryptedMarginalPrice.AuctionDataParams`

_cancelAuction

Implementation-specific auction cancellation logic

This function assumes the following:

The lot ID has been validated
The caller has been authorized
The auction has not concluded

This function performs the following:

Sets the auction status to settled, and prevents claiming of proceeds

This function reverts if:

The auction is active or has not concluded

function _cancelAuction(uint96 lotId_) internal override;

Parameters

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

_bid

Implementation-specific bid logic

This function performs the following:

Validates inputs
Stores the encrypted bid
Adds the bid ID to the list of bids to decrypt
Returns the bid ID

This function assumes:

The lot ID has been validated
The caller has been authorized
The auction is active

This function reverts if:

The parameters cannot be decoded into the correct format
The amount is greater than the max uint96 value
The amount is less than the minimum bid size for the lot
The bid public key is not valid

function _bid(
    uint96 lotId_,
    address bidder_,
    address referrer_,
    uint256 amount_,
    bytes calldata auctionData_
) internal override 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`	ABI-encoded data of type `IEncryptedMarginalPrice.BidParams`

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 decrypted or settled (but not concluded)
The lot is within the dedicated settle period
The bid id is invalid
caller_ is not the bid owner
The bid is claimed or refunded
The caller is not an internal module

This is a modified version of the refundBid function in the AuctionModule contract. It does not revert if the lot is concluded.

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

This function performs the following:

Validates inputs
Marks the bid as refunded
Removes the bid from the list of bids to decrypt
Returns the amount to be refunded

The encrypted bid is not deleted from storage, so that the details can be fetched later.

This function assumes:

The lot ID has been validated
The bid ID has been validated
The caller has been authorized
The auction is active
The bid has not been refunded

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

Returns

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

_claimBid

Claims a bid and calculates the paid and payout amounts

This function performs the following:

Validates inputs
Marks the bid as claimed
Calculates the paid and payout amounts

This function assumes:

The lot ID has been validated
The bid ID has been validated
The caller has been authorized
The auction is not settled
The bid has not already been claimed

function _claimBid(
    uint96 lotId_,
    uint64 bidId_
) internal returns (BidClaim memory bidClaim, bytes memory auctionOutput_);

_claimBids

Implementation-specific bid claim logic

This function performs the following:

Validates inputs
Marks the bid as claimed
Calculates the paid and payout amounts

This function assumes:

The lot ID has been validated
The caller has been authorized
The auction has concluded
The auction is not settled

This function reverts if:

The bid ID is invalid
The bid has already been claimed

function _claimBids(
    uint96 lotId_,
    uint64[] calldata bidIds_
) internal override 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`	auctionOutput The auction-specific output

submitPrivateKey

Submits the private key for the auction lot and decrypts an initial number of bids It does not require gating. If the seller wishes to limit who can call, they can simply not reveal the key to anyone else. On the other hand, if a key management service is used, then anyone can call it once the key is revealed.

This function reverts if:

The lot ID is invalid
The lot is not active
The lot has not concluded
The private key has already been submitted
The lot has been settled (cancelled, settled or aborted)
The private key is invalid for the public key

function submitPrivateKey(
    uint96 lotId_,
    uint256 privateKey_,
    uint64 num_,
    bytes32[] calldata sortHints_
) external override;

Parameters

Name	Type	Description
`lotId_`	`uint96`	The lot ID of the auction to submit the private key for
`privateKey_`	`uint256`	The ECIES private key to decrypt the bids
`num_`	`uint64`	The number of bids to decrypt after submitting the private key (passed to `_decryptAndSortBids()`)
`sortHints_`	`bytes32[]`	The sort hints for the bid decryption (passed to `_decryptAndSortBids()`)

decryptAndSortBids

Decrypts a batch of bids and sorts them by price in descending order

This function handles the following:

Performs state validation
Iterates over the encrypted bids:
- Decrypts the bid
- Ignores if the bid is incorrectly encrypted
- Does not add to the sorted bid queue if the decrypted amount out is less than the minimum bid size or overflows
- Otherwise, adds to the sorted bid queue for use during settlement
Determines the next decrypt index
Sets the auction status to decrypted if all bids have been decrypted

This function reverts if:

The lot ID is invalid
The lot has not started
The lot is active
The private key has not been provided
num_ and sortHints_ have different lengths

function decryptAndSortBids(
    uint96 lotId_,
    uint64 num_,
    bytes32[] calldata sortHints_
) external override;

Parameters

Name	Type	Description
`lotId_`	`uint96`	The lot ID
`num_`	`uint64`	The number of bids to decrypt and sort
`sortHints_`	`bytes32[]`	The sort hints for the bids

_decryptAndSortBids

function _decryptAndSortBids(uint96 lotId_, uint64 num_, bytes32[] calldata sortHints_) internal;

decryptBid

Returns the decrypted amountOut of a single bid without altering contract state

This function does not alter the state of the contract, but provides a way to peek at the decrypted bid

This function reverts if:

The lot ID is invalid
The private key has not been provided

function decryptBid(
    uint96 lotId_,
    uint64 bidId_
) public view override returns (uint256 amountOut);

Parameters

Name	Type	Description
`lotId_`	`uint96`	The lot ID of the auction to decrypt the bid for
`bidId_`	`uint64`	The bid ID to decrypt

Returns

Name	Type	Description
`amountOut`	`uint256`	The decrypted amount out

_decrypt

Decrypts a bid and stores it in the sorted bid queue

function _decrypt(uint96 lotId_, uint64 bidId_, bytes32 sortHint_, uint256 baseScale_) internal;

getNextInQueue

Returns the bid after key_ in the queue

function getNextInQueue(uint96 lotId_, bytes32 key_) external view override returns (bytes32);

Parameters

Name	Type	Description
`lotId_`	`uint96`	The lot ID
`key_`	`bytes32`	The key to search for

Returns

Name	Type	Description
`<none>`	`bytes32`	nextKey The key of the next bid in the queue

getNumBidsInQueue

Returns the number of decrypted bids remaining in the queue

function getNumBidsInQueue(uint96 lotId_) external view override returns (uint256);

Parameters

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

Returns

Name	Type	Description
`<none>`	`uint256`	numBids The number of decrypted bids remaining in the queue

_getNextBid

Helper function to get the next bid from the queue and calculate the price

This is split into a different function to avoid stack too deep errors

function _getNextBid(
    Queue storage queue_,
    uint256 baseScale_
) internal returns (uint64 bidId, uint256 amountIn, uint256 price);

Parameters

Name	Type	Description
`queue_`	`Queue`	The queue to get the next bid from
`baseScale_`	`uint256`	The scaling factor for the base token

Returns

Name	Type	Description
`bidId`	`uint64`	The ID of the bid
`amountIn`	`uint256`	The amount in of the bid (in quote token units)
`price`	`uint256`	The price of the bid (in quote token units), or 0 if it could not be determined

_getLotMarginalPrice

Calculates the marginal price of a lot

function _getLotMarginalPrice(
    uint96 lotId_,
    uint256 num_
) internal returns (MarginalPriceResult memory result);

Parameters

Name	Type	Description
`lotId_`	`uint96`	The lot ID of the auction to calculate the marginal price for
`num_`	`uint256`

Returns

Name	Type	Description
`result`	`MarginalPriceResult`	The result of the marginal price calculation

_settle

Implementation-specific lot settlement logic

This function performs the following:

Validates inputs
Iterates over the decrypted bids to calculate the marginal price and number of winning bids
If applicable, calculates the payout and refund for a partially filled bid
Sets the auction status to settled

This function assumes:

The lot ID has been validated
The auction has concluded
The auction is not settled

This function reverts if:

The auction has not been decrypted

The function has been written to avoid any reverts that would cause the settlement process to brick.

function _settle(
    uint96 lotId_,
    uint256 num_
)
    internal
    override
    returns (uint256 totalIn_, uint256 totalOut_, bool, 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`	totalIn The total amount of quote tokens that filled the auction
`totalOut_`	`uint256`	totalOut The total amount of base tokens sold
`<none>`	`bool`	finished Whether the settlement is finished
`auctionOutput_`	`bytes`	auctionOutput The auction-type specific output to be used with a condenser

_abort

Implementation-specific lot settlement logic

This function performs the following:

Validates state
Sets the lot status to Settled
Sets the marginal price to the maximum value

This function assumes:

The lot ID has been validated
The auction is not settled
The dedicated settle period has not passed

This function reverts if:

None

function _abort(uint96 lotId_) internal override;

Parameters

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

getBid

Returns the Bid and EncryptedBid data for a given lot and bid ID

This function reverts if:

The lot ID is invalid
The bid ID is invalid

function getBid(
    uint96 lotId_,
    uint64 bidId_
) external view returns (Bid memory bid, EncryptedBid memory encryptedBid);

Parameters

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

Returns

Name	Type	Description
`bid`	`Bid`	The `Bid` data
`encryptedBid`	`EncryptedBid`	The `EncryptedBid` data

getAuctionData

Returns the AuctionData data for an auction lot

This function reverts if:

The lot ID is invalid

function getAuctionData(
    uint96 lotId_
) external view override returns (AuctionData memory auctionData_);

Parameters

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

Returns

Name	Type	Description
`auctionData_`	`AuctionData`	The `AuctionData`

getPartialFill

Returns the PartialFill data for an auction lot

For ease of use, this function determines if a partial fill exists. This function reverts if:

The lot ID is invalid
The lot is not settled

function getPartialFill(
    uint96 lotId_
) external view returns (bool hasPartialFill, PartialFill memory partialFill);

Parameters

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

Returns

Name	Type	Description
`hasPartialFill`	`bool`	True if a partial fill exists
`partialFill`	`PartialFill`	The `PartialFill` data

getNumBids

Get the number of bids for a lot

This function reverts if:

The lot ID is invalid

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

Parameters

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

Returns

Name	Type	Description
`<none>`	`uint256`	numBids The number of bids

getBidIds

Get the bid IDs from the given index

This function reverts if:

The lot ID is invalid

function getBidIds(
    uint96 lotId_,
    uint256 startIndex_,
    uint256 num_
) external view override returns (uint64[] memory);

Parameters

Name	Type	Description
`lotId_`	`uint96`	The lot ID
`startIndex_`	`uint256`
`num_`	`uint256`

Returns

Name	Type	Description
`<none>`	`uint64[]`	bidIds The bid IDs

_getBidClaim

Returns the BidClaim data for a given lot and bid ID

This function assumes:

The lot ID has been validated
The bid ID has been validated

function _getBidClaim(
    uint96 lotId_,
    uint64 bidId_
) internal 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 `BidClaim` data

getBidIdAtIndex

Get the bid ID at the given index

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

Parameters

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

Returns

Name	Type	Description
`<none>`	`uint64`	bidId The bid ID

getBidClaim

Get the claim data for a bid

This function reverts if:

The lot ID is invalid
The lot is not settled (since there would be no claim)
The bid ID is invalid

function getBidClaim(
    uint96 lotId_,
    uint64 bidId_
) external view override 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

_revertIfLotActive

Checks that the lot represented by lotId_ is active

Should revert if the lot is active Inheriting contracts can override this to implement custom logic

function _revertIfLotActive(uint96 lotId_) internal view override;

Parameters

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

_revertIfKeySubmitted

Reverts if the private key has been submitted for the lot

function _revertIfKeySubmitted(uint96 lotId_) internal view;

_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 override;

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 override;

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 override;

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 override;

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 override;

Parameters

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

Structs

MarginalPriceResult

Stuct containing the marginal price result

Memory only, no need to pack

struct MarginalPriceResult {
    uint256 marginalPrice;
    uint64 marginalBidId;
    uint64 lastBidId;
    uint256 lastBidPrice;
    uint256 totalAmountIn;
    uint256 capacityExpended;
    bool finished;
}

Properties

Name	Type	Description
`marginalPrice`	`uint256`	The marginal price of the auction. Set only if the marginal price has been determined.
`marginalBidId`	`uint64`	The ID of the marginal bid (marking that bids following it are not filled). Set only if the marginal price has been determined and there is a need for this to be set.
`lastBidId`	`uint64`	The ID of the last bid processed during the marginal price calculation. This should always be set, regardless of the settlement outcome.
`lastBidPrice`	`uint256`	The price of the last bid that was processed. This should always be set, regardless of the settlement outcome.
`totalAmountIn`	`uint256`	The total amount in from bids processed so far. This should always be set, regardless of the settlement outcome.
`capacityExpended`	`uint256`	The total capacity expended from bids processed so far. This should always be set, regardless of the settlement outcome.
`finished`	`bool`	Whether settlement has been completed.

PartialSettlement

Struct to store the data for in-progress settlement

struct PartialSettlement {
    uint256 processedAmountIn;
    uint256 lastPrice;
    uint64 lastBidId;
}

Properties

Name	Type	Description
`processedAmountIn`	`uint256`	The total amount in from bids processed so far (during settlement)
`lastPrice`	`uint256`	The last price processed during settlement
`lastBidId`	`uint64`	The ID of the last bid processed during settlement

EncryptedMarginalPrice

State Variables​

auctionData​

_lotPartialFill​

_lotPartialSettlement​

bids​

encryptedBids​

decryptedBids​

Functions​

constructor​

VEECODE​

_auction​

_cancelAuction​

_bid​

refundBid​

_refundBid​

_claimBid​

_claimBids​

submitPrivateKey​

decryptAndSortBids​

_decryptAndSortBids​

decryptBid​

_decrypt​

getNextInQueue​

getNumBidsInQueue​

_getNextBid​

_getLotMarginalPrice​

_settle​

_abort​

getBid​

getAuctionData​

getPartialFill​

getNumBids​

getBidIds​

_getBidClaim​

getBidIdAtIndex​

getBidClaim​

_revertIfLotActive​

_revertIfKeySubmitted​

_revertIfLotSettled​

_revertIfLotNotSettled​

_revertIfBidInvalid​

_revertIfNotBidOwner​

_revertIfBidClaimed​

Structs​

MarginalPriceResult​

PartialSettlement​

State Variables

auctionData

_lotPartialFill

_lotPartialSettlement

bids

encryptedBids

decryptedBids

Functions

constructor

VEECODE

_auction

_cancelAuction

_bid

refundBid

_refundBid

_claimBid

_claimBids

submitPrivateKey

decryptAndSortBids

_decryptAndSortBids

decryptBid

_decrypt

getNextInQueue

getNumBidsInQueue

_getNextBid

_getLotMarginalPrice

_settle

_abort

getBid

getAuctionData

getPartialFill

getNumBids

getBidIds

_getBidClaim

getBidIdAtIndex

getBidClaim

_revertIfLotActive

_revertIfKeySubmitted

_revertIfLotSettled

_revertIfLotNotSettled

_revertIfBidInvalid

_revertIfNotBidOwner

_revertIfBidClaimed

Structs

MarginalPriceResult

PartialSettlement