Token Sale Flow

This flow walks through the token sale lifecycle: the admin path from sale creation to finalization, the investor happy path for buying tokens during a public sale, the presale-to-public transition, vested token withdrawal after a successful sale, and the soft cap failure and refund path.

Related

• Token Sale: contracts, roles, and configuration surface
• Signing Flow: transaction signing and custody
• Compliance Transfer: transfer compliance checks

---

Admin sale lifecycle

1. Create -- the admin creates the sale with a sale configuration, atomically deploying the proxy and configuring timing, pricing, limits, vesting, and presale parameters in a single transaction.
2. Fund -- the admin transfers the full token supply (up to the hard cap) to the sale contract address before activation.
3. Activate -- activation moves the sale from SETUP to PRESALE (if configured) or PUBLIC_SALE. Core parameters (timing, hard cap, vesting, soft cap, terms hash) become immutable at this point.
4. End -- the sale ends at saleEndTime or when the admin ends it early. Status transitions to ENDED.
5. Finalize -- anyone can finalize after the sale ends. It resolves the outcome: SUCCESS if total tokens sold meets the soft cap (or no soft cap), FAILED otherwise.

Happy path -- buying tokens

1. Eligibility and price preview -- the platform shows the advisory eligibility verdict and the expected token output before the investor commits. During presale, the discount multiplier is applied automatically.
2. ERC20 allowance -- the investor approves the sale contract to spend the payment amount. This is a separate transaction from the purchase.
3. Purchase -- the buy validates eligibility, phase, limits, and hard cap, then transfers payment in and distributes tokens (or records them under vesting if vesting is enabled).
4. Slippage protection -- if a minimum token amount is set and the calculated output falls below it, the transaction reverts with SlippageExceeded.

Presale-to-public transition

The presale-to-public transition is lazy: the on-chain status remains PRESALE until a transaction triggers the transition check. The platform computes the effective status from presaleEndTime and saleEndTime, so investors see the correct phase immediately after the presale window closes -- without waiting for a blockchain transaction.

Manual transition: the admin can transition to public sale at any time during PRESALE to force the transition on-chain.

Vesting withdrawal

1. Cliff gate -- no tokens can be withdrawn before vestingStart + vestingCliff.
2. Linear release -- after the cliff, the withdrawable amount grows linearly from 0 to the full purchased amount over vestingDuration.
3. Incremental withdrawal -- investors can withdraw multiple times as more tokens vest. Each withdrawal transfers only the newly vested portion.
4. Success gate -- token withdrawals are only available after finalization as SUCCESS. If the sale is FAILED, investors claim refunds instead.

Soft cap failure and refund

1. Finalization -- after the sale ends, finalization is permissionless. If total sold is below the soft cap, status is set to FAILED and failedTimestamp is recorded.
2. Grace period -- for 30 days after FAILED, administrator fund withdrawals are blocked (RefundGracePeriodActive). This protects investors from front-running.
3. Refund -- each investor claims a refund to receive back the contributions across every payment currency they used. The refund is per investor and cannot be claimed twice for the same contribution.
4. Unsold tokens -- the administrator can recover tokens not committed to any buyer, regardless of SUCCESS/FAILED outcome.

Related resources

• Token Sale: contracts, roles, and configuration surface
• Token Sale overview: operator and investor guides for the sale lifecycle
• Signing Flow: how transactions are signed and broadcast
• Compliance Transfer: transfer validation for compliance-enabled tokens
• Capabilities overview: how capabilities extend the platform