From 238fcde3ab0386df80de5586057d5a8714544c09 Mon Sep 17 00:00:00 2001 From: CharlieC3 <2747302+CharlieC3@users.noreply.github.com> Date: Wed, 30 Dec 2020 17:14:50 -0500 Subject: [PATCH] docs: mainnet changes for running node and miner --- next.config.js | 2 +- public/images/pages/mainnet-sm.svg | 18 + public/images/pages/mainnet.svg | 13 + src/common/navigation.yaml | 6 +- .../custom-blocks/page-reference.tsx | 6 + .../references/stacks-node-configuration.md | 35 +- src/pages/start-mining/mainnet.md | 367 ++++++++++++++++++ .../testnet.md} | 20 +- .../understand-stacks/running-mainnet-node.md | 242 ++++++++++++ .../understand-stacks/running-testnet-node.md | 49 ++- 10 files changed, 712 insertions(+), 46 deletions(-) create mode 100644 public/images/pages/mainnet-sm.svg create mode 100644 public/images/pages/mainnet.svg create mode 100644 src/pages/start-mining/mainnet.md rename src/pages/{start-mining.md => start-mining/testnet.md} (94%) create mode 100644 src/pages/understand-stacks/running-mainnet-node.md diff --git a/next.config.js b/next.config.js index 6abb39b5..5f15935c 100755 --- a/next.config.js +++ b/next.config.js @@ -605,7 +605,7 @@ async function redirects() { }, { source: '/mining', - destination: '/start-mining', + destination: '/start-mining/mainnet', permanent: true, }, { diff --git a/public/images/pages/mainnet-sm.svg b/public/images/pages/mainnet-sm.svg new file mode 100644 index 00000000..c8da8603 --- /dev/null +++ b/public/images/pages/mainnet-sm.svg @@ -0,0 +1,18 @@ + + + + + + + background + + + + Layer 1 + + + + + + + \ No newline at end of file diff --git a/public/images/pages/mainnet.svg b/public/images/pages/mainnet.svg new file mode 100644 index 00000000..842f6e75 --- /dev/null +++ b/public/images/pages/mainnet.svg @@ -0,0 +1,13 @@ + + + + background + + + + Layer 1 + + + + + \ No newline at end of file diff --git a/src/common/navigation.yaml b/src/common/navigation.yaml index 24a502fa..e1691f92 100644 --- a/src/common/navigation.yaml +++ b/src/common/navigation.yaml @@ -20,6 +20,7 @@ sections: pages: - path: /managing-accounts - path: /sending-tokens + - path: /running-mainnet-node - path: /running-testnet-node - path: /integrate-stacking - path: /stacking-using-CLI @@ -47,7 +48,10 @@ sections: - path: /signing-transactions - path: /public-registry-tutorial - path: /build-apps # is an overview page - - path: /start-mining # is an overview page + - path: /start-mining + pages: + - path: /mainnet + - path: /testnet - title: Technology pages: diff --git a/src/components/custom-blocks/page-reference.tsx b/src/components/custom-blocks/page-reference.tsx index 77b06621..c646b25f 100644 --- a/src/components/custom-blocks/page-reference.tsx +++ b/src/components/custom-blocks/page-reference.tsx @@ -244,6 +244,12 @@ const getIcon = (icon: string) => { ); + case 'MainnetIcon': + return (p: BoxProps) => ( + + + + ); default: return (p: BoxProps) => ; } diff --git a/src/pages/references/stacks-node-configuration.md b/src/pages/references/stacks-node-configuration.md index f7ba9bc3..0c94e4f3 100644 --- a/src/pages/references/stacks-node-configuration.md +++ b/src/pages/references/stacks-node-configuration.md @@ -47,6 +47,16 @@ Example: stacks-node xenon ``` +### mainnet + +Start a node that joins and streams blocks from the public mainnet. + +Example: + +```bash +stacks-node mainnet +``` + ### start Start a node with a config of your own. Can be used for joining a network, starting a new chain, or replacing default values used by the `mocknet` or `xenon` subcommands. @@ -99,7 +109,6 @@ Example: [node] rpc_bind = "0.0.0.0:20443" p2p_bind = "0.0.0.0:20444" -bootstrap_node = "048dd4f26101715853533dee005f0915375854fd5be73405f679c1917a5d4d16aaaf3c4c0d7a9c132a36b8c5fe1287f07dad8c910174d789eb24bdfb5ae26f5f27@testnet-miner.blockstack.org:20444" # Enter your private key here seed = "replace-with-your-private-key" miner = true @@ -296,7 +305,7 @@ Example: ```toml [connection_options] public_ip_address = "1.2.3.4:20444" -download_interval = 10 +download_interval = 60 walk_interval = 30 ``` @@ -317,7 +326,7 @@ Time (in seconds) between attempts to download blocks. Example: ```toml -download_interval = 10 +download_interval = 60 ``` #### walk_interval @@ -339,10 +348,10 @@ Example: ```toml [burnchain] chain = "bitcoin" -mode = "krypton" -peer_host = "bitcoind.blockstack.org" -rpc_port = 18443 -peer_port = 18444 +mode = "mainnet" +peer_host = "your.bitcoind.node.org" +rpc_port = 8332 +peer_port = 8333 ``` #### chain @@ -367,12 +376,12 @@ mode = "xenon" #### peer_host -Domain name of the host running the backend Bitcoin blockchain. +Domain name of the host running the backend Bitcoin blockchain. It's required to either run a personal Bitcoin node locally, or to use a publicly hosted Bitcoin node. Example: ```toml -peer_host = "bitcoind.xenon.blockstack.org" +peer_host = "your.bitcoind.node.org" ``` #### rpc_port @@ -382,7 +391,7 @@ peer_host's port stacks-node will connect to for RPC connections. Example: ```toml -rpc_port = 18443 +rpc_port = 8332 ``` #### peer_port @@ -392,7 +401,7 @@ peer_host's port stacks-node will connect to for P2P connections. Example: ```toml -peer_port = 18444 +peer_port = 8333 ``` #### process_exit_at_block_height (optional) @@ -435,11 +444,11 @@ Example: commit_anchor_block_within = 10000 ``` -### Section: ustx_balance +### Section: ustx_balance (testnet only) This section contains configuration options pertaining to the genesis block allocation for an address in micro-STX. If a user changes these values, their node may be in conflict with other nodes on the network and find themselves unable to sync with other nodes. --> This section can be repeated multiple times, and thus is in double-brackets. Each section can define only one address. +-> This section can repeat multiple times, and thus is in double-brackets. Each section can define only one address. This section is ignored if running a node on mainnet. Example: diff --git a/src/pages/start-mining/mainnet.md b/src/pages/start-mining/mainnet.md new file mode 100644 index 00000000..02220d02 --- /dev/null +++ b/src/pages/start-mining/mainnet.md @@ -0,0 +1,367 @@ +--- +title: Mine mainnet Stacks tokens +description: Set up and run a miner on the Stacks 2.0 mainnet +icon: MainnetIcon +experience: beginners +duration: 10 minutes +tags: + - tutorial +images: + large: /images/pages/start-mining.svg + sm: /images/pages/start-mining-sm.svg +--- + +## Introduction + +Make sure you've followed the [Running mainnet node](/understand-stacks/running-mainnet-node) tutorial. Once completed it's only a few more steps to run a proof-of-burn miner on the mainnet. + +[@page-reference | inline] +| /understand-stacks/running-mainnet-node + +If you're interested in mining on the testnet, you can find instructions on how to do that here: + +[@page-reference | inline] +| /start-mining/testnet + +If you want to learn more about the technical details of mining, please review the mining guide: + +[@page-reference | inline] +| /understand-stacks/mining + +## Running bitcoind locally + +To participate as a miner on mainnet, you must have access to a mainnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) + +First, download the bitcoind software for your platform from https://bitcoin.org/en/download. + +Next, start bitcoind with the following configuration: + +``` +server=1 +rpcuser=your-bitcoind-username +rpcpassword=your-bitcoind-password +txindex=0 +listen=1 +rpcserialversion=0 +maxorphantx=1 +banscore=1 +bind=0.0.0.0:8333 +rpcbind=0.0.0.0:8332 +rpcport=8332 +``` + +Finally, start bitcoind as follows: + +```bash +bitcoind -conf=path/to/bitcoin.conf +``` + +It may take a few days for the node to synchronize with the Bitcoin mainnet. + +## Running a miner + +First, a keychain needs to be generated. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. + +To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command. + +```bash +npx @stacks/cli make_keychain 2>/dev/null +``` + +After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: + +```json +{ + "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", + "keyInfo": { + "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", + "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", + "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", + "index": 0 + } +} +``` + +**Don't lose this information** - we'll need to use the `privateKey` field later on. + +The above BTC address will then need to be imported into the BTC network. + +```bash +bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress +``` + +Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). + +Now, we need to configure our node to use this Bitcoin keychain. In the `stacks-blockchain` folder, create a new file called `mainnet-miner-conf.toml`. + +Paste in the following configuration: + +```toml +[node] +rpc_bind = "0.0.0.0:20443" +p2p_bind = "0.0.0.0:20444" +# Enter your private key here +seed = "replace-with-your-private-key" +miner = true + +[burnchain] +chain = "bitcoin" +mode = "mainnet" +# peer_host should point to your local bitcoind node +peer_host = "127.0.0.1" +username = "your-bitcoind-username" +password = "your-bitcoind-password" +rpc_port = 8332 +peer_port = 8333 +``` + +Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. + +To run your miner, run this in the command line: + +```bash +stacks-node start --config=./mainnet-miner-conf.toml +``` + +Your node should start. It will take some time to sync, and then your miner will be running. + +### Creating an optimized binary + +The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: + +```bash +cd testnet/stacks-node +cargo build --release --bin stacks-node +``` + +The above code will compile an optimized binary. To use it, run: + +```bash +cd ../.. +./target/release/stacks-node start --config=./mainnet-miner-conf.toml +``` + +For a full reference of subcommands and configuration options used by `stacks-node`, please see this page. + +[@page-reference | inline] +| /references/stacks-node-configuration + +To read more about the technical details of mining on the Stacks 2.0 network, have a look at the minig guide: + +[@page-reference | inline] +| /understand-stacks/mining + +### Enable debug logging + +In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: + +```bash +BLOCKSTACK_DEBUG=1 stacks-node mainnet +``` + +## Running a miner in Windows + +### Prerequisites + +Make sure you've followed the [Running the mainnet node on Windows](/understand-stacks/running-mainnet-node#running-the-mainnet-node-on-windows) tutorial and [Running itcoind locally](#running-bitcoind-locally) section above before starting this tutorial. + +### Generate keychain and get mainnet tokens in Windows + +To setup the miner, first we need to generate a keychain. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. + +To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `stx make-keychain` command. + +Generate a keychain: + +```bash +npm install --global @stacks/cli +stx make_keychain > cli_keychain.json +type cli_keychain.json +``` + +After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: + +```json +{ + "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", + "keyInfo": { + "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", + "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", + "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", + "index": 0 + } +} +``` + +-> Check out the [Stacks CLI reference](/references/stacks-cli) for more details + +The above BTC address will then need to be imported into the BTC network. + +```bash +bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress +``` + +Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). + +### Create configuration file + +Now, we need to configure our node to use this Bitcoin keychain. In the **folder where your binary is extracted**, create a new file called `mainnet-miner-conf.toml`. + +Paste in the following configuration: + +```toml +[node] +rpc_bind = "0.0.0.0:20443" +p2p_bind = "0.0.0.0:20444" +# Enter your private key here +seed = "replace-with-your-private-key" +miner = true + +[burnchain] +chain = "bitcoin" +mode = "mainnet" +# peer_host should point to your local bitcoind node +peer_host = "127.0.0.1" +username = "your-bitcoind-username" +password = "your-bitcoind-password" +rpc_port = 8332 +peer_port = 8333 +``` + +Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. + +### Run the miner + +To start your miner, run this in the command line: + +```bash +stacks-node start --config=mainnet-miner-conf.toml +``` + +-> **Note** : While starting the node for the first time, windows defender might pop up with a message to allow access. If so, allow access to run the node. +![Windows Defender](/images/windows-defender.png) + +Your node should start. It will take some time to sync, and then your miner will be running. + +### Enable debug logging in Windows + +In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: + +```bash +set RUST_BACKTRACE=full; +set BLOCKSTACK_DEBUG=1; +stacks-node start --config=mainnet-miner-conf.toml +``` + +## Optional: Running with Docker + +Alternatively, you can run the mainnet node with Docker. + +-> Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. + +### Generate keychain and get tokens + +Generate a keychain: + +```bash +docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null +``` + +We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). + +### Create a config file directory + +You need a dedicated directory to keep the config files: + +```bash +mkdir -p $HOME/stacks +``` + +### Create config file + +Inside the new `$HOME/stacks` folder, you should create a new miner config `Config.toml`: + +```toml +[node] +rpc_bind = "0.0.0.0:20443" +p2p_bind = "0.0.0.0:20444" +# Enter your private key here +seed = "replace-with-your-private-key" +miner = true + +[burnchain] +chain = "bitcoin" +mode = "mainnet" +# peer_host should point to your local bitcoind node +peer_host = "127.0.0.1" +username = "your-bitcoind-username" +password = "your-bitcoind-password" +rpc_port = 8332 +peer_port = 8333 +``` + +### Start the miner + +-> The ENV VARS `RUST_BACKTRACE` and `BLOCKSTACK_DEBUG` are optional. If removed, debug logs will be disabled + +```bash +docker run -d \ + --name stacks_miner \ + --rm \ + --network host \ + -e RUST_BACKTRACE="full" \ + -e BLOCKSTACK_DEBUG="1" \ + -v "$HOME/stacks/Config.toml:/src/stacks-node/Config.toml" \ + -p 20443:20443 \ + -p 20444:20444 \ + blockstack/stacks-blockchain:latest \ +/bin/stacks-node start --config /src/stacks-node/Config.toml +``` + +You can review the node logs with this command: + +```bash +docker logs -f stacks_miner +``` + +## Optional: Running in Kubernetes with Helm + +In addition, you're also able to run a mainnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/blockstack/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). + +Ensure you have the following prerequisites installed on your machine: + +- [Docker](https://docs.docker.com/get-docker/) +- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) +- [helm](https://helm.sh/docs/intro/install/) + +### Generate keychain and get some tokens + +Generate a keychain: + +```bash +docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null +``` + +We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). + +### Install the chart and run the miner + +To install the chart with the release name `my-release` and run the node as a miner: + +```bash +minikube start # Only run this if standing up a local Kubernetes cluster +helm repo add blockstack https://charts.blockstack.xyz +helm install my-release blockstack/stacks-blockchain \ + --set config.node.miner=true \ + --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ + --set config.burnchain.mode="mainnet" +``` + +You can review the node logs with this command: + +```bash +kubectl logs -l app.kubernetes.io/name=stacks-blockchain +``` + +For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/blockstack/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/src/pages/start-mining.md b/src/pages/start-mining/testnet.md similarity index 94% rename from src/pages/start-mining.md rename to src/pages/start-mining/testnet.md index 57f9e621..8e6a81cd 100644 --- a/src/pages/start-mining.md +++ b/src/pages/start-mining/testnet.md @@ -1,5 +1,5 @@ --- -title: Mine Stacks tokens +title: Mine testnet Stacks tokens description: Set up and run a miner on the Stacks 2.0 testnet icon: TestnetIcon experience: beginners @@ -25,7 +25,7 @@ If you want to learn more about the technical details of mining, please review t ## Running bitcoind locally -To participate as a miner on Xenon, you must have access to a testnet bitcoin node. One way to accomplish this is to run bitcoind locally. You'll need a computer with ~10-GB disk space. +To participate as a miner on Xenon, you must have access to a testnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) First, download the bitcoind software for your platform from https://bitcoin.org/en/download. @@ -54,11 +54,11 @@ Finally, start bitcoind as follows: bitcoind -conf=path/to/bitcoin.conf ``` -It will take a few hours for the node to synchronize with the Bitcoin testnet -- be patient! +It may take a few hours for the node to synchronize with the Bitcoin testnet. ## Running a miner -First, we need to generate a keychain. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. +First, a keychain needs to be generated. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command, and pass `-t` to indicate that we want a testnet keychain. @@ -105,11 +105,9 @@ miner = true [burnchain] chain = "bitcoin" -mode = "xenon" # if connecting to Krypton, set this to "krypton" +mode = "xenon" # To mine on Xenon, you need to run bitcoind locally # Details can be found in above section, 'Running bitcoind locally' -# For Krypton, set peer_host to `bitcoind.krypton.blockstack.org` and -# omit `username` and `password` peer_host = "127.0.0.1" username = "your-bitcoind-username" password = "your-bitcoind-password" @@ -231,11 +229,9 @@ miner = true [burnchain] chain = "bitcoin" -mode = "xenon" # if connecting to Krypton, set this to "krypton" +mode = "xenon" # To mine on Xenon, you need to run bitcoind locally # Details can be found in above section, 'Running bitcoind locally' -# For Krypton, set peer_host to `bitcoind.krypton.blockstack.org` and -# omit `username` and `password` peer_host = "127.0.0.1" username = "your-bitcoind-username" password = "your-bitcoind-password" @@ -320,11 +316,9 @@ miner = true [burnchain] chain = "bitcoin" -mode = "xenon" # if connecting to Krypton, set this to "krypton" +mode = "xenon" # To mine on Xenon, you need to run bitcoind locally # Details can be found in above section, 'Running bitcoind locally' -# For Krypton, set peer_host to `bitcoind.krypton.blockstack.org` and -# omit `username` and `password` peer_host = "127.0.0.1" username = "your-bitcoind-username" password = "your-bitcoind-password" diff --git a/src/pages/understand-stacks/running-mainnet-node.md b/src/pages/understand-stacks/running-mainnet-node.md new file mode 100644 index 00000000..a1f82a11 --- /dev/null +++ b/src/pages/understand-stacks/running-mainnet-node.md @@ -0,0 +1,242 @@ +--- +title: Running a mainnet node +description: Learn how to set up and run a mainnet node +icon: MainnetIcon +duration: 15 minutes +experience: beginners +tags: + - tutorial +images: + large: /images/pages/mainnet.svg + sm: /images/pages/mainnet-sm.svg +--- + +## Introduction + +This tutorial will walk you through the following steps: + +- Download and install the node software +- Run the node +- Mine Stacks token + +## Requirements + +In order to run a node, some software and hardware requirements need to be considered. + +### Hardware + +Running a node has no specialized hardware requirements. People were successful at running a node on Raspberry Pis, for instance. +Minimum requirements are moving targets due to the nature of the project and some factors should be considered: + +- compiling node sources locally requires computing and storage resources +- as the chain grows, the on-disk state will grow over time + +With these considerations in mind, we suggest hardware based on a general-purpose specification, similarly to [GCP E2 machine standard 2](https://cloud.google.com/compute/docs/machine-types#general_purpose) or [AWS EC2 t3.large standard](https://aws.amazon.com/ec2/instance-types/): + +- 2 vCPUs +- 8 GB memory +- ~50-GB disk (preferably SSDs) + +It is also recommended to run the node with a publicly routable IP, that way other peers in the network will be able to connect to it. + +### Software + +If you use Linux, you may need to manually install [`libssl-dev`](https://wiki.openssl.org/index.php/Libssl_API) and other packages. In your command line, run the following to get all packages: + +```bash +sudo apt-get install build-essential cmake libssl-dev pkg-config +``` + +Ensure that you have Rust installed. If you are using macOS, Linux, or another Unix-like OS, run the following. If you are on a different OS, follow the [official Rust installation guide](https://www.rust-lang.org/tools/install). + +```bash +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y +``` + +In case you just installed Rust, you will be prompted to run the following command to make the `cargo` command available: + +```bash +source $HOME/.cargo/env +``` + +## Installing the node from pre-built binary + +### Step 1: Get the distributable + +Download and unzip the distributable which cooresponds to your environment [from the latest release](https://github.com/blockstack/stacks-blockchain/releases/latest). + +If you're running on Windows, [please follow our instructions from installing a node on Windows.](#running-the-mainnet-node-on-windows) + +### Step 2: Run the binary + +To run the `stacks-node` binary, execute the following: + +```bash +./stacks-node mainnet +``` + +**Awesome. Your node is now connected to the mainnet network.** + +Your node will receive new blocks when they are produced, and you can use the [Stacks Node RPC API](/understand-stacks/stacks-blockchain-api#proxied-stacks-node-rpc-api-endpoints) to send transactions, fetch information for contracts and accounts, and more. + +## Installing the node from source + +You might want to build and install from source if there are some updates in the [main branch](https://github.com/blockstack/stacks-blockchain) which aren't yet released, or if there is no pre-built binary for your environment. + +### Step 1: Install the node + +Clone this repository: + +```bash +git clone https://github.com/blockstack/stacks-blockchain.git; cd stacks-blockchain +``` + +Install the Stacks node by running: + +```bash +cargo build --workspace --release --bin stacks-node +# binary will be in target/release/stacks-node +``` + +To install Stacks node with extra debugging symbols, run: + +```bash +cargo build --workspace --bin stacks-node +# binary will be in target/debug/stacks-node +``` + +-> This process will take a few minutes to complete + +### Step 2: Run the node + +You're all set to run a node that connects to the mainnet network. + +If installed without debugging symbols, run: + +```bash +target/release/stacks-node mainnet +``` + +If installed with debugging symbols, run: + +```bash +target/debug/stacks-node mainnet +``` + +The first time you run this, you'll see some logs indicating that the Rust code is being compiled. Once that's done, you should see some logs that look something like the this: + +```bash +INFO [1588108047.585] [src/chainstate/stacks/index/marf.rs:732] First-ever block 0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206 +``` + +## Running the mainnet node on Windows + +### Prerequisites + +Before you begin, check that you have the below necessary softwares installed on your PC + +- [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/). + +-> **Tip**: While installing the Microsoft Visual Studio Build tools using the above link, select the C++ Build tools option when prompted. +![C++ Build Tools](/images/C++BuildTools.png) + +- [NodeJs](https://nodejs.org/en/download/). +- [Git](https://git-scm.com/downloads). + +#### Optional Dependencies + +- [Python](https://www.python.org/downloads/). +- [Rust](https://www.rust-lang.org/tools/install). + +### Download the Binary and run the follower node + +-> **Note**: Please make sure to download the new Binary and follow the below steps as and when a [new release build](https://github.com/blockstack/stacks-blockchain/releases/latest) is available. + +First, Visit the [Stacks Github releases repo](https://github.com/blockstack/stacks-blockchain/releases/latest). From the various binary list, click to download the Windows binary. Refer the image below. +![BinaryList](/images/mining-windows.png) + +Next, click on save file and Press **Ok** in the popup window. +![Windowspopup](/images/mining-windows-popup.png) + +Once saved, Extract the binary. Open the command prompt **from the folder where binary is extracted** and execute the below command: + +```bash +stacks-node mainnet +# This command will start the mainnet follower node. +``` + +-> **Note** : While starting the node for the first time, windows defender will pop up with a message to allow access. If so, allow access to run the node. +![Windows Defender](/images/windows-defender.png) + +To execute Stacks node with extra debugging enabled, run: + +```bash +set RUST_BACKTRACE=full +set BLOCKSTACK_DEBUG=1 +stacks-node mainnet +# This command will execute the binary and start the follower node with debug enabled. +``` + +The first time you run this, you'll see some logs indicating that the Rust code is being compiled. Once that's done, you should see some logs that look something like the this: + +```bash +INFO [1588108047.585] [src/chainstate/stacks/index/marf.rs:732] First-ever block 0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206 +``` + +**Awesome. Your node is now connected to the mainnet network.** + +## Optional: Running with Docker + +Alternatively, you can run the mainnet node with Docker. + +-> Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. + +```bash +docker run -d \ + --name stacks_follower \ + -p 20443:20443 \ + -p 20444:20444 \ + blockstack/stacks-blockchain \ + stacks-node mainnet +``` + +-> To enable debug logging, add the ENV VARS `RUST_BACKTRACE="full"` and `BLOCKSTACK_DEBUG="1"`. + +You can review the node logs with this command: + +```bash +docker logs -f stacks_follower +``` + +## Optional: Running in Kubernetes with Helm + +In addition, you're also able to run a mainnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/blockstack/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). + +Ensure you have the following prerequisites installed on your machine: + +- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) +- [helm](https://helm.sh/docs/intro/install/) + +To install the chart with the release name `my-release` and run the node as a follower: + +```bash +minikube start # Only run this if standing up a local Kubernetes cluster +helm repo add blockstack https://charts.blockstack.xyz +helm install my-release blockstack/stacks-blockchain +``` + +You can review the node logs with this command: + +```bash +kubectl logs -l app.kubernetes.io/name=stacks-blockchain +``` + +For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/blockstack/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). + +## Optional: Mining Stacks token + +Now that you have a running mainnet node, you can easily set up a miner. + +[@page-reference | inline] +| /start-mining diff --git a/src/pages/understand-stacks/running-testnet-node.md b/src/pages/understand-stacks/running-testnet-node.md index 3c2bffe2..d5e3460a 100644 --- a/src/pages/understand-stacks/running-testnet-node.md +++ b/src/pages/understand-stacks/running-testnet-node.md @@ -41,8 +41,6 @@ With these considerations in mind, we suggest hardware based on a general-purpos It is also recommended to run the node with a publicly routable IP, that way other peers in the network will be able to connect to it. --> There is no difference in hardware you need to run a node versus a miner - ### Software If you use Linux, you may need to manually install [`libssl-dev`](https://wiki.openssl.org/index.php/Libssl_API) and other packages. In your command line, run the following to get all packages: @@ -63,9 +61,33 @@ In case you just installed Rust, you will be prompted to run the following comma source $HOME/.cargo/env ``` -## Step 1: Installing the node +## Installing the node from pre-built binary + +### Step 1: Get the distributable + +Download and unzip the distributable which cooresponds to your environment [from the latest release](https://github.com/blockstack/stacks-blockchain/releases/latest). -Next, clone this repository: +If you're running on Windows, [please follow our instructions from installing a node on Windows.](#running-the-testnet-node-on-windows) + +### Step 2: Run the binary + +To run the `stacks-node` binary, execute the following: + +```bash +./stacks-node xenon +``` + +**Awesome. Your node is now connected to the testnet network.** + +Your node will receive new blocks when they are produced, and you can use the [Stacks Node RPC API](/understand-stacks/stacks-blockchain-api#proxied-stacks-node-rpc-api-endpoints) to send transactions, fetch information for contracts and accounts, and more. + +## Installing the node from source + +You might want to build and install from source if there are some updates in the [main branch](https://github.com/blockstack/stacks-blockchain) which aren't yet released, or if there is no pre-built binary for your environment. + +### Step 1: Install the node + +Clone this repository: ```bash git clone https://github.com/blockstack/stacks-blockchain.git; cd stacks-blockchain @@ -87,7 +109,7 @@ cargo build --workspace --bin stacks-node -> This process will take a few minutes to complete -## Step 2: Running the node +### Step 2: Run the node You're all set to run a node that connects to the testnet network. @@ -109,10 +131,6 @@ The first time you run this, you'll see some logs indicating that the Rust code INFO [1588108047.585] [src/chainstate/stacks/index/marf.rs:732] First-ever block 0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206 ``` -**Awesome. Your node is now connected to the testnet network.** - -Your node will receive new blocks when they are produced, and you can use the [Stacks Node RPC API](/understand-stacks/stacks-blockchain-api#proxied-stacks-node-rpc-api-endpoints) to send transactions, fetch information for contracts and accounts, and more. - ## Running the testnet node on Windows ### Prerequisites @@ -171,25 +189,20 @@ INFO [1588108047.585] [src/chainstate/stacks/index/marf.rs:732] First-ever block ## Optional: Running with Docker -Alternatively, you can run the testnet node with Docker. +Alternatively, you can run the mainnet node with Docker. -> Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. --> The ENV VARS `RUST_BACKTRACE` and `BLOCKSTACK_DEBUG` are optional. If removed, debug logs will be disabled - ```bash docker run -d \ --name stacks_follower \ - --rm \ - -e RUST_BACKTRACE="full" \ - -e BLOCKSTACK_DEBUG="1" \ -p 20443:20443 \ -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node xenon + blockstack/stacks-blockchain \ + stacks-node xenon ``` --> The ENV VARS `RUST_BACKTRACE` and `BLOCKSTACK_DEBUG` are optional. If removed, debug logs will be disabled +-> To enable debug logging, add the ENV VARS `RUST_BACKTRACE="full"` and `BLOCKSTACK_DEBUG="1"`. You can review the node logs with this command: