Documentation

Introduction

This documentation covers everything you need to register and manage Web3 domains across multiple blockchains using the Freename platform.

Freename is an NFT domain name service. You register domain names on-chain as NFTs you fully own. Use them for websites, crypto wallets, decentralized apps, and more.

Quick Start Guide

Four steps from wallet to domain:

1. Connect your Web3 Wallet to the Freename platform.
2. Search for your desired domain name and complete the purchasing process.
3. Select the blockchain network you want to register on (Minting Process).
   Complete the registration (minting).
4. Manage your domain through the dashboard.

Web3 Domains

Web3 domains are blockchain-based names stored as NFTs, which means you own them outright, not a registrar. No renewal fees, no central authority, no risk of seizure.

Key Benefits

• Ownership: You truly own your Domain as an NFT in your Wallet
• Censorship Resistance: No central authority can take away your NFT
• Simplified Crypto Payments: Use your Web3 Domain instead of complex wallet addresses (eg: 0x582692B4f53947d550dcd2B89Dd2E769312386de)
• Website Hosting: Host decentralized websites with IPFS integration or traditional hosting providers

Supported TLDs

Freename supports various top-level domains (TLDs) across different blockchains:

Blockchain Integration

Freename deploys smart contracts across multiple chains. You pick the network that fits your needs in terms of fees, speed, and ecosystem.

Supported Networks

Supported networks:

• Base
• Solana
• Polygon
• Binance Smart Chain
• Etherlink
• Abstract
• Aurora
• Chiliz
• Sei

Wallet Connection

Connecting your wallet to the Freename platform lets you sign transactions and manage your domains on-chain.

Supported Wallets

• MetaMask
• Brave Wallet
• Coinbase Wallet
• Trust Wallet
• Phantom (for Solana)
• WalletConnect
• ...

To connect your wallet:

1. Click the "Connect Wallet" button in the top-right corner of the Freename platform
2. Select your preferred wallet from the list
3. Follow the prompts in your wallet to approve the connection
4. Once connected, you'll see your wallet address displayed in the header

Domain Registration

Here is how you register a Web3 domain on Freename:

Registration Steps

1. Search for your desired domain name
2. If available, select the domain and Complete the Purchasing Process
3. Select the blockchain network for Registration Process (Minting)
4. Confirm the transaction in your wallet
5. Wait for the transaction to be confirmed on the blockchain

Domain Management

Once your domain is minted, the Freename dashboard gives you full control over it:

Managing Records

You can set various records for your domain:

• Crypto Addresses: Link wallet addresses for different cryptocurrencies
• Text Records: Store arbitrary text information
• Content Records: Point to IPFS content for decentralized websites
• DNS Records: Configure traditional DNS records
• Avatar: Change the visual representation of your domain by uploading or linking a new NFT
...

Transferring Domains

As domains are NFTs, you can transfer them to other wallets:

1. Go to your domain dashboard
2. Select the domain you want to transfer
3. Click "Transfer"
4. Enter the recipient's wallet address
5. Confirm the transaction in your wallet

Troubleshooting

Common issues and their solutions:

Transaction Failed

If your domain registration transaction fails:

• Check that you have enough funds for both the domain fee and gas
• Ensure you're connected to the correct network
• Try increasing the gas limit or gas price
• Wait for network congestion to decrease

Domain Not Showing in Dashboard

If your registered domain isn't appearing:

• Verify the transaction was confirmed on the blockchain
• Ensure you're connected with the same wallet used for registration
• Try refreshing the page or clearing your browser cache
• Contact support if the issue persists

How the Resolver Works

The Freenamers Resolver queries multiple name services from your browser in a single search. No server, no intermediary. Two resolution modes:

Forward Resolution

Enter a domain name (e.g. alice.crypto, bob.eth) and the resolver retrieves the associated wallet address, profile picture, and all on-chain records (social links, wallets, website, etc.).

Reverse Resolution

Enter a wallet address (e.g. 0x582...86de) and the resolver finds the primary domain linked to that wallet, along with its profile picture and all associated records.

Supported Providers

The resolver queries multiple naming providers to give you the most complete results:

Resilience & Reliability

Blockchain RPC nodes enforce rate limits. Too many requests in a short window and they throttle you. Without proper handling, that means missing records or failed lookups on the first try.

The resolver handles this automatically. Here is what runs under the hood so you get complete results on the first search:

Smart Retry with Backoff

When fetching domain records from the blockchain, individual RPC calls may fail due to temporary rate limits. Instead of showing you incomplete data, the resolver automatically:

• Retries failed record requests up to 3 times
• Waits progressively longer between each attempt (exponential backoff), giving the RPC node time to recover
• Only returns results once a complete set of records has been fetched

Rate-Limit Cooldown (Reverse Resolution)

Reverse resolution is more demanding than forward resolution. Finding which domain belongs to a wallet requires significantly more blockchain queries. By the time the domain is identified, the RPC node may already be near its rate limit.

To prevent record fetching from failing immediately after a heavy reverse lookup, the resolver introduces a brief cooldown pause before requesting the domain's records. This gives the blockchain node enough time to accept new requests.

• Only applies to reverse lookups (wallet → domain). Forward lookups are unaffected
• Adds a small delay (~2 seconds) but ensures records are returned on the first search
• Works together with the retry mechanism as a second safety net

Batched RPC Calls (Solana)

For Solana domains, the resolver groups multiple record requests into a single batched call rather than sending them one at a time. This significantly reduces the number of network round-trips and speeds up resolution.

Summary

Progress Pipeline

Domain resolution can take anywhere from 3 to 10 seconds depending on the provider and network conditions. Instead of showing a generic spinner, the resolver displays a vertical progress pipeline that tracks each step in real time, giving the user a clear visual understanding of what is happening behind the scenes.

How It Looks

The pipeline is a vertical track with stations connected by a gradient fill bar (purple → cyan) that descends as the resolution progresses:

• Pending stations: greyed out dot and label, waiting to be reached
• Active station: cyan-bordered dot with a radar ping animation and mini-spinner, floating blockchain icon, white bold label
• Completed stations: purple dot with an animated checkmark (stroke draw), green label

Each station displays a blockchain logo (Polygon, Ethereum, or Solana) on the left and a descriptive label on the right. A green flash animation plays when the final "Complete" station is reached.

Resolution Paths & Steps

The number of steps and labels adapt to the resolution type:

Portfolio Loading (Solana Reverse)

When resolving a Solana wallet address, the primary domain and its records are displayed immediately. The resolver then loads all other .sol domains owned by the wallet in the background.

During this phase, a portfolio loading animation is shown instead of a simple spinner:

• A pulsating Solana logo with the label "Scanning wallet portfolio..."
• Skeleton placeholder rows with shimmer animation, simulating domain entries being loaded
• A subtle hint: "Bigger collections take a bit longer"

Once loaded, the skeletons are replaced with the actual list of .sol domains, with the primary domain highlighted with a star.

Technical: onProgress Callback

The pipeline is powered by an onProgress callback passed through the resolution chain. Each resolver method (resolveDomain, reverseResolve, resolveFromTokenId) accepts an optional callback that receives progress events:

resolver.resolveDomain("sandy.crypto", (progress) => {
    // progress = {
    //   stage: 'resolving',
    //   label: 'Resolving on Polygon...',
    //   chainHint: 'polygon',
    //   index: 1,
    //   total: 4,
    //   done: false
    // }
});

The callback is invoked using optional chaining (onProgress?.()), so it is fully backward-compatible. If no callback is provided, the resolver behaves exactly as before with zero overhead.

API Overview

The Freename API will allow developers to integrate domain management features into their applications.

Authentication

Endpoints

Press Kit

The Freenamers Press Kit provides all official graphic assets to represent the brand. Use these resources for your projects, articles, or integrations.

Available Assets

How to Use

Each Press Kit asset offers several methods to retrieve files:

1. Direct Download

Click the PNG or SVG buttons to download the file directly to your device.

2. Copy URL

Click the URL button to copy the direct CDN link to the asset. Useful for integrating into your code:

<img src="https://freenamers.com/assets/logo_original.svg" alt="Freenamers Logo">

3. HTML Code for Favicons

Favicons include an HTML button that copies ready-to-paste code for your <head>:

<!-- Favicon for dark mode -->
<link rel="shortcut icon" type="image/x-icon"
      href="https://freenamers.com/assets/favicon/white.svg"
      media="(prefers-color-scheme: dark)">

<!-- Favicon for light mode -->
<link rel="shortcut icon" type="image/x-icon"
      href="https://freenamers.com/assets/favicon/black.svg"
      media="(prefers-color-scheme: light)">