# 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.