Skip to main content

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.

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:

git clone https://github.com/OffchainLabs/orbit-actions.git
cd orbit-actions/scripts/foundry/timeboost

Create and edit the environment configuration file:

cp .env.sample .env

Configure the following parameters in your .env file:

## 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:

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:

cast call --rpc-url=<Your chain's endpoint> <Your ExpressLaneAuction address> "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 guide.

To build only the autonomous-auctioneer component during the local build process:

make target/bin/autonomous-auctioneer

Running Bid Validator Service​

Start the bid validator with:

./autonomous-auctioneer \
--bid-validator.auction-contract-address=<Your ExpressLaneAuction address> \
--bid-validator.sequencer-endpoint=<Your sequencer URL> \
--auctioneer-server.enable=false \
--bid-validator.redis-url=<Your Redis URL> \
--auctioneer-server.db-directory=<Your_bid_validator_db_directory> \
--http.addr=0.0.0.0 \
--http.port=<port>

Running Auction Server Service​

Start the auction server with:

./autonomous-auctioneer \
--auctioneer-server.auction-contract-address=<Your ExpressLaneAuction address> \
--auctioneer-server.db-directory=<Your_auctioneer_server_db_directory> \
--auctioneer-server.redis-url=<Your Redis URL> \
--auctioneer-server.use-redis-coordinator=false \
--auctioneer-server.sequencer-endpoint=<Your sequencer URL> \
--auctioneer-server.wallet.private-key=<Your auctioneer 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:

{
  "http": {
    "api": [
      // existing APIs
      "auctioneer",
      "timeboost"
    ]
  },
  "ws": {
    "api": [
      // existing APIs
      "auctioneer",
      "timeboost"
    ]
  },
  "execution": {
    "sequencer": {
      "timeboost": {
        "enable": true,
        "auction-contract-address": "<Your ExpressLaneAuction address>",
        "auctioneer-address": "<Your auctioneer address>",
        "redis-url": "<Your 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.

A successful bid submission will trigger the auction resolution process and generate the corresponding logs mentioned above.