From 572cc3516e8e1c73f2849c90a31fd0a0d4ba1193 Mon Sep 17 00:00:00 2001 From: Redouane Lakrache Date: Thu, 21 Nov 2024 20:52:40 +0100 Subject: [PATCH 1/7] wip --- .../develop/contributing/observability.md | 4 +- .../performance_troubleshooting.md | 7 +- .../develop/developer_guide/quickstart.md | 67 ++++------------ .../docs/operate/infrastructure/devnet.md | 2 +- .../docs/operate/infrastructure/localnet.md | 11 +-- .../operate/infrastructure/private_testnet.md | 2 +- .../operate/infrastructure/repositories.md | 2 +- .../docker_compose_debian_cheatsheet.md | 20 ++--- .../quickstart/docker_compose_walkthrough.md | 78 +++++++++---------- .../operate/run_a_node/full_node_docker.md | 2 +- .../run_a_node/hardware_requirements.md | 15 ++-- .../{appgate_server.md => path_gateway.md} | 24 +++--- .../docs/operate/run_a_node/relay_miner.md | 6 +- .../operate/testing/load_testing_devnet.md | 4 +- .../operate/testing/load_testing_plan_1.md | 10 +-- docusaurus/docs/protocol/actors/actors.md | 4 +- .../docs/protocol/actors/appgate_server.md | 18 ++--- .../docs/protocol/actors/relay_miner.md | 4 +- 18 files changed, 118 insertions(+), 162 deletions(-) rename docusaurus/docs/operate/run_a_node/{appgate_server.md => path_gateway.md} (55%) diff --git a/docusaurus/docs/develop/contributing/observability.md b/docusaurus/docs/develop/contributing/observability.md index a1883b0e1..441afa3aa 100644 --- a/docusaurus/docs/develop/contributing/observability.md +++ b/docusaurus/docs/develop/contributing/observability.md @@ -15,7 +15,7 @@ We are still refining our observability guidelines. If in doubt - please reach o - [Best Practices](#best-practices) - [Examples](#examples) - [Counter](#counter) - - [x/proof/keeper/msg_server_create_claim.go](#xproofkeepermsg_server_create_claimgo) + - [x/proof/keeper/msg\_server\_create\_claim.go](#xproofkeepermsg_server_create_claimgo) - [Gauage](#gauage) - [x/tokenomics/module/abci.go](#xtokenomicsmoduleabcigo) - [Histogram](#histogram) @@ -28,7 +28,7 @@ We are still refining our observability guidelines. If in doubt - please reach o In our system, metrics are exposed using the Prometheus exporter. This approach aligns with tools like Rollkit, and we leverage the [go-kit metrics package](https://pkg.go.dev/github.com/go-kit/kit/metrics) for custom metrics implementation. For practical examples of metric definitions, refer to -[AppGate Metrics](https://github.com/pokt-network/poktroll/blob/main/pkg/appgateserver/metrics.go). +[RelayMiner Metrics](https://github.com/pokt-network/poktroll/blob/main/pkg/relayer/proxy/metrics.go). ### Types of Metrics diff --git a/docusaurus/docs/develop/developer_guide/performance_troubleshooting.md b/docusaurus/docs/develop/developer_guide/performance_troubleshooting.md index f27da1145..8bb2fdd71 100644 --- a/docusaurus/docs/develop/developer_guide/performance_troubleshooting.md +++ b/docusaurus/docs/develop/developer_guide/performance_troubleshooting.md @@ -11,7 +11,7 @@ title: Performance troubleshooting - [Available `pprof` Endpoints](#available-pprof-endpoints) - [Configure Software to Expose `pprof` Endpoints](#configure-software-to-expose-pprof-endpoints) - [Full Nodes and Validator Configuration](#full-nodes-and-validator-configuration) - - [AppGate Server and RelayMiner](#appgate-server-and-relayminer) + - [RelayMiner](#relayminer) - [Save the Profiling Data](#save-the-profiling-data) - [Explore the Profiling Data](#explore-the-profiling-data) - [Explore without saving data](#explore-without-saving-data) @@ -98,10 +98,9 @@ on a particular network interface and port. By default, `pprof` listens on `loca If the value has been modified, you must restart the process. -#### AppGate Server and RelayMiner +#### RelayMiner -Both `AppGate Server` and `RelayMiner` can be configured to expose a `pprof` -endpoint using a configuration file like this: +The `RelayMiner` can be configured to expose a `pprof` endpoint using a configuration file like this: ```yaml pprof: diff --git a/docusaurus/docs/develop/developer_guide/quickstart.md b/docusaurus/docs/develop/developer_guide/quickstart.md index 007aa9018..5f152833c 100644 --- a/docusaurus/docs/develop/developer_guide/quickstart.md +++ b/docusaurus/docs/develop/developer_guide/quickstart.md @@ -39,12 +39,11 @@ Create a new [GitHub issue here](https://github.com/pokt-network/pocket/issues/n - [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. Manually Stake an Application \& Deploy a PATH Gateway](#4-manually-stake-an-application--deploy-a-path-gateway) - [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) + - [4.4 Prepare the PATH Gateway configuration](#44-prepare-the-path-gateway-configuration) - [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) @@ -475,7 +474,7 @@ new shell instance. ::: -## 4. Manually Stake an Application & Deploy an AppGate Server +## 4. Manually Stake an Application & Deploy a PATH Gateway :::note Independent Gateway @@ -531,46 +530,13 @@ You can also you re-run, `make app_list` you should see that `SHANNON_APPLICATIO ![Apps](./img/quickstart_applist.png) -### 4.4 Prepare the AppGate Server configuration +### 4.4 Prepare the PATH Gateway 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:26657 -query_node_grpc_url: tcp://127.0.0.1:9090 -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:26657 \ - --home=./localnet/poktrolld -``` +You can learn more about our [PATH Gateway configs here](https://path.grove.city/operate). ## 5. Send A Relay -Now that we've staked an `Application`, are running an `AppGate Server`, staked +Now that we've staked an `Application`, are running a `PATH Gateway`, staked a `Supplier`, and are running a `RelayMiner`, we can send a relay! :::note Initialize Public Keys @@ -590,7 +556,7 @@ You can use `curl` ```bash curl -X POST -H "Content-Type: application/json" \ --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \ - http://localhost:42042/anvil + http://anvil.localhost:3000/v1 ``` If everything worked as expected, you should see output similar to the following: @@ -609,16 +575,16 @@ The Relay Request/Response from is captured in the sequence diagram below. sequenceDiagram actor U as User
(curl Client) - participant AG as AppGate Server
(off-chain Application Operator) + participant PG as PATH Gateway
(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 + U ->> +PG: eth_blockNumber
(JSON-RPC Request) + PG ->> +RM: POKT Relay Request RM ->> +anvil: eth_blockNumber anvil ->> -RM: eth_result - RM ->> -AG: POKT Relay Response - AG ->> -U: eth_result
(JSON-RPC Response) + RM ->> -PG: POKT Relay Response + PG ->> -U: eth_result
(JSON-RPC Response) ``` ### 5.3 What will happen later @@ -654,16 +620,17 @@ make supplier3_stake 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. +You can reuse the running `PATH Gateway` to send requests. However, since not all +of them have a `RelayMiner` running, you'll see that initially some of requests will fail. +Meanwhile `PATH Gateway` will build a set of responsive `RelayMiner`s excluding the +failing ones. Give it a shot by running the following multiple times: ```bash curl -X POST -H "Content-Type: application/json" \ --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \ - http://localhost:42042/anvil + http://anvil.localhost:3000/v1 ``` ### 5.5. Inspect the logs diff --git a/docusaurus/docs/operate/infrastructure/devnet.md b/docusaurus/docs/operate/infrastructure/devnet.md index 05ce3b679..9249acbed 100644 --- a/docusaurus/docs/operate/infrastructure/devnet.md +++ b/docusaurus/docs/operate/infrastructure/devnet.md @@ -135,7 +135,7 @@ We use the same ignite `config.yaml` to provision genesis in devnet as is used i ```yaml -appgateservers: +path_gateways: count: 1 gateways: count: 1 diff --git a/docusaurus/docs/operate/infrastructure/localnet.md b/docusaurus/docs/operate/infrastructure/localnet.md index 8c04b750f..e9a783c34 100644 --- a/docusaurus/docs/operate/infrastructure/localnet.md +++ b/docusaurus/docs/operate/infrastructure/localnet.md @@ -15,7 +15,7 @@ needed to send an end-to-end relay. - [Report issues](#report-issues) - [TL;DR](#tldr) - [Developing with LocalNet](#developing-with-localnet) - - [localnet_config.yaml](#localnet_configyaml) + - [localnet\_config.yaml](#localnet_configyaml) - [Scaling network actors](#scaling-network-actors) - [Off-chain actors configuration](#off-chain-actors-configuration) - [Modify Kubernetes workloads](#modify-kubernetes-workloads) @@ -83,8 +83,9 @@ workloads and local development. Following best practices in Helm chart design, we have default values defined in the `values.yaml` file of each service Helm chart. For example, [here are the RelayMiner `values.yaml`](https://github.com/pokt-network/helm-charts/blob/main/charts/relayminer/values.yaml). -Local infrastructure requires some changes to the default values to properly configure RelayMiner or AppGate Server, so -we override some of the values. You can find such overrides in the [poktroll/localnet/kubernetes directory](https://github.com/pokt-network/poktroll/tree/main/localnet/kubernetes). +Local infrastructure requires some changes to the default values to properly configure the RelayMiner +ro PATH Gateway, so we override some of the values. You can find such overrides in the +[poktroll/localnet/kubernetes directory](https://github.com/pokt-network/poktroll/tree/main/localnet/kubernetes). **IF YOU NEED TO CHANGE LocalNet configs, 👆 is the place.** @@ -135,7 +136,7 @@ observability: Each service in Tilt has a link to its own Grafana dashboard as seen in the image below. -Specifically, the RelayMiner, Validator, AppGateServer and others each have a separate dashboards. +Specifically, the RelayMiner, Validator, PATH Gateway and others each have a separate dashboards. ![Example](./access_dashboard_on_service.png) @@ -167,7 +168,7 @@ After you execute `make localnet_up`, many things happen: 1. Creates a new `localnet_config.yaml` if it doesn't exist. Updates it with default values if new ones are introduced. 2. Depending on the configuration in `localnet_config.yaml`, uses Helm charts from the local [helm-charts](https://github.com/pokt-network/helm-charts)repository or downloads Helm charts from our Helm chart repository (`https://pokt-network.github.io/helm-charts/`). 3. Compiles the `poktrolld` binary from the source code. - 4. Using values from `localnet_config.yaml`, provisions an observability stack (Grafana, Prometheus, Loki), a validator, AppGate servers, RelayMiners, etc. + 4. Using values from `localnet_config.yaml`, provisions an observability stack (Grafana, Prometheus, Loki), a validator, PATH Gateways, RelayMiners, etc. 4. With `make localnet_up` continually running in the background, `tilt` monitors for code changes and re-compiles the binary when a code change is detected. After the new binary is built, it is pushed to the containers and all processes restart. ## Troubleshooting diff --git a/docusaurus/docs/operate/infrastructure/private_testnet.md b/docusaurus/docs/operate/infrastructure/private_testnet.md index 56c5bfea3..262fbfca0 100644 --- a/docusaurus/docs/operate/infrastructure/private_testnet.md +++ b/docusaurus/docs/operate/infrastructure/private_testnet.md @@ -24,4 +24,4 @@ Community members provide explorers for this testnet: ## Deployment Example We provide an example for the community on how to deploy the Full Node, Relay Miner, -and AppGate Server in the [poktroll-docker-compose-example GitHub Repo](https://github.com/pokt-network/poktroll-docker-compose-example). +and PATH Gateway in the [poktroll-docker-compose-example GitHub Repo](https://github.com/pokt-network/poktroll-docker-compose-example). diff --git a/docusaurus/docs/operate/infrastructure/repositories.md b/docusaurus/docs/operate/infrastructure/repositories.md index 12d07ab01..e27dfed7e 100644 --- a/docusaurus/docs/operate/infrastructure/repositories.md +++ b/docusaurus/docs/operate/infrastructure/repositories.md @@ -10,6 +10,6 @@ title: Repositories `ArgoCD` consumes different manifests and provisions/maintains workloads using these manifests. - [pokt-network/poktroll-docker-compose-example](https://github.com/pokt-network/poktroll-docker-compose-example): Repository containing an example of how to provision the `poktroll` stack using `docker-compose`. - It includes instructions on configuring, staking and deploying Full Nodes, RelayMiner and AppGate Servers. + It includes instructions on configuring, staking and deploying Full Nodes, RelayMiner and PATH Gateways. - [pokt-network/helm-charts](https://github.com/pokt-network/helm-charts): helm charts to simplify the deployment of our software on `kubernetes`. - [pokt-network/pocket-network-genesis](https://github.com/pokt-network/pocket-network-genesis): repository containing genesis files for all networks. diff --git a/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md b/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md index 6493b012e..7c4b8f7d2 100644 --- a/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md @@ -16,7 +16,7 @@ import ReactPlayer from "react-player"; - [Create new addresses for all your accounts and update .env](#create-new-addresses-for-all-your-accounts-and-update-env) - [Fund your accounts](#fund-your-accounts) - [Stake a Supplier \& Deploy a RelayMiner](#stake-a-supplier--deploy-a-relayminer) -- [Stake an Application \& Deploy an AppGate Server](#stake-an-application--deploy-an-appgate-server) +- [Stake an Application \& Deploy a PATH Gateway](#stake-an-application--deploy-a-path-gateway) - [Send a Relay](#send-a-relay) - [Ensure you get a response](#ensure-you-get-a-response) - [\[BONUS\] Deploy a PATH Gateway](#bonus-deploy-a-path-gateway) @@ -25,7 +25,7 @@ import ReactPlayer from "react-player"; - [Fund the same accounts](#fund-the-same-accounts) - [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) + - [Start the PATH Gateway](#start-the-path-gateway) - [Re-stake the gateway](#re-stake-the-gateway) ## Results @@ -192,7 +192,7 @@ docker compose up -d relayminer docker logs -f --tail 100 relayminer ``` -## Stake an Application & Deploy an AppGate Server +## Stake an Application & Deploy a PATH Gateway Stake the application: @@ -203,18 +203,18 @@ poktrolld tx application stake-application --config=/poktroll/stake_configs/appl poktrolld query application show-application $APPLICATION_ADDR ``` -Start the appgate server: +Start the PATH gateway: ```bash -docker compose up -d appgate +docker compose up -d pathgw # OPTIONALLY view the logs -docker logs -f --tail 100 appgate +docker logs -f --tail 100 pathgw ``` ## Send a Relay ```bash -curl http://$NODE_HOSTNAME:85/0021 \ +curl http://eth-mainnet.$NODE_HOSTNAME:3000/v1 \ -X POST \ -H "Content-Type: application/json" \ --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}' @@ -308,7 +308,7 @@ docker compose up -d relayminer docker logs -f --tail 100 relayminer ``` -### Start the AppGate Server +### Start the PATH Gateway ```bash # Stake @@ -316,9 +316,9 @@ poktrolld tx application stake-application --config=/poktroll/stake_configs/appl # Check poktrolld query application show-application $APPLICATION_ADDR # Start -docker compose up -d appgate +docker compose up -d pathgw # View -docker logs -f --tail 100 appgate +docker logs -f --tail 100 pathgw ``` ### 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..4fc372de8 100644 --- a/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md +++ b/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md @@ -13,9 +13,8 @@ import ReactPlayer from "react-player"; - [Prerequisites](#prerequisites) - [A. Deploying a Full Node](#a-deploying-a-full-node) - [B. Creating a Supplier and Deploying a RelayMiner](#b-creating-a-supplier-and-deploying-a-relayminer) -- [C. Creating an Application and Deploying an AppGate Server](#c-creating-an-application-and-deploying-an-appgate-server) -- [D. Creating a Gateway Deploying an Gateway Server](#d-creating-a-gateway-deploying-an-gateway-server) - - [\[BONUS\] Deploy a PATH Gateway](#bonus-deploy-a-path-gateway) +- [C. Creating an Application and Deploying a PATH Gateway](#c-creating-an-application-and-deploying-a-path-gateway) +- [D. Creating a Gateway Deploying a PATH Gateway](#d-creating-a-gateway-deploying-a-path-gateway) +### 0. Prerequisites for PATH Gateway -- **Full Node**: This AppGate Server deployment guide assumes the Full Node is +- **Full Node**: This `PATH Gateway` deployment guide assumes the Full Node is deployed in the same docker-compose stack; see section A. - **A poktroll account with uPOKT tokens**: Tokens can be acquired by contacting the team. You are going to need a BIPmnemonic phrase for an existing @@ -480,38 +479,36 @@ Verify your application is staked poktrolld query application show-application $APPLICATION_ADDR ``` -### Configure and run your AppGate Server +### Configure and run your PATH Gateway -:::tip AppGate Server operation config +:::tip PATH Gateway operation config -[dev.poktroll.com/operate/configs/appgate_server_config](https://dev.poktroll.com/operate/configs/appgate_server_config) -explains what the AppGate Server operation config is and how it can be used. +[path.grove.city/operate/](https://path.grove.city/operate) explains what the +`PATH Gateway` operation config is and how it can be used. ::: -appgate/config/appgate_config.yaml - ```bash -docker-compose up -d appgate +docker-compose up -d pathgw ``` Check logs and confirm the node works as expected: ```bash -docker-compose logs -f --tail 100 appgate +docker-compose logs -f --tail 100 pathgw ``` ### Send a relay -You can send requests to the newly deployed AppGate Server. If there are any +You can send requests to the newly deployed `PATH Gateway`. If there are any Suppliers on the network that can provide the service, the request will be routed to them. -The endpoint you want to send request to is: `http://your_node:appgate_server_port/service_id`. For example, this is how the request can be routed to `ethereum` -represented by `0021`: +The endpoint you want to send request to is: `http://your_node:path_gateway_port/service_id`. +For example, this is how the request can be routed to `ethereum` represented by the alias `eth-mainnet`: ```bash -curl http://$NODE_HOSTNAME:85/0021 \ +curl http://eth-mainnet.$NODE_HOSTNAME:3000/v1 \ -X POST \ -H "Content-Type: application/json" \ --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}' @@ -523,7 +520,7 @@ You should expect a result that looks like so: {"jsonrpc":"2.0","id":1,"result":"0x1289571"} ``` -## D. Creating a Gateway Deploying an Gateway Server +## D. Creating a Gateway Deploying a PATH Gateway Gateway Server allows to use services provided by other operators on Pocket Network. @@ -608,23 +605,21 @@ poktrolld query gateway show-gateway $GATEWAY_ADDR ### Configure and run your Gateway Server -:::tip Gateway Server operation config +:::tip PATH Gateway operation config -[dev.poktroll.com/operate/configs/appgate_server_config](https://dev.poktroll.com/operate/configs/appgate_server_config) -explains what the Gateway Server operation config is and how it can be used. +[path.grove.city/operate](https://path.grove.city/operate) +explains what the `PATH Gateway` operation config is and how it can be used. ::: -appgate/config/gateway_config.yaml - ```bash -docker-compose up -d gateway-example +docker-compose up -d pathgw ``` Check logs and confirm the node works as expected: ```bash -docker-compose logs -f --tail 100 gateway-example +docker-compose logs -f --tail 100 pathgw ``` ### Delegate your Application to the Gateway @@ -633,23 +628,20 @@ docker-compose logs -f --tail 100 gateway-example poktrolld tx application delegate-to-gateway $GATEWAY_ADDR --from=application-1 --chain-id=poktroll --chain-id=poktroll --yes ``` -### [BONUS] Deploy a PATH Gateway - -If you want to deploy a real Gateway, you can use [Grove's PATH](https://github.com/buildwithgrove/path). - ### Send a relay You can send requests to the newly deployed Gateway Server. If there are any Suppliers on the network that can provide the service, the request will be routed to them. -The endpoint you want to send request to is: `http://your_node:gateway_server_port/service_id`. For example, this is how the request can be routed to `ethereum` -represented by `0021`: +The endpoint you want to send request to is: `http://your_node:gateway_server_port/service_id`. +For example, this is how the request can be routed to `ethereum` represented by the alias `eth-mainnet`: ```bash -curl http://$NODE_HOSTNAME:84/0021?applicationAddr=$APPLICATION_ADDR \ +curl http://eth-mainnet.$NODE_HOSTNAME:3000/v1 \ -X POST \ -H "Content-Type: application/json" \ + -H "X-Application-Address: $APPLICATION_ADDR" \ --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}' ``` @@ -665,9 +657,10 @@ To ensure you get a response, you may need to run the request a few times: ```bash for i in {1..10}; do - curl http://$NODE_HOSTNAME:85/0021 \ + curl http://eth-mainnet.$NODE_HOSTNAME:3000/v1 \ -X POST \ -H "Content-Type: application/json" \ + -H "X-Application-Address: $APPLICATION_ADDR" \ --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}' \ --max-time 1 echo "" @@ -679,4 +672,3 @@ Why? - Suppliers may have been staked, but the RelayMiner is no longer running. - Pocket does not currently have on-chain quality-of-service - Pocket does not currently have supplier jailing -- You can follow along with [buildwithgrove/path](https://github.com/buildwithgrove/path) for what we'll open source. diff --git a/docusaurus/docs/operate/run_a_node/full_node_docker.md b/docusaurus/docs/operate/run_a_node/full_node_docker.md index 13087c06e..49e1208c2 100644 --- a/docusaurus/docs/operate/run_a_node/full_node_docker.md +++ b/docusaurus/docs/operate/run_a_node/full_node_docker.md @@ -45,7 +45,7 @@ There are two types of Full Nodes: Within Pocket Network, the role of Full Nodes is pivotal for Node Runners. These nodes needed for off-chain entities like [RelayMiners](./relay_miner.md) and -[AppGates](./appgate_server.md), which rely on interaction with the Pocket Network +[PATH Gateways](./path_gateway.md), which rely on interaction with the Pocket Network blockchain for full functionality. This guide outlines how to configure, deploy and maintain Full Nodes. diff --git a/docusaurus/docs/operate/run_a_node/hardware_requirements.md b/docusaurus/docs/operate/run_a_node/hardware_requirements.md index 707fd6682..638899540 100644 --- a/docusaurus/docs/operate/run_a_node/hardware_requirements.md +++ b/docusaurus/docs/operate/run_a_node/hardware_requirements.md @@ -14,7 +14,7 @@ TODO_MAINNET: Update this document prior to MainNet release - [Validator / Full Node](#validator--full-node) - [RPC Node](#rpc-node) - [RelayMiner](#relayminer) -- [AppGate Server / Gateway](#appgate-server--gateway) +- [PATH Gateway](#path-gateway) - [Additional Considerations](#additional-considerations) ### Validator / Full Node @@ -34,7 +34,7 @@ If the Full Node will serve as the RPC endpoint for Gateways and RelayMiners und ### RelayMiner -See the [RelayMiner](../../protocol/actors/appgate_server.md) documentation for more +See the [RelayMiner](../../protocol/actors/relay_miner.md) documentation for more information on what a RelayMiner is. | Component | Minimum | Recommended | @@ -46,7 +46,7 @@ information on what a RelayMiner is. Note that resource requirements for RelayMiner scale linearly with load: - More suppliers --> Higher resource consumption -- More relays --> HIgher resource consumption +- More relays --> Higher resource consumption :::note @@ -54,18 +54,17 @@ TODO_POST_MAINNET(@okdas): Provide benchmarks for relayminers handling different ::: -### AppGate Server / Gateway +### PATH Gateway -See the [AppGate Server](../../protocol/actors/appgate_server.md) documentation for more -information on what an AppGate Server is. +See the [PATH Gateway](https://path.grove.city) documentation for more +information on what a `PATH Gateway` is. | Component | Minimum | Recommended | | ----------- | ------- | ----------- | | CPU Cores | 1 | 4 | | RAM | 1GB | 16GB | | SSD Storage | N/A | N/A | - -**Note**: This service is stateless and does not require SSD storage. + ### Additional Considerations diff --git a/docusaurus/docs/operate/run_a_node/appgate_server.md b/docusaurus/docs/operate/run_a_node/path_gateway.md similarity index 55% rename from docusaurus/docs/operate/run_a_node/appgate_server.md rename to docusaurus/docs/operate/run_a_node/path_gateway.md index e0b63cbc5..62ab1dd8f 100644 --- a/docusaurus/docs/operate/run_a_node/appgate_server.md +++ b/docusaurus/docs/operate/run_a_node/path_gateway.md @@ -1,25 +1,25 @@ --- -title: AppGate Server +title: PATH Gateway sidebar_position: 4 --- -# Run an AppGate Server +# Run a PATH Gateway -- [What is AppGate Server?](#what-is-appgate-server) -- [AppGate Server Operation Requirements](#appgate-server-operation-requirements) +- [What is PATH Gateway?](#what-is-path-gateway) +- [PATH Gateway Operation Requirements](#path-gateway-operation-requirements) - [Hardware requirements](#hardware-requirements) - [Docker Compose Example](#docker-compose-example) - [Kubernetes Example](#kubernetes-example) -## What is AppGate Server? +## What is PATH Gateway? -See the [AppGate Server](../../protocol/actors/appgate_server.md) documentation for more -information on what an AppGate Server is. This page aims to provide links and +See the [PATH Gateway](https://path.grove.city) documentation for more +information on what a `PATH Gateway` is. This page aims to provide links and details on how to deploy and operate it. -## AppGate Server Operation Requirements +## PATH Gateway Operation Requirements -An AppGate Server requires the following: +A PATH Gateway requires the following: 1. A staked on-chain [Application](../../protocol/actors/application.md) to pay for services. 2. An optional on-chain [Gateway](../../protocol/actors/gateway.md) to optionally proxy services. @@ -32,12 +32,12 @@ This ensures the necessary infrastructure for blockchain communication is in pla ## Hardware requirements -Please see the [Hardware Requirements](./hardware_requirements.md#appgate-server--gateway) page. +Please see the [Hardware Requirements](./hardware_requirements.md#path-gateway) page. ## Docker Compose Example -Please refer to the `Deploying an AppGate Server` section in [poktroll-docker-compose-example](https://github.com/pokt-network/poktroll-docker-compose-example#deploying-an-appgate-server) -GitHub repository on how to deploy an AppGate Server using `docker-compose`. +Please refer to the `Deploying a PATH Gateway` section in [Docker compose walkthrough](../quickstart/docker_compose_walkthrough#d-creating-a-gateway-deploying-a-path-gateway) +on how to deploy a `PATH Gateway` using `docker-compose`. ## Kubernetes Example diff --git a/docusaurus/docs/operate/run_a_node/relay_miner.md b/docusaurus/docs/operate/run_a_node/relay_miner.md index b1f59be9d..fcf6e254a 100644 --- a/docusaurus/docs/operate/run_a_node/relay_miner.md +++ b/docusaurus/docs/operate/run_a_node/relay_miner.md @@ -13,7 +13,7 @@ sidebar_position: 5 ## What is a RelayMiner -See the [RelayMiner](../../protocol/actors/appgate_server.md) documentation for more +See the [RelayMiner](../../protocol/actors/relay_miner.md) documentation for more information on what a RelayMiner is. This page aims to provide links and details on how to deploy and operate it. @@ -35,8 +35,8 @@ Please see the [Hardware Requirements](./hardware_requirements.md#relayminer) pa ## Docker Compose Example -Please refer to the `Deploying a RelayMiner` section in [poktroll-docker-compose-example](https://github.com/pokt-network/poktroll-docker-compose-example#deploying-a-relay-miner) -GitHub repository on how to deploy an AppGate Server using `docker-compose`. +Please refer to the `Deploying a RelayMiner` section in [Docker compose walkthrough](../quickstart/docker_compose_walkthrough#b-creating-a-supplier-and-deploying-a-relayminer) +on how to deploy a `RelayMiner` using `docker-compose`. _TODO_DOCUMENT: Move over the relevant information from the `poktroll-docker-compose-example` repository into the docs_ diff --git a/docusaurus/docs/operate/testing/load_testing_devnet.md b/docusaurus/docs/operate/testing/load_testing_devnet.md index 8e9207647..581c91b6a 100644 --- a/docusaurus/docs/operate/testing/load_testing_devnet.md +++ b/docusaurus/docs/operate/testing/load_testing_devnet.md @@ -50,9 +50,7 @@ networkName: "sophon" image: tag: sha-7042be3 -appgateservers: - count: 1 -gateways: +path_gateways: count: 3 relayminers: count: 3 diff --git a/docusaurus/docs/operate/testing/load_testing_plan_1.md b/docusaurus/docs/operate/testing/load_testing_plan_1.md index 33f717bea..d497e82eb 100644 --- a/docusaurus/docs/operate/testing/load_testing_plan_1.md +++ b/docusaurus/docs/operate/testing/load_testing_plan_1.md @@ -22,7 +22,7 @@ _This document outlines the first load test for the Shannon upgrade. IT **IS NOT - [What to measure?](#what-to-measure) - [1. Chain State Size](#1-chain-state-size) - [2. Validators](#2-validators) - - [3. AppGate Server (Application, Gateway, etc…)](#3-appgate-server-application-gateway-etc) + - [3. PATH Gateway (Application, Gateway, etc…)](#3-path-gateway-application-gateway-etc) - [4. RelayMiner (Supplier, SMT, etc..)](#4-relayminer-supplier-smt-etc) - [Out-of-scope](#out-of-scope) - [Architecture / Component Diagram](#architecture--component-diagram) @@ -131,7 +131,7 @@ pie showData | Block Publishing | | | ❓ | | | | Data Availability State | | | | ❓ | | -#### 3. AppGate Server (Application, Gateway, etc…) +#### 3. PATH Gateway (Application, Gateway, etc…) `What`: Multiple `line charts` to capture `Disk` (size & iops), `RAM`, `CPU` , `Network` usage (ingress/egress) @@ -140,7 +140,7 @@ pie showData - `Relay Proxies` Ingress/egress of relays could add up to large networking costs - `Caches & State` - All the caching & state can have impact across the board - `Request Processing` - Signature generation, request marshaling / unmarshaling, etc… -- `Response handling` - Slow supplier responses could increase pending relays at the AppGate level (i.e. RAM) +- `Response handling` - Slow supplier responses could increase pending relays at the `PATH Gateway` level (i.e. RAM) | | RAM | CPU | Network | Disk | Time | | ------------------ | --- | --- | ------- | ---- | ---- | @@ -206,8 +206,8 @@ flowchart TB P("Pocket Validator") subgraph G["Gateways"] - AG1["AppGate Server 1"] - AGN["AppGate Server N"] + PG1["PATH Gateway 1"] + PGN["PATH Gateway N"] end subgraph S["Suppliers / RelayMiner"] diff --git a/docusaurus/docs/protocol/actors/actors.md b/docusaurus/docs/protocol/actors/actors.md index 8df87e84e..d69371ce0 100644 --- a/docusaurus/docs/protocol/actors/actors.md +++ b/docusaurus/docs/protocol/actors/actors.md @@ -23,7 +23,7 @@ There are 3 on-chain actors: There are 2 off-chain actors: - [RelayMiners](./relay_miner.md) -- [AppGateServers](./appgate_server.md) +- [PATH Gateways](./path_gateway.md) ```mermaid --- @@ -38,7 +38,7 @@ flowchart TB end subgraph off-chain - APS[AppGate Server] + PG[PATH Gateway] RM[Relay Miner] end diff --git a/docusaurus/docs/protocol/actors/appgate_server.md b/docusaurus/docs/protocol/actors/appgate_server.md index 4f35846d3..7ac2a6d53 100644 --- a/docusaurus/docs/protocol/actors/appgate_server.md +++ b/docusaurus/docs/protocol/actors/appgate_server.md @@ -1,9 +1,9 @@ --- -title: AppGate Server +title: PATH Gateway sidebar_position: 6 --- -# AppGate Server +# PATH Gateway - [Overview](#overview) - [Configuration](#configuration) @@ -11,23 +11,23 @@ sidebar_position: 6 ## Overview -An `AppGate Server` is responsible for relaying requests between a client dApp +`PATH Gateway` is responsible for relaying requests between a client dApp (e.g. mobile app, web app, etc...) and the [Supplier](./supplier.md)s on Pocket Network, handling all intermediary business logic. A [Gateway](./gateway.md) operator or a sovereign [Application](./application.md) -interested in accessing Pocket Network directly would need to run an -`AppGate Server` or custom software that implements the same functionality. +interested in accessing Pocket Network directly would need to run a `PATH Gateway` +or custom software that implements the same functionality. ## Configuration -Configurations and additional documentation related to operating an `AppGate Server` -can be found at [appgate_server_config.md](../../operate/configs/appgate_server_config.md). +Configurations and additional documentation related to operating a `PATH Gateway` +can be found at [path_gateway.md](https://path.grove.city/operate). ## CLI -All of the operations needed to start and operate an `AppGate Server` can be viewed by running: +All of the operations needed to start and operate a `PATH Gateway` can be viewed by running: ```bash -poktrolld appgate-server --help +path --help ``` diff --git a/docusaurus/docs/protocol/actors/relay_miner.md b/docusaurus/docs/protocol/actors/relay_miner.md index 9ad73f215..31121f362 100644 --- a/docusaurus/docs/protocol/actors/relay_miner.md +++ b/docusaurus/docs/protocol/actors/relay_miner.md @@ -13,8 +13,8 @@ sidebar_position: 5 A `RelayMiner` is a specialized operation node (not an on-chain actor) designed for individuals to **offer services** through Pocket Network alongside a staked -`Supplier`. It is responsible for proxying `RelayRequests` between an -`AppGate Server` and the supplied `Service`. +`Supplier`. It is responsible for proxying `RelayRequests` between a `PATH Gateway` +and the supplied `Service`. [Suppliers](./supplier.md) interested in providing `Service`s on Pocket Network would need to run a `RelayMiner` in addition to the software that provides the said `Service`. From bcbe8ca1cbec6e408e3f6e9b43e3a3c73707d5d3 Mon Sep 17 00:00:00 2001 From: Redouane Lakrache Date: Wed, 27 Nov 2024 18:29:45 +0100 Subject: [PATCH 2/7] docs: Complete AppGate removal --- .../docs/develop/packages/appgate_server.md | 200 ------------------ .../operate/configs/appgate_server_config.md | 168 --------------- .../quickstart/docker_compose_walkthrough.md | 14 +- .../operate/run_a_node/gateway_walkthrough.md | 2 - .../{appgate_server.md => path_gateway.md} | 0 5 files changed, 7 insertions(+), 377 deletions(-) delete mode 100644 docusaurus/docs/develop/packages/appgate_server.md delete mode 100644 docusaurus/docs/operate/configs/appgate_server_config.md rename docusaurus/docs/protocol/actors/{appgate_server.md => path_gateway.md} (100%) diff --git a/docusaurus/docs/develop/packages/appgate_server.md b/docusaurus/docs/develop/packages/appgate_server.md deleted file mode 100644 index 393f640d4..000000000 --- a/docusaurus/docs/develop/packages/appgate_server.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: AppGate Server -sidebar_position: 3 ---- - -# AppGate Server - -- [What is AppGate Server?](#what-is-appgate-server) -- [Architecture Overview](#architecture-overview) - - [Starting the AppGate Server](#starting-the-appgate-server) -- [Application Mode (self_signing = true)](#application-mode-self_signing--true) - - [Application RPC Request Schema](#application-rpc-request-schema) -- [Gateway Mode (self_signing = false)](#gateway-mode-self_signing--false) - - [Gateway RPC Request Schema](#gateway-rpc-request-schema) -- [Shannon SDK integration](#shannon-sdk-integration) - -## What is AppGate Server? - -`AppGate Server` is a ready to use component that allows `Application`s and -`Gateway`s to relay RPC requests to the Pocket Network `Supplier`s without having -to manage the underlying logic of the protocol. - -An operator only needs to specify a single [configuration file](../../operate/configs/appgate_server_config.md), -in order to run a sovereign `Application` or a `Gateway` via an `AppGate Server`. - -## Architecture Overview - -The following diagram captures a high-level overview of the `AppGate Server`'s message flow. - -```mermaid -flowchart TB - Client([Client]) - AGS(AppGate Server) - SDK[[ShannonSDK]] - FN[Full Node] - S[Supplier] - - Client -- RPC Request --> AGS - AGS -- RPC Response --> Client - - AGS -..-> |Check Config| Mode{self_signing?} - Mode -. true .-> ApplicationMode(Application Mode) - Mode -. false .-> GatewayMode(Gateway Mode) - - ApplicationMode -- (AppPrivKey, AppAddr, ServiceId) --> SDK - GatewayMode -- (GatewayPrivKey, AppAddr, ServiceId) --> SDK - - SDK <-. Query \n Supplier list .-> FN - SDK <-- RelayRequest \n RelayResponse --> S - SDK -- RPC Response \n (After Signature Verification) --> AGS -``` - -### Starting the AppGate Server - -The `AppGate Server` could be configured to act as a `Gateway` or as a `Application`. - -It can be started by running the following command: - -```bash -poktrolld appgate-server \ - --config \ - --keyring-backend -``` - -Where `` is the path to the `.yaml` [appgate server config file](../../operate/configs/appgate_server_config.md) -and `` is the backend to use for the keying. See the [cosmos documentation](https://docs.cosmos.network/v0.46/run-node/keyring.html) -for the full available set. - -Launching the `AppGate Server` starts an HTTP server that listens for incoming -RPC requests, and forwards them to the appropriate Pocket Network `Supplier`s. - -It takes care of things such as: - -- Querying and updating the list of `Supplier`s that are allowed to serve the - `Application` for given a `serviceId` during a given `session`. -- Selecting a `Supplier` to send the RPC request to. -- Appending the `Application`/`Gateway` ring-signature to the `RelayRequest` - before sending it to the `Supplier`. -- Sending the `RelayRequest` to the `Supplier`. -- Verifying the `Supplier`'s signature. -- Returning the `RelayResponse` to the requesting client - -## Application Mode (self_signing = true) - -If the [`self_signing`](../../operate/configs/appgate_server_config.md#self_signing) field is -set to `true`, the `AppGate Server` will act as an `Application`. It will -only serve the address derived from the [`signing_key`](../../operate/configs/appgate_server_config.md#signing_key). - -`RelayRequests` sent to the `AppGate Server` will be signed with the `signing_key` -resulting in a ring-signature that is only associated with the `Application`'s address. - -:::warning - -The `Application` MUST be sufficiently staked for the service being used as a -pre-requisite for the `AppGate Server` to properly service these requests. - -::: - -### Application RPC Request Schema - -When acting as an `Application`, the `AppGate Server` expects: - -- The `serviceId` to be part of the URL path -- The payload to be the body of the POST request -- The request should be sent to the [`listening_endpoint`](../../operate/configs/appgate_server_config.md#listening_endpoint) specified in the config file - -The following `curl` command demonstrates how to send a JSON-RPC type request -to the `AppGate Server`: - -```bash -curl -X POST \ - http://:/ \ - -H 'Content-Type: application/json' \ - -d '{ - "jsonrpc": "2.0", - "method": "", - "params": [], - "id": 1 - }' -``` - -## Gateway Mode (self_signing = false) - -If the [`self_signing`](../../operate/configs/appgate_server_config.md#self_signing) field -is set to `false`, then the `AppGate Server` will act as a `Gateway`, serving -`Application`s that delegated to the `Gateway` address represented by the -[`signing_key`](../../operate/configs/appgate_server_config.md#signing_key). - -The `AppGate Server` will determine the `Application` address to use by extracting -it from the `senderAddr` query parameter and use it along with the `signing_key` to -generate a ring-signature associated with the `Application`'s and `Gateway`'s address. - -:::warning - -The `Gateway` and `Application` MUST be appropriately staked for this to work -with the `Application` also have sufficient stake to pay for the service in -order for this to work. - -::: - -### Gateway RPC Request Schema - -When acting as an `Gateway`, the `AppGate Server` expects: - -- The `serviceId` to be part of the URL path -- The `payload` to be the body of the POST request -- The `Application` address as a query parameter in the request URL -- The request should be sent to the [`listening_endpoint`](../../operate/configs/appgate_server_config.md#listening_endpoint) specified in the config file - -The following `curl` command demonstrates how to send a JSON-RPC type request -to the `AppGate Server`: - -```bash -curl -X POST \ - http://:/?senderAddr= \ - -H 'Content-Type: application/json' \ - -d '{ - "jsonrpc": "2.0", - "method": "", - "params": [], - "id": 1 - }' -``` - -## Shannon SDK integration - -:::warning - -TODO_LEGACY: This was written before the Shannon SDK was fully implemented so -some of the details may be outdated. - -::: - -The `AppGate Server` implementation uses the [Shannon SDK](https://github.com/pokt-network/shannon-sdk) to -interact with the Pocket Network. It can either be used directly or referenced on how -the `ShannonSDK` can be used with a custom build `Application` / `Gateway`. -RPC requests to Pocket Network. - -The `AppGate Server`'s own logic is responsible for: - -- Exposing the HTTP server that listens for incoming RPC requests. -- Extracting the `serviceId` and `Application` address from the RPC request. -- Calling `ShannonSDK.GetSessionSupplierEndpoints` to get the list of `Supplier`s - that are allowed to serve the `Application` at a specific point in time. -- Selecting a `Supplier` to send the RPC request to. -- Calling the `ShannonSDK.SendRelay` to send the `RelayRequest` to the selected - `Supplier`. -- Verifying and returning the `RelayResponse` to the RPC request sender. - -While `ShannonSDK` manages: - -- Being up-to-date with the latest `Session`. -- Maintaining the list of `Supplier`s that are allowed to serve the `Application`. -- Forming the `RelayRequest` object. -- Creating the ring-signature for the `RelayRequest`. -- Sending the `RelayRequest` to the `Supplier`. -- Verifying the `Supplier`'s signature. - -A sequence diagram demonstrating the interaction between the `AppGate Server` and -the `ShannonSDK` can be found in the [ShannonSDK documentation](https://github.com/pokt-network/shannon-sdk). diff --git a/docusaurus/docs/operate/configs/appgate_server_config.md b/docusaurus/docs/operate/configs/appgate_server_config.md deleted file mode 100644 index 583cd75bd..000000000 --- a/docusaurus/docs/operate/configs/appgate_server_config.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: AppGateServer config -sidebar_position: 5 ---- - -# AppGateServer config - -This document describes the configuration options for the `AppGateServer`, -an `Application` or `Gateway` co-processor/sidecar -that acts as the real server for querying request, signing requests and verifying responses. - -This document describes the configuration options available for the -`AppGateServer`through the `appgate_server_config.yaml` file. - -:::tip - -You can find a fully featured example configuration at [appgate_server_config_example.yaml](https://github.com/pokt-network/poktroll/blob/main/localnet/poktrolld/config/appgate_server_config_example.yaml). - -::: - -- [Introduction](#introduction) -- [Usage](#usage) -- [Configuration](#configuration) - - [`query_node_rpc_url`](#query_node_rpc_url) - - [`query_node_grpc_url`](#query_node_grpc_url) - - [`self_signing`](#self_signing) - - [`signing_key`](#signing_key) - - [`listening_endpoint`](#listening_endpoint) - - [`metrics`](#metrics) - - [`pprof`](#pprof) - -## Introduction - -The `AppGateServer` is responsible for multiple things: - -1. Determines how the `AppGateServer` with respect to Pocket network connectivity -2. Whether it acts as a self serving `Application` or a `Gateway` to other `Applications` -3. Configures the host(s) it listens on for incoming `RelayRequests` - -## Usage - -The `AppGateServer` start command accepts a `--config` flag that points to a -configuration `.yaml` file that will be used to initialize the `AppGateServer`. - -:::warning - -TestNet is not ready as of writing this documentation, so you may -need to adjust the command below appropriately. - -::: - -```bash -poktrolld appgate-server \ - --config ./appgate_server_config.yaml \ - --keyring-backend test -``` - -## Configuration - -The `AppGateServer` configuration file is a `.yaml` file that contains the -following fields: - -```yaml -query_node_rpc_url: tcp://: -query_node_grpc_url: tcp://: -self_signing: -signing_key: -listening_endpoint: http://: -metrics: - enabled: true - addr: :9090 -``` - -### `query_node_rpc_url` - -_`Required`_ - -The RPC URL of the Pocket node that allows the `AppGateServer` to subscribe to -on-chain CometBFT events via websockets. It is re-formatted by the SDK as -`ws://:/websocket` and establishes a persistent connection to -the Pocket Node in order to stream events such as latest blocks, and other -information such as on-chain (un)delegation events. - -### `query_node_grpc_url` - -_`Required`_ - -The gRPC URL of the Pocket node that allows the `AppGateServer` to fetch data -from the Pocket network (eg. Sessions, Accounts, Applications, etc...). - -### `self_signing` - -:::tip - -tl;dr - -- `true` -> `AppGateServer` acts as an `Application` -- `false` -> `AppGateServer` acts as a `Gateway` - -::: - -_`Optional`_ - -Indicates whether the `AppGateServer` acts as a self serving `Application` or a -`Gateway` to other `Application`s. - -If `true`, the `AppGateServer` will act as an `Application` and will only use -its own address to generate a ring-signer for signing `RelayRequest`s before -forwarding them to a `RelayMiner`. - -If `false`, the `AppGateServer` will act as a `Gateway` and will generate a -ring-signer from both its address and the `Application`'s address provided in -the request's `applicationAddr` query parameter then use it to sign the `RelayRequests` -before forwarding them to a `RelayMiner`. - -### `signing_key` - -_`Required`_ - -Name of the key used to derive the public key and the corresponding address -for cryptographic rings generation used to sign `RelayRequests`. - -The key name must be present in the keyring that is specified when the -`AppGateServer` is started. - -### `listening_endpoint` - -_`Required`_ - -The endpoint that the `AppGateServer` will listen on for incoming requests. - -### `metrics` - -_`Optional`_ - -This section configures a Prometheus exporter endpoint, enabling the collection -and export of metrics data. The `addr` field specifies the network address for -the exporter to bind to. It can be either a port number, which assumes binding -to all interfaces, or a specific host:port combination. - -Example configuration: - -```yaml -metrics: - enabled: true - addr: :9090 -``` - -When `enabled` is set to `true`, the exporter is active. The addr `value` of -`:9090` implies the exporter is bound to port 9090 on all available network -interfaces. - -### `pprof` - -_`Optional`_ - -Configures a [pprof](https://github.com/google/pprof/blob/main/doc/README.md) -endpoint for troubleshooting and debugging performance issues. - -Example configuration: - -```yaml -pprof: - enabled: true - addr: localhost:6060 -``` - -You can learn how to use that endpoint on the [Performance Troubleshooting](../../develop/developer_guide/performance_troubleshooting.md) page. diff --git a/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md b/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md index c64a9a3ef..9edd5f6f8 100644 --- a/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md +++ b/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md @@ -558,11 +558,11 @@ You should expect a result that looks like so: ## D. Creating a Gateway Deploying a PATH Gateway -Gateway Server allows to use services provided by other operators on Pocket Network. +`PATH Gateway` allows to use services provided by other operators on Pocket Network. -### 0. Prerequisites for a Gateway Server +### 0. Prerequisites for a PATH Gateway -- **Full Node**: This Gateway Server deployment guide assumes the Full Node is +- **Full Node**: This `PATH Gateway` deployment guide assumes the Full Node is deployed in the same docker-compose stack; see section A. - **A poktroll account with uPOKT tokens**: Tokens can be acquired by contacting the team. You are going to need a BIPmnemonic phrase for an existing @@ -639,7 +639,7 @@ Verify your gateway is staked poktrolld query gateway show-gateway $GATEWAY_ADDR ``` -### Configure and run your Gateway Server +### Configure and run your `PATH Gateway` :::tip PATH Gateway operation config @@ -666,11 +666,11 @@ poktrolld tx application delegate-to-gateway $GATEWAY_ADDR --from=application-1 ### Send a relay -You can send requests to the newly deployed Gateway Server. If there are any +You can send requests to the newly deployed `PATH Gateway`. If there are any Suppliers on the network that can provide the service, the request will be routed to them. -The endpoint you want to send request to is: `http://your_node:gateway_server_port/service_id`. +The endpoint you want to send request to is: `http://service_id.your_node:gateway_server_port/v1`. For example, this is how the request can be routed to `ethereum` represented by the alias `eth-mainnet`: ```bash @@ -687,7 +687,7 @@ You should expect a result that looks like so: {"jsonrpc":"2.0","id":1,"result":"0x1289571"} ``` -#### 5.1 Ensure you get a response +#### 5.1 Ensure you get a response To ensure you get a response, you may need to run the request a few times: diff --git a/docusaurus/docs/operate/run_a_node/gateway_walkthrough.md b/docusaurus/docs/operate/run_a_node/gateway_walkthrough.md index 8c8ec1f9a..6178ea217 100644 --- a/docusaurus/docs/operate/run_a_node/gateway_walkthrough.md +++ b/docusaurus/docs/operate/run_a_node/gateway_walkthrough.md @@ -5,8 +5,6 @@ sidebar_position: 4 # Run a Gateway -TODO_BETA(@red-0ne): Update this page to use PATH. - - [What is PATH Gateway?](#what-is-path-gateway) - [PATH Gateway Operation Requirements](#path-gateway-operation-requirements) - [Hardware requirements](#hardware-requirements) diff --git a/docusaurus/docs/protocol/actors/appgate_server.md b/docusaurus/docs/protocol/actors/path_gateway.md similarity index 100% rename from docusaurus/docs/protocol/actors/appgate_server.md rename to docusaurus/docs/protocol/actors/path_gateway.md From 31ed46f01d6830821d3122cfdd0172161be003d7 Mon Sep 17 00:00:00 2001 From: Redouane Lakrache Date: Wed, 27 Nov 2024 18:31:20 +0100 Subject: [PATCH 3/7] chore: Remove auto-added backslashes --- docusaurus/docs/develop/contributing/observability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/develop/contributing/observability.md b/docusaurus/docs/develop/contributing/observability.md index 441afa3aa..346e805fa 100644 --- a/docusaurus/docs/develop/contributing/observability.md +++ b/docusaurus/docs/develop/contributing/observability.md @@ -15,7 +15,7 @@ We are still refining our observability guidelines. If in doubt - please reach o - [Best Practices](#best-practices) - [Examples](#examples) - [Counter](#counter) - - [x/proof/keeper/msg\_server\_create\_claim.go](#xproofkeepermsg_server_create_claimgo) + - [x/proof/keeper/msg_server_create_claim.go](#xproofkeepermsg_server_create_claimgo) - [Gauage](#gauage) - [x/tokenomics/module/abci.go](#xtokenomicsmoduleabcigo) - [Histogram](#histogram) From 93f1677bee2c1ed865849c9e036707a7d53ed112 Mon Sep 17 00:00:00 2001 From: Redouane Lakrache Date: Wed, 27 Nov 2024 19:32:22 +0100 Subject: [PATCH 4/7] chore: Self review --- .../performance_troubleshooting.md | 1 + .../docs/develop/developer_guide/quickstart.md | 9 +++++---- .../docs/operate/infrastructure/devnet.md | 2 -- .../docs/operate/infrastructure/localnet.md | 6 +++--- .../docker_compose_debian_cheatsheet.md | 18 +----------------- .../quickstart/docker_compose_walkthrough.md | 12 +++++------- .../docs/protocol/actors/path_gateway.md | 9 --------- 7 files changed, 15 insertions(+), 42 deletions(-) diff --git a/docusaurus/docs/develop/developer_guide/performance_troubleshooting.md b/docusaurus/docs/develop/developer_guide/performance_troubleshooting.md index 8bb2fdd71..0bfdb8f75 100644 --- a/docusaurus/docs/develop/developer_guide/performance_troubleshooting.md +++ b/docusaurus/docs/develop/developer_guide/performance_troubleshooting.md @@ -101,6 +101,7 @@ If the value has been modified, you must restart the process. #### RelayMiner The `RelayMiner` can be configured to expose a `pprof` endpoint using a configuration file like this: + ```yaml pprof: diff --git a/docusaurus/docs/develop/developer_guide/quickstart.md b/docusaurus/docs/develop/developer_guide/quickstart.md index 5f152833c..b66183ae9 100644 --- a/docusaurus/docs/develop/developer_guide/quickstart.md +++ b/docusaurus/docs/develop/developer_guide/quickstart.md @@ -478,9 +478,10 @@ new shell instance. :::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. +This section will show how to deploy a `PATH Gateway` with `Centralized` mode, +which will use its configured `Application`s to sign relays. + +We are leaving delegated Gateways outside the scope of the Quickstart guide. ::: @@ -621,7 +622,7 @@ make supplier3_stake Running `make supplier_list` should now show that all three suppliers are staked. You can reuse the running `PATH Gateway` to send requests. However, since not all -of them have a `RelayMiner` running, you'll see that initially some of requests will fail. +the `Supplier`s have a `RelayMiner` running, you'll see that initially some of requests will fail. Meanwhile `PATH Gateway` will build a set of responsive `RelayMiner`s excluding the failing ones. diff --git a/docusaurus/docs/operate/infrastructure/devnet.md b/docusaurus/docs/operate/infrastructure/devnet.md index 9249acbed..48166bc00 100644 --- a/docusaurus/docs/operate/infrastructure/devnet.md +++ b/docusaurus/docs/operate/infrastructure/devnet.md @@ -137,8 +137,6 @@ We use the same ignite `config.yaml` to provision genesis in devnet as is used i ```yaml path_gateways: count: 1 -gateways: - count: 1 relayminers: count: 1 ``` diff --git a/docusaurus/docs/operate/infrastructure/localnet.md b/docusaurus/docs/operate/infrastructure/localnet.md index e9a783c34..76260c51c 100644 --- a/docusaurus/docs/operate/infrastructure/localnet.md +++ b/docusaurus/docs/operate/infrastructure/localnet.md @@ -15,7 +15,7 @@ needed to send an end-to-end relay. - [Report issues](#report-issues) - [TL;DR](#tldr) - [Developing with LocalNet](#developing-with-localnet) - - [localnet\_config.yaml](#localnet_configyaml) + - [localnet_config.yaml](#localnet_configyaml) - [Scaling network actors](#scaling-network-actors) - [Off-chain actors configuration](#off-chain-actors-configuration) - [Modify Kubernetes workloads](#modify-kubernetes-workloads) @@ -83,8 +83,8 @@ workloads and local development. Following best practices in Helm chart design, we have default values defined in the `values.yaml` file of each service Helm chart. For example, [here are the RelayMiner `values.yaml`](https://github.com/pokt-network/helm-charts/blob/main/charts/relayminer/values.yaml). -Local infrastructure requires some changes to the default values to properly configure the RelayMiner -ro PATH Gateway, so we override some of the values. You can find such overrides in the +Local infrastructure requires some changes to the default values to properly configure the `RelayMiner` +or `PATH Gateway`, so we override some of the values. You can find such overrides in the [poktroll/localnet/kubernetes directory](https://github.com/pokt-network/poktroll/tree/main/localnet/kubernetes). **IF YOU NEED TO CHANGE LocalNet configs, 👆 is the place.** diff --git a/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md b/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md index e4f5feec0..8bf30f1d2 100644 --- a/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md @@ -19,7 +19,6 @@ import ReactPlayer from "react-player"; - [Stake an Application \& Deploy a PATH Gateway](#stake-an-application--deploy-a-path-gateway) - [Send a Relay](#send-a-relay) - [Ensure you get a response](#ensure-you-get-a-response) -- [\[BONUS\] Deploy a PATH Gateway](#bonus-deploy-a-path-gateway) - [Managing a re-genesis](#managing-a-re-genesis) - [Full Nodes](#full-nodes) - [Fund the same accounts](#fund-the-same-accounts) @@ -244,22 +243,6 @@ for i in {1..10}; do done ``` -## [BONUS] Deploy a PATH Gateway - -If you want to deploy a real Gateway, you can use [Grove's PATH](https://github.com/buildwithgrove/path) -after running the following commands: - -```bash -# Stake the gateway -poktrolld tx gateway stake-gateway --config=/poktroll/stake_configs/gateway_stake_config_example.yaml --from=gateway --chain-id=poktroll --yes -# Delegate from the application to the gateway -poktrolld tx application delegate-to-gateway $GATEWAY_ADDR --from=application --chain-id=poktroll --chain-id=poktroll --yes - -# OPTIONALLY check the gateway's and application's status -poktrolld query gateway show-gateway $GATEWAY_ADDR -poktrolld query application show-application $APPLICATION_ADDR -``` - ## Managing a re-genesis Assuming you already had everything functioning following the steps above, this @@ -329,3 +312,4 @@ docker compose up -d pathgw # View docker logs -f --tail 100 pathgw ``` + \ No newline at end of file diff --git a/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md b/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md index 9edd5f6f8..cc8a017d6 100644 --- a/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md +++ b/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md @@ -80,9 +80,9 @@ In `Morse`, a `Validator` or a staked `Node` was responsible for both holding a copy of the on-chain data, as well as performing relays. With `Shannon`, the `RelayMiner` software, which runs the supplier logic, is distinct from the full-node/validator. -Furthermore, `Shannon` uses the `PATH Gateway`, a software component that acts on -behalf of either `Applications` or `Gateways` to access services provided by Pocket -Network `Supplier`s via `RelayMiners`. +Furthermore, `Shannon` uses [`PATH Gateway`](https://github.com/buildwithgrove/path), +a software component that acts on behalf of either `Applications` or `Gateways` +to access services provided by Pocket Network `Supplier`s via `RelayMiners`. The following diagram from the [actors](../../protocol/actors/) page captures the relationship between on-chain records (actors) and off-chain operators (servers). @@ -540,7 +540,7 @@ You can send requests to the newly deployed `PATH Gateway`. If there are any Suppliers on the network that can provide the service, the request will be routed to them. -The endpoint you want to send request to is: `http://your_node:path_gateway_port/service_id`. +The endpoint you want to send request to is: `http://service_alias.your_node:path_gateway_port/v1`. For example, this is how the request can be routed to `ethereum` represented by the alias `eth-mainnet`: ```bash @@ -670,14 +670,13 @@ You can send requests to the newly deployed `PATH Gateway`. If there are any Suppliers on the network that can provide the service, the request will be routed to them. -The endpoint you want to send request to is: `http://service_id.your_node:gateway_server_port/v1`. +The endpoint you want to send request to is: `http://service_alias.your_node:gateway_server_port/v1`. For example, this is how the request can be routed to `ethereum` represented by the alias `eth-mainnet`: ```bash curl http://eth-mainnet.$NODE_HOSTNAME:3000/v1 \ -X POST \ -H "Content-Type: application/json" \ - -H "X-Application-Address: $APPLICATION_ADDR" \ --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}' ``` @@ -696,7 +695,6 @@ for i in {1..10}; do curl http://eth-mainnet.$NODE_HOSTNAME:3000/v1 \ -X POST \ -H "Content-Type: application/json" \ - -H "X-Application-Address: $APPLICATION_ADDR" \ --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}' \ --max-time 1 echo "" diff --git a/docusaurus/docs/protocol/actors/path_gateway.md b/docusaurus/docs/protocol/actors/path_gateway.md index 7ac2a6d53..f2954923d 100644 --- a/docusaurus/docs/protocol/actors/path_gateway.md +++ b/docusaurus/docs/protocol/actors/path_gateway.md @@ -7,7 +7,6 @@ sidebar_position: 6 - [Overview](#overview) - [Configuration](#configuration) -- [CLI](#cli) ## Overview @@ -23,11 +22,3 @@ or custom software that implements the same functionality. Configurations and additional documentation related to operating a `PATH Gateway` can be found at [path_gateway.md](https://path.grove.city/operate). - -## CLI - -All of the operations needed to start and operate a `PATH Gateway` can be viewed by running: - -```bash -path --help -``` From a860456d3af5ed7ba4d17ee73edb0534a7b9dc38 Mon Sep 17 00:00:00 2001 From: Redouane Lakrache Date: Wed, 27 Nov 2024 19:41:18 +0100 Subject: [PATCH 5/7] chore: Change pprof TODO --- .../develop/developer_guide/performance_troubleshooting.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docusaurus/docs/develop/developer_guide/performance_troubleshooting.md b/docusaurus/docs/develop/developer_guide/performance_troubleshooting.md index 0bfdb8f75..277d2cecb 100644 --- a/docusaurus/docs/develop/developer_guide/performance_troubleshooting.md +++ b/docusaurus/docs/develop/developer_guide/performance_troubleshooting.md @@ -101,7 +101,11 @@ If the value has been modified, you must restart the process. #### RelayMiner The `RelayMiner` can be configured to expose a `pprof` endpoint using a configuration file like this: - + ```yaml pprof: From dc9cf550146e2fb5fcb70893314407fab770ba27 Mon Sep 17 00:00:00 2001 From: Daniel Olshansky Date: Fri, 6 Dec 2024 15:26:29 -0800 Subject: [PATCH 6/7] Minor NITs --- .../developer_guide/performance_troubleshooting.md | 9 +++++---- .../docs/develop/developer_guide/quickstart.md | 14 ++++++++------ 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/docusaurus/docs/develop/developer_guide/performance_troubleshooting.md b/docusaurus/docs/develop/developer_guide/performance_troubleshooting.md index 277d2cecb..e45755a38 100644 --- a/docusaurus/docs/develop/developer_guide/performance_troubleshooting.md +++ b/docusaurus/docs/develop/developer_guide/performance_troubleshooting.md @@ -10,8 +10,8 @@ title: Performance troubleshooting - [How to Use `pprof`](#how-to-use-pprof) - [Available `pprof` Endpoints](#available-pprof-endpoints) - [Configure Software to Expose `pprof` Endpoints](#configure-software-to-expose-pprof-endpoints) - - [Full Nodes and Validator Configuration](#full-nodes-and-validator-configuration) - - [RelayMiner](#relayminer) + - [Full Node \& Validator pprof](#full-node--validator-pprof) + - [RelayMiner pprof](#relayminer-pprof) - [Save the Profiling Data](#save-the-profiling-data) - [Explore the Profiling Data](#explore-the-profiling-data) - [Explore without saving data](#explore-without-saving-data) @@ -91,16 +91,17 @@ or DoS your services if these endpoints are exposed to the internet. ::: -#### Full Nodes and Validator Configuration +#### Full Node & Validator pprof In `config.toml`, you can configure `pprof_laddr` to expose a `pprof` endpoint on a particular network interface and port. By default, `pprof` listens on `localhost:6060`. If the value has been modified, you must restart the process. -#### RelayMiner +#### RelayMiner pprof The `RelayMiner` can be configured to expose a `pprof` endpoint using a configuration file like this: + \ No newline at end of file +``` \ No newline at end of file diff --git a/docusaurus/docs/operate/run_a_node/hardware_requirements.md b/docusaurus/docs/operate/run_a_node/hardware_requirements.md index 638899540..fc9af1981 100644 --- a/docusaurus/docs/operate/run_a_node/hardware_requirements.md +++ b/docusaurus/docs/operate/run_a_node/hardware_requirements.md @@ -63,8 +63,8 @@ information on what a `PATH Gateway` is. | ----------- | ------- | ----------- | | CPU Cores | 1 | 4 | | RAM | 1GB | 16GB | -| SSD Storage | N/A | N/A | - +| SSD Storage | 5GB | 5GB | + ### Additional Considerations