Walkthrough

The goal of this document is to get you up and running with a LocalNet, some manually deployed local actors, and sending an end-to-end relay. It will not go in depth into any concepts.

Create a new GitHub issue here if you encounter any problems.

1

Install Dependencies

Install the following dependencies:

If you've followed the LocalNet instructions, you may already have them installed.

2

Launch & Inspect LocalNet

This section helps you deploy a POKT LocalNet in a k8s cluster on your machine and inspect it.

You will manually configure a few actors to run in your shell for visibility into onchain and offchain actors. For dynamic scaling use localnet.

See actor docs: https://dev.poktroll.com/protocol/actors/actors

Example Tilt LocalNet View:

Tilt LocalNet View

Clone the poktroll repository

git clone https://github.com/pokt-network/poktroll.git pocket
cd pocket

See helper commands in Makefile

Run:

make help

You can also view the Makefile: https://github.com/pokt-network/poktroll/blob/main/Makefile

Prepare your development environment

Install Go dependencies:

make install_ci_deps

Compile protobufs, generate mocks and run tests:

make go_develop_and_test

Re-run tests (skip regen):

make test_all

Start up LocalNet

Bring up LocalNet and wait a few minutes:

make localnet_up

The make localnet_up target runs make k8s_kind_up which:

  • Creates a new kind cluster named pocket-localnet (kubectl context = kind-pocket-localnet).

  • Creates all namespaces required by the PATH Helm Charts.

To fully stop your LocalNet:

  • Exit the Tilt shell with Ctrl+C

  • Run make localnet_down to stop Tilt

  • Run kind delete cluster --name pocket-localnet to delete the kind cluster

Visit the Tilt UI at http://localhost:10350 and wait until containers are green.

Default LocalNet ports:

  • Tilt UI: http://localhost:10350

  • Grafana: http://localhost:3003

  • PATH Gateway (JSON-RPC): http://localhost:3069/v1

  • PATH Gateway (REST): http://localhost:3070/v1/

  • Anvil (ETH dev node): http://localhost:8547

  • CometBFT RPC (Pocket node): http://localhost:26657/status

  • Cosmos gRPC (Pocket node): grpc://localhost:9090

You won't be able to send a relay yet — continue the guide. If in a hurry, look for the acc_initialize_pubkeys step.

View Grafana Logs

Each actor has a Grafana dashboard. Example: RelayMiner Tilt UI -> Grafana dashboard:

Tilt RelayMiner
Grafana RelayMiner

Check blockchain status

Using pocketd:

pocketd status --network=local | jq

CometBFT status:

curl -s -X POST localhost:26657/status | jq

Latest block:

curl -s -X POST localhost:26657/block | jq

Example: get chain height:

curl -s -X POST localhost:26657/block | jq '.result.block.last_commit.height'
3

Fund New Accounts

We'll create shannon_supplier and shannon_application.

Create a Shannon Supplier account

List built-in accounts:

make ignite_acc_list

Create an account:

ignite account create shannon_supplier \
  --keyring-dir=./localnet/pocketd \
  --keyring-backend test

Export its address (example):

export SHANNON_SUPPLIER=pokt1rgaqf6kz655qktrjenqy6zjx97zgr8ghx8q7xu
Accounts

Create a Shannon Application account

ignite account create shannon_application \
  --keyring-dir=./localnet/pocketd \
  --keyring-backend test

Export its address (example):

export SHANNON_APPLICATION=pokt1s6cupe8uj4lwdn6dt5azjv9vm4x3mtt8aek0g2

Fund your Supplier account

Check balance:

make acc_balance_query ACC=$SHANNON_SUPPLIER

Send uPOKT from faucet:

pocketd \
  tx bank send \
  faucet $SHANNON_SUPPLIER 420000000000069upokt \
  --network=local \
  --home=./localnet/pocketd

Verify balance:

# should show amount 420000000000069

Fund your Application account

Send funds:

pocketd \
  tx bank send \
  faucet $SHANNON_APPLICATION 420000000000069upokt \
  --network=local \
  --home=./localnet/pocketd

Check balance:

make acc_balance_query ACC=$SHANNON_APPLICATION
4

Manually Stake a Supplier & Deploy a RelayMiner

This section walks through staking a Supplier and running a RelayMiner.

View existing suppliers

make supplier_list

You should see a default supplier; your SHANNON_SUPPLIER will not be listed yet.

Prepare your backend data node

LocalNet runs an anvil service (local Ethereum dev node). Verify it's running:

curl http://localhost:8547 \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}'

Expected response:

{ "jsonrpc": "2.0", "id": 1, "result": "0x61" }

If you prefer a prod node, you can provision one at https://www.grove.city/

Create a Supplier configuration

Example config:

cat <<🚀 >> shannon_supplier_config.yaml
owner_address: pokt1h04g6njyuv03dhd74a73pyzeadmd8dk7l9tsk8
operator_address: pokt1h04g6njyuv03dhd74a73pyzeadmd8dk7l9tsk8
stake_amount: 1000069upokt
services:
  - service_id: anvil
    endpoints:
      - publicly_exposed_url: http://localhost:6942
        rpc_type: JSON_RPC
🚀

See supplier configs: https://dev.poktroll.com/operate/configs/supplier_staking_config

Stake the new Supplier

pocketd \
  tx supplier stake-supplier \
  --config shannon_supplier_config.yaml \
  --keyring-backend test \
  --from shannon_supplier \
  --network=local \
  --home=./localnet/pocketd \
  --yes

