> For the complete documentation index, see [llms.txt](https://docs.sns.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sns.net/intro/core-architecture.md).

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sns.net/intro/core-architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.