Skip to main content

Local PATH Walkthrough

Introduction ​

This walkthrough assumes you have gone through environment setup and have gotten either a Shannon or Morse gateway running.

It dives deeper into how to develop on PATH, run E2E tests, etc...

Running PATH​

PATH offers two deployment modes for local development:

Runs PATH with full functionality in a local Kubernetes cluster:

  • Routes through Envoy Proxy (port 3070)
  • Enables authorization, rate limiting, and service aliasing
  • Uses configs from /local directory with Kind + Tilt

Review these configurations:

  • Tiltfile: Tiltfile config file in the PATH repository
  • Values file: Values file for the local cluster in the PATH repository

2. Standalone Binary Mode​

Runs PATH without Envoy Proxy for simpler setup:

  • Connects directly to PATH Service (port 3069)
  • Disables authorization, rate limiting, and service aliasing
  • Launches the binary directly without additional services, tools or kubernetes cluster

2. Protocol Configuration​

Grove Employee Only (Sensitive Information)

Search for PATH in 1Password for a ready to use copy-pasta config file for both Morse and Shannon.

2.1 Shannon Protocol Configs​

See the Shannon Cheat Sheet and PATH Config Docs for details on configuring a Shannon gateway.

If you are comfortable updating the config file manually, then:

# Create ./e2e/.shannon.config.yaml
make prepare_shannon_e2e_config
# Update it manually

# Copy it to ./local/path/config/.config.yaml
make copy_shannon_e2e_config_to_local

2.2 Morse Protocol Configs​

See the Morse Cheat Sheet and PATH Config Docs for details on configuring a Morse gateway.

If you are comfortable updating the config file manually, then:

# Create ./e2e/.morse.config.yaml
make prepare_morse_e2e_config
# Update it manually

# Copy it to ./local/path/config/.config.yaml
make copy_morse_config_to_local

3. Envoy Proxy Configuration​

See the Envoy Walkthrough for all the details on running and configuring Envoy.

To get up and running quickly, run:

make init_envoy

We recommend choosing Option 2 (no authorization) for now as a simpler starting point.

If you wish to use an 0Auth provider (for example Auth0) to enable authorizing requests using an issued JWT, you will need to provide the AUTH_DOMAIN and AUTH_AUDIENCE values to substitute the sensitive variables in the envoy.yaml file.

If you do not wish to use an OAuth provider, simply answer no when prompted. This will allow authorizing requests with a static API key only.

3.1 Configuring Relay Authorization​

tip

Saving .gateway-endpoints.yaml will automatically stream the updated file contents to PADS (PATH Auth Data Server) in Tilt; there is no need to restart PADS.

You can view the GatewayEndpoints and update local/path/envoy/.gateway-endpoints.yaml to configure authorization for your relays.

  • endpoint_1_static_key requires an API key in the authorization header set to api_key_1 by default.
  • endpoint_3_no_auth does not require an API key in the authorization header.

For detailed information on the GatewayEndpoint data structure, including how to use a Postgres database for storing GatewayEndpoints, see the PATH Auth Data Server section of the PATH Config Docs.

4. Run the PATH Gateway​

Once your configs are in place, simply run one of the following commands:

# Tilt Mode
make path_up

# Standalone Binary Mode
make path_up_standalone

4.1 View PATH Resources in Tilt​

Regardless of which mode you choose, you should see the output below and can visit localhost:10350 in your browser to view the Tilt dashboard.

❯ make path_up
#########################################################################
### ./local/path/config/.config.yaml already exists, not overwriting. ###
#########################################################################
No kind clusters found.
Cluster 'path-localnet' not found. Creating it...
Creating cluster "path-localnet" ...
# ...
Set kubectl context to "kind-path-localnet"
You can now use your cluster with:
# ...
kubectl cluster-info --context kind-path-localnet
# ...
(space) to open the browser
(s) to stream logs (--stream=true)
(t) to open legacy terminal mode (--legacy=true)
(ctrl-c) to exit

4.2 Wait for the PATH stack to initialize​

The PATH Gateway stack may take a minute or more to initialize the first time you run it as it must download all required Docker images.

You will be able to tell it is ready when you see log output like this in the path resource in the Tilt dashboard:

{"level":"info","message":"Starting PATH using config file: /app/config/.config.yaml"}
{"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"}
{"level":"info","services count":1,"message":"Running Hydrator"}

5. Send a Relay​

You can verify that servicing relays works by sending one yourself!

warning

Requests MAY hit unresponsive nodes. If that happens, keep retrying the request a few times.

Once PATHs QoS module is mature, this will be handled automatically.

5.1 Envoy Proxy Mode with Static Key Authorization​

Authorized relays are routed through Envoy Proxy running on port 3070.

This endpoint requires an API key in the authorization 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" }'

5.2 Envoy Proxy without any Authorization​

Authorized relays are routed through Envoy Proxy running on port 3070.

This endpoint does not require an API key in the authorization 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" }'

5.3 Standalone mode without any Authorization​

Unauthorized relays are routed directly to the PATH Service, running on port 3069.

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

E2E Tests​

Assuming you prepared ./e2e/.morse.config.yaml and ./e2e/.shannon.config.yaml following the instructions above, you can run the E2E tests like so:

# Run E2E tests against Shannon Beta Testnet
make test_e2e_shannon_relay

# Run E2E tests against Morse MainNet
make test_e2e_morse_relay

# Run all tests
make test_all