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