Core Architecture
Sonic Name Service (SNS) is a fully modular, on-chain naming protocol built for the Sonic blockchain. Its architecture emphasizes openness, composability, and gas efficiency, enabling seamless integration with smart contracts, wallets, and applications.
At the heart of SNS lies a clean separation between logic and data. Modules like Caster
handle user actions, while low-level contracts like Ledger
and DotS
persist core state immutably.
🔗 1. DotS (Domain Ownership NFTs)
The DotS contract is the foundation of the Sonic Name Service — it issues a non-transferable NFT for every registered .s
domain.
🧠 In SNS, owning a DotS NFT = owning the domain. The NFT is the domain.
✅ Key Features
Each domain name (like
rex.s
) is minted as a unique ERC721 NFT.Metadata is provided by an external, upgradeable MetadataRenderer contract.
Only the owner (or assigned manager module) can renew the domain, configure subdomains, or update pointer records.
🎨 Dynamic NFT Metadata
DotS NFTs are dynamic:
Their metadata (name, image, expiry, flags) is rendered on-demand based on current state.
Data comes from the on-chain Ledger (expiry, creation date, etc.) and external modules (e.g., pointer types).
As domain properties change — e.g., after renewal or flag updates — the NFT image and metadata update automatically.
Example: If a domain is flagged as “Premium” or renewed for 5 years, the NFT's metadata reflects it in real-time.
🧱 2. Ledger (Packed Domain Storage)
Ledger
acts as the canonical storage layer for domain metadata:
Stores one
uint256
per domain nameHash:pointer
(160 bits): destination address (app, resolver, etc.)expiry
,createdAt
(32 bits each)flags
(8 bits): reserved, premium, locked, verified, etc.pointerType
(8 bits): type of endpointrenewalCount
(16 bits)
Pure storage: no internal logic
Updatable only by trusted modules (like
Caster
)Fully Merkle-compatible for proof-based lookups
🔮 3. Caster (Logic Entry Point)
The Caster
contract is the user-facing gateway to SNS. It handles:
🔑 New domain registrations
♻️ Domain renewals
💸 Fee collection and validation
🔁 Refunds (for overpayment or blocked names)
⚙️ Calls to
DotS.mint()
andLedger.setDomain()
It enforces rules by consulting:
ListController
(blocked/reserved/premium names)FeeController
(pricing logic)ResellersHub
andReferralHub
(commission routing)
📍 4. Pointer (Resolver)
SNS uses a "pointer model" instead of hardcoded resolvers.
Every domain in Ledger
includes:
pointer
: address or endpointpointerType
: how to interpret the pointer
Supported pointer types (example):
0
None
1
Smart contract resolver
2
Subgraph / GraphQL
3+
Future (IPFS, etc.)
💰 5. FeeController (Unified Fee Logic)
Central controller for all protocol fees, used by Caster
and potentially other modules.
💵 Calculates dynamic fees based on:
Domain length
Premium status
Renewal duration
🎯 Supports discounts or tiered pricing
🧩 Easily replaceable to support future upgrades
📤 6. RevenueDistributor
The RevenueDistributor is the central module responsible for allocating protocol revenue to SNS token holders.
💡 All native
S
tokens collected as the protocol’s community fee are routed into this contract.
🔁 Core Responsibilities
Receives: Community fee share from domain registrations, renewals, and future modules
Accumulates: All received
S
tokens securelyDistributes: Funds to SNS holders using an epoch-based claiming model
🕓 Epoch-Based Claiming
SNS uses a lightweight and efficient epoch system to distribute earnings:
Revenue is pooled per epoch (e.g. daily, weekly)
Token holders can claim their share of each completed epoch based on their SNS holdings
Claims can be batched across multiple epochs for efficiency
Prevents front-running and ensures fair participation
This design allows precise and transparent distributions while minimizing gas costs.
🪙 In SNS, the protocol’s success flows directly to its community. All S
tokens collected as fees ultimately pass through the RevenueDistributor and are claimable by SNS holders.
🧑💼 6. ResellersHub
Manages authorized resellers (e.g. wallet apps, frontends, integrations):
Stores:
name
,status
(active, deactivated)balance
,claimedAmount
createdAt
,lastClaim
🏦 Resellers earn a share of protocol fees
🪙 Commissions are claimable on-chain
✅ Batch add/remove, status toggling, and name updates
🎁 7. ReferralHub
The ReferralHub module manages the SNS protocol’s multi-level referral system, enabling fair and composable incentive sharing for domain registrations and renewals.
💡 The system supports up to 3 levels of referral depth, with configurable fee sharing for each level.
✅ Multi-Level Referrals Supports referral chains up to 3 levels deep, where:
Level 1 (direct referrer) receives the highest share
Levels 2 and 3 receive progressively smaller shares
All levels are optional; missing levels default to zero allocation
🔁 Automatic Referral Propagation
New users can be attributed to a referrer at registration time
Referrals are tracked per address, not per domain
⚙️ Composable and Optional
Integrators and frontends may choose to use or ignore the referral system
Default behavior applies when no referrer is provided
🔐 ReferralHub Is Modular
All logic lives in the
ReferralHub
moduleCan be upgraded or replaced without touching core domain contracts
Compatible with other modules like
FeeController
,Caster
, andResellersHub
🔡 8. SubdomainHub
Responsible for assigning virtual subdomains under root domains:
Subdomains like
a.rex.s
are not NFTsRoot domain owner defines access/usage
SNS supports assigning a
user
(not owner) per subdomain🧩 Extensible for project-specific use (e.g. DAOs, teams, dApps)
🚫 9. ListController
Unified module to manage name restrictions:
❌ Blocked names: can’t be registered
🔒 Reserved names: can only be registered by allowlisted addresses
💎 Premium names: require higher fees
Queried in real-time by
Caster
during registration
📣 SNS supports deep, performance-driven referral loops — ideal for social sharing, affiliate integrations, and community-led onboarding.
Last updated
Was this helpful?