Technical FAQ

This document lists frequently-asked questions by developers interested in working with Blockstack application and core components. If you are new to Blockstack, you should read the general questions first.

If you have a technical question that gets frequently asked on the forum or Slack, feel free to send a pull-request with the question and answer.

DApp developers

Who should build with the Blockstack Platform?

Everyone! However, more seriously, if you are building an application in JavaScript that requires sign-in and storage, you should look at using Blockstack.

I’m a web developer. Can I build on the Blockstack Platform?

Yes! Blockstack is geared primarily towards web developers. All of your existing knowledge is immediately applicable to Blockstack. Anything you can do in a web browser, you can do in a Blockstack app.

I’m a non-web developer. Can I build on Blockstack Platform?

Yes! Blockstack implements a RESTful API which lets you interact with Blockstack from any language and any runtime. In fact, the reference client (blockstack.js) is mainly a wrapper around these RESTful API calls, so you won’t be missing much by using a language other than Javascript.

How do I get started using Blockstack to build decentralized applications?

The Zero-to-Dapp Tutorial is the best place to learn to build with Blockstack. The tutorial takes you through key aspects of building with Blockstack and takes less than 60 minutes. If you want something short and sweet, we have a Hello World that takes about 10 minutes. In the end, you’ll have a working demo and even get a free limited edition t-shirt!

What’s the difference between a web app and a Blockstack app?

Blockstack apps are built like single-page web apps — they are, in fact, a type of web application.

Blockstack apps are a subset of web applications that use Blockstack’s technology to preserve the user’s control over their identities and data. As such, they tend to be simple in design and operation, since in many cases they don’t have to host anything besides the application’s assets.

Do I need to learn any new languages or frameworks?

No. Blockstack applications are built using existing web frameworks and programming. The only new thing you need to learn is either blockstack.js or the Blockstack RESTful API.

What is the general architecture of the Blockstack Platform?

Applications built with Blockstack are serverless and decentralized. Developers don’t have to worry about running servers, maintaining databases, or building out user management systems.

Developers build an application in Javascript using the blockstack.js library. This library handles everything from identity and authentication to data storage. Applications can request permissions from users for read and write access to user resources. Data is stored off the blockchain in a storage provider running Blockstack’s Gaia Storage system. Gaia is simple and reliable and uses existing cloud infrastructure.

Under the hood, Blockstack provides a decentralized domain name system, the Blockstack Naming System (BNS). BNS is a decentralized public key distribution system and registry for apps and user identities.

What is a serverless app?

The application should not run application-specific functionality on a server. All of its functionality should run on end-points. Serverless can also mean applications where the application developer still writes some amount of server-side logic, but unlike traditional architectures, this logic is run in stateless compute containers that are event-triggered and ephemeral (may only last for one invocation).

However, applications may use some servers with the caveat that they must not be part of the application’s trusted computing base. The Gaia Storage System is part of most DApps’ computing base, but because user data is signed and verified end-to-end, the storage systems are not trusted to always serve correct data.

How does my web app interact with Blockstack?

The blockstack.js library gives any web application the ability to interact with Blockstack’s authentication and storage services. In addition, we supply a public RESTful API.

What does blockstack.js do?

This is the reference client implementation for Blockstack. You use it in your web app to do the following:

  • Authenticate users
  • Load and store user data
  • Reuse users’ public data in your application

There are also mobile libraries for iOS and Android.

How do I use blockstack.js?

Our documentation has several examples you can use to get started.

How do I register Blockstack IDs?

You should use the Blockstack Browser.

How can I look up names and profiles?

You can use blockstack.js, or you can use the public Blockstack Core endpoint.

What kind of scalability and performance can I expect from applications built with Blockstack?

Blockstack uses the blockchain only for name registration. Data storage is kept off-chain in the Gaia Storage System. This basic application architecture means any application can perform and scale as they do without a blockchain.

Is there a limit to the file sizes I can store in a Gaia Storage System

The file size limit is 25 MB per file.

Can I run a Gaia Storage System commercially?

Yes, you can. Anyone interested in running a Gaia Storage System can run one and make it available to users.

Is the platform private or open sourced?

The project is open-source, and anyone can contribute! The major contributors are mostly employees of Blockstack PBC. You can see the full list of contributors here:

What programming language can I use to build these apps?

To make apps that run in the web browser using Blockstack, you can use JavaScript and any of the same web frameworks or libraries you use today such as React, AngularJs, Vue.js or jQuery. Blockstack Core is implemented in Python (the next major release will be in Rust), but you can use any language you like for native apps as long as it can consume a JSON REST API.

How is Blockstack different from Ethereum for building decentralized apps?

