Skip to main content



The goal of this document is to get you up and running with a LocalNet, some manually deployed local actors, and sending an end-to-end relay. It will not go in depth into any concepts.

Create a new GitHub issue here if you encounter any problems.

Video Walkthrough

You can access the video here.

0. Install Dependencies

Install the following dependencies:

  1. Golang - The programming language we use to implement the protocol
  2. Docker - Containerization tool
  3. Ignite - Cosmos SDK CLI for building and deploying blockchains
  4. Kind - k8s local cluster manager
  5. Helm - k8s configuration and automation tool
  6. Tilt - k8s local development tool & environment manager

If you've followed the LocalNet instructions, you may already have them installed.

1. Launch & Inspect LocalNet

This section will help you deploy a POKT LocalNet in a k8s cluster on your machine and inspect it so you have an idea of what's going on!

We'll be manually configuring a few actors to run in your shell for the sake of the tutorial so you have visibility into the types of on-chain and off-chain actors. In practice, you should be using localnet to dynamically scale your actors.

To learn more about the different actors type, see the docs here.

It should look something like this once you're past the first section:

Tilt LocalNet View

1.1 Clone the poktroll repository

git clone
cd poktroll

1.2 See all the available helper commands in Makefile

We leverage the Makefile to abstract the complexity of some common commands, but you can view it directly to see what the underlying command being executed is.

make help

If you run make help from the root of the repo, you'll see a list of all the available commands. Looking inside the Makefile is a great way to learn how to use them!

1.3 Prepare your development environment

Compile protobufs, generate mocks and verify that all tests are passing by running:

make go_develop_and_test

There are some flaky tests, so you can re-run with the following command without needing to regenerate the mocks and types:

make test_all

1.4 Create a k8s cluster

Create a new k8s cluster for your LocalNet:

kind create cluster

If you use k8s for other things, you may need to switch your context as well:

kubectl config use-context kind-kind

1.5 Start up LocalNet

Bring up your LocalNet and wait a few minutes:

make localnet_up

Visit localhost:10350 and wait until all the containers are 🟢

If everything worked as expected, your screen should look similar to the following:

1.6 View Grafana Logs

Every actor has a local grafana dashboard associated with it.

For example, if you visit the RelayMiner Tilt UI, you can click in the top left corner to view its grafana dashboard.

Tilt RelayMiner

Grafana RelayMiner

1.7 Check the status of the blockchain

You can query the status of the blockchain using poktrolld by running:

poktrolld status --node=tcp:// | jq

Alternatively, you use the CometBFT status directly at:

curl -s -X POST localhost:26657/status | jq

Or at latest block at:

curl -s -X POST localhost:26657/block | jq

For example, you can get the height of the blockchain by visiting the Validator Grafana Dashboard or from the CLI like so:

curl -s -X POST localhost:26657/block | jq '.result.block.last_commit.height'

2. Fund New Accounts

This section will help you fund a few accounts that we'll use below. We're going to create a shannon_supplier and shannon_application, but a dedicated gateway is outside the scope of this guide.

2.1 Create a Shannon Supplier Account

List all the accounts we get out of the box by running:

make ignite_acc_list

And create a new account named shannon_supplier by running:

ignite account create shannon_supplier \
--keyring-dir=./localnet/poktrolld \
--keyring-backend test

If you re-run make ignite_acc_list, you should now see shannon_supplier in the list.

Make sure to note its address under the Address column and export it as an environment variable for convenience. For example:

export SHANNON_SUPPLIER=pokt1rgaqf6kz655qktrjenqy6zjx97zgr8ghx8q7xu


2.2 Create a Shannon Application Account

Let's do the same thing for a shannon_application:

ignite account create shannon_application \
--keyring-dir=./localnet/poktrolld \
--keyring-backend test
export SHANNON_APPLICATION=pokt1s6cupe8uj4lwdn6dt5azjv9vm4x3mtt8aek0g2

2.3 Fund your Supplier Account

