diff --git a/.gitignore b/.gitignore index 2b6011cfb..9fa71d3d6 100644 --- a/.gitignore +++ b/.gitignore @@ -91,5 +91,7 @@ summary.html # Quickstart helpers shannon_appgate_config.yaml shannon_app_config.yaml +shannon_relayminer_config.yaml +shannon_supplier_config.yaml -gentx-*.json \ No newline at end of file +gentx-*.json diff --git a/config.yml b/config.yml index 7a129a20f..3e505eef5 100644 --- a/config.yml +++ b/config.yml @@ -88,6 +88,10 @@ genesis: staking: params: bond_denom: upokt + # TODO_BLOCKER(@Olshansk): Figure out what this should be on Shannon + # re-genesis. We're setting it to 1 for Alpha TestNet #1 so Grove + # maintains the only validator until Alpha TestNet #2. + max_validators: 1 crisis: constant_fee: amount: "10000" diff --git a/docusaurus/docs/develop/developer_guide/code_review_guidelines.md b/docusaurus/docs/develop/developer_guide/code_review_guidelines.md index 88a2baa40..e9270240c 100644 --- a/docusaurus/docs/develop/developer_guide/code_review_guidelines.md +++ b/docusaurus/docs/develop/developer_guide/code_review_guidelines.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 title: Code Review Guidelines --- diff --git a/docusaurus/docs/develop/developer_guide/dev_tips.md b/docusaurus/docs/develop/developer_guide/debug_tips.md similarity index 83% rename from docusaurus/docs/develop/developer_guide/dev_tips.md rename to docusaurus/docs/develop/developer_guide/debug_tips.md index d973c9f6f..3ebdbe5d1 100644 --- a/docusaurus/docs/develop/developer_guide/dev_tips.md +++ b/docusaurus/docs/develop/developer_guide/debug_tips.md @@ -1,9 +1,9 @@ --- -sidebar_position: 3 -title: Developer Tips +sidebar_position: 2 +title: Debugging Tips --- -# Developer Tips +# Debugging Tips :::note This is a living document and will be updated as the ecosystem matures & grows. @@ -14,6 +14,8 @@ If you have a tip you'd like to share with others, please open a PR to add it he - [`itest` - Investigating Flaky Tests](#itest---investigating-flaky-tests) - [`itest` Usage](#itest-usage) - [`itest` Example](#itest-example) + - [TODO: pprof](#todo-pprof) + - [TODO: dlv](#todo-dlv) ## `itest` - Investigating Flaky Tests @@ -36,3 +38,7 @@ test in the `pkg/client/tx` 50 times in total (5 consecutive tests over 10 runs) ```bash make itest 5 10 ./pkg/client/tx/... -- -run TxClient_SignAndBroadcast_Succeeds ``` + +### TODO: pprof + +### TODO: dlv diff --git a/docusaurus/docs/develop/developer_guide/img/quickstart_accounts.png b/docusaurus/docs/develop/developer_guide/img/quickstart_accounts.png index 92c1a9553..f7b167cb4 100644 Binary files a/docusaurus/docs/develop/developer_guide/img/quickstart_accounts.png and b/docusaurus/docs/develop/developer_guide/img/quickstart_accounts.png differ diff --git a/docusaurus/docs/develop/developer_guide/img/quickstart_applist.png b/docusaurus/docs/develop/developer_guide/img/quickstart_applist.png index 199b1a7e7..4b371e6f5 100644 Binary files a/docusaurus/docs/develop/developer_guide/img/quickstart_applist.png and b/docusaurus/docs/develop/developer_guide/img/quickstart_applist.png differ diff --git a/docusaurus/docs/develop/developer_guide/img/quickstart_full_relay.png b/docusaurus/docs/develop/developer_guide/img/quickstart_full_relay.png new file mode 100644 index 000000000..adb5bf494 Binary files /dev/null and b/docusaurus/docs/develop/developer_guide/img/quickstart_full_relay.png differ diff --git a/docusaurus/docs/develop/developer_guide/img/quickstart_grafana_supplier.png b/docusaurus/docs/develop/developer_guide/img/quickstart_grafana_supplier.png new file mode 100644 index 000000000..5c24c5701 Binary files /dev/null and b/docusaurus/docs/develop/developer_guide/img/quickstart_grafana_supplier.png differ diff --git a/docusaurus/docs/develop/developer_guide/img/quickstart_localnet.png b/docusaurus/docs/develop/developer_guide/img/quickstart_localnet.png index cf5eaf5a6..8186d3860 100644 Binary files a/docusaurus/docs/develop/developer_guide/img/quickstart_localnet.png and b/docusaurus/docs/develop/developer_guide/img/quickstart_localnet.png differ diff --git a/docusaurus/docs/develop/developer_guide/img/quickstart_relayminer.png b/docusaurus/docs/develop/developer_guide/img/quickstart_relayminer.png new file mode 100644 index 000000000..01234a82d Binary files /dev/null and b/docusaurus/docs/develop/developer_guide/img/quickstart_relayminer.png differ diff --git a/docusaurus/docs/develop/developer_guide/img/quickstart_relayminer_grafana.png b/docusaurus/docs/develop/developer_guide/img/quickstart_relayminer_grafana.png new file mode 100644 index 000000000..a2c3a523e Binary files /dev/null and b/docusaurus/docs/develop/developer_guide/img/quickstart_relayminer_grafana.png differ diff --git a/docusaurus/docs/develop/developer_guide/img/quickstart_suppliers.png b/docusaurus/docs/develop/developer_guide/img/quickstart_suppliers.png new file mode 100644 index 000000000..b90430843 Binary files /dev/null and b/docusaurus/docs/develop/developer_guide/img/quickstart_suppliers.png differ diff --git a/docusaurus/docs/develop/developer_guide/img/quickstart_tilt_supplier.png b/docusaurus/docs/develop/developer_guide/img/quickstart_tilt_supplier.png new file mode 100644 index 000000000..6ee716944 Binary files /dev/null and b/docusaurus/docs/develop/developer_guide/img/quickstart_tilt_supplier.png differ diff --git a/docusaurus/docs/develop/developer_guide/quickstart.md b/docusaurus/docs/develop/developer_guide/quickstart.md index 1fc36e612..70895e7fc 100644 --- a/docusaurus/docs/develop/developer_guide/quickstart.md +++ b/docusaurus/docs/develop/developer_guide/quickstart.md @@ -5,37 +5,60 @@ title: Quickstart # Quickstart -- [Install Dependencies](#install-dependencies) -- [Launch LocalNet](#launch-localnet) - - [Clone the repository](#clone-the-repository) - - [Prepare your environment](#prepare-your-environment) - - [Create a k8s cluster](#create-a-k8s-cluster) - - [Start up LocalNet](#start-up-localnet) -- [Interact with the chain](#interact-with-the-chain) - - [Create a new Account](#create-a-new-account) - - [Fund your account](#fund-your-account) - - [Stake Shannon as an Application](#stake-shannon-as-an-application) - - [Send a relay](#send-a-relay) - - [Send a relay a shannon](#send-a-relay-a-shannon) -- [Explore the tools](#explore-the-tools) +:::info +The goal of this document is to get you up and running with a LocalNet, some +manually deployed local actors, and sending an end-to-end relay. It will not +go in depth into any concepts. + +Create a new [GitHub issue here](https://github.com/pokt-network/pocket/issues/new/choose) +**if you encounter any problems.** +::: + +- [0. Install Dependencies](#0-install-dependencies) +- [1. Launch \& Inspect LocalNet](#1-launch--inspect-localnet) + - [1.1 Clone the `poktroll` repository](#11-clone-the-poktroll-repository) + - [1.2 See all the available helper commands in `Makefile`](#12-see-all-the-available-helper-commands-in-makefile) + - [1.3 Prepare your development environment](#13-prepare-your-development-environment) + - [1.4 Create a `k8s` cluster](#14-create-a-k8s-cluster) + - [1.5 Start up LocalNet](#15-start-up-localnet) + - [1.6 View Grafana Logs](#16-view-grafana-logs) + - [1.7 Check the status of the blockchain](#17-check-the-status-of-the-blockchain) +- [2. Fund New Accounts](#2-fund-new-accounts) + - [2.1 Create a Shannon `Supplier` Account](#21-create-a-shannon-supplier-account) + - [2.2 Create a Shannon `Application` Account](#22-create-a-shannon-application-account) + - [2.3 Fund your `Supplier` Account](#23-fund-your-supplier-account) + - [2.4 Fund your Application Account](#24-fund-your-application-account) +- [3. Manually Stake a Supplier \& Deploy a RelayMiner](#3-manually-stake-a-supplier--deploy-a-relayminer) + - [3.1 View existing suppliers](#31-view-existing-suppliers) + - [3.2 Preparing your backend data node](#32-preparing-your-backend-data-node) + - [3.3 Create a Supplier configuration](#33-create-a-supplier-configuration) + - [3.4 Stake the new Supplier](#34-stake-the-new-supplier) + - [3.4 Prepare the RelayMiner configuration](#34-prepare-the-relayminer-configuration) + - [3.5 Start the RelayMiner locally](#35-start-the-relayminer-locally) +- [4. Manually Stake an Application \& Deploy an AppGate Server](#4-manually-stake-an-application--deploy-an-appgate-server) + - [4.1 View Existing Application](#41-view-existing-application) + - [4.2 Create an Application configuration](#42-create-an-application-configuration) + - [4.3 Stake the new Application](#43-stake-the-new-application) + - [4.4 Prepare the AppGate Server configuration](#44-prepare-the-appgate-server-configuration) + - [4.5 Start the AppGate Server locally](#45-start-the-appgate-server-locally) +- [5. Send A Relay](#5-send-a-relay) + - [5.1 Send a relay on Shannon](#51-send-a-relay-on-shannon) + - [5.2 What just happened?](#52-what-just-happened) + - [5.3 What will happen later](#53-what-will-happen-later) + - [5.4 Staking a few more Suppliers without RelayMiners](#54-staking-a-few-more-suppliers-without-relayminers) + - [5.5. Inspect the logs](#55-inspect-the-logs) +- [6. Dynamically Scaling LocalNet](#6-dynamically-scaling-localnet) +- [7. Explore the tools](#7-explore-the-tools) - [E2E Tests](#e2e-tests) - [poktrolld](#poktrolld) - [Makefile](#makefile) - [Ignite](#ignite) -:::tip -The goal of this document is to get you up and running with a LocalNet and -end-to-end relay. - -**If you encounter any problems**, the best way to get support -from the team is by creating a new [GitHub Issue here](https://github.com/pokt-network/pocket/issues/new/choose). -::: - -## Install Dependencies +## 0. Install Dependencies Install the following dependencies: -1. [Golang](https://go.dev/doc/install) - The language we use to implement the protocol +1. [Golang](https://go.dev/doc/install) - The programming language we use to implement the protocol 2. [Docker](https://docs.docker.com/get-docker/) - Containerization tool 3. [Ignite](https://docs.ignite.com/welcome/install) - Cosmos SDK CLI for building and deploying blockchains 4. [Kind](https://kind.sigs.k8s.io/#installation-and-usage) - k8s local cluster manager @@ -43,109 +66,208 @@ Install the following dependencies: 6. [Tilt](https://docs.tilt.dev/install.html) - k8s local development tool & environment manager :::note -You might already have these installed if you've followed the [localnet instructions](../internal_infrastructure/localnet.md). +If you've followed the [LocalNet instructions](../internal_infrastructure/localnet.md), +you may already have them installed. ::: -## Launch LocalNet +## 1. Launch & Inspect LocalNet -This section will help you deploy a Pocket LocalNet in a k8s cluster on your machine. +This section will help you deploy a POKT LocalNet in a k8s cluster on your machine +and inspect it so you have an idea of what's going on! -### Clone the repository +We'll be manually configuring a few actors to run in your shell for the sake of +the tutorial so you have visibility into the types of on-chain and off-chain +actors. In practice, you should be using [localnet](./../internal_infrastructure/localnet.md) +to dynamically scale your actors. + +To learn more about the different actors type, see the docs [here](../../protocol/actors/actors.md). + +It should look something like this once you're past the first section: + +![Tilt LocalNet View](./img/quickstart_localnet.png) + +### 1.1 Clone the `poktroll` repository ```bash git clone https://github.com/pokt-network/poktroll.git cd poktroll ``` -### Prepare your environment +### 1.2 See all the available helper commands in `Makefile` -Generate mocks, compile the protobufs and verify that all the tests are passing by running: +We leverage the `Makefile` to abstract the complexity of some common commands, +but you can [view it directly](https://github.com/pokt-network/poktroll/blob/main/Makefile) +to see what the underlying command being executed is. + +:::tip `make help` + +If you run `make help` from the root of the repo, you'll see a list of all the +available commands. Looking inside the Makefile is a great way to learn how to use them! + +::: + +### 1.3 Prepare your development environment + +Compile protobufs, generate mocks and verify that all tests are passing by running: ```bash make go_develop_and_test ``` -### Create a k8s cluster +There are some flaky tests, so you can re-run with the following command without +needing to regenerate the mocks and types: + +```bash +make go_test +``` + +### 1.4 Create a `k8s` cluster + +Create a new `k8s` cluster for your LocalNet: ```bash kind create cluster ``` -### Start up LocalNet +If you use `k8s` for other things, you may need to switch your context as well: + +```bash +kubectl config use-context kind-kind +``` + +### 1.5 Start up LocalNet + +Bring up your LocalNet and wait a few minutes: ```bash make localnet_up ``` -Visit [localhost:10350](http://localhost:10350) and wait until all the containers are 🟢. +Visit [localhost:10350]() and wait until all the containers are 🟢 If everything worked as expected, your screen should look similar to the following: -![LocalNet](./img/quickstart_localnet.png) +### 1.6 View Grafana Logs -## Interact with the chain +Every actor has a local grafana dashboard associated with it. -This section is an opinionated walkthrough of a small number of interactions you -can have with the network so you get a feel of how to interact with the chain. +For example, if you visit the [RelayMiner Tilt UI](http://localhost:10350/r/relayminer1/overview), +you can click in the top left corner to view its [grafana dashboard](http://localhost:3003/d/relayminer/protocol-relayminer?orgId=1&var-relayminer=relayminer1&refresh=5s). -### Create a new Account +![Tilt RelayMiner](./img/quickstart_relayminer.png) + +![Grafana RelayMiner](./img/quickstart_relayminer_grafana.png) + +### 1.7 Check the status of the blockchain + +You can query the status of the blockchain using `poktrolld` by running: + +```bash +poktrolld status --node=tcp://127.0.0.1:36657 | jq +``` + +Alternatively, you use the [CometBFT](https://github.com/cometbft/cometbft) status directly at: + +```bash +curl -s -X POST localhost:36657/status | jq +``` + +Or at latest block at: + +```bash +curl -s -X POST localhost:36657/block | jq +``` + +For example, you can get the height of the blockchain by visiting the +[Validator Grafana Dashboard](http://localhost:3003/d/cosmoscometbft/protocol-cometbft-dashboard?orgId=1&from=now-1h&to=now) +or from the CLI like so: + +```bash +curl -s -X POST localhost:36657/block | jq '.result.block.last_commit.height' +``` + +## 2. Fund New Accounts + +This section will help you fund a few accounts that we'll use below. We're going +to create a `shannon_supplier` and `shannon_application`, but a dedicated gateway +is outside the scope of this guide. + +### 2.1 Create a Shannon `Supplier` Account List all the accounts we get out of the box by running: ```bash -ignite account list \ - --keyring-dir=./localnet/poktrolld \ - --keyring-backend test --address-prefix pokt +make ignite_acc_list ``` -And create a new account named `shannon` by running: +And create a new account named `shannon_supplier` by running: ```bash -ignite account create shannon \ +ignite account create shannon_supplier \ --keyring-dir=./localnet/poktrolld \ --keyring-backend test ``` -If you re-run the command above, it should show up in the list. +If you re-run `make ignite_acc_list`, you should now see `shannon_supplier` in the list. + Make sure to note its address under the `Address` column and export it as an environment variable for convenience. For example: ```bash -export SHANNON_ADDRESS=pokt1skun4qy6z0cvac4fc37kcqcjsyr3qe9thhlzkv +export SHANNON_SUPPLIER=pokt1rgaqf6kz655qktrjenqy6zjx97zgr8ghx8q7xu ``` ![Accounts](./img/quickstart_accounts.png) -### Fund your account +### 2.2 Create a Shannon `Application` Account -Query your account's balance by running: +Let's do the same thing for a `shannon_application`: ```bash -poktrolld --home=./localnet/poktrolld \ - q bank balances $SHANNON_ADDRESS \ - --node tcp://127.0.0.1:36657 +ignite account create shannon_application \ + --keyring-dir=./localnet/poktrolld \ + --keyring-backend test +``` + +```bash +export SHANNON_APPLICATION=pokt1s6cupe8uj4lwdn6dt5azjv9vm4x3mtt8aek0g2 +``` + +### 2.3 Fund your `Supplier` Account + +Query your supplier's balance by running: + +```bash +make acc_balance_query ACC=$SHANNON_SUPPLIER ``` And you should see an empty balance: -```yaml +```bash +~ Balances ~ balances: [] -pagination: - next_key: null - total: "0" +pagination: {} + +~ Spendable Balances ~ +Querying spendable balance for pokt1h04g6njyuv03dhd74a73pyzeadmd8dk7l9tsk8 +balances: [] +pagination: {} ``` -But if you look in our genesis file (found at `localnet/poktrolld/config/genesis.json`) -you'll find that our validator has a lot of POKT, so we can use some of that. +But if you look in our genesis file (`./localnet/poktrolld/config/genesis.json`) +you'll find that you actually have direct access to the `faucet`! + +You can send some uPOKT to your `shannon_supplier` by running: ```bash -poktrolld --home=./localnet/poktrolld \ +poktrolld \ tx bank send \ - validator1 $SHANNON_ADDRESS 420000000000069upokt \ - --node tcp://127.0.0.1:36657 + faucet $SHANNON_SUPPLIER 420000000000069upokt \ + --node tcp://127.0.0.1:36657 \ + --home=./localnet/poktrolld ``` -And you'll find that Shannon is now rolling in POKT: +And you'll find that `shannon_supplier` is now rolling in `POKT`: ```yaml balances: @@ -156,55 +278,272 @@ pagination: total: "0" ``` -### Stake Shannon as an Application +### 2.4 Fund your Application Account + +Let's do the same thing for the `shannon_application`: + +```bash +poktrolld \ + tx bank send \ + faucet $SHANNON_APPLICATION 420000000000069upokt \ + --node tcp://127.0.0.1:36657 \ + --home=./localnet/poktrolld +``` + +And make sure to check its balance again: + +```bash +make acc_balance_query ACC=$SHANNON_APPLICATION +``` + +## 3. Manually Stake a Supplier & Deploy a RelayMiner + +As we mentioned earlier, if you want to understand the different on-chain actors +and off-chain operators in POKT Network, look at the docs [here](../../protocol/actors/actors.md). + +If you just want to follow instructions to make things work and get your hands +dirty, keep reading. + +### 3.1 View existing suppliers + +You can run the following command to see all the suppliers available in the network: + +```bash +make supplier_list +``` + +You'll find that we have a default supplier, but `SHANNON_SUPPLIER` won't be there yet. + +### 3.2 Preparing your backend data node + +We need a blockchain node (i.e. a backend data node) backend data node to +configure a supplier. Since LocalNet is already has a running [`anvil`](http://localhost:10350/r/anvil/overview) service, we can re-use that as our backend. + +[anvil](https://book.getfoundry.sh/anvil/) is a local Ethereum development node +that's equivalent to "running your own ETH node". It's a great way to test. + +You can verify the `anvil` node is running with the following curl: + +```bash +curl http://localhost:8547 \ + -X POST \ + -H "Content-Type: application/json" \ + --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}' +``` + +```json +{ "jsonrpc": "2.0", "id": 1, "result": "0x61" } +``` + +:::tip Grove's Prod Endpoints + +If you'd prefer to use a real blockchain node with production data for testing, +you can provision one at [grove.city](https://www.grove.city) and use it below. + +::: + +### 3.3 Create a Supplier configuration + +You can learn more about our [supplier configs here](../../operate/configs/supplier_staking_config.md). + +The following is an example config to get you started: + +```bash +cat <> shannon_supplier_config.yaml +stake_amount: 1000069upokt +services: + - service_id: anvil + endpoints: + - publicly_exposed_url: http://localhost:6942 + rpc_type: JSON_RPC +EOF +``` + +### 3.4 Stake the new Supplier + +Stake the `shannon_supplier` on-chain: -Run `make app_list` (a helper our team created) to see all the apps staked on the -network. There will be a default application, but `SHANNON_ADDRESS` won't be there. +```bash +poktrolld \ + tx supplier stake-supplier \ + --config shannon_supplier_config.yaml \ + --keyring-backend test \ + --from shannon_supplier \ + --node tcp://127.0.0.1:36657 \ + --home=./localnet/poktrolld \ + --yes +``` -In order to stake shannon as an app, we need to create a new config file and run -the stake command. +And verify that the supplier is now staked with: + +```bash +poktrolld query supplier show-supplier $SHANNON_SUPPLIER --node tcp://127.0.0.1:36657 +``` + +### 3.4 Prepare the RelayMiner configuration + +Next, we need to prepare a RelayMiner to operate on behalf of the Supplier. + +You can learn more about our [relay miner configs here](../../operate/configs/relayminer_config.md). + +The following is an example config to get you started: + +```bash +cat <> shannon_relayminer_config.yaml +signing_key_name: shannon_supplier +smt_store_path: smt_stores +metrics: + enabled: true + addr: :9090 +pocket_node: + query_node_rpc_url: tcp://127.0.0.1:36657 + query_node_grpc_url: tcp://127.0.0.1:36658 + tx_node_rpc_url: tcp://127.0.0.1:36657 +suppliers: + - service_id: anvil + listen_url: http://localhost:6942 + service_config: + backend_url: http://localhost:8081 + publicly_exposed_endpoints: + - localhost +pprof: + enabled: false + addr: localhost:6060 +EOF +``` + +### 3.5 Start the RelayMiner locally + +Start the RelayMiner locally: + +```bash +poktrolld relayminer \ + --config ./shannon_relayminer_config.yaml \ + --keyring-backend test \ + --home=./localnet/poktrolld +``` + +Leave it running in its own shell instance and open a new one. We'll be using it +to serve relays in the next section. + +:::tip + +You may need to re-export `SHANNON_APPLICATION` and `SHANNON_SUPPLIER` in the +new shell instance. + +::: + +## 4. Manually Stake an Application & Deploy an AppGate Server + +:::note Independent Gateway + +This section will show how to deploy a Sovereign Application, which acts as its +own Gateway. We are leaving delegated Gateways outside the scope of the +Quickstart guide. + +::: + +### 4.1 View Existing Application + +You can run the following command to see all the application available in the network: + +```bash +make app_list +``` + +### 4.2 Create an Application configuration + +You can learn more about our [application configs here](../../operate/configs/app_staking_config.md). + +The following example should get you started: ```bash cat <> shannon_app_config.yaml +stake_amount: 1000069upokt service_ids: - anvil EOF ``` -:::note -Details on all the available configurations are still in progress and will be linked here once ready. -TODO(@red-0ne): Link to the document for all the config files once ready. -::: - -We already have a supplier pre-configured (try running `make supplier_list`) to -supply services for `anvil` (an local ethereum testing node), so we can simply -reused that for simplicity. +### 4.3 Stake the new Application -Next, run the stake command: +Stake the application on-chain: ```bash poktrolld --home=./localnet/poktrolld \ - tx application stake-application 1000upokt \ + tx application stake-application \ --config shannon_app_config.yaml \ - --keyring-backend test --from shannon --node tcp://127.0.0.1:36657 + --keyring-backend test \ + --from shannon_application \ + --node tcp://127.0.0.1:36657 \ + --yes ``` -If you re-run, `make app_list` you should see that `SHANNON_ADDRESS` is now staked as an app. +And verify that the application is now staked with: + +```bash +poktrolld query application show-application $SHANNON_APPLICATION --node tcp://127.0.0.1:36657 +``` + +You can also you re-run, `make app_list` you should see that `SHANNON_APPLICATION` is now staked as an app: ![Apps](./img/quickstart_applist.png) -### Send a relay +### 4.4 Prepare the AppGate Server configuration + +You can learn more about our [appgate server configs here](../../operate/configs/appgate_server_config.md). + +The following example should get you started: + +```yaml +cat <> shannon_appgate_config.yaml +query_node_rpc_url: tcp://127.0.0.1:36657 +query_node_grpc_url: tcp://127.0.0.1:36658 +self_signing: true +signing_key: shannon_application +listening_endpoint: http://localhost:42042 +metrics: + enabled: true + addr: :9091 +EOF +``` + +### 4.5 Start the AppGate Server locally :::warning +You might need to add the following to your `/etc/hosts` file: +127.0.0.1 anvil +127.0.0.1 relayminers +::: + +And the start the appgate server locally: + +```bash +poktrolld appgate-server \ + --config shannon_appgate_config.yaml \ + --keyring-backend test \ + --node tcp://127.0.0.1:36657 \ + --home=./localnet/poktrolld +``` + +## 5. Send A Relay + +Now that we've staked an `Application`, are running an `AppGate Server`, staked +a `Supplier`, and are running a `RelayMiner`, we can send a relay! + +:::note Initialize Public Keys + You must run `make acc_initialize_pubkeys` before sending a relay in order for the public keys to be initialized correctly. + +See the [x/auth](https://docs.cosmos.network/main/build/modules/auth) for more +information on how public keys are stored and accessible on-chain. + ::: -If you look in `localnet/poktrolld/config/appgate_server_config.yaml`, you'll find -the configurations for an appgate server that is listening on port `42069`. +### 5.1 Send a relay on Shannon -You can send a relay to the `anvil` service (i.e. locally running -ethereum node) like so: +You can use `curl` ```bash curl -X POST -H "Content-Type: application/json" \ @@ -218,36 +557,66 @@ If everything worked as expected, you should see output similar to the following {"jsonrpc":"2.0","id":1,"result":"0x61"}% ``` -### Send a relay a shannon +![quickstart_full_relay](./img/quickstart_full_relay.png) -However, the appgate server above is not configured to sign relays on behalf of `SHANNON_ADDRESS`. +### 5.2 What just happened? -To do so, you'll need to create a similar configuration like so: +The Relay Request/Response from is captured in the sequence diagram below. -```yaml -cat <> shannon_appgate_config.yaml -self_signing: true -signing_key: shannon -listening_endpoint: http://localhost:42042 -query_node_url: tcp://127.0.0.1:36657 -EOF +```mermaid +sequenceDiagram + actor U as User
(curl Client) + + participant AG as AppGate Server
(off-chain Application Operator) + participant RM as RelayMiner
(off-chain Supplier Operator) + participant anvil as ETH Node
(Anvil) + + U ->> +AG: eth_blockNumber
(JSON-RPC Request) + AG ->> +RM: POKT Relay Request + RM ->> +anvil: eth_blockNumber + anvil ->> -RM: eth_result + RM ->> -AG: POKT Relay Response + AG ->> -U: eth_result
(JSON-RPC Response) ``` -And the start the appgate server locally: +### 5.3 What will happen later + +Please see our protocol docs [here](../../protocol/primitives/claim_and_proof_lifecycle) +for information on how the protocol actually works, but the following will +provide some intuition: + +```mermaid +sequenceDiagram + participant RM as RelayMiner
(Supplier Operator) + participant P as Pocket Node + actor A as Application
(on-chain Record) + actor S as Supplier
(on-chain Record) + + RM -->> P: CreateClaim
(Relays Served) + RM -->> P: SubmitProof
(Proof of Work) + P -->> A: Burn Delegated POKT + P -->> S: Mint New POKT +``` + +### 5.4 Staking a few more Suppliers without RelayMiners + +Even though we are running our own RelayMiner backed by our own Supplier, we +can stake a few more suppliers to diversify where the requests are going to go. + +Try using the following helpers: ```bash -poktrolld --home=./localnet/poktrolld appgate-server \ - --config shannon_appgate_config.yaml --keyring-backend test \ - --node tcp://127.0.0.1:36657 +make supplier2_stake +make supplier3_stake ``` -:::warning -You might need to add the following to your `/etc/hosts` file: -127.0.0.1 anvil -127.0.0.1 relayminers -::: +Running `make supplier_list` should now show that all three suppliers are staked. + +You can reuse the running AppGate Server to send requests, which should round-robin +through all the available suppliers. However, since not all of them have a RelayMiner +running, you'll see that some of requests will fail. -Repeat sending the relay to the new port: +Give it a shot by running the following multiple times: ```bash curl -X POST -H "Content-Type: application/json" \ @@ -255,11 +624,31 @@ curl -X POST -H "Content-Type: application/json" \ http://localhost:42042/anvil ``` -## Explore the tools +### 5.5. Inspect the logs + +As you're ready to dive in, develop or debug, you can view or inspect logs either +through Tilt or Grafana. + +Given that we just staked a few suppliers, you customize the query to look for +`Supplier` either on [Grafana](http://localhost:3003/explore?schemaVersion=1&panes=%7B%22d1l%22:%7B%22datasource%22:%22P8E80F9AEF21F6940%22,%22queries%22:%5B%7B%22refId%22:%22A%22,%22expr%22:%22%7Bcontainer%3D%5C%22poktrolld-validator%5C%22%7D%20%7C%3D%20%60Supplier%60%20%7C%20json%22,%22queryType%22:%22range%22,%22datasource%22:%7B%22type%22:%22loki%22,%22uid%22:%22P8E80F9AEF21F6940%22%7D,%22editorMode%22:%22builder%22%7D%5D,%22range%22:%7B%22from%22:%22now-1h%22,%22to%22:%22now%22%7D%7D%7D&orgId=1) or [Tilt](http://localhost:10350/r/validator/overview?term=Supplier). + +![Grafana Supplier Logs](./img/quickstart_grafana_supplier.png) + +![Tilt Supplier Logs](./img/quickstart_tilt_supplier.png) + +## 6. Dynamically Scaling LocalNet + +We went through a low of steps above just so you can get a feel for how things work. + +That said, you can dynamically scale the number of any actors in LocalNet by ony changing one line! + +Go to our [localnet tutorial](./../internal_infrastructure/localnet.md) to learn more. + +## 7. Explore the tools There are three primary tools you'll use to develop and interact with the network: -1. `poktrolld` - the Pocket Node CLI +1. `poktrolld` - the POKT Node CLI 2. `make` - a collection of helpers to make your life easier 3. `ignite` - a tool to manage the local k8s cluster diff --git a/docusaurus/docs/explore/_category_.json b/docusaurus/docs/explore/_category_.json new file mode 100644 index 000000000..7d5d2e58b --- /dev/null +++ b/docusaurus/docs/explore/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Explore", + "position": 5, + "link": { + "type": "generated-index", + "description": "Poktroll Exploration" + } +} diff --git a/docusaurus/docs/explore/block_explorer.md b/docusaurus/docs/explore/block_explorer.md new file mode 100644 index 000000000..db2e8c2dc --- /dev/null +++ b/docusaurus/docs/explore/block_explorer.md @@ -0,0 +1,8 @@ +--- +title: TestNet Block Explorer +sidebar_position: 4 +--- + +# TestNet Block Explorer + +TODO diff --git a/docusaurus/docs/explore/faucet.md b/docusaurus/docs/explore/faucet.md new file mode 100644 index 000000000..0613c1fd1 --- /dev/null +++ b/docusaurus/docs/explore/faucet.md @@ -0,0 +1,8 @@ +--- +title: TestNet Faucet +sidebar_position: 2 +--- + +# TestNet Faucet + +TODO diff --git a/docusaurus/docs/operate/configs/app_staking_config.md b/docusaurus/docs/operate/configs/app_staking_config.md index 0443b9839..2f2733c99 100644 --- a/docusaurus/docs/operate/configs/app_staking_config.md +++ b/docusaurus/docs/operate/configs/app_staking_config.md @@ -9,11 +9,15 @@ This document describes the configuration file used by the `Application` actor to submit a `stake` transaction, **which is a prerequisite** for it to use the Pocket Network's RPC services. +- [Reference Example](#reference-example) - [Usage](#usage) - [Configuration](#configuration) - [`stake_amount`](#stake_amount) - [`service_ids`](#service_ids) -- [Example](#example) + +## Reference Example + +A full example of the configuration file could be found at [application_staking_config.yaml](https://github.com/pokt-network/poktroll/tree/main/localnet/poktrolld/config/application1_stake_config.yaml) ## Usage @@ -71,7 +75,3 @@ that is available on Pocket network. It MUST be a string of 8 or fewer alphanumeric characters, underscores, and dashes (i.e. matching the regex `^[a-zA-Z0-9_-]{1,8}$`). - -## Example - -A full example of the configuration file could be found at [application_staking_config.yaml](https://github.com/pokt-network/poktroll/tree/main/localnet/poktrolld/config/application1_stake_config.yaml) diff --git a/docusaurus/docs/operate/configs/gateway_staking_config.md b/docusaurus/docs/operate/configs/gateway_staking_config.md index 2c06900aa..b7c0db4cb 100644 --- a/docusaurus/docs/operate/configs/gateway_staking_config.md +++ b/docusaurus/docs/operate/configs/gateway_staking_config.md @@ -9,10 +9,14 @@ This document describes the configuration file used by the `Gateway` actor to submit a stake transaction required to allow it to serve Pocket Network RPC services. +- [Reference Example](#reference-example) - [Usage](#usage) - [Configuration](#configuration) - [`stake_amount`](#stake_amount) -- [Example](#example) + +## Reference Example + +A full example of the configuration file could be found at [gateway_staking_config.yaml](https://github.com/pokt-network/poktroll/tree/main/localnet/poktrolld/config/gateway1_stake_config.yaml) ## Usage @@ -50,7 +54,3 @@ stake_amount: upokt Defines the amount of `upokt` to stake by the `Gateway` to be able to serve `RelayRequest` on the Pocket network on behalf of `Application`s. - -## Example - -A full example of the configuration file could be found at [gateway_staking_config.yaml](https://github.com/pokt-network/poktroll/tree/main/localnet/poktrolld/config/gateway1_stake_config.yaml) diff --git a/docusaurus/docusaurus.config.js b/docusaurus/docusaurus.config.js index 036e69d82..d40df1064 100644 --- a/docusaurus/docusaurus.config.js +++ b/docusaurus/docusaurus.config.js @@ -120,6 +120,12 @@ const config = { sidebarId: "planningSidebar", label: "🗒️ Planning", }, + { + type: "docSidebar", + position: "left", + sidebarId: "exploreSidebar", + label: "🗺 Explore", + }, ], }, footer: { diff --git a/docusaurus/sidebars.js b/docusaurus/sidebars.js index f7748237c..d45333759 100644 --- a/docusaurus/sidebars.js +++ b/docusaurus/sidebars.js @@ -26,6 +26,12 @@ const sidebars = { dirName: "planning", }, ], + exploreSidebar: [ + { + type: "autogenerated", + dirName: "explore", + }, + ], }; export default sidebars; diff --git a/e2e/tests/node.go b/e2e/tests/node.go index 5bf187556..e54fb0395 100644 --- a/e2e/tests/node.go +++ b/e2e/tests/node.go @@ -127,7 +127,6 @@ func (p *pocketdBin) runCurlPostCmd(rpcUrl string, service string, data string, args = append(base, args...) commandStr := "curl " + strings.Join(args, " ") // Create a string representation of the command cmd := exec.Command("curl", args...) - var stdoutBuf, stderrBuf bytes.Buffer cmd.Stdout = &stdoutBuf cmd.Stderr = &stderrBuf diff --git a/localnet/kubernetes/anvil.yaml b/localnet/kubernetes/anvil.yaml index d80f59b9a..9b890ca75 100644 --- a/localnet/kubernetes/anvil.yaml +++ b/localnet/kubernetes/anvil.yaml @@ -16,7 +16,7 @@ spec: # TODO: Add resource limits containers: - name: anvil - image: ghcr.io/foundry-rs/foundry:latest + image: ghcr.io/foundry-rs/foundry:nightly-3fa02706ca732c994715ba42d923605692062375 ports: - containerPort: 8547 command: ["anvil"] diff --git a/localnet/poktrolld/config/relayminer_config.yaml b/localnet/poktrolld/config/relayminer_config.yaml index 031999030..e6d92439c 100644 --- a/localnet/poktrolld/config/relayminer_config.yaml +++ b/localnet/poktrolld/config/relayminer_config.yaml @@ -1,19 +1,19 @@ -signing_key_name: supplier1 +signing_key_name: shannon_supplier smt_store_path: smt_stores metrics: enabled: true addr: :9090 pocket_node: - query_node_rpc_url: tcp://poktroll-validator:36657 - query_node_grpc_url: tcp://poktroll-validator:36658 - tx_node_rpc_url: tcp://poktroll-validator:36657 + query_node_rpc_url: tcp://127.0.0.1:36657 + query_node_grpc_url: tcp://127.0.0.1:36658 + tx_node_rpc_url: tcp://127.0.0.1:36657 suppliers: - service_id: anvil - listen_url: http://0.0.0.0:8545 + listen_url: http://localhost:6942 service_config: - backend_url: http://anvil:8547/ + backend_url: http://localhost:8081 publicly_exposed_endpoints: - - relayminers + - localhost pprof: enabled: false addr: localhost:6060 diff --git a/localnet/poktrolld/config/supplier1_stake_config.yaml b/localnet/poktrolld/config/supplier1_stake_config.yaml index 520e72090..559e43f42 100644 --- a/localnet/poktrolld/config/supplier1_stake_config.yaml +++ b/localnet/poktrolld/config/supplier1_stake_config.yaml @@ -4,7 +4,7 @@ stake_amount: 1000069upokt services: - service_id: svc1 endpoints: - - url: http://localhost:8081 + - publicly_exposed_url: http://localhost:8081 rpc_type: JSON_RPC # The endpoint URL for the Anvil service is provided via the RelayMiner. # The RelayMiner acts as a proxy, forwarding requests to the actual Anvil data node behind it. @@ -15,5 +15,5 @@ services: rpc_type: JSON_RPC - service_id: ollama endpoints: - - publicly_exposed_url: http://relayminer1:8545 + - publicly_exposed_url: http://relayminer2:8545 rpc_type: REST diff --git a/pkg/sdk/interface.go b/pkg/sdk/interface.go index 42e8ebf33..a25b58ce8 100644 --- a/pkg/sdk/interface.go +++ b/pkg/sdk/interface.go @@ -13,6 +13,7 @@ import ( type POKTRollSDK interface { // GetApplications queries a list of all on-chain applications, optionally filtered by // delegated gateway + // TODO(@redone): Replace `options GetApplicationsOptions` with `options ...GetApplicationsOptions` GetApplications(ctx context.Context, options GetApplicationsOptions) ([]apptypes.Application, error) // GetSessionSupplierEndpoints returns the suppliers endpoints of the current session for diff --git a/x/supplier/config/supplier_configs_reader.go b/x/supplier/config/supplier_configs_reader.go index 0ed02b1f4..dc1c2ad97 100644 --- a/x/supplier/config/supplier_configs_reader.go +++ b/x/supplier/config/supplier_configs_reader.go @@ -179,6 +179,10 @@ func parseEndpointRPCType(endpoint YAMLServiceEndpoint) (sharedtypes.RPCType, er switch strings.ToLower(endpoint.RPCType) { case "json_rpc": return sharedtypes.RPCType_JSON_RPC, nil + // TODO(@red-0ne): This hasn't been implemented yet but is part of the + // configurations, which is why we're not returning an error here. + case "rest": + return sharedtypes.RPCType_REST, nil default: return sharedtypes.RPCType_UNKNOWN_RPC, ErrSupplierConfigInvalidRPCType.Wrapf("%s", endpoint.RPCType) }