Table of contents
Freename is a Web3 domain service that allows users to mint, buy, own, and utilize Web3 top-level domains as well as earn royalties from them.
Freename’s Web3 domains are represented as NFTs compliant with the ERC-721 standard and can thus seamlessly integrate with existing apps and marketplaces and can be relied upon as a building block to build on top of.
This documentation provides a reference for the set of contracts that together make up the Freename Service (FNS).
🔗 Supported Blockchains
Freename currently supports the following blockchains:
🟣 Polygon
🔸 Binance Smart Chain
❇️ Aurora
⬛️ Cronos
All contracts that will be described in the following section have been deployed on each of the blockchains.
📜 Freename Smart Contracts
The Freename Service (FNS) currently consists of 3 different smart contracts:
- The FNS Registry contract, which is the heart of the Freename domain management and is the main constituent of the Freename Service (FNS)
- The ProxyAdmin contract, which gives necessary admin rights to the Freename team to allow for upgradeability
- The MintingManager contract, which enables the Freename team to mint Top Level and Second Level Domains
The following section will give an overview of the functionality of each contract. Also, the addresses of each contract on each chain can be found here.
📝 FNSRegistry Contract
The FNSRegistry contract acts as the registry that maintains records of all Freename domains. It is the most essential smart contract of FNS.
Interaction with these contracts allows users to manage their domains and perform actions like setting records, delegating management and more. It implements the OpenZeppelin ERC-721 Enumerable Metadata token standard and thus stores a list of all domains as NFTs. The Metadata extension allows linking to associated metadata that is individual for each domain, like crypto addresses, IPFS hashes, avatars and more (see section records management for further information).
ℹ️ Information stored in the Registry
In total, following information is stored in the FNSRegistry contract:
- The registered domains (stored as namehashes)
- The owner addresses of domains
- The approved address of domains
- The operator/manager addresses of domains
- The records stored in key-value format that are associated with an address.
- The whitelisted minters
The storing of the registered domain names in the registry is done via a process called Namehashing
More about Namehashing
The usage of the ERC-721 Enumerable standard allows for simple indexing and querying of the stored domains and thus enables developers to easily build on top of the Freename system.
🔎 Permissions & Rights
The FNSRegistry contract has no administrators and is fully governed by its code. This means that no interference in the domain ownership and management for any owned domain by any third party is possible in the FNS system.
The Freename team operates addresses that are specified as “whitelisted minters”. This grants the Freename team the right to mint top level domains (i.e .2themoon) and second level domains (i.e my.2themoon).
Ownership of a name grants an address the right to
- Transfer ownership
- Set domain records
- Set an approved address as well as manager/operator addresses (see section domain management for further information)
Contract addresses
The FNSRegistry contact has the following addresses on the blockchain supported by FNS:
Network | Contract address | Forwarder |
Aurora Mainnet | ||
BSC Mainnet | ||
Cronos Mainnet | ||
Polygon Mainnet |
ProxyAdmin Contract
The ProxyAdmin contract gives the Freename team the option to upgrade the FNSRegistry contract. For more information, please consult the OpenZeppelin documentation.
Contract addresses
The ProxyAdmin contact has the following addresses on the blockchain supported by FNS:
Network | Contract address | Forwarder |
Aurora Mainnet | — | |
BSC Mainnet | — | |
Cronos Mainnet | — | |
Polygon Mainnet | — |
Minting Manager Contract
The Freename team is supposed to have the right to mint Top Level Domains and Second Level Domains. At the same time, it should be avoided that any party has total admin rights over the registry.
To achieve this, MintingManager is used as a controller contract that gives the Freename team superuser powers within a limited scope. MintingManager therefore provides an interface that allows the Freename team to mint TLDs and SLDs and forwards all calls to the FNSRegistry contract.
Contract addresses
The MintingManager contact has the following addresses on the blockchain supported by FNS
Network | Contract address | Forwarder |
Aurora Mainnet | ||
BSC Mainnet | ||
Cronos Mainnet | ||
Polygon Mainnet |
Domain Ownership and Management
⚠️ Domain Ownership
Like most other ERC-721-compliant NFTs, a Freename top or second level domain can be owned by both external end user addresses (EOAs) as well as internal addresses (smart contracts. The domain management via smart contract opens up many interesting new ways to structure ownership. A simple example includes domains that are governed by a multi-signaturemulti-sigature wallet, but also many more complex setups are within the realm of possibilities.
Domain Management
Freename allows members to delegate transaction execution to accounts that aren't domain owners. This is implemented via supporting for EIP-2771 - Secure Protocol for Native Meta Transactions in the FNSRegistry contract.
One prominent use-case of meta transactions is that they allow delegation of (gas-using) blockchain calls to other accounts. Like this, domain owners can manage their domains from other accounts they own or even have some third party pay for the transaction fees associated with domain management.
🙌 Delegation to Freename
The delegation feature of FNS Domains is used by the Freename team to operate our managed domain platform. An internal transaction processor queues transactions and then submits them to the blockchain on behalf of our users. This way, domain owners can mint and manage their domains on Freename.io without having to worry about blockchain fees.
In the case of mintings of domains no signature from the domain owner is required, since the Freename team is a whitelisted minter in the FNSRegistry and therefore allowed to mint TLDs and second level domains.
Freename uses this delegation feature to operate an internal transaction processor. Our transaction processor makes it possible for members to mint and manage their domains without having to worry about their wallet's balance. Under the hood, the transaction processor is a queue-based job processor that sends transactions from Freename-owned accounts.
Managing domains, in contrast, can only be performed with a domain owner's permission, since the FNS system is fully trustless. Therefore each “management act”, like e.g. setting a domain record, requires a signature from the owner’s wallet in order to be performed. (Please note: This feature is part of the roadmap, but not yet live on freename.io.)
⏺️ Records management
Similar to the internet’s traditional DNS system Freename NFT domains also enable users to set records. Records allow owners of NFT domains to link arbitrary information to their domain via a key-value format.
This means that each key corresponds to a certain value (examples include crypto addresses, websites, social media accounts and many others) that can be looked up when being given the key as an input.
By this, users can customize their resolving preferences and provide different resolutions for different use-cases and services.
Users can set their own records using the Freename Platform in the domain management. It provides a set of possible records that users can set. Developers can configure their own records or resolve specific records using the SDK or directly interacting with the Smart Contract.
While Freename offers developers the liberty to set records in the way they wish and that’s useful to their application, some specific standards to follow on how to set the proper record key name are being provided. This helps keeping a clean set of records and brings order to the keyspace of every NFT domain.
🔑 Key & value structure
In the FNS domain records key-value store, each key follows the following structure:
javascript<TYPE>.<NAME>.<INDEX/SUB-LEVEL>
- Example A record key: record.A.0
- Example BTC address key (index 0): token.BTC.0
- Example BTC address key (index 1): token.BTC.1
The format of values depends on the type of record being set and therefore could follow various standards (e.g. crypto addresses, URIs, etc.).
Standard key record structure
The list below shows all standard keys that FNS supports, including desired value formats:
TYPE | NAME | INDEX/SUB-LEVEL | VALUE description | |
DNS A Record | record | A | 0 | Record A resolution
Value: 12.34.56.123 |
DNS CNAME Record | record | CNAME | 0 | Record CNAME resolution
Value: freename.io |
DNS TXT Record | record | TXT | 0 | Record TXT resolution
Value: domain verification=123 |
Token BTC | token | BTC | 0 | BTC wallet address for payments
Value: bc123 |
Token MATIC | token | MATIC | 0 | MATIC wallet address for payments
Value: 0x123 |
Token TOKEN_NAME | token | TOKEN_NAME | 0 | TOKEN_NAME wallet address for payments
Value: 0x123 |
Website redirect | redirect | WEBSITE | 0 | Website address for the redirect www.freename.io |
Avatar profile URL | profile | AVATAR | url | URL of the avatar image |
Avatar profile Base64 | profile | AVATAR | base64 | Base64 Encoded avatar |
Avatar profile NFT | profile | AVATAR | network | The avatar profile network to check: e.g. mainnet, bsc, |
Avatar profile NFT contract | profile | AVATAR | contract | The avatar profile NFT contract address |
Avatar profile NFT token id | profile | AVATAR | tokenId | The avatar NFT profile token Id |
Profile Linkedin URL | profile | LINK | linkedin | Linkedin URL |
Profile Mirror.xyz | profile | LINK | mirror | Mirror.xyz URL |
Profile <platform> | profile | LINK | <platform> | <platform> URL |
Profile name | profile | OWNER | fullname | Contains the name of the owner (E.g.: John Doe) |
🗝️ Custom key record structure
FNS allows setting of non-standard custom keys with arbitrary value formats. This allows developers to build on top of FNS and safe arbitrary data that can be used for their custom dApp integration. The table below lists some examples: