bowtieddeployer / stacks.js

JavaScript libraries for identity, auth, storage and transactions on the Stacks blockchain.

Stacks.js

This repo is home to most of the stacks.js libraries, which provide everything you need to work with the Stacks blockchain from JavaScript/TypeScript.

Connecting Wallets

• @stacks/connect Connect web application to Stacks wallet browser extensions (separate repo).

Stacks Primitives

• @stacks/transactions Construct, decode transactions and work with Clarity smart contracts on the Stacks blockchain.
• @stacks/wallet-sdk Library for building wallets, managing accounts, and handling keys for the Stacks blockchain.
• @stacks/storage Store and fetch files with Gaia, the decentralized storage system.
• @stacks/encryption Encryption functions used by stacks.js packages.
• @stacks/auth Construct and decode authentication requests for Stacks apps.
• @stacks/profile Functions for manipulating user profiles.
• @stacks/network Network and API library for working with Stacks blockchain nodes.
• @stacks/common Common utilities used by stacks.js packages.

Native Smart Contract Interaction

• @stacks/bns Library for interacting with the BNS contract.
• @stacks/stacking Library for PoX stacking.

Others

• @stacks/cli Command line interface to interact with auth, storage and Stacks transactions.
• @stacks/keychain DEPRECATED: replaced by @stacks/wallet-sdk

See README in each package directory for installation instructions and usage.

---

Importing & Polyfills

Most of the Stacks.js packages are released in multiple different forms. These typically include:

• commonjs under /dist
• esm under /dist/esm
• umd (with all dependencies bundled and polyfilled for the browser) under /dist/umd

The @stacks/keychain and @stacks/wallet-sdk include an additional esm bundle (with external dependecies bundled and polyfilled for the browser) under /dist/polyfill.

Build systems try to be smart and auto-detect the correct type. But you can specify which type to import as follows:

import { generateSecretKey } from '@stacks/wallet-sdk'; // auto-detect
import { generateSecretKey } from '@stacks/wallet-sdk/dist/polyfill'; // esm bundle (polyfilled)
// ...
const walletSdk = require('@stacks/wallet-sdk'); // auto-detect
const walletSdk = require('@stacks/wallet-sdk/dist'); // cjs bundle
const walletSdk = require('@stacks/wallet-sdk/dist/umd'); // umd bundle
// ...

For production builds it is recommended to configure the respective build system to optimize further. For more fine-grained control, import using esm and configure your build system to polyfill any necessary dependencies. You could also alias the packages to their /dist/<TYPE> alternative. E.g., if you are already polyfilling in webpack, add a resolve.alias section like this.

We are currently working to get rid of many dependencies to remove the need for complex configuration. For now, if you are seeing problems, try the /dist/umd import. Otherwise, open a new issue with details on your build setup.

Migrating from blockstack.js

To migrate your app from blockstack.js to Stacks.js follow the steps in the migration guide.

Development: environment setup

To setup the development environment for this repository, follow these steps:

Prerequisites:

• Node v16.x.x is recommended (Node v17 may run into issues that can be worked around)

1. Clone this package.
2. Run npm install to install dependencies
3. Run npm run bootstrap to bootstrap project
4. Run npm run build to build packages
5. Run npm run test to run tests
6. 🚀

Some tests may contain logging of errors and warnings. This should not be confused with failing tests. Make sure the last lines of npm run test show lerna success - @stacks/... for every package.

Development: adding dependencies

This repo uses Lerna hoisting for package dependencies.

In order to install a new dependency to a package, the lerna add command must be used, rather than npm install <package>.

For example, the following command installs lodash as a dependency to the @stacks/storage package:

# Run within the root directory
npx lerna add lodash --scope @stacks/storage

Add --dev to install as a development dependency:

npx lerna add lodash --scope @stacks/storage --dev

Documentation

Documentation for the stacks.js packages is located at stacks.js.org.

Contributing

Github issues marked help-wanted are great places to start. Please ask in a github issue or discord before embarking on larger issues that aren't labeled as help wanted or adding additional functionality so that we can make sure your contribution can be included!