From 2d485a3a686b28c747e0f27c9491cb3675318650 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Mon, 27 Apr 2026 15:17:41 -0700 Subject: [PATCH 1/8] remove deprecated minimum bid query method --- docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx index 73b7602aef..c2653be788 100644 --- a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx +++ b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx @@ -152,12 +152,6 @@ When bids get submitted to the autonomous auctioneer endpoint, we need to send a - the amount in `wei` of the deposit `ERC-20` token to bid - signature (explained below) - - -The amount to bid must be above the minimum reserve price at the moment you are bidding. This parameter is configurable per chain. You can obtain the minimum reserve price by calling the method `minReservePrice()(uint256)` in the `Auction` contract. - - - Let's see an example of a call to this RPC method: ```tsx From f9b0d8a4292bf48b0bcaa9dbae55cd5b790b3f46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Mon, 27 Apr 2026 15:32:53 -0700 Subject: [PATCH 2/8] add instructions to query the reserve pricer API --- .../timeboost/how-to-use-timeboost.mdx | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx index c2653be788..a244ecea94 100644 --- a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx +++ b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx @@ -22,6 +22,19 @@ A round's express lane controller, at their choice, can still send transactions +## How to query the Reserve Pricer API + +Any auction participant submitting a bid must first know the minimum acceptable bid amount for the round being bid on. The Timeboost Reserve Pricer API exposes this data publicly over HTTP, returning the current reserve price and the round it applies to. Query this API before submitting any bid. + +The reserve price is updated at the 31st second of every minute. + +### Endpoints + +The API exposes two endpoints: + +- `/api/latest` returns the newest reserve price and round. +- `/api/recent` returns the reserve price and rounds for the last two hours. + ## How to submit bids for the right to be the express lane controller To use the express lane for faster transaction inclusion, you must win an auction for the right to be the express lane controller for a specific round. @@ -143,6 +156,12 @@ Remember that, by default, auctions for a given round open 60 seconds before tha Once we know the current round, we can bid for (`currentRound + 1`) and verify that the auction is still open (`!currentAuctionRoundIsClosed`), then we can submit a bid. +:::tip Fetching the minimum bid amount + +Before submitting a bid, query the [Reserve Pricer API](#how-to-query-the-reserve-pricer-api) to retrieve the minimum acceptable bid amount for the round you're bidding on. + +::: + When bids get submitted to the autonomous auctioneer endpoint, we need to send an `auctioneer_submitBid` request with the following information: - chain id From 01436c1d52487a1a5afa9de4e1bec472ee530ad3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Mon, 27 Apr 2026 15:46:15 -0700 Subject: [PATCH 3/8] remove unnecessary viem prerequisite --- .../timeboost/how-to-use-timeboost.mdx | 31 ++++++++++++++++--- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx index a244ecea94..c9dbb6603c 100644 --- a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx +++ b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx @@ -5,14 +5,11 @@ author: jose-franco content_type: how-to --- -Timeboost is a new transaction ordering policy for Arbitrum chains. With Timeboost, anyone can bid for the right to access an express lane on the **Sequencer** for faster transaction inclusion. +Timeboost is a transaction ordering policy for Arbitrum chains. With Timeboost, anyone can bid for the right to access an express lane on the **Sequencer** for faster transaction inclusion. In this how-to, you'll learn how to bid for the right to use the express lane and submit transactions through the express lane. To learn more about Timeboost and the key terms used on this page, refer to the [gentle introduction](/how-arbitrum-works/timeboost/gentle-introduction.mdx). -This how-to assumes that you're familiar with the following: - -- [How Timeboost works](/how-arbitrum-works/timeboost/gentle-introduction.mdx) -- [viem](https://viem.sh/), since the snippets of code present in the how-to use this library +This how-to assumes that you're familiar with [How Timeboost works](/how-arbitrum-works/timeboost/gentle-introduction.mdx) @@ -73,6 +70,8 @@ Before bidding on an auction, we need to deposit funds in the auction contract. To see the amount of tokens we have deposited in the auction contract, we can call the function `balanceOf` in the `Auction` contract: ```tsx +// Code example uses viem + const depositedBalance = await publicClient.readContract({ address: auctionContractAddress, abi: auctionContractAbi, @@ -85,6 +84,8 @@ console.log(`Current balance of ${userAddress} in auction contract: ${depositedB If we want to deposit more funds to the `Auction` contract, we first need to know what the bidding token is. To obtain the address of the bidding token, we can call the function `biddingToken` in the `Auction` contract: ```tsx +// Code example uses viem + const biddingTokenContractAddress = await publicClient.readContract({ address: auctionContractAddress, abi: auctionContractAbi, @@ -102,6 +103,8 @@ On Arbitrum One and Arbitrum Nova, the default bidding token is `WETH`. Once we know what the bidding token is, we can deposit funds to the auction contract by calling the function `deposit` of the contract after having it approved as spender of the amount we want to deposit: ```tsx +// Code example uses viem + // Approving spending tokens const approveHash = await walletClient.writeContract({ account, @@ -130,6 +133,8 @@ Once we have deposited funds into the auction contract, we can submit bids for t We can obtain the current round by calling the function `currentRound` in the `Auction` contract: ```tsx +// Code example uses viem + const currentRound = await publicClient.readContract({ address: auctionContractAddress, abi: auctionContractAbi, @@ -141,6 +146,8 @@ console.log(`Current round: ${currentRound}`); The above shows the current round that's running. At the same time, the auction for the next round might be open. For example, if the `currentRound` is 10, the auction for round 11 is currently happening. To check whether or not that auction is open, we can call the function `isAuctionRoundClosed` of the `Auction` contract: ```tsx +// Code example uses viem + let currentAuctionRoundIsClosed = await publicClient.readContract({ address: auctionContractAddress, abi: auctionContractAbi, @@ -174,6 +181,8 @@ When bids get submitted to the autonomous auctioneer endpoint, we need to send a Let's see an example of a call to this RPC method: ```tsx +// Code example uses viem + const currentAuctionRound = currentRound + 1; const hexChainId: `0x${string}` = `0x${Number(publicClient.chain.id).toString(16)}`; @@ -208,6 +217,8 @@ The signature that needs to be sent is an [EIP-712](https://eips.ethereum.org/EI Here's an example to produce that signature with viem: ```tsx +// Code example uses viem + const currentAuctionRound = currentRound + 1; const signatureData = hashTypedData({ @@ -276,6 +287,8 @@ event SetExpressLaneController( Here's an example to get the log from the auction contract to determine the new express lane controller: ```tsx +// Code example uses viem + const fromBlock = const logs = await publicClient.getLogs({ address: auctionContractAddress, @@ -318,6 +331,8 @@ Timeboost doesn't currently support the `eth_sendRawTransactionConditional` meth Let's see an example of a call to this RPC method: ```tsx +// Code example uses viem + const hexChainId: `0x${string}` = `0x${Number(publicClient.chain.id).toString(16)}`; const transaction = await walletClient.prepareTransactionRequest(...); @@ -357,6 +372,8 @@ The required signature is an Ethereum signature that needs to be sent with the f Here's an example to produce that signature: ```tsx +// Code example uses viem + const hexChainId: `0x${string}` = `0x${Number(publicClient.chain.id).toString(16)}`; const transaction = await walletClient.prepareTransactionRequest(...); @@ -457,6 +474,8 @@ Funds are deposited in the auction contract to have the right to bid in auctions To initiate a withdrawal, we can call the function `initiateWithdrawal` in the `Auction` contract: ```tsx +// Code example uses viem + const initWithdrawalTransaction = await walletClient.writeContract({ account, address: auctionContractAddress, @@ -481,6 +500,8 @@ In this event, the `account` is the address from which we will withdraw funds, ` After two rounds have passed, we can call the method `finalizeWithdrawal` in the `Auction` contract to finalize the withdrawal: ```tsx +// Code example uses viem + const finalizeWithdrawalTransaction = await walletClient.writeContract({ account, address: auctionContractAddress, From 7d8bfd5aa4500439fa1bfcf8458796d7bd242c3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Mon, 27 Apr 2026 15:50:11 -0700 Subject: [PATCH 4/8] remove cancelled lane controller transferring logic --- .../timeboost/how-to-use-timeboost.mdx | 56 +------------------ 1 file changed, 1 insertion(+), 55 deletions(-) diff --git a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx index c9dbb6603c..72fee8a41d 100644 --- a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx +++ b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx @@ -13,9 +13,7 @@ This how-to assumes that you're familiar with [How Timeboost works](/how-arbitru -Please note that in the initial release of Timeboost, transferring control of the express lane via either the `setTransferor` or the `transferExpressLaneController` will not be supported by the Arbitrum Nitro node software at launch and may be implemented at a future date via a regular node upgrade. Calls made to these two functions on the auction contract will be successful, but the node software (including the Sequencer) will not recognize the actual rights transfer. - -A round's express lane controller, at their choice, can still send transactions signed by others on a per-transaction basis, as explained later in this guide. +A round's express lane controller, at their choice, can send transactions signed by others on a per-transaction basis, as explained later in this guide. @@ -415,58 +413,6 @@ If you are not the express lane controller and you try to submit a transaction t ::: - - ## How to withdraw funds deposited in the auction contract Funds are deposited in the auction contract to have the right to bid in auctions. Withdrawing funds is possible through a two-step process: initiate the withdrawal, wait for two rounds, and then finalize the withdrawal. From 4d3c058f8a199aa0242520e81973f6ba4c007282 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Mon, 27 Apr 2026 16:01:04 -0700 Subject: [PATCH 5/8] replace instructions as a step --- .../timeboost/how-to-use-timeboost.mdx | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx index 72fee8a41d..59cbb6c0dc 100644 --- a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx +++ b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx @@ -17,19 +17,6 @@ A round's express lane controller, at their choice, can send transactions signed -## How to query the Reserve Pricer API - -Any auction participant submitting a bid must first know the minimum acceptable bid amount for the round being bid on. The Timeboost Reserve Pricer API exposes this data publicly over HTTP, returning the current reserve price and the round it applies to. Query this API before submitting any bid. - -The reserve price is updated at the 31st second of every minute. - -### Endpoints - -The API exposes two endpoints: - -- `/api/latest` returns the newest reserve price and round. -- `/api/recent` returns the reserve price and rounds for the last two hours. - ## How to submit bids for the right to be the express lane controller To use the express lane for faster transaction inclusion, you must win an auction for the right to be the express lane controller for a specific round. @@ -124,7 +111,20 @@ const depositHash = await walletClient.writeContract({ console.log(`Deposit transaction sent: ${depositHash}`); ``` -### Step 2: Submit bids +### Step 2: query the reserve pricer API + +Any auction participant submitting a bid must first know the minimum acceptable bid amount for the round being bid on. The Timeboost Reserve Pricer API exposes this data publicly over HTTP, returning the current reserve price and the round it applies to. Query this API before submitting any bid. + +The reserve price is updated at the 31st second of every minute. + +#### Endpoints + +The API exposes two endpoints: + +- `/api/latest` returns the newest reserve price and round. +- `/api/recent` returns the reserve price and rounds for the last two hours. + +### Step 3: submit bids Once we have deposited funds into the auction contract, we can submit bids for the current auction round. @@ -163,7 +163,7 @@ Once we know the current round, we can bid for (`currentRound + 1`) and verify t :::tip Fetching the minimum bid amount -Before submitting a bid, query the [Reserve Pricer API](#how-to-query-the-reserve-pricer-api) to retrieve the minimum acceptable bid amount for the round you're bidding on. +Before submitting a bid, query the [Reserve Pricer API](how-to-query-the-reserve-pricer-api) to retrieve the minimum acceptable bid amount for the round you're bidding on. ::: @@ -265,7 +265,7 @@ When sending the request, the autonomous auctioneer will return an empty result | `RESERVE_PRICE_NOT_MET` | Bid amount does not meet the minimum required reserve price onchain | | `INSUFFICIENT_BALANCE` | The bid amount specified in the request is higher than the deposit balance of the depositor in the contract | -### Step 3: find out the winner of the auction +### Step 4: find out the winner of the auction After the auction closes and before the round starts, the autonomous auctioneer will call the auction contract with the two highest bids received, allowing the contract to declare the winner and deduct the second-highest bid from the winner's deposited funds. After this, the contract will emit an event with the new Express Lane Controller address. From 0184bc8292a555c3ae3c2ada37ab8c0dbf27cf19 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Mon, 27 Apr 2026 16:03:02 -0700 Subject: [PATCH 6/8] remove "table" from headers --- .../how-arbitrum-works/timeboost/how-to-use-timeboost.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx index 59cbb6c0dc..754e1a16ce 100644 --- a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx +++ b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx @@ -40,7 +40,7 @@ Before we begin, make sure you have: The following table shows this information for the Arbitrum DAO-owned chains: -#### Table 1: Timeboost reference URLs and addresses +#### Timeboost reference URLs and addresses | Network | Auction contract | Autonomous auctioneer endpoint | | ---------------- | ----------------------------------------------------------------------------- | ------------------------------------------ | @@ -253,7 +253,7 @@ You can also call the function `getBidHash` in the auction contract to obtain th When sending the request, the autonomous auctioneer will return an empty result with an HTTP status `200` if received correctly. If the result returned contains an error message, something went wrong. Following are some of the error messages that can help us understand what's happening: -#### Table 2: Errors relating to bid submission +#### Errors relating to bid submission | Error | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------- | @@ -392,7 +392,7 @@ const signature = await account.signMessage({ When sending the request, the sequencer will return an empty result with an HTTP status `200` if it received it correctly. If the result returned contains an error message, something went wrong. Following are some of the error messages that can help us understand what's happening: -#### Table 3: Errors relating to express lane transaction submission +#### Errors relating to express lane transaction submission Note that if you get any of the errors below, then the sequence number used in your express lane transaction was _not_ consumed. | Error | Description | @@ -492,7 +492,7 @@ In the sequencer feed, the `BroadcastFeedMessage` struct now contains a `blockMe In the current implementation, information about the winning bid for a resolved auction emits via the `AuctionResolved` event ([sample interface](https://github.com/OffchainLabs/nitro-contracts/blob/main/src/express-lane-auction/IExpressLaneAuction.sol#L95-L103)). Historical bid information, including the round number and bid amounts, are published to a public S3 bucket at a regular cadence. The domain for the S3 bucket where historical bids get saved is: -#### Table 4: S3 URLs for historical bid data +#### S3 URLs for historical bid data :::info URL updates for historical bid data On June 9 2025, at around 17:27 ET (UTC−05:00), the region in which the Amazon S3 bucket for historical bid data on Arbitrum One was _changed_ from `s3://timeboost-auctioneer-arb1/uw2/validated-timeboost-bids/` to `s3://timeboost-auctioneer-arb1/ue2/validated-timeboost-bids/`. The below table has been updated for the new, correct URL to access bid data after June 9, 2025 17:27 ET, but if you require data from before June 9, 2025 17:27 ET, then please use `s3://timeboost-auctioneer-arb1/uw2/validated-timeboost-bids/`. From 2980989d0ebb28fbc52a332e38d0c81ddc5341e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Mon, 27 Apr 2026 17:09:45 -0700 Subject: [PATCH 7/8] delete broken link --- docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx index 754e1a16ce..00029c76ce 100644 --- a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx +++ b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx @@ -163,7 +163,7 @@ Once we know the current round, we can bid for (`currentRound + 1`) and verify t :::tip Fetching the minimum bid amount -Before submitting a bid, query the [Reserve Pricer API](how-to-query-the-reserve-pricer-api) to retrieve the minimum acceptable bid amount for the round you're bidding on. +Before submitting a bid, query the reserve pricer API to retrieve the minimum acceptable bid amount for the round you're bidding on. ::: From c2e1e994dd53aebce56cdbe11a771d5754c7501a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Tue, 26 May 2026 12:18:53 -0700 Subject: [PATCH 8/8] Add Reserve Pricer API base URLs and curl examples (vbridge-hash review) Addresses review comment on docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx#L121 by vbridge-hash on PR #3242. The Endpoints section listed the relative paths /api/latest and /api/recent but never gave the per-network base URLs, so a reader couldn't actually call the API. Adds: - A per-network table with the Sepolia and Arbitrum One base URLs (arbsepolia-reserve-pricer.arbitrum.io and arb1-reserve-pricer.arbitrum.io), matching the style of the auctioneer table earlier in the file. - A shell example showing curl against /api/latest for both networks. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../timeboost/how-to-use-timeboost.mdx | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx index deba8cc71b..1bac6502f7 100644 --- a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx +++ b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx @@ -119,11 +119,28 @@ The reserve price is updated at the 31st second of every minute. #### Endpoints -The API exposes two endpoints: +The API exposes two endpoints over HTTPS: - `/api/latest` returns the newest reserve price and round. - `/api/recent` returns the reserve price and rounds for the last two hours. +The base URL differs per network: + +| Network | Base URL | +| ---------------- | ----------------------------------------------- | +| Arbitrum Sepolia | `https://arbsepolia-reserve-pricer.arbitrum.io` | +| Arbitrum One | `https://arb1-reserve-pricer.arbitrum.io` | + +For example, to fetch the latest reserve price and round: + +```shell +# Arbitrum One +curl https://arb1-reserve-pricer.arbitrum.io/api/latest + +# Arbitrum Sepolia +curl https://arbsepolia-reserve-pricer.arbitrum.io/api/latest +``` + ### Step 3: submit bids Once we have deposited funds into the auction contract, we can submit bids for the current auction round.