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 endpoint

  • renewalCount (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() and Ledger.setDomain()

It enforces rules by consulting:

• ListController (blocked/reserved/premium names)

• FeeController (pricing logic)

• ResellersHub and ReferralHub (commission routing)

---

📍 4. Pointer (Resolver)

SNS uses a "pointer model" instead of hardcoded resolvers.

Every domain in Ledger includes:

• pointer: address or endpoint

• pointerType: how to interpret the pointer

Supported pointer types (example):

Type	Meaning
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 securely

• Distributes: 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 module

• Can be upgraded or replaced without touching core domain contracts

• Compatible with other modules like FeeController, Caster, and ResellersHub

---

🔡 8. SubdomainHub

Responsible for assigning virtual subdomains under root domains:

• Subdomains like a.rex.s are not NFTs

• Root 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.