diff --git a/arbitrum-docs/launch-orbit-chain/02-configure-your-chain/advanced-configurations/04-deploy-timeboost.mdx b/arbitrum-docs/launch-orbit-chain/02-configure-your-chain/advanced-configurations/04-deploy-timeboost.mdx new file mode 100644 index 0000000000..c3ac98b027 --- /dev/null +++ b/arbitrum-docs/launch-orbit-chain/02-configure-your-chain/advanced-configurations/04-deploy-timeboost.mdx @@ -0,0 +1,188 @@ +--- +title: 'Deploy and configure Timeboost for your chain' +sidebar_label: 'Deploy and configure Timeboost' +description: 'Learn how to deploy and configure Timeboost' +user_story: As a current or prospective Orbit chain owner, I need to understand how to deploy and configure Timeboost +content_type: how-to +--- + +# Enabling Timeboost for Your Orbit Chain + +This guide walks you through the process of enabling Timeboost for your Arbitrum Orbit chain. For a conceptual introduction to Timeboost, see the [Timeboost Introduction](https://docs.arbitrum.io/how-arbitrum-works/timeboost/gentle-introduction). + +## Prerequisites + +Before starting, ensure you have: + +1. An ERC20 token address to use as the bid token +2. A Redis server for auctioneer coordination +3. A server to run the auctioneer service +4. A proxy admin contract address + +## Overview + +Enabling Timeboost requires completing these three steps: + +1. Deploy the `ExpressLaneAuction` contract +2. Run Auctioneer Services (bid validator and auction server) +3. Configure your sequencer node to support Timeboost + +## Step 1: Deploy the `ExpressLaneAuction` Contract + +First, clone the orbit-actions repository: + +```bash +git clone https://github.com/OffchainLabs/orbit-actions.git +cd orbit-actions/scripts/foundry/timeboost +``` + +Create and edit the environment configuration file: + +```bash +cp .env.sample .env +``` + +Configure the following parameters in your `.env` file: + +```bash +## Configuration for DeployExpressLaneAuction.s.sol +PROXY_ADMIN_ADDRESS= # Your proxy admin contract address +AUCTIONEER_ADDRESS= # Address that will send resolve auction requests +BIDDING_TOKEN_ADDRESS= # Your ERC20 bid token address +BENEFICIARY_ADDRESS= # Address to receive bid proceeds +AUCTIONEER_ADMIN_ADDRESS= # Admin address for the auctioneer +MIN_RESERVE_PRICE_SETTER_ADDRESS= # Address allowed to set minimum reserve price +RESERVE_PRICE_SETTER_ADDRESS= # Address allowed to set reserve price +RESERVE_PRICE_SETTER_ADMIN_ADDRESS=# Admin for reserve price setter +BENEFICIARY_SETTER_ADDRESS= # Address allowed to change beneficiary +ROUND_TIMING_SETTER_ADDRESS= # Address allowed to adjust round timing +MASTER_ADMIN_ADDRESS= # Master admin address + +MIN_RESERVE_PRICE=0 # Minimum price for bids (0 recommended for testing) + +# Round timing configuration (in seconds) +ROUND_DURATION_SECONDS=60 # Total duration of each round +AUCTION_CLOSING_SECONDS=15 # Time before round end when new bids are closed +RESERVE_SUBMISSION_SECONDS=15 # Time allocated for reserve price submission +``` + +Deploy the contract: + +```bash +forge script --sender $DEPLOYER --rpc-url $CHILD_CHAIN_RPC --slow ./DeployExpressLaneAuction.s.sol -vvv --verify --broadcast +# Use --account XXX / --private-key XXX / --interactive / --ledger to specify the transaction signer +``` + +Verify successful deployment by checking that the contract returns your configured bid token: + +```bash +cast call --rpc-url= "biddingToken()(address)" +# Example output: 0xYourBidTokenAddress +``` + +## Step 2: Run Auctioneer Services + +There are two distinct services to run: the bid validator and the auction server. The bid validator verifies submitted bids, while the auction server sends the winning bid on-chain. + +### Prerequisites + +The services require the `autonomous-auctioneer` binary, which is included in the Nitro Docker image. Alternatively, you can build it locally by following the [Build Nitro Locally](https://docs.arbitrum.io/run-arbitrum-node/nitro/build-nitro-locally) guide. + +To build only the `autonomous-auctioneer` component during the local build process: + +```bash +make target/bin/autonomous-auctioneer +``` + +### Running Bid Validator Service + +Start the bid validator with: + +```bash +./autonomous-auctioneer \ +--bid-validator.auction-contract-address= \ +--bid-validator.sequencer-endpoint= \ +--auctioneer-server.enable=false \ +--bid-validator.redis-url= \ +--auctioneer-server.db-directory= \ +--http.addr=0.0.0.0 \ +--http.port= +``` + +### Running Auction Server Service + +Start the auction server with: + +```bash +./autonomous-auctioneer \ +--auctioneer-server.auction-contract-address= \ +--auctioneer-server.db-directory= \ +--auctioneer-server.redis-url= \ +--auctioneer-server.use-redis-coordinator=false \ +--auctioneer-server.sequencer-endpoint= \ +--auctioneer-server.wallet.private-key= \ +--bid-validator.enable=false +``` + +## Step 3: Configure Your Sequencer Node for Timeboost + +Update your sequencer node configuration to enable Timeboost functionality. Add the following new config to your sequencer node's configuration file: + +```json +{ + "http": { + "api": [ + // existing APIs + "auctioneer", + "timeboost" + ] + }, + "ws": { + "api": [ + // existing APIs + "auctioneer", + "timeboost" + ] + }, + "execution": { + "sequencer": { + "timeboost": { + "enable": true, + "auction-contract-address": "", + "auctioneer-address": "", + "redis-url": "" + } + } + } +} +``` + +## Verifying Your Timeboost Setup + +There are multiple ways to confirm that Timeboost is correctly enabled on your chain: + +### Periodic Startup Logs + +When you start your sequencer with Timeboost enabled, you'll see periodic logs indicating the start of new express lane auction rounds: + +``` +New express lane auction round +``` + +This log indicates that the Timeboost mechanism is active and running normally. + +### Transaction Processing Confirmation + +After finishing a bid request, look for messages in your sequencer logs such as: + +``` +AuctionResolved: New express lane controller assigned round +``` + +This message confirms that your sequencer is processing express queue transactions from the express lane controller, and Timeboost is functioning correctly. + +### User Interaction Verification + +Users can interact with Timeboost by submitting bids through the `auctioneer_submitBid` endpoint of your auctioneer service. For detailed instructions on how users can interact with Timeboost, see [How to Use Timeboost](https://docs.arbitrum.io/how-arbitrum-works/timeboost/how-to-use-timeboost). + +A successful bid submission will trigger the auction resolution process and generate the corresponding logs mentioned above. diff --git a/arbitrum-docs/launch-orbit-chain/timeboost-for-orbit.mdx b/arbitrum-docs/launch-orbit-chain/timeboost-for-orbit.mdx new file mode 100644 index 0000000000..826349215a --- /dev/null +++ b/arbitrum-docs/launch-orbit-chain/timeboost-for-orbit.mdx @@ -0,0 +1,91 @@ +--- +title: 'Timeboost for Orbit chains' +sidebar_label: 'Timeboost for Orbit chains' +description: 'Guidance & best practices for using Timeboost on Orbit chains' +user_story: 'As a developer or researcher of the Arbitrum product suite, I want to learn about Timeboost, a new transaction ordering policy for Arbitrum chains' +content_type: release announcement +author: leeederek +sme: leeederek +--- + +:::info PUBLIC PREVIEW DOCUMENT + +This document is currently in **public preview** and may change significantly as feedback is captured from readers like you. Click the **Request an update** button at the top of this document or [join the Arbitrum Discord](https://discord.gg/arbitrum) to share your feedback. + +::: + +## Launch details and key dates + +- **Status:** Alpha - not formally supported yet for deployments on Orbit chains +- **Arbitrum Sepolia**: Feb 12, 2025 +- **Arbitrum One**: April 17, 2025{' '} +- **Arbitrum Nova**: April 17, 2025{' '} + +## tldr; + +Arbitrum Timeboost is a novel transaction ordering policy that +can be optionally deployed and enabled for any Arbitrum chain. Timeboost allows a chain owner to capture +some of the available Maximum Extractable Value (MEV) on their blockchain and reduces latency-related +spamming, in exchange for a small impact on user response times (despite block times not changing). It +is therefore recommended that chains only consider deploying and enabling Timeboost if there is substantial +DeFi and related MEV activity (e.g. liquidations, arbitrage, backrunning) on the chain. Please read the +[gentle introduction to Timeboost](../how-arbitrum-works/timeboost/gentle-introduction.mdx) to learn +more about how Timeboost works. + +As with all features on the Arbitrum stack, Orbit chains can adopt Timeboost at their own discretion and on their own timeline. To deploy and enable Arbitrum Timeboost on your chain, please refer to this guide on how to [deploy and configure Timeboost](../launch-orbit-chain/02-configure-your-chain/advanced-configurations/04-deploy-timeboost.mdx). + +## Recommended adoption path + +It is recommended that most Orbit chains **do not** deploy Arbitrum Timeboost, as the benefits do not outweigh the trade-offs in most cases. The primary reason behind this recommendation is based on cost and user experience considerations. The only instances in which Timeboost might make sense are for chains with significant DeFi and related MEV activity, as the potential revenue from bids may outweigh the costs and possible impact on user experience. + +Again, Orbit chains can adopt Timeboost at their discretion and on their timeline, so this is only a recommendation.f + +## Benefits of adopting Timeboost + +Timeboost enables a chain owner to capture a portion of the available MEV on their blockchain, reducing latency-related spam while preserving the built-in protections and UX benefits that Arbitrum users have come to know and enjoy. A more in-depth overview of the benefits of Timeboost is explored in the [gentle introduction to Timeboost](../how-arbitrum-works/timeboost/gentle-introduction.mdx), and also a paper on how Timeboost is more profitable for arbitrageurs compared to other forms of MEV capture, like Priority Gas Auctions (PGA) [here](https://arxiv.org/abs/2410.10797). + +#### Fair(er) MEV capture + +Timeboost provides sophisticated actors (e.g., searchers) with the ability to purchase a fixed time advantage over a specified number of blocks to perform various MEV activities, such as backrunning, liquidations, or arbitrage. This design preserves the use of a private mempool that all Arbitrum chains have by default, and it does not impact block times. This approach protects users from harmful types of MEV (e.g., frontrunning) while maintaining the same block times. + +#### Potential revenue capture for chain owners + +The auction, run at a fixed cadence, is held off-chain. Bids can be made in any asset the chain owner designates, including custom `ERC-20` tokens. Furthermore, the chain owner has full discretion over how to use the bid proceeds. For example, chain owners may decide to burn the bid proceeds or use the bid proceeds to support the chain in other ways. + +It stands to reason that sophisticated actors (e.g., searchers) will bid up to the amount they believe they can profit or realize from the time advantage. Therefore, at equilibrium, one could reasonably expect that the bid proceeds will approach or equal the amount of available MEV on a Timeboost-enabled chain. + +#### Potential reduction in latency-based spam + +As explained earlier, searchers will be incentivized to bid on-chain for the time advantage, rather than spending money on off-chain hardware to win latency races. Therefore, at equilibrium, one could reasonably expect that the amount of latency-based spam should reduce on a Timeboost-enabled chain. To learn more about this phenomenon, please check out this analysis on how the Timeboost ordering policy impacts backrunning strategies: [TimeBoost and Backrunning: Probabilistic Strategies](https://research.arbitrum.io/t/timeboost-and-backrunning-probabilistic-strategies/9727). + +## Trade offs with adopting Timeboost + +As mentioned earlier, chain owners should consider several trade-offs when deciding whether to adopt Timeboost. We will cover two of them below. + +#### Cost + +As explained in the guide on [how to deploy and configure Timeboost](../launch-orbit-chain/02-configure-your-chain/advanced-configurations/04-deploy-timeboost.mdx), there are are three core components to Timeboost: + +- An off-chain auctioneer (responsible for receiving and validating bids, and resolving express lane auctions), +- An on-chain smart contract (to manage the express lane auction), and +- A new configuration on the sequencer is implemented to take advantage of the express lane time. + +Often times, the cost required to set up, configure, and maintain the infrastructure above (especially the auctioneer) will exceed that of the potential revenue that Timeboost brings in. Most importantly, the revenue that Timeboost can generate for the chain is _not guaranteed_ either. + +#### User experience + +As explained in the [gentle introduction to Timeboost](../how-arbitrum-works/timeboost/gentle-introduction.mdx), the Timeboost express lane time advantage is implemented by imposing an artificial delay (default: `200ms`) on all non-express lane transactions whenever there is an express lane controller for a round (default: `1 minute`). While Timeboost does not change the default Arbitrum blocktimes (default: `250ms`), this artificial delay _does_ mean that the average response time for a user in the non-express lane is the sum of the artificial delay and the block time of the chain. Note that this artificial delay is only applied when there is an express lane controller for a round, meaning there is no change in user experience if nobody is using Timeboost, even though it is enabled (for the duration of that round). + +## Configuring Timeboost's Parameters + +Below is a table of the configurable parameters and how to think about adjusting their values, should you choose to deploy and enable Timeboost for your chain. + +| Parameter name | Description | Considerations | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `roundDurationSeconds` | Time during which the sequencer will honor the express lane privileges for transactions signed by the current round’s express lane controller. Default: 60 seconds | The larger this value, the more powerful and valuable controlling the express lane will be. Higher values may incentivize more participation and demand for the express lane time advantage. | +| `auctionClosingSeconds` | Time before the start of the next round. The autonomous auctioneer will not accept bids during this time interval. Default: 15 seconds | The larger the value, the more difficult it is for participants to predict the value of the future express lane round, and therefore, their ability and confidence in being able to place an accurate/fair bid for the time advantage. However, a value that is too small may not allow the auctioneer sufficient time to resolve the auction on time during periods of high activity. | +| `beneficiary` | An address where proceeds from the Timeboost auction are sent to when `flushBeneficiaryBalance()` gets called on the auction contract. Default: An address controlled by the chain's owner | Can be any address, including the burn address, that the chain owner designates or controls. | +| `_biddingToken` | Address of the token used to make bids in the Timeboost auction. It can be any `ERC-20` token, including the gas token of the network, provided the chosen token address does not have fee-on-transfer, rebasing, transfer hooks, or otherwise non-standard `ERC-20` logic. Default: `WETH` | This asset should ideally be liquid and easily obtainable for your auction participants. Furthermore, the less volatile this asset is, the more consistent your auction will be. | +| `nonExpressDelayMsec` | The artificial delay applied, by the sequencer, to the arrival timestamp on non-express lane transactions _before_ the non-express lane transactions eventually get sequenced. Default: 0.2 seconds, or 200 milliseconds | The larger this value, the greater the time advantage will be for the express lane controller, making it easier for the express lane controller to capture MEV opportunities (e.g., backrunning, liquidations, or arbitrage) and therefore the more valuable. However, increasing this value comes at the expense of slower response times for user transactions in the non-express lane. | +| `reservePrice` | The minimum bid amount accepted by the auction contract for Timeboost auctions, denominated in `_biddingToken`. Default: None | This value should be left empty and only be changed to raise the minimum bid post-deployment of the auction contract (see below). | +| `_minReservePrice` | A value that must be equal to or below the `reservePrice` to act as a "floor price" for Timeboost bids. Enforced by the auction contract. Default: 0.001 `WETH` | A value that is low enough to make the auction worth while participating in, but not high enough to pose a significant barrier to entry (i.e. ideally, chain owners will want a fair, competitive market for the timeboost time advantage). This value can also be set high such that if someone does bid, the bid proceeds could offset some of the costs spent on running the autonomous auctioneer. | diff --git a/stylus-by-example b/stylus-by-example index 01738fe1f2..a4ea27d6d6 160000 --- a/stylus-by-example +++ b/stylus-by-example @@ -1 +1 @@ -Subproject commit 01738fe1f24f64c0d22eceda1b542bfeeca6e521 +Subproject commit a4ea27d6d6268d506e22e3c505d088763d03239f diff --git a/website/sidebars.js b/website/sidebars.js index 91851a0ad0..951d5335f5 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -325,6 +325,11 @@ const sidebars = { id: 'launch-orbit-chain/configure-your-chain/advanced-configurations/fast-withdrawals', label: `Enable fast withdrawals`, }, + { + type: 'doc', + id: 'launch-orbit-chain/configure-your-chain/advanced-configurations/deploy-timeboost', + label: `Deploy and configure Timeboost`, + }, { type: 'doc', id: 'launch-orbit-chain/configure-your-chain/advanced-configurations/bold', @@ -548,6 +553,11 @@ const sidebars = { id: 'launch-orbit-chain/concepts/custom-gas-token-sdk', label: 'Custom gas token SDK', }, + { + type: 'doc', + id: 'launch-orbit-chain/timeboost-for-orbit', + label: 'Timeboost for Orbit chains', + }, { type: 'doc', id: 'launch-orbit-chain/bold-adoption-for-orbit-chains', @@ -1078,6 +1088,20 @@ const sidebars = { label: 'Troubleshoot Timeboost', id: 'how-arbitrum-works/timeboost/troubleshoot-timeboost', }, + { + type: 'html', + value: + 'Deploy Timeboost ↑', + // q: why use an anchor html tag here? + // a: see note at end of file + }, + { + type: 'html', + value: + 'Timeboost for Orbit chains↑', + // q: why use an anchor html tag here? + // a: see note at end of file + }, { type: 'link', href: 'https://github.com/OffchainLabs/timeboost-design/blob/main/research_spec.md', @@ -1093,6 +1117,11 @@ const sidebars = { href: 'https://arxiv.org/abs/2306.02179', label: 'White paper: Timeboost', }, + { + type: 'link', + href: 'https://arxiv.org/abs/2410.10797', + label: 'MEV Capture Through Time-Advantaged Arbitrage', + }, ], }, ],