Skip to main content

Morse Cheat Sheet

This guide covers setting up PATH with the Morse protocol. In MainNet as of 01/2025.

Table of Contents ​

0. Prerequisites​

  1. Prepare your environment by following the instructions in the environment setup guide.
  2. Install the Pocket CLI: CLI for interacting with Pocket's Morse Network

1. Setup Morse Protocol Accounts​

caution

This is a manual and poorly documented process in Morse.

Application Authentication Tokens (AATs) are auth tokens that allow application clients to access the network without the need to expose their private keys. Once you have one or more valid AATs, you can populate the configuration files required to run the full PATH Gateway instance.

The following resources are also good references and starting points:

If you are unsure of where to start, you should reach out to the team directly.

1.1 AAT Generation​

We strongly recommend following the resources above.

However, assuming you have access to a staked application, you can follow the instructions below.

tl;dr Use at your own risk copy-pasta commands

Get the source code:

git clone git@github.com:pokt-network/pocket-core.git
cd pocket-core

Build your own pocket-core binary:

go build -o pocket ./app/cmd/pocket_core/main.go

Generate an AAT:

./pocket-core create-aat <ADDR_APP> <CLIENT_PUB>

Take note of the output:

{
  "version": "0.0.1",
  "app_pub_key": <APP_PUB>,
  "client_pub_key": <CLIENT_PUB>,
  "signature": <APP_SIG>
}

So you can prepare a configuration like so:

morse_config:
  # ...
  relay_signing_key: "CLIENT_PRIV"
  # ...
signed_aats:
  <ADDR_APP>:
    client_public_key: "<CLIENT_PUB>"
    application_public_key: "<APP_PUB>"
    application_signature: "<APP_SIG>"

2. Configure PATH​

2.1 Generate Morse Config​

Run the following commands to generate a Morse config at local/path/config/.config.yaml:

make prepare_morse_e2e_config # Generate ./e2e/.morse.config.yaml
make copy_morse_e2e_config_to_local # Copy to ./local/path/config/.config.yaml
# Manually update ./local/path/config/.config.yaml

Update & Verify the Configuration​

You'll need to manually update these fields in the config file:

  • url
  • relay_signing_key
  • signed_aats

And then check the updated config:

cat local/path/config/.config.yaml

3. Start PATH​

Make sure to have followed the entire environment setup guide before proceeding.

3.1 Start PATH​

Run the entire stack (PATH, Envoy, Auth Server) by running:

make path_up

Run Standalone Mode (no Envoy Proxy) by running:

make path_up_standalone

You can stop the PATH stack by running:

make path_down

3.1 Monitor PATH​

Visit localhost:10350 to view the Tilt dashboard.

Wait for initialization logs:

{"level":"info","message":"Starting PATH gateway with Shannon protocol"}
{"level":"info","message":"Starting the cache update process."}
{"level":"info","package":"router","message":"PATH gateway running on port 3069"}

4. Test Relays​

tip

The makefile helpers in makefiles/test_requests.mk can make iterating on these requests easier.

Send a relay using static key authorization (make test_request__endpoint_url_path_mode__static_key_service_id_header):

curl http://localhost:3070/v1/endpoint_1_static_key \
    -X POST \
    -H "authorization: api_key_1" \
    -H "target-service-id: anvil" \
    -d '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber" }'

Send a relay without authorization (make test_request__endpoint_url_path_mode__no_auth__service_id_header):

curl http://localhost:3070/v1/endpoint_3_no_auth \
    -X POST \
    -H "target-service-id: anvil" \
    -d '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber" }'

If you launched PATH in standalone mode (no Envoy Proxy), you can test a relay like so:

curl http://localhost:3069/v1/ \
    -X POST \
    -H "target-service-id: anvil" \
    -d '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber" }'
Retries

If a requests fail, retry a few times as you may hit unresponsive nodes

Additional Notes​

  • The Morse protocol setup process is more manual than Shannon
  • Pay close attention to field names in configuration files
  • Keep your configuration secure as it contains sensitive information
  • For troubleshooting, consult the Gateway Server Kit instructions