LocalNet

LocalNet

This document walks you through launching a LocalNet that brings up a k8s cluster with a Data Availability network, a validator, Pocket actors and everything else needed to send an end-to-end relay.

Run Pocket Network locally

Report issues

If you encounter any problems, please create a new GitHub Issue here.

TL;DR

1

Install dependencies:

• Ignite

• Docker

• Kind

• Helm

• Tilt (note: we recommend using Kind cluster with Tilt)

2

Run:

make localnet_up

to start the network.

3

When prompted, press space to see the web UI with logs and current status of the network. Alternatively, open:

http://localhost:10350/

---

Developing with LocalNet

localnet_config.yaml

Once LocalNet is started, a new file localnet_config.yaml is generated in the root directory of the repository. This file contains the configuration of the network. It looks like this:

helm_chart_local_repo:
  enabled: false
  path: ../helm-charts
relayers:
  count: 1

Scaling network actors

To scale the number of actors, edit the localnet_config.yaml file and change the count of the relayers.

For example:

helm_chart_local_repo:
  enabled: false
  path: ../helm-charts
relayers:
-   count: 1
+   count: 2

You may need up to 1 minute for the new actors to be registered and deployed locally.

Offchain actors configuration

LocalNet uses Helm charts for configuring services. Default values are defined in each service chart's values.yaml. Example: the RelayMiner values.yaml in the helm-charts repository:

https://github.com/pokt-network/helm-charts/blob/main/charts/relayminer/values.yaml

Local infrastructure requires overrides to some defaults (for example to configure RelayMiner or PATH Gateway). These overrides live in the pocket/localnet/kubernetes directory:

https://github.com/pokt-network/poktroll/tree/main/localnet/kubernetes

If you need to change LocalNet configs, check that directory.

Modify Kubernetes workloads

Local cluster depends on the latest helm charts from:

https://github.com/pokt-network/helm-charts.git

To modify Kubernetes resources locally:

1. Clone the helm charts locally:

cd .. && git clone [email protected]:pokt-network/helm-charts.git
cd -

1. Update the path of the helm charts to the relative path of the cloned repository:

sed -i'' -e '/helm_chart_local_repo:/,/path:/ s|\(path: \).*|\1../helm-charts|' localnet_config.yaml

1. Set the helm_chart_local_repo.enabled flag in localnet_config.yaml to true:

sed -i'' -e '/helm_chart_local_repo:/,+1 s/\(enabled: \)true/\1false/; /helm_chart_local_repo:/,+1 s/\(enabled: \)false/\1true/' localnet_config.yaml

You can set it back to false with:

sed -i'' -e '/helm_chart_local_repo:/,+1 s/\(enabled: \)false/\1true/; /helm_chart_local_repo:/,+1 s/\(enabled: \)true/\1false/' localnet_config.yaml

---

Observability

You can configure LocalNet to deploy third-party observability tools such as Prometheus and Grafana by enabling observability in localnet_config.yaml:

observability:
  enabled: true

Access dashboards with graphs and logs

Each service in Tilt has a link to its own Grafana dashboard (RelayMiner, Validator, PATH Gateway, etc).

Example

How to update and save an existing dashboard?

1

Make the necessary modifications in the Grafana UI.

2

Click the save button. This will display the updated JSON output of the dashboard.

3

Copy-paste the output to the corresponding file in localnet/grafana-dashboards.

Example

---

High-level overview of LocalNet

This section describes how LocalNet operates and the interactions between different components to provision a working network.

LocalNet Deployment Flow

After you execute make localnet_up, many things happen. Overview:

1

ignite CLI provisions a new genesis.json and validator keys.

2

tilt starts and runs a Tiltfile — a Python-like script.

3

The logic in the Tiltfile executes various CLI commands, communicates with the k8s API, and creates or reads the LocalNet configuration file:

• Creates a new localnet_config.yaml if it doesn't exist. Updates it with default values if new ones are introduced.

• Depending on localnet_config.yaml, uses Helm charts from the local helm-charts repository or downloads Helm charts from the Helm chart repository at https://pokt-network.github.io/helm-charts/.

• Compiles the pocketd binary from source.

• Using values from localnet_config.yaml, provisions an observability stack (Grafana, Prometheus, Loki), a validator, PATH Gateways, RelayMiners, etc.

4

With make localnet_up continually running, tilt monitors for code changes and re-compiles the binary when code changes are detected. After the new binary is built it is pushed to containers and processes restart.

---

Troubleshooting

Clean Slate (Nuclear Option)

If you're encountering weird issues and need to start over, run:

make localnet_down
kind delete cluster --name pocket-localnet
make docker_wipe
make go_develop_and_test
kind create cluster --name pocket-localnet
make localnet_up

---