You can think of Ethereum as a heavy blockchain that does everything for you. All the complexity is handled on-chain, computations are run there, and all scalability and security concerns must be handled at the blockchain level. Ethereum amounts to a mainframe that runs all the applications in the ecosystem.

Blockstack puts minimal logic into a blockchain and handles scalability outside of the blockchain by re-using existing internet infrastructure. Our architectural design mirrors how computing has developed; moving from mainframes to smaller networked entities.

Can Blockstack applications interact with Bitcoin? Ethereum? Other blockchains?

Yes! Since Blockstack applications are built like web applications, all you need to do is include the relevant Javascript library into your application.

Core developers

What is Blockstack Core?

Blockstack Core is the reference implementation of the Blockstack protocol described in our white paper. Today, it consists of these components:

  • Blockstack Core: A Python backend service which reads transactions from the Stacks blockchain. This blockchain enables the Stacks Token (STX) and Blockstack Naming service.
  • Atlas: A peer network for communicating data about the Blockstack Naming System (BNS).
  • Blockstack API: A service for indexing the data stored by Blockstack Core and making it available in a performant way.

The next version of the Stacks Blockchain is under active development in the Rust programming language and employs our Tunable Proof-of-Work consensus algorithm and a unique scaling solution that enable individual apps to create their own app chains.

How will the next version of Blockstack Core change?

The next version of Blockstack core will incorporate smart contacts and do away with the virtual chain. This next version is expected toward the end of the year and will contain these components:

  • Leader election and Tunable Proof-of-Work implementation: This component governs how clients select the longest chain and which miners receive transaction fees for broadcasting transactions.
  • Peering network: This component distributes blocks and microblocks among peer nodes participating in the Stacks blockchain.
  • Smart contracting VM: This component is responsible for executing and validating transactions in the Stacks blockchain, including smart contract publishing and execution.
  • Blockstack API: This API indexes the data stored by Blockstack Core, exposing a JSON REST API for querying information about Stacks ownership, the Blockstack Naming System, and other data stored in smart contracts.

What is Leader Election and Proof-of-Burn?

Proof-of-Burn is a mechanism through which potential block miners (what we call leaders) burn an existing cryptocurrency to announce their candidacy for mining a particular block. The more cryptocurrency burnt by a particular leader, the more likely they are to be selected to lead a block (a process which uses cryptographic sortition). Once elected, a leader constructs a valid block, choosing the chain tip to base their fork off of, and announces the block to the network. In the event of chain forks, clients select the longest such fork as the correct fork.

How are user identities managed in the Blockstack architecture?

Identity is user-controlled and utilizes a smart contract implemented on the Stacks blockchain for secure management of keys, devices, and usernames. When users log in with apps, they are anonymous by default and use an app-specific key, but their full identity can be revealed and proven at any time. Keys are used for signing and encryption.

Can anyone register names on Blockstack?

Anyone can register a name or identity on Blockstack — you just need to use a Blockstack client to submit a registration request to a Blockstack core node. All of that software is Open-Source and can be run without any centralized parties.

What is a Blockstack Subdomain?

A Blockstack subdomain can be used for all the things a Blockstack ID can be used for. The only difference is that they have the format instead of ~~bar.baz~~. For example, is a Blockstack ID, and is a subdomain of Hundreds of subdomains can be registered with a single transaction. The BNS documentation describes them in detail.

Can I get a Blockstack subdomain without spending Bitcoin?

Blockstack subdomains can be obtained without spending Bitcoin by asking a subdomain registrar to create one for you.

Is there a Blockstack name explorer?

Yes! It’s at

Why should I trust the information, like name ownership or public key mappings, read from Blockstack?

Blockstack records are tough to tamper with. The difficulty comes from the fact that the bindings for name ownership (names on Blockstack are owned by public keys) are announced on the Stacks blockchain. To change these bindings, an attacker must initiate a winning fork of the Stacks blockchain that is longer than the true chain but with a different history. The longer your name binding exists on the correct chain, the harder this task becomes.

Do you have a testnet or sandbox to experiment with Blockstack?

We have an integration test framework that provides a private Blockstack testnet. It uses bitcoin -regtest to create a private blockchain that you can interact with, without having to spend any Bitcoin or having to wait for blocks to confirm. There is a deployed testnet of the current version of blockstack-core at To deploy your own testnet, please see the README for details.

Can the Blockstack blockchain fork?

Yes, the Blockstack network can fork. We hard fork the network once a year to make protocol-breaking changes and upgrade the network. The latest fork was in 2018 where we introduced the genesis block of the Stacks blockchain. For technical details, see the 2018 forum post for the annual hard fork.

Which coin fuels the Blockstack blockchain?

Currently, transactions fees are paid in Bitcoin. In 2018 our annual hard fork enabled the fuel payments for digital asset registration to be paid in Stacks token. For technical details, see the 2018 forum post for the annual hard fork. In the next version of the Stacks chain, which will implement Proof-of-Burn mining and leader election, all transaction fees will be paid in Stacks.

