updates to running a mainnet node

Author: asteria

src/pages/understand-stacks/running-mainnet-node.md

@@ -13,26 +13,27 @@ images:
 
 ## Introduction
 
-This procedure demonstrates how to run a local mainnet node using Docker images.
+This guide shows how to run a Stacks mainnet node using Docker images.
 
--> This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on
-Windows.
+It uses [Hiro's implementation](https://github.com/blockstack/stacks-blockchain) of a Stacks node, along with [Bitcoin Core](https://github.com/bitcoin/bitcoin).
+
+-> This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows.
 
 ## Prerequisites
 
-Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi
-boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software
-installed on the node host machine:
+Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine:
 
 - [Docker](https://docs.docker.com/get-docker/)
 - [curl](https://curl.se/download.html)
 - [jq](https://stedolan.github.io/jq/download/)
 
+You can use `brew install docker curl jq` for MacOS and usually `sudo apt-get install docker curl jq` for Linux. But this might not work for every system.
+
+You'll need at minimum 500GB for the Bitcoin Core node and somewhere around 20GB (as of block `704197`). This will grow in size, so a 1TB or more drive is usually recommended for future-proofing.
+
 ### Firewall configuration
 
-In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on
-the ports discussed in this section. The details of network and firewall configuration are highly specific to your
-machine and network, so a detailed example isn't provided.
+In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are specific to your setup and network, so we won't provide a detailed example.
 
 The following ports must open on the host machine:
 
@@ -59,53 +60,82 @@ persistent data from the services. Download and configure the Docker images with
 docker pull blockstack/stacks-blockchain
 ```
 
-Create a directory structure for the service data with the following command:
+Create some directories for the Stacks data with the following command:
 
 ```sh
 mkdir -p ./stacks-node/{persistent-data/stacks-blockchain/mainnet,config/mainnet} && cd stacks-node
 ```
 
-## Step 2: running Stacks blockchain
+## Step 2: running Bitcoin Core
+
+Stacks finds its blocks by looking through the Bitcoin chain for anchor transactions that store the hashes of Stacks blocks. This is one of the things that makes Stacks so secure.
+
+You'll need to be running an **unpruned** Bitcoin Core node for your Stacks node to sync from.
+
+You'll want your Bitcoin node config to look something like this...
+
+```toml
+# remove if you like, this lets the node use more threads
+par=512
+server=1
+txindex=1
+# comment this back in after the initial block download if you want to use TOR. 
+# you'll need to add TOR and the config separately. 
+# there are guides for this elsewhere :)
+# onlynet=onion
+daemon=1
+# hiro's implementation uses rpc v0
+rpcserialversion=0
+maxorphantx=1
+banscore=1
+bind=0.0.0.0:8333
+rpcbind=0.0.0.0:8332
+rpcport=8332
+```
+
+There are plenty of guides on how to run a Bitcoin Core node. Do a search and you'll find more indepth info.
+
+If you're on Linux, Bitcoin Core will load the config from `~/.bitcoin/bitcoin.conf` by default. 
+
+On MacOS, it loads from `~/Library/Application Support/Bitcoin/bitcoin.conf`.
+
+-> Wait 'til your Bitcoin Core node is fully synced to the rest of the chain before proceeding to connect your Stacks node to it
+
+## Step 3: running the Stacks node
 
-First, create the `./config/Config.toml` file and add the following content to the
-file using a text editor:
+After Bitcoin Core has synced, create the `./config/Config.toml` file and add the following content to the file using a text editor:
 
 ```toml
+# stacks node config
 [node]
-working_dir = "/root/stacks-node/data"
+# where the node stores stacks chain data
+working_dir = "~/stacks-node/data"
 rpc_bind = "0.0.0.0:20443"
 p2p_bind = "0.0.0.0:20444"
+# the nodes used to bootstrap your node
+# these are hiro's nodes, but you can use any other nodes too
 bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444"
+
+# time in ms to wait for a microblock
 wait_time_for_microblocks = 10000
 
+# bitcoin rpc config
 [burnchain]
 chain = "bitcoin"
 mode = "mainnet"
-peer_host = "bitcoin.blockstack.com"
-username = "blockstack"
-password = "blockstacksystem"
+# host is usually `localhost` if you're running Bitcoin Core on the same machine
+peer_host = "<YOUR_BTC_CORE_HOST>"
+# leave as "" if you didn't set them in your Bitcoin config
+username = "<BTC_RPC_USERNAME>"
+password = "<BTC_RPC_PW>"
 rpc_port = 8332
 peer_port = 8333
-
-[connection_options]
-read_only_call_limit_write_length = 0
-read_only_call_limit_read_length = 100000
-read_only_call_limit_write_count = 0
-read_only_call_limit_read_count = 30
-read_only_call_limit_runtime = 1000000000
 ```
 
 Start the [`stacks-blockchain`][] container with the following command:
 
 ```sh
-docker run -d --rm \
-  --name stacks-blockchain \
-  -v $(pwd)/persistent-data/stacks-blockchain/mainnet:/root/stacks-node/data \
-  -v $(pwd)/config/mainnet:/src/stacks-node \
-  -p 20443:20443 \
-  -p 20444:20444 \
-  blockstack/stacks-blockchain \
-/bin/stacks-node start --config /src/stacks-node/Config.toml
+docker run -d --name stacks-blockchain -v $(pwd)/persistent-data/stacks-blockchain/mainnet:/root/stacks-node/data -v $(pwd)/config/mainnet:/src/stacks-node -p 20443:20443 -p 20444:20444 blockstack/stacks-blockchain /bin/stacks-node start --config /src/stacks-node/Config.toml
 ```
 
 You can verify the running [`stacks-blockchain`][] container with the command:
@@ -114,6 +144,8 @@ You can verify the running [`stacks-blockchain`][] container with the command:
 docker ps --filter name=stacks-blockchain
 ```
 
+If you want more verbose output, you can add an environment variable to the container - `STACKS_LOG_DEBUG=1`
+
 ## Step 3: verifying the services
 
 -> The initial burnchain header sync can take several minutes, until this is done the following commands will not work
@@ -132,13 +164,15 @@ INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitc
 INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 691034)
 ```
 
-To verify the [`stacks-blockchain`][] tip height is progressing use the following command:
+To verify the [`stacks-blockchain`][] tip height is progressing use the following command.
+
+-> This normally will only work once all Bitcoin headers have been synced and it starts to pull the Stacks blocks from the chain
 
 ```sh
 curl -sL localhost:20443/v2/info | jq
 ```
 
-If the instance is running you should recieve terminal output similar to the following:
+You should get something like this back.
 
 ```json
 {