Setting up a Stacks Keychain

Not your keys, not your crypto.

Table of Contents

Creating a Keychain

Prerequisites

Note: To generate a keychain, the command npx is used and requires that Node.js is installed.

To check which version of each software you have installed, use the commands below:

node -v
npm -v
npx -v

If you need to install another version of node, the Node Version Manager (nvm) is recommended for Linux, MacOS, and Windows WSL. If you are using Windows, directly download the software from the Node.js website.

Using @stacks-cli

To generate a keychain using the command from the Stacks documentation: 

npx @stacks/cli make_keychain > keychain.json

Using stacks-gen

To generate a keychain using stacks-gen from Pascal: 

npx -q stacks-gen sk > keychain.json

Note: Both commands above will save the keychain information to a file named keychain.json. You can view this file in any text editor or via the command line using cat keychain.json on Mac/Linux/WSL or type keychain.json on Windows.

Importing address into Bitcoind

In order to use your BTC address with bitcoind, you will need to first tell your node about your BTC address using either importaddress or importprivkey with bitcoin-cli.

A quick description of both options is below, with more information on the Bitcoin Node page.

Note: When running importaddress or importprivkey, it is important to add -rpcclienttimeout=7200 when running bitcoin-cli to ensure the operation has enough time to complete.

Import Address

Adds an address or script (in hex) that can be watched as if it were in your wallet but cannot be used to spend. Requires a new wallet backup.

bitcoindeveloper: importaddress

In order to use importaddress we only need the BTC address generated by either tool listed above.

Import Private Key

Adds a private key (as returned by dumpprivkey) to your wallet. Requires a new wallet backup.

bitcoindeveloper: importprivkey

In order to use importprivkey we need a Wallet Import Format (WIF) formatted file, which can be obtained by using stacks-gen.

If you did not use stacks-gen to create your initial key, you can import your existing key using the backup phrase.

npx -q stacks-gen sk --phrase "replace with twenty four word backup phrase" > keychain_stacksgen.json

Note: Both commands above will save the keychain information to a file named keychain_stacksgen.json. You can view this file in any text editor or via the command line using cat keychain_stacksgen.json on Mac/Linux/WSL or type keychain_stacksgen.json on Windows.

The file generated by stacks-gen will contain a value for wif that can be used with bitcoin-cli importprivkey.

Other Resources

Bitcoin Node

A walkthrough for setting up and interacting with bitcoind for use with stacks-node.

Stacks Keychain

A walkthrough of setting up a stacks keychain using various tools.

Stacks Node

A walkthrough for setting up stacks-node and configuring it for mining.