Skip to content

Naming Contracts

Learn how to name your smart contracts with ENS

While it's commonly known that regular user accounts can have primary names, it's less known that smart contracts can also have names.

In order for you to manage the primary name of your smart contract, you need to own the reverse node for the contract address. There are several ways of doing this, depending on if you are actively developing your contract or if it is already deployed.

Skip to Naming Tools for a frontend solution to naming your smart contracts.

New Contracts

Depending on your use case, there are a few ways to set a smart contract's primary name.

If you want to be able to change the name later, you have two options:

  • (Recommended) Make the contract Ownable and set yourself as the owner.
  • Take ownership of the reverse node ({address}.addr.reverse) for the contract. This only works for contracts on Ethereum Mainnet.

The Ownable method is preferred since it doesn't require any additional code in many cases, and has the best Etherscan support.

For immutable smart contracts (without an owner), you can set the reverse record directly in the constructor at the time of deployment.

Let's look at a few examples.

Ownable (recommended)

If you want to be able to change the name in the future, you can make your smart contract Ownable.

import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 
contract MyContract is Ownable {
    constructor(address initialOwner) Ownable(initialOwner) {}
}

Reverse Registrars on all supported chains understand the Ownable interface and will let the owner() of a contract set its reverse record without having to add any ENS-specific code.

Once this contract is deployed, call setNameForAddr() on a Reverse Registrar from your authorized owner account on the relevant chain. Note that the arguments are slightly different on L1 and L2s.

  • The first address argument should be the address of your contract (both L1 and L2s)
  • The second address argument should be the owner of your smart contract (only L1)
  • The third address argument should be the defaultResolver() from the Reverse Registrar (only L1)
  • The last argument is the ENS name to set it to (both L1 and L2s)

Set a name in the constructor

If you don't want to be able to change the name in the future, you can call setName() on a Reverse Registrar directly from your contract's constructor. Your contract would look something like this:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.21;
 
interface IReverseRegistrar {
    function setName(string memory name) external returns (bytes32);
}
 
contract MyContract {
    /// @param reverseRegistrar The address of the Reverse Registrar contract on the relevant chain to use.
    /// @param name The reverse name to set for this contract's address.
    constructor(address reverseRegistrar, string memory name) {
        IReverseRegistrar(reverseRegistrar).setName(name);
    }
}

You can find the Reverse Registrar addresses here.

ReverseClaimer.sol (L1 only)

This is a simple drop-in module that transfers ownership of the reverse node to an address of your choice, which can then update the reverse name at any time.

import "@ensdomains/ens-contracts/contracts/registry/ENS.sol";
import "@ensdomains/ens-contracts/contracts/reverseRegistrar/ReverseClaimer.sol";
 
contract MyContract is ReverseClaimer {
    constructor (
        ENS ens
    ) ReverseClaimer(ens, msg.sender) {}
}

When you deploy your contract, the deployer account (msg.sender) will be given ownership of the reverse node for that contract address. This gives you authorization to call setName(node, newName) on the latest public resolver (resolver.ens.eth), where node is the reverse node for the contract address and newName is the name you want to set it to.

To find the reverse node for your contract address, you can use the following viem script:

import { namehash } from 'viem/ens'
 
const myContractAddress = '0x...' // replace with your contract address
 
const node = namehash(
  `${myContractAddress.slice(2).toLowerCase()}.addr.reverse`
)
 
console.log(node)

Existing Contracts

If your contract is already deployed you might still be able to set a name for it. If your contract supports the Ownable interface from OpenZeppelin, read the section above.

Safe, Multisig & DAO

If your contract is a Safe, Multisig, DAO or otherwise has the ability to execute arbitrary calldata, you can use a Reverse Registrar contract directly to set a name for it.

You might even be able to use the ENS Manager App inside of your safe app to set a primary name.

Naming Tools

Enscribe is a tool designed to simplify the process of naming smart contracts with ENS names. The application enables users to deploy new smart contracts with a primary name directly and easily name existing smart contracts.

Enscribe simplifies what is otherwise a multi-step, error-prone process by offering:

  • Atomic contract deployment using CREATE2
  • Naming Ownable, ERC173 and ReverseClaimer contracts as described above
  • ENS subname creation, forward resolution and reverse record assignment
  • Naming of existing contracts, with an easy way to locate contracts that you've already deployed

Even if you don't own an ENS name, you can still utilize Enscribe's hosted ENS parent, deployd.eth, to create subnames like my-app.deployd.eth and set them as the primary name for your contract.

To learn more, refer to the Enscribe Docs.