Query your supplier's balance by running:

make acc_balance_query ACC=$SHANNON_SUPPLIER

And you should see an empty balance:

~ Balances ~
balances: []
pagination: {}

~ Spendable Balances ~
Querying spendable balance for pokt1h04g6njyuv03dhd74a73pyzeadmd8dk7l9tsk8
balances: []
pagination: {}

But if you look in our genesis file (./localnet/poktrolld/config/genesis.json) you'll find that you actually have direct access to the faucet!

You can send some uPOKT to your shannon_supplier by running:

poktrolld \
tx bank send \
faucet $SHANNON_SUPPLIER 420000000000069upokt \
--node tcp:// \

And you'll find that shannon_supplier is now rolling in POKT:

- amount: "420000000000069"
denom: upokt
next_key: null
total: "0"

2.4 Fund your Application Account

Let's do the same thing for the shannon_application:

poktrolld \
tx bank send \
faucet $SHANNON_APPLICATION 420000000000069upokt \
--node tcp:// \

And make sure to check its balance again:

make acc_balance_query ACC=$SHANNON_APPLICATION

3. Manually Stake a Supplier & Deploy a RelayMiner

As we mentioned earlier, if you want to understand the different on-chain actors and off-chain operators in POKT Network, look at the docs here.

If you just want to follow instructions to make things work and get your hands dirty, keep reading.

3.1 View existing suppliers

You can run the following command to see all the suppliers available in the network:

make supplier_list

You'll find that we have a default supplier, but SHANNON_SUPPLIER won't be there yet.

3.2 Preparing your backend data node

We need a blockchain node (i.e. a backend data node) backend data node to configure a supplier. Since LocalNet is already has a running anvil service, we can re-use that as our backend.

anvil is a local Ethereum development node that's equivalent to "running your own ETH node". It's a great way to test.

You can verify the anvil node is running with the following curl:

curl http://localhost:8547 \
-H "Content-Type: application/json" \
--data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}'
{ "jsonrpc": "2.0", "id": 1, "result": "0x61" }
Grove's Prod Endpoints

If you'd prefer to use a real blockchain node with production data for testing, you can provision one at and use it below.

3.3 Create a Supplier configuration

You can learn more about our supplier configs here.

The following is an example config to get you started:

cat <<EOF >> shannon_supplier_config.yaml
stake_amount: 1000069upokt
- service_id: anvil
- publicly_exposed_url: http://localhost:6942
rpc_type: JSON_RPC

3.4 Stake the new Supplier

Stake the shannon_supplier on-chain:

poktrolld \
tx supplier stake-supplier \
--config shannon_supplier_config.yaml \
--keyring-backend test \
--from shannon_supplier \
--node tcp:// \
--home=./localnet/poktrolld \

And verify that the supplier is now staked with:

poktrolld query supplier show-supplier $SHANNON_SUPPLIER --node tcp://

3.4 Prepare the RelayMiner configuration

Next, we need to prepare a RelayMiner to operate on behalf of the Supplier.

You can learn more about our relay miner configs here.

The following is an example config to get you started:

cat <<EOF >> shannon_relayminer_config.yaml
default_signing_key_names: [ "keybase-key-name" ]
smt_store_path: smt_stores
enabled: true
addr: :9090
query_node_rpc_url: tcp://
query_node_grpc_url: tcp://
tx_node_rpc_url: tcp://
- service_id: anvil
listen_url: http://localhost:6942
backend_url: http://localhost:8547
- localhost
enabled: false
addr: localhost:6060

3.5 Start the RelayMiner locally

Start the RelayMiner locally:

poktrolld relayminer \
--config ./shannon_relayminer_config.yaml \
--keyring-backend test \

Leave it running in its own shell instance and open a new one. We'll be using it to serve relays in the next section.


You may need to re-export SHANNON_APPLICATION and SHANNON_SUPPLIER in the new shell instance.

4. Manually Stake an Application & Deploy an AppGate Server

