2_gateway_config

shannon_config:
  full_node_config:
    rpc_url: https://shannon-grove-rpc.mainnet.poktroll.com
    grpc_config:
      host_port: shannon-grove-grpc.mainnet.poktroll.com:443
    lazy_mode: false

  gateway_config:
    gateway_mode: "centralized"
    gateway_address: pokt1up7zlytnmvlsuxzpzvlrta95347w322adsxslw
    gateway_private_key_hex: 40af4e7e1b311c76a573610fe115cd2adf1eeade709cd77ca31ad4472509d388
    owned_apps_private_keys_hex:
      - 40af4e7e1b311c76a573610fe115cd2adf1eeade709cd77ca31ad4472509d388
    service_fallback:
      - service_id: eth
        send_all_traffic: false
        fallback_urls:
          - "https://eth.rpc.grove.city/v1/1a2b3c4d"
          - "https://eth.rpc.grove.city/v1/5e6f7a8b"

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

Config File Location (Local Development)

In local development mode, the config file must be located at:

./local/path/.config.yaml

Config File Validation

If you are using VSCode, we recommend using the YAML Language Support extension for in-editor validation of the .config.yaml file. Enable it by ensuring the following annotation is present at the top of your config file:

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

Protocol Configuration

The config file MUST contain EXACTLY one top-level shannon_config section.

`shannon_config` (required)

Configuration for the Shannon protocol gateway.

shannon_config:
  full_node_config:
    lazy_mode: false
    rpc_url: "https://shannon-grove-rpc.mainnet.poktroll.com"
    grpc_config: # Required
      host_port: "shannon-grove-grpc.mainnet.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

  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...
    service_fallback: # Optional: Fallback endpoints
      - service_id: eth
        send_all_traffic: false
        fallback_urls:
          - "https://eth.rpc.grove.city/v1/1a2b3c4d"
          - "https://eth.rpc.grove.city/v1/5e6f7a8b"
      - service_id: polygon
        send_all_traffic: false
        fallback_urls:
          - "https://polygon.rpc.grove.city/v1/9x8y7z6w"

`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

false

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

false

Whether to use insecure connection

backoff_base_delay

string

"1s"

Initial backoff delay duration

backoff_max_delay

string

"120s"

Maximum backoff delay duration

min_connect_timeout

string

"20s"

Minimum timeout for connection attempts

keep_alive_time

string

"20s"

Frequency of keepalive pings

keep_alive_timeout

string

"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

service_fallback

array

Array of service fallback configurations (see below for details)

`service_fallback` (optional)

Configures fallback endpoints that the gateway will use when all protocol endpoints for a service become unavailable (e.g., sanctioned or offline). This provides resilience by allowing the gateway to continue serving requests even when protocol endpoints are temporarily unavailable.

service_fallback:
  - service_id: eth
    send_all_traffic: false
    fallback_urls:
      - "https://eth.rpc.grove.city/v1/1a2b3c4d"
      - "https://eth.rpc.grove.city/v1/5e6f7a8b"
  - service_id: poly
    send_all_traffic: false
    fallback_urls:
      - "https://poly.rpc.grove.city/v1/9x8y7z6w"

Field

Type

Required

Default

Description

service_id

string

Yes

The service ID for this fallback configuration. Must be a valid onchain Shannon service ID. Each service_id must be unique within the service_fallback array.

fallback_urls

string[]

Yes

Array of fallback endpoint URLs for the specified service ID. Each URL must be a valid HTTP/HTTPS endpoint.

send_all_traffic

boolean

false

Whether to send all traffic to fallback endpoints for this service, regardless of protocol endpoint health. When true, bypasses protocol endpoints entirely for this service.

Key Features:

Automatic failover: Gateway automatically switches to fallback endpoints when protocol endpoints are unavailable
Send All
Protocol bypass: Fallback endpoints bypass protocol-level validation and are sent directly to the configured URLs
Service-specific: Each service ID can have its own set of fallback endpoints

`hydrator_config` (optional)

For a full list of supported QoS service implementations, refer to the QoS Documentation.

Configures the QoS hydrator. By default, all services configured in the shannon_config sections will have QoS checks run against them.

Field

Type

Required

Default

Description

run_interval_ms

string

"10000ms"

Interval at which the hydrator will run QoS checks

max_endpoint_check_workers

integer

100

Maximum number of workers to run concurrent QoS checks against a service's endpoints

qos_disabled_service_ids

array[string]

List of service IDs to exclude from QoS checks. Will throw an error on startup if a service ID is provided that the PATH instance doesn't configure.

Manually Disable QoS Checks for a Service

To manually disable QoS checks for a specific service, the qos_disabled_service_ids field may be specified in the .config.yaml file.

Example:

hydrator_config:
  qos_disabled_service_ids:
    - "eth"

`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

3069

Port number on which the gateway server listens

max_request_header_bytes

integer

1MB

Maximum request header size in bytes

read_timeout

string

"5000ms" (5s)

Time limit for reading request data

write_timeout

string

"10000ms" (10s)

Time limit for writing response data

idle_timeout

string

"120000ms" (120s)

Time limit for closing idle connections

`logger_config` (optional)

Controls the logging behavior of the PATH gateway.

logger_config:
  level: "warn"

Field

Type

Required

Default

Description

level

string

"info"

Minimum log level. Valid values are: "debug", "info", "warn", "error"

`data_reporter_config` (optional)

Configures HTTP-based data reporting to external services like BigQuery via data pipelines (e.g., Fluentd with HTTP input and BigQuery output plugins).

data_reporter_config:
  target_url: "https://fluentd-service.example.com/http-input"
  post_timeout_ms: 5000

Field

Type

Required

Default

Description

target_url

string

Yes

HTTP endpoint URL where data will be reported (must start with http:// or https://)

post_timeout_ms

integer

10000

Timeout in milliseconds for HTTP POST operations. If zero or negative, default of 10000ms is used

Currently, only JSON-accepting data pipelines are supported as of PR #215.

Previous3_auth_config Nextpath

Was this helpful?

Config File Location (Local Development)

Config File Validation

Protocol Configuration

shannon_config (required)

full_node_config

full_node_config.grpc_config

gateway_config

service_fallback (optional)

hydrator_config (optional)

Manually Disable QoS Checks for a Service

router_config (optional)

logger_config (optional)

data_reporter_config (optional)

`shannon_config` (required)

`full_node_config`

`full_node_config.grpc_config`

`gateway_config`

`service_fallback` (optional)

`hydrator_config` (optional)

`router_config` (optional)

`logger_config` (optional)

`data_reporter_config` (optional)