Name Resolution
NameRegistry
The NameRegistry
contract provides forward and reverse resolution.
Clients retrieve the current address of NameRegistry
by reading it from the storage of the proxy contract NameRegistry.CheckAddress (as explained in the Proxy Contracts chapter).
Resolution by off-chain clients with view support (recommended)
Clients that have the ability to invoke TZIP-16 views should use the following to resolve names and addresses.
View: resolve-name
Resolves a name to an address, optionally other domain data, and expiry information for reference. If no such record exists or it has expired, it returns None
.
Before passing a name for resolution, it should first be normalized using the encode algorithm.
Parameter Type | Description |
| The UTF-8 encoded name to resolve. |
View: resolve-address
Resolves an address to a name, optionally other domain data, and expiry information for reference. If no such record exists or it has expired, it returns None
.
Parameter Type | Description |
| The address to resolve. |
Return type
The return type for both resolve-name
and resolve-address
is as follows:
Instructions for Off-chain Clients lacking view support
Clients that lack TZIP-16 view support can read from the contract storage directly. The NameRegistry
contract has the following storage structure:
Clients must not rely on a particular storage or record layout. They should always use annotations to find the correct value.
Forward Resolution (name to address)
The resolution algorithm is as follows:
Normalize and validate the full domain name using the encode algorithm. See the section Name Validation and Normalization for more details.
Look up the name in the
records
bigmap. If the bigmap contains no such key, the given domain is not resolvable.Use the
expiry_key
value of the record to look up the validity in theexpiry_map
. If a timestamp is found and is lower or equal to the current time, the given domain is not resolvable.Extract the optional
address
value from the record. If the optional value isNone
, the given domain is not resolvable. Otherwise use theaddress
value.
Reverse Resolution (address to name)
The resolution algorithm is as follows:
Look up the address in the
reverse_records
bigmap. If the bigmap contains no such key, the given address is not resolvable.Extract the optional
name
value. If the optional value isNone
, the given address is not resolvable.Use the
name
value to look up the corresponding forward record. Use it'sexpiry_key
value to look up the validity of the record in theexpiry_map
. If a timestamp is found and is lower or equal to the current timestamp, the given address is not resolvableOtherwise, use the
name
value.
Instructions for Contracts
The resolution of names by contracts is currently not supported. Sometimes, it can be useful to validate on-chain that a name corresponds to an address. For example, a wallet might group a transaction sending money with another transaction that performs this check. If the check fails, both transactions fail and no money changes hands.
Both on-chain and off-chain clients can do this by calling the check_address
entry-point on NameRegistry.CheckAddress
.
The transaction will either do nothing (if the address is indeed correct) or fail with the message NAME_ADDRESS_MISMATCH
if the address is incorrect.
Name Validation and Normalization
Domain names generally have to conform to the IDNA 2008 mechanism (RFC 5891, 5892, 5893). The Unicode Standard UTS 46 is a more specific (and stricter) application standard which is to be used for validation and normalization of domain names to achieve IDNA conformance.
Length Limit
The length limitations are currently:
1 to 100 characters in a single label,
up to 400 bytes in a full domain name.
It is not necessary for clients to check length when performing lookup or reverse lookup, as the names are already validated on-chain. It is however strongly recommended to do so when creating new records to avoid transaction failures.
Name Encode Algorithm
This algorithm is used both for domain creation and lookup purposes when communicating with contracts. It permits the dot character (.
) so it can be used both for encoding names and individual labels.
The ToUnicode algorithm is used to produce a normalized and validated name string. The UTS 46 version of
ToUnicode
validates the string, making it notably different fromToUnicode
defined in IDNA, which does not have to fail on invalid labels. The algorithm is invoked with the following parameters:CheckHyphens = true
CheckBidi = true
CheckJoiners = true
UseSTD3ASCIIRules = true
Transitional_Processing = false
The name or label is encoded using UTF-8 into
bytes
.
Libraries
Some implementations of UTS 46 include:
idna-uts46-hx for JavaScript
idna for Python
Libraries that implement IDNA but not UTS 46 can alternatively be used. The string has to be first validated and normalized using ToAscii
and the result converted back with ToUnicode
. Some implementations of IDNA (that don't include validation and normalization as part of the ToUnicode
algorithm and have to be called using ToUnicode(ToAscii(name))
):
System.Globalization.IdnMapping in .NET
idna for Rust
java.net.IDN in Java (only implements IDNA 2003)
Last updated