Skip to main content

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.

Table of Contents ​

High Level Architecture Diagram​

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 (i.e. onchain record)
  2. Deploy a RelayMiner (i.e. offchain coprocessor)
  3. Serve relays
  4. Claim rewards
  5. Submit proofs
  6. 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"

And source them in your shell:

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

3. Fund the Supplier account​

  1. Retrieve your Supplier address:

    echo "Supplier address: $SUPPLIER_ADDR"

  2. Fund your account by going to Shannon Beta TestNet faucet.

  3. Check balance:

    pocketd query bank balances $SUPPLIER_ADDR $BETA_NODE_FLAGS
🌿 Grove employees only
pkd helpers
# Fund your account
pkd_beta_fund $SUPPLIER_ADDR

# Check balance
pkd_beta_query bank balances $SUPPLIER_ADDR

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.

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​

Critical must read for suppliers staked on behalf of owners

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.

(Optional) Start the anvil node​

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

How to run Anvil
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": []}'

1. Configure the RelayMiner​

Prepare the RelayMiner (i.e. the 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
🚀

2. Ensure the RelayMiner is funded with an onchain public key​

The RelayMiner is responsible

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.

3. Start the RelayMiner​

Start the RelayMiner (i.e. the offchain co-processor) server:

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

4. 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:

The following is an example of a relay request to an Anvil (i.e. EVM) node:

pocketd relayminer relay \
  --app=$APP_ADDR \
  --supplier=$SUPPLIER_ADDR \
  --node=$BETA_RPC_URL \
  --grpc-addr=$BETA_GRPC_URL_RAW \
  --grpc-insecure=false \
  --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