The Boson model

The whole protocol revolves around three on-chain entities. If you understand these and the state machines, everything else falls into place.

Offer

An offer is a seller's listing: a thing for sale at a price, valid for a window, with an associated dispute resolver, optional token-gating condition, and a pointer to off-chain metadata.

Created by createOffer(). Voided by voidOffer(). Lives forever on-chain; cannot be "deleted".

Key fields:

• price — what the buyer pays.
• sellerDeposit — what the seller stakes (slashed on a lost dispute).
• buyerCancelPenalty — what the buyer forfeits if they cancel after commit.
• exchangeToken — 0x0 for native (ETH / MATIC), otherwise an ERC-20.
• quantityAvailable — how many units can be committed before the offer sells out.
• valid{From,Until}DateInMS — commit window.
• voucherRedeemable{From,Until,ValidDuration} — redeem window (relative to commit).
• disputeResolverId — who arbitrates if things go wrong.
• metadataUri / metadataHash — IPFS pointer to the off-chain product detail.

See Build → Sellers → Publish an offer for the task; Reference → Core SDK → Offers for full types.

Exchange

An exchange is a specific buyer's commitment to a specific offer. One offer → many exchanges (one per buyer commit). Each exchange has:

• A numeric exchangeId.
• A state (see Exchange state machine).
• A single buyer, a single seller, a single offer.
• A linked voucher (rNFT) held in the buyer's wallet until redemption.

The exchange is the unit of state in Boson. Every protocol action — commit, redeem, complete, cancel, dispute — moves an exchange between states.

See Build → Buyers → Commit to an offer for the buyer side.

Dispute

A dispute is an exchange that's run into trouble after redemption. Modeled as a separate on-chain entity attached to its parent exchange.

• Raised by the buyer with raiseDispute() within the dispute window.
• Resolved mutually (resolveDispute()) within the resolution window.
• Otherwise escalated to the dispute resolver (escalateDispute()) for a binding decideDispute() or refuseEscalatedDispute().

Disputes have their own state machine, distinct from the exchange's.

See Build → Buyers → Raise a dispute and Build → Dispute Resolvers.

The relationship

Once you grok these three, the rest of the protocol is variations:

• Bundles — an offer that ships multiple items.
• Token-gated offers — an offer with a condition restricting who may commit.
• Pre-minted vouchers — vouchers minted before any commit.
• Atomic commit-and-redeem — collapse two state transitions into one tx.
• Buyer-initiated offers — the buyer drafts, the seller accepts.
• Sequential commit — secondary-market resale through the protocol with chained buyer protection and perpetual royalties.

Next

• Roles — who can do what.
• Exchange state machine — every state transition.
• Networks & ConfigIds — selecting a deployment.