Merge pull request #6 from rrybarczyk/2024.07-improve-setup-instructions

plebhash · web-flow · commit 631206267340 · 2024-07-14T23:23:17.000-03:00
Clarify setup specific instructions
diff --git a/README.md b/README.md
@@ -1,70 +1,198 @@
+# sv2-workshop
 This repository contains materials for a [StratumV2 Reference Implementation](https://github.com/stratum-mining/stratum) workshop.
 
-# Slides
-Slides leverage [`marp`](https://marp.app/). They are compiled from `md` to `html` via `marp.sh` (which assumes nix flakes are available on your system).
+* For useful materials see the [materials/](https://github.com/stratum-mining/sv2-workshop/blob/main/materials) directory.
 
-As an alternative to `marp.sh`, you can just install `marp` on the system and do:
-```
+These instructions cover the setup required for the instructor running the Stratum V2 workshop.
+
+1. Configuring and hosting the slides to be accessible by the participants.
+2. Configuring a publicly accessible Genesis node for participants to sync their nodes.
+3. Configuring the block explorer to display participants' mined blocks.
+
+## Slides
+
+### Config
+The `html/index.html` is built with [`marp`](https://marp.app/) and is based on the
+[`md/sv2-workshop.md`](https://github.com/stratum-mining/sv2-workshop/blob/main/md/sv2-workshop.md)
+file, and is committed to this repo.
+To generate the `html/index.html` file on changes to `sv2-workshop.md`, install `marp` on your
+system and run:
+
+```sh
 marp md/sv2-workshop.md -o html/sv2-workshop.html --theme-set css/sv2-workshop.css
 ```
 
-The slides can be served via:
+Or, if using `nix`, run (assuming nix flakes are available):
+
+```sh
+nix run github:tweag/nix-marp -- md/sv2-workshop.md -o html/sv2-workshop.html --theme-set css/sv2-workshop.css
 ```
-cd html
+
+### Run
+Serve the slides:
+
+```sh
 python3 -m http.server 8888
 ```
 
-# Custom Signet
-Which network should we do our workshop?
+To make the slides accessible on the SRI VM for participants to view on their machines:
 
-- `testnet3`? Well, [Lopp broke it](https://blog.lopp.net/griefing-bitcoin-testnet/).
-- `signet`? Well, we need the audience to be able to mine blocks.
-- `testnet4`? Well, we want a controlled hashrate environment.
+1. Remote into the SRI VM.
+2. Create a new `tmux` session.
+3. `cd ~/sv2-workshop`.
+4. Make sure the correct `workshop` branch (or branch of your choosing) is checked out.
+5. Run the HTTP server.
 
-Therefore, this workshop is based on a custom signet that does not require coinbase signatures. This way, the audience can deploy pools + hashers and emulate a confined hashrate environment.
+> Note: This can be done on any machine, however the slides specifically point the user to the SRI
+VM URL. If you choose to host the slides on another machine, remember to update the slides with the
+update endpoint.
 
-The `signet_genesis_node.sh` is responsible for:
-- Deploy a local signet.
-- Mine 16 blocks as bootstrapping for the SRI pool.
+## Custom Signet
+This workshop uses a custom `signet` for the following reasons:
 
-In order to use this script, you should first export some environment variables. For example:
-```
+- We want a confined hashrate environment, so `mainnet`, `testnet3`, `testnet4` and the public `signet` are ill suited.
+- `regtest` is too isolated and requires manual block generation, which is not practical for a collaborative workshop setting.
+- We will mine on a custom `signet` that does not require coinbase signatures.
+- This way, we can deploy pools + hashers and emulate a confined hashrate environment.
+
+Participants will connect to this Genesis node to sync their blocks.
+
+### Genesis Node
+The instructor can use the existing Genesis node hosted on the SRI VM, or spin up their own. The
+Genesis node should be configured via the [materials/signet-genesis-node.sh](https://github.com/stratum-mining/sv2-workshop/blob/main/materials/signet-genesis-node.sh) script which:
+
+* Deploys a local signet.
+* Mines 16 blocks as bootstrapping for the SRI pool.
+
+Before executing the script, ensure the following environment variables are defined:
+
+```sh
 $ export BITCOIND=$HOME/bitcoin/src/bitcoind
 $ export BITCOIN_CLI=$HOME/bitcoin/src/bitcoin-cli
 $ export BITCOIN_UTIL=$HOME/bitcoin/src/bitcoin-util
 $ export MINER=$HOME/bitcoin/contrib/signet/miner
 $ export BITCOIN_DATA_DIR=$HOME/.bitcoin
 ```
 
-# Blockchain Explorer
+#### SRI Node
+A Genesis node that is publicly accessible is needed for participants to sync their Bitcoin nodes.
+This can be set up by the instructor or use the existing SRI VM node.
+
+If using the SRI hosted Genesis node, verify it is running by remoting into the SRI VM and finding
+its process:
+
+```sh
+ps -ef | grep -i bitcoind
+> sri 3935787 1 0 Jun29 ? 01:19:13 /home/sri/btc_prague_workshop/bitcoin/src/bitcoind -signet -datadir=/home/sri/btc_prague_workshop/bitcoin_data_dir/ -fallbackfee=0.01 -daemon -sv2 -sv2port=38442
+```
+
+If spinning up a new node, see the instructions to install `bitcoin-core` in the Block Explorer
+section below.
+
+## Block Explorer
+A block explorer is needed to display participants' mined blocks on the custom `signet`. A custom
+`signet` Bitcoin node, [`electrs`](https://github.com/romanz/electrs), and
+[`mempool.space`](https://github.com/mempool/mempool) is used for this purpose.
+
+> Note: The steps for deploying a local `mempool.space` have not yet been automated and will need to
+be performed manually.
 
-In order to allow the audience to explore the blockchain, it's also recommended to provide a blockchain explorer.
+> Note: The Genesis node can also be used for this purpose. A second Bitcoin node for the block
+explorer only is needed if the instructor is running the block explorer on another machine (like
+their local machine).
 
-The steps for deploying a local `mempool.space` have not yet been automated, so they need to be performed manually.
+### Custom Signet `bitcoin-core`
 
-First, clone and start `electrs`:
+#### Install
+Install the required `bitcoin-core` fork by building from
+[Sjors's `sv2-tp-0.1.3` tag](https://github.com/Sjors/bitcoin/tree/sv2-tp-0.1.3):
+
+  ```sh
+  git clone https://github.com/Sjors/bitcoin.git
+  cd bitcoin
+  git fetch --all
+  git checkout sv2-tp-0.1.3
+  ./autogen.sh
+  ./configure --disable-tests --disable-bench --enable-wallet --with-gui=no
+  make  # or `make -j <num cores>`
+  ```
+
+Or alternatively via `nix`:
+  ```sh
+  git clone https://github.com/plebhash/nix-bitcoin-core-archive
+  cd nix-bitcoin-core-archive/fork/sv2
+  nix-build   # the executables are available at `result/bin`
+  ```
+
+#### Config
+Ensure the [`bitcoin.conf`](https://github.com/stratum-mining/sv2-workshop/blob/main/materials/block-explorer-bitcoin.conf)
+in the `datadir` contains:
+
+```conf
+[signet]
+signetchallenge=51      # OP_TRUE
+prune=0
+txindex=1
+server=1
+connect=75.119.150.111  # Genesis Node
+rpcallowip=0.0.0.0/0
+rpcbind=0.0.0.0
+rpcuser=mempool
+rpcpassword=mempool
+```
+
+#### Run
+Add the Bitcoin binaries to `$PATH`:
+```sh
+echo 'export PATH="$HOME/bitcoin/src:$PATH"' >> ~/.bashrc && export PATH="$HOME/bitcoin/src:$PATH"
 ```
-$ git clone https://github.com/romanz/electrs
-$ cd electrs
-$ git checkout v0.10.5
-$ cat << EOF > electrs.toml
+
+Start the Bitcoin node:
+
+```sh
+bitcoind -datadir=$HOME/.bitcoin-sv2-workshop -signet -sv2
+```
+
+### `electrs`
+
+#### Install
+Clone, checkout the `v0.10.5` branch, and configure:
+
+```sh
+git clone https://github.com/romanz/electrs
+cd electrs
+git checkout v0.10.5
+cat << EOF > electrs.toml
 network="signet"
 auth="mempool:mempool"
 EOF
-$ cargo run -- --signet-magic=54d26fbd
 ```
 
-Then, clone `mempool`:
+#### Run
+Run the server:
+
+```sh
+cargo run -- --signet-magic=54d26fbd
 ```
-$ git clone https://github.com/mempool/mempool
-$ cd mempool
-$ git checkout v2.5.0
+
+### `mempool.space`
+
+#### Install
+Clone and checkout the `v2.5.0` branch:
+
+```sh
+git clone https://github.com/mempool/mempool
+cd mempool
+git checkout v2.5.0
 ```
 
-We are going to use the docker deployment, so we need to adjust some configs.
-```diff
+#### Config
+The docker deployment is used with the following adjustments to the `docker/docker-compose.yml`:
+
+```sh
+git diff docker/docker-compose.yml
 diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
-index 68e73a1c8..98fa6a174 100644
+index 68e73a1c8..300aa3d80 100644
 --- a/docker/docker-compose.yml
 +++ b/docker/docker-compose.yml
 @@ -14,9 +14,12 @@ services:
@@ -73,18 +201,23 @@ index 68e73a1c8..98fa6a174 100644
      environment:
 -      MEMPOOL_BACKEND: "none"
 +      MEMPOOL_BACKEND: "electrum"
-+      ELECTRUM_HOST: "172.27.0.1"
-+      ELECTRUM_PORT: "50002"
++      ELECTRUM_HOST: "host.docker.internal"  # or the IP address of the Electrum server
++      ELECTRUM_PORT: "60601"  # match this with the port on which electrs is listening
 +      ELECTRUM_TLS_ENABLED: "false"
-       CORE_RPC_HOST: "172.27.0.1"
+-      CORE_RPC_HOST: "172.27.0.1"
++      CORE_RPC_HOST: "host.docker.internal"
 -      CORE_RPC_PORT: "8332"
 +      CORE_RPC_PORT: "38332"
        CORE_RPC_USERNAME: "mempool"
        CORE_RPC_PASSWORD: "mempool"
        DATABASE_ENABLED: "true"
 ```
 
-From the `docker` directory, you can start it via:
+#### Run
+Start the docker container:
+
+```sh
+docker-compose up
 ```
-$ docker-compose up
-```
+
+Navigate to the exposed `localhost` endpoint.
diff --git a/html/sv2-workshop.html b/html/sv2-workshop.html
diff --git a/marp.sh b/marp.sh
diff --git a/materials/README.md b/materials/README.md
@@ -0,0 +1,6 @@
+# Materials
+Useful configuration files or other materials both the instructor and participants.
+
+## Instructor
+* [`block-explorer-bitcoin.conf`](https://github.com/stratum-mining/sv2-workshop/blob/main/materials/block-explorer-bitcoin.conf): `bitcoin.conf` for the node use with the block explorer.
+* [`signet-genesis-node.sh`](https://github.com/stratum-mining/sv2-workshop/blob/main/materials/signet-genesis-node.sh): Genesis node setup script.
diff --git a/materials/block-explorer-bitcoin.conf b/materials/block-explorer-bitcoin.conf
@@ -0,0 +1,11 @@
+[signet]
+signetchallenge=51      # OP_TRUE
+prune=0
+txindex=1
+server=1
+connect=75.119.150.111  # Genesis Node
+rpcallowip=0.0.0.0/0
+rpcbind=0.0.0.0
+rpcuser=mempool
+rpcpassword=mempool
+
diff --git a/materials/signet-genesis-node.sh b/materials/signet-genesis-node.sh
@@ -1,4 +1,18 @@
 #!/bin/bash
+#
+# Genesis Node Setup
+#
+# - Deploys a local signet.
+# - Mines 16 blocks as bootstrapping for the SRI pool.
+#
+# Ensure the following environment variables are set:
+#
+# $BITCOIND=$HOME/bitcoin/src/bitcoind
+# $BITCOIN_CLI=$HOME/bitcoin/src/bitcoin-cli
+# $BITCOIN_UTIL=$HOME/bitcoin/src/bitcoin-util
+# $MINER=$HOME/bitcoin/contrib/signet/miner
+# $BITCOIN_DATA_DIR=$HOME/.bitcoin
+#
 
 # Check if the environment variables are set
 if [ -z "$BITCOIND" ] || [ -z "$BITCOIN_CLI" ] || [ -z "$BITCOIN_UTIL" ] || [ -z "$BITCOIN_DATA_DIR" ] || [ -z "$MINER" ]; then
@@ -52,4 +66,3 @@ done
 
 echo "script finalized... running getblockchaininfo as the last step"
 $BITCOIN_CLI -signet -datadir=$BITCOIN_DATA_DIR getblockchaininfo
-
diff --git a/md/sv2-workshop.md b/md/sv2-workshop.md
@@ -35,15 +35,24 @@ git checkout workshop
 
 ## Get a release from SV2 Bitcoin Core fork
 
-Grab a release from https://github.com/plebhash/bitcoin/releases/tag/btc-prague
+Install the required `bitcoin-core` fork by building from [Sjors's `sv2-tp-0.1.3` tag](https://github.com/Sjors/bitcoin/tree/sv2-tp-0.1.3):
+
+  ```sh
+  git clone https://github.com/Sjors/bitcoin.git
+  cd bitcoin
+  git fetch --all
+  git checkout sv2-tp-0.1.3
+  ./autogen.sh
+  ./configure --disable-tests --disable-bench --enable-wallet --with-gui=no
+  make  # or `make -j <num cores>`
+  ```
 
 Or alternatively via `nix`:
-```
-git clone https://github.com/plebhash/nix-bitcoin-core-archive
-cd nix-bitcoin-core-archive/fork/sv2
-nix-build
-# the executables are available at `result/bin`
-```
+  ```sh
+  git clone https://github.com/plebhash/nix-bitcoin-core-archive
+  cd nix-bitcoin-core-archive/fork/sv2
+  nix-build   # the executables are available at `result/bin`
+  ```
 
 ---
 
@@ -207,10 +216,15 @@ loglevel=sv2:debug
 
 ## Start `bitcoind` Template Provider
 
-assuming `$TP` is the path to `bitcoind`:
-
+Add the Bitcoin binaries to `$PATH`:
+```sh
+echo 'export PATH="$HOME/bitcoin/src:$PATH"' >> ~/.bashrc && export PATH="$HOME/bitcoin/src:$PATH"
 ```
-$TP -datadir=$HOME/.bitcoin-sv2-workshop -signet -sv2
+
+Start the Bitcoin node:
+
+```sh
+bitcoind -datadir=$HOME/.bitcoin-sv2-workshop -signet -sv2
 ```
 
 ---
@@ -232,24 +246,22 @@ Miners can jump to slide 28
 
 ## Create wallet (Pool)
 
-assuming `$CLI` is the path to `bitcoin-cli`
-
 ```
-$CLI -signet -datadir=$HOME/.bitcoin-sv2-workshop createwallet sv2-workshop
+bitcoin-cli -signet -datadir=$HOME/.bitcoin-sv2-workshop createwallet sv2-workshop
 ```
 
 ## Generate address (Pool)
 
 ```
-$CLI -signet -datadir=$HOME/.bitcoin-sv2-workshop getnewaddress sv2-workshop-address
+bitcoin-cli -signet -datadir=$HOME/.bitcoin-sv2-workshop getnewaddress sv2-workshop-address
 ```
 
 ---
 
 ## Get pubkey (Pool)
 
 ```
-$CLI -signet -datadir=$HOME/.bitcoin-sv2-workshop getaddressinfo <sv2-workshop-address>
+bitcoin-cli -signet -datadir=$HOME/.bitcoin-sv2-workshop getaddressinfo <sv2-workshop-address>
 ```
 
 ⚠️ Take note of the `pubkey` value so you can use it on the next step, and also to check your mining rewards on mempool later.
@@ -343,4 +355,4 @@ minerd -a sha256d -o stratum+tcp://localhost:34255 -q -D -P
 
 ---
 
-# Thank you
+# Thank you
