From aa0a2e96defa5dd7e297930c23713d1d311b1612 Mon Sep 17 00:00:00 2001 From: Redouane Lakrache Date: Mon, 25 Nov 2024 16:56:31 +0100 Subject: [PATCH 1/6] docs: Add PATH gateway cheat sheet --- .../docker_compose_debian_cheatsheet.md | 2 +- .../operate/quickstart/gateway_cheatsheet.md | 142 +++++++++++++++++- 2 files changed, 142 insertions(+), 2 deletions(-) diff --git a/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md b/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md index 6493b012e..2dd63e170 100644 --- a/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md @@ -5,7 +5,7 @@ title: Docker Compose Cheat Sheet import ReactPlayer from "react-player"; -# Docker Compose Cheat Sheet +# Docker Compose Cheat Sheet - [Results](#results) - [Deploy your server](#deploy-your-server) diff --git a/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md b/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md index b1ff586f7..a6d54397b 100644 --- a/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md @@ -11,4 +11,144 @@ See the [Gateway Walkthrough](./../run_a_node/gateway_walkthrough.md) for an in- ::: -TODO_BETA(@red-0ne): Finish this page. +## Build Shannon binary + +The `poktrolld` binary is needed to stake your `Gateway` and its delegating `Application`s. + +**Retrieve source code and build binaries** + +```bash +mkdir ~/poktroll && cd ~/poktroll +git clone https://github.com/pokt-network/poktroll.git +cd poktroll +make ignite_poktrolld_build +``` + +## Create, fund and stake the Gateway and Application accounts + +**Create a new key pair for the delegating `Application`** + +```bash +poktrolld keys add application +``` + +**Create a new key pair for the `Gateway`** + +```bash +poktrolld keys add gateway +``` + +**Fund the Gateway and Application accounts** + +Retrieve the `Gateway` and `Application` addresses: + +```bash +echo "Gateway address: $(poktrolld keys show gateway -a)" +echo "Application address: $(poktrolld keys show application -a)" +``` + +Then use the [faucet](https://faucet.testnet.pokt.network/) to fund the `Gateway` +and `Application` accounts. + +**Stake the Gateway** + +```bash +# Create a Gateway stake configuration file +cat < /tmp/stake_gateway +stake_amount: 1000000upokt +EOF + +poktrolld tx gateway stake-gateway --config=/tmp/stake_gateway --from=gateway --chain-id=poktroll --yes + +# OPTIONALLY check the gateway's status +poktrolld query gateway show-gateway $(poktrolld keys show gateway -a) +``` + +**Stake the delegating Application** + +```bash +# Create an Application stake configuration file +cat < /tmp/stake_app +stake_amount: 10000000upokt +service_ids: + - "0021" +EOF + +poktrolld tx application stake-application --config=/tmp/stake_app --from=application --chain-id=poktroll --yes + +# OPTIONALLY check the application's status +poktrolld query application show-application $(poktrolld keys show application -a) +``` + +**Delegate the Application to the Gateway** + +```bash +poktrolld tx application delegate-to-gateway $(poktrolld keys show gateway -a) --from=application --chain-id=poktroll --chain-id=poktroll --yes + +# OPTIONALLY check the application's status +poktrolld query application show-application $(poktrolld keys show application -a) +``` + +## Retrieve PATH Gateway source code + +Pull the latest `PATH Gateway` source code: + +```bash +mkdir ~/path-gateway && cd ~/path-gateway +git clone https://github.com/buildwithgrove/path.git +cd path-gateway +``` + +## Generate a PATH Gateway config file for the Shannon network + +Run the following command to generate a default Shannon config `cmd/.config.yaml` + +```bash +make copy_shannon_config +sed -i "s|rpc_url: ".*"|rpc_url: https://shannon-testnet-grove-rpc.beta.poktroll.com|" cmd/.config.yaml +sed -i "s|host_port: ".*"|host_port: shannon-testnet-grove-grpc.beta.poktroll.com:443|" cmd/.config.yaml +``` + +:::note + +We aim to setup a `PATH Gateway` with `Centralized Mode` (i.e. The operator owns +both the `Gateway` and the `Application` accounts). + +Refer to [PATH Gateway modes](https://path.grove.city/) for more information. + + +::: + +**Update the `cmd/.config.yaml` file with the `Gateway` and `Application` keys** + +```bash +sed -i '/owned_apps_private_keys_hex:/!b;n;c\ - '"$(yes | poktrolld keys export application --unsafe --unarmored-hex)" cmd/.config.yaml +sed -i "s|gateway_address: .*|gateway_address: $(poktrolld keys show gateway -a)|" cmd/.config.yaml +sed -i "s|gateway_private_key_hex: .*|gateway_private_key_hex: $(yes | poktrolld keys export gateway --unsafe --unarmored-hex)|" cmd/.config.yaml +``` + +## Build and run the PATH Gateway + +```bash +cd cmd/ && go build -o path . && ./path +``` + +You should see the following output: + +```json +{"level":"info","message":"Starting the cache update process."} +{"level":"warn","message":"endpoint hydrator is disabled: no service QoS generators are specified"} +{"level":"info","package":"router","message":"PATH gateway running on port 3000"} +{"level":"warn","error":"buildAppsServiceMap: no apps found.","message":"updateAppCache: error getting the list of apps; skipping update."} +{"level":"warn","method":"fetchSessions","error":"buildAppsServiceMap: no apps found.","message":"fetchSession: error listing applications"} +{"level":"warn","message":"updateSessionCache: received empty session list; skipping update."} +``` + +Check that the `PATH Gateway` is serving relays: + +```bash +curl http://eth.localhost:3000/v1 \ + -X POST \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber" }' +``` \ No newline at end of file From 0f39c16ece4501e8f509efb03bbd6282959355b8 Mon Sep 17 00:00:00 2001 From: Redouane Lakrache Date: Mon, 25 Nov 2024 17:48:29 +0100 Subject: [PATCH 2/6] fix: Disable $ linter --- docusaurus/docs/operate/quickstart/gateway_cheatsheet.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md b/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md index a6d54397b..70362c6f1 100644 --- a/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md @@ -4,6 +4,7 @@ title: Gateway Cheat Sheet --- ## Gateway Cheat Sheet + :::tip From 4de0488fb2b55a586bf235182e60940774baba42 Mon Sep 17 00:00:00 2001 From: Redouane Lakrache Date: Tue, 26 Nov 2024 04:11:49 +0100 Subject: [PATCH 3/6] chore: Tested walkthrough --- .../operate/quickstart/gateway_cheatsheet.md | 139 +++++++++++++----- 1 file changed, 99 insertions(+), 40 deletions(-) diff --git a/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md b/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md index 70362c6f1..cdc4989a3 100644 --- a/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md @@ -3,55 +3,92 @@ sidebar_position: 5 title: Gateway Cheat Sheet --- -## Gateway Cheat Sheet +# Gateway Cheat Sheet +This guide provides quick reference commands for setting up and running a gateway node. + +- [Prerequisites](#prerequisites) +- [Build Pocket](#build-pocket) +- [Account Setup](#account-setup) + - [Create and fund the `Gateway` and `Application` accounts](#create-and-fund-the-gateway-and-application-accounts) + - [Fund the Gateway and Application accounts](#fund-the-gateway-and-application-accounts) + - [Stake the `Gateway`](#stake-the-gateway) + - [Stake the delegating `Application`](#stake-the-delegating-application) + - [Delegate the `Application` to the `Gateway`](#delegate-the-application-to-the-gateway) +- [`PATH Gateway` Configuration](#path-gateway-configuration) + - [Generate a `PATH Gateway` config file for the Shannon network](#generate-a-path-gateway-config-file-for-the-shannon-network) +- [`PATH Gateway` Setup](#path-gateway-setup) + - [Build and run the PATH Gateway](#build-and-run-the-path-gateway) + :::tip +For detailed instructions, troubleshooting, and observability setup, see the [Gateway Walkthrough](./../run_a_node/gateway_walkthrough.md). +::: -See the [Gateway Walkthrough](./../run_a_node/gateway_walkthrough.md) for an in-depth guide on setting up a Gateway, troubleshooting, observability and more. +## Prerequisites -::: +Install the required dependencies: + +```bash +# Install go 1.23 +curl -o ./pkgx --compressed -f --proto '=https' https://pkgx.sh/$(uname)/$(uname -m) +sudo install -m 755 pkgx /usr/local/bin +pkgx install go@1.23.0 +export PATH=$PATH:$HOME/go/bin/ + +# Install PATH Gateway required dependencies +apt-get update && apt-get install git make build-essential + +# Install the ignite binary used to build the Pocket binary +curl https://get.ignite.com/cli! | bash +``` -## Build Shannon binary +## Build Pocket The `poktrolld` binary is needed to stake your `Gateway` and its delegating `Application`s. -**Retrieve source code and build binaries** +Retrieve source code and build binaries: ```bash -mkdir ~/poktroll && cd ~/poktroll git clone https://github.com/pokt-network/poktroll.git cd poktroll make ignite_poktrolld_build ``` -## Create, fund and stake the Gateway and Application accounts +## Account Setup + +### Create and fund the `Gateway` and `Application` accounts -**Create a new key pair for the delegating `Application`** +Create a new key pair for the delegating `Application`: ```bash poktrolld keys add application ``` -**Create a new key pair for the `Gateway`** +Create a new key pair for the `Gateway`: ```bash poktrolld keys add gateway ``` -**Fund the Gateway and Application accounts** +### Fund the Gateway and Application accounts -Retrieve the `Gateway` and `Application` addresses: +Set the environment variables needed to interact with the Shannon network: ```bash -echo "Gateway address: $(poktrolld keys show gateway -a)" -echo "Application address: $(poktrolld keys show application -a)" +export NODE="--node=https://shannon-testnet-grove-rpc.beta.poktroll.com" +export TX_PARAMS="--gas=auto --gas-prices=1upokt --gas-adjustment=1.5 --chain-id=pocket-beta --yes" +export GATEWAY_ADDR=$(poktrolld keys show gateway -a) +export APP_ADDR=$(poktrolld keys show application -a) + +echo "Gateway address: $GATEWAY_ADDR" +echo "Application address: $APP_ADDR" ``` -Then use the [faucet](https://faucet.testnet.pokt.network/) to fund the `Gateway` +Then use the [faucet](https://faucet.beta.testnet.pokt.network/) to fund the `Gateway` and `Application` accounts. -**Stake the Gateway** +### Stake the `Gateway` ```bash # Create a Gateway stake configuration file @@ -59,50 +96,57 @@ cat < /tmp/stake_gateway stake_amount: 1000000upokt EOF -poktrolld tx gateway stake-gateway --config=/tmp/stake_gateway --from=gateway --chain-id=poktroll --yes +poktrolld tx gateway stake-gateway --config=/tmp/stake_gateway --from=$GATEWAY_ADDR $TX_PARAMS $NODE +``` -# OPTIONALLY check the gateway's status -poktrolld query gateway show-gateway $(poktrolld keys show gateway -a) +Optionally check the `Gateway`'s status: +```bash +poktrolld query gateway show-gateway $GATEWAY_ADDR $NODE ``` -**Stake the delegating Application** +### Stake the delegating `Application` ```bash # Create an Application stake configuration file cat < /tmp/stake_app -stake_amount: 10000000upokt +stake_amount: 100000000upokt service_ids: - "0021" EOF -poktrolld tx application stake-application --config=/tmp/stake_app --from=application --chain-id=poktroll --yes +poktrolld tx application stake-application --config=/tmp/stake_app --from=$APP_ADDR $GAS_PARAMS $NODE +``` -# OPTIONALLY check the application's status -poktrolld query application show-application $(poktrolld keys show application -a) +Optionally check the `Application`'s status: +```bash +poktrolld query application show-application $APP_ADDR $NODE ``` -**Delegate the Application to the Gateway** +### Delegate the `Application` to the `Gateway` ```bash -poktrolld tx application delegate-to-gateway $(poktrolld keys show gateway -a) --from=application --chain-id=poktroll --chain-id=poktroll --yes +poktrolld tx application delegate-to-gateway $GATEWAY_ADDR --from=$APP_ADDR $GAS_PARAMS $NODE +``` -# OPTIONALLY check the application's status -poktrolld query application show-application $(poktrolld keys show application -a) +Optionally check if the application is delegating to the gateway +```bash +poktrolld query application show-application $APP_ADDR $NODE ``` -## Retrieve PATH Gateway source code +## `PATH Gateway` Configuration Pull the latest `PATH Gateway` source code: ```bash -mkdir ~/path-gateway && cd ~/path-gateway +cd ~ git clone https://github.com/buildwithgrove/path.git -cd path-gateway +cd path ``` -## Generate a PATH Gateway config file for the Shannon network +### Generate a `PATH Gateway` config file for the Shannon network -Run the following command to generate a default Shannon config `cmd/.config.yaml` +Run the following command to generate a default Shannon config `cmd/.config.yaml`: + ```bash make copy_shannon_config @@ -120,15 +164,26 @@ Refer to [PATH Gateway modes](https://path.grove.city/) for more information. ::: -**Update the `cmd/.config.yaml` file with the `Gateway` and `Application` keys** +Update the `cmd/.config.yaml` file with the `Gateway` address and private key: + +_You'll be prompted to confirm the `gateway` account private key export._ ```bash -sed -i '/owned_apps_private_keys_hex:/!b;n;c\ - '"$(yes | poktrolld keys export application --unsafe --unarmored-hex)" cmd/.config.yaml -sed -i "s|gateway_address: .*|gateway_address: $(poktrolld keys show gateway -a)|" cmd/.config.yaml -sed -i "s|gateway_private_key_hex: .*|gateway_private_key_hex: $(yes | poktrolld keys export gateway --unsafe --unarmored-hex)|" cmd/.config.yaml +sed -i "s|gateway_address: .*|gateway_address: $GATEWAY_ADDR|" cmd/.config.yaml +sed -i "s|gateway_private_key_hex: .*|gateway_private_key_hex: $(poktrolld keys export gateway --unsafe --unarmored-hex)|" cmd/.config.yaml ``` -## Build and run the PATH Gateway +Update the `cmd/.config.yaml` file with the delegating `Application` private key: + +_You'll be prompted to confirm the `application` account private key export._ + +```bash +sed -i '/owned_apps_private_keys_hex:/!b;n;c\ - '"$(poktrolld keys export application --unsafe --unarmored-hex)" cmd/.config.yaml +``` + +## `PATH Gateway` Setup + +### Build and run the PATH Gateway ```bash cd cmd/ && go build -o path . && ./path @@ -140,13 +195,17 @@ You should see the following output: {"level":"info","message":"Starting the cache update process."} {"level":"warn","message":"endpoint hydrator is disabled: no service QoS generators are specified"} {"level":"info","package":"router","message":"PATH gateway running on port 3000"} -{"level":"warn","error":"buildAppsServiceMap: no apps found.","message":"updateAppCache: error getting the list of apps; skipping update."} -{"level":"warn","method":"fetchSessions","error":"buildAppsServiceMap: no apps found.","message":"fetchSession: error listing applications"} -{"level":"warn","message":"updateSessionCache: received empty session list; skipping update."} ``` Check that the `PATH Gateway` is serving relays: +:::info + +Initial requests may hit unresponsive nodes, if that happens, retry the request a few times. +`PATH Gateway` will exclude unresponsive nodes on subsequent requests. + +::: + ```bash curl http://eth.localhost:3000/v1 \ -X POST \ From 72c821689c19efaf72c128e40f67023a828eb009 Mon Sep 17 00:00:00 2001 From: Redouane Lakrache Date: Tue, 26 Nov 2024 04:13:49 +0100 Subject: [PATCH 4/6] fix: Remove useless linter directive --- docusaurus/docs/operate/quickstart/gateway_cheatsheet.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md b/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md index cdc4989a3..a52c694e3 100644 --- a/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md @@ -4,7 +4,6 @@ title: Gateway Cheat Sheet --- # Gateway Cheat Sheet - This guide provides quick reference commands for setting up and running a gateway node. From b2df7950274edde3974429650e5d445e828d22a9 Mon Sep 17 00:00:00 2001 From: Daniel Olshansky Date: Mon, 2 Dec 2024 15:48:32 -0800 Subject: [PATCH 5/6] Almost done reviewing this PR --- api/poktroll/service/tx.pulsar.go | 2 +- .../docker_compose_debian_cheatsheet.md | 5 +- .../operate/quickstart/gateway_cheatsheet.md | 242 +++++++++++------- docusaurus/docs/operate/user_guide/install.md | 24 +- 4 files changed, 183 insertions(+), 90 deletions(-) diff --git a/api/poktroll/service/tx.pulsar.go b/api/poktroll/service/tx.pulsar.go index 3b140dce5..c4e61fa8a 100644 --- a/api/poktroll/service/tx.pulsar.go +++ b/api/poktroll/service/tx.pulsar.go @@ -5,11 +5,11 @@ import ( _ "cosmossdk.io/api/amino" v1beta1 "cosmossdk.io/api/cosmos/base/v1beta1" _ "cosmossdk.io/api/cosmos/msg/v1" + shared "github.com/pokt-network/poktroll/api/poktroll/shared" fmt "fmt" _ "github.com/cosmos/cosmos-proto" runtime "github.com/cosmos/cosmos-proto/runtime" _ "github.com/cosmos/gogoproto/gogoproto" - shared "github.com/pokt-network/poktroll/api/poktroll/shared" protoreflect "google.golang.org/protobuf/reflect/protoreflect" protoiface "google.golang.org/protobuf/runtime/protoiface" protoimpl "google.golang.org/protobuf/runtime/protoimpl" diff --git a/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md b/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md index 9520db012..afc6b8a63 100644 --- a/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md @@ -107,16 +107,19 @@ cd poktroll-docker-compose-example ## Update your environment First, copy the sample environment file: + ```bash cp .env.sample .env ``` By default, the `.env` file uses `testnet-beta`. If you want to use a different network, update the `NETWORK_NAME` in your `.env` file to one of: + - `testnet-alpha` - Unstable testnet - `testnet-beta` - Stable testnet (default) - `mainnet` - Production network Then set your external IP and source the environment: + ```bash EXTERNAL_IP=$(curl -4 ifconfig.me/ip) sed -i -e s/NODE_HOSTNAME=/NODE_HOSTNAME=$EXTERNAL_IP/g .env @@ -128,13 +131,11 @@ source ~/.bashrc ## Start up the full node - :::warning The Alpha TestNet currently requires manual steps to sync the node to the latest block. Please find the affected block(s) in [this document](../../protocol/upgrades/upgrade_list.md), which leads to the manual upgrade instructions. ::: - ```bash docker compose up -d full-node # Optional: watch the block height sync up & logs diff --git a/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md b/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md index a52c694e3..a5823bac2 100644 --- a/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md @@ -5,54 +5,41 @@ title: Gateway Cheat Sheet # Gateway Cheat Sheet -This guide provides quick reference commands for setting up and running a gateway node. +This guide provides quick reference commands for setting up and running a Gateway +on Pocket Network. -- [Prerequisites](#prerequisites) -- [Build Pocket](#build-pocket) +:::warning + +These instructions are intended to run on a Linux machine. + +TODO_TECHDEBT(@olshansky): Adapt the instructions to be macOS friendly. + +::: + +- [Pre-Requisites](#pre-requisites) - [Account Setup](#account-setup) - [Create and fund the `Gateway` and `Application` accounts](#create-and-fund-the-gateway-and-application-accounts) + - [Prepare your environment](#prepare-your-environment) - [Fund the Gateway and Application accounts](#fund-the-gateway-and-application-accounts) - [Stake the `Gateway`](#stake-the-gateway) - [Stake the delegating `Application`](#stake-the-delegating-application) - [Delegate the `Application` to the `Gateway`](#delegate-the-application-to-the-gateway) -- [`PATH Gateway` Configuration](#path-gateway-configuration) +- [`PATH` Setup](#path-setup) + - [`PATH` Gateway Setup](#path-gateway-setup) - [Generate a `PATH Gateway` config file for the Shannon network](#generate-a-path-gateway-config-file-for-the-shannon-network) -- [`PATH Gateway` Setup](#path-gateway-setup) - - [Build and run the PATH Gateway](#build-and-run-the-path-gateway) + - [Run the `PATH` Gateway](#run-the-path-gateway) + - [Build and run the `PATH` Gateway from source](#build-and-run-the-path-gateway-from-source) + - [\[TODO\] Run the `PATH` Gateway using Docker](#todo-run-the-path-gateway-using-docker) + - [Check the `PATH Gateway` is serving relays](#check-the-path-gateway-is-serving-relays) -:::tip +:::note For detailed instructions, troubleshooting, and observability setup, see the [Gateway Walkthrough](./../run_a_node/gateway_walkthrough.md). ::: -## Prerequisites - -Install the required dependencies: - -```bash -# Install go 1.23 -curl -o ./pkgx --compressed -f --proto '=https' https://pkgx.sh/$(uname)/$(uname -m) -sudo install -m 755 pkgx /usr/local/bin -pkgx install go@1.23.0 -export PATH=$PATH:$HOME/go/bin/ - -# Install PATH Gateway required dependencies -apt-get update && apt-get install git make build-essential +## Pre-Requisites -# Install the ignite binary used to build the Pocket binary -curl https://get.ignite.com/cli! | bash -``` - -## Build Pocket - -The `poktrolld` binary is needed to stake your `Gateway` and its delegating `Application`s. - -Retrieve source code and build binaries: - -```bash -git clone https://github.com/pokt-network/poktroll.git -cd poktroll -make ignite_poktrolld_build -``` +1. Make sure to [install the `poktrolld` CLI](../user_guide/install.md). +2. Make sure you know how to [create and fund a new account](../user_guide/create-new-wallet.md). ## Account Setup @@ -62,127 +49,203 @@ Create a new key pair for the delegating `Application`: ```bash poktrolld keys add application + +# Optionally, to avoid entering the password each time: +# poktrolld keys add application --keyring-backend test ``` Create a new key pair for the `Gateway`: ```bash poktrolld keys add gateway + +# Optionally, to avoid entering the password each time: +# poktrolld keys add gateway --keyring-backend test ``` -### Fund the Gateway and Application accounts +:::tip -Set the environment variables needed to interact with the Shannon network: +You can set the `--keyring-backend` flag to `test` to avoid entering the password +each time. Learn more about [cosmos keyring backends here](https://docs.cosmos.network/v0.46/run-node/keyring.html). + +::: + +### Prepare your environment + +For convenience, we're setting several environment variables to streamline +the process of interacting with the Shannon network: + +We recommend you put these in your `~/.bashrc` file: ```bash -export NODE="--node=https://shannon-testnet-grove-rpc.beta.poktroll.com" -export TX_PARAMS="--gas=auto --gas-prices=1upokt --gas-adjustment=1.5 --chain-id=pocket-beta --yes" +export NODE="https://shannon-testnet-grove-rpc.beta.poktroll.com" +export NODE_FLAGS="--node=https://shannon-testnet-grove-rpc.beta.poktroll.com" +export TX_PARAM_FLAGS="--gas=auto --gas-prices=1upokt --gas-adjustment=1.5 --chain-id=pocket-beta --yes" export GATEWAY_ADDR=$(poktrolld keys show gateway -a) export APP_ADDR=$(poktrolld keys show application -a) +# Optionally, to avoid entering the password each time: +# export GATEWAY_ADDR=$(poktrolld keys show gateway -a --keyring-backend test) +# export APP_ADDR=$(poktrolld keys show application -a --keyring-backend test) +``` + +:::tip + +You can put the above in a special `~/.pocketrc` and add `source ~/.pocketrc` to +your `~/.bashrc` file for a cleaner organization. + +::: + +### Fund the Gateway and Application accounts + +Run the following command to get the `Gateway` and `Application` addresses: + +```bash echo "Gateway address: $GATEWAY_ADDR" echo "Application address: $APP_ADDR" ``` -Then use the [faucet](https://faucet.beta.testnet.pokt.network/) to fund the `Gateway` -and `Application` accounts. +Then use the [Shannon Beta TestNet faucet](https://faucet.beta.testnet.pokt.network/) to fund the `Gateway` +and `Application` accounts respectively. + +Afterwards, you can query their balances using the following command: + +```bash +poktrolld query bank balances $GATEWAY_ADDR $NODE_FLAGS +poktrolld query bank balances $APP_ADDR $NODE_FLAGS +``` + +:::tip +You can find all the explorers, faucets and tools at the [tools page](../../explore/tools.md). +::: ### Stake the `Gateway` +Create a Gateway stake configuration file: + ```bash -# Create a Gateway stake configuration file -cat < /tmp/stake_gateway +cat < /tmp/stake_gateway_config.yaml stake_amount: 1000000upokt EOF +``` + +And run the following command to stake the `Gateway`: + +```bash +poktrolld tx gateway stake-gateway --config=/tmp/stake_gateway_config.yaml --from=$GATEWAY_ADDR $TX_PARAM_FLAGS $NODE_FLAGS -poktrolld tx gateway stake-gateway --config=/tmp/stake_gateway --from=$GATEWAY_ADDR $TX_PARAMS $NODE +# Optionally, to avoid entering the password each time: +# poktrolld tx gateway stake-gateway --config=/tmp/stake_gateway_config.yaml --from=$GATEWAY_ADDR $TX_PARAM_FLAGS $NODE_FLAGS --keyring-backend test ``` -Optionally check the `Gateway`'s status: +After about a minute, you can check the `Gateway`'s status like so: + ```bash -poktrolld query gateway show-gateway $GATEWAY_ADDR $NODE +poktrolld query gateway show-gateway $GATEWAY_ADDR $NODE_FLAGS ``` ### Stake the delegating `Application` +Create an Application stake configuration file: + ```bash -# Create an Application stake configuration file -cat < /tmp/stake_app +cat < /tmp/stake_app_config.yaml stake_amount: 100000000upokt service_ids: - - "0021" + - "F00C" EOF +``` + +And run the following command to stake the `Application`: + +```bash +poktrolld tx application stake-application --config=/tmp/stake_app_config.yaml --from=$APP_ADDR $TX_PARAM_FLAGS $GAS_PARAMS $NODE_FLAGS -poktrolld tx application stake-application --config=/tmp/stake_app --from=$APP_ADDR $GAS_PARAMS $NODE +# Optionally, to avoid entering the password each time: +# poktrolld tx application stake-application --config=/tmp/stake_app_config.yaml --from=$APP_ADDR $TX_PARAM_FLAGS $GAS_PARAMS $NODE_FLAGS --keyring-backend test ``` -Optionally check the `Application`'s status: +After about a minute, you can check the `Application`'s status like so: + ```bash -poktrolld query application show-application $APP_ADDR $NODE +poktrolld query application show-application $APP_ADDR $NODE_FLAGS ``` ### Delegate the `Application` to the `Gateway` ```bash -poktrolld tx application delegate-to-gateway $GATEWAY_ADDR --from=$APP_ADDR $GAS_PARAMS $NODE +poktrolld tx application delegate-to-gateway $GATEWAY_ADDR --from=$APP_ADDR $TX_PARAM_FLAGS $GAS_PARAMS $NODE_FLAGS + +# Optionally, to avoid entering the password each time: +# poktrolld tx application delegate-to-gateway $GATEWAY_ADDR --from=$APP_ADDR $TX_PARAM_FLAGS $GAS_PARAMS $NODE_FLAGS --keyring-backend test ``` -Optionally check if the application is delegating to the gateway +After about a minute, you can check the `Application`'s status like so: + ```bash -poktrolld query application show-application $APP_ADDR $NODE +poktrolld query application show-application $APP_ADDR $NODE_FLAGS ``` -## `PATH Gateway` Configuration +## `PATH` Setup + +### `PATH` Gateway Setup + +Assuming you have followed the instructions above, the following should be true: -Pull the latest `PATH Gateway` source code: +1. You have created, funded and stake a `Gateway`. +2. You have created, funded and stake a `Application`. +3. You have from the staked `Application` to staked the `Gateway`. + +Next, you can run a `PATH` Gateway. + +Star by following these instructions: ```bash -cd ~ +cd ~/workspace git clone https://github.com/buildwithgrove/path.git cd path ``` ### Generate a `PATH Gateway` config file for the Shannon network -Run the following command to generate a default Shannon config `cmd/.config.yaml`: - - -```bash -make copy_shannon_config -sed -i "s|rpc_url: ".*"|rpc_url: https://shannon-testnet-grove-rpc.beta.poktroll.com|" cmd/.config.yaml -sed -i "s|host_port: ".*"|host_port: shannon-testnet-grove-grpc.beta.poktroll.com:443|" cmd/.config.yaml -``` + :::note -We aim to setup a `PATH Gateway` with `Centralized Mode` (i.e. The operator owns +The instructions below show how to setup a `PATH` in `Centralized Mode` (i.e. The operator owns both the `Gateway` and the `Application` accounts). -Refer to [PATH Gateway modes](https://path.grove.city/) for more information. - +Refer to [PATH Gateway modes](https://path.grove.city/) for more configuration options. ::: -Update the `cmd/.config.yaml` file with the `Gateway` address and private key: +Run the following command to generate a default Shannon config `cmd/.config.yaml`: -_You'll be prompted to confirm the `gateway` account private key export._ +_NOTE: You'll be prompted to confirm the `gateway` account private key export._ ```bash -sed -i "s|gateway_address: .*|gateway_address: $GATEWAY_ADDR|" cmd/.config.yaml -sed -i "s|gateway_private_key_hex: .*|gateway_private_key_hex: $(poktrolld keys export gateway --unsafe --unarmored-hex)|" cmd/.config.yaml -``` - -Update the `cmd/.config.yaml` file with the delegating `Application` private key: +# Make a copy of the default config file +make copy_shannon_config -_You'll be prompted to confirm the `application` account private key export._ +# Replace the endpoints as needed +sed -i "s|rpc_url: ".*"|rpc_url: $NODE|" cmd/.config.yaml +sed -i "s|host_port: ".*"|host_port: shannon-testnet-grove-grpc.beta.poktroll.com:443|" cmd/.config.yaml -```bash +# Update the gateway and application addresses +sed -i "s|gateway_address: .*|gateway_address: $GATEWAY_ADDR|" cmd/.config.yaml +sed -i "s|gateway_private_key_hex: .*|gateway_private_key_hex: $(poktrolld keys export gateway --unsafe --unarmored-hex)|" cmd/.config.yaml sed -i '/owned_apps_private_keys_hex:/!b;n;c\ - '"$(poktrolld keys export application --unsafe --unarmored-hex)" cmd/.config.yaml + +# If you're using the test keyring-backend: +# sed -i "s|gateway_private_key_hex: .*|gateway_private_key_hex: $(poktrolld keys export gateway --unsafe --unarmored-hex --keyring-backend test)|" cmd/.config.yaml +# sed -i '/owned_apps_private_keys_hex:/!b;n;c\ - '"$(poktrolld keys export application --unsafe --unarmored-hex --keyring-backend test)" cmd/.config.yaml ``` -## `PATH Gateway` Setup +When you're done, run `cat cmd/.config.yaml` to view the updated config file. -### Build and run the PATH Gateway +### Run the `PATH` Gateway + +#### Build and run the `PATH` Gateway from source ```bash cd cmd/ && go build -o path . && ./path @@ -196,18 +259,25 @@ You should see the following output: {"level":"info","package":"router","message":"PATH gateway running on port 3000"} ``` -Check that the `PATH Gateway` is serving relays: +#### [TODO] Run the `PATH` Gateway using Docker -:::info +_TODO_IMPROVE(@olshansk): Add instructions for running the `PATH` Gateway using Docker._ -Initial requests may hit unresponsive nodes, if that happens, retry the request a few times. -`PATH Gateway` will exclude unresponsive nodes on subsequent requests. +### Check the `PATH Gateway` is serving relays -::: +Check that the `PATH Gateway` is serving relays by running the following command yourself: ```bash curl http://eth.localhost:3000/v1 \ -X POST \ -H "Content-Type: application/json" \ -d '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber" }' -``` \ No newline at end of file +``` + +:::warning + +Requests MAY hit unresponsive nodes. If that happens, keep retrying the request a few times. + +Once `PATH`s QoS module is mature, this will be handled automatically. + +::: diff --git a/docusaurus/docs/operate/user_guide/install.md b/docusaurus/docs/operate/user_guide/install.md index 4c20f0824..dab4f98b2 100644 --- a/docusaurus/docs/operate/user_guide/install.md +++ b/docusaurus/docs/operate/user_guide/install.md @@ -17,6 +17,8 @@ brew install poktrolld - [MacOS \& Linux Users](#macos--linux-users) - [Using Homebrew](#using-homebrew) - [From Source](#from-source) + - [Installing dependencies](#installing-dependencies) + - [Installing poktrolld](#installing-poktrolld) - [Using release binaries](#using-release-binaries) - [Windows Users](#windows-users) @@ -48,12 +50,32 @@ or debug the CLI. ### From Source +#### Installing dependencies + Ensure you have the following installed: - [Go](https://go.dev/doc/install) (version 1.18 or later) - [Ignite CLI](https://docs.ignite.com/welcome/install) -Then run the following commands: +If you're on a Linux machine, you can follow the steps below for convenience: + +```bash +# Install go 1.23 +curl -o ./pkgx --compressed -f --proto '=https' https://pkgx.sh/$(uname)/$(uname -m) +sudo install -m 755 pkgx /usr/local/bin +pkgx install go@1.23.0 +export PATH=$PATH:$HOME/go/bin/ + +# Install PATH Gateway required dependencies +apt-get update && apt-get install git make build-essential + +# Install the ignite binary used to build the Pocket binary +curl https://get.ignite.com/cli! | bash +``` + +#### Installing poktrolld + +Then, Retrieve the source code and build the `poktrolld` locally like so: ```bash git clone https://github.com/pokt-network/poktroll.git From 2764324539b2a69b22b8574533581f2bbc310727 Mon Sep 17 00:00:00 2001 From: Redouane Lakrache Date: Tue, 3 Dec 2024 01:57:42 +0100 Subject: [PATCH 6/6] fix: remove unused env var --- docusaurus/docs/operate/quickstart/gateway_cheatsheet.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md b/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md index a5823bac2..e74e32bf3 100644 --- a/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md @@ -159,10 +159,10 @@ EOF And run the following command to stake the `Application`: ```bash -poktrolld tx application stake-application --config=/tmp/stake_app_config.yaml --from=$APP_ADDR $TX_PARAM_FLAGS $GAS_PARAMS $NODE_FLAGS +poktrolld tx application stake-application --config=/tmp/stake_app_config.yaml --from=$APP_ADDR $TX_PARAM_FLAGS $NODE_FLAGS # Optionally, to avoid entering the password each time: -# poktrolld tx application stake-application --config=/tmp/stake_app_config.yaml --from=$APP_ADDR $TX_PARAM_FLAGS $GAS_PARAMS $NODE_FLAGS --keyring-backend test +# poktrolld tx application stake-application --config=/tmp/stake_app_config.yaml --from=$APP_ADDR $TX_PARAM_FLAGS $NODE_FLAGS --keyring-backend test ``` After about a minute, you can check the `Application`'s status like so: @@ -174,10 +174,10 @@ poktrolld query application show-application $APP_ADDR $NODE_FLAGS ### Delegate the `Application` to the `Gateway` ```bash -poktrolld tx application delegate-to-gateway $GATEWAY_ADDR --from=$APP_ADDR $TX_PARAM_FLAGS $GAS_PARAMS $NODE_FLAGS +poktrolld tx application delegate-to-gateway $GATEWAY_ADDR --from=$APP_ADDR $TX_PARAM_FLAGS $NODE_FLAGS # Optionally, to avoid entering the password each time: -# poktrolld tx application delegate-to-gateway $GATEWAY_ADDR --from=$APP_ADDR $TX_PARAM_FLAGS $GAS_PARAMS $NODE_FLAGS --keyring-backend test +# poktrolld tx application delegate-to-gateway $GATEWAY_ADDR --from=$APP_ADDR $TX_PARAM_FLAGS $NODE_FLAGS --keyring-backend test ``` After about a minute, you can check the `Application`'s status like so: