Custom Contracts

Overview

For most sales, Sonar deploys and manages the SettlementSale contract for you. However, if you have specific requirements not covered by the standard contract, you can build a custom contract that integrates with Sonar’s compliance infrastructure.

When to Build a Custom Contract

You need custom onchain logic beyond what Sonar provides
You want to integrate token sale logic with other contract functionality
You have specific requirements for how commitments are structured
You want to extend the standard contract with additional features

Deployment Models

Sonar supports different levels of customization:

Model	Contract	Settlement
Standard	Sonar deploys SettlementSale	You determine allocations via the dashboard; Sonar syncs to contract
Fully Custom	You deploy custom contract	You determine and write allocations directly to contract

The Core Integration

Your custom contract must validate purchase permits—signed authorizations from Sonar that prove a wallet is eligible to participate. Sonar handles all compliance (KYC/KYB, accreditation, jurisdiction checks) and issues permits for eligible participants. The permit contains:

Entity identity and authorization proof
Purchase limits (min/max amounts)
Price limits (for auctions)
Expiration timestamp

Purchase Permit

Sonar generates permits with this structure (see also the sonar contract repo):

struct PurchasePermitV3 {
    bytes16 saleSpecificEntityID;  // Sale-specific entity identifier (same entity has different IDs per sale)
    bytes16 saleUUID;              // Your Sale UUID
    address wallet;                // Authorized wallet address
    uint64 expiresAt;              // Unix timestamp expiration
    uint256 minAmount;             // Minimum commitment amount
    uint256 maxAmount;             // Maximum commitment amount
    uint64 minPrice;               // Minimum bid price (for auctions)
    uint64 maxPrice;               // Maximum bid price (for auctions)
    uint64 opensAt;                // Unix timestamp when permit becomes valid (inclusive)
    uint64 closesAt;               // Unix timestamp when permit stops being valid (exclusive)
    bytes payload;                 // Additional data (e.g., forcedLockup)
}

Validation

To ensure the validity of a purchase permit, you need to verify the following aspects (see also the example implementation below). Please make sure to implement all of these checks to ensure correct enforcement of the requirements of your sale.

The ECDSA signature was issued by the Sonar signer
The permit’s sale UUID matches yours
The permit is not expired
The current time is within the permit’s time window (opensAt <= now < closesAt)
The sender matches the wallet address in the permit
The commitment amount is within the minimum and maximum amount limits
The bid price is within the minimum and maximum price limits (for auctions)

Example Validation

These snippets are based on the example sale contract.

1. Signature Verification

You must verify that permits are signed by Sonar’s authorized signer:

// Grant this role to the signer address provided by Sonar
bytes32 public constant PURCHASE_PERMIT_SIGNER_ROLE = keccak256("PURCHASE_PERMIT_SIGNER_ROLE");

// Verify signature in your purchase function
address recoveredSigner = PurchasePermitV3Lib.recoverSigner(permit, signature);
if (!hasRole(PURCHASE_PERMIT_SIGNER_ROLE, recoveredSigner)) {
    revert PurchasePermitUnauthorizedSigner(recoveredSigner);
}

2. Sale UUID Validation

Prevent permit reuse across different sales:

if (permit.saleUUID != saleUUID) {
    revert PurchasePermitSaleUUIDMismatch(permit.saleUUID, saleUUID);
}

3. Expiration Checks

Permits have short expiration times:

if (permit.expiresAt <= block.timestamp) {
    revert PurchasePermitExpired();
}

4. Time Window Validation

Permits include a time window during which they are valid for commitments:

if (block.timestamp < permit.opensAt) {
    revert PurchasePermitNotYetValid();
}
if (block.timestamp >= permit.closesAt) {
    revert PurchasePermitWindowClosed();
}

5. Wallet Authorization

Ensure the permit is used by the authorized wallet:

if (permit.wallet != msg.sender) {
    revert PurchasePermitSenderMismatch(msg.sender, permit.wallet);
}

Integration Patterns

Wallet-Level Tracking (Basic)

The example contract tracks purchases by wallet address:

// Track amount purchased by each wallet
mapping(address => uint256) public amountByAddress;

