# Token Sale (DAIO) Source: https://docs.settlemint.com/docs/architecture/components/capabilities/token-sale The Token Sale capability provides primary offering infrastructure for SMART tokens, with ERC-20 payment support, optional terms acknowledgement, optional vesting, soft-cap finalization, and identity-gated buyer eligibility. The Token Sale capability deploys and operates primary offerings for SMART tokens. The sale contract records setup, payment currencies, buyer terms, presale access, purchases, vesting, refunds, and finalization. Eligibility comes from the token's SMART Protocol compliance rules, so the offering can sell only to buyers who can receive the asset. ## Scope [#scope] Token Sale covers the offering itself: sale deployment, payment configuration, sale funding, buyer eligibility checks, terms acknowledgement, purchase recording, finalization, refunds, and token withdrawal. Secondary trading, lifecycle compliance outside the purchase path, and post-offering asset servicing remain with the SMART Protocol and other DALP capabilities. For the per-asset rule model behind purchase eligibility, see [asset policy](/docs/architecture/concepts/asset-policy). ## Before activation [#before-activation] A sale starts in `SETUP`. The creation request sets the sale window, hard cap, accepted ERC-20 payment currencies, optional soft cap, optional purchase limits, optional presale controls, optional vesting, and optional terms hash. The sale contract must hold at least the full hard cap of the sold token before `activateSale` succeeds. If a presale is configured, activation moves the sale to `PRESALE`. Without presale configuration, activation moves the sale directly to `PUBLIC_SALE`. The deprecated `ACTIVE` status remains in the API enum for legacy indexed data. Current contracts use `PRESALE` and `PUBLIC_SALE` for active sale phases. ## Contract architecture [#contract-architecture] | Contract | Responsibility | | ---------------------------------- | ------------------------------------------------------------------------------------ | | IDALPTokenSale | Interface defining the complete Token Sale API (functions, events, errors) | | DALPTokenSaleImplementation | Main logic: compliance checks, vesting, multi-currency pricing, lifecycle management | | DALPTokenSaleProxy | Factory-managed proxy preserving state and address across implementation updates | | DALPTokenSaleFactoryImplementation | Factory for CREATE2 deployment of new sale instances with deterministic addresses | The proxy pattern allows implementation updates without redeploying a sale or changing its address. The factory uses CREATE2 so teams can predict a sale address before deployment. ## Roles [#roles] | Role | Source | Permissions | | ---------------------------- | --------------------- | -------------------------------------------------------------------------------- | | SALE\_ADMIN\_ROLE | Token access manager | Configure sale parameters, manage lifecycle transitions, set vesting and pricing | | FUNDS\_MANAGER\_ROLE | Token access manager | Withdraw collected sale proceeds | | GOVERNANCE\_ROLE | Token access manager | Create token sales for the governed token | | TOKEN\_FACTORY\_MODULE\_ROLE | System access control | Create token sales through approved system automation | | SYSTEM\_MANAGER\_ROLE | System access control | Update the shared Token Sale implementation used by the factory | Role assignments flow through the token's ISMARTTokenAccessManager, so sale administration uses the same access control framework as the underlying asset. ## Sale lifecycle [#sale-lifecycle] The token sale progresses through setup, active sale phases, and final outcomes. Transitions are enforced on-chain. | Phase | Status | Behavior | | ----------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Setup | `SETUP` | Configure timing, pricing, payment currencies, purchase limits, and vesting before purchases open. | | Presale | `PRESALE` (optional) | Accept purchases from whitelisted presale investors only. The contract lazily advances to public sale after the presale end time when a write action runs. | | Public Sale | `PUBLIC_SALE` | Accept purchases from all eligible buyers. Enforce per-investor limits and hard cap. | | Paused | `PAUSED` | Temporarily halt all purchases. Configuration preserved. Can resume to presale or public sale. | | Ended | `ENDED` | Manually concluded. Can be finalized after the sale closes. | | Success | `SUCCESS` | Finalized successfully. Buyers withdraw tokens according to vesting and soft-cap rules. | | Failed | `FAILED` | Finalized below the configured soft cap. Buyers can claim refunds for recorded contributions. | The usual path is setup, optional presale, public sale, and finalization. Paused is a reversible detour from an active phase. If the sale is paused during presale and the presale end time passes, unpausing restores the previous phase and then advances to public sale. If a soft cap is configured, finalization records whether the sale succeeded or failed. ## Payment support [#payment-support] The token sale accepts approved ERC-20 tokens as payment. Native currency payments are not part of the current sale contract. Each accepted currency has a configurable price ratio that determines the exchange rate between payment currency and sale tokens. Price ratios are set by the sale administrator during setup and can accommodate different decimal precisions across payment currencies. The contract calculates token amounts at purchase time based on the configured ratio and rejects purchases where the calculated token amount is below the buyer's minimum expected amount. ## Vesting [#vesting] When vesting is configured, purchased tokens release according to the configured schedule: * A **cliff period** must elapse before any tokens can be withdrawn * After the cliff, tokens release linearly over the configured **vesting duration** * Investors withdraw their vested portion at any time after the cliff Without vesting and without a soft cap, tokens transfer to the buyer during purchase. If a soft cap is configured, purchased tokens stay in the sale contract until the sale finalizes as `SUCCESS`; buyers then withdraw the amount available under any vesting schedule. ## Compliance [#compliance] Buyer eligibility is enforced through the SMART Protocol compliance layer. Before any purchase executes, the contract checks whether the underlying token can transfer the purchased amount from the sale contract to the buyer. Purchases that fail the token's compliance rules are rejected. The purchase check uses the same mechanism DALP uses for transfer restrictions and investor verification. The same rule path applies during the offering and later transfers. When a terms hash is configured, a buyer must acknowledge the terms before purchasing. During presale, the buyer must also be on the presale whitelist. ## Event-indexed sale state [#event-indexed-sale-state] Token Sale contracts emit sale-state data for DALP to build the indexed read model from lifecycle events over time. `DALPTokenSaleCreated` seeds the sale address, token address, sale timing, hard cap, purchase limits, and initial optional configuration such as payment currencies, soft cap, presale settings and whitelist, vesting settings, and terms hash. Later events keep mutable sale state current: `SaleParametersUpdated` identifies the operator and carries `saleStartTime`, `saleEndTime`, `hardCap`, `minPurchase`, `maxPurchase`, `softCap`, and `softCapReached` as sale-state fields; `PaymentCurrencyAdded` and `PaymentCurrencyRemoved` update accepted payment currencies; `PresaleConfigured`, `VestingConfigured`, `PresaleWhitelistUpdated`, and `TermsHashSet` update optional sale controls; `SaleStatusUpdated` and `PhaseTransitioned` update sale status; `TokensPurchased` records purchases and sold totals; `SaleTimingExtended` updates the sale end time; and `SoftCapReached` marks the soft cap as reached. Use the API, CLI, or Token Sale read model for operational queries. Contract events provide audit evidence and indexing inputs. A current application view needs the creation event plus the later lifecycle, configuration, purchase, timing, and soft-cap events. The API remains the stable integration boundary for applications. ## Trust boundaries [#trust-boundaries] * **Eligibility checks**: every purchase is checked through the SMART Protocol compliance layer before tokens are allocated. * **Terms gate**: when a terms hash exists, purchases require prior buyer acknowledgement of that hash. * **Presale gate**: presale purchases require a whitelisted buyer address. * **Reentrancy protection**: purchase, refund, token withdrawal, unsold-token withdrawal, and fund withdrawal operations use ReentrancyGuard. * **Pausable operations**: the sale administrator can halt purchases during incident response and resume the active phase later. * **Setup-time controls**: hard cap, purchase limits, payment currencies, presale settings, vesting, and terms hash are configured before activation. Active sales can be extended through the sale timing control. * **Refund protection**: if a soft-cap sale finalizes as `FAILED`, investors claim payment-currency refunds. Funds withdrawal is blocked during the refund grace period. ## Dependencies [#dependencies] | Dependency | Role | | -------------------------------- | -------------------------------------------------- | | SMART Protocol compliance layer | Buyer eligibility verification | | Token contracts (SMART Protocol) | The digital asset being sold | | System access control | System automation and implementation management | | Token access manager | Role assignments for sale and funds administration | ## Configuration surface [#configuration-surface] | Parameter | Scope | Mutability | | ------------------------------------------- | ------------- | ----------------------------------------------------------------- | | Sale timing (start, end, presale window) | Sale instance | Set during setup; sale end can be extended while active or paused | | Price ratios per payment currency | Sale instance | Configurable by `SALE_ADMIN_ROLE` during setup | | Per-investor purchase limits (min/max) | Sale instance | Set during setup | | Hard cap (total tokens available) | Sale instance | Immutable after activation | | Soft cap | Sale instance | Set during setup; finalization uses it to mark success or failure | | Vesting parameters (start, duration, cliff) | Sale instance | Set during setup; vesting start must be at or after sale end | | Terms hash | Sale instance | Set during setup; buyers acknowledge it before purchasing | | Accepted payment currencies | Sale instance | Managed by `SALE_ADMIN_ROLE` during setup | Token Sale smart contracts, developer APIs, CLI commands, and UI workflows are available. Use the surface exposed by your deployment to create the offering, fund the sale contract, activate the sale, monitor purchases, finalize the outcome, and handle refunds or token withdrawals. ## Related [#related] * [DAIO offering flow](/docs/architecture/flows/daio-offering) for the step-by-step participation and settlement sequence * [Capabilities layer overview](/docs/architecture/components/capabilities) for how capabilities extend the platform * [SMART Protocol integration (ERC-3643)](/docs/architecture/components/asset-contracts/smart-protocol-integration) for the compliance and identity framework * [Component catalog](/docs/architecture/components) for the full platform inventory