Verify:

pocketd query supplier show-supplier $SHANNON_SUPPLIER --network=local

Prepare the RelayMiner configuration

Example RelayMiner config:

cat <<🚀 >> shannon_relayminer_config.yaml
default_signing_key_names: [ "shannon_supplier" ]
smt_store_path: /home/pocket/.pocket/smt
metrics:
  enabled: true
  addr: :9999
pocket_node:
  query_node_rpc_url: tcp://127.0.0.1:26657
  query_node_grpc_url: tcp://127.0.0.1:9090
  tx_node_rpc_url: tcp://127.0.0.1:26657
suppliers:
  - service_id: anvil
    listen_url: http://localhost:6942
    service_config:
      backend_url: http://localhost:8547
pprof:
  enabled: false
  addr: localhost:6060
🚀

See relayminer configs: https://dev.poktroll.com/operate/configs/relayminer_config

Start the RelayMiner locally

Run in a dedicated shell:

pocketd relayminer start \
  --config ./shannon_relayminer_config.yaml \
  --chain-id=pocket \
  --keyring-backend test \
  --home=./localnet/pocketd

Leave it running. Re-export SHANNON_APPLICATION and SHANNON_SUPPLIER in new shells if needed.

5

Manually Stake an Application & Deploy a PATH Gateway

This shows deploying a PATH Gateway in Centralized mode (uses its configured Application accounts to sign relays).

Other gateway types (e.g. Delegated) are outside the Quickstart scope.

View existing applications

make app_list

Create an Application configuration

Example:

cat <<EOF >> shannon_app_config.yaml
stake_amount: 1000069upokt
service_ids:
 - anvil
EOF

See app staking config docs: https://dev.poktroll.com/operate/configs/app_staking_config

Stake the new Application

pocketd --home=./localnet/pocketd \
  tx application stake-application \
  --config shannon_app_config.yaml \
  --keyring-backend test \
  --from shannon_application \
  --network=local \
  --yes

Verify:

pocketd query application show-application $SHANNON_APPLICATION --network=local

You can also run make app_list to see the application listed.

Apps

Prepare the PATH Gateway configuration

See PATH Gateway configs: https://path.grove.city/operate

6

Send A Relay

Once the Application is staked, PATH Gateway and RelayMiner running, and Supplier staked, you can send a relay.

You must run make acc_initialize_pubkeys before sending a relay so public keys are initialized correctly. This is required for the Shannon SDK to query account info (part of relay signing).

Ensure POCKET_NODE in your shell is set to http://localhost:26657. See x/auth docs for public key storage: https://docs.cosmos.network/main/build/modules/auth

Send a relay on Shannon

Example curl to PATH Gateway:

curl http://localhost:3070/v1 \
    -H "Authorization: test_api_key" \
    -H "Target-Service-Id: anvil" \
    -H "App-Address: pokt1mrqt5f7qh8uxs27cjm9t7v9e74a9vvdnq5jva4" \
    -d '{"jsonrpc":"2.0","method":"eth_blockNumber","id":1}

Expected response:

{"jsonrpc":"2.0","id":1,"result":"0x61"}

If you get an error like:

{
  "id": 1,
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Failed to receive any response from endpoints. This could be due to network issues or high load. Please try again.",
    "data": {
      "retryable": "true"
    }
  }
}

You probably forgot to run make acc_initialize_pubkeys.

quickstart_full_relay

What just happened?

A Relay Request/Response flow:

  • User (curl) -> PATH Gateway -> RelayMiner -> ETH Node (Anvil) -> RelayMiner -> PATH Gateway -> User

(Sequence: eth_blockNumber request -> POKT relay request -> eth_blockNumber forwarded to node -> result returned through relays back to user.)

What will happen later?

Protocol lifecycle (intuitive summary):

  • RelayMiner creates claims for relays served

  • Submit proofs, burn delegated POKT, mint new POKT, update onchain records for Applications and Suppliers

See: https://dev.poktroll.com/protocol/primitives/claim_and_proof_lifecycle

Stake additional suppliers (without RelayMiners)

Use provided helpers:

make supplier2_stake
make supplier3_stake

make supplier_list should show three staked suppliers.

You can reuse the PATH Gateway. Expect occasional failures for non-performant suppliers.

Example test curl:

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://anvil.localhost:3000/v1

Inspect logs

Use Tilt or Grafana to inspect logs. Filter for "Supplier" in Grafana or Tilt.

Grafana explore example: http://localhost:3003/explore?... (use supplied dashboard/query in your environment)

Grafana Supplier Logs
Tilt Supplier Logs
7

Dynamically Scaling LocalNet

You can dynamically scale actors in LocalNet by changing one line in the LocalNet configuration. See the LocalNet tutorial: https://dev.poktroll.com/develop/networks/localnet

8

Explore the tools

Primary tools:

  • pocketd — the POKT Node CLI

  • make — helper commands

  • ignite — manage local k8s cluster

These tools are extensive; you'll likely need only subsets day-to-day.

E2E Tests

Run end-to-end tests (Cucumber & Gherkin):

make test_e2e

pocketd

Explore commands:

pocketd --help
pocketd query --help
pocketd tx --help

Makefile

Run make to see available helpers.

Ignite

Run ignite --help to explore commands.

PreviousDeveloper Guide NextDebugging Tips

Was this helpful?