IEncryptedMarginalPrice

Git Source

Interface for encrypted marginal price (batch) auctions

This contract does not inherit from BatchAuctionModule in order to avoid conflicts. Implementing contracts should inherit from both BatchAuctionModule and this interface.

Functions

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.

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

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

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

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

decryptBid

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

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

getNextInQueue

Returns the bid after key_ in the queue

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

Parameters

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

Returns

Name	Type	Description
nextKey	bytes32	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 returns (uint256 numBids);

Parameters

Name	Type	Description
lotId_	uint96	The lot ID

Returns

Name	Type	Description
numBids	uint256	The number of decrypted bids remaining in the queue

getBid

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

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

function getAuctionData(uint96 lotId_) external view 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

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

Events

BidDecrypted

Emitted when a bid is decrypted

event BidDecrypted(uint96 indexed lotId, uint64 indexed bidId, uint96 amountIn, uint96 amountOut);

Parameters

Name	Type	Description
lotId	uint96	The lot ID
bidId	uint64	The bid ID
amountIn	uint96	The amount in
amountOut	uint96	The amount out

PrivateKeySubmitted

Emitted when the private key for an auction lot is submitted

event PrivateKeySubmitted(uint96 indexed lotId);

Parameters

Name	Type	Description
lotId	uint96	The lot ID

Errors

Auction_InvalidKey

error Auction_InvalidKey();

Auction_WrongState

error Auction_WrongState(uint96 lotId);

Bid_WrongState

error Bid_WrongState(uint96 lotId, uint64 bidId);

NotPermitted

error NotPermitted(address caller);

Structs

AuctionDataParams

Parameters that are used to set auction-specific data

struct AuctionDataParams {
    uint256 minPrice;
    uint24 minFillPercent;
    uint256 minBidSize;
    Point publicKey;
}

Properties

Name	Type	Description
minPrice	uint256	The minimum price (in quote tokens) that a bid must fulfill
minFillPercent	uint24	The minimum percentage of capacity that the lot must fill in order to settle. Maximum value = 10000 = 100e2.
minBidSize	uint256	The minimum size of a bid in quote tokens
publicKey	Point	The public key used to encrypt bids

BidParams

Parameters to the bid function

struct BidParams {
    uint256 encryptedAmountOut;
    Point bidPublicKey;
}

Properties

Name	Type	Description
encryptedAmountOut	uint256	The encrypted value of the bid amount out
bidPublicKey	Point	The public key used to encrypt the bid

AuctionData

Struct containing auction-specific data

struct AuctionData {
    uint64 nextBidId;
    uint64 nextDecryptIndex;
    LotStatus status;
    uint64 marginalBidId;
    uint256 marginalPrice;
    uint256 minPrice;
    uint256 minFilled;
    uint256 minBidSize;
    Point publicKey;
    uint256 privateKey;
    uint64[] bidIds;
}

Properties

Name	Type	Description
nextBidId	uint64	The ID of the next bid to be submitted
nextDecryptIndex	uint64	The index of the next bid to decrypt
status	LotStatus	The status of the auction
marginalBidId	uint64	The ID of the marginal bid (marking that bids following it are not filled)
marginalPrice	uint256	The marginal price of the auction (determined at settlement, blank before)
minPrice	uint256
minFilled	uint256	The minimum amount of the lot that must be filled
minBidSize	uint256	The minimum size of a bid in quote tokens
publicKey	Point	The public key used to encrypt bids (a point on the alt_bn128 curve from the generator point (1,2))
privateKey	uint256	The private key used to decrypt bids (not provided until after the auction ends)
bidIds	uint64[]	The list of bid IDs to decrypt in order of submission, excluding cancelled bids

Bid

Core data for a bid

struct Bid {
    address bidder;
    uint96 amount;
    uint96 minAmountOut;
    address referrer;
    BidStatus status;
}

Properties

Name	Type	Description
bidder	address	The address of the bidder
amount	uint96	The amount of the bid
minAmountOut	uint96	The minimum amount out (not set until the bid is decrypted)
referrer	address	The address of the referrer
status	BidStatus	The status of the bid

EncryptedBid

Struct containing data for an encrypted bid

struct EncryptedBid {
    uint256 encryptedAmountOut;
    Point bidPubKey;
}

Properties

Name	Type	Description
encryptedAmountOut	uint256	The encrypted amount out, the bid amount is encrypted with a symmetric key that can be derived from the bidPubKey using the private key for the provided auction public key on the alt_bn128 curve
bidPubKey	Point	The alt_bn128 public key used to encrypt the amount out (see bid() for more details)

PartialFill

Struct containing partial fill data for a lot

struct PartialFill {
    uint64 bidId;
    uint96 refund;
    uint256 payout;
}

Properties

Name	Type	Description
bidId	uint64	The ID of the bid
refund	uint96	The amount to refund to the bidder
payout	uint256	The amount to payout to the bidder

Enums

LotStatus

The status of an auction lot

enum LotStatus {
    Created,
    Decrypted,
    Settled
}

BidStatus

The status of a bid

Bid status will also be set to claimed if the bid is cancelled/refunded

enum BidStatus {
    Submitted,
    Decrypted,
    Claimed
}