Skip to main content

Shannon Cheat Sheet (30-60 min)

This guide covers setting up PATH with Pocket Network's Shannon protocol.

Shannon is in Beta TestNet as of 01/2025 and private MainNet as of 04/2025.

Table of Contents ​

0. Prerequisites​

  1. Prepare your environment by following the instructions in the environment setup guide.
  2. Install the pocketd CLI to interact with Pocket Network's Shannon Network.
tip

You can use the make install_deps command to install the dependencies for the PATH stack, including the pocketd CLI.

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

Before starting, you'll need to create and configure:

  1. An onchain Gateway: An onchain actor that facilitates (i.e. proxies) relays to ensure Quality of Service (QoS)
  2. An onchain Application: An onchain actor that pays (i.e. the API key holder) for relays

1.1 Gateway and Application Account Creation​

We strongly recommend following the App & PATH Gateway Cheat Sheet for setting up your accounts and getting a thorough understanding of all the elements.

But, if this is your first time going through the docs, you can follow the copy-pasta instructions below to get a feel for the end-to-end process.

tl;dr Copy-pasta to stake onchain Application & Gateway

Prepare a gateway stake config:

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

Prepare an application stake config:

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

Create gateway and application accounts in your keyring:

pocketd keys add gateway
pocketd keys add application

Fund the accounts by finding a link to the faucet here.

Grove employees only

You can manually fund the accounts using the pkd_beta_tx helper by following the instructions in this notion doc:

pkd_beta_tx bank send faucet_beta $(pkd keys show -a application) 6900000000042upokt
pkd_beta_tx bank send faucet_beta $(pkd keys show -a gateway) 6900000000042upokt

Stake the 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-testnet-grove-rpc.beta.poktroll.com \
 --yes

Stake the 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-testnet-grove-rpc.beta.poktroll.com \
 --yes

Delegate from the application to the gateway:

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

1.2 Application and Gateway Account Validation​

After following the instructions above, you should have keys with the names gateway and application in your keyring.

You can validate it like so:

# All accounts
pocketd keys list

# Gateway only
pocketd keys show -a gateway

# Application only
pocketd keys show -a application

2. Configure PATH for Shannon​

2.1 Generate Shannon Config​

Run the following command to generate a Shannon config at local/path/.config.yaml:

make shannon_populate_config
Command configuration

This command relies on pocketd command line interface to export the Gateway and Application address from your keyring backend.

You can set the following environment variables to override the default values:

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

2.2 Verify Configuration​

Check your config file:

cat local/path/.config.yaml

It should look similar to the following with the gateway_config filled out.

shannon_config:
  full_node_config:
    rpc_url: https://shannon-testnet-grove-rpc.beta.poktroll.com
    grpc_config:
      host_port: shannon-testnet-grove-grpc.beta.poktroll.com:443
    lazy_mode: true
  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
hydrator_config:
  service_ids:
    - "anvil"
Gateway Configuration Validation

  1. Do a manual sanity check of the addresses to ensure everything looks correct before continuing.

  2. The configuration about is set up for anvil, so ensure your application is staked for the same service id. You can verify this by running:

    pocketd query application show-application \
      $(pkd keys show -a application) \
      --node=https://shannon-testnet-grove-rpc.beta.poktroll.com

3. Run PATH in development mode​

3.1 Start PATH​

Run PATH in local development mode in Tilt by running:

make path_up

You can stop the PATH stack by running:

make path_down

3.2 Monitor PATH​

Grab a ☕

It could take a few minutes for path, guard and watch to start up the first time.

You should see an output similar to the following relatively quickly (~30 seconds):

Tilt Output in Console

Once you see the above log, visit localhost:10350 to view the Tilt dashboard.

Tilt Dashboard in Browser

4. Test Relays​

Anvil Node & Request Retries

tl;dr Retry the requests below if the first one fails.

The instructions above were written to get you to access an anvil node accessible on Pocket Network.

Since anvil is an Ethereum node used for testing, there is a chance it may not be available.

We recommend you try the instructions below a few times to ensure you can get a successful relay. Otherwise, reach out to the community on Discord.

Test Relay with curl​

Send a test relay to check the height of

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

And you should expect to see a response similar to the following:

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

Test Relay with make​

For your convenience, we have provided a few makefile helpers to test relays with curl and jq. You can find that in the makefiles/test_requests.mk file.

For example, to mimic the curl command above, you can simply run:

make test_request__shannon_service_id_header

To see all available helpers, simply run:

make help

Load Testing with relay-util​

You can use the relay-util tool to load test your relays.

The following will send 100 requests to the anvil node and give you performance metrics.

make test_request__shannon_relay_util_100
TODO: Screenshots

Add a screenshot of the output.