Gateway Cheat Sheet
This guide provides quick reference commands for setting up and running a Gateway on Pocket Network.
These instructions are intended to run on a Linux machine.
TODO_TECHDEBT(@olshansky): Adapt the instructions to be macOS friendly.
For detailed instructions, troubleshooting, and observability setup, see the Gateway Walkthrough.
Pre-Requisites
- Make sure to install the
poktrolld
CLI. - 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
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)
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
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:
- You have created, funded and stake a
Gateway
. - You have created, funded and stake a
Application
. - You have from the staked
Application
to staked theGateway
.
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
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" }'
Requests MAY hit unresponsive nodes. If that happens, keep retrying the request a few times.
Once PATH
s QoS module is mature, this will be handled automatically.