Overview
The Broker is a service that runs within the Bento proving stack. It is responsible for market interactions including bidding on jobs, locking them, issuing job requests to the Bento proving cluster, and submitting proof fulfillments onchain.Broker Configuration
Broker configuration is primarily managed through thebroker.toml file in the Boundless directory. This file is mounted into the Broker container and it is used to configure the Broker daemon.
Deposit / Balance
The Boundless market requires funds (ZKC) deposited as collateral before a prover can bid on requests. Brokers must first deposit some ZKC into the market contract to fund their account. These funds cover collateral during lock-in. It is recommend that a broker keep a balance on the market >=max_collateral (configured via broker.toml).
Deposit Collateral to the Market
You will need the Boundless CLI installed to deposit/check your balance.
Please see Installing the Boundless CLI for instructions.
Terminal
Check Current Collateral Balance
Terminal
PRIVATE_KEY environment variable here and specify your wallet_address as a optional parameter to the balance command, i.e., account balance 0x000....
Settings in Broker.toml
Below are allbroker.toml settings organized by section:
[market] Settings
| Setting | Description |
|---|---|
| min_mcycle_price | The minimum price per mega-cycle (i.e. million RISC-V cycles) for the broker to attempt to lock an order. Accepts "<value> ETH" (e.g., "0.00002 ETH") or "<value> USD" (e.g., "0.02 USD"); USD values are converted to ETH at runtime via the price oracle. Plain numbers without a suffix still work and default to ETH for backward compatibility. This value is used for both primary orders (compared against the order’s ETH price per mcycle) and secondary fulfillment orders (converted to ZKC via price oracle for collateral-based comparisons). |
| expected_probability_win_secondary_fulfillment | Expected probability (as a percentage) of winning a secondary fulfillment proof race. When another prover fails to fulfill an order and is slashed, multiple provers may race to fulfill the order for the collateral reward. This setting scales the expected reward of those lock-expired orders by the configured percentage before comparing against min_mcycle_price. Default: 50. Values below 100 discount the reward (conservative — fewer secondary orders picked up), 100 means no discount, values above 100 boost the reward (aggressive — more secondary orders picked up). |
| priority_requestor_addresses | Optional priority requestor addresses that can bypass the mcycle limit and max input size limit. If enabled, the order will be preflighted without constraints. |
| priority_requestor_lists | URLs to fetch requestor priority lists from. Requestor priority lists specify requestors that the broker should prioritize for proving. Requestors on these lists are considered more likely to request useful work with profitable pricing. Priority requestors are prioritized when there is a surplus of demand: their requests will be preflighted first, locked first (in situations where multiple orders exceed minimum lock pricing), and configuration for max_mcycle_limit and max_file_size will be skipped. These lists will be periodically refreshed and merged with priority_requestor_addresses. |
| peak_prove_khz | Estimated peak performance of the proving cluster, in kHz. Used to estimate proving capacity and accept only as much work as your prover cluster can handle. Estimates can be derived from benchmarking using the Boundless CLI. See Benchmarking Bento. |
| max_mcycle_limit | Optional max cycles (in mcycles). Orders over this max_cycles will be skipped after preflight. |
| max_journal_bytes | Max journal size in bytes. Orders that produce a journal larger than this size in preflight will be skipped. Since journals must be posted onchain to complete an order, an excessively large journal may prevent completion of a request. |
| min_deadline | Min seconds left before the deadline to consider bidding on a request. If there is not enough time left before the deadline, the prover may not be able to complete proving of the request and finalize the batch for publishing before expiration. |
| lookback_blocks | On startup, the number of blocks to look back for possible open orders. |
| max_collateral | Maximum collateral amount that the broker will use to lock orders. Accepts "<value> ZKC" (e.g., "200 ZKC") or "<value> USD" (e.g., "100 USD"); USD values are converted to ZKC at runtime via the price oracle. Requests that require a higher collateral amount than this will be skipped. |
| max_file_size | Max input / image file size allowed for downloading from request URLs. |
| max_fetch_retries | Max retries for fetching input / image contents from URLs. |
| assessor_default_image_url | Default URL for assessor image. This URL will be tried first before falling back to the image URL from the boundless market contract. |
| set_builder_default_image_url | Default URL for set builder image. This URL will be tried first before falling back to the image URL from the set verifier contract. |
| max_concurrent_proofs | Maximum number of concurrent proofs that can be processed at once. Used to limit proof tasks spawned to prevent overwhelming the system. |
| max_concurrent_preflights | Maximum number of orders to concurrently preflight. Used to limit preflight tasks spawned to prevent overwhelming the system. Recommended default: 8 to be able to follow all market orders. |
| order_pricing_priority | Determines how orders are prioritized for pricing. Options: “random” (default, process orders in random order), “observation_time” (prioritize orders in the order they were observed, FIFO), “shortest_expiry” (prioritize orders with the earliest deadline first). |
| order_commitment_priority | Determines how orders are prioritized when committing to prove them. Options: “cycle_price” (default, prioritize orders with the highest ETH price per cycle), “random” (process orders in random order), “shortest_expiry” (prioritize orders with the earliest deadline first), “tightest_deadline” (prioritize orders whose deadline is closest, giving preference to the most time-urgent work), “price” (prioritize orders with the highest ETH payment regardless of cycle count). |
| max_critical_task_retries | Max critical task retries on recoverable failures. The broker service has a number of subtasks. Some are considered critical. If a task fails, it will be retried, but after this number of retries, the process will exit. |
| allow_client_addresses | Optional allow list for customer address. If enabled, all requests from clients not in the allow list are skipped. |
| deny_requestor_addresses | Optional deny list for requestor address. If enabled, all requests from clients in the deny list are skipped. |
| lockin_priority_gas | Optional additional gas to add to the transaction for lockinRequest, good for increasing the priority if competing with multiple provers during the same block. |
| balance_warn_threshold | Optional balance warning threshold (in native token). If the submitter balance drops below this the broker will issue warning logs. |
| balance_error_threshold | Optional balance error threshold (in native token). If the submitter balance drops below this the broker will issue error logs. |
| collateral_balance_warn_threshold | Optional collateral balance warning threshold (in collateral tokens). If the collateral balance drops below this the broker will issue warning logs. |
| collateral_balance_error_threshold | Optional collateral balance error threshold (in collateral tokens). If the collateral balance drops below this the broker will issue error logs. |
| cache_dir | Optional cache directory for storing downloaded images and inputs. If not set, files will be re-downloaded every time. |
| lockin_gas_estimate | Gas estimate for lockin call. Used for estimating the gas costs associated with an order during pricing. If not set a conservative default will be used. |
| fulfill_gas_estimate | Gas estimate for fulfill call. Used for estimating the gas costs associated with an order during pricing. If not set a conservative default will be used. |
| groth16_verify_gas_estimate | Gas estimate for proof verification using the RiscZeroGroth16Verifier. Used for estimating the gas costs associated with an order during pricing. If not set a conservative default will be used. |
| max_order_expiry_secs | Maximum order expiry duration in seconds (current time to order expiry time). Orders exceeding this duration are skipped. Prevents orders with long deadlines from tying up resources or storing inputs beyond MinIO’s TTL. |
| min_mcycle_price_overrides | Optional per-requestor and per-selector overrides for min_mcycle_price. Allows fine-grained pricing control so you can set different minimum prices for specific requestors or program selectors. See example below. |
| telemetry_mode | Controls broker telemetry reporting. "full" (default) sends anonymized health and performance metrics to help the Boundless team diagnose issues across the network. No sensitive data (private keys, wallet balances) is collected. Set to "logsonly" to disable remote reporting and only emit local debug logs. |
[prover] Settings
| Setting | Description |
|---|---|
| status_poll_retry_count | Number of retries to poll for proving status. Provides a little durability for transient failures. |
| status_poll_ms | Polling interval to monitor proving status (in millisecs). |
| req_retry_count | Number of retries to query a prover backend for on failures. Used for API requests to a prover backend, creating sessions, preflighting, uploading images, etc. Provides a little durability for transient failures. |
| req_retry_sleep_ms | Number of milliseconds to sleep between retries. |
| proof_retry_count | Number of retries for running the entire proof generation process. This is separate from the request retry count, as the proving process is a multi-step process involving multiple API calls to create a proof job and then polling for the proof job to complete. |
| proof_retry_sleep_ms | Number of milliseconds to sleep between proof retries. |
| set_builder_guest_path | Set builder guest program (ELF) path. When using a durable deploy, set this to the published current SOT guest program path on the system. |
| assessor_set_guest_path | Assessor ELF path. |
| reaper_interval_secs | Interval for checking expired committed orders (in seconds). This is the interval at which the ReaperTask will check for expired orders and mark them as failed. If not set, it defaults to 60 seconds. |
| reaper_grace_period_secs | Grace period before marking expired orders as failed (in seconds). This provides a buffer time after an order expires before the reaper marks it as failed. This helps prevent race conditions with the aggregator that might be processing the order. If not set, it defaults to 10800 seconds (3 hours). |
[batcher] Settings
| Setting | Description |
|---|---|
| batch_max_time | Max batch duration before publishing (in seconds). |
| min_batch_size | Batch size (in proofs) before publishing. |
| block_deadline_buffer_secs | Batch blocktime buffer. Number of seconds before the lowest block deadline in the order batch to flush the batch. This should be approximately snark_proving_time * 2. |
| txn_timeout | Timeout, in seconds for transaction confirmations. |
| single_txn_fulfill | Use the single TXN submission that batches submit_merkle / fulfill_batch into a single transaction. Requires the submitRootAndFulfill method be present on the deployed contract. |
| withdraw | Whether to withdraw from the prover balance when fulfilling. |
| batch_poll_time_ms | Polling time, in milliseconds. The time between polls for new orders to aggregate and how often to check for batch finalize conditions. |
| batch_max_journal_bytes | Max combined journal size (in bytes) that once exceeded will trigger a publish. |
| batch_max_fees | Max batch fees (in ETH) before publishing. |
| max_submission_attempts | Number of attempts to make to submit a batch before abandoning. |
[price_oracle] Settings
The price oracle fetches live ETH/USD and ZKC/USD exchange rates, enabling broker config values to be specified in USD. Chainlink (on-chain, ETH/USD only) and CoinGecko (off-chain, both pairs) are enabled by default; CoinMarketCap is optionally available with an API key. Prices from multiple sources are aggregated using the configuredaggregation_mode.
| Setting | Description |
|---|---|
| eth_usd | Price source for ETH/USD. "auto" (default) uses live oracle prices. Set to a static number (e.g., "2500.00") to fix the price and disable live fetching. |
| zkc_usd | Price source for ZKC/USD. "auto" (default) uses live oracle prices. Set to a static number (e.g., "1.00") to fix the price and disable live fetching. |
| refresh_interval_secs | How often to refresh prices from sources, in seconds (default: 60). |
| aggregation_mode | How to combine prices from multiple sources: "median" (default), "priority" (use first available source), or "average". |
| max_secs_without_price_update | Maximum seconds without a successful price update before the broker logs an error (default: 43200 / 12h). Set to 0 to disable this check. |
Experimental RPC Optimizations
This feature was introduced in PR #1715 and is experimental. Behavior and flags may change in future releases.
--experimental-rpc flag replaces the standard two-service monitoring architecture (ChainMonitorService + MarketMonitor) with a single unified ChainMonitorV2. Instead of polling eth_getLogs for market events on every tick, the ChainMonitorV2 uses eth_getBlockReceipts to fetch all receipts per block in a single call, then filters for market events locally. This significantly reduces the number of RPC calls — especially on chains like Base where eth_getLogs can be expensive or rate-limited.
In steady state, the experimental monitor requires roughly 2 RPC requests per block:
eth_getBlockByNumberto follow the chain head and get the base feeeth_getBlockReceiptsto get all receipts and transaction fee data
ChainMonitorV2 also performs local EIP-1559 gas estimation from receipt data, removing the need for separate eth_feeHistory calls.
On startup, the ChainMonitorV2 uses adaptive log retrieval with binary-search chunking to auto-discover the maximum block range accepted by the RPC provider, catching up on any missed events for open orders. This means the broker won’t miss events if it restarts or experiences downtime.
Enabling Experimental RPC
To enable, set theBROKER_EXTRA_ARGS environment variable before starting the broker:
Terminal
Terminal
https://base.gateway.tenderly.co.
Sequential Fallback Transport
The experimental RPC mode introduces aSequentialFallbackTransport that tries RPC providers in priority order (rather than in parallel), minimizing calls to paid or metered fallback endpoints. When multiple RPC URLs are configured, the transport includes health tracking: it skips providers after consecutive failures and periodically retries them to detect recovery.
The retry and fallback layers are stacked so that on a single RPC failure, the sequential fallback immediately tries the next URL. The outer retry layer only kicks in once all URLs have been exhausted.
Analyzing RPC Usage
To analyze RPC call patterns, enable debug logging for the relevant modules and pipe the output to a log file. An analysis script is available to parse these logs:Terminal
Broker Operation
Terminal
Benchmarking Bento
Start a bento cluster:Terminal
RPC_URL environment variable to the network the order is on:
Terminal
Terminal
Running the Broker service with bento
Running a broker withjust will also start the Bento cluster through docker compose.
just installation instructions can be found here.Terminal
Make sure Bento is running
To check Bento is running correctly, you can send a sample proof workload:Before running this, install Bento CLI
Terminal
Running a standalone broker
To run broker with an already initialized Bento cluster or with a different prover, you can build and run a broker directly with the following:Terminal
Stopping The Broker Service
Terminal
Safe Upgrade Steps
When upgrading your Boundless broker to a new version, follow these steps to ensure a safe migration:Stop the broker and optionally clean the database
Terminal
While it is generally not necessary to clear volumes unless specifically noted in release, it is recommended to avoid any potential state breaking changes.
Update to the new version
See releases for latest tag to use.
Terminal
Running Multiple Brokers
You can run multiple broker instances simultaneously to serve different networks at the same time while sharing the same Bento cluster. The Docker compose setup supports this through thebroker2 service example.
Multi-Broker Configuration
Each broker instance requires:- Separate configuration file: Create different
broker.tomlfiles (e.g.,broker.toml,broker2.toml, etc.) - Different RPC URL: Use different chain endpoints via setting respective
RPC_URLenvironment variables, or modifying thecompose.ymlmanually. - Optional separate private key: Use different
PRIVATE_KEYvariables if desired for different accounts on different networks.
Environment Variables for Multi-Broker Setup
If using the defaultcompose.yml file and uncommenting the second broker config:
[.env]
Terminal
- The
peak_prove_khzsetting is shared across all brokers- For example, if you have benchmarked your broker to be able to prove at 500kHz, the values in each config should not sum up to be more than 500kHz.
max_concurrent_preflightsdefaults to8and should be set to a value that the bento cluster can keep up with- It is recommended that the max concurrent preflights across all networks is less than the number of exec agents you have specified in your
compose.yml.
- It is recommended that the max concurrent preflights across all networks is less than the number of exec agents you have specified in your
max_concurrent_proofsis a per-broker configuration, and is not shared across brokers
Terminal
Broker Optimization
Increasing Lock-in Rate
Once your broker is running, there are a few methods to optimize the lock-in rate. These methods are aimed at making your broker service more competitive in the market through different means:- Decreasing the
min_mcycle_pricewould tune your Broker to bid at lower prices for proofs. This value can be specified in ETH (e.g.,"0.00001 ETH") or USD (e.g.,"0.02 USD"). - Increasing
lockin_priority_gasexpedites your market operations by consuming more gas which could help outrun other bidders.
Tuning Service Settings
The[prover] settings in broker.toml are used to configure the prover service and significantly impact the operation of the service. The most important configuration variable to monitor and iteratively tune is txn_timeout. This is the number of seconds to wait for a transaction to be confirmed before timing out. Therefore, if you see timeouts in your logs, txn_timeout can be increased to wait longer for transaction confirmations onchain.