Skip to main content

Shannon Cheat Sheet (30-60 min)

tl;dr Set up PATH with Pocket Network's Shannon protocol

TIP: Coming from dev.poktroll.com?

Coming from the App & PATH Gateway Cheat Sheet?

Skip to 2.1 Generate Shannon Config.

NOTE: Are you a Grove 🌿 employee?
Download your configs here
  1. Download the preferred config file from 1Password:
  2. Copy to local/path/.config.yaml in your PATH repository
  3. Comment out the data_reporter_config section
  4. Comment out the owned_apps_private_keys_hex you're not using for testing
  5. Skip to section 3: Run PATH

Table of Contents ​

0. Prerequisites​

⚠️ Complete the Quick Start guide.

1. Setup Shannon Protocol Accounts (Gateway & Application)​

You will need:

  1. Gateway: Facilitates relays and ensures QoS
  2. Application: Sends and pays for relays

1.1 Gateway and Application Account Creation​

Choose one of the following flows to setup your accounts:

  1. Recommended Setup: Follow the App & PATH Gateway Cheat Sheet for complete setup.

  2. Quick Setup for first-time users:

    Copy-pasta to stake onchain Application & Gateway

    Create gateway stake config:

    cat <<EOF > /tmp/stake_gateway_config.yaml
    stake_amount: 1000000upokt
    EOF

    Create application stake config:

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

    Create accounts:

    pocketd keys add gateway
    pocketd keys add application

    Fund accounts: Use faucet links here.

    Grove employees only

    Fund using pkd_beta_tx helper (instructions):

    pkd_beta_tx bank send faucet_beta $(pocketd keys show -a application --keyring-backend=test) 6900000000042upokt
    pkd_beta_tx bank send faucet_beta $(pocketd keys show -a gateway --keyring-backend=test) 6900000000042upokt

    Stake gateway:

    pocketd tx gateway stake-gateway \
    --config=/tmp/stake_gateway_config.yaml \
    --from=gateway --gas=auto --gas-prices=200upokt --gas-adjustment=1.5 --chain-id=pocket-beta \
    --node=https://shannon-grove-rpc.mainnet.poktroll.com \
    --keyring-backend=test \
    --yes

    Stake application:

    pocketd tx application stake-application \
    --config=/tmp/stake_app_config.yaml \
    --from=application --gas=auto --gas-prices=200upokt --gas-adjustment=1.5 --chain-id=pocket-beta \
    --node=https://shannon-grove-rpc.mainnet.poktroll.com \
    --keyring-backend=test \
    --yes

    Delegate application to gateway:

    pocketd tx application delegate-to-gateway $(pocketd keys show -a gateway --keyring-backend=test) \
    --from=application --gas=auto --gas-prices=200upokt --gas-adjustment=1.5 --chain-id=pocket-beta \
    --node=https://shannon-grove-rpc.mainnet.poktroll.com \
    --keyring-backend=test \
    --yes

1.2 Account Validation​

Verify the keys are in your keyring:

# All accounts
pocketd keys list --keyring-backend=test

# Gateway only
pocketd keys show -a gateway --keyring-backend=test

# Application only
pocketd keys show -a application --keyring-backend=test

2. Configure PATH for Shannon​

2.1 Generate Shannon Config​

Generate config at local/path/.config.yaml:

make config_shannon_populate
Environment variables

Override defaults if needed:

  • POCKETD_HOME: Path to pocketd home (default $HOME/.pocketd)
  • POCKETD_KEYRING_BACKEND: Keyring backend (default test)

2.2 Manual Configuration Verification​

Check config:

cat local/path/.config.yaml

Expected format:

shannon_config:
  full_node_config:
    rpc_url: https://shannon-grove-rpc.mainnet.poktroll.com
    grpc_config:
      host_port: shannon-grove-grpc.mainnet.poktroll.com:443
    lazy_mode: false
  gateway_config:
    gateway_mode: "centralized"
    gateway_address: pokt1... # Your gateway address
    gateway_private_key_hex: "0x..." # Your gateway private key
    owned_apps_private_keys_hex:
      - "0x..." # Your application private key

2.3 Ensure onchain configuration matches​

Verify service configuration for each application:

pocketd query application show-application \
     $(pocketd keys show -a application --keyring-backend=test) \
     --node=https://shannon-grove-rpc.mainnet.poktroll.com

:::

3. Run the full PATH stack locally​

3.1 Run & Monitor PATH​

Run the following command and wait 1-2 minutes:

make path_up

Your terminal should display the following:

Terminal

Visit the Tilt dashboard at localhost:10350 and make sure everything is 🟢.

Tilt Dashboard

3.2 Check configured services​

curl http://localhost:3070/healthz | jq

4. Test Relays​

Test Relay with curl​

Assuming you have an app staked for eth, you can query eth_blockNumber.

By specifying the Target-Service-Id header:

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

Or by using the eth subdomain:

curl http://eth.localhost:3070/v1 \
 -H "Authorization: test_api_key" \
 -d '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber" }'

Expected response:

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

Load Testing with relay-util​

Send 100 requests with performance metrics:

SERVICE_ID=eth make test_request__shannon_relay_util_100

5. Stop PATH​

When you're finished testing:

make path_down