ENSBuilder lets you set up your own ENS instance for testing purposes.

Usage no npm install needed!

<script type="module">
  import ensBuilder from 'https://cdn.skypack.dev/ens-builder';


Build Status


ENSBuilder lets you set up your own ENS instance for testing purposes.

Works best with ethers.js, but can also be used with web3js (see Using with Web3 section below).

Basic usage

To install:

npm install ens-builder

To create a new instance of the builder using ethers.js wallet:

import ENSBuilder from 'ens-builder';
const builder = new ENSBuilder(wallet);

The fastest way to start is to use the bootstrapWith convenience method:

const ensAddress = await builder.bootstrapWith('example', 'eth');

This will setup ENS, register the eth top-level domain and the example.eth subdomain under it. It will also create a registrar for example.eth, a reverse registrar, as well as a global resolver.

The method will return the address of the deployed ENS. It can then be used, for example, to setup a new ethers provider and use it's methods for domain resolution:

const provider = ethers.providers.getDefaultProvider({..., ensAddress})
const address = provider.resolveName('example.eth');
const name = provider.lookupAddress('example.eth');

You can also use the registerAddress to add even more domains. For example:

await builder.registerAddress('alex', 'mylogin.eth', givenAddress);

Or it's registerAddressWithReverse variant that also registers a revers record:

await builder.registerAddressWithReverse('alex', 'mylogin.eth', wallet);

Using with web3

To use with web3 you will have to wrap a web3 provider with an ethers Web3Provider, as well as adding the private key into a ethers wallet:

const privateKey = ...;
const web3Provider = ...;
const ethersProvider = new providers.Web3Provider(web3Provider);
wallet = new ethers.Wallet(privateKey, ethersProvider);
builder = new ENSBuilder(deployer);

Advanced usage

To bootstrap system without any domains yet:

await builder.bootstrap();

Single resolver for all domains is available with resolver property:


To created top level domain:

await builder.registerTLD('eth');

To add reverse registrar for reverse ENS lookup:

await builder.registerReverseRegistrar();

To register a domain with a registrar:

await builder.registerDomain('mylogin', 'eth');

The registrar for the domain is available with registrars property:


To register domain with registrar pointing to given address:

await builder.registerAddress('alex', 'mylogin.eth', givenAddress);