Ethereum Name Service

The Ethereum Name Service is analogous to the Domain Name Service. It enables users and developers to use human-friendly names in place of error-prone hexadecimal addresses, content hashes, and more.

The ens module is included with web3.py. It provides an interface to look up an address from a name, set up your own address, and more.

Setup

Create an ENS object (named ns below) in one of three ways:

  1. Automatic detection
  2. Specify an instance or list of Providers
  3. From an existing web3.Web3 object via ens.main.ENS.from_web3()
# automatic detection
from ens.auto import ns


# or, with a provider
from web3 import IPCProvider
from ens import ENS

provider = IPCProvider(...)
ns = ENS(provider)


# or, with a w3 instance
# Note: This inherits the w3 middlewares from the w3 instance and adds a stalecheck middleware to the middleware onion
from ens import ENS

w3 = Web3(...)
ns = ENS.from_web3(w3)

Usage

Name info

Look up the address for an ENS name

from ens.auto import ns


# look up the hex representation of the address for a name

eth_address = ns.address('jasoncarver.eth')

assert eth_address == '0x5B2063246F2191f18F2675ceDB8b28102e957458'

The ENS module has no opinion as to which TLD you can use, but will not infer a TLD if it is not provided with the name.

Get name from address

domain = ns.name('0x5B2063246F2191f18F2675ceDB8b28102e957458')

# name() also accepts the bytes version of the address
assert ns.name(b'[ c$o!\x91\xf1\x8f&u\xce\xdb\x8b(\x10.\x95tX') == domain


# confirm that the name resolves back to the address that you looked up:
assert ns.address(domain) == '0x5B2063246F2191f18F2675ceDB8b28102e957458'

Get owner of name

eth_address = ns.owner('exchange.eth')

Set up your name

Point your name to your address

Do you want to set up your name so that address() will show the address it points to?

ns.setup_address('jasoncarver.eth', '0x5B2063246F2191f18F2675ceDB8b28102e957458')

You must already be the owner of the domain (or its parent).

In the common case where you want to point the name to the owning address, you can skip the address

ns.setup_address('jasoncarver.eth')

You can claim arbitrarily deep subdomains. Gas costs scale up with the number of subdomains!

ns.setup_address('supreme.executive.power.derives.from.a.mandate.from.the.masses.jasoncarver.eth')

Wait for the transaction to be mined, then:

assert ns.address('supreme.executive.power.derives.from.a.mandate.from.the.masses.jasoncarver.eth') == \
    '0x5B2063246F2191f18F2675ceDB8b28102e957458'

Allow people to find your name using your address

Do you want to set up your address so that name() will show the name that points to it?

This is like Caller ID. It enables you and others to take an account and determine what name points to it. Sometimes this is referred to as “reverse” resolution.

ns.setup_name('jasoncarver.eth', '0x5B2063246F2191f18F2675ceDB8b28102e957458')

Note

Do not rely on reverse resolution for security.

Anyone can claim any “caller ID”. Only forward resolution implies that the owner of the name gave their stamp of approval.

If you don’t supply the address, setup_name() will assume you want the address returned by address().

ns.setup_name('jasoncarver.eth')

If the name doesn’t already point to an address, setup_name() will call setup_address() for you.

Wait for the transaction to be mined, then:

assert ns.name('0x5B2063246F2191f18F2675ceDB8b28102e957458') == 'jasoncarver.eth'

Set Text Metadata for an ENS Record

As the owner of an ENS record, you can add text metadata. A list of supported fields can be found in the ENS documentation. You’ll need to setup the address first, and then the text can be set:

ns.setup_address('jasoncarver.eth', 0x5B2063246F2191f18F2675ceDB8b28102e957458)
ns.set_text('jasoncarver.eth', 'url', 'https://example.com')

A transaction dictionary can be passed as the last argument if desired:

transaction_dict = {'from': '0x123...'}
ns.set_text('jasoncarver.eth', 'url', 'https://example.com', transaction_dict)

If the transaction dictionary is not passed, sensible defaults will be used, and if a transaction dictionary is passed but does not have a from value, the default will be the owner.

Read Text Metadata for an ENS Record

Anyone can read the data from an ENS Record:

url = ns.get_text('jasoncarver.eth', 'url')
assert url == 'https://example.com'