The fulfilment valve

request_fulfillment burns units from the holder's ledger, quotes them in USDC at the print, and reserves rather than moves the money. An off-chain agent ships the thing and calls settle_fulfillment.

Denominated only#

require!(market.quote_mode == QuoteMode::Denominated,
         Err::FulfillmentNeedsDenominated);

The valve spends dollars to buy an object. A Native vault holds SPYx, so the mode simply does not apply, and refusing is better than quietly quoting a shipment against an equity balance.

What request_fulfillment checks#

It accrues first, then checks four things against Pairable.fulfillment, in this order:

let quoted = usdc_from_units(units, price);
require!(quoted <= cfg.max_request_usd,       Err::RequestTooLarge);
require!(quoted >= cfg.min_request_usd,       Err::RequestTooSmall);
require!(quoted <= cfg.remaining_budget(now), Err::BudgetExhausted);
require!(quoted <= market.holder_usdc(),      Err::InsufficientVault);

Then it burns the units from both the position and units_outstanding, reserves the dollars rather than moving them, charges the epoch, and writes a FulfillmentRequest at ["fulfillment", market, seq].

Reserving rather than moving is what keeps the refund path from depending on the agent holding funds. Reserved dollars are excluded from available_usdc() and therefore from coverage and from claims, because a bottle that has been promised is not buffer.

commitment is a 32-byte hash of the shipping payload. No address ever touches the chain; the agent proves it holds the preimage.

Why there is a minimum as well as a maximum#

A ceiling alone bounds the blast radius of a bad print. A floor is what keeps every request from being economically absurd, and the program needs both: register_pairable enforces min_request_usd <= max_request_usd.

The Coke case is the cleanest statement of it. A 20oz Coke is $2.49 and a parcel is $8 to $10, so a one-bottle request costs four times the bottle to honour and, in the registry's own words, "reads as the protocol being trolled rather than used". The floor is $25, roughly a case, which is what these things actually ship as.

Pears exposed the gap first: produce moves by the carton and shipping a single pear costs several times the pear.

Ship versus Voucher#

A Big Mac is a hot prepared item with a ten-minute quality life, and a gallon of petrol is not going in a parcel. For those the honest deliverable is a claim on the good, not the good: a gift card or a fuel card worth N units.

The voucher floor is higher because a $6 voucher is not worth the transaction, and the TTL is much shorter because a redeemable claim nobody has actioned in two days is not coming.

Three tiers across the registry: ship the object (Coke, eggs, ramen, rice, pears), voucher a claim on it (Big Mac US, Big Mac CH, gas, milk), or nothing at all (Drake's listeners, the Phoenix high).

Settling#

settle_fulfillment(shipped) is signed by Global.fulfillment_authority.

expire_fulfillment closes a real hole. Without it, an agent going dark holds a holder's units, the vault's reserved dollars, and a slice of the epoch budget hostage indefinitely. Perishables make that acute: "we will ship when they are back in season" is indistinguishable from never.

A config update cannot reset the epoch#

One related guard sits in update_pairable. A config update carries the existing epoch_start_ts and epoch_spent_usd forward rather than taking them from the new struct, because resetting the rolling epoch would be a budget bypass dressed as a parameter change.