function purchase(uint256 amount, /* permit params */) external {
    _validatePurchasePermit(purchasePermit, purchasePermitSignature);
    
    uint256 newTotalAmount = amountByAddress[msg.sender] + amount;
    
    // Validate purchase limits
    if (newTotalAmount < purchasePermit.minAmount) {
        revert AmountBelowMinimum(newTotalAmount, purchasePermit.minAmount);
    }
    if (newTotalAmount > purchasePermit.maxAmount) {
        revert AmountExceedsMaximum(newTotalAmount, purchasePermit.maxAmount);
    }
    
    amountByAddress[msg.sender] = newTotalAmount;
}

Entity-Level Tracking

One might want to additionally enforce limits by entity, across all wallets they can use:

// Track amount purchased by each entity
mapping(bytes16 => uint256) public amountByEntity;

function purchase(uint256 amount, /* permit params */) external {
    _validatePurchasePermit(purchasePermit, purchasePermitSignature);

    bytes16 entityID = purchasePermit.saleSpecificEntityID;
    uint256 newTotalAmount = amountByEntity[entityID] + amount;

    if (newTotalAmount > purchasePermit.maxAmount) {
        revert AmountExceedsMaximum(newTotalAmount, purchasePermit.maxAmount);
    }

    amountByEntity[entityID] = newTotalAmount;
}

Auction bid price validation

If you are running a sale with a dynamic pricing model where the user can commit with a requested price (e.g. auctions), you should validate the bid price is within the minimum and maximum price limits.

struct Bid {
    uint64 price;
    uint256 amount;
}

mapping(address => Bid) internal bidByAddress;

function processBid(uint64 price, uint256 amount, /* permit params */) external {
    _validatePurchasePermit(purchasePermit, purchasePermitSignature);

    if (price > purchasePermit.maxPrice) {
        revert BidPriceExceedsMaxPrice(price, purchasePermit.maxPrice);
    }

    if (price < purchasePermit.minPrice) {
        revert BidPriceBelowMinPrice(price, purchasePermit.minPrice);
    }

    if (amount < purchasePermit.minAmount) {
        revert BidBelowMinAmount(amount, purchasePermit.minAmount);
    }

    if (amount > purchasePermit.maxAmount) {
        revert BidExceedsMaxAmount(amount, purchasePermit.maxAmount);
    }
    
    // Replace the existing bid
    bidByAddress[msg.sender] = Bid(price, amount);
}

Getting the Signer Address

Sonar signs all purchase permits using a global infrastructure key. When deploying your contract, grant the PURCHASE_PERMIT_SIGNER_ROLE to this address. For EVM chains: 0x9a1964e04d10ccfe1a9ce300d943f71c6e3ae24c For other chains, contact support@echo.xyz to get the correct signer address.

The permit signer role is always held by Sonar’s infrastructure. This ensures all purchase authorizations flow through Sonar’s compliance verification, maintaining the integrity of the permit system.

SettlementSale Reference

Reference for the standard Sonar sale contract

Frontend Integration

Generate and use purchase permits in your frontend

Purchase Permits

Deep dive into permit structure and validation

Example Contract

View the example sale contract on GitHub

Planning Your Sale

Integration Guides

Technical Features

Contract Reference

JS Reference

HTTP Reference

Overview

When to Build a Custom Contract

Deployment Models

The Core Integration

Purchase Permit

Validation

Example Validation

1. Signature Verification

2. Sale UUID Validation

3. Expiration Checks

4. Time Window Validation

5. Wallet Authorization

Integration Patterns

Wallet-Level Tracking (Basic)

Entity-Level Tracking

Auction bid price validation

Getting the Signer Address

See Also

SettlementSale Reference

Frontend Integration

Purchase Permits

Example Contract

​Overview

​When to Build a Custom Contract

​Deployment Models

​The Core Integration

​Purchase Permit

​Validation

​Example Validation

​1. Signature Verification

​2. Sale UUID Validation

​3. Expiration Checks

​4. Time Window Validation

​5. Wallet Authorization

​Integration Patterns

​Wallet-Level Tracking (Basic)

​Entity-Level Tracking

​Auction bid price validation

​Getting the Signer Address

​See Also

SettlementSale Reference

Frontend Integration

Purchase Permits

Example Contract

Overview

When to Build a Custom Contract

Deployment Models

The Core Integration

Purchase Permit

Validation

Example Validation

1. Signature Verification

2. Sale UUID Validation

3. Expiration Checks

4. Time Window Validation

5. Wallet Authorization

Integration Patterns

Wallet-Level Tracking (Basic)

Entity-Level Tracking

Auction bid price validation

Getting the Signer Address

See Also