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.
 
 

473 lines
23 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>How to Use the Atlas Network | Blockstack</title>
<meta name="generator" content="Jekyll v3.8.3" />
<meta property="og:title" content="How to Use the Atlas Network" />
<meta name="author" content="Blockstack" />
<meta property="og:locale" content="en_US" />
<meta name="description" content="How to Use the Atlas Network" />
<meta property="og:description" content="How to Use the Atlas Network" />
<link rel="canonical" href="https://zbabystack.netlify.com/core/atlas/howtouse.html" />
<meta property="og:url" content="https://zbabystack.netlify.com/core/atlas/howtouse.html" />
<meta property="og:site_name" content="Blockstack" />
<meta property="og:type" content="article" />
<meta property="article:published_time" content="2018-09-10T15:18:11-07:00" />
<script type="application/ld+json">
{"description":"How to Use the Atlas Network","author":{"@type":"Person","name":"Blockstack"},"@type":"BlogPosting","url":"https://zbabystack.netlify.com/core/atlas/howtouse.html","headline":"How to Use the Atlas Network","dateModified":"2018-09-10T15:18:11-07:00","datePublished":"2018-09-10T15:18:11-07:00","mainEntityOfPage":{"@type":"WebPage","@id":"https://zbabystack.netlify.com/core/atlas/howtouse.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">
<!-- -->
<ul class="uk-nav uk-nav-default doc-nav">
<!-- -->
<li class=""><a href="/core/atlas/overview.html">Overview of the Atlas network</a></li>
<!-- -->
<li class=""><a href="/core/atlas/howitworks.html">How Atlas Works</a></li>
<!-- -->
<li class="uk-active"><a href="/core/atlas/howtouse.html">How to Use the Atlas Network</a></li>
</ul>
<!-- -->
</div>
</div>
<div class="uk-width-1-1 uk-width-expand@m">
<article class="uk-article">
<h1 class="uk-article-title">How to Use the Atlas Network</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-10T15:18:11-07:00" itemprop="datePublished">
<a "target="_blank" href="https://github.com/blockstack/blockstack-core/blob/master/docs/howtouse.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">&#119;</span> Sep 10, 2018
</time>
</div>
<div class="article-content">
<p class="no_toc">This section teaches you how to use the Atlas network, it contains the
following sections:</p>
<ul id="markdown-toc">
<li><a href="#the-api" id="markdown-toc-the-api">The API</a></li>
<li><a href="#looking-up-chunks" id="markdown-toc-looking-up-chunks">Looking up Chunks</a></li>
<li><a href="#adding-a-new-chunk" id="markdown-toc-adding-a-new-chunk">Adding a New Chunk</a></li>
<li><a href="#propagating-chunks" id="markdown-toc-propagating-chunks">Propagating Chunks</a></li>
</ul>
<h2 id="the-api">The API</h2>
<p>While the Blockstack software stack expects that Atlas-hosted data is made up of
DNS zone files, Atlas itself does not enforce this (nor does it care about the
format of its chunks). It is designed as a general-purpose chunk store.
Nevertheless, the ubiquitous use of Atlas to store data as DNS zone files has
had an influence on its API design—fields and method names frequently allude
to zone files and zone file hashes. This is intentional.</p>
<p>The <a href="https://core.blockstack.org">public BNS API endpoint</a> does not support
resolving Atlas chunks that do not encode Gaia routing information or subdomain
information. To directly interact with Atlas, developers will need to install
<a href="https://github.com/blockstack/blockstack-core">Blockstack Core</a> and use its
Python client libraries for these examples.</p>
<h2 id="looking-up-chunks">Looking up Chunks</h2>
<p>All Atlas chunks are addressed by the RIPEMD160 hash of the SHA256 hash of the
chunk data. A client can query up to 100 chunks in one RPC call.</p>
<p>A client can look up a chunk with the <code class="highlighter-rouge">get_zonefiles()</code> method. If successful,
the returned payload will be a <code class="highlighter-rouge">dict</code> with a <code class="highlighter-rouge">zonefiles</code> key that maps the chunk
hashes to their respective data.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">blockstack</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">data</span> <span class="o">=</span> <span class="n">blockstack</span><span class="o">.</span><span class="n">lib</span><span class="o">.</span><span class="n">client</span><span class="o">.</span><span class="n">get_zonefiles</span><span class="p">(</span><span class="s">'https://node.blockstack.org:6263'</span><span class="p">,</span> <span class="p">[</span><span class="s">'1b89a685f4c4ea245ce9433d0b29166c22175ab4'</span><span class="p">])</span>
<span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> <span class="n">data</span><span class="p">[</span><span class="s">'zonefiles'</span><span class="p">][</span><span class="s">'1b89a685f4c4ea245ce9433d0b29166c22175ab4'</span><span class="p">]</span>
<span class="err">$</span><span class="n">ORIGIN</span> <span class="n">duckduckgo_tor</span><span class="o">.</span><span class="nb">id</span>
<span class="err">$</span><span class="n">TTL</span> <span class="mi">3600</span>
<span class="n">tor</span> <span class="n">TXT</span> <span class="s">"3g2upl4pq6kufc4m.onion"</span>
<span class="o">&gt;&gt;&gt;</span>
</code></pre>
</div>
<p>(This particular chunk happens to be associated with the BNS name
<code class="highlighter-rouge">duckduckgo_tor.id</code>).</p>
<h2 id="adding-a-new-chunk">Adding a New Chunk</h2>
<p>The only way to add a chunk to Atlas is to do so through an on-chain name in
BNS. Adding a new chunk is a two-step process:</p>
<ul>
<li>The name owner announces the chunk hash as a name’s state
via a <code class="highlighter-rouge">NAME_REGISTRATION</code>, <code class="highlighter-rouge">NAME_UPDATE</code>, <code class="highlighter-rouge">NAME_RENEWAL</code>, or <code class="highlighter-rouge">NAME_IMPORT</code> transaction.</li>
<li>Once the transaction is confirmed and processed by BNS, the name owner
broadcasts the matching zone file.</li>
</ul>
<p>Setting a name’s state to be the hash of a chunk is beyond the scope of this
document, since it needs to be done through a BNS client.
See the relevant documentation for
<a href="https://github.com/blockstack/blockstack.js">blockstack.js</a> and the <a href="https://github.com/blockstack/blockstack-browser">Blockstack
Browser</a> for doing this.</p>
<p>Once the name operation is confirmed, you can announce the data to the
Atlas network. You can do so with the Python client as follows:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">blockstack</span>
<span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">base64</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">data</span> <span class="o">=</span> <span class="s">"..."</span> <span class="c"># this is the chunk data you will announce</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">data_b64</span> <span class="o">=</span> <span class="n">base64</span><span class="o">.</span><span class="n">b64encode</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">result</span> <span class="o">=</span> <span class="n">blockstack</span><span class="o">.</span><span class="n">lib</span><span class="o">.</span><span class="n">client</span><span class="o">.</span><span class="n">put_zonefiles</span><span class="p">(</span><span class="s">'https://node.blockstack.org:6263'</span><span class="p">,</span> <span class="p">[</span><span class="n">data_b64</span><span class="p">])</span>
<span class="o">&gt;&gt;&gt;</span> <span class="k">assert</span> <span class="n">result</span><span class="p">[</span><span class="s">'saved'</span><span class="p">][</span><span class="mi">0</span><span class="p">]</span> <span class="o">==</span> <span class="mi">1</span>
<span class="o">&gt;&gt;&gt;</span>
</code></pre>
</div>
<p>At most five chunks can be announced in one RPC call.
Note that the data must be base64-encoded before it can be announced.</p>
<p>When the <code class="highlighter-rouge">put_zonefiles()</code> method succeeds, it returns a <code class="highlighter-rouge">dict</code> with a list
under the <code class="highlighter-rouge">saved</code> key. Here, <code class="highlighter-rouge">result['saved'][i]</code> will be 1 if the <code class="highlighter-rouge">i</code>th
chunk given to <code class="highlighter-rouge">put_zonefiles()</code> was saved by the node, and 0 if not.
The node will not save a chunk if it is too big, or if it has not yet processed
the name operation that contained the chunk’s hash.</p>
<p>The <code class="highlighter-rouge">put_zonefiles()</code> method is idempotent.</p>
<h2 id="propagating-chunks">Propagating Chunks</h2>
<p>Atlas peers will each store a copy of the chunks you announce. In the
background, they will asynchronously announce to one another which chunks they
have available, and replicate them to one another in a rarest-first order (much
like how BitTorrent works). Eventually, every Atlas peer will receive the
chunk.</p>
<p>However, developers can accelerate this process by eagerly propagating chunks.
To do so, they can ask an Atlas peer for its immediate neighbors in the Atlas
peer graph, and replicate the chunk to each of them as well.</p>
<p>For example, this code will replicate the chunk to not only
<code class="highlighter-rouge">https://node.blockstack.org:6263</code>, but also to its immediate neighbors.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">blockstack</span>
<span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">base64</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">data</span> <span class="o">=</span> <span class="s">"..."</span> <span class="c"># this is the chunk you will replicate widely</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">data_b64</span> <span class="o">=</span> <span class="n">base64</span><span class="o">.</span><span class="n">b64encode</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="o">&gt;&gt;&gt;</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">result</span> <span class="o">=</span> <span class="n">blockstack</span><span class="o">.</span><span class="n">lib</span><span class="o">.</span><span class="n">client</span><span class="o">.</span><span class="n">get_atlas_peers</span><span class="p">(</span><span class="s">'https://node.blockstack.org:6263'</span><span class="p">)</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">neighbors</span> <span class="o">=</span> <span class="n">result</span><span class="p">[</span><span class="s">'peers'</span><span class="p">]</span>
<span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> <span class="s">", "</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">neighbors</span><span class="p">)</span>
<span class="mf">13.65</span><span class="o">.</span><span class="mf">207.163</span><span class="p">:</span><span class="mi">6264</span><span class="p">,</span> <span class="mf">52.225</span><span class="o">.</span><span class="mf">128.191</span><span class="p">:</span><span class="mi">6264</span><span class="p">,</span> <span class="n">node</span><span class="o">.</span><span class="n">blockstack</span><span class="o">.</span><span class="n">org</span><span class="p">:</span><span class="mi">6264</span><span class="p">,</span> <span class="mf">23.102</span><span class="o">.</span><span class="mf">162.7</span><span class="p">:</span><span class="mi">6264</span><span class="p">,</span> <span class="mf">52.167</span><span class="o">.</span><span class="mf">230.235</span><span class="p">:</span><span class="mi">6264</span><span class="p">,</span> <span class="mf">23.102</span><span class="o">.</span><span class="mf">162.124</span><span class="p">:</span><span class="mi">6264</span><span class="p">,</span> <span class="mf">52.151</span><span class="o">.</span><span class="mf">59.26</span><span class="p">:</span><span class="mi">6264</span><span class="p">,</span> <span class="mf">13.92</span><span class="o">.</span><span class="mf">134.106</span><span class="p">:</span><span class="mi">6264</span>
<span class="o">&gt;&gt;&gt;</span>
<span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">neighbor</span> <span class="ow">in</span> <span class="n">neighbors</span><span class="p">:</span>
<span class="o">...</span> <span class="n">result</span> <span class="o">=</span> <span class="n">blockstack</span><span class="o">.</span><span class="n">lib</span><span class="o">.</span><span class="n">client</span><span class="o">.</span><span class="n">put_zonefiles</span><span class="p">(</span><span class="n">neighbor</span><span class="p">,</span> <span class="p">[</span><span class="n">data_b64</span><span class="p">])</span>
<span class="o">...</span> <span class="k">assert</span> <span class="n">result</span><span class="p">[</span><span class="s">'saved'</span><span class="p">][</span><span class="mi">0</span><span class="p">]</span> <span class="o">==</span> <span class="mi">1</span>
<span class="o">...</span>
<span class="o">&gt;&gt;&gt;</span>
</code></pre>
</div>
<p>This is not strictly necessary, but it does help accelerate chunk replication
and makes it less likely that a chunk will get lost due to individual node
failures.</p>
<div class="share uk-text-center">
<a href="https://twitter.com/intent/tweet?text=How to Use the Atlas Network&url=https://zbabystack.netlify.com/core/atlas/howtouse.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%2Fatlas%2Fhowtouse.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">&copy; 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>