PATH
Path API & Toolkit Harness
Table of Contents
- 1. Introduction
- 2. Path Releases
- 3. Quickstart
- 4. Configuration
- 5. Running PATH
- 6. E2E Tests
- Troubleshooting
- Special Thanks
- License
1. Introduction
PATH (Path API & Toolkit Harness) is an open source framework for enabling access to a decentralized supply network.
It provides various tools and libraries to streamline the integration and interaction with decentralized protocols.
1.1. Prerequisites
Deployment:
Development only:
2. Path Releases
Path releases provide a Docker image you can start using right away to bootstrap your Path gateway without the need of building your own image.
You can find:
You can pull them directly using the following command:
docker pull ghcr.io/buildwithgrove/path
3. Quickstart
3.1 Shannon Quickstart
-
Stake Apps and Gateway: Refer to the Poktroll Docker Compose Walkthrough for instructions on staking your Application and Gateway on Shannon.
-
Populate Config File: Run
make copy_shannon_config
to copy the example configuration file tocmd/.config.yaml
.Update the configuration file
cmd/.config.yaml
with your Gateway's private key & address and your delegated Application's address.*TIP: If you followed the Debian Cheat Sheet, you can run
path_prepare_config
to get you most of the way there. Make sure to review thegateway_private_key
field.* -
Start the PATH Container: Run
make path_up_build_gateway
ormake path_up_gateway
to start & build the PATH gateway. -
Run a curl command: Example
eth_blockNumber
request to a PATH supportingeth
:curl http://eth.localhost:3000/v1 \
-X POST \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber" }'
3.2 Morse Quickstart
-
Retrieve Application Authentication Token & Keys
This is a relatively manual process in Morse that is not well documented.
You should reach out to the team directly if you are doing this, but can refer to the following resources as references:
-
Populate Config File: Run
make copy_morse_config
to copy the example configuration file tocmd/.config.yaml
.Update the configuration file
cmd/.config.yaml
with your Gateway's private key, address and your delegated Application's address.2.1 If you're a Grove employee, you can use copy-paste the PROD configs from here.
2.2 If you're a community member, run the following command to get started quickly with a prefilled configuration for Bitcoin MainNet on Pocket Morse TestNet:
cp ./cmd/.config.morse_example_testnet.yaml ./cmd/.config.yaml
-
Start the PATH Container: Run
make path_up_build_gateway
ormake path_up_gateway
to start & build PATH gateway -
Run a curl command: Example
eth_blockNumber
request to a PATH supportingeth
:curl http://eth.localhost:3000/v1 \
-X POST \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber" }'
4. Configuration
4.1 Configuration File
The configuration for PATH is defined in a YAML file, which should be named .config.yaml
.
This file is required for setting up a PATH instance and must be populated with the appropriate values.
The configuration is divided into several sections:
-
Morse Configuration (
morse_config
):- Required for Morse gateways.
- Must include full node URL and relay signing key.
- Must include AAT data for all onchain staked applications assigned to the gateway operator
-
Shannon Configuration (
shannon_config
):- Required for Shannon gateways.
- Must include RPC URL, gRPC host/port, and gateway address/private key.
- Must include the addresses of the onchain Applications that are delegated to the onchain Gateway.
-
Services Configuration (
services
):- Required for all gateways; at least one service must be listed.
- The key is the Service ID (e.g.
F00C
) and the value is the service configuration. - Only the Service ID is required. All other fields are optional.
-
Router Configuration (
router_config
):- Optional. Default values will be used if not specified.
- Configures router settings such as port and timeouts.
4.2 Example Shannon Configuration Format
shannon_config:
full_node_config:
rpc_url: "https://rpc-url.io"
grpc_config:
host_port: "grpc-url.io:443"
gateway_address: "pokt1710ed9a8d0986d808e607c5815cc5a13f15dba"
gateway_private_key: "d5fcbfb894059a21e914a2d6bf1508319ce2b1b8878f15aa0c1cdf883feb018d"
delegated_app_addresses:
- "pokt1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0"
- "pokt1u2v3w4x5y6z7a8b9c0d1e2f3g4h5i6j7k8l9m0"
services:
"F00C":
alias: "eth"
4.3 Example Morse Configuration Format
# For a morse gateway, the following config is required:
morse_config:
full_node_config:
url: "https://pocket-network-full-full-node-url.io"
relay_signing_key: "example_relay_signing_key"
http_config:
retries: 3
timeout: "5000ms"
request_config:
retries: 3
signed_aats:
"example_application_address":
client_public_key: "example_application_client_public_key"
application_public_key: "example_application_public_key"
application_signature: "example_application_signature"
# services is required. At least one service must be configured with a valid id.
# All fields are optional but the id is required.
services:
"F00C":
alias: "eth"
request_timeout: "3000ms"
4.4 Other Examples
- Full example config YAML files:
- Config YAML Schema
5. Running PATH
5.1. Setup Config YAML
-
Run
make copy_shannon_config
ormake copy_morse_config
to prepare the.config.yaml
file.NOTE: For a full example of the config YAML format for both Shannon and Morse protocols, see the example config YAML files.
-
You will then need to populate the
.config.yaml
file with the appropriate values for the protocol you wish to use.⚠️ IMPORTANT: The data required to populate the
.config.yaml
file is sensitive and the contents of this file must never be shared outside of your organization. ⚠️
5.2. Start the Container
-
Once the
.config.yaml
file is populated, to start the PATH service for a specific protocol, use themake
target:make path_up
NOTE: The protocol version (
morse
orshannon
) depends on whethermorse_config
orshannon_config
is populated in the.config.yaml
file. -
Once the Docker container is running, you may send service requests to the PATH service.
By default, the PATH service will run on port
3000
. -
To stop the PATH service, use the following
make
target:make path_down
6. E2E Tests
This repository contains end-to-end (E2E) tests for the Shannon relay protocol. The tests ensure that the protocol behaves as expected under various conditions.
To use E2E tests, a make
target is provided to copy the example configuration file to the .config.test.yaml
needed by the E2E tests:
make copy_test_config
Then update the protocol.shannon_config.full_node_config
values with the appropriate values.
You can find the example configuration file here.
Currently, the E2E tests are configured to run against the Shannon testnet.
Future work will include adding support for other protocols.
6.1. Running Tests
To run the tests, use the following make
targets:
# Run all tests
make test_all
# Unit tests only
make test_unit
# Shannon E2E test only
make test_e2e_shannon_relay
Troubleshooting
Docker Permissions Issues - Need to run sudo?
If you're hitting docker permission issues (e.g. you need to use sudo), see the solution here or just copy-paste the following command:
sudo chmod 666 /var/run/docker.sock
Special Thanks
The origins of this repository were inspired by the work kicked off in gateway-server by the Nodies team. We were inspired and heavily considering forking and building off of that effort.
However, after a week-long sprint, the team deemed that starting from scratch was the better path forward for multiple reasons. These include but are not limited to:
- Enabling multi-protocol support; Morse, Shanon and beyond
- Set a foundation to migrate Grove's quality of service and data pipelineta
- Integrating with web2 standards like Envoy, gRPC, Stripe, NATS, Auth0, etc...
- Etc...
License
This project is licensed under the MIT License; see the LICENSE file for details.