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(provider: BaseProvider = <object object>, addr: NewType.<locals>.new_type = 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: str) → hexbytes.main.HexBytes¶

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 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: str) → str¶

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: str) → bool¶

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: Web3, addr: NewType.<locals>.new_type = None) → ENS¶

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: str) → Optional[NewType.<locals>.new_type]¶

Look up the Ethereum address that name currently points to.

Parameters: name (str) – an ENS name to look up
Raises: InvalidName – if name has invalid syntax

name(address: NewType.<locals>.new_type) → Optional[str]¶

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: str, address: Union[NewType.<locals>.new_type, NewType.<locals>.new_type, NewType.<locals>.new_type] = <object object>, transact: TxParams = {}) → hexbytes.main.HexBytes¶

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
address (str) – name will point to this address, in checksum format. 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

InvalidName – if name has invalid syntax
UnauthorizedError – if 'from' in transact does not own name

setup_name(name: str, address: NewType.<locals>.new_type = None, transact: TxParams = {}) → hexbytes.main.HexBytes¶

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

AddressMismatch – if the name does not already point to the address
InvalidName – if name has invalid syntax
UnauthorizedError – if 'from' in transact does not own name
UnownedName – if no one owns name

owner(name: str) → NewType.<locals>.new_type¶

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: str, new_owner: NewType.<locals>.new_type = <object object>, transact: TxParams = {}) → NewType.<locals>.new_type¶

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

InvalidName – if name has invalid syntax
UnauthorizedError – if 'from' in transact does not own name

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