Supplier & RelayMiner Cheat Sheet (~25 minutes)

🖨 🍝 with Scripted Abstractions 🍝 🖨

Stake an onchain Supplier and run an offchain RelayMiner in less than an hour, without deep explanations.

High Level Architecture Diagram

🌀 Pocket Network (Onchain)

Network State

RPC Request/Response

References

References

Signed Relay Request/Response

Suppliers

Supplier Node 1

Supplier Private Key

Supplier Node N

Supplier Private Key

🌿 Grove Gateway (Offchain)

Shannon SDK

PATH SDK

PATH Config File

Gateway Private Key

App Private Key(s)

User

Application Registry

Gateway Registry

Supplier Registry

App Config 1

App Config N

Gateway Config

20 Minute Video Walkthrough

Prerequisites

Optional Vultr Setup

The instructions on this page assume you have experience maintaining backend services.

You can reference the Vultr Playbook for a quick guide on how to set up a server with Vultr.

What will you do in this cheatsheet?

1

Stake a Supplier (onchain record)

Stake a Supplier.

2

Deploy a RelayMiner (offchain coprocessor)

Deploy a RelayMiner.

3

Serve relays

Serve relays.

4

Claim rewards

Claim rewards.

5

Submit proofs

Submit proofs.

6

Earn rewards for onchain services

Earn rewards for onchain services.

Account Setup

1

Create Supplier account

pocketd keys add supplier
2

Prepare your environment

Create the following environment variables:

cat > ~/.pocketrc << EOF
export SUPPLIER_ADDR=$(pocketd keys show supplier -a)
export TX_PARAM_FLAGS="--gas=auto --gas-prices=1upokt --gas-adjustment=1.5 --yes"
export BETA_NODE_FLAGS="--network=beta"
export BETA_NETWORK="pocket-beta"
export BETA_RPC_URL="https://shannon-testnet-grove-rpc.beta.poktroll.com"
export BETA_GRPC_URL="https://shannon-testnet-grove-grpc.beta.poktroll.com:443"
export BETA_GRPC_URL_RAW="shannon-testnet-grove-grpc.beta.poktroll.com:443"
EOF

And source them in your shell:

echo "source ~/.pocketrc" >> ~/.profile
source ~/.profile
3

Fund the Supplier account

Retrieve your Supplier address:

echo "Supplier address: $SUPPLIER_ADDR"

Fund your account by going to Shannon Beta TestNet faucet or running:

pocketd tx bank send $FUNDING_ADDR $SUPPLIER_ADDR 100000000upokt --network=beta --fees=100upokt --unordered --timeout-duration=5s --yes

Check balance:

pocketd query bank balances $SUPPLIER_ADDR $BETA_NODE_FLAGS

Supplier Configuration

For more details on supplier configurations, see the full supplier config docs.

1

Get your public URL

Retrieve your external IP:

EXTERNAL_IP=$(curl -4 ifconfig.me/ip)

Pick a public port to open (e.g. 8545):

sudo ufw allow 8545/tcp

Your supplier will be accessible at:

echo http://${EXTERNAL_IP}:8545
2

Configure your Supplier

Prepare the stake supplier config:

cat <<🚀 > /tmp/stake_supplier_config.yaml
owner_address: $SUPPLIER_ADDR
operator_address: $SUPPLIER_ADDR
stake_amount: 1000069upokt
default_rev_share_percent:
  $SUPPLIER_ADDR: 100
services:
  - service_id: "anvil" # change if not using Anvil
    endpoints:
      - publicly_exposed_url: http://$EXTERNAL_IP:8545 # must be public
        rpc_type: JSON_RPC
🚀

Replace service_id.

The example uses service_id: anvil. Use your own service_id or create a new one.

Revenue Share Update Permissions (Operator-Only Updates)

Revenue share addresses and percentages CAN ONLY be updated by the OPERATOR account.

In this example, both owner_address and operator_address are the same (custodial staking). This means the same account can update both stake amounts and revenue share configurations. For non-custodial staking, only the operator can modify revenue share settings.

3

Stake your Supplier

Submit the staking transaction:

pocketd tx supplier stake-supplier \
  --config /tmp/stake_supplier_config.yaml \
  --from=$SUPPLIER_ADDR $TX_PARAM_FLAGS $BETA_NODE_FLAGS

And check the status onchain:

pocketd query supplier show-supplier $SUPPLIER_ADDR $BETA_NODE_FLAGS
4

