dc-over-dns
v1.2.2
Published
Decentralized Content over DNS (**dc-over-dns** or **dcdns**) is a library that allows for using Domain Name System (DNS) `TXT` records as a method to associate decentralized content with domains, such as content identifiers and paths, blockchain wallet a
Downloads
13
Readme
Decentralized Content over DNS
Decentralized Content over DNS (dc-over-dns or dcdns) is a library that allows for using Domain Name System (DNS) TXT
records as a method to associate decentralized content with domains, such as content identifiers and paths, blockchain wallet and contract addresses, and redirection to non-DNS domains. The library remains agnostic to specific content, address, or domain protocols, and does not provide any resolution service for decentralized content identified from records. Instead, the library offers a DNS lookup function with validation of the data from the TXT
record to ensure it meets the specification included in this README.
Record Specification
There are a number of components in a TXT
record for dc-over-dns that are used to properly communicate information about the content contained by the record and to prevent conflicting or problematic data.
| example.com | Record Type | Value | Recommended TTL | |--|--|--|--| | _dcdns | TXT | dc=hybrid; addr=/eth/0x0000000000000000000000000000000000000000; cont=/ipfs/QmabZ1pL9npKXJg8JGdMwQMJo2NCVy9yDVYjhiHK4LTJQH | 60 | | _dcdns.eth | TXT | dc=address; addr=/eth/0x0000000000000000000000000000000000000000 | 60 | | _dcdns.ipfs | TXT | dc=content; cont=/ipfs/QmabZ1pL9npKXJg8JGdMwQMJo2NCVy9yDVYjhiHK4LTJQH | 60 | | _dcdns.ens | TXT | dc=redirect; redir=/ens/ethereum.eth | 60 |
It is reccomended to set an A
record for the target with the IPv4 address 192.0.2.1
(e.g.. for _dcdns.ipfs, set the A record for ipfs.example.com).
Components
- dc=: The
dc=
component of a record (dc for decentralized content) is used to specify a type of content or behavior the domain is associated with so that it may be properly handled by users of the library. This has four possible values:address
,content
,hybrid
, andredirect
.- address: The
address
type fordc=
indicates the record value supports a blockchain wallet or contract address so that the domain can be used as an alias for the address. For example, the domainsexample.com
withdc=
typeaddress
can be used as an alias of an Ethereum wallet address. This allows the domain to act as a mutable pointer for an address. - content: The
content
type fordc=
indicates the record value supports content identifiers/content hashes for decentralized content sources. For example, a viable value in this record is a content identifier (CID) for the InterPlanetary File System (IPFS). - hybrid: The
hybrid
type fordc=
indicates the record value supports both address and decentralized content data as a hybrid of the previously describedaddress
andcontent
types. - redirect: The
redirect
type fordc=
indicates the record supports data for the redirection to a non-DNS domain. For example, the record can indicate thatexample.com
is to redirect to the Ethereum Name Service (ENS) domainexample.eth
.
- address: The
- addr=: The
addr=
component of a record is used to specify the value for an address the domain acts as a mutable pointer for when thedc=
type is eitheraddress
orhybrid
. - cont=: The
cont=
component of a record is used to specify the value for a decentralized content source the domain points to when thedc=
type is eithercontent
orhybrid
. - redir=: The
redir=
component of a record is used to specify the value for a non-DNS domain the domain is to redirect to when thedc=
type isredirect
.
Validation
The validateTxtRecord
function from the dnsLookup.js
module is designed to validate the structure and content of the TXT
record data, ensuring that the records comply with the specification. Within the validation, a common format for the content values (the value for the addr=
, cont=
, and redir=
components) is enforced, where the expected format of a content value is /{protocol}/{content}
. As part of remaining protocol agnostic, no checks of a valid protocol or valid content are performed, only validation for adherence for the protocol-content pairing format as previously described. This allows for any protocol and any content to be accepted.
dc=
Validation: The first validation step is ensuring the presence of adc=
component, which is required for defining the type of decentralized content the record is meant to handle. Ifdc=
does not contain an acceptable value (a type that is not address, content, hybrid, or redirect), or does not exist at all, the domain will be rejected for failed validation. If thedc=
validation check passes, the context of the resolveddc=
type is used to determine the remaining validation checks.- Protocol Duplication Check: For the
dc=
types allowing foraddr=
orcont=
components, multipleaddr=
orcont=
values may be passed, as long as they use unique protocols. For example, a record withdc=
typeaddress
can support multipleaddr=
components (in this example, two), as long as a protocol is not repeated. If the two addresses are a Bitcoin address and an Ethereum address, recorded asaddr=/btc/{btc-address}; addr=/eth/{eth-address}
, this would pass validation since there is no duplicate appearance of the protocol in the protocol-content pairing. If instead the record contained something such as two Solana addresses, recorded asaddr=/sol/{address-1}; addr=/sol/{address-2}
, this would fail validation for the duplicate appearance ofsol
in the protocol position. - Content and Address Restrictions: Depending on the
dc=
type, there are restrictions on the presence ofaddr=
andcont=
components in a record. Non-compliance with these restrictions will result in a rejection.- If the
dc=
type isaddress
, the record cannot contain anycont=
components, as this is solely intended for blockchain addresses. - If the
dc=
type iscontent
, the record cannot include anyaddr=
components, as this is solely intended for serving decentralized content sources. - For
hybrid
types, these restrictions do not apply, allowing for a mix of address and content components in the record.
- If the
redir=
Component Validation: When thedc=
type of a record isredirect
, this validation step ensures that there is exactly oneredir=
component present in the record. Additionally, the record cannot contain anyaddr=
orcont=
components, as theredirect
type is incompatible with direct references to addresses or content.- Exclusivity of
redir=
: If thedc=
type is anything other thanredirect
, the presence of anyredir=
component is deemed invalid, which will result in a rejection. This rule maintains the exclusivity of the redirection functionality to theredirect
type to prevent any confusion or misconfiguration.
Usage
To utilize this library, install it via npm i dc-over-dns
. Two imports are supported, dcDNS
for the record resolution, and configureResolver
to set a DNS resolver other than the default resolver. The dcDNS
function supports two methods, resolve
, which returns the resolved data in plaintext separated by commas and spaces, and jsonResolve
, which returns the resolved data as a JSON object.
Example Usage for dcDNS.resolve
// This sample does not use configureResolver
const { dcDNS } = require('dc-over-dns');
dcDNS.resolve('example.com').then(value => {
console.log(value);
});
This will return plaintext output, as seen in the following examples:
- Example 1, Ethereum Address:
/eth/0x0000000000000000000000000000000000000000
- Example 2, IPFS CID:
/ipfs/QmabZ1pL9npKXJg8JGdMwQMJo2NCVy9yDVYjhiHK4LTJQH
- Example 3, Redirect Domain:
/ens/ethereum.eth
Example Usage for dcDNS.jsonResolve
// This sample uses configureResolver
const { dcDNS, configureResolver } = require('dc-over-dns');
configureResolver(['8.8.8.8']);
dcDNS.jsonResolve('example.com').then(value => {
console.log(value);
});
This will return a JSON object, as seen in the following examples:
Example 1, dc=address
.
{
"type": "_dcdns.address",
"protocol": "eth",
"content": "0x0000000000000000000000000000000000000000"
}
Example 2, dc=content
.
{
"type": "_dcdns.content",
"protocol": "ipfs",
"content": "QmabZ1pL9npKXJg8JGdMwQMJo2NCVy9yDVYjhiHK4LTJQH"
}
Example 3, dc=hybrid
.
{
"type": "_dcdns.hybrid",
"contents": [
{
"protocol": "eth",
"content": "0x0000000000000000000000000000000000000000"
},
{
"protocol": "ipfs",
"content": "QmabZ1pL9npKXJg8JGdMwQMJo2NCVy9yDVYjhiHK4LTJQH"
}
]
}
Example 4, dc=redirect
.
{
"type": "_dcdns.redirect",
"redirect": {
"protocol": "ens",
"name": "ethereum.eth"
}
}