Token Sale (DAIO)
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
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.
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 | 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
| 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
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
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
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
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
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
- 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
| 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
| 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
- DAIO offering flow for the step-by-step participation and settlement sequence
- Capabilities layer overview for how capabilities extend the platform
- SMART Protocol integration (ERC-3643) for the compliance and identity framework
- Component catalog for the full platform inventory
XvP Settlement
The XvP Settlement capability provides atomic cross-party token exchanges with all-or-nothing local execution, per-sender approvals, expiration controls, and optional hashlock coordination for referenced external legs.
Issuer-signed scalar feed
Issuer-signed scalar feeds let trusted issuers publish signed integer values for a subject and topic, then expose the latest value through a Chainlink-compatible read interface.