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

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.

Previous.⌐◨-◨ NamesNextResolving NNS Names

Last updated