How is the Blockstack network upgraded over time? What parties need to agree on an upgrade?

We’re working on an on-chain voting strategy similar to how mining works, where anyone can cast a vote proportional to the amount of Bitcoin burned. Similar to how Bitcoin upgrades, a new feature is activated if a certain threshold (e.g., 80%) of votes consistently request its adoption over a given time interval (e.g., a couple of weeks).

Until then, Blockstack publicly announces the availability of new software, with the promise that each release will bring highly-desired features to make upgrading worth the users’ whiles.

Who gets the registration fees for name registrations?

With the current design, names are secured through proof of burn mining which uses Bitcoin. Namespace creators determine how much names costs in a space, when and if the names expire. These creators can also elect to receive fees for creating names in the first year that a namespace exists.

Do I need to run a full Blockstack node to use Blockstack?

No. We maintain a fleet of Blockstack Core nodes that your Blockstack applications can connect to by default.

Can I run my own Blockstack node?

If you want to run your own, we provide detailed instructions on our install page. It only takes about 5-10 minutes to spin up your full node! Running a Blockstack node keeps you secure by ensuring that your app gets the right names and public keys. It’s not expensive; it takes as many resources as a Chrome tab.

What is the capacity per block for registrations using Blockstack?

Initial registrations can be done at an order of hundreds per block, and once an identity is registered, you can do unlimited updates to the data because that is off-chain.

Can I programmatically register Blockstack IDs?

Blockstack applications do not currently have access to the user’s wallet. Users are expected to register Blockstack IDs themselves.

However, if you feel particularly ambitious, you can do one of the following:

  • Set up a blockstack api endpoint (see the project README) and write a program to automatically register names. Also, see the API documentation for registering names on this endpoint.

  • Write a node.js program that uses blockstack.js to register names. This is currently in development.

Can I programmatically register Blockstack Subdomains?

Yes! Once you deploy your own subdomain registrar, you can have your web app send it requests to register subdomains on your Blockstack ID. You can also create a program that drives subdomain registration on your Blockstack ID.

What language is the Blockstack software written in?

The current Stacks chain is implemented in Python 2. The next version of the Stacks chain will be written in Rust.

Our libraries and many of our developer tools are written in Javascript (and we’re working on porting much of our Javascript to TypeScript).

What if the current companies and developers working on Blockstack disappear, would the network keep running?

Yes, the Blockstack network will keep running. All of Blockstack’s code is open-source, and anyone can deploy Blockstack nodes or maintain the code. Further, Blockstack nodes don’t need to coordinate with each other to function. Any node that a user deploys can function correctly independently.

Open source developers

How old is the Blockstack project?

Work on the project started in late 2013. First public commits on the code are from Jan 2014. The first registrar for Blockstack was launched in March 2014, and the project has been growing since then.

What is the current development roadmap look like?

See this page for the current development roadmap.

Where are the current core developers based? What are the requirements for being a core developer?

Our core developers work in various cities, New York City, Seattle, Toronto, Chicago, Minneapolis, NYC, San Francisco Bay Area, Barcelona, and the Netherlands. Developers who’ve contributed to the core open-source software over a long enough period, by default, get included in the list of core developers. There is no formal process for being part of this informal list. Core developers, generally, can write high-quality code, understand distributed systems and applied crypto, and share a vision of building a genuinely decentralized internet and are dedicated to that cause.

I heard some companies working on Blockstack have raised venture capital, how does that impact the project?

Blockstack, like Linux, is an open-source project with a Linux GPLv2 license for the core technology. Just like different companies build apps and services on top of Linux and have different individual business models, some companies are building apps & services for Blockstack on top of the core open-source technology, and these companies have various business models and funding sources respectively. Having more venture-backed companies join the ecosystem for a decentralized internet is a good thing for everyone participating in the ecosystem including users and developers.

Miscellaneous questions

What’s the difference between Onename and Blockstack?

Onename was a free Blockstack ID registrar run by Blockstack. It makes it easy to register your name and set up your profile. Once the name has been registered in Onename, you can transfer it to a wallet you control, or leave it there and use it as you like.

Does Blockstack use a DHT (Distributed Hash Table)?

It does not, as of November 2016. It uses a much more reliable system called the Atlas Network. Details here:

How can I transfer my Stacks Token out of my Stacks Wallet?

Your Stacks Wallet seed phrase is required to send Stacks Tokens from your Stacks Wallet. Access your Stacks Wallet using your unique wallet address and seed phrase to transfer unlocked STX tokens. Please see here for more information on time and transfer locks on various Stacks Tokens based on when you purchased your tokens.