Set up the Auction

Overview

Why is the auction important?

Each request specifies a set of request parameters; these parameters specify the request ID, the proof requirements, the URL for the relevant guest program and its inputs, and the auction parameters.

This guide helps requestors understand, configure and optimize their requests via these auction parameters. Requestors, who understand these auction parameters, will be able to more effectively tailor their request auctions to current market conditions. This is essential for getting timely and cost-effective proofs.

What are the auction parameters?

The auction parameters determine how the auction is executed, and therefore how provers respond to the request. Concretely, they specify the parameters of the reverse Dutch auction. This is the mechanism by which the requestor and prover can agree upon a price, and helps ensure the requestor receives the best price available from the market.

Where are these auction parameters specified?

The recommended method to request a proof is via the Boundless SDK (see Request a Proof). The Boundless SDK sets some sensible defaults which should work for most testing purposes, however it is recommended to adjust the auction parameters via the with_offer() method.

It is also possible to request a proof directly using the CLI. This requires a valid request.yaml file which specifies the auction parameters under offer.

What auction parameters are configurable?

Example request walkthrough

This sections walks through a typical proof request from the perspective of a requestor. It uses the recommendations listed below to set sensible auction parameters. Boundless is an open market and these static recommendations may not reflect the current state of the market. It is recommended to set auction parameters conservatively and adjust them, based on required latency and price, only once these test requests are being fulfilled regularly.

Estimate relevant times based on program size

For this example request, the guest program being proven is 500MCycles. To calculate the estimated execution and proving times, this calculator assumes an average market execution speed of 30MHz and an average market proving speed of 1MHz; these assumptions can be modified in the calculator under "Advanced Settings". Therefore, for 500MCycles, the estimated execution time is ~17 seconds (rounding up) and the estimated proving time is ~500 seconds.

Setting latency sensitive parameters

Using the table for suggested latency sensitive parameters, the following parameters are set based on the estimated execution and proving time:

• "Ramp Up Start" is set to 5 * 17s = 85s.
• "Ramp Up Period" is set to 10 x 17s = 170s ~= 85 blocks (assuming Base mainnet blocktime is ~2 seconds).
• "Lock Timeout" is set to 1.25 x 500s = 625s.
• "Timeout" is set to 3 x 500s = 1500s.

Setting price sensitive parameters

Using the table for suggested price sensitive parameters, the following parameters are set based on the estimated execution and proving time:

• "Minimum Price" is set to 0.0001 ETH (100000000000000 wei), which is around $0.40 with 1 ETH = $4000.
• "Maximum Price" is set to 0.00025 ETH (250000000000000 wei), which is around $1 with 1 ETH = $4000. This is about $0.2 ETH per GCycle.
• "Lock Collateral" is set to 10 x maxPrice ~= $10 worth of ZKC which is around 20 ZKC at $0.5 per ZKC. ZKC uses 18 decimal places like ETH, so 20 ZKC is specified with 20000000000000000000.

Auction walkthrough

These auction parameters can be set in the request.yaml file, which is used when requesting a proof with the CLI. This is recommended only for testing purposes to get a feel for the sensitivity of each auction parameter on the request fulfillment rate.

Therefore, the example requests auction parameters are:

offer:
    minPrice: 100000000000000 # 0.0001 ETH
    maxPrice: 250000000000000 # 0.00025 ETH
    lockCollateral: 20000000000000000000 # 20 ZKC
    rampUpStart: 85 # seconds
    rampUpPeriod: 85 # blocks
    lockTimeout: 625 # 10 minutes 25 seconds
    timeout:  1500 # 25 minutes

Once the request is submitted to the market, the auction will follow the auction parameters as specified in this diagram:

• Once the request is processed, and the order is created, the order is surfaced to the market and the auction begins.
• For 85 seconds (specified by rampUpStart), the order will be at the minimum price (minPrice). This time allows for provers to see the request, and run checks on the request (known as a preflight)¹. During this 85 second period, provers can lock the order at the minimum price (remember that, at any time, any prover locking the order successfully will close the auction).
• At 85 seconds, the "ramp up period" begins. During this timeframe, the auction price grows linearly from the minimum price to the maximum price of 0.00025 ETH, over the span of 85 blocks (~170 seconds on Base mainnet).
• After the "ramp up period", the price remains at the maximum price until the primary prover deadline (the "lock timeout" of 10 minutes 25 seconds since the ramp up start).
• If the prover who locked the order (the primary prover) does not fulfill by this deadline, they will be slashed. This means that they will lose their proving collateral for this order; 50% of it will be burned and 50% of it will go to a secondary prover.
• After the "lock timeout", a race amongst secondary provers begins. They have until the "timeout" (25 minutes from the ramp up start, or just under 15 minutes from the primary prover deadline) to fulfill the request otherwise the order expires. The first prover to win this race will receive 50% of the order's proving collateral as a reward; this reward is sent directly to the collateral balance of the winning secondary prover.

What should requestors know about provers?

Provers can lock a request at any time before the "lock timeout". When a prover locks a request, they are agreeing to be paid the price set at the time of their bid. They are also agreeing to be slashed if they do not fulfill the request before the "lock timeout". In this case, if the request was locked but not fulfilled in time, the order is slashed and the prover loses their "lock collateral". Concretely, 50% of the "lock collateral" is burned and 50% is allocated to the first prover who fulfills the proof, after the "lock timeout" but before the "timeout"; this prover is known as the secondary prover. The reward for the winning secondary prover is sent directly to the collateral balance of the winning secondary prover.

Setting optimal auction parameters

Time Calculator

Based on current average execution and proving MHz, this calculator will estimate the execution and proving time of a request:

For the following recommendations, the estimated execution and proving times will be labelled as estimated_execution_time and estimated_proving_time respectively.

The following two sections detail some recommended guidelines when setting the auction parameters. These guidelines are formulas, and they are to be taken with a pinch of salt. Please remember to start conservatively when tuning each parameter. Provers have to respond and some may set their pricing strategy based on each requestor's standard request profile. Therefore, it is recommended to change auction parameters in small increments during testing, and only change auction parameters again once proof fulfillment becomes stable.

Latency sensitive parameters

Each requestor will have a different latency tolerance; some might be fine with receiving a proof on the scale of hours, whereas others will have more time-critical applications and require proof fulfillment on the scale of minutes. These latency requirements should dictate how requestors set the time-based auction parameters.

Price sensitive parameters

The price of a request determines how competitively provers bid on the request, and therefore how quickly the request is locked.