Documentation
Lifecycle
Every state a portion can be in, from issuance to its end: consumed, resold, expired or refunded.
A portion is a unit of a series. Units of the same series can be in different states at the same time: some held, some consumed, some sitting in the pool. The states below describe one unit.
States
| State | Where the unit is | Who can act |
|---|---|---|
| Issued | Minted by PortionFactory, bond posted | Provider |
| Listed | Held by PortionMarket, for sale | Any buyer |
| Held | In a buyer's wallet | Holder |
| Partially consumed | Holder's balance reduced by burns | Holder, provider |
| Consumed | Burned by the Redeemer | Nobody |
| Resold | Sold into the v4 pool, held by a new owner | New holder |
| Expired | Past expiry, no longer redeemable or tradable | Nobody |
| Refunded | Burned by the Slasher against a USDC refund | Nobody |
Transitions
Issued → Listed
The provider calls issue on the PortionFactory with the series parameters and the bond. The factory mints the full quantity to the PortionMarket, which lists it at a fixed price or opens a Dutch auction. Issuance fails if the bond posted is below the requirement.
Listed → Held
A buyer calls buy on the PortionMarket with USDC. At a fixed price, the price is constant. In a Dutch auction, the price falls linearly from the start price to the floor over the auction duration, and each buyer pays the price at the block of purchase. The provider receives the USDC minus the 0.75 % protocol fee in the same transaction.
Held → Partially consumed
The holder calls the provider's x402 endpoint and presents a signed redemption as payment. After serving the request, the provider submits it to the Redeemer, which verifies the signature, checks that the series is active and not expired, and burns the units consumed. Each call reduces the balance. See For buyers & agents.
Partially consumed → Consumed
The last units are burned. Nothing remains to trade or refund.
Held or Partially consumed → Resold
The holder sells the remaining units into the series' Uniswap v4 pool against USDC. The 0.75 % protocol fee is taken on the USDC side. The buyer on the other side becomes the holder and the unit returns to Held for them.
Held or Partially consumed → Expired
At expiry, remaining units freeze. The Redeemer rejects them and the v4 hook blocks them from trading. No refund is due: capacity was available and was not used.
Held or Partially consumed → Refunded
If the series is slashed after a dispute, every remaining unit is refunded at the series' average primary price, pro rata if the bond is short, and burned. Units in the v4 pool are refunded to the pool's liquidity like any other holder.
Invariants
- Units are only ever burned, never re-minted. Total supply of a series only goes down after issuance.
- A unit burned by the
Redeemeris never refunded. - The bond requirement never increases after issuance. It only falls as units are burned.
- While a dispute is open, units cannot be sold on the primary market or traded on the pool. They can still be redeemed if the endpoint serves them.