Offers & Lists

struct Offer {
  uint48 gives;        // Amount offered (in units)
  uint48 received;     // Amount received from fills (in units)
  uint40 next;         // Next offer ID in list
  uint40 prev;         // Previous offer ID in list
  uint32 expiry;       // Expiration timestamp (0 = never)
  uint24 provision;    // Provision in native token (in provision units)
  address maker;       // Offer owner
  bool isActive;       // Whether offer is in the book
  int24 tick;          // Price level (redundantly stored)
}

actualAmount = gives * outboundUnits;
 
// Example: WETH offer with outboundUnits = 1e13
gives = 100_000;  // 100,000 units
actualAmount = 100_000 * 1e13 = 1e18 = 1 WETH

// Offer sells 1 WETH for USDC at tick -2,072,336 (~1221 USDC/WETH)
// Taker buys 0.5 WETH
 
gives = 100_000 units (1 WETH initially)
// After fill:
gives = 50_000 units (0.5 WETH remaining)
received = 61_050_000 units (~610.5 USDC in inboundUnits=1e4)

Head → [Offer 1] ⇄ [Offer 2] ⇄ [Offer 3] ← Tail
       prev=0       prev=1       prev=2
       next=2       next=3       next=0

expiry = 0;                    // Never expires
expiry = 1735689600;           // Expires Jan 1, 2025
expiry = block.timestamp + 1 days;  // Expires in 1 day

provisionUnits = globalProvision;  // Set at contract deployment
actualProvision = provision * provisionUnits;
 
// Example: globalProvision = 1e12
provision = 1000;
actualProvision = 1000 * 1e12 = 1e15 wei = 0.001 ETH

// Creating offer
vif.make(maker, market, 0, gives, tick, expiry, provision);
// → Creates offer owned by `maker`
 
// Editing offer (must use same maker)
vif.make(maker, market, offerId, newGives, newTick, expiry, provision);
// → Reverts if caller isn't authorized by `maker`

isActive = true;   // Offer is in book, can be matched
isActive = false;  // Offer removed (fully filled, cancelled, or expired)

struct OfferList {
  uint40 head;           // First offer ID
  uint40 tail;           // Last offer ID
  uint48 totalVolume;    // Sum of all gives (in units)
  uint40 offerCount;     // Number of active offers
  int24 tick;            // Price level (redundant)
}

Tick -2,072,336 (Price: ~1221 USDC/WETH)
┌──────────────────────────────────────────┐
│ head: 42                                 │
│ tail: 105                                │
│ totalVolume: 500,000 units (5 WETH)     │
│ offerCount: 3                            │
└──────────────────────────────────────────┘
         ↓
    [Offer 42] ⇄ [Offer 73] ⇄ [Offer 105]
    gives: 200K   gives: 150K   gives: 150K

// List before: Head → [42] ⇄ [73] ← Tail
// Insert offer 105
 
1. Create offer 105 with:
   - prev = 73 (current tail)
   - next = 0 (will be new tail)
 
2. Update offer 73:
   - next = 105
 
3. Update list:
   - tail = 105
   - totalVolume += 150,000
   - offerCount += 1
 
// List after: Head → [42] ⇄ [73] ⇄ [105] ← Tail

// List: Head → [42] ⇄ [73] ⇄ [105] ← Tail
// Remove offer 73
 
1. Update offer 42:
   - next = 105 (skip 73)
 
2. Update offer 105:
   - prev = 42 (skip 73)
 
3. Update offer 73:
   - isActive = false
   - (links remain for historical data)
 
4. Update list:
   - totalVolume -= 150,000
   - offerCount -= 1
 
// List: Head → [42] ⇄ [105] ← Tail

vif.make(maker, market, 0, gives, tick, expiry, provision);

vif.consume(taker, market, maxTick, fillVolume, fillWants, maxOffers);

vif.claim(market, offerId);

vif.cancel(market, offerId);

vif.clean(market, offerId);

function consume(taker, market, maxTick, fillVolume, fillWants, maxOffers) {
  cursor = tree.first();  // Get best tick
  remaining = fillVolume;
 
  while (remaining > 0 && offersConsumed < maxOffers) {
    if (cursor.tick > maxTick) break;  // Price limit reached
 
    offer = offerList[cursor.tick].head;  // Get first offer
 
    while (offer != null && remaining > 0) {
      // Match offer
      filled = min(offer.gives, remaining);
      offer.gives -= filled;
      offer.received += calculateInbound(filled, cursor.tick);
      remaining -= filled;
      offersConsumed++;
 
      if (offer.gives == 0) {
        // Fully filled, remove
        offer.isActive = false;
        offer = offer.next;
      } else {
        // Partially filled, stay in list
        break;
      }
    }
 
    if (offerList[cursor.tick].head == null) {
      // All offers consumed at this tick, move to next
      cursor = tree.next(cursor);
    }
  }
}

vif.make(maker, market, existingOfferId, newGives, newTick, newExpiry, newProvision);