Independent Gateway

This section will show how to deploy a Sovereign Application, which acts as its own Gateway. We are leaving delegated Gateways outside the scope of the Quickstart guide.

4.1 View Existing Application

You can run the following command to see all the application available in the network:

make app_list

4.2 Create an Application configuration

You can learn more about our application configs here.

The following example should get you started:

cat <<EOF >> shannon_app_config.yaml
stake_amount: 1000069upokt
- anvil

4.3 Stake the new Application

Stake the application on-chain:

poktrolld --home=./localnet/poktrolld \
tx application stake-application \
--config shannon_app_config.yaml \
--keyring-backend test \
--from shannon_application \
--node tcp:// \

And verify that the application is now staked with:

poktrolld query application show-application $SHANNON_APPLICATION --node tcp://

You can also you re-run, make app_list you should see that SHANNON_APPLICATION is now staked as an app:


4.4 Prepare the AppGate Server configuration

You can learn more about our appgate server configs here.

The following example should get you started:

cat <<EOF >> shannon_appgate_config.yaml
query_node_rpc_url: tcp://
query_node_grpc_url: tcp://
self_signing: true
signing_key: shannon_application
listening_endpoint: http://localhost:42042
enabled: true
addr: :9091

4.5 Start the AppGate Server locally


You might need to add the following to your /etc/hosts file: anvil relayminers

And the start the appgate server locally:

poktrolld appgate-server \
--config shannon_appgate_config.yaml \
--keyring-backend test \
--node tcp:// \

5. Send A Relay

Now that we've staked an Application, are running an AppGate Server, staked a Supplier, and are running a RelayMiner, we can send a relay!

Initialize Public Keys

You must run make acc_initialize_pubkeys before sending a relay in order for the public keys to be initialized correctly.

See the x/auth for more information on how public keys are stored and accessible on-chain.

5.1 Send a relay on Shannon

You can use curl

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \

If everything worked as expected, you should see output similar to the following:



5.2 What just happened?

The Relay Request/Response from is captured in the sequence diagram below.

5.3 What will happen later

Please see our protocol docs here for information on how the protocol actually works, but the following will provide some intuition:

5.4 Staking a few more Suppliers without RelayMiners

Even though we are running our own RelayMiner backed by our own Supplier, we can stake a few more suppliers to diversify where the requests are going to go.

Try using the following helpers:

make supplier2_stake
make supplier3_stake

Running make supplier_list should now show that all three suppliers are staked.

You can reuse the running AppGate Server to send requests, which should round-robin through all the available suppliers. However, since not all of them have a RelayMiner running, you'll see that some of requests will fail.

Give it a shot by running the following multiple times:

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \

5.5. Inspect the logs

As you're ready to dive in, develop or debug, you can view or inspect logs either through Tilt or Grafana.

Given that we just staked a few suppliers, you customize the query to look for Supplier either on Grafana or Tilt.

Grafana Supplier Logs

Tilt Supplier Logs

6. Dynamically Scaling LocalNet

We went through a low of steps above just so you can get a feel for how things work.

That said, you can dynamically scale the number of any actors in LocalNet by ony changing one line!

Go to our localnet tutorial to learn more.

7. Explore the tools

There are three primary tools you'll use to develop and interact with the network:

  1. poktrolld - the POKT Node CLI
  2. make - a collection of helpers to make your life easier
  3. ignite - a tool to manage the local k8s cluster

All of these are extensive and you will likely only need a small subset of their functionality in your day-to-day development. However, knowing of their existence will help you when you need to do something that you haven't done before.

E2E Tests

The e2e package contains a collection of end-to-end tests that leverage Cucumber & Gherkin. You can execute all of them with:

make test_e2e


Run poktrolld --help in order to explore all the different. You will likely spend most of your time with either poktrolld query --help or poktrolld tx --help.


Run make in order to see all the helpers our team has developed to improve our development experience.


Run ignite --help in order to explore all the different commands.