{"description":"Choose a name","author":{"@type":"Person","name":"Blockstack"},"@type":"BlogPosting","url":"https://docs.blockstack.org/core/naming/pickname.html","headline":"Choose a name","dateModified":"2018-09-13T13:13:37-07:00","datePublished":"2018-09-13T13:13:37-07:00","mainEntityOfPage":{"@type":"WebPage","@id":"https://docs.blockstack.org/core/naming/pickname.html"},"@context":"http://schema.org"}</script>
<pclass="no_toc">This section explains how to choose and create a namespace, it contains the
following sections:</p>
<ulid="markdown-toc">
<li><ahref="#intended-uses-for-a-namespace"id="markdown-toc-intended-uses-for-a-namespace">Intended uses for a namespace</a></li>
<li><ahref="#list-all-namespaces-in-existence-reference"id="markdown-toc-list-all-namespaces-in-existence-reference">List all namespaces in existence (reference).</a></li>
<li><ahref="#list-all-names-within-a-namespace-reference"id="markdown-toc-list-all-names-within-a-namespace-reference">List all names within a namespace (reference)</a></li>
<li><ahref="#get-the-cost-to-register-a-namespace-reference"id="markdown-toc-get-the-cost-to-register-a-namespace-reference">Get the Cost to Register a Namespace (reference)</a></li>
<li><ahref="#getting-the-current-consensus-hash-reference"id="markdown-toc-getting-the-current-consensus-hash-reference">Getting the Current Consensus Hash (reference)</a></li>
<li><ahref="#create-a-namespace"id="markdown-toc-create-a-namespace">Create a namespace</a></li>
</ul>
<h2id="intended-uses-for-a-namespace">Intended uses for a namespace</h2>
<p>The intention is that each application can create its own BNS
namespace for its own purposes. Applications can use namespaces for things like:</p>
<ul>
<li>Giving users a SSO system, where each user registers their public key under a
username. Blockstack applications do this with names in the <codeclass="highlighter-rouge">.id</code> namespace,
for example.</li>
<li>Providing a subscription service, where each name is a 3rd party that provides
a service for users to subscribe to. For example, names in
<codeclass="highlighter-rouge">.podcast</code> point to podcasts that users of the
<ahref="https://dotpodcast.co">DotPodcast</a> app can subscribe to.</li>
<li>Implementing software licenses, where each name corresponds to an access key.
Unlike conventional access keys, access keys implemented as names
can be sold and traded independently. The licensing fee (paid as a name
registration) would be set by the developer and sent to a developer-controlled
blockchain address.</li>
</ul>
<p>Names within a namespace can serve any purpose the developer wants. The ability
to collect registration fees for 1 year after creating the namespace not only
gives developers the incentive to get users to participate in the app, but also
gives them a way to measure economic activity.</p>
<p>Developers can query individual namespaces and look up names within them using
the BNS API.</p>
<h2id="list-all-namespaces-in-existence-reference">List all namespaces in existence (<ahref="https://core.blockstack.org/#namespace-operations-get-all-namespaces">reference</a>).</h2>
<h2id="list-all-names-within-a-namespace-reference">List all names within a namespace (<ahref="https://core.blockstack.org/#namespace-operations-get-all-namespaces">reference</a>)</h2>
<h2id="get-the-cost-to-register-a-namespace-reference">Get the Cost to Register a Namespace (<ahref="https://core.blockstack.org/#price-checks-get-namespace-price">reference</a>)</h2>
<h2id="getting-the-current-consensus-hash-reference">Getting the Current Consensus Hash (<ahref="https://core.blockstack.org/#blockchain-operations-get-consensus-hash">reference</a>)</h2>
document for details on how the consensus hash is used to construct the
transaction.</p>
<h2id="create-a-namespace">Create a namespace</h2>
<p>There are four steps to creating a namespace:</p>
<ol>
<li>
<p><strong>Send a <codeclass="highlighter-rouge">NAMESPACE_PREORDER</code> transaction</strong> (<ahref="https://www.blocktrail.com/BTC/tx/5f00b8e609821edd6f3369ee4ee86e03ea34b890e242236cdb66ef6c9c6a1b28">live example</a>).
This is the first step. This registers the <em>salted hash</em> of the namespace with BNS nodes, and burns the
requisite amount of cryptocurrency. In addition, it proves to the
BNS nodes that user has honored the BNS consensus rules by including
a recent <em>consensus hash</em> in the transaction
(see the section on <ahref="#bns-forks">BNS forks</a> for details).</p>
</li>
<li>
<p><strong>Send a <codeclass="highlighter-rouge">NAMESPACE_REVEAL</code> transaction</strong> (<ahref="https://www.blocktrail.com/BTC/tx/ab54b1c1dd5332dc86b24ca2f88b8ca0068485edf0c322416d104c5b84133a32">live example</a>).
This is the second step. This reveals the salt and the namespace ID (pairing it with its
<codeclass="highlighter-rouge">NAMESPACE_PREORDER</code>), it reveals how long names last in this namespace before
they expire or must be renewed, and it sets a <em>price function</em> for the namespace
that determines how cheap or expensive names its will be. The price function takes
a name in this namespace as input, and outputs the amount of cryptocurrency the
name will cost (i.e. by examining how long the name is, and whether or not it
has any vowels or non-alphabet characters). The namespace creator
has the option to collect name registration fees for the first year of the
namespace’s existence by setting a <em>namespace creator address</em>.</p>
</li>
<li>
<p><strong>Seed the namespace with <codeclass="highlighter-rouge">NAME_IMPORT</code> transactions</strong> (<ahref="https://www.blocktrail.com/BTC/tx/c698ac4b4a61c90b2c93dababde867dea359f971e2efcf415c37c9a4d9c4f312">live example</a>).
Once the namespace has been revealed, the user has the option to populate it with a set of
names. Each imported name is given both an owner and some off-chain state.
This step is optional—namespace creators are not required to import names.</p>
</li>
<li>
<p><strong>Send a <codeclass="highlighter-rouge">NAMESPACE_READY</code> transaction</strong> (<ahref="https://www.blocktrail.com/BTC/tx/2bf9a97e3081886f96c4def36d99a677059fafdbd6bdb6d626c0608a1e286032">live example</a>).
This is the final step of the process. It <em>launches</em> the namespace, which makes it available to the
public. Once a namespace is ready, anyone can register a name in it if they
pay the appropriate amount of cryptocurrency (according to the price funtion
revealed in step 2).</p>
</li>
</ol>
<p>The reason for the <codeclass="highlighter-rouge">NAMESPACE_PREORDER/NAMESPACE_REVEAL</code> pairing is to prevent
frontrunning. The BNS consensus rules require a <codeclass="highlighter-rouge">NAMESPACE_REVEAL</code> to be
paired with a previous <codeclass="highlighter-rouge">NAMESPACE_PREORDER</code> sent within the past 24 hours.
If it did not do this, then a malicious actor could watch the blockchain network
and race a victim to claim a namespace.</p>
<p>Namespaces are created on a first-come first-serve basis. If two people try to
create the same namespace, the one that successfully confirms both the
<codeclass="highlighter-rouge">NAMESPACE_PREORDER</code> and <codeclass="highlighter-rouge">NAMESPACE_REVEAL</code> wins. The fee burned in the
<codeclass="highlighter-rouge">NAMESPACE_PREORDER</code> is spent either way.</p>
<p>Once the user issues the <codeclass="highlighter-rouge">NAMESPACE_PREORDER</code> and <codeclass="highlighter-rouge">NAMESPACE_REVEAL</code>, they have
1 year before they must send the <codeclass="highlighter-rouge">NAMESPACE_READY</code> transaction. If they do not
do this, then the namespace they created disappears (along with all the names
<p>Developers wanting to create their own namespaces should read the <ahref="/core/naming/namespace.html">namespace creation section</a> document. It is highly recommended that
developers request individual support before creating their own space, given the large amount of
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
