Blockstack-core vs blockstack.js


What is criteria used to determine what functionality should be accessed via blockstack-core API calls and what functionality should be built into blockstack.js (or blockstack-browser)? For example, it appears as though blockstack.js no longer makes a call to the blockstack core API for the following:

  • Looking up users
  • Pending transactions
  • Name pricing

I found the following statement in a couple places in the core documentation:

Blockstack Core’s API module provides a set of API calls for interacting with the node’s configuration. However, most of this section is DEPRECATED in favor of moving configuration state to the Blockstack Browser. Client-side state is managed by blockstack.js.

Moving configuration state into blockstack-browser (where it can be accessed via UI, but not API) seems contrary to “API-first” design principals. What options are there for blockstack clients that do not have the ability to display a browser UI?

Also, moving Client-side state into Blockstack.js introduces the necessity of more code duplication should there be interest in other language bindings. As proof… the following proposal in the 2018-03-29 engineering meeting notes:

What advantage is there in browser no longer being dependent on Core?


There are two separate daemons in Blockstack Core: the indexer daemon which crawls the blockchain, and the API daemon that provides a RESTful API. They are designed to be deployable separately, since the indexer is considerably heavier in its resource usage. Also, the RESTful API daemon implements a lot of stateful functionality (like a wallet).

The Browser currently ships with a locally-running RESTful API daemon, but this lead to a lot of packaging problems on Mac OS. We’ve been addressing this in the background by moving the stateful functionality from the RESTful API daemon into blockstack.js, so we can avoid shipping the RESTful API daemon. At the same time, the stateless RESTful calls have been migrated to the indexer process, so the RESTful API daemon can be dropped from the codebase entirely.

The long-term goal is that the Browser will use blockstack.js internally for all of its wallet, configuration, and storage functionality (i.e. stateful things that really shouldn’t be exposed via a network API, and really shouldn’t be implemented in more than one place in the architecture). If you want a RESTful API server that lets you manage your state, you should implement it with blockstack.js.

When we say that the Browser will no longer depend on Core, we mean that it won’t need a locally-running Core RESTful API daemon to function. Both it and other Blockstack clients (like my node.js CLI) can instead use an indexer Core daemon via blockstack.js. Moreover, the indexer Core daemon will implement the read-only RESTful API calls, so clients like curl can interact with it directly.

More background on this topic can be found here.


@jude, Thank you for your thorough answer. The linked topic was especially useful.