Sale API Reference

The sale object. Holds the inventory, collected proceeds, caps, window, phase, the paired vault's id and controller cap, the optional per-buyer contributions table, and the optional vesting schedule. key-only: created owned in Init, shared on activation, and never deleted.

VestingWitness is the drop-only schedule witness (e.g. vesting_wallet_linear::Linear); pinning it in the type is what makes an attached vesting lockup unbypassable. For a non-vesting sale the vesting slots are inert.

The lifecycle phase: Init (owned, under setup), Active (shared, accepting purchases within the window), Finalized (successful close), or Cancelled (failed close). Finalized and Cancelled are terminal. Read it with phase.

Admin capability for a single sale, bound to it by id. Gates cancel_emergency, withdraw_proceeds, and withdraw_unsold_inventory. Losing it never strands buyer funds - all buyer-facing flows are permissionless.

Witness-gated, single-use carrier for share_and_activate. Has no abilities, so it must be minted and consumed in the same PTB. Pins the sale_id and the curve's committed required_inventory.

Hot-potato carrying a curve-priced quote for a single purchase: the buyer's payment Balance welded to the curve-computed allocation, pinned to a sale_id. Has no abilities, so it can only be minted by the sale's curve module (via mint_quote) and consumed by purchase, in the same PTB. Cannot be stored, copied, replayed, or transferred.

The reason a sale was cancelled, carried by SaleCancelled: SoftCapMissed (the window closed below the minimum raise) or AdminEmergency (an admin cancelled while the sale was still open).

Creates a sale in Init phase, returning it as an owned value plus its admin cap. The caller threads the sale through the setup calls below and then share_and_activate. curve_params is opaque to the sale; build it with the curve module's params constructor. soft_cap == 0 means no soft cap.

Aborts with EHardCapZero if hard_cap == 0.

Aborts with EInvalidCapsOrdering if soft_cap > hard_cap.

Aborts with EInvalidTimeRange if opens_at_ms >= closes_at_ms.

Emits SaleCreated.

Adds sale tokens to inventory. May be called multiple times during Init. Authority is implicit: the sale is owned.

Aborts with ENotInit if the sale is not in Init phase.

Emits InventoryDeposited.

Configures a cumulative per-buyer payment cap, enforced inside purchase against each buyer's running total. One-shot.

Aborts with ENotInit if the sale is not in Init phase.

Aborts with EPerBuyerCapAlreadySet if a per-buyer cap is already configured.

Aborts with EPerBuyerCapZero if per_buyer_cap == 0.

Emits PerBuyerCapSet.

Attaches an issuer-defined vesting schedule. Once set, plain claim aborts and redemption must go through claim_into_vesting. The schedule is unbypassable - the wallet is built under the sale's pinned VestingWitness. One-shot, Init-only.

Aborts with ENotInit if the sale is not in Init phase.

Aborts with EVestingScheduleAlreadySet if a schedule is already configured.

Emits VestingScheduleParamsSet.

Pairs a refund vault with the sale, required before activation. The cap is consumed into the sale (never returned); from then on only the sale's gated functions drive the vault. The vault must be Active and empty.

Aborts with ENotInit if the sale is not in Init phase.

Aborts with EVaultAlreadyPaired if a vault has already been paired.

Aborts with EWrongVault if vault_cap does not control vault.

Aborts with EVaultNotActive if vault is not in the Active state.

Aborts with EVaultNotEmpty if vault holds a non-zero balance.

Emits RefundVaultPaired.

Switches the sale into compliance-gated mode and returns the single AllowlistAdmin<SaleCoin>, to be wrapped in the consumer's compliance module. After this, every purchase must consume an AllowEntry. One-shot.

Aborts with ENotInit if the sale is not in Init phase.

Aborts with EAllowlistAlreadyEnabled if the allowlist is already enabled.

Emits AllowlistEnabled.

Witness-gated constructor for the ActivationTicket that share_and_activate consumes. Requires a value of type Curve, whose constructor is private to the declaring curve module, so only that module can mint a ticket for its sale. Curve modules wrap it (e.g. fixed_rate_curve::activation_ticket).

