{"url":"https://docs.blockstack.org/core/atlas/howtouse.html","headline":"How to Use the Atlas Network","dateModified":"2018-10-26T14:14:34-07:00","datePublished":"2018-10-26T14:14:34-07:00","mainEntityOfPage":{"@type":"WebPage","@id":"https://docs.blockstack.org/core/atlas/howtouse.html"},"author":{"@type":"Person","name":"Blockstack"},"description":"How to Use the Atlas Network","@type":"BlogPosting","@context":"http://schema.org"}</script>
<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 <ahref="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
<ahref="https://github.com/blockstack/blockstack-core">Blockstack Core</a> and use its
Python client libraries for these examples.</p>
<h2id="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 <codeclass="highlighter-rouge">get_zonefiles()</code> method. If successful,
the returned payload will be a <codeclass="highlighter-rouge">dict</code> with a <codeclass="highlighter-rouge">zonefiles</code> key that maps the chunk
<h2id="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 <codeclass="highlighter-rouge">NAME_REGISTRATION</code>, <codeclass="highlighter-rouge">NAME_UPDATE</code>, <codeclass="highlighter-rouge">NAME_RENEWAL</code>, or <codeclass="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
<ahref="https://github.com/blockstack/blockstack.js">blockstack.js</a> and the <ahref="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>
<spanclass="o">>>></span><spanclass="n">data</span><spanclass="o">=</span><spanclass="s">"..."</span><spanclass="c"># this is the chunk data you will announce</span>
<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 <codeclass="highlighter-rouge">put_zonefiles()</code> method succeeds, it returns a <codeclass="highlighter-rouge">dict</code> with a list
under the <codeclass="highlighter-rouge">saved</code> key. Here, <codeclass="highlighter-rouge">result['saved'][i]</code> will be 1 if the <codeclass="highlighter-rouge">i</code>th
chunk given to <codeclass="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 <codeclass="highlighter-rouge">put_zonefiles()</code> method is idempotent.</p>
<spanclass="o">>>></span><spanclass="n">data</span><spanclass="o">=</span><spanclass="s">"..."</span><spanclass="c"># this is the chunk you will replicate widely</span>
<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>
<divclass="share uk-text-center">
<ahref="https://twitter.com/intent/tweet?text=How to Use the Atlas Network&url=https://docs.blockstack.org/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;"><spandata-uk-icon="icon: twitter; ratio: 1.2"></span></a>
/* A CSS selector that points to your search box */
searchBox: {
selector: '#searchBox'
},
results: {
embedConfig: undefined, // {'url':undefined,'contentBlock':'.page-content-body'}, // if url is given the page will change to that URL and look for the content block there to insert the results
fullScreenConfig: undefined, // {trigger: '#ss360-search-trigger', caption: 'Search this site'}, trigger is the CSS selector to the element that starts the search full screen overlay and searchCaption the caption on the full screen search page
caption: 'Found #COUNT# search results for \"#QUERY#\"', // the caption of the search results
group: true, // whether results should be grouped if content groups are available
filters: undefined,
num: 96, // the maximum number of search results to be shown
highlightQueryTerms: true, // whether to highlight the query terms in search results
moreResultsButton: "Show more results", // HTML for the more results button, all results will be shown if this is null
noResultsText: 'Sorry, we have not found any matches for your query.', // the text to show when there are no results
queryCorrectionText: 'Did you mean "#CORRECTION#"?',
searchQueryParamName: 'ss360Query', // the name of the search query parameter
linksOpenNewTab: false, // should clicking on the result links open a new tab/window?
showSearchBoxLayover: true, //whether to show search box in search result layover
moreResultsPagingSize: 12, // the number of new results to show each time the more results button is pressed (max: 24)
orderByRelevanceText: "Relevance" // the text to be shown in order select box to describe 'order by relevance' option
},
suggestions: {
show: true, // whether to show search suggestions
maxQuerySuggestions: 3, // the maximum number of query suggestions
querySuggestionHeadline: undefined, // the headline of the query suggestions, leave blank if no headline should be shown
emptyQuerySuggestions: undefined,
showImages: false, // show images in search suggestions
num: 6, // the maximum number of search suggestions to be shown
minChars: 3, // minimum number of characters before the suggestions shows, default: 3,
maxWidth: 'auto', // the maximum width of the suggest box, default: as wide as the input box, at least 275px
throttleTime: 300, // the number of milliseconds before the suggest is triggered after finished input, default: 300ms
extraHtml: undefined, // extra HTML code that is shown in each search suggest, you can even show values of datapoints here,
highlight: true, // whether matched words should be highlighted, default: true
},
smart404: { /* The caption of the search results. */
caption: 'These links might be useful', /* The string in the title that identifies the page as a 404 page. */
identifier: 'Page not found', /* A CSS selector that points to the area in which the alternative links should be shown. */
