ENS Logo

Primary Names

We can all agree 42-character long machine-optimized addresses (eg. 0x225...c3b5) are not aesthetically pleasing. Fortunately, it is super easy to retrieve a user's preferred name, and this page will show you how.

0x225...c3B5to
luc.eth

In order to convert them to human-readable names, we use the reverse registrar. The reverse registrar is a smart contract that allows users to register their preferred name, referred to as their "primary name" for simplicity purposes.

Getting a Primary Name

To get a users preferred primary name is very simple. In most libraries you will find a function to do a lookup by address as shown below. This allows us to turn any address into a human-readable name.

Reverse Lookup
import { useEnsName } from 'wagmi';
import { mainnet } from 'wagmi/chains';

export const Name = () => {
    const { data: name } = useEnsName({
        address: '0x225f137127d9067788314bc7fcc1f36746a3c3B5',
        chainId: mainnet.id, // resolution always starts from L1
    });

    return <div>Name: {name}</div>;
};
// 0x225f137127d9067788314bc7fcc1f36746a3c3B5 -> luc.eth
const name = await provider.lookupAddress(
    '0x225f137127d9067788314bc7fcc1f36746a3c3B5'
);
// 0x225f137127d9067788314bc7fcc1f36746a3c3B5 -> luc.eth
import { publicClient } from './client';

const ensName = await publicClient.getEnsName({
    address: '0x225f137127d9067788314bc7fcc1f36746a3c3B5',
});
from ens.auto import ns

# 0x225f137127d9067788314bc7fcc1f36746a3c3B5 -> luc.eth
name = ns.name('0x225f137127d9067788314bc7fcc1f36746a3c3B5')
package main

import (
	"fmt"

	"github.com/ethereum/go-ethereum/common"
	"github.com/ethereum/go-ethereum/ethclient"
	ens "github.com/wealdtech/go-ens/v3"
)

func main() {
	client, _ := ethclient.Dial("https://rpc.ankr.com/eth")

	name, _ := ens.ReverseResolve(client, common.HexToAddress("0x225f137127d9067788314bc7fcc1f36746a3c3B5"))
	fmt.Println("Name:", name)
	// Name: luc.eth
}

🎉 And that's it! Now you can turn all your pages from this, to this:

0x225...c3B5
sent 0.1 ETH to
0x123...4567
turns into
luc.eth
sent 0.1 ETH to
domico.eth

Setting Primary Names

In some cases you might want to encourage users to set their primary name. This might be in the event you are issuing names, or want people to be part of a community.

Currently, primary names are only support on L1 mainnet. Soon, primary names are also coming to L2s and are already available on testnets. The examples below use the testnet deployments, for which the latest code can be found here.

Deployments for the latest L2 reverse registrars, the contracts that power L2 primary names,

L2 Testnet ChainAddress
Base Sepolia0xa12159e5131b1eEf6B4857EEE3e1954744b5033A
OP Sepolia0x74E20Bd2A1fE0cdbe45b9A1d89cb7e0a45b36376
Arbitrum Sepolia0x74E20Bd2A1fE0cdbe45b9A1d89cb7e0a45b36376
Scroll Sepolia0xc0497E381f536Be9ce14B0dD3817cBcAe57d2F62
Linea Sepolia0x74E20Bd2A1fE0cdbe45b9A1d89cb7e0a45b36376

On these chains, you can set a primary name for the sender via setName() most simply, or via signature.

setNameForAddrWithSignature() can be used for EOAs or smart contracts with an ERC-1271 signature, while setNameForAddrWithSignatureAndOwnable() can be used when a smart contract has an explicit owner().

Do's and Dont's

It must be noted that under no situation is it recommended to force a user to change their primary name, nor doing so without clearly notifying the user of what the transaction they are about to execute could modify. Doing so could be seen as hostile or undesired behaviour by end users and might degrade their experience with your app.

Contributors
Last Modified
14 days ago