# Introduction
## **Welcome to the Sonic Name Service!**
**Sonic Name Service (SNS)** is a fully modular, extensible, and on-chain naming protocol built for the Sonic network. Inspired by ENS but purpose-built for speed, composability, and scalability, SNS enables users and developers to register `.s` domains that resolve across wallets, dApps, and smart contracts.
Each `.s` domain is represented as an ERC721 NFT, ensuring true ownership, transferability, and integration with existing Web3 infrastructure. The protocolโs architecture is built around a lightweight **Ledger**, a flexible **Registrar (Caster)**, and a suite of optional modules for referrals, resellers, renewals, blacklists, and subdomains โ all working together through clean, minimal interfaces.
### SNS is designed from day one to be:
* ๐งฉ **Composable** โ Each module (e.g. FeeRouter, RenewalEngine, ResellerHub) is deployable and replaceable without touching core logic.
* โก **Gas-optimized** โ Packed storage, minimal calldata, and a short TLD `.s` reduce every byte of cost.
* ๐งช **Tested and Transparent** โ Deployed with full coverage and modern testing (Viem + Hardhat), and readable by anyone.
* ๐ **Secure and Permissioned** โ Role-based access controls are enforced on all write actions.
* ๐ **Upgradeable by Design** โ While core contracts are immutable, logic lives in modules that can evolve independently.
* ๐ง **Developer-first** โ Interfaces and libraries are structured for easy contract-to-contract use and off-chain resolution tooling.
### Why `.s`?
Unlike verbose alternatives (e.g. `.sonic`, `.network`, `.xyz`), `.s` minimizes calldata, storage, and UI clutter. In fact, `.s` is one of the shortest possible valid TLDs โ saving bytes in every transaction and every EVM call. This is not just a branding choice โ itโs a performance optimization.
### How it works
At the heart of SNS is a **name-to-token mapping**, where:
* Each domain (e.g. `rex.s`) maps to a `tokenId` (`keccak256(name)`),
* Metadata is stored on-chain in a packed format inside the **Ledger**,
* Ownership of the token is canonical โ this is the root controller of the domain,
* Subdomains (`app.rex.s`) are stored and resolved separately using `SubdomainHub`.
The SNS system follows the principle of **clean separation of concerns**: resolution logic, metadata, fees, access control, and registry state are all isolated and replaceable.
### License and Open-Source Vision
SNS is currently released under a **source-available license**:
```
SPDX-License-Identifier: BUSL-1.1
Copyright (c) 2025 Sonic Name Service
Source-available for audit, integration, and visibility only.
Forking, modification, or commercial use requires written permission.
```
This allows auditability, developer integration, and transparency โ while protecting the protocolโs core mechanics during early growth. SNS is committed to fully open-sourcing under a license such as Apache 2.0 in the future, once the ecosystem and governance mechanisms have matured.
### Whatโs inside this documentation
This GitBook provides:
* ๐ A complete guide to the SNS contract architecture
* ๐ฆ Technical specs for all modules and storage layouts
* ๐ Integration examples for dApps, wallets, and registrars
* ๐งช Testing tips and security considerations
* ๐งญ A roadmap of future modules and governance
Whether youโre building a wallet integration, writing a registrar frontend, or extending the SNS protocol itself, this guide is designed to help you understand and contribute confidently.
# 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.
# SNS vs. ENS
**How Sonic Name Service differs from Ethereum Name Service**
While SNS and ENS share the same vision โ decentralized identity and naming โ their architectures diverge significantly to meet the evolving demands of high-performance L2s and modern dApps.
This page breaks down the technical and practical differences between **SNS** (Sonic Name Service) and **ENS** (Ethereum Name Service).
### ๐ง Architecture Comparison
| Feature | **ENS** | **SNS** |
| ------------------------------ | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Domain Representation** | ERC721 NFTs | ERC721 NFTs |
| **Storage Structure** | Multiple contracts (ENS Registry, Resolver, Registrar) | Modular contracts with centralized `Ledger` for packed metadata โ drastically reduces gas and storage via efficient bit-level encoding |
| **Metadata** | Mostly static, rendered off-chain | Fully dynamic, rendered via on-chain state + `MetadataRenderer` |
| **Subdomain Ownership** | Full ownership of subdomains | Full ownership of subdomains + Root domain owner assigns *users* |
| **Fee Routing** | Hardcoded per contract | Controlled via `FeeController` (upgradable) |
| **Blacklist / Reserved Names** | Not enforced at core level | Controlled via `ListController` |
| **Referral System** | Not natively supported | Built-in multi-level referral logic (up to 3 levels) |
| **Reseller Support** | None | Native `ResellersHub` with metadata, payouts, and commission tracking |
| **Claiming Revenue** | No fee redistribution | SNS token holders can claim protocol revenue via `RevenueDistributor` |
### โก Performance & Cost
| Feature | **ENS** | **SNS** |
| ----------------- | ----------------------------- | ---------------------------------------- |
| **Chain** | Ethereum mainnet | Sonic (ultra-low fees, ultra-high speed) |
| **Calldata Size** | Higher (e.g., `.eth` vs `.s`) | Smaller (`.s` TLD = fewer bytes) |
| **Gas Costs** | High (due to Ethereum L1) | Minimal (optimized for Sonic) |
### ๐งฑ Composability
| Category | **ENS** | **SNS** |
| ---------------------------- | ----------------------- | --------------------------------------------------- |
| **Upgradeable Core Modules** | Limited | Modular, upgradeable via roles |
| **Custom Resolvers** | Supported | Planned via `Pointer` system (standard & subgraph) |
| **DAO Integration** | Optional, external | Core to revenue distribution and governance |
| **Protocol Incentives** | Mostly organic adoption | Built-in rewards for builders, referrers, resellers |
### ๐ Security & Control
| Feature | **ENS** | **SNS** |
| ----------------------------- | ---------------------- | ---------------------------------------------------------- |
| **Ownership Model** | NFT-based | NFT-based |
| **Expiration & Grace Period** | Yes | Yes (customizable via `Ledger`) |
| **Permission Roles** | Limited (mostly admin) | Granular (`AGENT_ROLE`, `BALANCE_MANAGER`, etc.) |
| **Reentrancy Protections** | Varies by resolver | All modules protected (e.g., `claim`, `receiveCommission`) |
#### ๐ท Ownership Model
| Feature | **ENS** | **SNS** |
| ---------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| **Domain Ownership** | Stored in the ENS Registry contract, not tied directly to the NFT | **Directly tied to the DotS NFT** โ NFT owner **is** the domain owner |
| **Ownership Transfer** | Transferring the NFT **does not** update ENS Registry automatically โ requires additional transactions | Transferring a DotS NFT **automatically transfers domain ownership**, no updates needed elsewhere |
| **Ledger Design** | Registry holds ownership info, separate from metadata/resolver | **Ledger stores only metadata**, not ownership โ full separation for efficiency and clarity |
| **Model Type** | Coupled: Registry + NFT must stay in sync | **Decoupled**: DotS NFT = single source of truth for domain ownership |
***
### Summary
| **ENS** | **SNS** |
| ---------------------------------------- | -------------------------------------------------------- |
| Mature and widely adopted on Ethereum | Fresh, modular, and optimized for L2-native applications |
| `.eth` domains with legacy compatibility | `.s` domains with tiny calldata and fast resolution |
| High gas costs limit experimentation | Built for speed, scale, and composability |
# SNS Roadmap
SNS is being deployed in structured phases to ensure modular scalability, ecosystem alignment, and long-term sustainability.
#### ๐ฅ Phase 0: SNS Token Launch
**๐ฅ 0.1 Burn-to-Mint on WigoSwap**
* **Timeline**: โ Completed
* **Platform**: WigoSwap (Fantom)
* **Mechanism**: Users burned WIGO tokens to mint SNS tokens
* **Purpose**: Establish early token distribution while supporting WIGO ecosystem
* **Impact**: Bootstrapped SNS token holders with value-aligned users
**๐ 0.2 SNS Token IDO on Fantom**
* **Timeline**: โ Completed (post burn-to-mint)
* **Platform**: Fantom
* **Mechanism**: Initial DEX Offering (IDO) for SNS token
* **Token Symbol**: `SNS`
* **Utility**: Governance, staking, participation in protocol fee distribution
* **Result**: SNS token entered public circulation and core protocol holders were established
**๐ 0.3 Migration**
* **Timeline**: โ Completed
* **Platform**: WigoSwap (Fantom) & Defive (Sonic)
* **Result**: Users migrated their SNS tokens on Fantom to SNS tokens on Sonic
#### ๐ 1. Private Domain Reservation
* Reserved `.s` domains for core contributors, partners, and protocol-aligned teams
* Each reserved name is tied to a specific address and **can only be registered by that address**.
* These domains are not pre-minted โ they are locked until claimed by their rightful owners during public registration.
* Ensures that premium, protocol-critical, or identity-sensitive names (e.g., `team.s`, `sns.s`, `rex.s`) are protected from front-running or squatting.
***
#### ๐ 2. Public Domain Reservation
* Open reservation of `.s` root domains for the community
* Each reserved name is tied to a specific address and **can only be registered by that address**.
***
#### ๐๏ธ 3. DAO Governance Launch
* SNS holders will govern:
* Fee multipliers
* Module parameters
* Revenue distribution mechanics
* `RevenueDistributor` feeds community earnings into DAO-based claiming
* DAO tools will be integrated via Snapshot or custom veSNS model
***
#### ๐งฉ 4. Reseller Dashboard & SDK Activation
* Activate `ResellersHub` for commission tracking and payments
* Build dashboard for monitoring reseller stats and balances
* SDKs available for 3rd-party storefronts, wallets, and app integrations
* Balance tracking and claiming is fully on-chain and non-custodial
***
#### ๐ 5. Core Launch on Sonic Mainnet
* Launch of all SNS core contracts on **Sonic**:
* `DotS`, `Ledger`, `Caster`, `ListController`, `FeeController`, `ReferralHub`, `ResellersHub`, `RevenueDistributor`
* Public `.s` registration goes live
* UI, APIs, and contract SDKs available for integrators
***
#### ๐ง 6. Standard Resolvers Go Live
* `Pointer` module enables resolution to:
* Wallets, contracts, apps, subgraphs
* Pluggable record types, pointer type registry, and optional reverse records
***
#### ๐งฌ 7. Subdomain Activation
* Launch of `SubdomainHub`:
* Assign roles for subdomain managers
* Dynamic virtual ownership (not NFTs)
* Usage-based subdomain limits (some free, some paid)
* Custom logic per domain (e.g. `free.rex.s`, `pro.rex.s`)
***
#### ๐ 8. Ecosystem dApp Integrations
* `.s` names usable in:
* Wallets
* DEX frontends
* Governance tools
* Social protocols
* Integration SDKs and incentives for protocols adopting SNS resolution
***
#### ๐ 9. Web2 & DNS Bridge Research
* Researching `.s` โ Web2 integrations:
* HTTP resolution and forwarding
* `.s` as pseudo-DNS namespace
* Email routing and traditional domain functionality
* Goal: make `.s` domains usable across Web2 and Web3
***
#### **Stay Informed**
Our roadmap is constantly evolving, and we will keep the community informed with the latest updates and progress. Make sure to follow our channels for key announcements and new developments. The future of decentralized name services is just around the corner, and we canโt wait to launch the Sonic Name Service!
# Tokenomics
The **Sonic Name Service (SNS)** tokenomics model is designed to ensure long-term sustainability, community engagement, and fair distribution of the SNS tokens. Below is a breakdown of the key components of the SNS token distribution and its utility within the ecosystem.
#### **1. Total Supply**
The total supply of SNS tokens is **100 million (100M)**. Importantly, the SNS token supply will **never exceed** this amount, ensuring a controlled and deflationary supply model.
#### **2. Token Allocation**
The distribution of SNS tokens is structured to support the growth and development of the SNS platform while incentivizing participation from both developers and the community. The allocation is as follows:
* **50%** โ **Burn to Mint Distribution**: Half of the total SNS supply will be distributed through the burn-to-mint mechanism, rewarding users who participate by burning their WIGO tokens in exchange for SNS.
* **25%** โ **Developer Allocation**: A quarter of the total supply is reserved for the development team, ensuring long-term commitment and project sustainability.
* **15%** โ **Ecosystem Incentives**: These tokens will be used to incentivize participation in the ecosystem, such as rewarding users for contributing to the platform or helping to grow the SNS user base.
* **10%** โ **DAO**: A portion of the tokens is reserved for the Decentralized Autonomous Organization (DAO), which will allow the community to participate in governance decisions.
#### **3. Staking and Protocol Fees**
**SNS stakers** will have the opportunity to earn rewards from a portion of the protocol fees. By staking SNS tokens, users will receive a share of the fees generated within the SNS platform, providing an ongoing incentive for active participation.
#### **4. Burning Mechanism: De-Mint Function**
In addition to the burn-to-mint mechanism, SNS has a **de-mint function**. A portion of the protocol fees collected will be de-minted, permanently reducing the circulating supply of SNS tokens. This feature is designed to maintain a healthy token economy by keeping inflation in check and adding deflationary pressure to the token supply over time.
#### **5. Utility of the SNS Token**
The SNS token has several key utilities within the ecosystem, providing ongoing value for holders:
* **Staking**: SNS token holders can stake their tokens to earn rewards from protocol fees, offering a passive income opportunity for long-term holders.
* **Governance (DAO)**: SNS will introduce a decentralized governance model, allowing token holders to vote on important platform upgrades, policy changes, and community-driven initiatives, ensuring that the project remains decentralized and community-led.
* **Incentives for Developers and Ecosystem Growth**: A portion of SNS tokens will be allocated to incentivize developers who integrate the SNS protocol into their projects, as well as to foster ecosystem growth through partnerships and collaborations.
* **Protocol Fee Reductions**: Holders of SNS tokens may also benefit from discounts on platform-related fees, further encouraging token retention and usage within the ecosystem.
{% hint style="info" %}
**Note**: SNS tokens will not be used for **domain registration**. Domain registration on the Sonic Name Service will be paid with **S tokens**, the native token of the Sonic blockchain.
{% endhint %}
# Smart Contracts
SNS Token (Sonic)\
[0x7B0a41f0c17474e41a0c36c0Bf33b9AED06eE9f5](https://sonicscan.org/token/0x7b0a41f0c17474e41a0c36c0bf33b9aed06ee9f5)
SNS Token (Fantom) - Deprecated\
[0xD702993613686Ab0f706Ef07883870a97D36fdcf](https://explorer.fantom.network/address/0xd702993613686ab0f706ef07883870a97d36fdcf)
Burn-to-mint (Fantom)\
[0xB5F4fe02654Fbbffe857d335836a41917b53DB23](https://explorer.fantom.network/address/0xB5F4fe02654Fbbffe857d335836a41917b53DB23)
# Brand Assets
SNS Logo .SVG
SNS Logo .PNG - Light
SNS Logo .PNG - Dark
***
SNS Token .PNG - Light
SNS Token .PNG - Dark
***
SNS Icon .PNG
***
{% file src="/files/wDHX7qrjDl9z6dnxojDr" %}
SNS Font
{% endfile %}