Skip to main content

Gateway Cheat Sheet

This guide provides quick reference commands for setting up and running a Gateway on Pocket Network.

warning

These instructions are intended to run on a Linux machine.

TODO_TECHDEBT(@olshansky): Adapt the instructions to be macOS friendly.

note

For detailed instructions, troubleshooting, and observability setup, see the Gateway Walkthrough.

Pre-Requisites​

  1. Make sure to install the poktrolld CLI.
  2. Make sure you know how to create and fund a new account.

Account Setup​

Create and fund the Gateway and Application accounts​

Create a new key pair for the delegating Application:

poktrolld keys add application

# Optionally, to avoid entering the password each time:
# poktrolld keys add application --keyring-backend test

Create a new key pair for the Gateway:

poktrolld keys add gateway

# Optionally, to avoid entering the password each time:
# poktrolld keys add gateway --keyring-backend test
tip

You can set the --keyring-backend flag to test to avoid entering the password each time. Learn more about cosmos keyring backends here.

Prepare your environment​

For convenience, we're setting several environment variables to streamline the process of interacting with the Shannon network:

We recommend you put these in your ~/.bashrc file:

export NODE="https://shannon-testnet-grove-rpc.beta.poktroll.com"
export NODE_FLAGS="--node=https://shannon-testnet-grove-rpc.beta.poktroll.com"
export TX_PARAM_FLAGS="--gas=auto --gas-prices=1upokt --gas-adjustment=1.5 --chain-id=pocket-beta --yes"
export GATEWAY_ADDR=$(poktrolld keys show gateway -a)
export APP_ADDR=$(poktrolld keys show application -a)

# Optionally, to avoid entering the password each time:
# export GATEWAY_ADDR=$(poktrolld keys show gateway -a --keyring-backend test)
# export APP_ADDR=$(poktrolld keys show application -a --keyring-backend test)
tip

You can put the above in a special ~/.poktrollrc and add source ~/.poktrollrc to your ~/.profile file for a cleaner organization.

Fund the Gateway and Application accounts​

Run the following command to get the Gateway and Application addresses:

echo "Gateway address: $GATEWAY_ADDR"
echo "Application address: $APP_ADDR"

Then use the Shannon Beta TestNet faucet to fund the Gateway and Application accounts respectively.

Afterwards, you can query their balances using the following command:

poktrolld query bank balances $GATEWAY_ADDR $NODE_FLAGS
poktrolld query bank balances $APP_ADDR $NODE_FLAGS
tip

You can find all the explorers, faucets and tools at the tools page.

Stake the Gateway​

Create a Gateway stake configuration file:

cat <<EOF > /tmp/stake_gateway_config.yaml
stake_amount: 1000000upokt
EOF

And run the following command to stake the Gateway:

poktrolld tx gateway stake-gateway --config=/tmp/stake_gateway_config.yaml --from=$GATEWAY_ADDR $TX_PARAM_FLAGS $NODE_FLAGS

# Optionally, to avoid entering the password each time:
# poktrolld tx gateway stake-gateway --config=/tmp/stake_gateway_config.yaml --from=$GATEWAY_ADDR $TX_PARAM_FLAGS $NODE_FLAGS --keyring-backend test

After about a minute, you can check the Gateway's status like so:

poktrolld query gateway show-gateway $GATEWAY_ADDR $NODE_FLAGS

Stake the delegating Application​

Create an Application stake configuration file:

cat <<EOF > /tmp/stake_app_config.yaml
stake_amount: 100000000upokt
service_ids:
  - "F00C"
EOF

And run the following command to stake the Application:

poktrolld tx application stake-application --config=/tmp/stake_app_config.yaml --from=$APP_ADDR $TX_PARAM_FLAGS $NODE_FLAGS

# Optionally, to avoid entering the password each time:
# poktrolld tx application stake-application --config=/tmp/stake_app_config.yaml --from=$APP_ADDR $TX_PARAM_FLAGS $NODE_FLAGS --keyring-backend test

After about a minute, you can check the Application's status like so:

poktrolld query application show-application $APP_ADDR $NODE_FLAGS

Delegate the Application to the Gateway​

poktrolld tx application delegate-to-gateway $GATEWAY_ADDR --from=$APP_ADDR $TX_PARAM_FLAGS $NODE_FLAGS

# Optionally, to avoid entering the password each time:
# poktrolld tx application delegate-to-gateway $GATEWAY_ADDR --from=$APP_ADDR $TX_PARAM_FLAGS $NODE_FLAGS --keyring-backend test

After about a minute, you can check the Application's status like so:

poktrolld query application show-application $APP_ADDR $NODE_FLAGS

PATH Setup​

PATH Gateway Setup​

Assuming you have followed the instructions above, the following should be true:

  1. You have created, funded and stake a Gateway.
  2. You have created, funded and stake a Application.
  3. You have from the staked Application to staked the Gateway.

Next, you can run a PATH Gateway.

Star by following these instructions:

cd ~/workspace
git clone https://github.com/buildwithgrove/path.git
cd path

Generate a PATH Gateway config file for the Shannon network​

note

The instructions below show how to setup a PATH in Centralized Mode (i.e. The operator owns both the Gateway and the Application accounts).

Refer to PATH Gateway modes for more configuration options.

Run the following command to generate a default Shannon config cmd/.config.yaml:

NOTE: You'll be prompted to confirm the gateway account private key export.

# Make a copy of the default config file
make copy_shannon_config

# Replace the endpoints as needed
sed -i "s|rpc_url: ".*"|rpc_url: $NODE|" cmd/.config.yaml
sed -i "s|host_port: ".*"|host_port: shannon-testnet-grove-grpc.beta.poktroll.com:443|" cmd/.config.yaml

# Update the gateway and application addresses
sed -i "s|gateway_address: .*|gateway_address: $GATEWAY_ADDR|" cmd/.config.yaml
sed -i "s|gateway_private_key_hex: .*|gateway_private_key_hex: $(poktrolld keys export gateway --unsafe --unarmored-hex)|" cmd/.config.yaml
sed -i '/owned_apps_private_keys_hex:/!b;n;c\      - '"$(poktrolld keys export application --unsafe --unarmored-hex)" cmd/.config.yaml

# If you're using the test keyring-backend:
# sed -i "s|gateway_private_key_hex: .*|gateway_private_key_hex: $(poktrolld keys export gateway --unsafe --unarmored-hex --keyring-backend test)|" cmd/.config.yaml
# sed -i '/owned_apps_private_keys_hex:/!b;n;c\      - '"$(poktrolld keys export application --unsafe --unarmored-hex --keyring-backend test)" cmd/.config.yaml

When you're done, run cat cmd/.config.yaml to view the updated config file.

Run the PATH Gateway​

Build and run the PATH Gateway from source​

cd cmd/ && go build -o path . && ./path

You should see the following output:

{"level":"info","message":"Starting the cache update process."}
{"level":"warn","message":"endpoint hydrator is disabled: no service QoS generators are specified"}
{"level":"info","package":"router","message":"PATH gateway running on port 3000"}

[TODO] Run the PATH Gateway using Docker​

TODO_IMPROVE(@olshansk): Add instructions for running the PATH Gateway using Docker.

Check the PATH Gateway is serving relays​

Check that the PATH Gateway is serving relays by running the following command yourself:

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

Requests MAY hit unresponsive nodes. If that happens, keep retrying the request a few times.

Once PATHs QoS module is mature, this will be handled automatically.