Stacks Mono Repo RFC


Blockstack’s main JavaScript package blockstack.js has been central to all Blockstack apps built since its debut. The platform has been evolving continuously and as new features are added, libraries out grow the original scope. A host of major recent changes to the platform, including the recent release of Connect, Stacks 2.0 Transactions Library, an updated CLI, Stacks 2.0 Testnet have prompted us to revisit the structuring of the developer libraries.

We’re proposing the creation of a Stacks mono repo which will contain almost everything a developer needs to build on the Stacks platform. The objective is to make it easy to understand what the packages do by clearly separating them by use case. Under the hood, we’ll be utilizing existing blockstack.js code and new libraries. This will also reduce the amount of unused code included by developers as not every Blockstack app makes use of the entire suite of tools.

As part of this change. we propose splitting the blockstack.js library into the following 4 packages:


A package that contains all functions relating to authentication. The API will be updated to support new implementations of authenticators. Functions depending on a legacy Blockstack browser will be dropped in favour of Connect. If your app already makes use of Connect, no changes are required.


All storage and Gaia related functions, including Collections.


API used by authenticators to manipulate user profiles on BNS. Most apps do not make use of this.


Common encryption functions used across the platform.

Additionally, we propose adding the following packages to the mono repo:


Generation and manipulation of keys and wallets for Stacks 2.0. This package will merge overlapping logic from blockstack.js, the stacks-transactions library and the ux/keychain library.


API for constructing Stacks transactions. This is essentially moving the stacks-transactions library into the new repo structure.


API for communicating with Stacks nodes including fee estimation, transaction broadcasting, transaction status and etc.


This package will be a redesigned unified Stacks command line interface that represents the developer’s main entry point to the Stacks ecosystem. This is a planned project that we’ll have more details on soon.

What does this change for developers?

The main change for developers would be imports. For example:


import { userSession } from 'blockstack'


import { userSession } from '@blockstack/auth'

We expect most API method names to remain the same so no changes are required in your code beyond the import statements.


The rationale is two fold, first the libraries you currently need to build on Blockstack are spread across multiple repositories and some have overlapping functionality. For example, logic dealing with key pair generation exists in blockstack.js, stacks-transactions and keychain. This is confusing and does not provide for a great developer onboarding experience. The mono repo will bring all of these libraries into one repo and make it easier for developers to understand the dependency relationships and make it easier to find answers to problems.

Second, with this refactor, developers can choose which packages they need in their app and do not need to include unused modules. For example, apps typically do not need the profile functions included with blockstack.js. Apps that do not utilize smart contracts do not need to include the transactions and network modules. This helps reduce package sizes and improves app performance.

As this is a major change to our developer tools, we wanted to get feedback from the community first. Please let us know what you think. Your input is greatly appreciated.


Great news - sounds much clearer! How will this relate to the ‘ux’ monorepo which has the browser extension and connect - will this stay where it is - does it overlap or fold into this mono repo?

I’d love to see this. Thanks @yukan! Will this coincide with a new release of “blockstack”? Also will the library be rename to “Stacks”, to align with the community rebrand. cc @jeffd

ie import { userSession } from '@stacks/auth' ???

looks good to me. stacks-node will remain separate, right?

The extension will remain as a separate repo. It may make sense for Connect to be part of the mono repo in the future but for now it will remain separate as well.


Those APIs are not exposed directly in the current SDK … consider this a request to have access to manipulating user profiles from user apps.

Currently there’s no way for apps to edit user profiles since that requires the master private key which apps do not have access to. I can imagine an API that goes through the authenticator like the new transaction signing API.