Transitions Init -> Active and shares both the sale and its paired vault, consuming all three arguments. Taking the vault by value and sharing it here is what makes the permissionless refund guarantee structural: the paths that need &mut vault can never be bricked by a forgotten share step. Activation after closes_at_ms is rejected.

Aborts with ETicketSaleMismatch if ticket was minted for a different sale.

Aborts with ENotInit if the sale is not in Init phase.

Aborts with EVaultRequiredForActivate if no refund vault has been paired.

Aborts with EWrongVault if vault is not the one paired with this sale.

Aborts with EActivationAfterClose if now >= closes_at_ms.

Aborts with EInsufficientInventoryAtActivate if inventory < required_inventory.

Emits SaleActivated.

Buys sale tokens, delivering a Receipt<SaleCoin> to ctx.sender() and adding the payment to proceeds. Applies the quote's allocation verbatim (the curve is trusted), bounded only by unallocated inventory and overflow. The hard cap is all-or-nothing - a payment past hard_cap reverts in full. Pass Some(entry) iff the sale requires an allowlist.

Aborts with ENotActive if the sale is not in Active phase.

Aborts with EQuoteSaleMismatch if quote was minted for a different sale.

Aborts with ESaleWindowClosed if now is outside [opens_at_ms, closes_at_ms].

Aborts with EAllowlistRequired / EAllowlistNotRequired if the entry is missing when required, or supplied when not.

Aborts with allowlist::EWrongSaleId / allowlist::EWrongBuyer if the entry was issued for a different sale or buyer.

Aborts with ERaisedOverflow if raised + paid would exceed u64::MAX.

Aborts with EHardCapExceeded if raised + paid would exceed hard_cap.

Aborts with EPerEntryCapExceeded if paid exceeds the entry's max_amount.

Aborts with EPerBuyerCapExceeded if paid exceeds the buyer's remaining per-buyer cap.

Aborts with EInsufficientInventory if allocation exceeds unallocated inventory (only reachable via a dishonest curve).

Emits Purchased.

Closes the sale as a success and flips the paired vault to Closed. Permissionless. Allowed once the window has closed with the soft cap met, or as soon as the hard cap is reached (closing early). Proceeds stay in the sale for the admin to withdraw.

Aborts with ENotActive if the sale is not in Active phase.

Aborts with ESaleWindowStillOpen if the window is still open and the hard cap is not reached.

Aborts with ESoftCapNotMet if raised < soft_cap.

Aborts with EWrongVault if vault is not the one paired with this sale.

Emits SaleFinalized.

Closes the sale as a soft-cap miss. Permissionless. Drains proceeds into the vault and flips it to Refunding. Allowed once the window has closed with a configured soft cap that was missed.

Aborts with ENotActive if the sale is not in Active phase.

Aborts with ESaleWindowStillOpen if the window has not yet closed.

Aborts with ESoftCapMet if no soft cap is configured or raised >= soft_cap.

Aborts with EWrongVault if vault is not the one paired with this sale.

Emits SaleCancelled.

Emergency cancellation. Admin-only. Drains proceeds into the vault and flips it to Refunding. Allowed only while the window is open and the sale has not met its goal - the guards prevent rugging a successful sale. Pre-open cancel is permitted.

Aborts with EWrongAdminCap if cap was issued for a different sale.

Aborts with ENotActive if the sale is not in Active phase.

Aborts with EEmergencyCancelAfterClose if now > closes_at_ms.

Aborts with ESaleAlreadyComplete if raised >= hard_cap.

Aborts with ESoftCapMet if a soft cap is configured and raised >= soft_cap.

Aborts with EWrongVault if vault is not the one paired with this sale.

Emits SaleCancelled.

Redeems a receipt for its allocation, returned as Balance<SaleCoin> split from inventory, and destroys the receipt. A vesting sale must use claim_into_vesting instead.

Aborts with EClaimRequiresVesting if the sale has a vesting schedule attached.

Aborts with ENotFinalized if the sale is not in Finalized phase.

Aborts with EReceiptSaleMismatch if receipt was issued by a different sale.

