Browser Resolution Algorithm
A browser can select the supported protocol. If a domain is configured for multiple protocols, it should prioritize a protocol based on
browser.preferred_protocols record that can be set to a list of the defined protocols.
browser.preferred_protocols is not set, a browser should use the following value as a default
["bzz", "ipfs", "https", "http", "ftp"]. If
browser.preferred_protocols is set but is not complete, a browser should append the absent protocols in the default order specified above. A domain can have a single content identifier for each distributed protocol stored in
dweb.bzz.hash for Swarm's
bzz protocol. See D-Web Records for more information.
If none of the
dweb hash records are set, a browser should fall back to legacy ipfs record that is set as
If none of the
dweb or legacy
ipfs.html.value records are set, a browser should fall back to DNS resolution that is set within
If none of the
dns.* records are set, a browser should fall back to the
browser.redirect_url or legacy
browser.redirect_url key has a priority over
ipfs.redirect_domain.value if both are set.
Generally, browsers automatically add
http:// prefix for any domain in the address bar if the protocol is not specified explicitly by a user. For Web3 domain names (assuming a browser supports many protocols), it is preferred to determine a protocol only after resolving domain records.
ipfs.redirect_domain.value contains full URL according to RFC-1738 and no additional actions required to provide redirect.
Browser resolution records
All records related to browser resolution are stored within these namespaces:
dns.*— For traditional DNS records
dweb.*— For distributed content records
browser.*— Hint records to help a browser determine a preferred hypermedia protocol
To retrieve records associated with a domain, see Resolve Using Smart Contracts.
Resolver records may contain classical DNS records along with other records. To distinguish those from other CNS (Crypto Name Service) records, the
dns.* namespace is used. So DNS
A corresponds to the
dns.A CNS record. Any listed DNS record described in RFC standards is supported. All record names must follow the uppercase naming convention.
Unlike DNS, the CNS
Resolver doesn't support multiple records with the same key. Therefore, DNS record values must be stored as a JSON serialized array of strings.
A domain that needs one
CNAMErecord set to
example.com.must be configured as one crypto record
A domain that needs two
Arecords set to
10.0.0.2must be configured as one crypto record
This serialization is the only data transformation required when converting a traditional DNS record into a CNS record.
CNS records do not have a domain name associated with them. That is why there is no feature for storing your subdomain records inside a parent domain. Example:
www.example.com record can only be set inside a resolver of
www.example.com but never inside
A recommended way to display content in a browser for Web3 domains is explained in Resolve Domains in Web Applications.
TTL records can be set for all records or individual types of records. TTL for all records can be set in
dns.ttl. TTL for an individual record type can be set in
ttl for individual an record type is not set, a default
dns.ttl must be applied. If a
dns.ttl record is not set, the client recommends using
300 (5 minutes) as a default value.
Example CNS records setup:
Should be transformed into the following DNS records:
TTL for individual records of the same type is currently unsupported. This is due to needing to change the record value format, increased gas cost, and their deprecated status according to RFC-2181. Setting
dns.ttl instead of TTL for individual records is recommended due to higher gas efficiency.
It is a common practice in DNS to have an authority of a subdomain delegated to a parent domain. This mechanism is not necessary for Web3 domains because the cost of subdomain registration is comparable to setting records. In other words, configuring a subdomain using the parent domain has no benefit and may result in even higher gas costs since it's necessary to store associated subdomain names to each record.
Therefore, authority configurations are not supported by Web3 domains at the moment.
Decentralized Web Records
Decentralized Web (D-Web) records allow configuring a domain for decentralized website protocols like IPFS or Swarm. These records are stored in the
dweb.* namespace. Each protocol has its own sub-namespace for its data using a canonical name. Example: Swarm's protocol canonic name is
bzz so its records are stored at
Record structure can be different based on the protocol. However, all protocols have a common
.hash record used to reference content in the decentralized network. Example:
dweb.ipfs.hash for IPFS protocol.
See Resolve Domains in Web Applications for information on how to interpret those records.
Legacy records support
As of Q3 2020, most .crypto domains are configured using legacy record names for IPFS hash and redirect domain:
ipfs.html.valuedeprecated in favor of
ipfs.redirect_domain.valuedeprecated in favor of
Browsers are strongly recommended to support those records as a fallback when corresponding replacement records are not set.