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 (i.e. SupplierOperator). 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

Payable Proof Submissions​

Overview​

Submitting Proofs requires the payment of a fee, which is defined by the proof_submission_fee governance parameter.

This fee mechanism is designed to prevent spam attacks (e.g., Sybil bloat attacks) by discouraging invalid or unnecessary Proofs.

Since Proofs are the most block space-consuming primitive in the Pocket Network, this fee plays a crucial role in maintaining the integrity of the network.

Key Requirements for Operators​

Due to the probabilistic nature of the Proof requirement, Supplier operators must ensure that they maintain sufficient funds to cover the submission fees for all Proofs associated with the Claims they plan to submit.

Failure to maintain adequate funds can result in missed submissions, which can result in Supplier slashing if the Proof is required.

Recommendations for Supplier Operators​

  • Sufficient Balance: Operators should regularly check their account balance and ensure they have enough funds to cover the submission fees for Proofs.

The following command can be used to check the balance of a Supplier operator:

poktrolld query bank balance <supplier_operator_address> upokt --node https://shannon-testnet-grove-seed-rpc.poktroll.com

Which output would look like:

balance:
  amount: "109999000"
  denom: upokt
  • Automated Monitoring: It is highly recommended to implement balance monitoring or alert systems to avoid running out of funds during critical periods.
  • Cost Awareness: Operators should familiarize themselves with the current proof_submission_fee and plan their funding accordingly, especially if they anticipate submitting a higher volume of Proofs.

The following command can be used to check the current proof_submission_fee:

poktrolld query proof params --node https://shannon-testnet-grove-seed-rpc.poktroll.com

Which output would look like:

  proof_submission_fee:
    amount: "1000000"
    denom: upokt

The list of Proof governance parameters can be found at proto/proof/params.proto

warning

If you submit a claim but do not submit its corresponding proof, this could result in SLASHING!

Having insufficient funds could lead to rejected Proof submissions . This can disrupt the operator’s participation in the Pocket Network. To maintain a smooth operation, avoid being slashed, and earn your rewards, operators must plan and manage their account balance as part of their operational procedures.