Namespace ENS Web3 Plugin

Web3 plugin that extends ENS functionality, and provides the following features:

• ENS name registration
• text record management and resolution
• address and name resolution

Installation

yarn add web3 @namespace-ens/web3-plugin-ens

Basic usage

import { Web3 } from 'web3';
import { Chain, EnsPlugin } from '@namespace-ens/web3-plugin-ens';

const web3 = new Web3('_your_rpc_connection_url_');
web3.registerPlugin(new EnsPlugin(Chain.Sepolia));
web3.eth.accounts.wallet.add('_your_private_key_');

// set and resolve an address for your ENS name
await web3.ens.setAddress('_your_ens_name_', '_your_address_');
await web3.ens.getAddress('_your_ens_name_');

Step by step

Setting up the plugin

Register your plugin. There are two types of connections for which the plugin can be registered:

• public connection - connecting with a wallet such as MetaMask.
• private connection - connecting with your private key

Public connection

const web3 = new Web3(window.ethereum);

Private connection

const web3 = new Web3('_your_rpc_connection_url_');

For private connections you will also need to link your account to the plugin.

web3.eth.accounts.wallet.add('_your_private_key_');

Plugin registration

Next you will need to register the plugin. The plugin supports Ethereum Mainnet: const chain = Chain.Mainnet and Sepolia: const chain = Chain.Sepolia.

web3.registerPlugin(new EnsPlugin(chain));

Domain registration

In order to register an ENS domain, you will need to create a RegistrationRequest:

interface RegistrationRequest {
  label: string; // label of the ENS domain (eg. web3js.eth, where web3js is the label)
  owner: string; // address of the wallet that will own the domain
  durationInSeconds: number; // how long the domain will registered for (set 31536000 for one year)
  secret: string; // random secret string
  resolver: string; // address of the domain name resolver (use 0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63 for the official ENS PublicResolver)
  setAsPrimary: boolean; // is the domain primary for the address registering the domain (creates reverese record)
  fuses: number; // fuses that will be burned for the domain name
}

To learn more about the registration details please refer to: https://docs.ens.domains/registry/eth#controllers

Once you have RegistrationRequest, proceed with the registration:

1. Submit a commitment hash based on the instance of registrationRequest, which is used to prevent front running of the registration process:

await web3.ens.commit(registrationRequest);

2. To prevent front running and ensure that the registration makes it to another block, ENS requires at least one minute delay before proceeding to the next step.
3. Finally, after the one minute delay submit the registration request:

await web3.ens.registerEnsDomain(registrationRequest);

Setting and retrieving text records

To set records call setTextRecords with these parameters:

• name: ENS domain for which the records are set (for example yourname.eth)
• recordsToUpdate: array of TextRecords, where TextRecord is defined as:

interface TextRecord {
  key: string;
  value: string;
}

• recordsToRemove: array of record keys for which removal is required

await web3.ens.setTextRecords(name, recordsToUpdate, recordsToRemove);

To get records call getRecords with these parameters:

• name: ENS domain for which the records are retrieved (for example yourname.eth)
• recordKeys: array of record keys for which the retrieval is required

await web3.ens.getTextRecords(name, recordKeys);

Address and name resolution

Address resolution

To set the address to which the name will resolve, call setAddress with these parameters:

• name: for which the address is set (for example yourname.eth)
• address: address of the wallet

await web3.ens.setAddress(name, address);

To resolve the address call:

await web3.ens.getAddress(name);

Reverse name resolution

To set the name for your address call setName:

await web3.ens.setName(name);

You can also call setNameForAddr and provide these parameters:

• address: address for which to set the record
• owner: address that owns the reverse record
• resolver: address of the resolver (use 0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63 for the official ENS PublicResolver)
• name: name for which the address will resolve (for example yourname.eth)

The wallet calling setNameForAddr will need to be given the approval by the wallet at the above address - this can be done by calling setApprovalForAll

await web3.ens.setNameForAddr(address, owner, resolver, name);

To resolve the name for the stored adddress call:

const node = await web3.ens.node(address);
const name = await web3.ens.getName(node);