PATH Config

PATH
Path Configration YAML File

PATH Configuration

These instructions are intended for configuring the PATH Gateway.

Envoy Proxy has its own set of configuration files.

For details, see the the Envoy Configuration Guide.

Table of Contents

• Configuration YAML File: .config.yaml
  • Config File Location
  • Example Config Files
  • Config YAML Schema Validation
  • Full Config Example
• YAML Field Explanations
  • Protocol Section
  • morse_config
    • Morse Field Descriptions
  • shannon_config
    • Shannon Field Descriptions
  • router_config (optional)
  • hydrator_config (optional)
  • auth_server_config (optional)
  • logger_config (optional)
  • messaging_config (TODO)

Configuration YAML File: .config.yaml

All configuration for the PATH gateway is defined in a single YAML file named .config.yaml.

Config File Location

The config file .config.yaml is located in:

• Default: ./config/.config.yaml (relative to PATH binary)
• Tilt: /app/config/.config.yaml (mounted in container from ./local/path/config/.config.yaml)

Override Config Location

Use -config flag to specify a custom location:

./path -config ./config/.config.custom.yaml

Example Config Files

We provide example configuration files with detailed comments for each protocol type:

• Shannon Gateway
• Morse Gateway

Config YAML Schema Validation

The configuration is validated against our YAML schema.

VSCode Validation

Use the YAML Language Support extension for real-time validation by adding:

# yaml-language-server: $schema=https://raw.githubusercontent.com/buildwithgrove/path/refs/heads/main/config/config.schema.yaml

Full Config Example

The following is quick example of a full config file.

Note exactly one of morse_config or shannon_config is acceptable and required.

Click to expand full config

# (Required) Morse Protocol Configuration
morse_config:
  full_node_config:
    url: "https://pocket-rpc.liquify.com" # Required: Pocket node URL
    relay_signing_key: "<128-char-hex>" # Required: Relay signing private key
    http_config: # Optional
      retries: 3 # Default: 3
      timeout: "5000ms" # Default: "5000ms"

  signed_aats: # Required
    "<40-char-app-address>": # Application address (hex)
      client_public_key: "<64-char-hex>" # Client public key
      application_public_key: "<64-char-hex>" # Application public key
      application_signature: "<128-char-hex>" # Application signature

# (Required) Morse Protocol Configuration
shannon_config:
  full_node_config:
    rpc_url: https://shannon-testnet-grove-rpc.beta.poktroll.com
    grpc_config:
      host_port: shannon-testnet-grove-grpc.beta.poktroll.com:443
    lazy_mode: true

  gateway_config:
    gateway_mode: "centralized"
    gateway_address: pokt1up7zlytnmvlsuxzpzvlrta95347w322adsxslw
    gateway_private_key_hex: 40af4e7e1b311c76a573610fe115cd2adf1eeade709cd77ca31ad4472509d388
    owned_apps_private_keys_hex:
      - 40af4e7e1b311c76a573610fe115cd2adf1eeade709cd77ca31ad4472509d388

# (Optional) Quality of Service (QoS) Configuration
hydrator_config:
  service_ids:
    - "eth"
    - "solana"
    - "pokt"

# (Optional) Authorization Server Configuration
auth_server_config:
  grpc_host_port: path-auth-data-server:50051
  grpc_use_insecure_credentials: true
  endpoint_id_extractor_type: url_path

# (Optional) Logger Configuration
logger_config:
  level: "info" # Valid values: debug, info, warn, error

YAML Field Explanations

This is a comprehensive outline and explanation of each YAML field in the configuration file.

Protocol Section

The config file MUST contain EXACTLY one of the following top-level protocol-specific sections:

• morse_config
• shannon_config

---

morse_config

Configuration for the Morse protocol gateway.

morse_config:
  full_node_config:
    url: "https://pocket-rpc.liquify.com" # Required: Pocket node URL
    relay_signing_key: "<128-char-hex>" # Required: Relay signing private key
    http_config: # Optional
      retries: 3 # Default: 3
      timeout: "5000ms" # Default: "5000ms"

  signed_aats: # Required
    "<40-char-app-address>": # Application address (hex)
      client_public_key: "<64-char-hex>" # Client public key
      application_public_key: "<64-char-hex>" # Application public key
      application_signature: "<128-char-hex>" # Application signature

Morse Field Descriptions

full_node_config

Field	Type	Required	Default	Description
url	string	Yes	-	URL of the full Pocket RPC node
relay_signing_key	string	Yes	-	128-character hex-encoded private key for signing relays

full_node_config.http_config

Field	Type	Required	Default	Description
retries	integer	No	3	Number of HTTP request retry attempts
timeout	string	No	"5000ms"	HTTP request timeout duration

signed_aats

Field	Type	Required	Default	Description
client_public_key	string	Yes	-	64-character hex-encoded client public key
application_public_key	string	Yes	-	64-character hex-encoded application public key
application_signature	string	Yes	-	128-character hex-encoded signature

---

shannon_config

Configuration for the Shannon protocol gateway.

