Skip to main content
The TimeBoost Vault is a Stylus contract that manages funds for Arbitrum TimeBoost express lane bidding and handles payments when reselling express lane access to third parties.

​
Revenue Model

The vault operates on a buy low, resell high model:
  1. The off-chain TimeBoostBidder signals the vault to record a round win at cost X.
  2. While the vault controls the express lane, buyers pay a configurable USDC resale price to purchase access.
  3. The difference between resale earnings and bid costs is the vault’s profit.
Bid cost (ETH) ---> Win express lane ---> Resale access (USDC)
                                             |
                                     Earnings accumulate
                                             |
                                     Owner withdraws profit

​
Storage Layout

sol_storage! {
    #[entrypoint]
    pub struct TimeBoostVault {
        address owner;
        address usdc;                              // USDC token on Arbitrum
        address bid_agent;                         // Authorized bidding agent
        uint256 resale_price_usdc;                 // Price per express lane slot
        bool is_express_lane_controller;           // Current round status
        uint256 current_round;                     // Active round number
        uint256 total_resale_earnings;             // Lifetime USDC earned
        uint256 total_bid_cost;                    // Lifetime ETH spent on bids
        mapping(address => bool) authorized_buyers; // Current round buyers
    }
}

​
Access Control

The vault has two privileged roles:
RoleAddressPowers
OwnerownerWithdraw funds, set resale price, record wins
Bid Agentbid_agentRecord round wins, end rounds
Both the owner and the bid agent can call record_round_win and end_round. Only the owner can withdraw funds and update the resale price.

​
Public Methods

Set the owner, USDC token address, authorized bid agent, and initial resale price. Can only be called once.
Deposit ETH into the vault for bidding capital. Payable method — send ETH with the transaction.
  • Emits Deposited(from, amount, isEth: true).
Deposit USDC into the vault. Requires prior ERC-20 approval.
  • Calls transferFrom on the USDC contract.
  • Emits Deposited(from, amount, isEth: false).
Called by the bid agent when the vault wins an express lane round.
  • Sets is_express_lane_controller = true.
  • Updates current_round and accumulates total_bid_cost.
  • Emits RoundWon(round, bidCost).
Called at the end of a round to reset controller status.
  • Sets is_express_lane_controller = false.
Buyers call this to purchase express lane access for the current round.
  • Reverts if the vault is not the express lane controller.
  • Collects resale_price_usdc USDC from the caller via transferFrom.
  • Adds the caller to authorized_buyers.
  • Accumulates total_resale_earnings.
  • Emits ResalePurchased(buyer, pricePaid, round).
Check if an address has purchased express lane access for the current round.
Update the resale price. Owner only.
  • Emits ResalePriceUpdated(oldPrice, newPrice).
Withdraw ETH from the vault. Owner only.
  • Emits Withdrawn(to, amount, isEth: true).
Withdraw USDC from the vault. Owner only.
  • Emits Withdrawn(to, amount, isEth: false).
Returns a snapshot of vault state:
IndexFieldType
0ETH balanceU256
1USDC balanceU256
2Total resale earningsU256
3Total bid costU256
4Is express lane controllerbool

​
Events

EventIndexed FieldsData Fields
Depositedfromamount, isEth
Withdrawntoamount, isEth
RoundWonroundbidCost
ResalePurchasedbuyerpricePaid, round
ResalePriceUpdated—oldPrice, newPrice

​
Off-Chain Integration

The vault works in tandem with the TimeBoostBidder in the TypeScript layer:
  1. The TimeBoostBidder estimates MEV for the next round and calculates an optimal bid.
  2. It submits the bid to the Arbitrum TimeBoost auction.
  3. On a win, it calls record_round_win(round, bidCostWei) on the vault.
  4. During the round, users can call purchase_express_lane_access to buy resale slots.
  5. At round end, the bidder calls end_round() to reset the controller flag.
The get_stats method provides a real-time view of:
  • Current ETH and USDC balances
  • Lifetime resale earnings vs bid costs
  • Whether the vault currently controls the express lane
The agent uses this data to answer user queries about TimeBoost performance.
The resale price is denominated in USDC with 6 decimal places. A value of 5_000_000 represents 5 USDC per express lane slot.

​
Test Coverage

The contract has 27 tests covering:
  • Initialization and double-init rejection
  • Access control (owner, bid agent, stranger)
  • ETH and USDC deposits with event verification
  • Round win recording and bid cost accumulation
  • Round end and controller reset
  • Express lane purchase (success, unauthorized, not-controller rejection)
  • Authorized buyer tracking before and after purchase
  • Earnings accumulation across multiple purchases
  • Resale price updates (owner only, event emission)
  • ETH and USDC withdrawals (owner only, event emission)
  • Stats reporting with correct values and defaults