Skip to main content

RelayMiner config

This document describes the configuration options for the RelayMiner, a Supplier co-processor/sidecar that acts as the real server for querying request, building claims and submitting proofs.

tip

You can find a fully featured example configuration at relayminer_config_full_example.yaml.

Introduction​

The following diagram illustrates how the off-chain RelayMiner operator config (yaml) MUST match the on-chain Supplier actor service endpoints for correct and deterministic behavior.

If these do not match, the behavior is non-deterministic and could result in a variety of errors such as bad QoS, incorrect proxying, burning of the actor, etc...

Assuming that the on-chain endpoints 1 and 2 have different hosts

Usage​

The RelayMiner start command accepts a --config flag that points to a configuration yaml file that will be used to setup the RelayMiner instance.

poktrolld relayminer --config ./relayminer_config.yaml --keyring-backend test

Structure​

The RelayMiner configuration file is a yaml file that contains global options and supplier specific sections and configurations.

Global options​

default_signing_key_names: [<string>, <string>]
smt_store_path: <string>

default_signing_key_names​

Required if suppliers.*.signing_key_names is not specified.

This configuration option specifies a list of key names from the keyring that the RelayMiner will use to sign transactions. These key names are used to derive the public key and the corresponding address, which are essential for interacting with POKT. Each key name listed here must be present in the keyring used to start the RelayMiner instance.

For more details, see Configuring Signing Keys.

smt_store_path​

Required

The relative or absolute path to the directory where the RelayMiner will store the SparseMerkleTree data on disk. This directory is used to persist the SMT in a BadgerDB KV store data files.

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:

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 endpoint for troubleshooting and debugging performance issues.

Example configuration:

pprof:
  enabled: true
  addr: localhost:6060

You can learn how to use that endpoint on the Performance Troubleshooting page.

Pocket node connectivity​

pocket_node:
  query_node_rpc_url: tcp://<hostname>:<port>
  query_node_grpc_url: tcp://<hostname>:<port>
  tx_node_rpc_url: tcp://<hostname>:<port>

query_node_rpc_url​

Required

The RPC URL of the Pocket node that allows the RelayMiner to subscribe to events via websockets. It is then re-formatted as ws://<hostname>:<port>/websocket and establishes a persistent connection to the Pocket node to stream events such as latest blocks, application staking events, etc... If unspecified, tx_node_rpc_url value will be used.

query_node_grpc_url​

Optional

The gRPC URL of the Pocket node that allows the RelayMiner to query/pull data from the Pocket network (eg. Sessions, Accounts, etc...).

tx_node_rpc_url​

Required

The RPC URL of the Pocket node that allows the RelayMiner to broadcast transactions to the a Pocket network Tendermint node. It may have a different host than the query_node_rpc_url but the same value is acceptable too.

Suppliers​

The suppliers section configures the services that the RelayMiner will offer to Pocket Network. It specifies exactly where those requests will be forwarded to by the Supplier's infrastructure.

Each suppliers entry's service_id MUST reflect the on-chain Service.Id the supplier staked for. In addition, the publicly_exposed_endpoints list MUST contain the same endpoints that the Supplier advertised on-chain when staking for that service.

At least one supplier is required for the RelayMiner to be functional.

suppliers:
  - service_id: <string>
    listen_url: <enum{http}>://<host>
    service_config:
      backend_url: <url>
      authentication:
        username: <string>
        password: <string>
      headers:
        <key>: <value>
      publicly_exposed_endpoints:
        - <host>

service_id​

Required, Unique

The Id of the service which will be used as a unique identifier to reference a service provided by the Supplier and served by the RelayMiner instance.

It MUST match the Service.Id specified by the supplier when staking for the service.

signing_key_names​

Required if default_signing_key_names is empty.

This option specifies the list of signing key names specific to a supplier. If a supplier does not provide its own signing_key_names, the RelayMiner will use the default_signing_key_names.

For more details, see Configuring Signing Keys.

listen_url​

Required

The address on which the RelayMiner will start a server to listen for incoming requests. The server type is inferred from the URL scheme (http, https, etc...).

The same listen_url can be used for multiple suppliers and/or different publicly_exposed_endpoints, the RelayMiner takes care of routing the requests to the correct backend_url based on the service_id and the publicly_exposed_endpoints it received a request form.

service_config​

Required

The service_config section of the supplier configuration is a set of options that are specific to the service that the RelayMiner will be offering to the Pocket network.

backend_url​

Required

The URL of the service that the RelayMiner will forward the requests to when a relay is received, also known as data node or service node. It MUST be a valid URL (not just a host) and be reachable from the RelayMiner instance.

authentication​

Optional

The authentication section of the supplier configuration is a pair of username and password that will be used by the basic authentication mechanism to authenticate the requests that are forwarded to the service.

headers​

Optional

The headers section of the supplier configuration is a set of key-value pairs that will be added to the request headers when the RelayMiner forwards the requests to the service. It can be used to add additional headers like Authorization: Bearer <TOKEN> for example.

publicly_exposed_endpoints​

Required, Unique within the supplier's publicly_exposed_endpoints list

The publicly_exposed_endpoints section of the supplier configuration is a list of hosts that the RelayMiner will accept requests from. It MUST be a valid host that reflects the on-chain supplier staking service endpoints.

It is used to determine if the incoming request is allowed to be processed by the server listening on listen_url host address as well as to check if the request's RPC-Type matches the on-chain endpoint's RPC-Type.

note

The service_id of the supplier is automatically added to the publicly_exposed_endpoints list as it may help troubleshooting the RelayMiner and/or send requests internally from a k8s cluster for example.

Why should one supplier have multiple publicly_exposed_endpoints?​

There are various reasons to having multiple publicly_exposed_endpoints for the same supplier service.

  • The on-chain Supplier may provide the same Service on multiple domains (e.g. for different regions).
  • The operator may want to route requests of different RPC types to the same server
  • Migrating from one domain to another. Where the operator could still accept requests on the old domain while the new domain is being propagated.
  • The operator may want to have a different domain for internal requests.
  • The on-chain Service configuration accepts multiple endpoints.

Configuring Signing Keys​

RelayMiner expects the addresses with signing keys to be staked before running a RelayMiner.

There are two ways to configure signing keys for RelayMiner: globally using default_signing_key_names or individually for each supplier using signing_key_names.

  1. Global Configuration (default_signing_key_names)
  • Provides a default list of key names used by all suppliers unless overridden.
  • Useful for ensuring a base level of configuration and simplicity.
  1. Supplier-specific Configuration (signing_key_names)
  • Allows each supplier to have its own set of signing key names.
  • Provides flexibility and granular control over key management.

In summary, use default_signing_key_names for a robust fallback and simplified setup. Use signing_key_names for greater control and security tailored to individual suppliers.

Example Configuration​

default_signing_key_names:
  - keyname1
  - keyname2
suppliers:
  # RelayMiner will only provide service for `llm-model` using `keyname3` and `keyname4` keys.
  - service_id: llm-model
    signing_key_names:
      - keyname3
      - keyname4
    # ... the rest of the config

  # RelayMiner will only provide service for `etherium-mainnet` using `keyname1` and `keyname2` keys.
  - service_id: etherium-mainnet
    # ... the rest of the config
note

Multiple RelayMiners can be configured with the same signing keys to sign RelayResponses and submit Claims and Proofs transactions to the Pocket network. (e.g. This is useful for a Supplier that is willing to provide redundant or geographically distributed services.)

Supported server types​

The list of supported server types can be found at pkg/relayer/config/types.go