Aborts with EBuyerOnly if ctx.sender() is not the receipt's buyer.

Emits Claimed.

Batches claim over several receipts, summing their allocations into one balance. Aborts the whole call if any receipt is invalid.

Aborts with EClaimRequiresVesting if the sale has a vesting schedule attached.

Aborts with ENotFinalized if the sale is not in Finalized phase.

Aborts with EReceiptSaleMismatch if any receipt was issued by a different sale.

Aborts with EBuyerOnly if ctx.sender() is not the buyer of any receipt.

Emits Claimed per receipt.

The only redemption path for a vesting sale. Redeems a receipt into a funded VestingWallet (from openzeppelin_finance) with beneficiary forced to the buyer and the sale's fixed schedule, plus the wallet's DestroyCap. Every type argument is inferred from the sale.

Aborts with ENoVestingScheduleAttached if the sale has no vesting schedule (use claim).

Aborts with ENotFinalized if the sale is not in Finalized phase.

Aborts with EReceiptSaleMismatch if receipt was issued by a different sale.

Aborts with EBuyerOnly if ctx.sender() is not the receipt's buyer.

Emits Claimed.

Batch variant of claim_into_vesting: redeems several receipts into one funded VestingWallet, summing their allocations. Aborts the whole call if any receipt is invalid.

Aborts with ENoVestingScheduleAttached if the sale has no vesting schedule (use claim_all).

Aborts with ENotFinalized if the sale is not in Finalized phase.

Aborts with EReceiptSaleMismatch if any receipt was issued by a different sale.

Aborts with EBuyerOnly if ctx.sender() is not the buyer of any receipt.

Emits Claimed per receipt.

Withdraws all collected proceeds. Admin-only, Finalized-only. Idempotent: a second call returns an empty balance and emits nothing.

Aborts with EWrongAdminCap if cap was issued for a different sale.

Aborts with ENotFinalized if the sale is not in Finalized phase.

Emits ProceedsWithdrawn (only when the amount is non-zero).

Withdraws strictly the unallocated inventory (inventory - total_allocated); tokens backing outstanding receipts stay put. Admin-only, valid in Finalized or Cancelled. Idempotent.

Aborts with EWrongAdminCap if cap was issued for a different sale.

Aborts with ENotTerminal if the sale is neither Finalized nor Cancelled.

Emits InventoryWithdrawn (only when the amount is non-zero).

Refunds a buyer's payment from the paired vault, returning exactly the receipt's paid amount and destroying the receipt. Permissionless but buyer-bound. Never depends on admin liveness.

Aborts with ENotCancelled if the sale is not in Cancelled phase.

Aborts with EReceiptSaleMismatch if receipt was issued by a different sale.

Aborts with EBuyerOnly if ctx.sender() is not the receipt's buyer.

Aborts with EWrongVault if vault is not the one paired with this sale.

Emits Refunded.

Witness-gated quote constructor. The curve module calls this from its own quote(..) after running its pricing math; the allocation is payment.value() * rate. Requires a Curve value, so a caller cannot mint a quote without the declaring curve module.

Aborts with EZeroPayment if payment has zero value.

Aborts with EAllocationOverflow if payment.value() * rate would exceed u64::MAX.

The sale's current lifecycle phase.

The total payment raised so far, in PaymentCoin units.

The stored curve configuration. Opaque to the sale; interpreted by the declaring curve module.

The configured hard cap (maximum raise), in PaymentCoin units.

The configured soft cap (minimum raise to finalize); 0 means none.

The start of the purchase window (ms).

The end of the purchase window (ms).

Whether purchases require an AllowEntry (allowlist mode).

Some(params) if a vesting schedule was attached during Init, otherwise None.

Total inventory currently held (allocated plus unallocated).

Sale tokens promised to outstanding (unredeemed) receipts.

Unallocated inventory: inventory_total - total_allocated.

Payment currently held as proceeds (before withdrawal or cancel).

Whether a purchase would pass its phase and window checks right now.

Whether raised >= soft_cap. Always true when no soft cap is configured.

