Skip to content
0xSlots

OfferBook

Standing bids on a slot, and the fill that settles them. Anyone may post "I will take that slot at this price"; the occupant reads the best one and accepts it.

The book is periphery. The core knows nothing about it — deploy another and it competes.

Why the book performs the fill

A consensual sale is two calls the core already has, in one transaction:

slot.selfAssess(price)                 // the occupant's price, restated
slot.buy(bidder, price, deposit, max)  // the ordinary market path

buy already refunds the outgoing occupant their deposit plus the price. So there is one seating path, and the slot's module gets its say — on the reprice and on the seating — like on any other buy.

Posting a bid

function offer(address slot, uint256 price, uint256 deposit, uint64 expiry)
    external returns (uint256 id);
 
function cancel(address slot, uint256 id) external;   // bidder only

One transaction, and no signature: offer is a call from the bidder, so posting is the consent. One offer per bidder per slot — posting again updates your standing one under the same id.

Bids are allowance-backed, not escrowed. The book pulls the payment during the fill and spends it in the same transaction; if the funds are gone when the occupant accepts, the transfer reverts and the seller loses gas and nothing else.

Accepting a bid

function acceptOffer(address slot, uint256 id, uint256 minPrice) external;   // occupant only

selfAssess is onlyOccupantOrOperator, so the occupant makes the book their operator first:

slot.setOperator(book, true);
book.acceptOffer(slot, id, minPrice);

minPrice is the price the seller reviewed. A bidder edits an offer in place under the same id, so without it a bidder could lower their price between the seller reading the board and the fill landing.

The operator grant is keyed by tenure on the slot's side, so it lapses by itself when the slot changes hands.

Errors worth handling

ErrorMeaning
NotOccupantonly the sitting occupant may accept a bid on their slot
NotOperatorthe book has not been granted setOperator for this tenure
OfferNotLivecancelled, expired, filled, unfunded, or the bidder is the occupant
PriceBelowMinimum(price, minPrice)the offer was lowered after the seller read it
NativeSlotNotSupportednative slots cannot be filled — see below
TopUpRequired(shortfall)accepting a higher bid raises the escrow floor above what the seller holds

TopUpRequired is the one that surprises people. Raising the declared price raises the minimum escrow with it, and selfAssess enforces that floor against the deposit already in the slot — the seller's, not the bidder's. Top up by the reported shortfall and retry; it comes straight back in the sale proceeds.

Reading the board

function board(address slot) external view
    returns (Offer[] memory offers, bool[] memory live);
 
function best(address slot) external view
    returns (bool found, uint256 id, Offer memory offer);
 
function liveCount(address slot) external view returns (uint256);
function offerCount(address slot) external view returns (uint256);
function isLive(address slot, uint256 id) external view returns (bool);
function isFundable(address slot, uint256 id) external view returns (bool);
function offerOf(address slot, address bidder) external view
    returns (bool has, uint256 id, Offer memory offer);
function offerAt(address slot, uint256 id) external view returns (Offer memory);
function offers(address slot) external view returns (Offer[] memory);
 
// The same reads over offer ids [start, start + count), clipped to the board.
function boardPage(address slot, uint256 start, uint256 count) external view
    returns (Offer[] memory offers, bool[] memory live);
function bestIn(address slot, uint256 start, uint256 count) external view
    returns (bool found, uint256 id, Offer memory offer);
function liveCountIn(address slot, uint256 start, uint256 count) external view
    returns (uint256);

board returns the list and the contract's own per-entry liveness verdict in one call, which is why it is preferred over offers plus N isLive reads. The board only grows — cancelling sets a flag, nothing removes an entry — so a client should read it with boardPage in chunks (the SDK uses 200) and take the live count and the best bid from the same pages; a whole-board read can be pushed past an RPC's gas budget by enough dust bids.

An offer is live only if its deposit meets the slot's entry floor at its price (minDepositForBuy) — a bid the slot would refuse to seat is never shown as fillable. acceptOffer never pulls more than the offer's price + deposit plus the bidder's debt; a quote above that reverts QuoteAboveOffer.

Events

event Offered(address indexed slot, address indexed bidder, uint256 indexed id,
              uint256 price, uint256 deposit, uint64 expiry);
event Cancelled(address indexed slot, address indexed bidder, uint256 indexed id);
event Filled(address indexed slot, address indexed bidder, uint256 indexed id,
             address seller, uint256 price, uint256 deposit);

Filled is the seller's side of a sale. The slot emits Bought in the same transaction, so occupancy history is complete from the slot alone.