mirror of https://github.com/lukechilds/docs.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
714 lines
34 KiB
714 lines
34 KiB
<!DOCTYPE html>
|
|
<html lang="en">
|
|
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<!-- Begin Jekyll SEO tag v2.5.0 -->
|
|
<title>BNS Subdomains | Blockstack</title>
|
|
<meta name="generator" content="Jekyll v3.8.3" />
|
|
<meta property="og:title" content="BNS Subdomains" />
|
|
<meta name="author" content="Blockstack" />
|
|
<meta property="og:locale" content="en_US" />
|
|
<meta name="description" content="BNS Subdomains" />
|
|
<meta property="og:description" content="BNS Subdomains" />
|
|
<link rel="canonical" href="https://zbabystack.netlify.com/core/naming/subdomains.html" />
|
|
<meta property="og:url" content="https://zbabystack.netlify.com/core/naming/subdomains.html" />
|
|
<meta property="og:site_name" content="Blockstack" />
|
|
<meta property="og:type" content="article" />
|
|
<meta property="article:published_time" content="2018-09-08T19:24:57-07:00" />
|
|
<script type="application/ld+json">
|
|
{"description":"BNS Subdomains","author":{"@type":"Person","name":"Blockstack"},"@type":"BlogPosting","url":"https://zbabystack.netlify.com/core/naming/subdomains.html","headline":"BNS Subdomains","dateModified":"2018-09-08T19:24:57-07:00","datePublished":"2018-09-08T19:24:57-07:00","mainEntityOfPage":{"@type":"WebPage","@id":"https://zbabystack.netlify.com/core/naming/subdomains.html"},"@context":"http://schema.org"}</script>
|
|
<!-- End Jekyll SEO tag -->
|
|
|
|
<!-- <meta property="og:image" content="https://zbabystack.netlify.com/assets/posts/logo.png"/> -->
|
|
<meta property="og:image" content="/assets/posts/logo.png"/>
|
|
<link rel="stylesheet" href="/assets/css/main.css">
|
|
<link rel="shortcut icon" type="image/png" href="/assets/img/touch-icon.png" >
|
|
<link rel="alternate" type="application/rss+xml" title="Blockstack" href="/feed.xml">
|
|
<script src="/assets/js/main.js"></script>
|
|
|
|
</head>
|
|
|
|
|
|
<body>
|
|
|
|
<header class="uk-background-secondary">
|
|
<div data-uk-sticky="sel-target: .uk-navbar-container; cls-active: uk-navbar-sticky" class="uk-sticky uk-sticky-fixed" style="position: fixed; top: 0px; width: 1904px;">
|
|
<nav class="uk-navbar-container">
|
|
<div class="uk-container">
|
|
<div data-uk-navbar>
|
|
<div class="uk-navbar-left">
|
|
|
|
<!-- <a class="uk-navbar-item uk-logo" href="/"><img src="https://zbabystack.netlify.com/assets/posts/logo.png" alt="Docs"></a> -->
|
|
<a class="uk-navbar-item uk-logo" href="/"><img src="/assets/posts/logo.png" alt="Docs"></a>
|
|
|
|
</div>
|
|
<div class="uk-navbar-right">
|
|
<ul class="uk-navbar-nav uk-visible@m">
|
|
|
|
|
|
|
|
|
|
<li><a href="https://blockstack.org" target="_blank" >Blockstack.org</a></li>
|
|
|
|
|
|
|
|
|
|
|
|
<li><a href="https://forum.blockstack.org/" target="_blank" >Forums</a></li>
|
|
|
|
|
|
|
|
|
|
|
|
<li><a href="https://github.com/blockstack" target="_blank" >GitHub</a></li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
<div>
|
|
<a class="uk-navbar-toggle" uk-search-icon href="#"></a>
|
|
<div class="uk-drop uk-background-default uk-border-rounded" uk-drop="mode: click; pos: left-center; offset: 0">
|
|
<form class="uk-search uk-search-navbar uk-width-1-1" onsubmit="return false;">
|
|
<input id="searchBox" class="uk-search-input" type="search" placeholder="Search..." autofocus>
|
|
</form>
|
|
<ul id="searchBox-results" class="uk-position-absolute uk-width-1-1 uk-list"></ul>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<a class="uk-navbar-toggle uk-hidden@m" href="#offcanvas" data-uk-navbar-toggle-icon data-uk-toggle></a>
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
</nav>
|
|
</div>
|
|
</header>
|
|
|
|
|
|
|
|
|
|
<div class="uk-section">
|
|
<div class="uk-container">
|
|
<div class="uk-grid-large" data-uk-grid>
|
|
|
|
<div class="sidebar-fixed-width uk-visible@m">
|
|
<div class="sidebar-docs uk-position-fixed">
|
|
|
|
<h5>Overview</h5>
|
|
<ul class="uk-nav uk-nav-default doc-nav">
|
|
|
|
|
|
<!-- -->
|
|
|
|
<li class=""><a href="/core/naming/introduction.html">Blockstack Naming Service (BNS)</a></li>
|
|
|
|
|
|
<!-- -->
|
|
|
|
<li class=""><a href="/core/naming/architecture.html">Understand the Architecture</a></li>
|
|
|
|
|
|
<!-- -->
|
|
|
|
<li class=""><a href="/core/naming/namespaces.html">Understand Namespaces</a></li>
|
|
|
|
</ul>
|
|
|
|
<h5>Tutorials</h5>
|
|
<ul class="uk-nav uk-nav-default doc-nav">
|
|
|
|
|
|
<!-- -->
|
|
|
|
<li class=""><a href="/core/naming/tutorial_creation.html">Create and Launch a Namespace</a></li>
|
|
|
|
|
|
<!-- -->
|
|
|
|
<li class=""><a href="/core/naming/tutorial_subdomains.html">Subdomain Design and Implementation</a></li>
|
|
|
|
</ul>
|
|
|
|
<h5>How to use BNS</h5>
|
|
<ul class="uk-nav uk-nav-default doc-nav">
|
|
|
|
|
|
<!-- -->
|
|
|
|
<li class=""><a href="/core/naming/pickname.html">Choose a name</a></li>
|
|
|
|
|
|
<!-- -->
|
|
|
|
<li class=""><a href="/core/naming/creationhowto.html">Creating a Namespace</a></li>
|
|
|
|
|
|
<!-- -->
|
|
|
|
<li class=""><a href="/core/naming/resolving.html">Resolve a name</a></li>
|
|
|
|
|
|
<!-- -->
|
|
|
|
<li class=""><a href="/core/naming/register.html">Register a name</a></li>
|
|
|
|
|
|
<!-- -->
|
|
|
|
<li class=""><a href="/core/naming/manage.html">Manage BNS Names</a></li>
|
|
|
|
|
|
<!-- -->
|
|
|
|
<li class="uk-active"><a href="/core/naming/subdomains.html">BNS Subdomains</a></li>
|
|
|
|
</ul>
|
|
|
|
<h5>Other topics</h5>
|
|
<ul class="uk-nav uk-nav-default doc-nav">
|
|
|
|
|
|
<!-- -->
|
|
|
|
<li class=""><a href="/core/naming/forks.html">BNS Forks</a></li>
|
|
|
|
|
|
<!-- -->
|
|
|
|
<li class=""><a href="/core/naming/did.html">Decentralized Identifiers (DIDs)</a></li>
|
|
|
|
|
|
<!-- -->
|
|
|
|
<li class=""><a href="/core/naming/comparison.html">Naming system feature comparison</a></li>
|
|
|
|
</ul>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div class="uk-width-1-1 uk-width-expand@m">
|
|
|
|
<article class="uk-article">
|
|
|
|
<h1 class="uk-article-title">BNS Subdomains</h1>
|
|
|
|
|
|
|
|
<div class="uk-article-meta uk-margin-top uk-margin-medium-bottom">
|
|
|
|
|
|
|
|
<!-- <img class="avatar avatar-small" alt="Blockstack" width="32" height="32" data-proofer-ignore="true" src="https://avatars2.githubusercontent.com/Blockstack?v=3&s=32" srcset="https://avatars2.githubusercontent.com/Blockstack?v=3&s=32 1x, https://avatars2.githubusercontent.com/Blockstack?v=3&s=64 2x, https://avatars2.githubusercontent.com/Blockstack?v=3&s=96 3x, https://avatars2.githubusercontent.com/Blockstack?v=3&s=128 4x" /> -->
|
|
|
|
|
|
|
|
<!-- Written by <span itemprop="author" itemscope itemtype="http://schema.org/Person"><span itemprop="name">Blockstack</span></span><br> -->
|
|
|
|
|
|
<time datetime="2018-09-08T19:24:57-07:00" itemprop="datePublished">
|
|
|
|
|
|
|
|
<a "target="_blank" href="https://github.com/blockstack/blockstack-core/blob/master/docs/subdomains.md" class="btn btn-default githubEditButton" role="button">
|
|
<span data-uk-icon="icon: pencil; ratio: 1.2"></span> Edit this page on Github</a>
|
|
<span style="font-family:Wingdings">w</span> Sep 8, 2018
|
|
</time>
|
|
|
|
</div>
|
|
|
|
<div class="article-content">
|
|
|
|
<p class="no_toc">This section explains BNS subdomains and provides instructions for methods
|
|
you can use to work with them. The following topics are included:</p>
|
|
|
|
<ul id="markdown-toc">
|
|
<li><a href="#overview-of-subdomains" id="markdown-toc-overview-of-subdomains">Overview of subdomains</a> <ul>
|
|
<li><a href="#subdomain-lifecycle" id="markdown-toc-subdomain-lifecycle">Subdomain Lifecycle</a></li>
|
|
<li><a href="#resolving-subdomains" id="markdown-toc-resolving-subdomains">Resolving Subdomains</a> <ul>
|
|
<li><a href="#look-up-a-subdomains-public-key-and-zone-file-reference" id="markdown-toc-look-up-a-subdomains-public-key-and-zone-file-reference">Look up a subdomain’s public key and zone file (reference)</a></li>
|
|
<li><a href="#look-up-a-subdomains-transaction-history-reference" id="markdown-toc-look-up-a-subdomains-transaction-history-reference">Look up a subdomain’s transaction history (reference)</a></li>
|
|
<li><a href="#look-up-the-list-of-names-and-subdomains-owned-by-a-given-public-key-hash-reference" id="markdown-toc-look-up-the-list-of-names-and-subdomains-owned-by-a-given-public-key-hash-reference">Look up the list of names and subdomains owned by a given public key hash (reference)</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#subdomain-creation-and-management" id="markdown-toc-subdomain-creation-and-management">Subdomain Creation and Management</a></li>
|
|
<li><a href="#subdomain-registrars" id="markdown-toc-subdomain-registrars">Subdomain Registrars</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h1 id="overview-of-subdomains">Overview of subdomains</h1>
|
|
|
|
<p>BNS names are strongly-owned because the owner of its private key can generate
|
|
valid transactions that update its zone file hash and owner. However, this comes at the
|
|
cost of requiring a name owner to pay for the underlying transaction in the
|
|
blockchain. Moreover, this approach limits the rate of BNS name registrations
|
|
and operations to the underlying blockchain’s transaction bandwidth.</p>
|
|
|
|
<p>BNS overcomes this with subdomains. A <strong>BNS subdomain</strong> is a type of BNS name whose state
|
|
and owner are stored outside of the blockchain, but whose existence and
|
|
operation history are anchored to the
|
|
blockchain. In the example table in the <a href="#resolving-bns-names">Resolving BNS
|
|
Names</a> section, the names <code class="highlighter-rouge">cicero.res_publica.id</code> and
|
|
<code class="highlighter-rouge">podsaveamerica.verified.podcast</code> are subdomains.</p>
|
|
|
|
<p>Like their on-chain counterparts, subdomains are globally
|
|
unique, strongly-owned, and human-readable. BNS gives them their own name state
|
|
and public keys.</p>
|
|
|
|
<p>Unlike on-chain names, subdomains can be created and managed
|
|
cheaply, because they are broadcast to the
|
|
BNS network in batches. A single blockchain transaction can send up to 120
|
|
subdomain operations.</p>
|
|
|
|
<p>This is achieved by storing subdomain records in the <a href="atlas_network.md">Atlas Network</a>.
|
|
An on-chain name owner broadcasts subdomain operations by encoding them as
|
|
<code class="highlighter-rouge">TXT</code> records within a DNS zone file. To broadcast the zone file,
|
|
the name owner sets the new zone file hash with a <code class="highlighter-rouge">NAME_UPDATE</code> transaction and
|
|
replicates the zone file via Atlas. This, in turn, replicates all subdomain
|
|
operations it contains, and anchors the set of subdomain operations to
|
|
an on-chain transaction. The BNS node’s consensus rules ensure that only
|
|
valid subdomain operations from <em>valid</em> <code class="highlighter-rouge">NAME_UPDATE</code> transactions will ever be
|
|
stored.</p>
|
|
|
|
<p>For example, the name <code class="highlighter-rouge">verified.podcast</code> once wrote the zone file hash <code class="highlighter-rouge">247121450ca0e9af45e85a82e61cd525cd7ba023</code>,
|
|
which is the hash of the following zone file:</p>
|
|
|
|
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -sL https://core.blockstack.org/v1/names/verified.podcast/zonefile/247121450ca0e9af45e85a82e61cd525cd7ba023 | jq -r <span class="s1">'.zonefile'</span>
|
|
<span class="nv">$ORIGIN</span> verified.podcast
|
|
<span class="nv">$TTL</span> 3600
|
|
1yeardaily TXT <span class="s2">"owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH"</span> <span class="s2">"seqn=0"</span> <span class="s2">"parts=1"</span> <span class="s2">"zf0=JE9SSUdJTiAxeWVhcmRhaWx5CiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMXllYXJkYWlseS9oZWFkLmpzb24iCg=="</span>
|
|
2dopequeens TXT <span class="s2">"owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH"</span> <span class="s2">"seqn=0"</span> <span class="s2">"parts=1"</span> <span class="s2">"zf0=JE9SSUdJTiAyZG9wZXF1ZWVucwokVFRMIDM2MDAKX2h0dHAuX3RjcCBVUkkgMTAgMSAiaHR0cHM6Ly9waC5kb3Rwb2RjYXN0LmNvLzJkb3BlcXVlZW5zL2hlYWQuanNvbiIK"</span>
|
|
10happier TXT <span class="s2">"owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH"</span> <span class="s2">"seqn=0"</span> <span class="s2">"parts=1"</span> <span class="s2">"zf0=JE9SSUdJTiAxMGhhcHBpZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMGhhcHBpZXIvaGVhZC5qc29uIgo="</span>
|
|
31thoughts TXT <span class="s2">"owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH"</span> <span class="s2">"seqn=0"</span> <span class="s2">"parts=1"</span> <span class="s2">"zf0=JE9SSUdJTiAzMXRob3VnaHRzCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzF0aG91Z2h0cy9oZWFkLmpzb24iCg=="</span>
|
|
359 TXT <span class="s2">"owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH"</span> <span class="s2">"seqn=0"</span> <span class="s2">"parts=1"</span> <span class="s2">"zf0=JE9SSUdJTiAzNTkKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8zNTkvaGVhZC5qc29uIgo="</span>
|
|
30for30 TXT <span class="s2">"owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH"</span> <span class="s2">"seqn=0"</span> <span class="s2">"parts=1"</span> <span class="s2">"zf0=JE9SSUdJTiAzMGZvcjMwCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzBmb3IzMC9oZWFkLmpzb24iCg=="</span>
|
|
onea TXT <span class="s2">"owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH"</span> <span class="s2">"seqn=0"</span> <span class="s2">"parts=1"</span> <span class="s2">"zf0=JE9SSUdJTiBvbmVhCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vb25lYS9oZWFkLmpzb24iCg=="</span>
|
|
10minuteteacher TXT <span class="s2">"owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH"</span> <span class="s2">"seqn=0"</span> <span class="s2">"parts=1"</span> <span class="s2">"zf0=JE9SSUdJTiAxMG1pbnV0ZXRlYWNoZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMG1pbnV0ZXRlYWNoZXIvaGVhZC5qc29uIgo="</span>
|
|
36questionsthepodcastmusical TXT <span class="s2">"owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH"</span> <span class="s2">"seqn=0"</span> <span class="s2">"parts=1"</span> <span class="s2">"zf0=JE9SSUdJTiAzNnF1ZXN0aW9uc3RoZXBvZGNhc3RtdXNpY2FsCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzZxdWVzdGlvbnN0aGVwb2RjYXN0bXVzaWNhbC9oZWFkLmpzb24iCg=="</span>
|
|
_http._tcp URI 10 1 <span class="s2">"https://dotpodcast.co/"</span>
|
|
</code></pre>
|
|
</div>
|
|
|
|
<p>Each <code class="highlighter-rouge">TXT</code> record in this zone file encodes a subdomain-creation.
|
|
For example, <code class="highlighter-rouge">1yeardaily.verified.podcast</code> resolves to:</p>
|
|
|
|
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl https://core.blockstack.org/v1/names/1yeardaily.verified.podcast
|
|
<span class="o">{</span>
|
|
<span class="s2">"address"</span>: <span class="s2">"1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH"</span>,
|
|
<span class="s2">"blockchain"</span>: <span class="s2">"bitcoin"</span>,
|
|
<span class="s2">"last_txid"</span>: <span class="s2">"d87a22ebab3455b7399bfef8a41791935f94bc97aee55967edd5a87f22cce339"</span>,
|
|
<span class="s2">"status"</span>: <span class="s2">"registered_subdomain"</span>,
|
|
<span class="s2">"zonefile_hash"</span>: <span class="s2">"e7acc97fd42c48ed94fd4d41f674eddbee5557e3"</span>,
|
|
<span class="s2">"zonefile_txt"</span>: <span class="s2">"</span><span class="nv">$ORIGIN</span><span class="s2"> 1yeardaily</span><span class="se">\n</span><span class="nv">$TTL</span><span class="s2"> 3600</span><span class="se">\n</span><span class="s2">_http._tcp URI 10 1 </span><span class="se">\"</span><span class="s2">https://ph.dotpodcast.co/1yeardaily/head.json</span><span class="se">\"\n</span><span class="s2">"</span>
|
|
<span class="o">}</span>
|
|
</code></pre>
|
|
</div>
|
|
|
|
<p>This information was extracted from the <code class="highlighter-rouge">1yeardaily</code> <code class="highlighter-rouge">TXT</code> resource record in the zone
|
|
file for <code class="highlighter-rouge">verified.podcast</code>.</p>
|
|
|
|
<h2 id="subdomain-lifecycle">Subdomain Lifecycle</h2>
|
|
|
|
<p>Note that <code class="highlighter-rouge">1yeardaily.verified.podcast</code> has a different public key
|
|
hash (address) than <code class="highlighter-rouge">verified.podcast</code>. A BNS node will only process a
|
|
subsequent subdomain operation on <code class="highlighter-rouge">1yeardaily.verified.podcast</code> if it includes a
|
|
signature from this address’s private key. <code class="highlighter-rouge">verified.podcast</code> cannot generate
|
|
updates; only the owner of <code class="highlighter-rouge">1yeardaily.verified.podcast can do so</code>.</p>
|
|
|
|
<p>The lifecycle of a subdomain and its operations is shown in Figure 2.</p>
|
|
|
|
<div class="highlighter-rouge"><pre class="highlight"><code> subdomain subdomain subdomain
|
|
creation update transfer
|
|
+----------------+ +----------------+ +----------------+
|
|
| cicero | | cicero | | cicero |
|
|
| owner="1Et..." | signed | owner="1Et..." | signed | owner="1cJ..." |
|
|
| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ...
|
|
| seqn=0 | | seqn=1 | | seqn=2 |
|
|
| | | sig="xxxx" | | sig="xxxx" |
|
|
+----------------+ +----------------+ +----------------+
|
|
| | |
|
|
| off-chain | |
|
|
~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ...
|
|
| on-chain | |
|
|
V V (zone file hash ) V
|
|
+----------------+ +----------------+ +----------------+
|
|
| res_publica.id | | jude.id | | res_publica.id |
|
|
| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ...
|
|
+----------------+ +----------------+ +----------------+
|
|
blockchain blockchain blockchain
|
|
block block block
|
|
|
|
|
|
Figure 2: Subdomain lifetime with respect to on-chain name operations. A new
|
|
subdomain operation will only be accepted if it has a later "sequence=" number,
|
|
and a valid signature in "sig=" over the transaction body. The "sig=" field
|
|
includes both the public key and signature, and the public key must hash to
|
|
the previous subdomain operation's "addr=" field.
|
|
|
|
Thesubdomain-creation and subdomain-transfer transactions for
|
|
"cicero.res_publica.id" are broadcast by the owner of "res_publica.id".
|
|
However, any on-chain name ("jude.id" in this case) can broadcast a subdomain
|
|
update for "cicero.res_publica.id".
|
|
</code></pre>
|
|
</div>
|
|
|
|
<p>Subdomain operations are ordered by sequence number, starting at 0. Each new
|
|
subdomain operation must include:</p>
|
|
|
|
<ul>
|
|
<li>The next sequence number</li>
|
|
<li>The public key that hashes to the previous subdomain transaction’s address</li>
|
|
<li>A signature from the corresponding private key over the entire subdomain
|
|
operation.</li>
|
|
</ul>
|
|
|
|
<p>If two correctly-signed but conflicting subdomain operations are discovered
|
|
(i.e. they have the same sequence number), the one that occurs earlier in the
|
|
blockchain’s history is accepted. Invalid subdomain operations are ignored.</p>
|
|
|
|
<p>Combined, this ensures that a BNS node with all of the zone files with a given
|
|
subdomain’s operations will be able to determine the valid sequence of
|
|
state-transitions it has undergone, and determine the current zone file and public
|
|
key hash for the subdomain.</p>
|
|
|
|
<h2 id="resolving-subdomains">Resolving Subdomains</h2>
|
|
|
|
<p>Developers interact with subdomains the same way they interact with names.
|
|
Using the BNS API, a developer can:</p>
|
|
|
|
<h3 id="look-up-a-subdomains-public-key-and-zone-file-reference">Look up a subdomain’s public key and zone file (<a href="https://core.blockstack.org/#name-querying-get-name-info">reference</a>)</h3>
|
|
|
|
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl https://core.blockstack.org/v1/names/aaron.personal.id
|
|
<span class="o">{</span>
|
|
<span class="s2">"address"</span>: <span class="s2">"1PwztPFd1s2STMv4Ntq6UPBdYgHSBr5pdF"</span>,
|
|
<span class="s2">"blockchain"</span>: <span class="s2">"bitcoin"</span>,
|
|
<span class="s2">"last_txid"</span>: <span class="s2">"85e8273b0a38d3e9f0af7b4b72faf0907de9f4616afc101caac13e7bbc832394"</span>,
|
|
<span class="s2">"status"</span>: <span class="s2">"registered_subdomain"</span>,
|
|
<span class="s2">"zonefile_hash"</span>: <span class="s2">"a6dda6b74ffecf85f4a162627d8df59577243813"</span>,
|
|
<span class="s2">"zonefile_txt"</span>: <span class="s2">"</span><span class="nv">$ORIGIN</span><span class="s2"> aaron.personal.id</span><span class="se">\n</span><span class="nv">$TTL</span><span class="s2"> 3600</span><span class="se">\n</span><span class="s2">_https._tcp URI 10 1 </span><span class="se">\"</span><span class="s2">https://gaia.blockstack.org/hub/1PwztPFd1s2STMv4Ntq6UPBdYgHSBr5pdF/profile.json</span><span class="se">\"\n</span><span class="s2">"</span>
|
|
<span class="o">}</span>
|
|
</code></pre>
|
|
</div>
|
|
|
|
<h3 id="look-up-a-subdomains-transaction-history-reference">Look up a subdomain’s transaction history (<a href="https://core.blockstack.org/#name-querying-name-history">reference</a>)</h3>
|
|
|
|
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl https://core.blockstack.org/v1/names/aaron.personal.id/history
|
|
<span class="o">{</span>
|
|
<span class="s2">"509981"</span>: <span class="o">[</span>
|
|
<span class="o">{</span>
|
|
<span class="s2">"address"</span>: <span class="s2">"1PwztPFd1s2STMv4Ntq6UPBdYgHSBr5pdF"</span>,
|
|
<span class="s2">"block_number"</span>: 509981,
|
|
<span class="s2">"domain"</span>: <span class="s2">"personal.id"</span>,
|
|
<span class="s2">"name"</span>: <span class="s2">"aaron.personal.id"</span>,
|
|
<span class="s2">"sequence"</span>: 0,
|
|
<span class="s2">"txid"</span>: <span class="s2">"85e8273b0a38d3e9f0af7b4b72faf0907de9f4616afc101caac13e7bbc832394"</span>,
|
|
<span class="s2">"value_hash"</span>: <span class="s2">"a6dda6b74ffecf85f4a162627d8df59577243813"</span>,
|
|
<span class="s2">"zonefile"</span>: <span class="s2">"JE9SSUdJTiBhYXJvbi5wZXJzb25hbC5pZAokVFRMIDM2MDAKX2h0dHBzLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vZ2FpYS5ibG9ja3N0YWNrLm9yZy9odWIvMVB3enRQRmQxczJTVE12NE50cTZVUEJkWWdIU0JyNXBkRi9wcm9maWxlLmpzb24iCg=="</span>
|
|
<span class="o">}</span>
|
|
<span class="o">]</span>
|
|
<span class="o">}</span>
|
|
</code></pre>
|
|
</div>
|
|
|
|
<h3 id="look-up-the-list-of-names-and-subdomains-owned-by-a-given-public-key-hash-reference">Look up the list of names and subdomains owned by a given public key hash (<a href="https://core.blockstack.org/#name-querying-get-names-owned-by-address">reference</a>)</h3>
|
|
|
|
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl https://core.blockstack.org/v1/addresses/bitcoin/1PwztPFd1s2STMv4Ntq6UPBdYgHSBr5pdF
|
|
<span class="o">{</span>
|
|
<span class="s2">"names"</span>: <span class="o">[</span>
|
|
<span class="s2">"aaron.personal.id"</span>
|
|
<span class="o">]</span>
|
|
<span class="o">}</span>
|
|
</code></pre>
|
|
</div>
|
|
|
|
<h2 id="subdomain-creation-and-management">Subdomain Creation and Management</h2>
|
|
|
|
<p>Unlike an on-chain name, a subdomain owner needs an on-chain name owner’s help
|
|
to broadcast their subdomain operations. In particular:</p>
|
|
<ul>
|
|
<li>A subdomain-creation transaction can only be processed by the owner of the on-chain
|
|
name that shares its suffix. For example, only the owner of <code class="highlighter-rouge">res_publica.id</code>
|
|
can broadcast subdomain-creation transactions for subdomain names ending in
|
|
<code class="highlighter-rouge">.res_publica.id</code>.</li>
|
|
<li>A subdomain-transfer transaction can only be broadcast by the owner of the
|
|
on-chain name that created it. For example, the owner of
|
|
<code class="highlighter-rouge">cicero.res_publica.id</code> needs the owner of <code class="highlighter-rouge">res_publica.id</code> to broadcast a
|
|
subdomain-transfer transaction to change <code class="highlighter-rouge">cicero.res_publica.id</code>’s public key.</li>
|
|
<li>In order to send a subdomain-creation or subdomain-transfer, all
|
|
of an on-chain name owner’s zone files must be present in the Atlas network.
|
|
This lets the BNS node prove the <em>absence</em> of any conflicting subdomain-creation and
|
|
subdomain-transfer operations when processing new zone files.</li>
|
|
<li>A subdomain update transaction can be broadcast by <em>any</em> on-chain name owner,
|
|
but the subdomain owner needs to find one who will cooperate. For example,
|
|
the owner of <code class="highlighter-rouge">verified.podcast</code> can broadcast a subdomain-update transaction
|
|
created by the owner of <code class="highlighter-rouge">cicero.res_publica.id</code>.</li>
|
|
</ul>
|
|
|
|
<p>That said, to create a subdomain, the subdomain owner generates a
|
|
subdomain-creation operation for their desired name
|
|
and gives it to the on-chain name owner.
|
|
The on-chain name owner then uses Atlas to
|
|
broadcast it to all other BNS nodes.</p>
|
|
|
|
<p>Once created, a subdomain owner can use any on-chain name owner to broadcast a
|
|
subdomain-update operation. To do so, they generate and sign the requisite
|
|
subdomain operation and give it to an on-chain name owner, who then packages it
|
|
with other subdomain operations into a DNS zone file
|
|
and sends them all out on the Atlas network.</p>
|
|
|
|
<p>If the subdomain owner wants to change the address of their subdomain, they need
|
|
to sign a subdomain-transfer operation and give it to the on-chain name owner
|
|
who created the subdomain. They then package it into a zone file and broadcast
|
|
it.</p>
|
|
|
|
<h2 id="subdomain-registrars">Subdomain Registrars</h2>
|
|
|
|
<p>Because subdomain names are cheap, developers may be inclined to run
|
|
subdomain registrars on behalf of their applications. For example,
|
|
the name <code class="highlighter-rouge">personal.id</code> is used to register Blockstack application users without
|
|
requiring them to spend any Bitcoin.</p>
|
|
|
|
<p>We supply a reference
|
|
implementation of a <a href="https://github.com/blockstack/subdomain-registrar">BNS Subdomain Registrar</a>
|
|
to help developers broadcast subdomain operations. Users would still own their
|
|
subdomain names; the registrar simply gives developers a convenient way for them
|
|
to register and manage them in the context of a particular application.
|
|
Please see the <a href="subdomains.md">tutorial on running a subdomain registrar</a> for
|
|
details on how to use it.</p>
|
|
|
|
<div class="share uk-text-center">
|
|
<a href="https://twitter.com/intent/tweet?text=BNS Subdomains&url=https://zbabystack.netlify.com/core/naming/subdomains.html&via=&related=" rel="nofollow" target="_blank" title="Share on Twitter" onclick="window.open(this.href, 'twitter', 'width=550,height=235');return false;"><span data-uk-icon="icon: twitter; ratio: 1.2"></span></a>
|
|
<a class="uk-margin-small-left" href="https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fzbabystack.netlify.com%2Fcore%2Fnaming%2Fsubdomains.html" rel="nofollow" target="_blank" title="Share on Facebook" onclick="window.open(this.href, 'facebook-share','width=580,height=296');return false;"><span data-uk-icon="icon: facebook; ratio: 1.2"></span></a>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<hr class="uk-margin-medium">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="uk-margin-large-top">
|
|
<h3>Related Articles</h3>
|
|
|
|
|
|
|
|
|
|
|
|
<ul class="uk-list">
|
|
|
|
</ul>
|
|
</div>
|
|
|
|
|
|
|
|
</article>
|
|
|
|
<script>
|
|
// Table of contents scroll to
|
|
UIkit.scroll('#markdown-toc a', {
|
|
duration: 400,
|
|
offset: 120
|
|
});
|
|
</script>
|
|
|
|
</div>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<div id="offcanvas" data-uk-offcanvas="flip: true; overlay: true">
|
|
<div class="uk-offcanvas-bar">
|
|
|
|
<button class="uk-offcanvas-close" type="button" data-uk-close></button>
|
|
|
|
<ul class="uk-nav uk-nav-default">
|
|
<!-- <li><a class="uk-logo uk-margin-small-bottom" href="/"><img src="https://zbabystack.netlify.com/assets/posts/logo.png" alt="Docs"></a></li> -->
|
|
<li><a class="uk-logo uk-margin-small-bottom" href="/"><img src="/assets/posts/logo.png" alt="Docs"></a></li>
|
|
|
|
|
|
<li><a href="https://blockstack.org" target="_blank" >Blockstack.org</a></li>
|
|
|
|
|
|
<li><a href="https://forum.blockstack.org/" target="_blank" >Forums</a></li>
|
|
|
|
|
|
<li><a href="https://github.com/blockstack" target="_blank" >GitHub</a></li>
|
|
|
|
</ul>
|
|
|
|
<div class="uk-margin-small-top uk-text-center uk-text-muted uk-link-muted">
|
|
<div data-uk-grid class="uk-child-width-auto uk-grid-small uk-flex-center uk-grid">
|
|
|
|
<div class="uk-first-column">
|
|
<a href="https://twitter.com/" data-uk-icon="icon: twitter" class="uk-icon-link uk-icon" target="_blank"></a>
|
|
</div>
|
|
|
|
|
|
<div>
|
|
<a href="https://www.facebook.com/" data-uk-icon="icon: facebook" class="uk-icon-link uk-icon" target="_blank"></a>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div>
|
|
<a href="https://www.instagram.com/" data-uk-icon="icon: instagram" class="uk-icon-link uk-icon" target="_blank"></a>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
<div>
|
|
<a href="https://vimeo.com/" data-uk-icon="icon: vimeo" class="uk-icon-link uk-icon" target="_blank"></a>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
<footer class="uk-section uk-text-center uk-text-muted uk-link-muted">
|
|
<div class="uk-container uk-container-small">
|
|
|
|
<!-- <div>
|
|
<ul class="uk-subnav uk-flex-center">
|
|
|
|
|
|
|
|
|
|
<li><a href="https://blockstack.org" target="_blank" >Blockstack.org</a></li>
|
|
|
|
|
|
|
|
|
|
|
|
<li><a href="https://forum.blockstack.org/" target="_blank" >Forums</a></li>
|
|
|
|
|
|
|
|
|
|
|
|
<li><a href="https://github.com/blockstack" target="_blank" >GitHub</a></li>
|
|
|
|
|
|
</ul>
|
|
</div>
|
|
<div class="uk-margin-medium">
|
|
<div data-uk-grid class="uk-child-width-auto uk-grid-small uk-flex-center uk-grid">
|
|
|
|
<div class="uk-first-column">
|
|
<a href="https://twitter.com/" data-uk-icon="icon: twitter" class="uk-icon-link uk-icon" target="_blank"></a>
|
|
</div>
|
|
|
|
|
|
<div>
|
|
<a href="https://www.facebook.com/" data-uk-icon="icon: facebook" class="uk-icon-link uk-icon" target="_blank"></a>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div>
|
|
<a href="https://www.instagram.com/" data-uk-icon="icon: instagram" class="uk-icon-link uk-icon" target="_blank"></a>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
<div>
|
|
<a href="https://vimeo.com/" data-uk-icon="icon: vimeo" class="uk-icon-link uk-icon" target="_blank"></a>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</div>
|
|
</div> -->
|
|
<div class="uk-margin-medium uk-text-small copyright">© 2018 Blockstack</div>
|
|
|
|
</div>
|
|
</footer>
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
/* Create a configuration object */
|
|
var ss360Config = {
|
|
/* Your site id */
|
|
siteId: 'blockstack',
|
|
/* A CSS selector that points to your search box */
|
|
searchBox: {selector: '#searchBox'}
|
|
};
|
|
</script>
|
|
<script src="https://cdn.sitesearch360.com/sitesearch360-v11.min.js" async></script>
|
|
|
|
|
|
|
|
</body>
|
|
|
|
</html>
|
|
|