From 7ad7fd1f7b3cbe2873fcd81fb8cd867e77c1ac27 Mon Sep 17 00:00:00 2001 From: Vitalii Drohan Date: Mon, 4 May 2026 15:36:34 +0200 Subject: [PATCH 1/5] priority updates intro --- docs/api.mdx | 50 +++++++++++++++++++++++++++++++++++++++++ docs/send-orderflow.mdx | 1 + 2 files changed, 51 insertions(+) diff --git a/docs/api.mdx b/docs/api.mdx index cbda37f..625d4bb 100644 --- a/docs/api.mdx +++ b/docs/api.mdx @@ -9,6 +9,7 @@ BuilderNet provides these APIs to send orderflow: - [`eth_sendBundle`](#eth_sendbundle) - [`eth_sendRawTransaction`](#eth_sendrawtransaction) +- [Priority updates](#priority-updates) - [TEE Proof Validation API (aTLS)](#tee-proof-validation-api-atls) --- @@ -196,6 +197,55 @@ The response contains the transaction hash: --- +### Priority updates + +A priority update is a transaction that BuilderNet includes only if either: +- it's configured to land at the top of the next block, **or** +- its post-state is read by another transaction in the same block (e.g. a taker trade matching a quoted price). + +The mode is set per API key. + +This is intended for operators of proprietary AMMs to publish quote updates with low replacement latency. Access requires an API key, granted on request. + +#### Endpoints + +Priority updates are submitted over WebSocket on the same hosts as the JSON-RPC endpoints (see [BuilderNet endpoints](send-orderflow#buildernet-endpoints)) at the path `/ws/sendquoteupdate`, e.g. `wss://rpc.buildernet.org/ws/sendquoteupdate`. + +#### Request + +Messages are protobuf-encoded: + +```proto +message PWebsocketQuoteUpdateV1Args { + bytes tx = 1; // RLP-encoded quote tx (empty for cancellation) + uint64 block_number = 2; // Target block + bytes replacement_uuid = 3; // 16-byte quote identifier + uint64 replacement_seq_number = 4; // Monotonic sequence (>0) + bool disable_cross_region_sharing = 5; +} +``` + +**Replacement and cancellation:** +- **Replace**: send a new message with the same `replacement_uuid` and a higher `replacement_seq_number`. +- **Cancel**: same as replace, but with an empty `tx`. + +#### Response + +```proto +message PWebsocketQuoteUpdateV1Response { + bytes replacement_uuid = 1; + uint64 replacement_seq_number = 2; + uint64 timestamp = 3; // RPC receive time (UNIX nanos) + string error = 4; // Error details on failure +} +``` + +#### Authentication + +Set the API key in the `Authorization` header when establishing the WebSocket connection. + +--- + ### TEE Proof Validation API (aTLS) BuilderNet uses attested TLS (aTLS) to verify the attestation of specific builder node instances. diff --git a/docs/send-orderflow.mdx b/docs/send-orderflow.mdx index 6f8dd22..11387eb 100644 --- a/docs/send-orderflow.mdx +++ b/docs/send-orderflow.mdx @@ -37,6 +37,7 @@ See [TEE proof validation](#tee-attestation) for details. 1. [`eth_sendBundle`](https://docs.flashbots.net/flashbots-auction/advanced/rpc-endpoint#eth_sendbundle) 3. [`eth_sendRawTransaction`](https://docs.metamask.io/wallet/reference/json-rpc-methods/eth_sendrawtransaction/) +4. [Priority updates](api#priority-updates) — for operators of proprietary AMMs (WebSocket, requires an API key) See also the [API reference](api) for more details on the API methods. From ea834a001322cf17c5df93c9983d6d18e031d7cc Mon Sep 17 00:00:00 2001 From: Vitaly Drogan Date: Fri, 15 May 2026 12:04:10 +0200 Subject: [PATCH 2/5] Update docs/api.mdx Co-authored-by: Quintus <47097067+quintuskilbourn@users.noreply.github.com> --- docs/api.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/api.mdx b/docs/api.mdx index 625d4bb..63b3933 100644 --- a/docs/api.mdx +++ b/docs/api.mdx @@ -199,7 +199,9 @@ The response contains the transaction hash: ### Priority updates -A priority update is a transaction that BuilderNet includes only if either: +A priority update is a transaction that is given precedence to write to specific onchain storage before any other transaction accesses the same state. This is intended to enable actively managed liquidity systems like PropAMMs, but can be used for any system which requires prioritisation of certain onchain actions over others. + +Depending on configuration, BuilderNet can conditionally included the priority update if and only if there is another transaction which attempts to access the same state in the block (e.g. a taker trading against the actively managed pool). This is a gas optimisation feature. - it's configured to land at the top of the next block, **or** - its post-state is read by another transaction in the same block (e.g. a taker trade matching a quoted price). From 945d2533dc88988dd77ab1dab024414a1eb7b26c Mon Sep 17 00:00:00 2001 From: Vitalii Drohan Date: Fri, 15 May 2026 13:01:32 +0200 Subject: [PATCH 3/5] manual apply comments --- docs/api.mdx | 14 ++++++++------ docs/send-orderflow.mdx | 4 ++-- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/api.mdx b/docs/api.mdx index 63b3933..cebadb6 100644 --- a/docs/api.mdx +++ b/docs/api.mdx @@ -199,15 +199,17 @@ The response contains the transaction hash: ### Priority updates -A priority update is a transaction that is given precedence to write to specific onchain storage before any other transaction accesses the same state. This is intended to enable actively managed liquidity systems like PropAMMs, but can be used for any system which requires prioritisation of certain onchain actions over others. +A priority update is a transaction that BuilderNet includes ahead of other transactions accessing the same state. This can be used by smart contracts to ensure that some interactions are prioritized ahead of others (e.g. for maker vs. taker prioritization). -Depending on configuration, BuilderNet can conditionally included the priority update if and only if there is another transaction which attempts to access the same state in the block (e.g. a taker trading against the actively managed pool). This is a gas optimisation feature. -- it's configured to land at the top of the next block, **or** -- its post-state is read by another transaction in the same block (e.g. a taker trade matching a quoted price). +Priority update transactions must post data via the [Priority Update Registry](https://github.com/flashbots/priority-update-registry). -The mode is set per API key. +These updates can be configured in one of two modes: +* **Top-of-Block:** to land at the **top of the next block** +* **Conditional:** to land only on the condition that another transaction reading the update is also included in the same block. Conditional updates are not guaranteed to be at the top of the block. This is an experimental gas savings feature subject to change. Currently, inclusion is not triggered by reads that occur in reverting call frames. -This is intended for operators of proprietary AMMs to publish quote updates with low replacement latency. Access requires an API key, granted on request. +When multiple updates for the same state are available at the time a block is built, the builder will prioritise the latest update. + +The mode is set per API key, which can be granted on request. This requirement may be dropped in future. Operators needing both modes can request multiple keys. #### Endpoints diff --git a/docs/send-orderflow.mdx b/docs/send-orderflow.mdx index 11387eb..72ddb9f 100644 --- a/docs/send-orderflow.mdx +++ b/docs/send-orderflow.mdx @@ -36,8 +36,8 @@ See [TEE proof validation](#tee-attestation) for details. ### Supported API methods 1. [`eth_sendBundle`](https://docs.flashbots.net/flashbots-auction/advanced/rpc-endpoint#eth_sendbundle) -3. [`eth_sendRawTransaction`](https://docs.metamask.io/wallet/reference/json-rpc-methods/eth_sendrawtransaction/) -4. [Priority updates](api#priority-updates) — for operators of proprietary AMMs (WebSocket, requires an API key) +2. [`eth_sendRawTransaction`](https://docs.metamask.io/wallet/reference/json-rpc-methods/eth_sendrawtransaction/) +3. [Priority updates](api#priority-updates) — for operators of proprietary AMMs (WebSocket, requires an API key) See also the [API reference](api) for more details on the API methods. From d95cc1116dc2173b2e42365d0b111301794850a4 Mon Sep 17 00:00:00 2001 From: Vitalii Drohan Date: Fri, 15 May 2026 13:02:41 +0200 Subject: [PATCH 4/5] remove call frme sentence --- docs/api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api.mdx b/docs/api.mdx index cebadb6..d6525f5 100644 --- a/docs/api.mdx +++ b/docs/api.mdx @@ -205,7 +205,7 @@ Priority update transactions must post data via the [Priority Update Registry](h These updates can be configured in one of two modes: * **Top-of-Block:** to land at the **top of the next block** -* **Conditional:** to land only on the condition that another transaction reading the update is also included in the same block. Conditional updates are not guaranteed to be at the top of the block. This is an experimental gas savings feature subject to change. Currently, inclusion is not triggered by reads that occur in reverting call frames. +* **Conditional:** to land only on the condition that another transaction reading the update is also included in the same block. Conditional updates are not guaranteed to be at the top of the block. This is an experimental gas savings feature subject to change. When multiple updates for the same state are available at the time a block is built, the builder will prioritise the latest update. From dcd1c5e14a23ba9dda377c6fa814a62933cba664 Mon Sep 17 00:00:00 2001 From: Vitaly Drogan Date: Fri, 15 May 2026 19:25:45 +0200 Subject: [PATCH 5/5] Update api.mdx Co-authored-by: Quintus <47097067+quintuskilbourn@users.noreply.github.com> --- docs/api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api.mdx b/docs/api.mdx index d6525f5..e829ad5 100644 --- a/docs/api.mdx +++ b/docs/api.mdx @@ -209,7 +209,7 @@ These updates can be configured in one of two modes: When multiple updates for the same state are available at the time a block is built, the builder will prioritise the latest update. -The mode is set per API key, which can be granted on request. This requirement may be dropped in future. Operators needing both modes can request multiple keys. +The mode is set per API key, which can be granted on request (see [How to participate](how-to-participate)). This requirement may be dropped in future. Operators needing both modes can request multiple keys. #### Endpoints