ENS API

Ethereum Name Service has a friendly overview.

Continue below for the detailed specs on each method and class in the ens module.

ens.main module

class ens.main.ENS(providers=<object object>, addr=None)

Quick access to common Ethereum Name Service functions, like getting the address for a name.

Unless otherwise specified, all addresses are assumed to be a str in checksum format, like: "0x314159265dD8dbb310642f98f50C066173C1259b"

static namehash(name)

Generate the namehash. This is also known as the node in ENS contracts.

In normal operation, generating the namehash is handled behind the scenes. For advanced usage, it is a helpful utility.

This will add ‘.eth’ to name if no TLD given. Also, it normalizes the name with nameprep before hashing.

Parameters:name (str) – ENS name to hash
Returns:the namehash
Return type:bytes
Raises:InvalidName – if name has invalid syntax
static nameprep(name)

Clean the fully qualified name, as defined in ENS EIP-137

This does not enforce whether name is a label or fully qualified domain.

Parameters:name (str) – the dot-separated ENS name
Raises:InvalidName – if name has invalid syntax
static is_valid_name(name)

Validate whether the fully qualified name is valid, as defined in ENS EIP-137

Parameters:name (str) – the dot-separated ENS name
Returns:True if name is set, and nameprep() will not raise InvalidName
classmethod fromWeb3(web3, addr=None)

Generate an ENS instance with web3

Parameters:
  • web3 (web3.Web3) – to infer connection information
  • addr (hex-string) – the address of the ENS registry on-chain. If not provided, ENS.py will default to the mainnet ENS registry address.
address(name, guess_tld=True)

Look up the Ethereum address that name currently points to.

Parameters:
  • name (str) – an ENS name to look up
  • guess_tld (bool) – should name be appended with ‘.eth’ if no common TLD found?
Raises:

InvalidName – if name has invalid syntax

name(address)

Look up the name that the address points to, using a reverse lookup. Reverse lookup is opt-in for name owners.

Parameters:address (hex-string) –
reverse(address)

Look up the name that the address points to, using a reverse lookup. Reverse lookup is opt-in for name owners.

Parameters:address (hex-string) –
setup_address(name, address=<object object>, transact={})

Set up the name to point to the supplied address. The sender of the transaction must own the name, or its parent name.

Example: If the caller owns parentname.eth with no subdomains and calls this method with sub.parentname.eth, then sub will be created as part of this call.

Parameters:
  • name (str) – ENS name to set up, in checksum format
  • address (str) – name will point to this address. If None, erase the record. If not specified, name will point to the owner’s address.
  • transact (dict) – the transaction configuration, like in sendTransaction()
Raises:
setup_name(name, address=None, transact={})

Set up the address for reverse lookup, aka “caller ID”. After successful setup, the method name() will return name when supplied with address.

Parameters:
  • name (str) – ENS name that address will point to
  • address (str) – to set up, in checksum format
  • transact (dict) – the transaction configuration, like in sendTransaction()
Raises:
owner(name)

Get the owner of a name. Note that this may be different from the deed holder in the ‘.eth’ registrar. Learn more about the difference between deed and name ownership in the ENS Managing Ownership docs

Parameters:name (str) – ENS name to look up
Returns:owner address
Return type:str
setup_owner(name, new_owner=<object object>, transact={})

Set the owner of the supplied name to new_owner.

For typical scenarios, you’ll never need to call this method directly, simply call setup_name() or setup_address(). This method does not set up the name to point to an address.

If new_owner is not supplied, then this will assume you want the same owner as the parent domain.

If the caller owns parentname.eth with no subdomains and calls this method with sub.parentname.eth, then sub will be created as part of this call.

Parameters:
  • name (str) – ENS name to set up
  • new_owner – account that will own name. If None, set owner to empty addr. If not specified, name will point to the parent domain owner’s address.
  • transact (dict) – the transaction configuration, like in sendTransaction()
Raises:
Returns:

the new owner’s address

ens.exceptions module

exception ens.exceptions.AddressMismatch

Bases: ValueError

In order to set up reverse resolution correctly, the ENS name should first point to the address. This exception is raised if the name does not currently point to the address.

exception ens.exceptions.InvalidName

Bases: idna.core.IDNAError

This exception is raised if the provided name does not meet the syntax standards specified in EIP 137 name syntax.

For example: names may not start with a dot, or include a space.

exception ens.exceptions.UnauthorizedError

Bases: Exception

Raised if the sending account is not the owner of the name you are trying to modify. Make sure to set from in the transact keyword argument to the owner of the name.

exception ens.exceptions.UnownedName

Bases: Exception

Raised if you are trying to modify a name that no one owns.

If working on a subdomain, make sure the subdomain gets created first with setup_address().

exception ens.exceptions.BidTooLow

Bases: ValueError

Raised if you bid less than the minimum amount

exception ens.exceptions.InvalidBidHash

Bases: ValueError

Raised if you supply incorrect data to generate the bid hash.

exception ens.exceptions.InvalidLabel

Bases: ValueError

Raised if you supply an invalid label

exception ens.exceptions.OversizeTransaction

Bases: ValueError

Raised if a transaction you are trying to create would cost so much gas that it could not fit in a block.

For example: when you try to start too many auctions at once.

exception ens.exceptions.UnderfundedBid

Bases: ValueError

Raised if you send less wei with your bid than you declared as your intent to bid.