PATH Cheat Sheet
This guide provides quick reference (i.e. a cheat sheet leveraging lots of helpers) for setting up and running a local PATH instance in Tilt. If you'd like to understand all the underlying details, please refer to the PATH Introduction.
- These instructions are intended to run on a Linux machine.
- TODO_TECHDEBT(@olshansk): Adapt the instructions to be macOS friendly.
- The following instructions are specific to setting up a
PATH
instance onShannon
.- TODO_TECHDEBT(@commoddity): Adapt the instructions to include a Morse example.
Table of Contents â
1. Prerequisitesâ
1.1 Clone the PATH
Repositoryâ
git clone https://github.com/buildwithgrove/path.git
cd ./path
1.2 Install Dependenciesâ
The following tools are required to start a local PATH instance in Tilt:
A script is provided to install the dependencies to start a PATH instance in Tilt.
make install_deps
This will check if the required tools are installed and install them if they are not.
1.3 Setup Shannon Accountâ
Before starting a PATH instance, you will need to set up both a Gateway and Application account on Shannon.
For a quick and easy way to set up your Shannon accounts, see the Account Setup section of the Gateway cheat sheets.
2. Populate Required Config Filesâ
Assuming you have followed the instructions above, the following should be true:
- You have created, funded and staked a
Gateway
. - You have created, funded and staked a
Application
. - You have delegated the staked
Application
to the stakedGateway
.
Now you can populate the configuration files required to run the full PATH Gateway
instance.
2.1 Populate the PATH
config YAML fileâ
Run the following command to generate a default Shannon config in local/path/config/.config.yaml
using the values from your Gateway
and Application
accounts:
make shannon_populate_config
You'll be prompted to confirm the Gateway
account private key export. Say Yes.
When you're done, run the following command to view your updated config file:
cat local/path/config/.config.yaml
It should look something like this:
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: false
gateway_config:
gateway_mode: centralized
gateway_address: pokt1...
gateway_private_key_hex: { REDACTED }
owned_apps_private_keys_hex:
- { REDACTED }
services:
"anvil":
alias: "eth"
Pre-prepare a handful of apps/gateways to get users started EVEN faster.
2.2 Populate the Envoy Proxy
config filesâ
Run the following command to generate the 4 Envoy config files:
make init_envoy
You can view them by running the following command:
cat local/path/envoy/.allowed-services.lua
cat local/path/envoy/.envoy.yaml
cat local/path/envoy/.ratelimit.yaml
cat local/path/envoy/.gateway-endpoints.yaml
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. Run the PATH
Gatewayâ
Start the PATH
Gateway by running the following command:
make path_up
You should see the following output:
⯠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" ...
â Ensuring node image (kindest/node:v1.31.2) đŧ
â Preparing nodes đĻ
â Writing configuration đ
â Starting control-plane đšī¸
â Installing CNI đ
â Installing StorageClass đž
Set kubectl context to "kind-path-localnet"
You can now use your cluster with:
kubectl cluster-info --context kind-path-localnet
Thanks for using kind! đ
Switched to context "kind-path-localnet".
Checking if secret 'path-config-local' exists...
Secret 'path-config-local' not found. Creating it...
secret/path-config-local created
Tilt started on http://localhost:10350/
v0.33.21, built 2024-11-08
(space) to open the browser
(s) to stream logs (--stream=true)
(t) to open legacy terminal mode (--legacy=true)
(ctrl-c) to exit
You can visit localhost:10350 in your browser to view the Tilt dashboard, which allows you to view the log output for all running containers.
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 3000"}
{"level":"info","services count":1,"message":"Running Hydrator"}
Once the PATH Gateway
container is ready, you can send a relay to test.
4. Send a Relayâ
Check that the PATH Gateway
is serving relays by running the following command yourself:
4.1 Endpoint with Static Key Authorizationâ
curl http://localhost:3001/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" }'
4.2 Endpoint with No Authorizationâ
curl http://localhost:3001/v1/endpoint_3_no_auth \
-X POST \
-H "target-service-id: anvil" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber" }'
The GatewayEndpoint
IDs endpoint_1_static_key
and endpoint_3_no_auth
, as well as the API key api_key_1
are defined in the local/path/envoy/.gateway-endpoints.yaml
file.
To add or modify the GatewayEndpoints
that are authorized to use your PATH instance, you may modify this file.
Saving this file will trigger a hot-reloading of the PATH Auth Data Server (PADS) resource in Tilt.
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 Auth README.md.
Requests MAY hit unresponsive nodes. If that happens, keep retrying the request a few times.
Once PATH
s QoS module is mature, this will be handled automatically.