Auction Contract in detail

This section walks you through the functions of the Auction contract: what arguments are expected, what are the requirements and what is returned.

File	Type	Proxy
Auction.sol	Singleton	Transparent Proxy

Make a bid

getPriceToPay

function getPriceToPay(
    address _nodeOpAddr,
    uint256[] calldata _discountRates,
    uint256[] calldata _timesInDays
) 
    public
    view
    returns (uint256)

Since the function bid is payable, it is important to check the price to pay beforehand, hence the function getPriceToPay.

Parameters:

• _nodeOpAddr: the address of the operator who will make the bid. The price to pay can vary depending on the whitelist. Whitelisted operators won't have to pay the 1ETH bond per bid. Join the Discord and get in touch the tech team to ask for a whitelisted access.

• _discountRates: as it is possible to make multiple bids in one transaction, an array of discount rates (in percentage from 0 (0%) to 10_000 (100%)) is expected.

• _timesInDays: as it is possible to make multiple bids in one transaction, an array of validation durations (in days) is expected.

Returns:

• The price to pay for the specified bid(s) parameters. The 1ETH bond for each bid is included in the result.

Requirements:

• The two entry arrays must have the same length.

• Every discountRate must be lower than the maxDiscountRate authorized by Byzantine.

• Every timeInDays must be higher than the minDuration authorized by Byzantine.

bid

function bid(
    uint256[] calldata _discountRates,
    uint256[] calldata _timesInDays
) 
    external
    payable
    nonReentrant
    returns (uint256[] memory)

Allows an operator to make one or several bids in a single transaction. If you only want to make one bid, just create an array of size 1.

Parameters:

• msg.value: bid is a payable function. The caller must send the corresponding amount of ETH to cover his bid(s) price(s). Check getPriceToPay for more information. If not enough ETH are sent, the transaction will revert. If to many ETH are sent, the surplus will be returned to the caller.

• _discountRates: as it is possible to make multiple bids, an array of discount rates (in percentage from 0 (0%) to 10000 (100%)) is expected, upscaled to accept up to two percentage decimal points.

• _timesInDays: as it is possible to make multiple bids, an array of validation durations (in days) is expected.

Returns:

• The Auction Scores of each bid. The indexes are respected: the first Auction Score corresponds to the first bid, the second to the second bid, etc.

Requirements:

• The ETH sent in the transaction (msg.value) must be equal or greater than the price to pay for the bid(s).

• The two entry arrays must have the same length.

• Every discountRate must be lower than the maxDiscountRate authorized by Byzantine.

• Every timeInDays must be higher than the minDuration authorized by Byzantine.

Updating a bid

Bids can be updated only one by one. It not possible to update a batch of bids.

getUpdateOneBidPrice

function getUpdateOneBidPrice(
    address _nodeOpAddr,
    uint256 _oldAuctionScore,
    uint256 _newDiscountRate,
    uint256 _newTimeInDays
) 
    public
    view
    returns (uint256)

If the operator decides to update his bid to a higher price, they will have to pay the difference between the new and the last bid price. Thus, it is advised to call this function before calling updateOneBid. If the operator decides to update to a lower bid price, the function will return 0 and, upon calling updateOneBid, the Escrow contract will refund the difference between the last and the new bid price.

Parameters:

• _nodeOpAddr: the address of the operator who wishes to update their bid.

• _oldAuctionScore: the current Auction Score of the bid to update

• _newDiscountRate: the new discountRate (in percentage from 0 (0%) to 10000 (100%)), upscaled to accept up to two percentage decimal points

• _newTimeInDays: the new validavalidation duration (in days)

Returns:

• The amount to add if the operator updates to a higher bid, zero if they update to a lower bid.

Requirements:

• _nodeOpAddr must have at least one bid with Auction Score _oldAuctionScore.

• _newDiscountRate must be lower than the maxDiscountRate authorized by Byzantine.

• _newTimeInDays must be higher than the minDuration authorized by Byzantine.

updateOneBid

function updateOneBid(
    uint256 _oldAuctionScore,
    uint256 _newDiscountRate,
    uint256 _newTimeInDays
) 
    external
    payable
    nonReentrant
    returns (uint256)

Allows an operator to update an existing bid (either by increasing or decreasing the bid).

Parameters:

• msg.value: updateOneBid is a payable function. The caller must send a positive amount of ETH if he outbids. Check getUpdateOneBidPrice for more information. If the caller wants to decrease their bid, msg.value can be set at 0ETH. If too many ETH are sent, the surplus will be returned to the caller.

• _oldAuctionScore: the current Auction Score of the bid to update (this mechanism will change soon as it is difficult to retrieve the Auction Score of an existing bid).

• _newDiscountRate: the new discountRate (in percentage from 0 (0%) to 10_000 (100%))

• _newTimeInDays: the new validation duration (in days)

Returns:

• The new Auction Score of the updated bid.

Requirements:

• The ETH sent in the transation (msg.value) must be equal or greater than the amount to add for the update.

• The caller must have at least one bid with Auction Score _oldAuctionScore.

• _newDiscountRate must be lower than the maxDiscountRate authorized by Byzantine.

• _newTimeInDays must be higher than the minDuration authorized by Byzantine.

Withdrawing a bid

withdrawBid

function withdrawBid(uint256 _auctionScore) external

Allows an operator to withdraw a bid and be refunded of the bid price and the bond.

Entries:

• _auctionScore: the current Auction Score of the bid to withdraw. If several bids made by this operator have the same Auction Score, it refunds the price of the last one.

Requirements:

• The caller must have at least one bid with Auction Score _auctionScore.

Get node operators Auction details

getNodeOpBidNumber

function getNodeOpBidNumber(address _nodeOpAddr) public view returns (uint256)

Returns the number of pending bids of a node operator. If an operator win an auction, his number of pending bids is reduced by 1.

Function getNodeOpAuctionScoreBidPrices

function getNodeOpAuctionScoreBidPrices(
    address _nodeOpAddr,
    uint256 _auctionScore
) public view returns (uint256[] memory)

Returns the price of all bids of a node operator associated to a specific Auction Score.

Entries:

• _nodeOpAddr: the address of the node operator

• _auctionScore: the Auction Score of the bid(s) to retrieve

Note: If _nodeOpAddr doesn't have a bid with _auctionScore, the function returns an empty array.

getNodeOpAuctionScoreVcs

function getNodeOpAuctionScoreVcs(
    address _nodeOpAddr,
    uint256 _auctionScore
) public view returns (uint256[] memory)

Exact same function as getNodeOpAuctionScoreBidPrices, but for the VCs associated to a node operator's bid.

Get Auction configuration parameters

It is possible to access the current Auction configuration parameters by calling the following functions:

numNodeOpsInAuction

function numNodeOpsInAuction() external view returns (uint64)

Returns the number of different node operators that have made a bid and are waiting to join a DV.

expectedDailyReturnWei

function expectedDailyReturnWei() external view returns (uint256)

Returns the expected daily PoS rewards of a full Ethereum validator used to calculate the VC price (in Wei).

maxDiscountRate

function maxDiscountRate() external view returns (uint16)

Returns the maximum operator discount rate authorized by Byzantine (in percentage upscaled by 10e2, so 20% would be returned as 2000).

minDuration

function minDuration() external view returns (uint160)

Returns the minimum validating duration authorized by Byzantine (in days).

clusterSize

function clusterSize() external view returns (uint8)

Returns the number of operators in a DV cluster.