Skip to main content

​
Overview

SettlementSale is Sonar’s standard smart contract for token sales. It supports both fixed-price sales and English auctions, with settlement computed offchain and recorded onchain.
For standard sale configurations, Sonar deploys and manages this contract for you. You only need to deploy your own contract if you have custom requirements.
Source code: SettlementSale.sol

​
Deployment

You can deploy a SettlementSale contract via the Founder Dashboard. In order to deploy the contract, you must have configured the following settings in the sale’s general settings page:
  • Chain and payment tokens
  • Proceeds receiver address - the address that will receive the proceeds of the sale
  • Contract admin address - see Roles & Permissions for more details
Contract deployments are triggered differently depending on whether it is a test sale or production sale.
  • Test sales - the contract can be deployed at any time via the Integration page. You are able to redeploy the contract at any time.
  • Production sales - the contract is currently deployed by the Sonar team on request.

​
Sale Stages

The contract progresses through the following stages:
By default, new sales start directly in the Commitment stage. An optional PreOpen stage exists for legacy reasons or for sales with non-standard requirements, but it is not enabled by default.

​
Commitment

The active commitment phase where participants submit bids.
  • Participants with valid purchase permits can submit bids
  • Bids specify price, amount, and lockup preference
  • Bids can only increase (amounts and prices cannot be lowered)
  • Each new bid replaces the previous bid for the same entity
  • Bids are only accepted between the configured opensAt and closesAt timestamps
Transitions to: Cancellation or Settlement

​
Cancellation

Optional cooling-off period for regulatory compliance (e.g., EU requirements).
  • Participants can cancel their bids and receive immediate refunds
  • Preliminary allocations are computed offchain and shown to participants
  • Once a bid is cancelled, it cannot be reinstated
Transitions to: Settlement

​
Settlement

Final allocations are computed offchain and recorded onchain.
  • Settler role records allocations via setAllocations()
  • Each entity’s accepted amount is recorded per payment token
  • Settlement is finalized when all allocations are recorded
Transitions to: Done

​
Done

Sale is complete. Refunds and proceeds can be processed.
  • Refunds equal commitment minus accepted allocation
  • Participants can claim refunds (if enabled) or refunder role processes them
  • Proceeds are withdrawn to the designated receiver

​
Roles & Permissions

The contract uses role-based access control. Multiple addresses can hold each role.
RolePurposeTypical Holder
DEFAULT_ADMIN_ROLEFull administrative access, can grant/revoke all rolesProject (always)
SALE_MANAGER_ROLEManage sale stages (open, close, reopen)Sonar or Project
PURCHASE_PERMIT_SIGNER_ROLESign purchase permits that authorize participationSonar (always)
SETTLER_ROLERecord final allocations during settlementSonar or Project
SETTLEMENT_FINALIZER_ROLEFinalize settlement (signing off of the allocations set by the settler) and transition to DoneProject (always)
REFUNDER_ROLEProcess refunds for participantsSonar or Project
PAUSER_ROLEEmergency pause functionalitySonar or Project
TOKEN_RECOVERER_ROLEEmergency token recovery (not granted by default)Granted manually by the admin if needed
The project always retains DEFAULT_ADMIN_ROLE and full control over the contract. Sonar holds PURCHASE_PERMIT_SIGNER_ROLE to authorize eligible participants.

​
Key Concepts

​
Bids

Each entity has a single active bid containing:
FieldDescription
priceThe maximum price the entity is willing to pay (for auctions)
amountTotal commitment amount across all payment tokens
lockupWhether the entity opts for token lockup (general information on lockup)
The price is denominated in the auction’s bid increment. For example, if the bid increment is $0.01, then a price of 100 represents a willingness to pay $1.00.
Bid constraints:
  • Amounts can only increase, never decrease
  • Prices can only increase, never decrease
  • Lockup can be enabled but not disabled once set
  • Forced lockup can be required via purchase permit

​
Entity vs Wallet

  • Entity: A compliance identity (individual or organization) verified by Sonar
  • Wallet: A blockchain address used to commit funds
One entity can use multiple wallets, but each wallet is tied to exactly one entity. Limits and allocations are tracked at the entity level, not wallet level.

​
Multi-Token Support

The contract accepts multiple payment tokens (e.g., USDC and USDT):
  • All tokens assumed to have the same value (e.g., USD stablecoins)
  • Commitments, allocations, and refunds tracked separately per token
  • Each transaction uses a single payment token
Not compatible with rebasing tokens (e.g., stETH) or fee-on-transfer tokens. Using incompatible tokens will result in incorrect accounting.

​
When to Use

Use SettlementSale when:
  • Running a fixed-price sale with pro-rata or iterative fill settlement
  • Running an English auction
  • You need offchain settlement computation
  • Standard Sonar compliance and permit validation is sufficient
Consider a custom contract when:
  • You need first-come first-served with on-chain ordering
  • You have custom allocation logic
  • You need multiple commitments per entity (increase and decrease)

​
See Also

Custom Contracts

Build your own contract with Sonar permit validation

Settlement Strategies

How allocations are computed

Purchase Permits

How permits authorize participation

Sale Lifecycle

End-to-end sale process