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=<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 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, andnameprep()
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)¶ 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)¶ 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 withsub.parentname.eth
, thensub
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, 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: 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)¶ 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()
orsetup_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 withsub.parentname.eth
, thensub
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
-
static
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.
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 thetransact
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.