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

# TimeBoost Vault

> Bid funding and resale payments for express lane access

The TimeBoost Vault is a Stylus contract that manages funds for Arbitrum
[TimeBoost](https://docs.arbitrum.io/how-arbitrum-works/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

```rust theme={"theme":{"light":"dracula","dark":"dracula"}}
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:

| Role          | Address     | Powers                                        |
| ------------- | ----------- | --------------------------------------------- |
| **Owner**     | `owner`     | Withdraw funds, set resale price, record wins |
| **Bid Agent** | `bid_agent` | Record 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

<AccordionGroup>
  <Accordion title="initialize(usdc, bid_agent, resale_price_usdc) -> Result<()>">
    Set the owner, USDC token address, authorized bid agent, and initial resale
    price. Can only be called once.
  </Accordion>

  <Accordion title="deposit_eth() -> Result<()>">
    Deposit ETH into the vault for bidding capital. Payable method -- send ETH
    with the transaction.

    * Emits `Deposited(from, amount, isEth: true)`.
  </Accordion>

  <Accordion title="deposit_usdc(amount) -> Result<()>">
    Deposit USDC into the vault. Requires prior ERC-20 approval.

    * Calls `transferFrom` on the USDC contract.
    * Emits `Deposited(from, amount, isEth: false)`.
  </Accordion>

  <Accordion title="record_round_win(round, bid_cost_wei) -> Result<()>">
    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)`.
  </Accordion>

  <Accordion title="end_round() -> Result<()>">
    Called at the end of a round to reset controller status.

    * Sets `is_express_lane_controller = false`.
  </Accordion>

  <Accordion title="purchase_express_lane_access() -> Result<()>">
    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)`.
  </Accordion>

  <Accordion title="is_authorized_buyer(buyer) -> bool">
    Check if an address has purchased express lane access for the current round.
  </Accordion>

  <Accordion title="set_resale_price(new_price) -> Result<()>">
    Update the resale price. Owner only.

    * Emits `ResalePriceUpdated(oldPrice, newPrice)`.
  </Accordion>

  <Accordion title="withdraw_eth(amount) -> Result<()>">
    Withdraw ETH from the vault. Owner only.

    * Emits `Withdrawn(to, amount, isEth: true)`.
  </Accordion>

  <Accordion title="withdraw_usdc(amount) -> Result<()>">
    Withdraw USDC from the vault. Owner only.

    * Emits `Withdrawn(to, amount, isEth: false)`.
  </Accordion>

  <Accordion title="get_stats() -> Result<(U256, U256, U256, U256, bool)>">
    Returns a snapshot of vault state:

    | Index | Field                      | Type   |
    | ----- | -------------------------- | ------ |
    | 0     | ETH balance                | `U256` |
    | 1     | USDC balance               | `U256` |
    | 2     | Total resale earnings      | `U256` |
    | 3     | Total bid cost             | `U256` |
    | 4     | Is express lane controller | `bool` |
  </Accordion>
</AccordionGroup>

## Events

| Event                | Indexed Fields | Data Fields            |
| -------------------- | -------------- | ---------------------- |
| `Deposited`          | `from`         | `amount`, `isEth`      |
| `Withdrawn`          | `to`           | `amount`, `isEth`      |
| `RoundWon`           | `round`        | `bidCost`              |
| `ResalePurchased`    | `buyer`        | `pricePaid`, `round`   |
| `ResalePriceUpdated` | --             | `oldPrice`, `newPrice` |

## Off-Chain Integration

The vault works in tandem with the `TimeBoostBidder` in the TypeScript layer:

<AccordionGroup>
  <Accordion title="Bid lifecycle">
    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.
  </Accordion>

  <Accordion title="Profit tracking">
    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.
  </Accordion>
</AccordionGroup>

<Tip>
  The resale price is denominated in USDC with 6 decimal places. A value of
  `5_000_000` represents 5 USDC per express lane slot.
</Tip>

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