└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Blockchain-DNS Resolver 2 | 3 | This repository will later contain the implementation for a web resolver of BDNS domains. 4 | 5 | Right now it contains description of the [blockchain-dns.info](https://blockchain-dns.info)'s public resolver API. This API is used by BDNS browser extensions. 6 | 7 | ## Blockchain-DNS.info API 8 | 9 | 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. 10 | 11 | ### Request 12 | 13 | All requests are stateless GET with no authentication built using this URL format: 14 | 15 | ``` 16 | https://BASE_DOMAIN/FUNC/DOMAIN_TO_RESOLVE?QUERY 17 | ``` 18 | 19 | **BASE_DOMAIN** is one of the following API servers (it doesn't matter which one is used): 20 | 21 | ``` 22 | bdns.at 23 | bdns.by 24 | bdns.co 25 | bdns.im 26 | bdns.io 27 | bdns.link 28 | bdns.nu 29 | bdns.pro 30 | b-dns.se 31 | ``` 32 | 33 | These domains are no more functional ([details](https://blockchain-dns.info/#laghaus)): ~~bdns.bz, bdns.name, bdns.us, bdns.ws, bdns.su, bdns.tv, bdns.mn~~. 34 | 35 | There are also several unlisted API servers that you can find by scanning existing `bdns.*` domains (they might use invalid/self-signed HTTPS certs). 36 | 37 | **DOMAIN_TO_RESOLVE** is the domain name of interest, belonging to one of the supported TLDs: 38 | 39 | TLD | Authority 40 | ------- | --------------------------------- 41 | .bit | ![](https://blockchain-dns.info/img/menu-namecoin.png) [Namecoin](https://namecoin.org) 42 | .emc | ![](https://blockchain-dns.info/img/menu-emercoin.png) [Emercoin](https://emercoin.com) 43 | .coin | ![](https://blockchain-dns.info/img/menu-emercoin.png) [Emercoin](https://emercoin.com) 44 | .lib | ![](https://blockchain-dns.info/img/menu-emercoin.png) [Emercoin](https://emercoin.com) 45 | .bazar | ![](https://blockchain-dns.info/img/menu-emercoin.png) [Emercoin](https://emercoin.com) 46 | .bbs | [OpenNIC](https://wiki.opennic.org/opennic/dot) 47 | .chan | [OpenNIC](https://wiki.opennic.org/opennic/dot) 48 | .cyb | [OpenNIC](https://wiki.opennic.org/opennic/dot) 49 | .dyn | [OpenNIC](https://wiki.opennic.org/opennic/dot) 50 | .geek | [OpenNIC](https://wiki.opennic.org/opennic/dot) 51 | .gopher | [OpenNIC](https://wiki.opennic.org/opennic/dot) 52 | .indy | [OpenNIC](https://wiki.opennic.org/opennic/dot) 53 | .libre | [OpenNIC](https://wiki.opennic.org/opennic/dot) 54 | .neo | [OpenNIC](https://wiki.opennic.org/opennic/dot) 55 | .null | [OpenNIC](https://wiki.opennic.org/opennic/dot) 56 | .o | [OpenNIC](https://wiki.opennic.org/opennic/dot) 57 | .oss | [OpenNIC](https://wiki.opennic.org/opennic/dot) 58 | .oz | [OpenNIC](https://wiki.opennic.org/opennic/dot) 59 | .parody | [OpenNIC](https://wiki.opennic.org/opennic/dot) 60 | .pirate | [OpenNIC](https://wiki.opennic.org/opennic/dot) 61 | .ku | [OpenNIC](https://wiki.opennic.org/opennic/dot) 62 | .te | [OpenNIC](https://wiki.opennic.org/opennic/dot) 63 | .ti | [OpenNIC](https://wiki.opennic.org/opennic/dot) 64 | .uu | [OpenNIC](https://wiki.opennic.org/opennic/dot) 65 | 66 | **QUERY** is **FUNC**-dependent and is the only optional part built using regular URL encoding. 67 | 68 | ### Resolve (`r`) 69 | 70 | **FUNC** = `r`. 71 | 72 | Recognized **QUERY** parameters: 73 | 74 | Parameter | Example | Description 75 | --------- | ------- | ----------- 76 | **n** | 3 | Maximum number of IPs to return (default: all). 77 | **r** | 0 | Shuffle returned IPs (default: yes, `0` to disable and return in DNS order). 78 | 79 | #### Response 80 | 81 | There are three possible responses differentiated by HTTP status code: 82 | 83 | Code | Description 84 | --------- | -------------------------- 85 | 200 | Response contains list of IPs, separated by CR/LF (essentially putting every IP on its own line). 86 | 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~~. 87 | 500 | Response is irrelevant. **Added 20 Oct 2017** to indicate a server error. Clients should retry at another endpoint. 88 | 89 | First two response types are cached for approximately 10 minutes. 90 | 91 | #### Examples 92 | 93 | Simple query: 94 | https://bdns.io/r/nx.bit 95 | 96 | Query with preserved order of IP entries: 97 | https://bdns.at/r/t411.bit?r=0 98 | 99 | First IP entry, preserving order: 100 | https://bdns.bz/r/rutracker.lib?n=1&r=0 101 | 102 | A single random entry: 103 | https://bdns.ws/r/register.bbs?n=1 104 | 105 | ### Exists (`x`) 106 | 107 | **FUNC** = `x`. 108 | 109 | There are no recognized **QUERY** parameters: 110 | 111 | #### Response 112 | 113 | There are three possible responses differentiated by HTTP status code: 114 | 115 | Code | Description 116 | --------- | -------------------------- 117 | 200 | Response contains string `xx`, indicating that **DOMAIN_TO_RESOLVE** exists. 118 | 404 | Response contains string `nx`, indicating that there is no record for the given domain name in the blockchain. 119 | 500 | Response is irrelevant. Indicates a server error. Clients should retry at another endpoint. 120 | 121 | First two response types are cached for approximately 10 minutes. 122 | 123 | #### `r` vs `x` 124 | 125 | `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. 126 | 127 | `x` only checks for domain existence. If it returns `nx` then the name can be registered. 128 | 129 | #### Examples 130 | 131 | https://bdns.io/x/randomrumble.lib 132 | 133 | https://bdns.at/x/t411.bit 134 | 135 | For a practical application (CORS+XHR) see *blockchain-dns.info*'s own [name availability checker](https://blockchain-dns.info/explorer/). 136 | --------------------------------------------------------------------------------