# What is NNS
[Nouns Name Service](https://nns.xyz) is a new concept of open Naming System funded by [Nouns](https://nouns.wtf).
Launched on Ethereum Mainnet, it has now been migrated to Base.
### The Problem
NNS was born to solve a simple but massive problem for projects and communities:
**It's incredibly hard for a new project to build a Naming System from zero.**
The biggest challenge is not the creation of the Top Level Domain itself. That's the easiest part.
Everyone can create a TLD with a few clicks and everyone can start selling names.
The real challenge is making sure that the TLD is resolved everywhere. If the TLD is not resolved by websites, apps, wallets and platforms...then it's basically useless.
Which is exactly why the market is currently controlled by a limited number of players who in the last years have been able to build a great network of resolvers.
{% hint style="info" %}
**Example**
What makes a .eth incredibly valuable is not the TLD itself, but the network of resolvers that makes it resolved everywhere.
{% endhint %}
### **The Solution**
NNS takes a completely different approach compared to the other Naming Systems.
Instead of creating a closed network of resolvers to bring value to a proprietary TLD, **NNS mission is to create a network of resolvers that is fully open and accessible to any project that wants to build their own TLD on the protocol.**
Projects and communities will be able to launch their naming system - fully resolved everywhere from the start - in a matter of minutes.
**On NNS, everything is shared with the participants who contribute to make the protocol bigger and stronger.**
The protocol began this experiment with the [.⌐◨-◨](/names/.-names) and [.nouns](/names/.nouns-names) names and it will soon be open to more and more projects and communities in the Nouns ecosystem and beyond.
# How do you earn Rewards
NNS is designed to be the first identity protocol that shares its revenue with its participants.
Participants can earn rewards in 2 ways:
* NNS Resolvers
* Referrals
# NNS Resolvers
A resolver is any website, platform, or app that natively resolves NNS names.
Resolvers are the backbone of NNS, contributing to the protocol’s vision of enabling every TLD under NNS to be resolved universally across the web.
For example, [nouns.wtf](https://nouns.wtf) qualifies as a resolver because it natively resolves NNS names throughout the entire site, from auction bids to the wallet section at the top of the page.
# How to become a Resolver
To be approved as a Resolver, follow the steps [here](/for-devs/resolving-nns-names).
Once our verification is completed, your platform will be featured on the [NNS website](https://nns.xyz), and you will begin receiving rewards on a weekly basis.
# Referrals
While [Resolvers](/rewards/nns-resolvers) allow NNS names to be visible on platforms and apps, Referrals play a key role in expanding the protocol's reach by introducing new users.
By sharing their referral link, users earn rewards for every NNS name they help mint.
Currently, Referrals are reserved for those who own at least one .⌐◨-◨ name.
Holders of a .⌐◨-◨ name can easily copy their Referral URL directly from their dashboard.
Once you have your Referral link, you can use it anywhere, including integrating it into your project to create an additional income stream. Every time someone mints a name after clicking your link, you will receive a reward.
The amount of the reward earned by a user will depend on the TLD of the name minted. Some TLDs may offer higher referral rewards, while others might choose to set lower or even zero rewards.
To know the exact amount of Referrals for each community, always make sure to check the field "Referrals" in the Revenue Distribution box of the community page.
For example, the Referrals reward for .⌐◨-◨ names is 20%. This means that each time a user mints a .⌐◨-◨ name through your link, you will automatically earn between $20 and $2000, depending on the length of the name minted.
# Price Structure
The price of every name built on the NNS protocol consists of the following components:
* Rewards to [NNS Resolvers](/rewards/nns-resolvers)
* Rewards to users who promote the TLD through [Referrals](/rewards/referrals)
* Protocol Fee
* Revenue for the owner of the TLD
Each TLD may differ in the exact percentage assigned to these elements. Specifically:
* **NNS Resolvers:** Typically ranges from 5-10%, but can go up to 75% for special TLDs (e.g., .⌐◨-◨)
* **Referrals:** Set at the discretion of the TLD owner
* **Protocol Fee:** Fixed at 5% for every TLD
* **TLD Owner:** Receives the remaining amount after subtracting the Protocol Fee, NNS Resolvers rewards, and Referrals rewards from the minting price.
{% hint style="info" %}
#### A note regarding the Protocol Fee
NNS retains 5% of the minting price of every name as a protocol fee.
This fee goes directly to NNS Labs and is used to support the ongoing development and expansion of the protocol.
{% endhint %}
# How to Use Your Names
NNS names are designed to give users complete flexibility in choosing the identity they want to use within their favorite communities.
Unlike other naming systems, where your name is the default identity everywhere, NNS allows you to set a specific Primary Name for each community you're a part of.
For example, if you own both a .⌐◨-◨ and a .nouns name, you can choose to set the .⌐◨-◨ as your default identity and the .nouns as your identity within the Nouns ecosystem.
In this case, any NNS resolver that prioritizes .nouns will display your .nouns identity instead of your default name.
# .nouns Names
.nouns are special domains that can only be claimed by holders of a [Noun NFT](https://nouns.wtf) or [$NOUNS](https://dexscreener.com/base/0x338f3e577312f90a74754dddd0d7568c2c3dc211) token.
### Prices
Names are paid in ETH and are subject to yearly renewal. Lower digits have higher prices due to scarcity.
Every name directly funds the DAO and the nounish network of NNS resolvers across the world.
| Digits | Price |
| ------ | ---------- |
| 4+ | $50/year |
| 3 | $125/year |
| 2 | $500/year |
| 1 | $2500/year |
### Revenue Distribution
Revenue generated from the minting of .nouns names will follow the distribution below.
| Receiver | Reward Distribution |
| ----------------------------------- | ------------------- |
| Nouns DAO | 70% |
| [Referrals](/rewards/referrals) | 15% |
| [Ecosystem](/rewards/nns-resolvers) | 10% |
| NNS protocol | 5% |
You can find more info on the categories of the Receivers [here](/names/price-structure).
{% hint style="success" %}
**Special reservation for .⌐◨-◨ holders**
Every holder of a .⌐◨-◨ name (who is also an holder of a Noun NFT or $NOUNS token) will have the correspondent .nouns name reserved for 30 days after launch.
This will prevent names squatting and will give everyone in the ecosystem the possibility to secure their .nouns identity.
{% endhint %}
{% hint style="success" %}
**Special reservation for Noun holders**
Numbers from 0 to 9999 will be reserved to holders of the correspondent Noun NFT.
For example, if you own Noun #69 and Noun #420, you will be able to claim 69.nouns and 420.nouns.
This reservation doesn’t have an expiration time and these names can be claimed at any time.
{% endhint %}
# .⌐◨-◨ Names
.⌐◨-◨ is the core of NNS. It's a one time fee domain that allow you to proliferate the ⌐◨-◨ meme with every onchain transaction.
These unique and super nounish names also give you access to a growing set of benefits, from $NOGS allocations to Referral Rewards and much more!
### Prices
Names are paid in ETH and are only subject to a one time fee. Lower digits have higher prices due to scarcity.
| Digits | Price |
| ------ | ------ |
| 4+ | $100 |
| 3 | $250 |
| 2 | $1000 |
| 1 | $10000 |
### Revenue Distribution
Revenue generated from the minting of ⌐◨-◨ names will follow the distribution below:
| Receiver | Reward Distribution |
| ----------------------------------- | ------------------- |
| [Ecosystem](/rewards/nns-resolvers) | 75% |
| [Referrals](/rewards/referrals) | 20% |
| NNS protocol | 5% |
You can find more info on every category of Receivers [here](/names/price-structure).
# NNS Protocol
The protocol is a suite of smart contracts that issues names for different communities. It rewards communities, referrals, everyone in the ecosystem that resolves names directly on their product and holders of `.⌐◨-◨` names. All rewards are issued in $NOGS.
## Terminology
* Each community has its own top-level domain called `community level domain` or `CLD` for short
* 3rd parties natively resolving NNS names are referred to as the `ecosystem`
## Smart contract architecture
The protocol is implemented with 5 key smart contracts:
* `CldRegistry`: a registry of names (ERC721 tokens) for each community
* `NNSController`: manages creation of CLDs, registration of new names and renewal of existing expiring names
* `NNSResolver`: resolves account addresses to an NNS name
* `NNSRewarder`: collects all revenues and splits them to different groups
* `NNSResolverToken`: ERC721 tokens issued to the ecosystem
There are also `CldFactory`, `AccountRewarder` and `ERC721BasedRewarder` which are additional contracts and their use will be explained below.
### CldRegistry
A `CldRegistry` is an ERC721 contract with a fixed CLD, eg `.⌐◨-◨` or `.nouns`. The identifier of the CLD is its `namehash`. For instance, the cldId of the `.⌐◨-◨` CLD is `0x739305fdceb24221237c3dea9f36a6fcc8dc81b45730358192886e1510532739`.
Names are ERC721 tokens whose id is the `namehash` of `name.extension`, e.g. the token id of `hello` in the `.⌐◨-◨` CLD is `namehash("hello.⌐◨-◨")` and the contract has many functionalities associated to each name:
* `nameOf` returns the full name of the of the token, e.g. `hello.⌐◨-◨`
* create, delete and query subdomains such as `sub.hello.⌐◨-◨`. Note that subdomains are not separate tokens but rather properties of each name.
* set/delete text records
* manage reverse name, i.e. an address -> name lookup
Moreover:
* each registry has a community manager which has special permissions in the protocol, discussed later
* registration and renewal of names is done via the `NNSController`, discussed below.
### NNSController
The NNSController is the main entry point to create registries (`CldRegistry`), manage prices, register and renew names.
#### Creation of new CLDs
Creation of new CLDs is only possible via `NNSController.registerCld` which can be only called by a multi-sign wallet owned by the NNS team. This operation:
* deploys a new instance of `CldRegistry`
* sets up the rewarder to distribute rewards according to the given splits
* sets up the resolver to work with the new registry
#### Registration of new names
Registration of new names is only possible via `NNSController.register` and `NNSController.registerWithSignature` which can be called by anyone. Only one of these method will work for each CLD, depending on what `NNSController.isSignatureRequired` returns.
We have implemented a signature-based registration process to give communities extreme flexibility in determining when someone can register a name. For instance:
* `.⌐◨-◨` names that were registered in the original version of NNS on ETH Mainnet can only be registered by the original owner
* `.nouns` names can only be registered by owners of a Noun or a $NOUN token and numbered names such as `1.nouns` or `123.nouns` can only be registered by the owner of the associated Noun.
Signatures are issued by our api at `https://api.nns.xyz/register`.
Names of CLDs without special rules can be registed directly with `NNSController.register`.
Pricing of names is determined for each CLD by its pricing oracle (`IPricingOracle`) which can be found by calling `NNSController.pricingOracleOf`. Only the community manager can change the pricing oracle of their CLD.
### NNSResolver
The NNSResolver is responsible for resolving addresses to names, i.e. to return a name from an address. This is generally called the *primary name*. The basic functionality is just to proxy the call to the underlying registry to fetch the associated lookup but it can also help people aggregate their names across the NNS registries.
In fact, one functionality the NNS protocol provides is allowing people to set one reverse per registry which means that you can have `0x123...abc` being resolved to `A.⌐◨-◨` in the `.⌐◨-◨` registry and to `B.nouns` in the `.nouns` registry. The `NNSResolver` makes cross-registry resolutions really easy thanks to
```solidity
function reverseNameOf(
address addr,
uint256[] calldata cldIds,
bool fallbackToDefault
) external view returns (string memory);
```
which resolves a given address in a certain list of CLDs, falling back to a set default in case none of the given clds has a lookup set.
The default CLD can be customised for each account via `NNSResolver.setDefaultCld` and fallback to `NNSResolver.fallbackCld()` which is set by the NNS team (to `.⌐◨-◨`).
You can find the default CLD being referred to as the *Primary Collection* following the same naming used for names.
### NNSRewarder
The `NNSRewarder` is responsible for collecting revenues from registrations and renewal and distribute them to the different groups.
#### Distribuition of revenues
Each community (via the community manager) can define and change how revenues are split and specifically set the following values:
* referral share: percentage given to the referrer which must own at least one `.⌐◨-◨`. In case the refer is not set of doesn't own `.⌐◨-◨` names, this shares goes to the community.
* community share: percentage given to the community owning the CLD
* ecosystem share: percentage given to the ecosystem of resolvers
There are also two additional splits:
* protocol share: percentage given to the protocol and is fixed to 5%
* holder share: percentage given to holders of `.⌐◨-◨` names. This automatically set to what is left, i.e. `100 - referral - community - ecosystem - protocol`.
Revenues come from the `NNSController` and are transferred to the `NNSRewarder` via the `collect` method which exchanges ETH to $NOGS via Uniswap and then splits the $NOGS to each group according to the splits for the community.
There are two ways of distributing rewards:
* to a specific account: used for referrals, communities and the protocol which is implemented via the `AccountRewarder` contract which simply keeps a balance for each address.
* to holders of an ERC71: used for the ecosystem and holders of `.⌐◨-◨` which is implemented via the `ERC721BasedRewarder` contract.
**ERC721BasedRewarder**
This contract is responsible for accumulating and distributing revenues to a group on ERC721 holders. Since the number of holders can change at any time, this process is implemented via snapshotting and has different phases.
1. Revenues are simply accumulated in a simple counter without actually distributing them.
2. At regular intervals (30 days), anyone can take a snapshot which:
* Equally distributes the accumulated balance to all existing ERC721 tokens for a given collection at the time of snapshot
* Tracks the block in which the snapshot was taken
* Keeps track of how much revenues have been withdrawn
3. One a snapshot exists, holders can withdraw their share long as their ERC721 was minted before the snapshot was taken. This is achieved by keeping the minting block when tokens are minted. Note that while a snapshot exists revenues are still accumulated, but won't be added to it.
When a new snapshot is taken, the unclaimed balance is redistributed to ensure nothing is ever lost.
The protocol has 2 instances of this contract:
* the first distributes rewards to holders of `.⌐◨-◨` and it's simply setup with the `.⌐◨-◨` registry
* the second distributes rewards the ecosystem and to track who is part of this group we issue a special ERC721 called `NNS Resolver (NNSR)` (contract `NNSResolverToken`). The process of verifying whether projects integrate with NNS is off-chain and therefore, the NNS Team is responsible for minting and burning these tokens as new community add or remove integrations.
# Resolving NNS Names
There are 2 ways to resolve addresses to NNS Names: calling the `NNSResolver` or our API.
{% hint style="info" %}
Make sure you understand how the `NNSResolver` works [here](/for-devs/nns-protocol#nnsresolver).
{% endhint %}
### Resolving via the API
You just need to make a `POST` request to `https://api.nns.nyz/resolve` with
```json5
{
"address": "0x123...456",
// clds is optional and defaults to []
"clds": [
"0x1",
"0x2",
],
// fallback is optional and defaults to true
"fallback": true,
// disable_v1 is optional and when true disables the resolution of v1 names
"disable_v1": false
}
```
which will return
```json5
{
"name": "hello.⌐◨-◨" // or null
}
```
### Resolving by calling the contract
You just need to call
```solidity
function reverseNameOf(
address addr,
uint256[] calldata cldIds,
bool fallbackToDefault
) external view returns (string memory);
```
on the resolver. The inputs are the same as the API call.
### Inputs
* `address` is the address that will be resolved
* `clds` is an array of cld ids to perform a lookup on
* `fallback` whether you want to fallback to the default cld in case no lookup is found in the given list
### Common Scenario
The most common scenario is to let the owner choose where they want to be resolved and this can be done by simply omitting the clds and setting the fallback to true.
{% hint style="success" %}
As people migrate their old NNS name to the new contracts, we recommend to also integrate with the [old NNS resolver](https://etherscan.io/address/0x849F92178950f6254db5D16D1ba265E70521aC1B) as shown here. This is give one, with one simple integration:
* Resolution of NNS v2 names
* Resolution of NNS v1 names
* Fallback to .eth names
in this order of priority.
{% endhint %}
### Code Samples
The code below assumes you are using `wagmi` and `@tanstack/react-query`.
#### API call
```ts
async function fetchNNSName(address: Address) {
const res = await fetch(`https://api.nns.xyz/resolve`, {
method: "POST",
body: JSON.stringify({ address }),
});
if (!res.ok) {
throw new Error("invalid response");
}
const body = await res.json();
return body.name as string | null;
}
function useNNSName(address?: Address) {
return useQuery({
queryKey: [address, "nns-name"],
queryFn: () => fetchNNSName(address || zeroAddress),
enabled: Boolean(address),
});
}
```
As an example, if you only want to resolve `.nouns` names you can pass:
```typescript
async function fetchNNSName(address: Address) {
const res = await fetch(`https://api.nns.xyz/resolve`, {
method: "POST",
body: JSON.stringify({
address,
// only resolve in .nouns
clds: [
// namehash("nouns")
"0x84917c06116ee3d3a59b0b08f1c872deae04baecba033ea58cc455c7ca79c62c"
],
// don't fallback to the default cld
// we recommend setting this to true, see comment below.
fallback: false,
}),
});
if (!res.ok) {
throw new Error("invalid response");
}
const body = await res.json();
return body.name as string | null;
}
```
Note however that this is going to return `null` if the account has no `.nouns`. We recommend to set `fallback: true` to ensure you get one resolution back.
#### Contract call
```ts
const nnsV2ResolverABI = [
{
inputs: [
{ internalType: "address", name: "addr", type: "address" },
{ internalType: "uint256[]", name: "cldIds", type: "uint256[]" },
{ internalType: "bool", name: "fallbackToDefault", type: "bool" },
],
name: "reverseNameOf",
outputs: [{ internalType: "string", name: "", type: "string" }],
stateMutability: "view",
type: "function",
},
] as const;
export const nnsV1ResolverABI = [
{
stateMutability: "view",
type: "function",
inputs: [{ name: "addr", internalType: "address", type: "address" }],
name: "resolve",
outputs: [{ name: "", internalType: "string", type: "string" }],
},
] as const;
function useNNSName(address: Address) {
const v2Name = useReadContract({
abi: nnsV2ResolverABI,
functionName: "reverseNameOf",
args: [address, [], true],
address: NNS_RESOLVER_ADDRESS,
chainId: base.id,
});
const v1Name = useReadContract({
abi: nnsV1ResolverABI,
address: "0x849F92178950f6254db5D16D1ba265E70521aC1B",
functionName: "resolve",
args: [address],
chainId: mainnet.id,
query: {
enabled: v2Name.isSuccess && !v2Name.data,
},
});
return useMemo(() => {
if (v2Name.isSuccess && !v2Name.data) {
return v1Name;
}
return v2Name;
}, [v1Name, v2Name]);
}
```
In this example, you can simply return `v2Name` if you don't want to use the old resolver.
# Contract Addresses
