> ## Documentation Index
> Fetch the complete documentation index at: https://ouroborai.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure TimeBoost

> Set up express lane bidding and MEV estimation

TimeBoost is Arbitrum's express lane mechanism that gives the winning bidder
a 200ms sequencing advantage for each 60-second round. ouroborai includes a
`TimeBoostBidder` that automates round bidding, MEV estimation, and express
lane resale.

## How TimeBoost Works

* Rounds last **60 seconds** each
* Bidding closes **15 seconds** before the next round starts
* Auction is **sealed-bid, second-price** (you pay the second-highest bid)
* The winner can submit transactions via `timeboost_sendExpressLaneTransaction`
* Express lane access can be **resold** to other searchers

## Setup

<Steps>
  <Step title="Initialize the bidder">
    Create a `TimeBoostBidder` instance with your configuration:

    ```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
    import { TimeBoostBidder } from "@arb-agent/timeboost";

    const bidder = new TimeBoostBidder({
      privateKey: "0xYOUR_PRIVATE_KEY",
      rpcUrl: "https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY",
      auctioneerUrl: "https://arb1-auctioneer.arbitrum.io/",
      minProfitThresholdWei: 1_000_000_000_000_000n, // 0.001 ETH minimum
    });
    ```

    Configuration options:

    | Option                  | Type     | Default             | Description                           |
    | ----------------------- | -------- | ------------------- | ------------------------------------- |
    | `privateKey`            | `Hex`    | required            | Wallet key for signing bids           |
    | `rpcUrl`                | `string` | Arbitrum public RPC | JSON-RPC endpoint                     |
    | `auctioneerUrl`         | `string` | Official auctioneer | TimeBoost auctioneer RPC URL          |
    | `minProfitThresholdWei` | `bigint` | `0n`                | Skip rounds below this expected value |
  </Step>

  <Step title="Start the bid loop">
    The bidder continuously monitors round transitions and bids when
    profitable:

    ```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
    await bidder.start();
    ```

    The loop runs every 5 seconds and:

    1. Checks if a new round has started
    2. Estimates expected profit using configured strategies
    3. Fetches the average winning bid from the auctioneer
    4. Caps the bid at 90% of the average to avoid overbidding
    5. Submits the bid if profitable

    Stop the loop with:

    ```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
    bidder.stop();
    ```
  </Step>

  <Step title="Listen for events">
    Register event handlers for round outcomes:

    ```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
    bidder.on("roundWon", (round) => {
      console.log(`Won round ${round} -- executing priority trades`);
      // Submit your time-sensitive transactions here
    });

    bidder.on("roundLost", (round) => {
      console.log(`Lost round ${round}`);
    });

    bidder.on("resaleSold", (slot) => {
      console.log(`Sold express lane access to ${slot.buyer}`);
    });
    ```
  </Step>

  <Step title="Manual bidding (optional)">
    For fine-grained control, bypass the automatic loop and bid manually:

    ```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
    const round = await bidder.getCurrentRound();
    const nextRound = round + 1n;
    const bidAmount = 2_000_000_000_000_000n; // 0.002 ETH

    await bidder.bidForRound(nextRound, bidAmount);
    ```

    <Warning>
      The auctioneer only considers the most recent bid per address per round.
      Submitting a second bid replaces the first.
    </Warning>
  </Step>

  <Step title="Send express lane transactions">
    When you control the express lane, submit transactions with priority
    sequencing:

    ```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
    if (bidder.isExpressLaneController) {
      const txHash = await bidder.sendExpressLaneTransaction(signedTx);
      console.log(`Express lane tx: ${txHash}`);
    }
    ```

    Express lane transactions use the
    `timeboost_sendExpressLaneTransaction` RPC method and bypass the standard
    sequencer queue.
  </Step>

  <Step title="Resell express lane access">
    Monetize winning rounds by reselling access to other searchers:

    ```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
    const slot = await bidder.resellExpressLane(
      "0xBuyerAddress",
      5_000_000n, // 5 USDC
    );
    console.log(`Resale valid until: ${slot.validUntilMs}`);
    ```

    The on-chain `TimeBoostVault` contract handles USDC collection from
    buyers. See [Contract Methods](/docs/reference/contract-methods) for the
    vault's `purchase_express_lane_access` function.
  </Step>
</Steps>

## MEV Estimation

The bidder includes a built-in MEV estimator that calculates expected round
value based on available strategies.

### Per-Strategy Values

| Strategy      | Estimated Value | Risk   |
| ------------- | --------------- | ------ |
| `arb`         | \~0.002 ETH     | Low    |
| `liquidation` | \~0.005 ETH     | Low    |
| `sandwich`    | \~0.0015 ETH    | High   |
| `backrun`     | \~0.0008 ETH    | Medium |
| `resale`      | \~0.003 ETH     | Low    |

### Using the Estimator

```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
const estimatedValue = bidder.estimateRoundValue([
  "arb",
  "liquidation",
  "resale",
]);
console.log(`Expected round value: ${estimatedValue} wei`);
```

The estimator subtracts estimated gas costs (\~0.00002 ETH on Arbitrum) and
applies a historical performance multiplier.

### Historical Calibration

Record actual profits after each won round to improve future estimates:

```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
bidder.recordRoundResult(round, actualProfitWei);
```

The bidder maintains the last 100 round results. The history multiplier
adjusts estimates:

* Fewer than 5 recorded rounds: neutral (1x)
* Average profit below zero: reduces estimates to 0.6x
* Average profit above 0.005 ETH: boosts estimates to 1.2x

### Auctioneer Stats

The bidder periodically fetches aggregate stats from the auctioneer to inform
bidding:

```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
const stats = await bidder.refreshAuctioneerStats();
if (stats) {
  console.log(`Average winning bid: ${stats.avgWinningBidWei} wei`);
  console.log(`Recent rounds tracked: ${stats.recentRounds}`);
}
```

Stats are cached for 5 minutes to avoid excessive RPC calls.