v1 state

marketPath

StatusFilled

StatusCancelled

StatusReplaced

StatusExpired

maxSecondaryFeeBPS

// 2% of a sale price

maxLifetime

graceToClose

maxOrders

Listing

Listing offers one token at a fixed price. The seller keeps the token and approves this realm; nothing is held here. A listing exists while it is open and no longer, and can be bought only within the token's custody epoch it was made in.

lastListing

listings

// listing key -> \*Listing, in creation order

listed

// "\<collection>/\<token number key>" -> \*Listing

bySeller

// "\<seller>/\<listing key>" -> \*Listing

directCaller

orderKey

orderKey reads an order ID, its prefix ('L' listing, 'O' offer) then its number, as its tree key.

nextOrder

findListing

findListing returns an open listing, or nil: a closed one is gone.

mustListing

tokenKey

tokenKey sorts a collection's tokens in number order.

listingOf

listingOf returns the open listing of a token, or nil.

sellable

sellable reports whether seller owns the active token and has approved this realm for that token. Only a single-token approval counts, as an approval for all would outlive the token's moves.

pinned

pinned checks what every new order needs (a collection that can be sold, a price, a lifetime of at most 90 days) and returns the protocol fee to pin on it: the current one, which must not exceed what its owner accepts nor this realm's cap.

List

List offers the caller's token for sale and returns the listing ID. The caller must first approve this realm in the NFT ledger, and names the highest protocol fee it accepts; the fee in force is pinned on the listing. A new listing replaces the token's previous one.

closeListing

closeListing deletes a listing and says why in its closing event.

live

live reports whether a listing can be bought right now. A move or an approval change starts a new custody epoch, so a listing never comes back to life when a token that left the seller returns or the market is approved again: the seller lists anew.

Cancel

Cancel withdraws a listing. The seller can always do it, paused market or not. Anyone can clear a listing whose seller no longer owns the token, or one that expired more than graceToClose ago; the chain returns the storage deposit of what a call frees to its caller, so clearing pays whoever does it.

Buy

Buy pays a listing's exact price and moves the token to the caller. currencyKey and price are the terms the buyer read: a listing on other terms, such as an ID the buyer never saw, takes nothing.

GetListing

GetListing returns an open listing; a closed or unknown ID aborts.

Render

OfferToken

// one named token

OfferCollection

// any token of the collection

OfferTrait

// any token proven to carry a trait

StatusAccepted

StatusSuperseded

maxTraitBytes

Offer

Offer is a bid whose full price sits in this realm until it is accepted, cancelled by its buyer or returned after expiry. An offer exists while it is open and no longer.

lastOffer

offers

// offer key -> \*Offer, in creation order

open

// "\<collection>/\<offer key>" -> \*Offer

byBuyer

// "\<buyer>/\<offer key>" -> \*Offer

findOffer

findOffer returns an open offer and its key, or nil: a closed one is gone.

mustOffer

TraitLeaf

TraitLeaf is the Merkle leaf that proves a token carries a trait, as committed by the collection's creator in the NFT ledger.

MakeOffer

MakeOffer escrows price and returns the offer ID. kind selects what the offer is for: number is set for a token offer, trait for a trait offer, and both are zero and empty otherwise. A trait offer needs a collection whose creator committed its traits. The protocol fee in force is pinned on the offer; it comes out of what the seller receives, never on top of the price, and maxFeeBPS is the highest the buyer lets a seller be charged.

release

