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 pathbuy 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 onlyOne 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 onlyselfAssess 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
| Error | Meaning |
|---|---|
NotOccupant | only the sitting occupant may accept a bid on their slot |
NotOperator | the book has not been granted setOperator for this tenure |
OfferNotLive | cancelled, expired, filled, unfunded, or the bidder is the occupant |
PriceBelowMinimum(price, minPrice) | the offer was lowered after the seller read it |
NativeSlotNotSupported | native 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.