Overview

Vif is an ultra-efficient, fully on-chain order book protocol that combines innovative design patterns to deliver optimal performance and user experience.

Core Design Principles

The protocol is built on three fundamental pillars:

1. Efficient Price Discovery with Tick Trees

Vif uses a 3-level 256-bit bitmap tree to efficiently locate active price points in the order book. This structure allows for:

• O(1) best price lookup - Finding the best available price requires checking at most 3 bitmaps
• Efficient price traversal - Moving to the next price point is extremely gas-efficient
• Compact storage - The entire tree fits in a fixed-size array of 1 + 256 + 256*256 elements

2. Flash Accounting System

Instead of transferring tokens on every operation, Vif uses transient storage to track debts and credits:

// All these operations only update transient storage:
- Market orders
- Limit orders
- Claiming orders
- Cancelling orders
- Cleaning expired offers
 
// Only these operations transfer tokens:
- Settling debts (settle)
- Taking credits (take)
- Clearing dust (clear)

• Batch multiple operations without any token transfers until final settlement
• Free flash loans - Borrow any amount as long as you settle before the lock ends
• Multi-hop swaps without intermediate transfers
• Gas savings - Net all operations before transferring tokens

3. Double Linked Offer Lists

At each price point (tick), offers are organized in a double linked list with:

• Head and tail pointers for efficient insertion/removal
• Total volume tracking at each price level
• Offer count for analytics
• Metadata storage without impacting matching performance

Market Structure

Each market in Vif is uniquely identified by a hash of five parameters:

marketId = keccak256(
  outboundToken,
  outboundUnits,
  inboundToken,
  inboundUnits,
  tickSpacing
)

Order Types

Limit Orders (Making)

Makers place limit orders at specific price points:

• Provide liquidity at a chosen tick (price level)
• Earn from the spread when takers consume your offer
• Optional expiry with provision requirements
• Claim anytime to withdraw filled amounts

Market Orders (Taking)

Takers consume existing limit orders:

• Instant execution at best available prices
• Exact input or output - specify what you give or want to receive
• Price limits via maxTick parameter
• Gas control via maxOffers parameter

Token Units

To achieve optimal storage efficiency, Vif represents amounts in units:

effectiveAmount = floor(amount / units) * units

Units allow packing amounts into 48 bits (~281 trillion units), significantly reducing storage costs.

The Lock Pattern

All interactions with Vif go through the lock pattern:

function lock(bytes calldata data) external returns (bytes memory result)

1. User calls lock() with encoded action data
2. Vif calls back lockCallback() on the caller
3. Caller performs operations (modifying transient balances)
4. Caller settles debts and takes credits
5. Vif verifies all balances are zero
6. Transaction succeeds or reverts if imbalanced

This pattern enables atomic batching of complex operations while maintaining security.

Authorization & Operators

Users can authorize operators to act on their behalf:

vif.authorize(operatorAddress, true);

Operators can:

• Create market orders for the user
• Create limit orders for the user
• Claim and cancel orders
• Settle debts using user allowances

Governance Features

The protocol owner can:

• Pause the contract (prevents all lock operations)
• Blacklist malicious router contracts
• Create markets with custom parameters
• Set fees (protocol and maker/taker fees)
• Configure provisions for expired orders
• Withdraw governance fees

Next Steps

Explore the detailed mechanics:

• Tick Tree Structure - Deep dive into price discovery
• Flash Accounting - Understanding transient balances
• Markets & Units - Token configuration details
• Offers & Lists - Order book data structures

Or jump to practical examples:

• Creating Swaps - Execute market orders
• Placing Limit Orders - Provide liquidity