release deletes an offer, takes its price out of escrow and says why in its closing event; the caller then pays the price out. Every exit goes through here, and an offer leaves escrow once, by its own key: with \`settled\`, an exit pays out exactly the price of the one offer it closed, so a fault in one offer's exit can never spend another offer's escrow.

refund

refund returns an open offer's escrow to its buyer. Refunds never consult the config realm: no pause or policy change can hold a buyer's funds.

CancelOffer

CancelOffer takes back the caller's own open offer, expired or not.

ExpireOffer

ExpireOffer returns to its buyer the escrow of an offer that expired more than graceToClose ago. Anyone may call it: the price goes to the buyer, and the chain pays the caller the storage deposit of the bytes the offer occupied, so for a week after expiry only the buyer, with CancelOffer, takes its own offer back.

AcceptOffer

AcceptOffer sells the caller's token number to an open offer. proof is the comma-separated Merkle path of the token's trait for a trait offer, and empty otherwise. currencyKey and price are the terms the seller read: an offer on other terms, such as an ID the seller never saw, buys nothing. The caller must first approve this realm in the NFT ledger.

GetOffer

GetOffer returns an open offer; a closed or unknown ID aborts.

EscrowOf

EscrowOf is the total of open offers in a currency.

escrow

escrow is, per currency, the total of open offers: everything this realm owes. Currencies are few (config allows sixteen), so a map is enough.

terms

terms is what this realm needs from config.

policy

policy returns the current terms after checking that the market lane is open for the currency. It is a variable only so that unit tests can stand in for the config realm, whose admin cannot be set from another package's tests.

balance

surplus

surplus is what the realm holds beyond its open offers. Every entry point must leave it exactly as it found it.

take

take collects exactly amount from the direct caller, attached for native coins and pulled for a token, and returns the surplus before the payment.

untouched

untouched is take for an entry point that receives nothing.

pay

settle

settle splits a sale price: the protocol fee to the treasury, each royalty to its receiver, the rest, rounding included, to the seller.

settled

settled aborts the transaction unless the realm holds exactly its open offers plus the surplus it had before the call: nothing taken is left behind, and nothing owed has been spent.

num

splitJSON

splitJSON is how a price would be divided at a protocol fee: what the seller keeps, the treasury's fee and each royalty.

listingJSON

offerJSON

ListingJSON

ListingJSON is an open listing, or "null" once it is closed.

OfferJSON

OfferJSON is an open offer, or "null" once it is closed. An open offer can be past its expiry: it then only waits for its refund.

maxSlice

Lists are read in slices of 1 to maxSlice entries that start after a cursor: what identifies the last entry already read, or nothing to start from the beginning. Orders come and go between two reads, and a cursor never skips or repeats one that stayed. A slice costs the same wherever it starts.

sliceJSON

sliceJSON renders up to size entries of tree whose keys lie in \[from, to), in key order, or from the last key down when reverse.

cursorKey

cursorKey reads an order cursor: the ID of the last order already read.

after

after is the first key an oldest-first slice may hold: the one following the cursor, or "" with no cursor.

below

below is the last key a newest-first slice may hold: the one preceding the cursor, or "" with no cursor. No order has key zero, so the first order's ID leaves nothing below it.

renderListing

renderOffer

ListingsJSON

ListingsJSON reads every open listing, newest first, starting below the listing ID before ("" starts from the newest).

CollectionListingsJSON

CollectionListingsJSON reads a collection's open listings in token number order, starting after the token number afterNumber (0 starts from the first).

account

account checks an address argument of a view.

SellerListingsJSON

SellerListingsJSON reads an account's open listings, oldest first, starting after the listing ID afterID ("" starts from the oldest).

OffersJSON

OffersJSON reads every open offer, newest first, starting below the offer ID before ("" starts from the newest).

CollectionOffersJSON

CollectionOffersJSON reads a collection's open offers of every kind, oldest first, starting after the offer ID afterID ("" starts from the oldest).

BuyerOffersJSON

BuyerOffersJSON reads an account's open offers, oldest first, starting after the offer ID afterID ("" starts from the oldest).

TokenListingJSON

TokenListingJSON is the open listing of a token, or "null".

TermsJSON

TermsJSON is what a sale costs now: the protocol fee a new listing would pin, and how a price would split for the collection. A fee of -1 means the lane is closed; config's ActionStatusJSON tells whether the market lane accepts new orders right now.