Blockchain-DNS Resolver

This repository will later contain the implementation for a web resolver of BDNS domains.

Right now it contains description of the blockchain-dns.info's public resolver API. This API is used by BDNS browser extensions.

Blockchain-DNS.info API

This document describes API v0, i.e .the basic level that will remain stable and be available for the lifetime of the project. Subsequent versions will be made available under separate paths.

Request

All requests are stateless GET with no authentication built using this URL format:

https://BASE_DOMAIN/FUNC/DOMAIN_TO_RESOLVE?QUERY

BASE_DOMAIN is one of the following API servers (it doesn't matter which one is used):

bdns.at
bdns.by
bdns.co
bdns.im
bdns.io
bdns.link
bdns.nu
bdns.pro
b-dns.se

These domains are no more functional (details): bdns.bz, bdns.name, bdns.us, bdns.ws, bdns.su, bdns.tv, bdns.mn.

There are also several unlisted API servers that you can find by scanning existing bdns.* domains (they might use invalid/self-signed HTTPS certs).

DOMAIN_TO_RESOLVE is the domain name of interest, belonging to one of the supported TLDs:

TLD	Authority
.bit	Namecoin
.emc	Emercoin
.coin	Emercoin
.lib	Emercoin
.bazar	Emercoin
.bbs	OpenNIC
.chan	OpenNIC
.cyb	OpenNIC
.dyn	OpenNIC
.geek	OpenNIC
.gopher	OpenNIC
.indy	OpenNIC
.libre	OpenNIC
.neo	OpenNIC
.null	OpenNIC
.o	OpenNIC
.oss	OpenNIC
.oz	OpenNIC
.parody	OpenNIC
.pirate	OpenNIC
.ku	OpenNIC
.te	OpenNIC
.ti	OpenNIC
.uu	OpenNIC

QUERY is FUNC-dependent and is the only optional part built using regular URL encoding.

Resolve (r)

FUNC = r.

Recognized QUERY parameters:

Parameter	Example	Description
n	3	Maximum number of IPs to return (default: all).
r	0	Shuffle returned IPs (default: yes, 0 to disable and return in DNS order).

Response

There are three possible responses differentiated by HTTP status code:

Code	Description
200	Response contains list of IPs, separated by CR/LF (essentially putting every IP on its own line).
404	Response contains string nx. This may indicate that the domain doesn't exist, has no IP entries (which is common for Namecoin and Emercoin) or that there was an error.
500	Response is irrelevant. Added 20 Oct 2017 to indicate a server error. Clients should retry at another endpoint.

First two response types are cached for approximately 10 minutes.

Examples

Simple query: https://bdns.io/r/nx.bit

Query with preserved order of IP entries: https://bdns.at/r/t411.bit?r=0

First IP entry, preserving order: https://bdns.bz/r/rutracker.lib?n=1&r=0

A single random entry: https://bdns.ws/r/register.bbs?n=1

Exists (x)

FUNC = x.

There are no recognized QUERY parameters:

Response

There are three possible responses differentiated by HTTP status code:

Code	Description
200	Response contains string xx, indicating that DOMAIN_TO_RESOLVE exists.
404	Response contains string nx, indicating that there is no record for the given domain name in the blockchain.
500	Response is irrelevant. Indicates a server error. Clients should retry at another endpoint.

First two response types are cached for approximately 10 minutes.

r vs x

r expects a domain to exist and to resolve to valid IPs. Even if a domain doesn't resolve (you cannot browse it), it may still exist in the blockchain meaning it cannot be registered.

x only checks for domain existence. If it returns nx then the name can be registered.

Examples

https://bdns.io/x/randomrumble.lib

https://bdns.at/x/t411.bit

For a practical application (CORS+XHR) see blockchain-dns.info's own name availability checker.