From c6b2a0928e9ead38abcb5e5e97e9ede46202d017 Mon Sep 17 00:00:00 2001 From: Daniel Olshansky Date: Thu, 21 Nov 2024 13:02:52 -0800 Subject: [PATCH 1/7] [Docs] Update documentation on installing the `poktrolld` CLI (#949) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updating the following page for details on how to install the `poktrolld` CLI using homebrew: https://dev.poktroll.com/operate/user_guide/install ![Screenshot 2024-11-21 at 12 58 19β€―PM](https://github.com/user-attachments/assets/cee0c036-cc6e-486f-8c8e-4db5fa25c4b5) --- docusaurus/docs/operate/user_guide/install.md | 68 ++++++++++++------- 1 file changed, 43 insertions(+), 25 deletions(-) diff --git a/docusaurus/docs/operate/user_guide/install.md b/docusaurus/docs/operate/user_guide/install.md index ffa17875c..b19473f01 100644 --- a/docusaurus/docs/operate/user_guide/install.md +++ b/docusaurus/docs/operate/user_guide/install.md @@ -3,41 +3,47 @@ title: CLI Installation sidebar_position: 0 --- -- [Release binaries](#release-binaries) -- [Installing from source](#installing-from-source) - - [Prerequisites](#prerequisites) -- [Homebrew and pkgx](#homebrew-and-pkgx) +- [MacOS \& Linux Users](#macos--linux-users) + - [Using Homebrew](#using-homebrew) + - [From Source](#from-source) + - [Using release binaries](#using-release-binaries) - [Windows Users](#windows-users) -## Release binaries +## MacOS & Linux Users -Pre-built binaries are available on our [releases page](https://github.com/pokt-network/poktroll/releases). +### Using Homebrew -The following snippet downloads/upgrades the binary to the latest released version (Linux and macOS only): +:::tip +See the [homebrew-poktroll](https://github.com/pokt-network/homebrew-poktroll/) +repository for details on how to install homebrew or other details to install +or debug the CLI. +::: -```bash -# Download the correct binary based on the OS and architecture -curl -LO "https://github.com/pokt-network/poktroll/releases/latest/download/poktroll_$(uname | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" +Ensure you have [Homebrew](https://brew.sh/) installed. -# Extract the downloaded tarball to /usr/local/bin -sudo tar -zxf "poktroll_$(uname | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" -C /usr/local/bin +Then run the following commands: -# Make the binary executable -sudo chmod +x /usr/local/bin/poktrolld +```bash +brew tap pokt-network/poktroll +brew install poktrolld +``` -# Check version +And verify it worked by running: + +```bash poktrolld version +poktrolld --help ``` -## Installing from source - -### Prerequisites +### From Source 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: + ```bash git clone https://github.com/pokt-network/poktroll.git cd poktroll @@ -45,20 +51,32 @@ make go_develop make ignite_poktrolld_build ``` -Verify it worked by running: +And verify it worked by running: ```bash +poktrolld version poktrolld --help ``` -## Homebrew and pkgx +### Using release binaries -:::tip -We have an [open GitHub issue](https://github.com/pokt-network/poktroll/issues/535) -to introduce `poktrolld` to [brew](https://brew.sh/) and [pkgx](https://github.com/pkgxdev/pkgx). +Pre-built binaries are available on our [releases page](https://github.com/pokt-network/poktroll/releases). -Please reach out to us in the ticket if you want to pick this ticket! -::: +The following snippet downloads/upgrades the binary to the latest released version: + +```bash +# Download the correct binary based on the OS and architecture +curl -LO "https://github.com/pokt-network/poktroll/releases/latest/download/poktroll_$(uname | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" + +# Extract the downloaded tarball to /usr/local/bin +sudo tar -zxf "poktroll_$(uname | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" -C /usr/local/bin + +# Make the binary executable +sudo chmod +x /usr/local/bin/poktrolld + +# Check version +poktrolld version +``` ## Windows Users From 59ec254f58895cb0a7209d07cd86d59f84e9ae7e Mon Sep 17 00:00:00 2001 From: Daniel Olshansky Date: Thu, 21 Nov 2024 13:37:57 -0800 Subject: [PATCH 2/7] [Docs] Update links to RPC & explorers (#950) Update links to RPC endpoints, faucet & explorers --- docusaurus/docs/explore/rpc.md | 13 ++++++------- docusaurus/docs/explore/tools.md | 14 ++++++++------ 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/docusaurus/docs/explore/rpc.md b/docusaurus/docs/explore/rpc.md index a87c5e1a2..5a407e2ce 100644 --- a/docusaurus/docs/explore/rpc.md +++ b/docusaurus/docs/explore/rpc.md @@ -13,7 +13,6 @@ sidebar_position: 3 ## Types of RPC Endpoints - You can review the difference between them in the [Cosmos SDK docs](https://docs.cosmos.network/main/learn/advanced/grpc_rest#comparison-table). ## Beta TestNet @@ -22,9 +21,9 @@ You can review the difference between them in the [Cosmos SDK docs](https://docs We provide `gRPC`, `JSON-RPC` and `REST` endpoints, which are available here: -- **RPC**: `https://shannon-testnet-grove-seed-rpc.beta.poktroll.com` -- **gRPC**: `https://shannon-testnet-grove-seed-grpc.beta.poktroll.com` -- **REST**: `https://shannon-testnet-grove-seed-api.beta.poktroll.com` +- **RPC**: `https://shannon-testnet-grove-rpc.beta.poktroll.com` +- **gRPC**: `https://shannon-testnet-grove-grpc.beta.poktroll.com` +- **REST**: `https://shannon-testnet-grove-api.beta.poktroll.com` ### Beta JSON-RPC Example @@ -46,9 +45,9 @@ poktrolld query block --type=height 0 --node https://shannon-testnet-grove-seed- We provide `gRPC`, `JSON-RPC` and `REST` endpoints, which are available here: -- **RPC**: `https://shannon-testnet-grove-seed-rpc.alpha.poktroll.com` -- **gRPC**: `https://shannon-testnet-grove-seed-grpc.alpha.poktroll.com` -- **REST**: `https://shannon-testnet-grove-seed-api.alpha.poktroll.com` +- **RPC**: `https://shannon-testnet-grove-rpc.alpha.poktroll.com` +- **gRPC**: `https://shannon-testnet-grove-grpc.alpha.poktroll.com` +- **REST**: `https://shannon-testnet-grove-api.alpha.poktroll.com` ### Alpha JSON-RPC Example diff --git a/docusaurus/docs/explore/tools.md b/docusaurus/docs/explore/tools.md index 1034d1565..9e46f4f64 100644 --- a/docusaurus/docs/explore/tools.md +++ b/docusaurus/docs/explore/tools.md @@ -9,15 +9,17 @@ sidebar_position: 1 ## Beta TestNet -- πŸͺ™ [Shannon Beta Token Faucet](https://faucet.beta.testnet.pokt.network/) -- πŸ—ΊοΈ [Shannon Beta Explorer](https://shannon.beta.testnet.pokt.network) -- πŸ—ΊοΈ [PoktScan's Shannon Beta Explorer](https://shannon.beta.poktscan.com/) +- πŸͺ™ [Token Faucet](https://faucet.beta.testnet.pokt.network/) +- πŸ—ΊοΈ [Explorer](https://shannon.beta.testnet.pokt.network) +- πŸ—ΊοΈ [POKTScan's Explorer](https://shannon-beta.poktscan.com/) +- πŸ‘¨β€πŸ’» [POKTScan's GraphQL Playground](https://shannon-beta-api.poktscan.com/) ## Alpha TestNet -- πŸͺ™ [Shannon Alpha Token Faucet](https://faucet.alpha.testnet.pokt.network/) -- πŸ—ΊοΈ [Shannon Alpha Explorer](https://shannon.alpha.testnet.pokt.network) -- πŸ—ΊοΈ [PoktScan's Shannon Alpha Explorer](https://shannon.alpha.poktscan.com/) +- πŸͺ™ [Token Faucet](https://faucet.alpha.testnet.pokt.network/) +- πŸ—ΊοΈ [Explorer](https://shannon.alpha.testnet.pokt.network) +- πŸ—ΊοΈ [POKTScan's Explorer](https://shannon-alpha.poktscan.com/) +- πŸ‘¨β€πŸ’» [POKTScan's GraphQL Playground](https://shannon-alpha-api.poktscan.com/) ## πŸ› οΈ Tools & References From 4ad2c9152668797382947e899e3eaaab4851abb0 Mon Sep 17 00:00:00 2001 From: Bryan White Date: Mon, 25 Nov 2024 20:40:58 +0100 Subject: [PATCH 3/7] [Docs] adding params - fix gRPC status error code (#958) ## Summary ```diff func (k msgServer) UpdateParam(ctx context.Context, msg *examplemodtypes.MsgUpdateParam) (*examplemodtypes.MsgUpdateParamResponse, error) { // ... if k.GetAuthority() != msg.Authority { return nil, status.Error( - codes.InvalidArgument, + codes.PermissionDenied, examplemodtypes.ErrExamplemodInvalidSigner.Wrapf( "invalid authority; expected %s, got %s", k.GetAuthority(), msg.Authority, ).Error(), ) } // ... } ``` ## Issue - N/A ## Type of change Select one or more from the following: - [ ] New feature, functionality or library - [ ] Consensus breaking; add the `consensus-breaking` label if so. See #791 for details - [ ] Bug fix - [ ] Code health or cleanup - [x] Documentation - [ ] Other (specify) ## Testing - [ ] **Documentation**: `make docusaurus_start`; only needed if you make doc changes - [ ] **Unit Tests**: `make go_develop_and_test` - [ ] **LocalNet E2E Tests**: `make test_e2e` - [ ] **DevNet E2E Tests**: Add the `devnet-test-e2e` label to the PR. ## Sanity Checklist - [ ] I have tested my changes using the available tooling - [ ] I have commented my code - [ ] I have performed a self-review of my own code; both comments & source code - [ ] I create and reference any new tickets, if applicable - [ ] I have left TODOs throughout the codebase, if applicable --- docusaurus/docs/develop/developer_guide/adding_params.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/develop/developer_guide/adding_params.md b/docusaurus/docs/develop/developer_guide/adding_params.md index 48de66434..df8bf2c7d 100644 --- a/docusaurus/docs/develop/developer_guide/adding_params.md +++ b/docusaurus/docs/develop/developer_guide/adding_params.md @@ -243,7 +243,7 @@ Prepare `x/examplemod/keeper/msg_server_update_param.go` to handle parameter upd + + if k.GetAuthority() != msg.Authority { + return nil, status.Error( -+ codes.InvalidArgument, ++ codes.PermissionDenied, + examplemodtypes.ErrExamplemodInvalidSigner.Wrapf( + "invalid authority; expected %s, got %s", + k.GetAuthority(), msg.Authority, From f46dd4fa9e9717d594ecd2899189aa540bbc5b42 Mon Sep 17 00:00:00 2001 From: Daniel Olshansky Date: Mon, 25 Nov 2024 13:38:06 -0800 Subject: [PATCH 4/7] Commit outdated proto files --- api/poktroll/application/event.pulsar.go | 2 +- api/poktroll/application/types.pulsar.go | 2 +- api/poktroll/supplier/event.pulsar.go | 2 +- api/poktroll/supplier/tx.pulsar.go | 2 +- api/poktroll/tokenomics/event.pulsar.go | 2 +- api/poktroll/tokenomics/types.pulsar.go | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/api/poktroll/application/event.pulsar.go b/api/poktroll/application/event.pulsar.go index 292a46750..09bac55c2 100644 --- a/api/poktroll/application/event.pulsar.go +++ b/api/poktroll/application/event.pulsar.go @@ -3,11 +3,11 @@ package application import ( _ "cosmossdk.io/api/cosmos/base/v1beta1" + _ "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" - _ "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/api/poktroll/application/types.pulsar.go b/api/poktroll/application/types.pulsar.go index ca032ba67..f482e77bb 100644 --- a/api/poktroll/application/types.pulsar.go +++ b/api/poktroll/application/types.pulsar.go @@ -3,11 +3,11 @@ package application import ( v1beta1 "cosmossdk.io/api/cosmos/base/v1beta1" + 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/api/poktroll/supplier/event.pulsar.go b/api/poktroll/supplier/event.pulsar.go index 8558365eb..22dcc4989 100644 --- a/api/poktroll/supplier/event.pulsar.go +++ b/api/poktroll/supplier/event.pulsar.go @@ -3,11 +3,11 @@ package supplier import ( _ "cosmossdk.io/api/cosmos/base/v1beta1" + 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/api/poktroll/supplier/tx.pulsar.go b/api/poktroll/supplier/tx.pulsar.go index 7a709f7f0..1d2057b01 100644 --- a/api/poktroll/supplier/tx.pulsar.go +++ b/api/poktroll/supplier/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/api/poktroll/tokenomics/event.pulsar.go b/api/poktroll/tokenomics/event.pulsar.go index e62c41344..af0c412dc 100644 --- a/api/poktroll/tokenomics/event.pulsar.go +++ b/api/poktroll/tokenomics/event.pulsar.go @@ -3,10 +3,10 @@ package tokenomics import ( v1beta1 "cosmossdk.io/api/cosmos/base/v1beta1" + proof "github.com/pokt-network/poktroll/api/poktroll/proof" fmt "fmt" runtime "github.com/cosmos/cosmos-proto/runtime" _ "github.com/cosmos/gogoproto/gogoproto" - proof "github.com/pokt-network/poktroll/api/poktroll/proof" protoreflect "google.golang.org/protobuf/reflect/protoreflect" protoiface "google.golang.org/protobuf/runtime/protoiface" protoimpl "google.golang.org/protobuf/runtime/protoimpl" diff --git a/api/poktroll/tokenomics/types.pulsar.go b/api/poktroll/tokenomics/types.pulsar.go index 9ca1a54f9..e48600e95 100644 --- a/api/poktroll/tokenomics/types.pulsar.go +++ b/api/poktroll/tokenomics/types.pulsar.go @@ -3,11 +3,11 @@ package tokenomics import ( v1beta1 "cosmossdk.io/api/cosmos/base/v1beta1" + proof "github.com/pokt-network/poktroll/api/poktroll/proof" fmt "fmt" _ "github.com/cosmos/cosmos-proto" runtime "github.com/cosmos/cosmos-proto/runtime" _ "github.com/cosmos/gogoproto/gogoproto" - proof "github.com/pokt-network/poktroll/api/poktroll/proof" protoreflect "google.golang.org/protobuf/reflect/protoreflect" protoiface "google.golang.org/protobuf/runtime/protoiface" protoimpl "google.golang.org/protobuf/runtime/protoimpl" From afa7c8646c011884d227ee679f69f54cf6ba8d95 Mon Sep 17 00:00:00 2001 From: Daniel Olshansky Date: Tue, 26 Nov 2024 12:57:05 -0800 Subject: [PATCH 5/7] [Docs] Beta TestNet - Service Cheatsheet (#965) Cheatsheet to add a new onchain `Service` plus a few other improvements. - Add a service quickstart - Update `.gitignore` w/ a few config files - Add `tl;dr` to `CLI installation` and use account setup` - Add instructions on creating a new Debian user --- Co-authored-by: Redouane Lakrache Co-authored-by: Dima K. --- .gitignore | 7 +- .../docker_compose_debian_cheatsheet.md | 13 ++- .../quickstart/docker_compose_walkthrough.md | 38 +++++++- .../operate/quickstart/service_cheatsheet.md | 90 ++++++++++++++++++- .../operate/quickstart/supplier_cheatsheet.md | 14 --- .../operate/user_guide/create-new-wallet.md | 23 ++++- docusaurus/docs/operate/user_guide/install.md | 23 +++-- 7 files changed, 178 insertions(+), 30 deletions(-) delete mode 100644 docusaurus/docs/operate/quickstart/supplier_cheatsheet.md diff --git a/.gitignore b/.gitignore index f444c077b..862f41be0 100644 --- a/.gitignore +++ b/.gitignore @@ -100,4 +100,9 @@ cmd/poktrolld/*debug_bin* job.yaml # tmp directory for locally produced artifacts -tmp/* \ No newline at end of file +tmp/* + +# Common testing configurations +relayminer_config.yaml +gateway_config.yaml +path_config.yaml diff --git a/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md b/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md index 6493b012e..ad7d2b632 100644 --- a/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md @@ -26,7 +26,6 @@ import ReactPlayer from "react-player"; - [Faucet is not ready and you need to fund the accounts manually](#faucet-is-not-ready-and-you-need-to-fund-the-accounts-manually) - [Start the RelayMiner](#start-the-relayminer) - [Start the AppGate Server](#start-the-appgate-server) - - [Re-stake the gateway](#re-stake-the-gateway) ## Results @@ -85,6 +84,16 @@ And then install docker: sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ``` +### [Optional] Create a new user + +You can optionally create a new user and give it sudo permissions instead of using `root`. + +```bash +export USERNAME=olshansky +sudo adduser $USERNAME +sudo usermod -aG sudo $USERNAME +``` + ## Retrieve the source code Then pull the github repo @@ -320,5 +329,3 @@ docker compose up -d appgate # View docker logs -f --tail 100 appgate ``` - -### Re-stake the gateway diff --git a/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md b/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md index ca58321bc..1d0518d7f 100644 --- a/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md +++ b/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md @@ -115,7 +115,7 @@ flowchart TB _Note: the system must be capable of exposing ports to the internet for peer-to-peer communication._ -### 0. Software & Tooling +### Software & Tooling Ensure the following software is installed on your system: @@ -152,6 +152,42 @@ Update `NODE_HOSTNAME` in `.env` to the IP address or hostname of your node. For sed -i -e s/NODE_HOSTNAME=/NODE_HOSTNAME=69.42.690.420/g .env ``` +### [Optional] Create a new user + +:::note + +Make sure to replace `olshansky` with your username. + +::: + +You can generally do everything as the `root` user, but it's recommended to +create a new user and give it sudo permissions. + +This is necessary, in particular, if you want to use [homebrew](https://brew.sh/) [to install `poktrolld`](../user_guide/install.md). + +```bash +# Create a new user and give sudo permissions +export USERNAME=olshansky +sudo adduser $USERNAME +sudo usermod -aG sudo $USERNAME +``` + +Then, switch to the new user: + +```bash +su - olshansky +``` + +You can also avoid needing to pass in the password each time by running the following: + +```bash +# Optionally avoid needing to provide a password +sudo vi /etc/sudoers + +# Add the following line to the end of the file +olshansky ALL=(ALL) NOPASSWD:ALL +``` + ## A. Deploying a Full Node ### Launch the Node diff --git a/docusaurus/docs/operate/quickstart/service_cheatsheet.md b/docusaurus/docs/operate/quickstart/service_cheatsheet.md index e7a99290c..c1cfa6bf0 100644 --- a/docusaurus/docs/operate/quickstart/service_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/service_cheatsheet.md @@ -5,4 +5,92 @@ title: Service Cheat Sheet ## Service Cheat Sheet -TODO_BETA(@olshansk): Document how to add a service onchain. +- [Pre-Requisites](#pre-requisites) +- [How do I query for all existing onchain Services?](#how-do-i-query-for-all-existing-onchain-services) +- [How do I create a new service?](#how-do-i-create-a-new-service) +- [How do I learn more about interacting with Services?](#how-do-i-learn-more-about-interacting-with-services) + - [Service Transactions](#service-transactions) + - [Service Queries](#service-queries) + +### Pre-Requisites + +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). + +### How do I query for all existing onchain Services? + +You can query for all services like so: + +```bash +poktrolld query service all-services --node https://shannon-testnet-grove-rpc.beta.poktroll.com --output json | jq +``` + +Here is an example of the output on Beta TestNet as of writing this document: + +```json +{ + "service": [ + { + "id": "svc_8ymf38", + "name": "name for svc_8ymf38", + "compute_units_per_relay": "7", + "owner_address": "pokt1aqsr8ejvwwnjwx3ppp234l586kl06cvas7ag6w" + }, + { + "id": "svc_drce83", + "name": "name for svc_drce83", + "compute_units_per_relay": "7", + "owner_address": "pokt1mgtf9k4k3pze57gwp3qsne88jmvqkc37t7vd9g" + }, + { + "id": "svc_jk07qh", + "name": "name for svc_jk07qh", + "compute_units_per_relay": "7", + "owner_address": "pokt1mwynfsnzesc38f98zrk08pttjn48tu7crc2p09" + } + ], + "pagination": { + "total": "3" + } +} +``` + +### How do I create a new service? + +You can use the `add-service` command to create a new service like so: + +```bash +poktrolld tx service add-service ${SERVICE_ID} "${SERVICE_NAME_OR_DESCRIPTION}" ${COMPUTE_UNITS_PER_RELAY} --from ${SERVICE_OWNER} +``` + +Here is a concrete copy-pasta assuming you have created and funded a new account called `$USER`: + +```bash +poktrolld tx service add-service "svc-$USER" "service description for $USER" 69 \ + --node https://shannon-testnet-grove-rpc.beta.poktroll.com \ + --fees 1upokt --from $USER --chain-id pocket-beta +``` + +Optionally, you can add some more flags to be ultra-verbose about your local environment: + +```bash +poktrolld tx service add-service "svc-$USER" "service description for $USER" 69 \ + --node https://shannon-testnet-grove-rpc.beta.poktroll.com \ + --fees 1upokt --from $USER --chain-id pocket-beta \ + --home ~/.poktroll --keyring-backend test \ + --yes --output json +``` + +### How do I learn more about interacting with Services? + +#### Service Transactions + +```bash +poktrolld tx service -h +``` + +#### Service Queries + +```bash +poktrolld query service -h +``` diff --git a/docusaurus/docs/operate/quickstart/supplier_cheatsheet.md b/docusaurus/docs/operate/quickstart/supplier_cheatsheet.md deleted file mode 100644 index 5e991ed70..000000000 --- a/docusaurus/docs/operate/quickstart/supplier_cheatsheet.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -sidebar_position: 4 -title: Supplier Cheat Sheet ---- - -## Supplier Cheat Sheet - -:::tip - -See the [Supplier Walkthrough](./../run_a_node/supplier_walkthrough.md) for an in-depth guide on setting up a Supplier. - -::: - -TODO_BETA(@olshansk): Finish this page. diff --git a/docusaurus/docs/operate/user_guide/create-new-wallet.md b/docusaurus/docs/operate/user_guide/create-new-wallet.md index 6a2af0e61..8df204d14 100644 --- a/docusaurus/docs/operate/user_guide/create-new-wallet.md +++ b/docusaurus/docs/operate/user_guide/create-new-wallet.md @@ -5,11 +5,18 @@ sidebar_position: 1 # Create a New Wallet -:::warning Security Notice +:::warning -**ALWAYS back up your key and/or mnemonic**. Store it in a secure -location accessible only to you, such as a password manager, or written down -in a safe place. Under your πŸ›οΈ does not count! +tl;dr IFF you know what you're doing. + +```bash +# Add a new wallet +poktrolld keys add $USER +# Retrieve the address +poktrolld keys show $USER -a +``` + +Use the `address` and go to the [Beta TestNet Faucet](https://faucet.beta.testnet.pokt.network/) to fund your account. ::: @@ -20,6 +27,14 @@ This guide will walk you through creating a new wallet on the Pocket Network. - [Step 2: Creating the Wallet](#step-2-creating-the-wallet) - [Step 3: Backing Up Your Wallet](#step-3-backing-up-your-wallet) +:::warning Security Notice + +**ALWAYS back up your key and/or mnemonic**. Store it in a secure +location accessible only to you, such as a password manager, or written down +in a safe place. Under your πŸ›οΈ does not count! + +::: + ## What is a keyring backend? Before proceeding, it's critical to understand the implications of keyring backends diff --git a/docusaurus/docs/operate/user_guide/install.md b/docusaurus/docs/operate/user_guide/install.md index b19473f01..4c20f0824 100644 --- a/docusaurus/docs/operate/user_guide/install.md +++ b/docusaurus/docs/operate/user_guide/install.md @@ -3,6 +3,17 @@ title: CLI Installation sidebar_position: 0 --- +:::warning + +tl;dr IFF you know what you're doing. + +```bash +brew tap pokt-network/poktroll +brew install poktrolld +``` + +::: + - [MacOS \& Linux Users](#macos--linux-users) - [Using Homebrew](#using-homebrew) - [From Source](#from-source) @@ -13,12 +24,6 @@ sidebar_position: 0 ### Using Homebrew -:::tip -See the [homebrew-poktroll](https://github.com/pokt-network/homebrew-poktroll/) -repository for details on how to install homebrew or other details to install -or debug the CLI. -::: - Ensure you have [Homebrew](https://brew.sh/) installed. Then run the following commands: @@ -35,6 +40,12 @@ poktrolld version poktrolld --help ``` +:::tip +See the [homebrew-poktroll](https://github.com/pokt-network/homebrew-poktroll/) +repository for details on how to install homebrew or other details to install +or debug the CLI. +::: + ### From Source Ensure you have the following installed: From fa86fe8716101dedfbdd98b3e5a2e3a68bd85bb5 Mon Sep 17 00:00:00 2001 From: "Dima K." Date: Wed, 27 Nov 2024 15:13:37 -0800 Subject: [PATCH 6/7] [Docs] Upgrade list (#928) ## Summary Add recent Alpha TestNet upgrades ## Type of change Select one or more from the following: - [ ] New feature, functionality or library - [ ] Consensus breaking; add the `consensus-breaking` label if so. See #791 for details - [ ] Bug fix - [ ] Code health or cleanup - [x] Documentation - [ ] Other (specify) ## Testing - [x] **Documentation**: `make docusaurus_start`; only needed if you make doc changes - [ ] **Unit Tests**: `make go_develop_and_test` - [ ] **LocalNet E2E Tests**: `make test_e2e` - [ ] **DevNet E2E Tests**: Add the `devnet-test-e2e` label to the PR. ## Sanity Checklist - [x] I have tested my changes using the available tooling - [ ] I have commented my code - [x] I have performed a self-review of my own code; both comments & source code - [ ] I create and reference any new tickets, if applicable - [x] I have left TODOs throughout the codebase, if applicable --------- Co-authored-by: Daniel Olshansky --- .../docker_compose_debian_cheatsheet.md | 7 ++++ .../quickstart/docker_compose_walkthrough.md | 5 +++ .../docs/protocol/upgrades/upgrade_list.md | 35 ++++++++++++------- tools/scripts/tx_jsons/staking_params.json | 18 ++++++++++ .../scripts/tx_jsons/staking_validator2.json | 16 +++++++++ .../scripts/tx_jsons/staking_validator3.json | 16 +++++++++ 6 files changed, 85 insertions(+), 12 deletions(-) create mode 100644 tools/scripts/tx_jsons/staking_params.json create mode 100644 tools/scripts/tx_jsons/staking_validator2.json create mode 100644 tools/scripts/tx_jsons/staking_validator3.json diff --git a/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md b/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md index ad7d2b632..c75358cb1 100644 --- a/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md @@ -119,6 +119,13 @@ 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/docker_compose_walkthrough.md b/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md index 1d0518d7f..e2a83d340 100644 --- a/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md +++ b/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md @@ -192,6 +192,11 @@ olshansky ALL=(ALL) NOPASSWD:ALL ### Launch the 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. +::: + _Note: You may need to replace `docker-compose` with `docker compose` if you are running a newer version of Docker where `docker-compose` is integrated into `docker` itself._ diff --git a/docusaurus/docs/protocol/upgrades/upgrade_list.md b/docusaurus/docs/protocol/upgrades/upgrade_list.md index f4b2c8d19..6480086c3 100644 --- a/docusaurus/docs/protocol/upgrades/upgrade_list.md +++ b/docusaurus/docs/protocol/upgrades/upgrade_list.md @@ -8,8 +8,10 @@ sidebar_position: 1 The tables below provide a list of past and upcoming protocol upgrades. For more detailed information about what upgrades are, how they work, and what changes they bring to the protocol, please refer to our [upgrade overview page](./protocol_upgrades.md). - [Legend](#legend) -- [TestNet](#testnet) - [MainNet](#mainnet) +- [Beta TestNet](#beta-testnet) +- [Alpha TestNet](#alpha-testnet) + - [Syncing from genesis - manual steps](#syncing-from-genesis---manual-steps) ## Legend @@ -18,21 +20,30 @@ The tables below provide a list of past and upcoming protocol upgrades. For more - ❓ - Unknown/To Be Determined - ⚠️ - Warning/Caution Required -## TestNet +## MainNet +Coming... + +## Beta TestNet +| Version | Planned | Breaking | Requires Manual Intervention | Upgrade Height | +| -------------------------------------------------------------------------------- | :-----: | :------: | :--------------------------: | -------------- | +| [`v0.0.11-rc`](https://github.com/pokt-network/poktroll/releases/tag/v0.0.11-rc) | N/A | N/A | ❌ genesis version | N/A | + +## Alpha TestNet :::warning -This table is currently incomplete and does not include all protocol upgrades. Our recent TestNet upgrades, which were performed via a regenesis, are not listed here. +Some manual steps are currently required to sync to the latest block. Please follow instructions below. ::: - + -| Version | Planned | Breaking | Requires Manual Intervention | Upgrade Height | -| ------------------------------------------------------------------------ | :-----: | :------: | :---------------------------------: | -------------- | -| [`v0.0.7`](https://github.com/pokt-network/poktroll/releases/tag/v0.0.7) | ❓ | ❓ | βœ… (Alpha TestNet Participants Only) | ❓ | -| [`v0.0.6`](https://github.com/pokt-network/poktroll/releases/tag/v0.0.6) | ❓ | ❓ | βœ… (Alpha TestNet Participants Only) | ❓ | -| [`v0.0.5`](https://github.com/pokt-network/poktroll/releases/tag/v0.0.5) | ❓ | ❓ | βœ… (Alpha TestNet Participants Only) | ❓ | -| [`v0.0.4`](https://github.com/pokt-network/poktroll/releases/tag/v0.0.4) | ❓ | ❓ | βœ… (Alpha TestNet Participants Only) | ❓ | +| Version | Planned | Breaking | Requires Manual Intervention | Upgrade Height | +| ---------------------------------------------------------------------------- | :-----: | :------: | :--------------------------------------------------------------------------------------------------------------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------- | +| [`v0.0.10`](https://github.com/pokt-network/poktroll/releases/tag/v0.0.10) | βœ… | βœ… | ❌ (automatic upgrade) | [56860](https://shannon.alpha.testnet.pokt.network/poktroll/tx/4E201E5C397AB881F417266154C907D38404BE00BE9A443DE28E44A2B09C5CFB) | +| [`v0.0.9-4`](https://github.com/pokt-network/poktroll/releases/tag/v0.0.9-4) | ❌ | βœ… | ⚠️ [follow manual upgrade instructions](https://github.com/pokt-network/poktroll/releases/tag/v0.0.9-4) ⚠️ | `46329` | +| [`v0.0.9-3`](https://github.com/pokt-network/poktroll/releases/tag/v0.0.9-3) | ❌ | βœ… | ❌ Active Alpha TestNet Participants Only: [follow manual upgrade instructions](https://github.com/pokt-network/poktroll/releases/tag/v0.0.9-3) | `17102` | +| [`v0.0.9`](https://github.com/pokt-network/poktroll/releases/tag/v0.0.9) | N/A | N/A | ❌ genesis version | N/A | -## MainNet +### Syncing from genesis - manual steps + -Coming... +When syncing Alpha TestNet from the first block, the node will fail at height `46329`. Some manual steps are required in order for it to continue. Please [follow manual upgrade instructions](https://github.com/pokt-network/poktroll/releases/tag/v0.0.9-4). diff --git a/tools/scripts/tx_jsons/staking_params.json b/tools/scripts/tx_jsons/staking_params.json new file mode 100644 index 000000000..fc5074a44 --- /dev/null +++ b/tools/scripts/tx_jsons/staking_params.json @@ -0,0 +1,18 @@ +{ + "body": { + "messages": [ + { + "@type": "/cosmos.staking.v1beta1.MsgUpdateParams", + "authority": "pokt10d07y265gmmuvt4z0w9aw880jnsr700j8yv32t", + "params": { + "bond_denom": "upokt", + "historical_entries": 10000, + "max_entries": 7, + "max_validators": 3, + "min_commission_rate": "0", + "unbonding_time": "504h0m0s" + } + } + ] + } +} \ No newline at end of file diff --git a/tools/scripts/tx_jsons/staking_validator2.json b/tools/scripts/tx_jsons/staking_validator2.json new file mode 100644 index 000000000..d64e2db42 --- /dev/null +++ b/tools/scripts/tx_jsons/staking_validator2.json @@ -0,0 +1,16 @@ +{ + "pubkey": { + "@type": "/cosmos.crypto.ed25519.PubKey", + "key": "ojUaD7c/Ssmor53eOMl0BNczr4u1VdgVnUL+IQFcC/g=" + }, + "amount": "900000000upokt", + "moniker": "validator2", + "identity": "", + "website": "", + "security": "", + "details": "", + "commission-rate": "0.100000000000000000", + "commission-max-rate": "0.200000000000000000", + "commission-max-change-rate": "0.01000000000000000", + "min-self-delegation": "1" +} \ No newline at end of file diff --git a/tools/scripts/tx_jsons/staking_validator3.json b/tools/scripts/tx_jsons/staking_validator3.json new file mode 100644 index 000000000..86c76a7a1 --- /dev/null +++ b/tools/scripts/tx_jsons/staking_validator3.json @@ -0,0 +1,16 @@ +{ + "pubkey": { + "@type": "/cosmos.crypto.ed25519.PubKey", + "key": "U+Qi//fZhYtbr25PsWqFQZpxft3erzyrg2cWbLOj6+A=" + }, + "amount": "900000000upokt", + "moniker": "validator3", + "identity": "", + "website": "", + "security": "", + "details": "", + "commission-rate": "0.100000000000000000", + "commission-max-rate": "0.200000000000000000", + "commission-max-change-rate": "0.01000000000000000", + "min-self-delegation": "1" +} \ No newline at end of file From 76d131c07540581a2541de27536f1c7cdd738f35 Mon Sep 17 00:00:00 2001 From: "Dima K." Date: Wed, 27 Nov 2024 15:25:41 -0800 Subject: [PATCH 7/7] [Docs/Tools] Validator: support multiple networks + cheat sheet (#941) ## Summary Allows to support multiple networks in the installation script. ## Issue - https://github.com/pokt-network/pocket-network-genesis/pull/9 --- .../docker_compose_debian_cheatsheet.md | 21 +- .../quickstart/full_node_cheatsheet.md | 145 ++++++++++ .../quickstart/validator_cheatsheet.md | 14 - .../run_a_node/full_node_cosmovisor.md | 108 -------- .../run_a_node/full_node_walkthrough.md | 252 ++++++++++++++++++ .../run_a_node/validator_walkthrough.md | 8 - .../protocol/upgrades/protocol_upgrades.md | 2 +- .../protocol/upgrades/upgrade_procedure.md | 4 +- tools/installer/full-node.sh | 147 ++++++++-- 9 files changed, 544 insertions(+), 157 deletions(-) create mode 100644 docusaurus/docs/operate/quickstart/full_node_cheatsheet.md delete mode 100644 docusaurus/docs/operate/quickstart/validator_cheatsheet.md delete mode 100644 docusaurus/docs/operate/run_a_node/full_node_cosmovisor.md create mode 100644 docusaurus/docs/operate/run_a_node/full_node_walkthrough.md delete mode 100644 docusaurus/docs/operate/run_a_node/validator_walkthrough.md diff --git a/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md b/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md index c75358cb1..7a1157639 100644 --- a/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md @@ -72,7 +72,7 @@ sudo apt-get update if command -v ufw > /dev/null 2>&1; then sudo ufw allow from 172.16.0.0/12 sudo ufw allow from 192.168.0.0/16 - echo "UFW rules added for Docker networks" + echo "UFW rules added for Docker networks and validator endpoint" else echo "UFW is not installed, skipping firewall configuration" fi @@ -106,9 +106,18 @@ 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 @@ -169,15 +178,19 @@ FINALLY, `source .env` to update the environment variables. ## Fund your accounts -Run the following: +Run the following to see your addresses: ```bash show_actor_addresses ``` -For each one, fund the accounts using the [faucet](https://faucet.testnet.pokt.network/) +Get the faucet URL for your network: + +```bash +show_faucet_url +``` -Next, run this helper (it's part of `helpers.sh`) to find each of them on the explorer: +Fund each address using the faucet URL shown above. Then run this helper to find each account on the explorer: ```bash show_explorer_urls diff --git a/docusaurus/docs/operate/quickstart/full_node_cheatsheet.md b/docusaurus/docs/operate/quickstart/full_node_cheatsheet.md new file mode 100644 index 000000000..d2986bb30 --- /dev/null +++ b/docusaurus/docs/operate/quickstart/full_node_cheatsheet.md @@ -0,0 +1,145 @@ +--- +sidebar_position: 3 +title: Full Node Cheat Sheet +--- + +This cheat sheet provides quick instructions for installing a Full Node using an automated script. + +- [Pre-Requisites](#pre-requisites) +- [Install a Full Node using Cosmovisor](#install-a-full-node-using-cosmovisor) +- [What Gets Installed](#what-gets-installed) +- [Useful Commands](#useful-commands) + - [Check the status of your node](#check-the-status-of-your-node) + - [View the logs](#view-the-logs) + - [Stop the node](#stop-the-node) + - [Start the node](#start-the-node) + - [Restart the node](#restart-the-node) + - [Advanced Operations](#advanced-operations) +- [Automatic Upgrades](#automatic-upgrades) + +### Pre-Requisites + +1. **Linux-based System**: Ensure you have a Debian-based Linux distribution (other distributions may work but are not fully supported). +2. **Root or Sudo Access**: You need administrative privileges to run the installation script. +3. **Dedicated Server or Virtual Machine**: Any provider should work (Vultr and Hetzner have been tested). + +### Install a Full Node using Cosmovisor + +To install and set up a Full Node, follow these steps: + +1. **Download the Installation Script**: + + ```bash + curl -O https://raw.githubusercontent.com/pokt-network/poktroll/main/tools/installer/full-node.sh + ``` + +2. **Run the Script with Sudo Privileges**: + + ```bash + sudo bash full-node.sh + ``` + +3. **Follow the Prompts**: + + - **Choose the Network**: Select `testnet-alpha`, `testnet-beta`, or `mainnet`. + - **Set Username**: Input the desired username to run `poktrolld` (default: `poktroll`). + - **Set Node Moniker**: Input the node moniker (default: your hostname). + - **Confirm Seeds and Genesis File**: The script fetches seeds and the genesis file automatically. + - **External IP Address**: The script detects your external IP address. Confirm or input manually if incorrect. + +The script will handle the installation of dependencies, user creation, environment variable setup, and configuration of Cosmovisor and `poktrolld`. + +### What Gets Installed + +When you run the installation script, the following components are set up: + +1. **System User**: A dedicated user (default: `poktroll`) is created to run the node securely. + +2. **Cosmovisor**: A binary manager that handles chain upgrades automatically: + - Location: `/home/poktroll/bin/cosmovisor` + - Purpose: Manages different versions of `poktrolld` and handles chain upgrades + - Configuration: Set up to automatically download and switch to new binaries during upgrades + +3. **Poktrolld**: The core node software: + - Location: `/home/poktroll/.poktroll/cosmovisor/genesis/bin/poktrolld` + - Configuration: `/home/poktroll/.poktroll/config/` + - Data: `/home/poktroll/.poktroll/data/` + +4. **Systemd Service**: A service that manages the node: + - Name: `cosmovisor.service` + - Status: Enabled and started automatically + - Configured for automatic restarts and upgrades + +### Useful Commands + +After installation, you can manage your node using the following commands: + +#### Check the status of your node + +```bash +sudo systemctl status cosmovisor.service +``` + +#### View the logs + +```bash +sudo journalctl -u cosmovisor.service -f +``` + +#### Stop the node + +```bash +sudo systemctl stop cosmovisor.service +``` + +#### Start the node + +```bash +sudo systemctl start cosmovisor.service +``` + +#### Restart the node + +```bash +sudo systemctl restart cosmovisor.service +``` + +#### Advanced Operations + +Check the current version: +```bash +sudo -u poktroll poktrolld version +``` + +View the Cosmovisor directory structure: +```bash +ls -la /home/poktroll/.poktroll/cosmovisor/ +``` + +Check if an upgrade is available: +```bash +ls -la /home/poktroll/.poktroll/cosmovisor/upgrades/ +``` + +View node configuration: +```bash +cat /home/poktroll/.poktroll/config/config.toml +``` + +### Automatic Upgrades + +Your node is configured to handle chain upgrades automatically through Cosmovisor. When a chain upgrade is proposed and approved: + +1. Cosmovisor will download the new binary +2. The node will stop at the designated upgrade height +3. Cosmovisor will switch to the new binary +4. The node will restart automatically + +No manual intervention is required for standard upgrades. + + diff --git a/docusaurus/docs/operate/quickstart/validator_cheatsheet.md b/docusaurus/docs/operate/quickstart/validator_cheatsheet.md deleted file mode 100644 index d09097e4b..000000000 --- a/docusaurus/docs/operate/quickstart/validator_cheatsheet.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -sidebar_position: 3 -title: Validator Cheat Sheet ---- - -## Validator Cheat Sheet - -:::tip - -See the [Validator Walkthrough](./../run_a_node/validator_walkthrough.md) for an in-depth guide on setting up a Validator Node. - -::: - -TODO_BETA(@okdas): Finish this page. diff --git a/docusaurus/docs/operate/run_a_node/full_node_cosmovisor.md b/docusaurus/docs/operate/run_a_node/full_node_cosmovisor.md deleted file mode 100644 index e8bb2ee3b..000000000 --- a/docusaurus/docs/operate/run_a_node/full_node_cosmovisor.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Full Node (Cosmovisor) -sidebar_position: 2 ---- - -## Run a Full Node using Cosmovisor - -This document provides instructions on using the official Cosmos SDK [Cosmosvisor](https://docs.cosmos.network/v0.45/run-node/cosmovisor.html) to run a full Pocket Network node. - -- [What is a Full Node](#what-is-a-full-node) -- [What is Cosmovisor](#what-is-cosmovisor) -- [Installation Instructions](#installation-instructions) - - [Prerequisites](#prerequisites) - - [Installation Steps](#installation-steps) -- [Useful Command Cheat Sheet](#useful-command-cheat-sheet) - - [Check the status of your node](#check-the-status-of-your-node) - - [View the logs](#view-the-logs) - - [Stop the node](#stop-the-node) - - [Start the node](#start-the-node) - - [Restart the node](#restart-the-node) - -### What is a Full Node - -In blockchain networks, a full node retains continuous synchs and updates the latest copy of the ledger. It may either be a pruned full node (the latest data only) or an archival full node (including complete and historical data). - -You can visit the [Cosmos SDK documentation](https://docs.cosmos.network/main/user/run-node/run-node) for more information on Full Nodes. - -### What is Cosmovisor - -[Cosmovisor](https://docs.cosmos.network/main/build/tooling/cosmovisor) is a tool that automates the version management for our blockchain. It allows operators to automatically upgrade their full nodes and validators without downtime and reduce maintenance overhead. - -### Installation Instructions - -To install and set up a Poktroll Full Node using Cosmovisor, we provide a comprehensive installation script. This script will handle all the necessary steps, including user creation, dependency installation, Cosmovisor and Poktrolld setup, and system configuration. - -#### Prerequisites - -- A Linux-based system (Debian-based distributions are fully supported, others may work as well) -- Root or sudo access -- A dedicated server or a virtual machine (any provider should work, Vultr and Hetzner have been tested) - -#### Installation Steps - -1. Download the installation script: - - ```bash - curl -O https://raw.githubusercontent.com/pokt-network/poktroll/main/tools/installer/full-node.sh - ``` - -2. Make the script executable: - - ```bash - chmod +x full-node.sh - ``` - -3. Run the script with sudo privileges: - - ```bash - sudo ./full-node.sh - ``` - -4. Follow the prompts to provide the necessary information: - - Desired username to run poktrolld (`default: poktroll`) - - Node moniker (`default: hostname`) - - Seeds (`default: fetched` [from the official source](https://github.com/pokt-network/pocket-network-genesis/tree/master/shannon/alpha)) - - Chain ID (`default: poktroll-testnet`) - -The script will then proceed with the installation and setup process. - -### Useful Command Cheat Sheet - -After the installation is complete, your Poktroll Full Node should be up and running. - -:::tip -Remember to keep your system updated and monitor your node regularly to ensure its proper functioning and security. -::: - -Here are some useful commands for managing your node: - -#### Check the status of your node - -```bash - sudo systemctl status cosmovisor.service -``` - -#### View the logs - -```bash -sudo journalctl -u cosmovisor.service -f -``` - -#### Stop the node - -```bash -sudo systemctl stop cosmovisor.service -``` - -#### Start the node - -```bash -sudo systemctl start cosmovisor.service -``` - -#### Restart the node - -```bash -sudo systemctl restart cosmovisor.service -``` diff --git a/docusaurus/docs/operate/run_a_node/full_node_walkthrough.md b/docusaurus/docs/operate/run_a_node/full_node_walkthrough.md new file mode 100644 index 000000000..d0adb768c --- /dev/null +++ b/docusaurus/docs/operate/run_a_node/full_node_walkthrough.md @@ -0,0 +1,252 @@ +--- +title: Full Node (systemd) +sidebar_position: 2 +--- + +## Run a Validator + +This walkthrough provides step-by-step instructions to manually install and configure a Full Node from scratch. + +- [Introduction](#introduction) +- [Pre-Requisites](#pre-requisites) +- [Step 1: Create a New User](#step-1-create-a-new-user) +- [Step 2: Install Dependencies](#step-2-install-dependencies) +- [Step 3: Set Up Environment Variables](#step-3-set-up-environment-variables) +- [Step 4: Install Cosmovisor](#step-4-install-cosmovisor) +- [Step 5: Install `poktrolld`](#step-5-install-poktrolld) +- [Step 6: Configure `poktrolld`](#step-6-configure-poktrolld) +- [Step 7: Set Up `systemd` Service](#step-7-set-up-systemd-service) +- [Step 8: Open Firewall Ports](#step-8-open-firewall-ports) +- [Next Steps](#next-steps) + +### Introduction + +This guide will help you install a Full Node for Pocket Network manually, giving you control over each step of the process. Running a Full Node is the first step toward becoming a Validator. + +**TL;DR**: If you're comfortable using an automated script, check out the [Full Node Cheat Sheet](../quickstart/full_node_cheatsheet.md) for quick setup instructions. + +### Pre-Requisites + +- **Linux-based System**: Preferably Debian-based distributions. +- **Root or Sudo Access**: Administrative privileges are required. +- **Dedicated Server or Virtual Machine**: Any provider is acceptable. + +### Step 1: Create a New User + +Create a dedicated user to run `poktrolld`: + +```bash +sudo adduser poktroll +``` + +Set a password when prompted, and add the user to the sudo group: + +```bash +sudo usermod -aG sudo poktroll +``` + +### Step 2: Install Dependencies + +Update your package list and install necessary dependencies: + +```bash +sudo apt-get update +sudo apt-get install -y curl tar wget jq +``` + +### Step 3: Set Up Environment Variables + +Switch to the `poktroll` user and set environment variables required for Cosmovisor: + +```bash +sudo su - poktroll +``` + +Add the following to your `.profile`: + +```bash +echo "export DAEMON_NAME=poktrolld" >> ~/.profile +echo "export DAEMON_HOME=\$HOME/.poktroll" >> ~/.profile +echo "export DAEMON_RESTART_AFTER_UPGRADE=true" >> ~/.profile +echo "export DAEMON_ALLOW_DOWNLOAD_BINARIES=true" >> ~/.profile +echo "export UNSAFE_SKIP_BACKUP=false" >> ~/.profile +source ~/.profile +``` + +### Step 4: Install Cosmovisor + +Download and install Cosmovisor: + +:::info +Alternatively, you can follow the [official cosmovisor installation instructions](https://docs.cosmos.network/main/build/tooling/cosmovisor#installation). +::: + +```bash +mkdir -p $HOME/.local/bin +COSMOVISOR_VERSION="v1.6.0" +ARCH=$(uname -m) +if [ "$ARCH" = "x86_64" ]; then + ARCH="amd64" +elif [ "$ARCH" = "aarch64" ]; then + ARCH="arm64" +fi + +curl -L "https://github.com/cosmos/cosmos-sdk/releases/download/cosmovisor%2F${COSMOVISOR_VERSION}/cosmovisor-${COSMOVISOR_VERSION}-linux-${ARCH}.tar.gz" | tar -zxvf - -C $HOME/.local/bin +echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.profile +source ~/.profile +``` + + +### Step 5: Install `poktrolld` + +Download and install `poktrolld`: + +1. **Download Genesis and Extract Version**: + + ```bash + # Select network (testnet-alpha, testnet-beta, or mainnet) + NETWORK="testnet-beta" # Change this to your desired network + + # Create config directory if it doesn't exist + mkdir -p $HOME/.poktroll/config + + # Download genesis file + GENESIS_URL="https://raw.githubusercontent.com/pokt-network/pocket-network-genesis/master/shannon/${NETWORK}/genesis.json" + curl -s -o $HOME/.poktroll/config/genesis.json "$GENESIS_URL" + + # Extract version and set architecture + POKTROLLD_VERSION=$(jq -r '.app_version' < $HOME/.poktroll/config/genesis.json) + ARCH=$(uname -m) + if [ "$ARCH" = "x86_64" ]; then ARCH="amd64" + elif [ "$ARCH" = "aarch64" ]; then ARCH="arm64" + fi + ``` + +2. **Download and Install the Binary**: + + Create the cosmovisor genesis directory and download the binary. + ```bash + mkdir -p $HOME/.poktroll/cosmovisor/genesis/bin + curl -L "https://github.com/pokt-network/poktroll/releases/download/v${POKTROLLD_VERSION}/poktroll_linux_${ARCH}.tar.gz" | tar -zxvf - -C $HOME/.poktroll/cosmovisor/genesis/bin + chmod +x $HOME/.poktroll/cosmovisor/genesis/bin/poktrolld + ln -sf $HOME/.poktroll/cosmovisor/genesis/bin/poktrolld $HOME/.local/bin/poktrolld + ``` + +### Step 6: Configure `poktrolld` + +Initialize configuration files and set up the node: + +1. **Extract Chain ID and Initialize Node**: + + ```bash + # Extract chain-id from existing genesis + CHAIN_ID=$(jq -r '.chain_id' < $HOME/.poktroll/config/genesis.json) + + # Initialize the node + poktrolld init "YourNodeMoniker" --chain-id="$CHAIN_ID" --home=$HOME/.poktroll + ``` + + :::note + You may see a message saying `genesis.json file already exists`. This is expected since we downloaded the genesis file in Step 5. The initialization will still complete successfully and set up the required configuration files. + ::: + +2. **Set Seeds**: + + ```bash + SEEDS_URL="https://raw.githubusercontent.com/pokt-network/pocket-network-genesis/master/shannon/${NETWORK}/seeds" + SEEDS=$(curl -s "$SEEDS_URL") + sed -i -e "s|^seeds *=.*|seeds = \"$SEEDS\"|" $HOME/.poktroll/config/config.toml + ``` + +3. **Set External Address**: + + ```bash + EXTERNAL_IP=$(curl -s https://api.ipify.org) + sed -i -e "s|^external_address *=.*|external_address = \"${EXTERNAL_IP}:26656\"|" $HOME/.poktroll/config/config.toml + ``` + +### Step 7: Set Up `systemd` Service + +Create a `systemd` service file to manage the node: + +```bash +sudo tee /etc/systemd/system/cosmovisor.service > /dev/null < diff --git a/docusaurus/docs/operate/run_a_node/validator_walkthrough.md b/docusaurus/docs/operate/run_a_node/validator_walkthrough.md deleted file mode 100644 index 49fabfb3a..000000000 --- a/docusaurus/docs/operate/run_a_node/validator_walkthrough.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Validator Walkthrough -sidebar_position: 6 ---- - -# Run a Validator - -TODO_BETA(@okdas): Update this page with all the details. diff --git a/docusaurus/docs/protocol/upgrades/protocol_upgrades.md b/docusaurus/docs/protocol/upgrades/protocol_upgrades.md index 61b86e29e..684bc8e7a 100644 --- a/docusaurus/docs/protocol/upgrades/protocol_upgrades.md +++ b/docusaurus/docs/protocol/upgrades/protocol_upgrades.md @@ -5,7 +5,7 @@ sidebar_position: 1 # Protocol Upgrades -Pocket Network is continuously evolving through regular protocol upgrades. We implement software upgrades via a DAO process, allowing validator nodes to incorporate consensus-breaking changes. These upgrades can be automatically applied when using [Cosmovisor](../../operate/run_a_node/full_node_cosmovisor.md), or manually if not using `cosmovisor`. +Pocket Network is continuously evolving through regular protocol upgrades. We implement software upgrades via a DAO process, allowing validator nodes to incorporate consensus-breaking changes. These upgrades can be automatically applied when using [Cosmovisor](../../operate/run_a_node/full_node_walkthrough.md), or manually if not using `cosmovisor`. - [What is a Protocol Upgrade?](#what-is-a-protocol-upgrade) - [List of Upgrades](#list-of-upgrades) diff --git a/docusaurus/docs/protocol/upgrades/upgrade_procedure.md b/docusaurus/docs/protocol/upgrades/upgrade_procedure.md index b1098f509..2e0998251 100644 --- a/docusaurus/docs/protocol/upgrades/upgrade_procedure.md +++ b/docusaurus/docs/protocol/upgrades/upgrade_procedure.md @@ -27,7 +27,7 @@ When a consensus-breaking change is made to the protocol, we must carefully eval 2. **Implementation**: The proposed changes are implemented in the codebase. 3. **Testing**: Thorough testing of the proposed changes is conducted in devnet and testnet environments before mainnet deployment. 4. **Announcement**: Upon successful testing, we announce the upgrade through our social media channels and community forums. -5. **Deployment**: An upgrade transaction is sent to the network, allowing node operators using [Cosmovisor](../../operate/run_a_node/full_node_cosmovisor.md) to automatically upgrade their nodes at the specified block height. +5. **Deployment**: An upgrade transaction is sent to the network, allowing node operators using [Cosmovisor](../../operate/run_a_node/full_node_walkthrough.md) to automatically upgrade their nodes at the specified block height. 6. **Monitoring**: Post-deployment, we closely monitor the network to ensure everything functions as expected. ## When is an Upgrade Warranted? @@ -112,7 +112,7 @@ We use Kubernetes to manage software versions, including validators. Introducing ### TestNet -We currently deploy TestNet validators using Kubernetes with helm charts, which prevents us from managing the validator with `cosmovisor`. We do not control what other TestNet participants are running. However, if participants have deployed their nodes using the [cosmovisor guide](../../operate/run_a_node/full_node_cosmovisor.md), their nodes will upgrade automatically. +We currently deploy TestNet validators using Kubernetes with helm charts, which prevents us from managing the validator with `cosmovisor`. We do not control what other TestNet participants are running. However, if participants have deployed their nodes using the [cosmovisor guide](../../operate/run_a_node/full_node_walkthrough.md), their nodes will upgrade automatically. Until we transition to [cosmos-operator](https://github.com/strangelove-ventures/cosmos-operator), which supports scheduled upgrades (although not fully automatic like `cosmovisor`), we need to manually manage the process: diff --git a/tools/installer/full-node.sh b/tools/installer/full-node.sh index 0804bc278..1274933de 100644 --- a/tools/installer/full-node.sh +++ b/tools/installer/full-node.sh @@ -8,6 +8,9 @@ GREEN='\033[0;32m' YELLOW='\033[1;33m' NC='\033[0m' # No Color +# DEV_NOTE: For testing purposes, you can change the branch name before merging to master. +POCKET_NETWORK_GENESIS_BRANCH="master" + # Function to print colored output print_color() { COLOR=$1 @@ -23,19 +26,72 @@ check_root() { fi } +# Function to install jq if not installed +install_jq() { + if ! command -v jq &> /dev/null; then + print_color $YELLOW "Installing jq..." + if [ -f /etc/debian_version ]; then + apt-get update + apt-get install -y jq + elif [ -f /etc/redhat-release ]; then + yum update -y + yum install -y jq + else + print_color $RED "Unsupported distribution. Please install jq manually." + exit 1 + fi + print_color $GREEN "jq installed successfully." + else + print_color $YELLOW "jq is already installed." + fi +} + # Function to get user input get_user_input() { + # Ask user which network to install + echo "Which network would you like to install?" + echo "1) testnet-alpha" + echo "2) testnet-beta" + echo "3) mainnet" + read -p "Enter your choice (1-3): " network_choice + + case $network_choice in + 1) NETWORK="testnet-alpha" ;; + 2) NETWORK="testnet-beta" ;; + 3) NETWORK="mainnet" ;; + *) print_color $RED "Invalid network choice. Exiting."; exit 1 ;; + esac + + print_color $GREEN "Installing the $NETWORK network." + read -p "Enter the desired username to run poktrolld (default: poktroll): " POKTROLL_USER POKTROLL_USER=${POKTROLL_USER:-poktroll} read -p "Enter the node moniker (default: $(hostname)): " NODE_MONIKER NODE_MONIKER=${NODE_MONIKER:-$(hostname)} - read -p "Enter the chain-id (default: poktroll): " CHAIN_ID - CHAIN_ID=${CHAIN_ID:-"poktroll"} + # Update URLs to use the branch constant + BASE_URL="https://raw.githubusercontent.com/pokt-network/pocket-network-genesis/${POCKET_NETWORK_GENESIS_BRANCH}/shannon/$NETWORK" + SEEDS_URL="$BASE_URL/seeds" + GENESIS_URL="$BASE_URL/genesis.json" + + # Download genesis.json and store it + GENESIS_FILE="/tmp/genesis.json" + curl -s -o "$GENESIS_FILE" "$GENESIS_URL" + if [ $? -ne 0 ]; then + print_color $RED "Failed to download genesis file. Please check your internet connection and try again." + exit 1 + fi + + # Extract chain_id from genesis.json + CHAIN_ID=$(jq -r '.chain_id' < "$GENESIS_FILE") + if [ -z "$CHAIN_ID" ]; then + print_color $RED "Failed to extract chain_id from genesis file." + exit 1 + fi + print_color $GREEN "Using chain_id: $CHAIN_ID from genesis file" # Fetch seeds from the provided URL - SEEDS_URL="https://raw.githubusercontent.com/pokt-network/pocket-network-genesis/master/shannon/alpha/testnet-validated.seeds" SEEDS=$(curl -s "$SEEDS_URL") if [ -z "$SEEDS" ]; then print_color $RED "Failed to fetch seeds from $SEEDS_URL. Please check your internet connection and try again." @@ -125,6 +181,7 @@ EOF print_color $GREEN "Cosmovisor set up successfully." } + # Function to download and set up Poktrolld setup_poktrolld() { print_color $YELLOW "Setting up Poktrolld..." @@ -138,20 +195,38 @@ setup_poktrolld() { exit 1 fi - # Get the version genesis started from. We can't just use `latest` as the new binary won't sync from genesis. - # We need to start syncing from scratch using the version that was used when the network started. - POKTROLLD_VERSION=$(curl -s https://raw.githubusercontent.com/pokt-network/pocket-network-genesis/master/shannon/alpha/testnet-validated.init-version) + # Extract the version from genesis.json using jq + POKTROLLD_VERSION=$(jq -r '.app_version' < "$GENESIS_FILE") + print_color $YELLOW "Detected version from genesis: $POKTROLLD_VERSION" + + if [ -z "$POKTROLLD_VERSION" ]; then + print_color $RED "Failed to extract version information from genesis file." + exit 1 + fi - # Use the direct download link for the correct release - RELEASE_URL="https://github.com/pokt-network/poktroll/releases/download/${POKTROLLD_VERSION}/poktroll_linux_${ARCH}.tar.gz" + # Construct the release URL with proper version format + RELEASE_URL="https://github.com/pokt-network/poktroll/releases/download/v${POKTROLLD_VERSION}/poktroll_linux_${ARCH}.tar.gz" + print_color $YELLOW "Attempting to download from: $RELEASE_URL" + # Download and extract directly as the POKTROLL_USER sudo -u "$POKTROLL_USER" bash << EOF mkdir -p \$HOME/.poktroll/cosmovisor/genesis/bin + mkdir -p \$HOME/.local/bin curl -L "$RELEASE_URL" | tar -zxvf - -C \$HOME/.poktroll/cosmovisor/genesis/bin + if [ \$? -ne 0 ]; then + echo "Failed to download or extract binary" + exit 1 + fi chmod +x \$HOME/.poktroll/cosmovisor/genesis/bin/poktrolld - ln -sf \$HOME/.poktroll/cosmovisor/genesis/bin/poktrolld \$HOME/bin/poktrolld + ln -sf \$HOME/.poktroll/cosmovisor/genesis/bin/poktrolld \$HOME/.local/bin/poktrolld source \$HOME/.profile EOF + + if [ $? -ne 0 ]; then + print_color $RED "Failed to set up Poktrolld" + exit 1 + fi + print_color $GREEN "Poktrolld set up successfully." } @@ -159,16 +234,24 @@ EOF configure_poktrolld() { print_color $YELLOW "Configuring Poktrolld..." - # Ask for confirmation to download the genesis file - GENESIS_URL="https://raw.githubusercontent.com/pokt-network/pocket-network-genesis/master/shannon/alpha/testnet-validated.json" - print_color $YELLOW "The script will download the genesis file from:" + # Ask for confirmation to use the downloaded genesis file + print_color $YELLOW "The script has downloaded the genesis file from:" print_color $YELLOW "$GENESIS_URL" - read -p "Are you OK with downloading and using this genesis file? (y/N): " confirm_genesis + read -p "Are you OK with using this genesis file? (y/N): " confirm_genesis if [[ ! $confirm_genesis =~ ^[Yy] ]]; then - print_color $RED "Genesis file download cancelled. Exiting." + print_color $RED "Genesis file usage cancelled. Exiting." exit 1 fi + # Detect external IP address + EXTERNAL_IP=$(curl -s https://api.ipify.org) + print_color $YELLOW "Detected external IP address: $EXTERNAL_IP" + read -p "Is this your correct external IP address? (Y/n): " confirm_ip + if [[ $confirm_ip =~ ^[Nn] ]]; then + read -p "Please enter your external IP address: " custom_ip + EXTERNAL_IP=${custom_ip:-$EXTERNAL_IP} + fi + sudo -u "$POKTROLL_USER" bash << EOF source \$HOME/.profile @@ -177,12 +260,9 @@ configure_poktrolld() { echo "Poktrolld version: \$POKTROLLD_VERSION" poktrolld init "$NODE_MONIKER" --chain-id="$CHAIN_ID" --home=\$HOME/.poktroll - curl -o \$HOME/.poktroll/config/genesis.json $GENESIS_URL - if [ \$? -ne 0 ]; then - echo "Failed to download genesis file. Please check your internet connection and try again." - exit 1 - fi + cp "$GENESIS_FILE" \$HOME/.poktroll/config/genesis.json sed -i -e "s|^seeds *=.*|seeds = \"$SEEDS\"|" \$HOME/.poktroll/config/config.toml + sed -i -e "s|^external_address *=.*|external_address = \"$EXTERNAL_IP:26656\"|" \$HOME/.poktroll/config/config.toml EOF if [ $? -eq 0 ]; then print_color $GREEN "Poktrolld configured successfully." @@ -223,10 +303,36 @@ EOF print_color $GREEN "Systemd service set up and started successfully." } +# Function to check if ufw is installed and open port 26656. We need to open the port to keep the network healthy. +# By default, at least on Debian vultr, this port is not open to the internet. +configure_ufw() { + if command -v ufw &> /dev/null; then + print_color $YELLOW "ufw is installed." + + # Check if rule already exists + if ufw status | grep -q "26656"; then + print_color $YELLOW "Port 26656 is already allowed in ufw rules." + return + fi + + read -p "Do you want to open port 26656 for p2p communication? (Y/n): " open_port + if [[ $open_port =~ ^[Yy] ]]; then + ufw allow 26656 + print_color $GREEN "Port 26656 opened successfully." + print_color $YELLOW "To remove this rule later, run: sudo ufw delete allow 26656" + else + print_color $YELLOW "No firewall rules modified." + fi + else + print_color $YELLOW "ufw is not installed. Skipping firewall configuration." + fi +} + # Main function main() { print_color $GREEN "Welcome to the Poktroll Full Node Install Script!" check_root + install_jq get_user_input create_user install_dependencies @@ -235,7 +341,8 @@ main() { setup_poktrolld configure_poktrolld setup_systemd - print_color $GREEN "Poktroll Full Node installation completed successfully!" + configure_ufw + print_color $GREEN "Poktroll Full Node installation for $NETWORK completed successfully!" print_color $YELLOW "You can check the status of your node with: sudo systemctl status cosmovisor.service" print_color $YELLOW "View logs with: sudo journalctl -u cosmovisor.service -f" }