Whether raised >= hard_cap (sold out and able to finalize early).

The id of the sale this admin cap controls.

The id of the sale this quote was minted for.

The payment balance carried by this quote.

The curve-computed allocation this quote will deliver on purchase.

Emitted by create_sale.

Emitted by deposit when sale tokens are added to inventory.

Emitted by set_per_buyer_cap.

Emitted by set_vesting_schedule_params.

Emitted by pair_refund_vault.

Emitted by enable_allowlist.

Emitted by share_and_activate when the sale goes live.

Emitted by purchase for each successful buy.

Emitted by finalize when the sale closes successfully.

Emitted by cancel_after_close and cancel_emergency. reason is a CancelReason.

Emitted for each receipt redeemed through claim / claim_all and the vesting variants.

Emitted by refund when a buyer recovers their payment.

Emitted by withdraw_proceeds.

Emitted by withdraw_unsold_inventory.

The supplied SaleAdminCap was issued for a different sale.

A redemption path was called by an address other than the receipt's buyer.

cancel_emergency was called after the window closed; use cancel_after_close.

create_sale was given opens_at_ms >= closes_at_ms.

A purchase was attempted outside [opens_at_ms, closes_at_ms].

A close was attempted while the window is still open and the hard cap is not reached.

share_and_activate was called after closes_at_ms had already passed.

create_sale was given hard_cap == 0.

create_sale was given soft_cap > hard_cap.

A quote was requested for a zero-value payment.

A purchase would push raised + paid past u64::MAX.

A purchase would push raised past hard_cap. The cap is all-or-nothing.

At activation, inventory did not cover the backing the curve's ActivationTicket requires.

A quote's allocation (paid * rate) would exceed u64::MAX.

A purchase's allocation exceeded unallocated inventory. Only reachable via a dishonest curve.

A purchase would push the buyer's cumulative payment past the per-buyer cap.

A purchase's payment exceeded the consumed AllowEntry's max_amount.

finalize was called with raised < soft_cap.

A cancel was attempted on a sale that has met its goal, or has no soft cap set.

cancel_emergency was called on a sold-out sale (raised >= hard_cap); it must finalize.

The sale requires an AllowEntry but purchase was called without one.

The sale does not require an AllowEntry but purchase was given one.

enable_allowlist was called a second time on the same sale.

pair_refund_vault was called after a vault had already been paired.

share_and_activate was called before a refund vault was paired.

The vault passed to a sale operation is not the one paired with this sale.

The vault offered to pair_refund_vault was not in the Active state.

The vault offered to pair_refund_vault held a non-zero balance.

A receipt passed to claim / refund was issued by a different sale.

A quote passed to purchase was minted for a different sale.

An activation ticket passed to share_and_activate was minted for a different sale.

set_per_buyer_cap was called a second time on the same sale.

set_per_buyer_cap was given 0, which would block every buyer.

set_vesting_schedule_params was called a second time on the same sale.

Plain claim was called on a vesting sale; redeem via claim_into_vesting.

claim_into_vesting was called on a sale with no vesting schedule; use claim.

A setup operation required the Init phase but the sale was past it.

An operation required the Active phase: the sale was not yet activated, or has already closed.

An operation required the Finalized phase (e.g. a claim before finalize).

An operation required the Cancelled phase (e.g. a refund before cancel).

An operation required a terminal phase (Finalized or Cancelled).

The curve witness. Field-less, drop-only, with a module-private constructor, so no other module can mint a Quote<FixedRateCurve> or activation ticket. This is the security boundary that makes the curve first-party and trusted.

The fixed-rate parameters stored on the sale via curve_params: rate, the sale tokens (smallest units) allocated per 1 payment-coin smallest unit. Obtain a validated value via params.

Builds a validated Params. The only way to obtain a Params outside this module, so a protocol driving create_sale directly can build the config itself.

Aborts with ERateZero if rate == 0.

Mints the ActivationTicket that share_and_activate consumes, committing the inventory backing this curve requires: hard_cap * rate.

Aborts with ERequiredInventoryOverflow if hard_cap * rate would exceed u64::MAX.

Mints a Quote for a buyer's payment balance, allocating balance.value() * rate. The Quote carries the balance through to purchase, welding pricing and funds together for one PTB.

Aborts with prefunded_sale::EZeroPayment if balance has zero value.

Aborts with prefunded_sale::EAllocationOverflow if balance.value() * rate would exceed u64::MAX.

The configured fixed rate: sale tokens allocated per 1 payment-coin unit.

params was called with rate == 0, which allocates nothing for any payment.

hard_cap * rate would exceed u64::MAX, so the required inventory backing cannot be represented.

A refundable escrow holding a locked Balance<P> and a lifecycle state. key-only; share it with share.

Controller capability, bound to a vault by id and phantom-typed on P so it cannot be paired with a vault or sale of a different payment coin.

The vault's lifecycle state: Active (accepting deposits), Refunding (per-amount releases), or Closed (a single full withdrawal). Transitions are one-way from Active.

Creates a fresh, empty vault in Active state and its controller cap. The typical paired-sale flow is new -> pair with a sale -> the sale shares it on activation.

Emits RefundVaultCreated.

Shares a vault. Provided because RefundVault<P> is key-only, so external modules cannot share it directly.

Adds funds to the locked balance. A zero-value deposit is a no-op. Vault must be Active.

Aborts with EWrongVaultCap if cap does not control vault.

Aborts with ENotActiveState if vault is not Active.

Emits VaultDeposit (only when the amount is non-zero).

Transitions Active -> Refunding, enabling per-amount releases.

Aborts with EWrongVaultCap if cap does not control vault.

Aborts with ENotActiveState if vault is not Active.

Emits VaultStateChanged.

Transitions Active -> Closed, enabling withdraw_all.

Aborts with EWrongVaultCap if cap does not control vault.

Aborts with ENotActiveState if vault is not Active.

Emits VaultStateChanged.

Releases a specific amount from the locked balance. Vault must be Refunding.

Aborts with EWrongVaultCap if cap does not control vault.

Aborts with ENotRefundingState if vault is not Refunding.

Aborts with EInsufficientLocked if amount exceeds the locked balance.

Emits VaultRelease.

Withdraws the entire locked balance. Vault must be Closed.

Aborts with EWrongVaultCap if cap does not control vault.

Aborts with ENotClosedState if vault is not Closed.

Emits VaultRelease.

The vault's current state.

The locked balance amount.

The id of the vault this cap controls.

True if the vault is Active.

True if the vault is Refunding.

True if the vault is Closed.

Emitted by new.

Emitted by deposit when funds are added.

Emitted by flip_to_refunding and flip_to_closed.

Emitted by release_balance and withdraw_all when funds leave the vault.

A state-gated operation (deposit, flip_to_*) required the Active state.

release_balance was called while the vault was not Refunding.

withdraw_all was called while the vault was not Closed.

The supplied cap does not control this vault.

A release requested more than the vault's locked balance.

A single-use compliance ticket. No abilities, so it cannot be stored, copied, replayed, or transferred - it must be minted and consumed in the same transaction. Carries the sale_id, the approved buyer, and a per-entry max_amount (0 = no per-entry cap).

The authority to mint AllowEntry<S> for a specific sale. Owned and transferable so the consumer can wrap it in an access-controlled compliance module. Losing it bricks the allowlist sale.

Mints a fresh entry, called by the compliance module after running its verification. max_amount is per-entry, not cumulative (0 = no per-entry cap); for a cumulative bound use the sale's set_per_buyer_cap.

The id of the sale this admin gates entries for.

The consumed AllowEntry was issued for a different sale than the one consuming it.

The consumed AllowEntry's buyer does not match the transaction sender.

The non-transferable, buyer-bound claim ticket. key-only. One receipt per purchase; a buyer with several purchases holds several receipts.

The id of the sale that issued this receipt.

The address that purchased, and the only address that may redeem this receipt.

The payment amount backing this receipt. A refund pays back exactly this.

The sale-token allocation promised by this receipt. A claim returns exactly this.

The timestamp (ms) at which the purchase happened.