From b4e96bcb1d22345e40581c0f3c8d97404485cf73 Mon Sep 17 00:00:00 2001 From: Sasha <33594434+sasha-computer@users.noreply.github.com> Date: Thu, 2 Apr 2026 10:21:49 +0100 Subject: [PATCH] draft PR for release 1.4 --- provers/broker.mdx | 76 +++++++++++++++++++++++++++++++++++- provers/monitoring.mdx | 13 ++++++ provers/quick-start.mdx | 6 +-- snippets/cli.mdx | 2 +- snippets/release-version.mdx | 2 +- 5 files changed, 93 insertions(+), 6 deletions(-) diff --git a/provers/broker.mdx b/provers/broker.mdx index 61aa442..fe09345 100644 --- a/provers/broker.mdx +++ b/provers/broker.mdx @@ -79,7 +79,7 @@ Below are all `broker.toml` settings organized by section: | 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), "price" (prioritize orders with the highest ETH payment regardless of cycle count). | +| 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. | @@ -93,6 +93,8 @@ Below are all `broker.toml` settings organized by section: | 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 @@ -149,6 +151,78 @@ eth_usd = "auto" zkc_usd = "auto" ``` +**Example per-requestor and per-selector pricing overrides:** + +```toml +[market] +min_mcycle_price = "0.02 USD" + +# Override min_mcycle_price for a specific requestor address +[[market.min_mcycle_price_overrides]] +requestor = "0x1234...abcd" +min_mcycle_price = "0.01 USD" + +# Override min_mcycle_price for a specific program selector +[[market.min_mcycle_price_overrides]] +selector = "aabbccdd" +min_mcycle_price = "0.03 USD" +``` + +### Experimental RPC Optimizations + + +This feature was introduced in [PR #1715](https://github.com/boundless-xyz/boundless/pull/1715) and is experimental. Behavior and flags may change in future releases. + + +The `--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_getBlockByNumber` to follow the chain head and get the base fee +- `eth_getBlockReceipts` to get all receipts and transaction fee data + +The `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 the `BROKER_EXTRA_ARGS` environment variable before starting the broker: + +```bash Terminal +export BROKER_EXTRA_ARGS="--experimental-rpc" +just broker +``` + +You can also configure the RPC request timeout (default 15s) to cut off hanging requests so the retry and fallback layers can activate: + +```bash Terminal +export BROKER_EXTRA_ARGS="--experimental-rpc --rpc-request-timeout 15" +just broker +``` + +If no RPC URLs are provided, the experimental mode defaults to `https://base.gateway.tenderly.co`. + +#### Sequential Fallback Transport + +The experimental RPC mode introduces a `SequentialFallbackTransport` 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](https://github.com/boundless-xyz/protocol-experiments/tree/main/broker-rpc) is available to parse these logs: + +```bash Terminal +RISC0_DEV_MODE=1 \ + RUST_LOG=INFO,broker::chain_monitor_v2=debug,broker::rpcmetrics=debug \ + BROKER_EXTRA_ARGS="--listen-only --experimental-rpc" \ + just broker 2>&1 | tee rpc_metrics.log +``` + + +This feature is experimental. The `eth_getBlockReceipts` RPC method may not be supported by all RPC providers. While it is possible to run with a free public RPC, these can be unreliable — a dedicated RPC provider is recommended for production use. + + ## Broker Operation ```txt Terminal diff --git a/provers/monitoring.mdx b/provers/monitoring.mdx index 47cb9b3..57ec433 100644 --- a/provers/monitoring.mdx +++ b/provers/monitoring.mdx @@ -8,6 +8,19 @@ icon: monitor-waveform For technical support, please post your questions on the [Boundless Discussions Forum](https://github.com/boundless-xyz/boundless/discussions). +## Telemetry + +The broker includes an optional telemetry service that reports anonymized health and performance metrics. When enabled, this helps the Boundless team identify issues, diagnose bugs, and prioritize improvements across the network. Telemetry is designed to be lightweight and non-intrusive — no sensitive data such as private keys or wallet balances is collected. + +Telemetry is **enabled by default**. To opt out, add the following to your `broker.toml`: + +```toml broker.toml +[market] +telemetry_mode = "logsonly" +``` + +This switches to local debug logging only, with no data sent to any remote service. + ## Grafana The Bento / Broker Docker compose stack includes a [Grafana](https://grafana.com/) instance with some template dashboards. To access them, Grafana is hosted at `http://localhost:3000`. Default credentials are defined in `.env.broker-template` as `admin:admin`. diff --git a/provers/quick-start.mdx b/provers/quick-start.mdx index 7b1e339..aa72a89 100644 --- a/provers/quick-start.mdx +++ b/provers/quick-start.mdx @@ -31,7 +31,7 @@ To get started, first clone the Boundless monorepo on your proving machine, and ```bash git clone https://github.com/boundless-xyz/boundless cd boundless -git checkout release-1.2 +git checkout release-1.4 ``` ## Install Dependencies @@ -79,7 +79,7 @@ Boundless is comprised of two major components: To get started with a test proof on a new proving machine, you'll need to install the `bento_cli`: ```bash -cargo install --locked --git https://github.com/boundless-xyz/boundless bento-client --branch release-1.2 --bin bento_cli +cargo install --locked --git https://github.com/boundless-xyz/boundless bento-client --branch release-1.4 --bin bento_cli ``` Once installed, you can run bento with: @@ -112,7 +112,7 @@ Once Bento is running successfully, it is time to configure the [broker](/prover First, install the Boundless CLI (the Boundless CLI is separate to the Bento CLI we installed earlier): ```bash -cargo install --locked --git https://github.com/boundless-xyz/boundless boundless-cli --branch release-1.2 --bin boundless +cargo install --locked --git https://github.com/boundless-xyz/boundless boundless-cli --branch release-1.4 --bin boundless ``` Once installed, run `boundless` to check it has been installed properly: diff --git a/snippets/cli.mdx b/snippets/cli.mdx index f51275a..a0fe975 100644 --- a/snippets/cli.mdx +++ b/snippets/cli.mdx @@ -11,7 +11,7 @@ The Boundless CLI source code can be found at [boundless/crates/boundless-cli](h You'll need to [install Rust](https://doc.rust-lang.org/cargo/getting-started/installation.html), then you can run the following command to install the CLI. ```bash -cargo install --locked --git https://github.com/boundless-xyz/boundless boundless-cli --branch release-1.2 --bin boundless +cargo install --locked --git https://github.com/boundless-xyz/boundless boundless-cli --branch release-1.4 --bin boundless ``` ## Overview diff --git a/snippets/release-version.mdx b/snippets/release-version.mdx index 7f53456..a78b37b 100644 --- a/snippets/release-version.mdx +++ b/snippets/release-version.mdx @@ -1 +1 @@ -export const RELEASE_TAG = "release-1.2"; +export const RELEASE_TAG = "release-1.4";