Suppliers staked on behalf of Owners (must read)

Make sure to read this section if your supplier WAS NOT staked by the operator.

Additional requirements for suppliers staked on behalf of owners:

Problem: Suppliers WITHOUT onchain public keys for their operators CANNOT sign Relay Responses and will be sanctioned by PATH.

Root Cause: A supplier operator may have an onchain account, but it does not necessarily mean it has an onchain public key until it signs its first onchain transaction.

Solution: Submit any onchain transaction where --from is the operator address.

Any transaction will work. For example, a small transfer:

pocketd tx bank send <your_supplier_operator_address> <some_address_you_own> 1upokt --from=<your_supplier_operator_address> ...

How to check if you have an onchain account

pocketd q auth account <your_supplier_operator_address> ...

Account without public key:

account:
  type: /cosmos.auth.v1beta1.BaseAccount
  value:
    account_number: "..."
    address: pokt1...
    sequence: "..."

Account with public key:

account:
  type: /cosmos.auth.v1beta1.BaseAccount
  value:
    account_number: "..."
    address: pokt1...
    public_key:
      type: /cosmos.crypto.secp256k1.PubKey
      value: Ap/Nr...
    sequence: "..."

RelayMiner Configuration

See RelayMiner config docs for all options.

1

(Optional) Start the anvil node

If using service_id: anvil, run a local Anvil node:

curl -L https://foundry.paradigm.xyz | bash
source ~/.foundry/bin
foundryup
anvil --port 8546

Test:

curl -X POST http://127.0.0.1:8546 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []}'
2

Configure the RelayMiner

Prepare the RelayMiner (offchain co-processor) config:

cat <<🚀 > /tmp/relayminer_config.yaml
default_signing_key_names:
  - supplier
smt_store_path: $HOME/.pocket/smt
pocket_node:
  query_node_rpc_url: $BETA_RPC_URL
  query_node_grpc_url: $BETA_GRPC_URL
  tx_node_rpc_url: $BETA_RPC_URL
suppliers:
  - service_id: "anvil" # change if not using Anvil
    service_config:
      backend_url: "http://127.0.0.1:8546" # change if not using Anvil
    listen_url: http://0.0.0.0:8545 # must match Supplier's public URL
metrics:
  enabled: false
  addr: :9090
pprof:
  enabled: false
  addr: :6060
🚀
3

Ensure the RelayMiner is funded with an onchain public key

Supplier Public Key Issue Fix

Problem: New suppliers without public keys on-chain can't validate relay responses during their first session, even after delivering claims.

Root Cause: Igniter allows staking without operator signatures, leaving suppliers without required public keys.

Solution:

  • Ensure operators sign at least one transaction before staking

  • First claim submission will set the public key on-chain

  • Monitor for suppliers missing public keys

Consequences: Session-long relay validation failures until public key is established.

Status: Fleet re-staked, monitoring solution in development.

4

Start the RelayMiner

Start the RelayMiner (offchain co-processor) server:

pocketd \
  relayminer start \
  --log_level=debug \
  --config=/tmp/relayminer_config.yaml \
  --chain-id=$BETA_NETWORK
5

Test the RelayMiner

After following the instructions in the Gateway cheatsheet, you will need a staked Application to send a relay request to your supplier assuming it is staked for the same service.

Example relay request to an Anvil (EVM) node:

pocketd relayminer relay \
  --app=$APP_ADDR \
  --supplier=$SUPPLIER_ADDR \
  --node=$BETA_RPC_URL \
  --grpc-addr=$BETA_GRPC_URL_RAW \
  --payload="{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"eth_blockNumber\", \"params\": []}"

Specifying a supplier: The request will fail if the specified supplier is not in the session at the time of the relay.

tl;dr example staking an application for anvil

Create an application:

pocketd keys add application

Fund it (faucet or other).

Prepare the stake config:

cat <<🚀 > /tmp/stake_app_config.yaml
stake_amount: 100000000upokt
service_ids:
  - "anvil"
🚀

Stake it:

pocketd tx application stake-application \
  --config=/tmp/stake_app_config.yaml \
  --from=$(pocketd keys show application -a) $TX_PARAM_FLAGS $BETA_NODE_FLAGS

Check the staking status:

pocketd query application show-application $(pocketd keys show application -a) $BETA_NODE_FLAGS
PreviousValidator Cheat Sheet (~15 min)NextGateway & Application (~30 min)

Was this helpful?