shannon_config:
  full_node_config:
    rpc_url: "https://shannon-testnet-grove-rpc.beta.poktroll.com" # Required: Shannon node RPC URL
    grpc_config: # Required
      host_port: "shannon-testnet-grove-grpc.beta.poktroll.com:443" # Required: gRPC host and port
      # Optional backoff and keepalive configs...
      insecure: false # Optional: whether to use insecure connection
      backoff_base_delay: "1s" # Optional: initial backoff delay duration
      backoff_max_delay: "120s" # Optional: maximum backoff delay duration
      min_connect_timeout: "20s" # Optional: minimum timeout for connection attempts
      keep_alive_time: "20s" # Optional: frequency of keepalive pings
      keep_alive_timeout: "20s" # Optional: timeout for keepalive pings
    lazy_mode: true

  gateway_config: # Required
    gateway_mode: "centralized" # Required: centralized, delegated, or permissionless
    gateway_address: "pokt1up7zlytnmvlsuxzpzvlrta95347w322adsxslw" # Required: Bech32 address
    gateway_private_key_hex: "<64-char-hex>" # Required: Gateway private key
    owned_apps_private_keys_hex: # Required for centralized mode only
      - "<64-char-hex>" # Application private key
      - "<64-char-hex>" # Additional application private keys...

Shannon Field Descriptions

full_node_config

Field	Type	Required	Default	Description
rpc_url	string	Yes	-	URL of the Shannon RPC endpoint
grpc_config	object	Yes	-	gRPC connection configuration
lazy_mode	boolean	No	true	If true, disables caching of onchain data (e.g. apps, sessions)

full_node_config.grpc_config

Field	Type	Required	Default	Description
host_port	string	Yes	-	Host and port for gRPC connections
insecure	boolean	No	false	Whether to use insecure connection
backoff_base_delay	string	No	"1s"	Initial backoff delay duration
backoff_max_delay	string	No	"120s"	Maximum backoff delay duration
min_connect_timeout	string	No	"20s"	Minimum timeout for connection attempts
keep_alive_time	string	No	"20s"	Frequency of keepalive pings
keep_alive_timeout	string	No	"20s"	Timeout for keepalive pings

gateway_config

Field	Type	Required	Default	Description
gateway_mode	string	Yes	-	Mode of operation: centralized, delegated, or permissionless
gateway_address	string	Yes	-	Bech32-formatted gateway address (starts with pokt1)
gateway_private_key_hex	string	Yes	-	64-character hex-encoded secp256k1 gateway private key
owned_apps_private_keys_hex	string[]	Only in centralized mode	-	List of 64-character hex-encoded secp256k1 application private keys

---

router_config (optional)

Enables configuring how incoming requests are handled.

In particular, allows specifying server parameters for how the gateway handles incoming requests.

Field	Type	Required	Default	Description
port	integer	No	3069	Port number on which the gateway server listens
max_request_body_size	integer	No	1MB	Maximum request size in bytes
read_timeout	string	No	"5000ms" (5s)	Time limit for reading request data
write_timeout	string	No	"10000ms" (10s)	Time limit for writing response data
idle_timeout	string	No	"120000ms" (120s)	Time limit for closing idle connections

---

hydrator_config (optional)

Required To enable QoS for a service.

The service ID must be provided here.

Field	Type	Required	Default	Description
service_ids	array[string]	No	-	List of service IDs for which the Quality of Service (QoS) logic will apply

info

In order to enable QoS for a service, the ID provided here must match a service ID in config/service_qos.go.

warning

Not all services currently have a QoS implementation in PATH; new QoS implementations are actively being worked on.

If a service ID is not present in config/service_qos.go, a No-Op QoS implementation will be used for that service. This means a random endpoint will be selected for requests to that service.

---

auth_server_config (optional)

Required in order to authorize requests with Envoy Proxy.

Configures the External Authorization Server.

Field	Type	Required	Default	Description
grpc_host_port	string	Yes	-	Host and port for the remote gRPC connection to the Remote gRPC Server (eg. PADS). Pattern requires a host:port format.
grpc_use_insecure_credentials	boolean	No	false	Set to true if the Remote gRPC Server does not use TLS
endpoint_id_extractor_type	string	No	-	Either url_path or header. Specifies how endpoint IDs are extracted. See here for more details
port	integer	No	10003	The local port for running the Auth Server

info

For detailed information on the External Auth Server, please refer to the External Auth Server Documentation.

caution

This IS NOT used by the PATH Gateway logic itself, but was placed in the PATH Gateway's config file for convenience with the goal of avoiding another config file. This may change in the future.

:::

---

logger_config (optional)

Controls the logging behavior of the PATH gateway.

Field	Type	Required	Default	Description
level	string	No	"info"	Minimum log level. Valid values are: "debug", "info", "warn", "error"

Example configuration:

logger_config:
  # Valid values are: debug, info, warn, error
  # Defaults to info if not specified
  level: "warn"

---

messaging_config (TODO)

TODO

TODO_MVP(@adshmh): Add messaging_config