From ce1a1a4cf30bf5754db29fda8137362f97a6d7cd Mon Sep 17 00:00:00 2001 From: CharlieC3 <2747302+CharlieC3@users.noreply.github.com> Date: Tue, 20 Apr 2021 15:10:40 -0400 Subject: [PATCH] docs: adding regtest docs --- public/images/pages/regtest-sm.svg | 10 + public/images/pages/regtest.svg | 5 + src/common/navigation.yaml | 2 + .../custom-blocks/page-reference.tsx | 6 + src/pages/404.md | 2 +- src/pages/index.md | 2 +- .../references/stacks-node-configuration.md | 6 +- src/pages/understand-stacks/regtest.md | 34 +++ .../understand-stacks/running-mainnet-node.md | 2 +- .../understand-stacks/running-regtest-node.md | 250 ++++++++++++++++++ .../understand-stacks/running-testnet-node.md | 6 +- src/pages/understand-stacks/testnet.md | 2 +- 12 files changed, 316 insertions(+), 11 deletions(-) create mode 100644 public/images/pages/regtest-sm.svg create mode 100644 public/images/pages/regtest.svg create mode 100644 src/pages/understand-stacks/regtest.md create mode 100644 src/pages/understand-stacks/running-regtest-node.md diff --git a/public/images/pages/regtest-sm.svg b/public/images/pages/regtest-sm.svg new file mode 100644 index 00000000..3ad8d2be --- /dev/null +++ b/public/images/pages/regtest-sm.svg @@ -0,0 +1,10 @@ + + + + + + + + + + diff --git a/public/images/pages/regtest.svg b/public/images/pages/regtest.svg new file mode 100644 index 00000000..f19961f9 --- /dev/null +++ b/public/images/pages/regtest.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/src/common/navigation.yaml b/src/common/navigation.yaml index d4ac0536..b0be8e79 100644 --- a/src/common/navigation.yaml +++ b/src/common/navigation.yaml @@ -5,6 +5,7 @@ sections: pages: - path: /overview - path: /testnet + - path: /regtest - path: /proof-of-transfer - path: /mining - path: /accounts @@ -22,6 +23,7 @@ sections: - path: /sending-tokens - path: /running-mainnet-node - path: /running-testnet-node + - path: /running-regtest-node - path: /integrate-stacking - path: /integrate-stacking-delegation - path: /stacking-using-CLI diff --git a/src/components/custom-blocks/page-reference.tsx b/src/components/custom-blocks/page-reference.tsx index c646b25f..2a9f6284 100644 --- a/src/components/custom-blocks/page-reference.tsx +++ b/src/components/custom-blocks/page-reference.tsx @@ -238,6 +238,12 @@ const getIcon = (icon: string) => { ); + case 'RegtestIcon': + return (p: BoxProps) => ( + + + + ); case 'TestnetIcon': return (p: BoxProps) => ( diff --git a/src/pages/404.md b/src/pages/404.md index 2ad8d85d..c229987f 100644 --- a/src/pages/404.md +++ b/src/pages/404.md @@ -25,7 +25,7 @@ Looks like the page you are looking for isn't here. Try out some of these popula ## Start mining [@page-reference | grid] -| /start-mining/mainnet, /start-mining/testnet, /understand-stacks/running-testnet-node, /understand-stacks/running-mainnet-node +| /start-mining/mainnet, /start-mining/testnet, /understand-stacks/running-mainnet-node, /understand-stacks/running-testnet-node, /understand-stacks/running-regtest-node ## Ecosystem diff --git a/src/pages/index.md b/src/pages/index.md index ce80a416..44aaf8b7 100644 --- a/src/pages/index.md +++ b/src/pages/index.md @@ -21,7 +21,7 @@ description: Write Clarity smart contracts, build apps, and starting mining with ## Start mining [@page-reference | grid] -| /start-mining/mainnet, /start-mining/testnet, /understand-stacks/running-testnet-node, /understand-stacks/running-mainnet-node +| /start-mining/mainnet, /start-mining/testnet, /understand-stacks/running-mainnet-node, /understand-stacks/running-testnet-node, /understand-stacks/running-regtest-node ## Ecosystem diff --git a/src/pages/references/stacks-node-configuration.md b/src/pages/references/stacks-node-configuration.md index 1a56138f..48318a90 100644 --- a/src/pages/references/stacks-node-configuration.md +++ b/src/pages/references/stacks-node-configuration.md @@ -27,9 +27,9 @@ Example: stacks-node mocknet ``` -### krypton (deprecated) +### krypton -Start a node that will join and stream blocks from the public krypton testnet, powered by Blockstack via [Proof of Transfer](/understand-stacks/overview#proof-of-transfer-pox). +Start a node that will join and stream blocks from the public krypton regtest, powered by Blockstack via [Proof of Transfer](/understand-stacks/overview#proof-of-transfer-pox). Example: @@ -467,7 +467,7 @@ Example: commit_anchor_block_within = 10000 ``` -### Section: ustx_balance (testnet only) +### Section: ustx_balance (testnet/regtest 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. diff --git a/src/pages/understand-stacks/regtest.md b/src/pages/understand-stacks/regtest.md new file mode 100644 index 00000000..1656f055 --- /dev/null +++ b/src/pages/understand-stacks/regtest.md @@ -0,0 +1,34 @@ +--- +title: Regtest +description: Test your smart contracts and apps +images: + large: /images/pages/regtest.svg + sm: /images/pages/regtest-sm.svg +--- + +## About regtest + +The regtest is a separate blockchain from the Stacks mainnet analogous to a development environnment. Similar to the testnet, it's a network used by developers to test their apps, smart contracts, or changes to the protocol in a production-like environment. However, it differs by producing a new BTC and STX block every two minutes, making it much more suitable for rapid development. The regtest is reset frequently. + +## Regtest nodes + +If you would like to run your own regtest node, please follow these steps: + +[@page-reference | inline] +| /understand-stacks/running-regtest-node + +## Regtest API + +The hosted [Stacks Blockchain API](/understand-stacks/stacks-blockchain-api) for the regtest is available at this base URL: + +```shell +https://stacks-node-api.regtest.stacks.co/ +``` + +### Faucet + +The regtest faucet provides you with free Stacks Token (STX) to test with. These are not the same as STX on mainnet and have no value. You can get STX from the faucet on the [Stacks Explorer Sandbox](https://explorer.stacks.co/sandbox?chain=regtest), or using the [API](https://blockstack.github.io/stacks-blockchain-api/#tag/Faucets). + +To get STX tokens from within the Explorer Sandbox, navigate to the "Faucet" tab and click on "Request STX" button. If you would like to get enough STX tokens to try out [Stacking](/understand-stacks/stacking), you should click on "I want to stack". + +> The Explorer Sandbox requires you to login with a Secret Key diff --git a/src/pages/understand-stacks/running-mainnet-node.md b/src/pages/understand-stacks/running-mainnet-node.md index 49c56be5..0932797a 100644 --- a/src/pages/understand-stacks/running-mainnet-node.md +++ b/src/pages/understand-stacks/running-mainnet-node.md @@ -16,7 +16,7 @@ images: This tutorial will walk you through the following steps: - Download and install the node software -- Run the node +- Run the node against mainnet - Mine Stacks token ## Requirements diff --git a/src/pages/understand-stacks/running-regtest-node.md b/src/pages/understand-stacks/running-regtest-node.md new file mode 100644 index 00000000..cd378e1c --- /dev/null +++ b/src/pages/understand-stacks/running-regtest-node.md @@ -0,0 +1,250 @@ +--- +title: Running a regtest node +description: Learn how to set up and run a regtest node +icon: RegtestIcon +duration: 15 minutes +experience: beginners +tags: + - tutorial +images: + large: /images/cli.svg + sm: /images/cli.svg +--- + +## Introduction + +-> Note: The Stacks 2.0 regtest is similar to the testnet, however BTC and STX blocks are produced at a much faster rate at 1 block every 2 minutes. Making it ideal for rapid development. + +This tutorial will walk you through the following steps: + +- Download and install the node software +- Run the node against regtest +- 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-regtest-node-on-windows) + +### Step 2: Run the binary + +To run the `stacks-node` binary, execute the following: + +```bash +./stacks-node krypton +``` + +**Awesome. Your node is now connected to the regtest 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 +``` + +Change the below values to reflect the version, branch, and git commit of the source code being built for accuracy: + +```bash +# The following values are just an example +export STACKS_NODE_VERSION=2.0.9 +export GIT_BRANCH=master +export GIT_COMMIT=e7f178b +``` + +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 regtest network. + +If installed without debugging symbols, run: + +```bash +target/release/stacks-node krypton +``` + +If installed with debugging symbols, run: + +```bash +target/debug/stacks-node krypton +``` + +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 regtest 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 krypton +# This command will start the regtest 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 STACKS_LOG_DEBUG=1 +stacks-node krypton +# 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 regtest network.** + +## Optional: Running with Docker + +Alternatively, you can run the regtest 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 krypton +``` + +-> To enable debug logging, add the ENV VARS `RUST_BACKTRACE="full"` and `STACKS_LOG_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 regtest 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 + +Mining is not currently available on the Stacks regtest. diff --git a/src/pages/understand-stacks/running-testnet-node.md b/src/pages/understand-stacks/running-testnet-node.md index 015dc3f1..4fd65bbc 100644 --- a/src/pages/understand-stacks/running-testnet-node.md +++ b/src/pages/understand-stacks/running-testnet-node.md @@ -13,12 +13,10 @@ images: ## Introduction --> Note: The Stacks 2.0 testnet is currently in development. As part of the testnet, you can run a node and connect it to a public network. - This tutorial will walk you through the following steps: - Download and install the node software -- Run the node +- Run the node against testnet - Mine Stacks token ## Requirements @@ -198,7 +196,7 @@ INFO [1588108047.585] [src/chainstate/stacks/index/marf.rs:732] First-ever block ## Optional: Running with Docker -Alternatively, you can run the mainnet node with Docker. +Alternatively, you can run the testnet node with Docker. -> Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. diff --git a/src/pages/understand-stacks/testnet.md b/src/pages/understand-stacks/testnet.md index 27ba003b..76cdcf29 100644 --- a/src/pages/understand-stacks/testnet.md +++ b/src/pages/understand-stacks/testnet.md @@ -8,7 +8,7 @@ images: ## About testnet -The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnment. It's a network used by developers to test their apps, smart contracts, or changes to the protocol in a production-like environment. The testnet is reset frequently. +The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnment. It's a network used by developers to test their apps, smart contracts, or changes to the protocol in a production-like environment. ## Testnet nodes