Skip to main content

PATH
Path API & Toolkit Harness

Grove logo

Static Badge GitHub Actions Workflow Status GitHub last commit GitHub go.mod Go version GitHub Release GitHub Downloads (all assets, all releases) GitHub Issues or Pull Requests GitHub Issues or Pull Requests GitHub Issues or Pull Requests App Status

Table of Contents

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.

We use Tilt + Kind to spin up local environment for development and local testing purposes.

Kind is intentionally used instead of Docker Kubernetes cluster since we have observed that images created through Tilt are not accesible when using Docker K8s cluster.

Prerequisites​

Deployment:

Development only:

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:

  • All the releases here
  • All the package versions here
  • The containers page here

You can pull them directly using the following command:

docker pull ghcr.io/buildwithgrove/path

Quickstart​

Shannon Quickstart​

See the PATH Quickstart Cheat Sheet for instructions on how to get started with a local PATH instance on Shannon.

  1. Stake Apps and Gateway: Refer to the Poktroll Docker Compose Walkthrough for instructions on staking your Application and Gateway on Shannon.

  2. Populate Config File: Run make config_shannon_localnet to copy the example configuration file to local/path/config/.config.yaml.

    Update the configuration file local/path/config/.config.yaml with your Gateway's private key & address and your 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 the gateway_private_key field.*

  3. Start the PATH Container: Run make path_up to build and start the PATH gateway in the Local development environment using Tilt.

  4. Run a curl command: Example eth_blockNumber request to a PATH supporting eth:

    curl http://eth.localhost:3000/v1/ \
        -X POST \
        -H "Content-Type: application/json" \
        -d '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber" }'

Morse Quickstart​

  1. 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:

  2. Populate Config File: Run make config_morse_localnet to copy the example configuration file to local/path/config/.config.yaml.

    Update the configuration file local/path/config/.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

  3. Start the PATH Container: Run make path_up to build and start the PATH gateway in the Local development environment using Tilt.

  4. Run a curl command: Example eth_blockNumber request to a PATH supporting eth:

    curl http://localhost:3000/v1/ \
        -X POST \
        -H "Content-Type: application/json" \
        -H "target-service-id: eth" \
        -d '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber" }'

Configuration​

The location of the configuration file may be set using the -config flag.

For example, when running the compiled PATH binary using make path_run, the configuration file will be located at ./bin/config/.config.yaml.

When running PATH in Tilt, the configuration file mount point is /app/config/.config.yaml.

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:

  1. 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

  2. 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.

  3. Router Configuration (router_config):

    • Optional. Default values will be used if not specified.
    • Configures router settings such as port and timeouts.

Running PATH​

By default, the PATH service runs without any authorization or rate limiting. This means all requests are allowed.

To enable authorization and rate limiting, you can run the PATH service with the dependencies using the make path_up target.

This will start the PATH service with all the appropriate dependencies, seen in the `docker-compose.yml file, under the Profile 2: PATH Entire Stack section.

tip

For more information about PATH's authorization and rate limiting, see the Envoy Proxy & Auth Server README.md.

Setup Config YAML​

  1. Run make copy_shannon_config or make copy_morse_config to prepare the bin/config/.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.

  2. 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. ⚠️

Run the PATH binary​

  1. Once the .config.yaml file is populated under the bin/config directory, to start the PATH service for a specific protocol, use the following make target to run path:

    make path_run
    • All requests pass through Envoy Proxy on port 3001
    • The PATH service runs on port 3000

  2. Once PATH is running, you may send service requests to it.

    By default, PATH will listen on port 3000.

  3. To stop the PATH instance, press Ctrl-C in the terminal from which the make path_run command was issued.

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.

Running the E2E tests against Shannon Testnet​

Preparing the configuration​

A make target is provided to copy the example Shannon configuration file to the e2e/.shannon.config.yaml needed by the E2E tests on Shannon.

make copy_shannon_e2e_config

Then update the shannon_config.gateway_config values with the appropriate values.

You can find the example Shannon configuration file here.

Running the E2E tests​

To run the tests, use the following make targets:

# Run E2E tests against Shannon Testnet
make test_e2e_shannon_relay

# Run all tests
make test_all

Running the E2E tests against Morse​

Preparing the configuration​

A make target is provided to copy the example Morse configuration file to the e2e/.morse.config.yaml needed by the E2E tests on Morse. To run the tests, use the following make targets:

make copy_morse_e2e_config

Then update the morse_config.full_node_config and morse_config.signed_aats values with the appropriate values.

You can find the example Morse configuration file here.

NOTE: If you are a Grove employee, download Grove's Morse configuration file for PATH E2E tests and COPY IT OVER the e2e/.morse.config.yaml file.

⚠️ IMPORTANT: The above configuration file is sensitive and the contents of this file must never be shared outside of your organization. ⚠️

Running the E2E tests​

To run the tests, use the following make targets:

# Run E2E tests against Morse
make test_e2e_morse_relay

Running Localnet​

You can use path configuration under /local to spin up a local development environment using Kind + Tilt.

Make sure to review Tiltfile and values file to make sure they have your desired configuration.

Spinning up / Tearing down Localnet​

Localnet can be spun up/torn down using the following targets:

  • path_up -> Spins up localnet environment using Kind + Tilt
  • path_down -> Tears down localnet.

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.