In this document, we'll go over how to run a stacks-blockchain-api instance.
There are several components involved here to have a working setup, and we'll go over each.
Please note that the following guide is targeted for Debian based systems - that in mind, most of the commands will work on other Unix systems with some small adjustments.
- Running a stacks-blockchain API instance from source
bash
or some other Unix-like shell (i.e.zsh
)sudo
or root level access to the system
Since we'll need to create some files/dirs for persistent data,
we'll first create a base directory structure and set some permissions:
$ sudo mkdir -p /stacks-node/{persistent-data/stacks-blockchain,config,binaries}
$ sudo chown -R $(whoami) /stacks-node
$ cd /stacks-node
$ PG_VERSION=14 \
&& NODE_VERSION=16 \
&& sudo apt-get update \
&& sudo apt-get install -y \
gnupg2 \
git \
lsb-release \
curl \
jq \
openjdk-11-jre-headless \
build-essential \
zip \
&& curl -sL https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add - \
&& echo "deb http://apt.postgresql.org/pub/repos/apt/ `lsb_release -cs`-pgdg main" | sudo tee -a /etc/apt/sources.list.d/pgsql.list \
&& curl -sL https://deb.nodesource.com/setup_${NODE_VERSION}.x | sudo bash - \
&& sudo apt-get update \
&& sudo apt-get install -y \
postgresql-${PG_VERSION} \
postgresql-client-${PG_VERSION} \
nodejs
We'll need to set a basic role, database to store data, and a password for the role.
Clearly, this password is insecure so modify password
to something stronger before creating the role.
$ cat <<EOF> /tmp/file.sql
create role stacks login password 'password';
create database stacks_db;
grant all on database stacks_db to stacks;
EOF
$ sudo su - postgres -c "psql -f /tmp/file.sql" && rm -f /tmp/file.sql
$ echo "local all stacks md5" | sudo tee -a /etc/postgresql/14/main/pg_hba.conf
$ sudo systemctl restart postgresql
$ sudo systemctl stop postgresql
$ git clone https://github.com/hirosystems/stacks-blockchain-api /stacks-node/stacks-blockchain-api && cd /stacks-node/stacks-blockchain-api \
&& echo "GIT_TAG=$(git tag --points-at HEAD)" >> .env \
&& npm config set unsafe-perm true \
&& npm install \
&& npm run build \
&& npm prune --production
The stacks blockchain api requires several Environment Variables to be set in order to run properly.
To reduce complexity, we're going to create a .env
file that we'll use for these env vars.
Create a new file: /stacks-node/stacks-blockchain-api/.env
with the following content:
$ cat <<EOF> /stacks-node/stacks-blockchain-api/.env
NODE_ENV=production
GIT_TAG=master
PG_HOST=localhost
PG_PORT=5432
PG_USER=stacks
PG_PASSWORD=password
PG_DATABASE=stacks_db
STACKS_CHAIN_ID=0x00000001
V2_POX_MIN_AMOUNT_USTX=90000000260
STACKS_CORE_EVENT_PORT=3700
STACKS_CORE_EVENT_HOST=0.0.0.0
STACKS_BLOCKCHAIN_API_PORT=3999
STACKS_BLOCKCHAIN_API_HOST=0.0.0.0
STACKS_CORE_RPC_HOST=localhost
STACKS_CORE_RPC_PORT=20443
EOF
$ cd /stacks-node/stacks-blockchain-api && nohup node ./lib/index.js &
$ ps -ef | grep "lib/index.js" | grep -v grep
user 17788 827 39 18:14 pts/0 00:07:55 node ./lib/index.js
$ sudo kill $(ps -ef | grep "lib/index.js" | grep -v grep | awk {'print $2'})
In order to have a usable API instance, it needs to have data from a running stacks-blockchain instance.
You will need to have the following in your Config.toml
- this config block will send blockchain events to the API instance that was previously started:
[[events_observer]]
endpoint = "<fqdn>:3700"
retry_count = 255
events_keys = ["*"]
Here is an example Config.toml
that you can use - create this file as /stacks-node/config/Config.toml
:
$ cat <<EOF> /stacks-node/config/Config.toml
[node]
working_dir = "/stacks-node/persistent-data/stacks-blockchain"
rpc_bind = "0.0.0.0:20443"
p2p_bind = "0.0.0.0:20444"
bootstrap_node = "02196f005965cebe6ddc3901b7b1cc1aa7a88f305bb8c5893456b8f9a605923893@seed.mainnet.hiro.so:20444"
wait_time_for_microblocks = 10000
[[events_observer]]
endpoint = "localhost:3700"
retry_count = 255
events_keys = ["*"]
[burnchain]
chain = "bitcoin"
mode = "mainnet"
peer_host = "bitcoind.stacks.co"
username = "blockstack"
password = "blockstacksystem"
rpc_port = 8332
peer_port = 8333
EOF
- Download latest release binary from https://github.com/blockstack/stacks-blockchain/releases/latest
- Linux archive for latest release:
curl -L https://github.com/blockstack/stacks-blockchain/releases/download/$(curl --silent https://api.github.com/repos/blockstack/stacks-blockchain/releases/latest | jq .name -r | cut -f2 -d " ")/linux-x64.zip -o /tmp/linux-x64.zip
- Extract the zip archive:
unzip /tmp/linux-x64.zip -d /stacks-node/binaries/
$ cd /stacks-node && nohup /stacks-node/binaries/stacks-node start --config /stacks-node/config/Config.toml &
$ ps -ef | grep "/stacks-node/binaries/stacks-node" | grep -v grep
user 17835 17834 99 18:17 pts/0 00:20:23 /stacks-node/binaries/stacks-node start --config /stacks-node/config/Config.toml
$ sudo kill $(ps -ef | grep "/stacks-node/binaries/stacks-node" | grep -v grep | awk {'print $2'})
To verify the database is ready:
- Connect to the DB instance:
psql -h localhost -U stacks stacks_db
- use the password from the Postgres Permissions Step
- List current databases:
\l
- Verify data is being written to the database:
select * from blocks limit 1;
- Disconnect from the DB :
\q
$ curl localhost:20443/v2/info | jq
{
"peer_version": 402653184,
"pox_consensus": "e99b880a26405d3cda724f4c2b815ca0e7b681a8",
"burn_block_height": 666201,
"stable_pox_consensus": "8be2fc9f9156b31af688b9e3c484dc7a26cefc4f",
"stable_burn_block_height": 666194,
"server_version": "stacks-node 2.0.11.0.0 (master:bf4a577+, release build, linux [x86_64])",
"network_id": 1,
"parent_network_id": 3652501241,
"stacks_tip_height": 92,
"stacks_tip": "a251bfa158c7887c575798b79c8df57190690e023af245e45513110399c0cb5f",
"stacks_tip_consensus_hash": "ae29e81af9e7febfd4af6b53a3e515660a84150c",
"genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b",
"unanchored_tip": "9fb08dd696d4e05bd042998dba8dd204ee64e11266cd4fba95b3a7bdaa709400",
"unanchored_seq": 0,
"exit_at_block_height": null
}
$ curl localhost:3999/v2/info | jq
{
"peer_version": 402653184,
"pox_consensus": "e99b880a26405d3cda724f4c2b815ca0e7b681a8",
"burn_block_height": 666201,
"stable_pox_consensus": "8be2fc9f9156b31af688b9e3c484dc7a26cefc4f",
"stable_burn_block_height": 666194,
"server_version": "stacks-node 2.0.11.0.0 (master:bf4a577+, release build, linux [x86_64])",
"network_id": 1,
"parent_network_id": 3652501241,
"stacks_tip_height": 93,
"stacks_tip": "74223951b9dddfe82b1b116c852f0a14ff9432270d680042a5ef11cb0533b935",
"stacks_tip_consensus_hash": "2d521daf879f2e00f745c47000b856e1d41b15d4",
"genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b",
"unanchored_tip": "9fb08dd696d4e05bd042998dba8dd204ee64e11266cd4fba95b3a7bdaa709400",
"unanchored_seq": 0,
"exit_at_block_height": null
}