Welcome

Pocket Network is the TCP/IP of Web3 node infrastructure – a multi-chain relay protocol that incentivizes RPC nodes to provide DApps and their users with unstoppable Web3 access.

Pocket supports dozens of blockchains, with more being added all the time.

View the list of supported blockchains

Overview of Pocket Network’s Nodes, Sessions, and Applications

Get Started

Use Pocket Network’s RPC

Using Pocket Network is as easy as any other RPC. If you’re already using a centralized RPC provider, the Pocket Portal will be a familiar interface, and is where we recommend everyone get started.

Run a POKT Node

Shape Pocket Network’s Future

Supported Blockchains

Pocket can be made to work with any network/blockchain (RelayChain) that uses the RPC standard.

Current RelayChains

The following table shows the full list of supported, reward-generating RelayChains. This list should be identical to the SupportedBlockchains parameter.

NamePortal API PrefixRelayChainID
Algorandalgo-mainnet0029
Avalancheavax-mainnet0003
Binance Smart Chainbsc-mainnet0004
Binance Smart Chain Archivalbsc-archival0010
Bobaboba-mainnet0048
DFKchain Subnetavax-dfk03DF
Dogechaindogechain-mainnet0059
Ethereumeth-mainnet0021
Ethereum Archivaleth-archival0022
Ethereum Archival Traceeth-archival-trace0028
Ethereum Goerlieth-goerli0026
Ethereum Kovanpoa-kovan0024
Ethereum Rinkebyeth-rinkeby0025
Ethereum Ropsteneth-ropsten0023
Evmosevmos-mainnet0046
Fantomfantom-mainnet0049
FUSEfuse-mainnet0005
FUSE Archivalfuse-archival000A
Gnosis Chaingnosischain-mainnet0027
Gnosis Chain Archivalgnosischain-archival000C
Harmony Shard 0harmony-00040
IoTeXiotex-mainnet0044
Klaytn Mainnetklaytn-mainnet0056
Metermeter-mainnet0057
Metismetis-mainnet0058
Moonbeammoonbeam-mainnet0050
Moonrivermoonriver-mainnet0051
NEARnear-mainnet0052
OKExChainoec-mainnet0047
Optimismoptimism-mainnet0053
Osmosis Mainnetosmosis-mainnet0054
Pocket Networkmainnet0001
Polygonpoly-mainnet0009
Polygon Archivalpoly-archival000B
Polygon Mumbaipolygon-mumbai000F
Solanasolana-mainnet0006
Starknet Mainnetstarknet-mainnet0060
Starknet Testnetstarknet-testnet0061
Swimmer Network Mainnetavax-cra03CB

Pocket Testnet RelayChains

The following table shows the full list of currently-supported blockchains on the Pocket Testnet.

NameRelayChainID
Ethereum Goerli0020
Ethereum Rinkeby0022
Ethereum Ropsten0023
Pocket Network Testnet0002

Adding a New RelayChain

Pocket Network is expandable, and is continually adding support for new chains.

Individuals interested in bringing a new RelayChain to Pocket Network are encouraged to advocate for chains to be considered by reaching out on Discord and posting a suggestion to our team. Join our Discord.

In order for a RelayChain to be successfully deployed with Pocket, the node running community will need to support the chain. So a chain that is easier to deploy, sync, and maintain, has helpful documentation, and provides stable nodes, will all tend to increase the likelihood of the chain being approved. Pocket Network aims to give the community of node runners sufficient notice to deploy their nodes with that chain to ensure a level playing field before making a determination to support the chain.

Once the determination has been made to support a new RelayChain, the RelayChainID will be added to the SupportedBlockchains parameter, meaning that nodes will earn POKT for every request that they relay for the RelayChain based on the RelaysToTokensMultiplier parameter.

For more information, please see PIP-6.2: Settlers of New Chains.

Build with Pocket

Quickstart

Pocket Network Portal endpoints are designed to be compatible in any web3 library or environment that access an RPC URL. This means that getting up and started is a simple 2 step process.

Step 1 – Get an Endpoint

The first step to getting started using Pocket Network is to sign up for the Portal, create an application, and get the endpoint for the chain(s) that you need access to.

Head over to the Get an Endpoint page for full details of this process.

Step 2 – Plug it into your Application

There are many different reasons why a developer would need to access a blockchain in their application. Your Portal URL is designed to work directly in some of the existing frameworks and libraries that different developers would be interacting with.

UI and Interface Developers

If you’re building an interface to blockchain applications, a collection of examples of how to use your Portal endpoint is available under Popular Libraries.

Smart Contract Developers

If you’re a smart contract developer needing access to live chains in your development environment, a collection of how to of examples of how to leverage your Portal endpoint can be found under Smart Contract Enviornments.

Interacting Directly with the Chain

If you’re looking to access blockchain data directly, but aren’t using a framework or library, head over to our interactive API Documentation to see how to interact directly with the underlying blockchain API, either directly in your browser with your Portal endpoint, or through the code samples provided for each of the different supported requests.

Get An Endpoint

In order to take advantage of Pocket’s network of thousands of decentralized nodes, you need to get an endpoint that you can use in your application.

You can create your own using the Pocket Portal.

The Pocket Portal is a gateway to a decentralized RPC network, where developers can create (“mint”) blockchain network endpoints for use in their applications. Portal users can also monitor network performance and configure custom security features around their endpoint.

In this way, the Pocket Portal provides similar functionality to more centralized API services, all while retaining the decentralization that Pocket Network is built on.

The Portal has two usage tiers, an Always Free tier that allows for up to 250,000 relays per day, and a Pay As You Go tier that also offers relays beyond that with a nominal fee.

Jump to:

Create an account

To use the Pocket Portal, you must first create an account.

The Portal accepts two different methods of account creation and authentication:

  • Using your email address
  • Using your GitHub account
Warning

Once you create an account with one login method, you can’t switch to another method with that account, so make sure you choose the method that works best for you.

Sign up with email

From the main Pocket Portal page:

  1. Click Get Started at the bottom of the page. Alternatively, you can click Sign Up at the top right.

  2. On the sign up page, enter your email address and a password. When done, click Continue.

    Info

    Your password must contain at least 8 characters, and at least 3 of the following character types: lower case letters, upper case letters, numbers, and special characters. If your password does not meet these requirements, the failing criteria will be displayed on the screen.

  3. On the next screen, click Accept to authorize the app to allow access to your newly-created account.

  4. You will then be sent a verification email to the address you entered above. Open this email, and click Confirm Email Address.

    Info

    When you click this link, you will be taken to the main Portal homepage. You will know that verification succeeded because you will receive a subsequent email confirming your registration.

  5. You can now log in. Click the Log In button and you will be taken to the Login page. Enter your credentials as previously given and click Continue.

Continue below at Explore the Portal.

Sign up with GitHub

You can also log in the Portal using your existing GitHub account.

  1. Click Get Started at the bottom of the page. Alternatively, you can click Sign Up at the top right.

  2. Click Continue with GitHub.

  3. On the next screen, click Accept to authorize the app to allow access to your GitHub account.

  4. You will then be logged in and taken to the Network Overview page. You will also receive an email confirming your registration.

Continue below at Explore the Portal.

Explore the Portal

Once you’ve logged in, you’ll be taken to the Network page (also known as the Dashboard).

Network Summary

In this section, you’ll see all the important parts of the Pocket network: how many nodes are staked on the network, blockchains supported, number of relays served over time, latest block details, and much more.

To search for a specific chain and its details, the Available Networks section has a search box where you can type in the name of a chain you would like to see.

Apps and Endpoints

Your Portal account is organized into Applications (Apps), which are subdivided into Endpoints.

  • An App is a project or container that allows you to view network throughput and relays across multiple blockchains.
  • An Endpoint is the RPC URL that connects to a specific blockchain via Pocket’s network of decentralized nodes.

Your account can contain a maximum of two Apps, and each App can contain any number of Endpoints for any number of chains.

Usage Tiers

Pocket Portal allows you to have 250,000 blockchain relays per App daily, absolutely free.

For many users, this is probably all you need. For others, especially with production-ready apps, you may wish to have more usage on-demand.

With both of these cases in mind, Pocket Portal offers two tiers: Always Free and Pay As You Go.

  • Always Free: Provides 250,000 relays per App per day, through any combination of Endpoints.
  • Pay As You Go: Also provides the same 250,000 relays per App per day, through any combination of Endpoints. However, should your App request more than this in a day, you will be charged a per-relay usage fee.

You can always switch between tiers. If you are hitting your limits in the Always Free tier, you can Upgrade to the Pay As You Go tier. And if you don’t need or want the extra daily relays, you can downgrade to the Always Free tier.

Info

The Portal has overflow protection in case an App in the Always Free plan accidentally goes over 250,000 relays in a day. All surplus relays are served by our backup infrastructure, ensuring no service interruptions. This is only a temporary measure, so the app owner should upgrade the plan to Pay As You Go or contact sales for an enterprise plan.

If your App doesn’t hit the 250,000 relay cap, the tiers are identical; the only difference is that you will be asked to enter your payment information during the creation of the App (or during the Upgrade process).

Info

If you created an App prior to September 27, 2022, it will show up as “Legacy” instead of “Always Free” or “Pay As You Go”. Your App will be grandfathered into a legacy free tier for a limited time, with no rate limiting put in place.

Calculate usage

On the page where you create your app, there is a pricing calculator that allows you to estimate what the costs could be, given a certain number of relays per day.

For example, 500,000 daily relays at a price per relay of $0.000007456 would cost approximately $56.68 per month.

Info

This is necessarily an estimate, as the way the relays vary over a period of time will affect the total cost. To take a simple example, if 1,000,000 relays were to happen in a single day, there would be a charge for 750,000 relays, but if those 1,000,000 relays were spread out equally over four days, there wouldn’t be a charge, due to the 250,000 free relays per day.

If your App uses less than 250,000 relays per day, across all of your Endpoints, you will not be charged.

Create an App

When you first create an account on the Pocket Portal, you will have no Apps, so the first thing to do is to create one.

Click the Apps link on the top bar to go to its section. This is where you manage your Apps.

To create a new App:

  1. Click Create New Application.

  2. Enter a name for your App (which can be anything, as it’s just a container).

  3. Choose your tier: Pay As You Go or Always Free.

    Info

    See the section on Usage Tiers for the differences between the two tiers.

  4. When finished, click Create App.

  5. If you chose the Always Free tier, you will be taken to the App overview section.

  6. If you chose the Pay As You Go tier, you will be redirected to a checkout page. Enter your payment information and click Subscribe. You will then be taken to the App overview section.

Congratulations! You have created an App and are ready to start connecting to Pocket’s network of decentralized infrastructure. You can find a list of your Apps by clicking the Apps link on the top bar.

App Overview

Clicking one of your Apps in the list takes you to the App Overview page.

The App Overview displays all the metrics associated with your App. The charts will start being populated as soon as you start submitting requests through an Endpoint associated with your App.

You’ll see key details:

  • Endpoints: List of Endpoints associated with the App, from the list of supported blockchains. Any number of Endpoints can be created for a given App.
  • Portal ID: Unique identifier for the App. This string is included as part of the URL for each Endpoint.
  • Secret Key: Security feature for Apps. If “Private Secret Key Required” is selected in the Security section, the Secret Key will need to be sent along with the request using HTTP Basic Authentication.
  • Public Key: Unique identifier for a given App that will allow you to inspect the App on-chain.

Manage Endpoints

Every App gets created with Ethereum Mainnet as its single Endpoint.

To add a new Endpoint to your App:

  1. Click Add New in the Endpoint section.

  2. In the box that appears, click the name of the chain you wish to connect to. You may also use the search box to narrow down the choices.

The new Endpoint will then appear in the list.

To delete an Endpoint, click the trash can icon next to the Endpoint.

All Endpoints have a similar URL structure:

https://<NETWORK>.gateway.pokt.network/v1/lb/<YOUR-PORTAL-ID>
  • The network prefix. You can find them on the list of supported blockchains in the column Portal API Prefix. For example, Ethereum Mainnet is eth-mainnet.
  • The main URL (gateway.pokt.network/v1/)
  • If it’s a load-balanced endpoint (and most of them are), it will also have the /lb/ prefix.
  • The Portal ID, which is unique to your App.

Requests

The Requests page for a given App shows the success and error rates for your App across all of your Endpoints. It will also log the errors found as part of the requests made.

Security

The Security page for a given App allows you to better secure your Endpoints and your associated dApps. We recommend setting some or all of these for your specific App to reduce the risk of undesired activity.

  • Private Secret Key Required: When this is enabled every request sent to an Endpoint has to be sent using HTTP Basic Authentication with your Secret Key to be accepted. (When using curl, you would add --user :YOUR-SECRET-KEY.)
  • Approved Chains: Limits the Endpoints to be used only with specific chains. This list need not be exactly the same as the list of Endpoints on the App Overview page.
  • Whitelist User-Agents: Limits requests to only the HTTP User-Agents specified. If a User-Agent not on the list attempts to connect to the Endpoint, the request will be blocked. If nothing is specified, all User-Agents will be accepted.
  • Whitelist Origins: Limits requests to only the HTTP Origins specified. If an Origin not on the list is used in a request to the Endpoint, the request will be blocked. If nothing is specified, all Origins will be accepted. Wildcards are supported.
  • Whitelist Contracts: Limits requests to the smart contract addresses specified. If the Endpoint is used in a contract address not specified in the list, the request will be denied. Each contract address listed is chain-specific. If nothing is specified, all contract addresses on all chains will be valid.
  • Whitelist Methods: Limits requests to use specific RPC methods. If a request uses a method not on this list, the request will be denied. Each method listed is chain-specific. If nothing is specified, all methods on all chains will be valid.

When making changes, be sure to click Save at the bottom of the page.

Notifications

Info

This section is only visible for Apps on the Always Free tier. If your App is on the Pay As You Go tier, you will see the Plan Details page instead.

On this page, you can set up email alerts to be warned when you are approaching your relay limits.

There are four thresholds available for alerts. Each can be individually toggled:

  • 25% of 250,000 relays per day
  • 50% of 250,000 relays per day
  • 75% of 250,000 relays per day
  • 100% of 250,000 relays per day

You can also see your weekly bandwidth usage on this page, including average, maximum, and minimum values.

When making any changes, be sure to click Save Changes.

Plan Details

Info

This section is only visible for Apps on the Pay As You Go tier. If your App is on the Always Free tier, you will see the Notifications page instead.

This page shows you details about your subscription, including your total relays on the billing period, and your latest invoice. You can view and download your latest invoice, as well as manage your plan.

Test your Endpoint

Once you’ve set up your Apps and Endpoints to your liking, you can send requests to them to test that your settings are correct.

For EVM-based chains such as Ethereum, you can refer to the official JSON-RPC specification. Below is an example of such a request using cURL.

curl -X POST \\
-H "Content-Type: application/json" \\
--data '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []}' \\
"https://<NETWORK>.gateway.pokt.network/v1/lb/<YOUR-PORTAL-ID>"
curl -X POST ^
-H "Content-Type: application/json" ^
--data "{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"eth_blockNumber\", \"params\": []}" ^
"https://<NETWORK>.gateway.pokt.network/v1/lb/<YOUR-PORTAL-ID>"

Pocket also maintains API docs that include various methods to test out your specific Endpoint, by generating and sending requests to that Endpoint.

To test out your Endpoint, navigate to the API Docs page for the Pocket blockchain, and click any of the queries on the left sidebar. For example, a simple request is to check the block height.

Once on the page, enter your Portal ID in the box on the right and then click Send API Request. The response will be shown below.

There are also code samples for various platforms available in the Request Sample box. You can copy these code samples and use them in your own test applications.

More questions?

If you have more questions about the Portal, please see the Portal FAQ. And you can always reach out to the team on Discord.

Popular Libraries

.NET – Web3

Overview

Web3 is a simple wrapper for interacting with JSON RPC, and is provided by Nethereum, a suite of .NET Ethereum development tools.

Resources

Basic Usage

Supported Chains
using System;
using System.Threading.Tasks;
using Nethereum.Web3;

namespace NethereumSample
{
    class Program
    {
        static void Main(string[] args)
        {
            GetAccountBalance().Wait();
            Console.ReadLine();
        }

        static async Task GetAccountBalance()
        {
            var URL = "https://<PREFIX>.gateway.pokt.network/v1/lb/<PORTAL-ID>";
            var ACCCOUNT = "0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae";
            var web3 = new Web3(URL);
            var balance = await web3.Eth.GetBalance.SendRequestAsync(ACCOUNT);
            Console.WriteLine($"Balance in Wei: {balance.Value}");

            var etherAmount = Web3.Convert.FromWei(balance.Value);
            Console.WriteLine($"Balance in Ether: {etherAmount}");
        }
    }
}

Go – ethclient

Overview

The ethclient package built to enable remote communication directly to an ethereum mode, including RPC access over HTTP.

Resources

Basic Usage

Supported Chains
package main

import (
    "context"
    "fmt"
    "log"
    "math"
    "math/big"

    "github.com/ethereum/go-ethereum/common"
    "github.com/ethereum/go-ethereum/ethclient"
)

func main() {
    url :=
    client, err := ethclient.Dial("https://<PREFIX>.gateway.pokt.network/v1/lb/<PORTAL-ID>")
    if err != nil {
        log.Fatal(err)
    }

    account := common.HexToAddress("0x71c7656ec7ab88b098defb751b7401b5f6d8976f")
    balance, err := client.BalanceAt(context.Background(), account, nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(balance)

    blockNumber := big.NewInt(5532993)
    balanceAt, err := client.BalanceAt(context.Background(), account, blockNumber)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(balanceAt)

    fbalance := new(big.Float)
    fbalance.SetString(balanceAt.String())
    ethValue := new(big.Float).Quo(fbalance, big.NewFloat(math.Pow10(18)))
    fmt.Println(ethValue) // 25.729324269165216041

    pendingBalance, err := client.PendingBalanceAt(context.Background(), account)
    fmt.Println(pendingBalance)
}

JavaScript – ethers.js

Overview

Ethers is a JavaScript library for interacting with Ethereum and the ecosystem that's been built on it, including first class support for Pocket Network.

Resources

Basic Usage

Supported Chains
import { ethers } from "ethers";

const POCKET_URL = "https://<PREFIX>.gateway.pokt.network/v1/lb/<PORTAL-ID>"

const provider = new ethers.providers.JsonRpcProvider(POCKET_URL);

const blockNumber = await provider.getBlockNumber();

console.log(blockNumber);

JavaScript – web3.js

Overview

web3.js is a collection of JavaScript libraries that enable communicating with Ethereum nodes.

Resources

Basic Usage

Supported Chains
import { Web3 } from "web3";

const POCKET_URL = "https://<PREFIX>.gateway.pokt.network/v1/lb/<PORTAL-ID>"

const provider = new Web3(POCKET_URL);

const blockNumber = await provider.eth.getBlockNumber();

console.log(blockNumber);

Python – Web3.py

Overview

Web3.py is a Python library for interacting with Ethereum nodes; it originally began as a port of web3.js, but has evolved to better serve the needs of Python developers.

Resources

Basic Usage

Supported Chains
from web3 import Web3

POCKET_URL = "https://<PREFIX>.gateway.pokt.network/v1/lb/<PORTAL-ID>"

provider = Web3(Web3.HTTPProvider(POCKET_URL))

print(provider.blockNumber)

Rust – web3

Overview

web3-rust is a rust implementation of web3.js.

Resources

Basic Usage

Supported Chains
async fn main() -> web3::Result<()> {
    let url = "https://<PREFIX>.gateway.pokt.network/v1/lb/<PORTAL-ID>";
    let transport = web3::transports::Http::new(url)?;
    let web3 = web3::Web3::new(transport);

    let account = "00a329c0648769a73afac7f9381e08fb43dbea72";

    println!("Calling balance.");
    let balance = web3.eth().balance(account, None).await?;
    println!("Balance of {:?}: {}", account, balance);

    Ok(())
}

Swift – web3.swift

Overview

web3.swift is a Swift API that supports a subset of the Ethereum JSON RPC, as well as additional methods to ease ENS, ERC20, and ERC721 interaction.

Resources

Basic Usage

Supported Chains
import web3

guard let clientUrl = URL(string: "https://<PREFIX>.gateway.pokt.network/v1/lb/<PORTAL-ID>") else { return }
let client = EthereumClient(url: clientUrl)

client.eth_gasPrice { (error, currentPrice) in
    print("The current gas price is \(currentPrice)")
}

Smart Contract Environments

Solidity & Vyper – Apeworx

Overview

Apeworx is an Ethereum development framework targeted at Python developers, data scientists, and security professionals.

Resources

Basic Usage

Supported Chains

Apeworx allows you to specify multiple ecosystems, networks, and providers. Apeworx specifically has configurations in ape-config.yaml for connecting to live network nodes; it’s here where you would want to specify the Portal Endpoint. While this section is called geth, it’s not limited to just geth nodes.

For our example, let’s specify 2 ecosystems, Ethereum and Polygon, both including testnets.

geth:
  ethereum:
    mainnet:
      uri: https://eth-mainnet.gateway.pokt.network/v1/lb/<PORTAL-ID>
    goerli:
      uri: https://eth-goerli.gateway.pokt.network/v1/lb/<PORTAL-ID>
  polygon:
    mainnet:
      uri: https://poly-mainnet.gateway.pokt.network/v1/lb/<PORTAL-ID>
    mumbai:
      uri: https://poly-mumbai.gateway.pokt.network/v1/lb/<PORTAL-ID>

You would then be able to connect your Apeworx console to Goerli through Pocket Network as follows:

ape console --network ethereum:goerli:geth

Solidity & Vyper – Brownie

Overview

Brownie is a Python-based development and testing framework for EVM compiled smart contracts.

Resources

Basic Usage

Supported Chains

Brownie handles all of its network management via the CLI, meaning that you’ll have to specify networks individually as commands.

For example, this is how you would add Goerli.

brownie networks add Ethereum goerli host=https://eth-goerli.gateway.pokt.network/v1/lb/<PORTAL-ID> chainId=5

Note, the chainId is not related to the Pocket Relay Chain ID, but rather, the value returned by eth_chainId.

From here, you’d be able to connect your brownie console to this network by running:

brownie --network goerli

Solidity & Vyper – Hardhat

Overview

Hardhat is a highly extensible and modular TypeScript-based Ethereum development environment, with a mature Solidity debugging experience.

Resources

Basic Usage

Supported Chains

Hardhat allows you to configure networks through a networks object exported in the hardhat.config.js file. Here’s an example of adding networks for Ethereum and Polygon, both mainnet and testnet.

require("@nomicfoundation/hardhat-toolbox");

const PORTAL_ID = "<PORTAL-ID>";

// Replace these privates key with your respective account private key
// To export your private key from Metamask, open Metamask and
// go to Account Details > Export Private Key
// Beware: NEVER put real Ether into testing accounts

const MAINNET_PRIVATE_KEY = "YOUR MAINNET PRIVATE KEY";
const GOERLI_PRIVATE_KEY = "YOUR GOERLI PRIVATE KEY";
const POLY_PRIVATE_KEY = "YOUR MAINNET PRIVATE KEY";
const MUMBAI_PRIVATE_KEY = "YOUR MAINNET PRIVATE KEY";

module.exports = {
  solidity: "0.8.9",
  networks: {
    mainnet: {
      url: `https://eth-mainnet.gateway.pokt.network/v1/lb/${PORTAL_ID}`,
      accounts: [MAINNET_PRIVATE_KEY]
    },
    goerli: {
      url: `https://eth-goerli.gateway.pokt.network/v1/lb/${PORTAL_ID}`,
      accounts: [GOERLI_PRIVATE_KEY]
    },
    polygon: {
      url: `https://poly-mainnet.gateway.pokt.network/v1/lb/${PORTAL_ID}`,
      accounts: [POLYGON_PRIVATE_KEY]
    },
    mumbai: {
      url: `https://poly-mumbai.gateway.pokt.network/v1/lb/${PORTAL_ID}`,
      accounts: [MUMBAI_PRIVATE_KEY]
    }
  }
};

Then, say you wanted to deploy to Goerli, you’d simply run your deployment as follows:

npx hardhat run scripts/deploy.js --network goerli

Solidity & Vyper – Truffle

Overview

Truffle is a JavaScript based EVM development environment, testing framework, and asset pipeline.

Resources

Basic Usage

Supported Chains

Truffle allows you to configure networks through a networks object exported in the truffler-.config.js file. Here’s an example of adding networks for Ethereum and Polygon, both mainnet and testnet.

const PORTAL_ID = "<PORTAL-ID>"

module.exports = {
  networks: {
    mainnet: {
      host: `https://eth-mainnet.gateway.pokt.network/v1/lb/${PORTAL_ID}`,
      port: 80,
      network_id: "1",
    },
    goerli: {
      host: `https://eth-goerli.gateway.pokt.network/v1/lb/${PORTAL_ID}`,
      port: 80,
      network_id: "5",
    },
    polygon: {
      host: `https://poly-mainnet.gateway.pokt.network/v1/lb/${PORTAL_ID}`,
      port: 80,
      network_id: "137",
    },
    mumbai: {
      host: `https://poly-mumbai.gateway.pokt.network/v1/lb/${PORTAL_ID}`,
      port: 80,
      network_id: "80001",
    }
  }
};

Note, the chainId is not related to the Pocket Relay Chain ID, but rather, the value returned by eth_chainId.

From here, you’ll be able to connect your truffle console to Pocket as follows:

truffle console --network mainnet

Own POKT

POKT is the native cryptocurrency that powers Pocket. In this section, we’ll go over how to store your POKT safely, as well as buying and staking.

Manage POKT

Before buying any POKT, you should first ensure that you know how to store it safely.

Create Wallet

You can use the official wallet web app to create your wallet. Note: desktop and Ledger apps are in development. This documentation will be updated when they are available to use.

  1. Click ‘Create’.

2. Enter a unique passphrase.

Warning

The passphrase unlocks/decrypts an encrypted version of the private key that is stored in a Key File. Make sure to store your passphrase safely, if you lose it you will not be able to unlock your Key File.

  1. Download the Key File by clicking the blue download icon and click Continue to open your account.

If you accidentally click Back, as long as you downloaded your Key File and saved your passphrase, you will now be able to import your new wallet.

Warning

Make sure to store your Key File safely, if you lose it you will only be able to use the Private Key method to import your wallet anywhere. The Key File is the more secure method of importing your wallet since it is encrypted by your passphrase.

  1. Click “Reveal Private Key” then enter your passphrase again to reveal the Private Key for your wallet.

Private Key obfuscated for security

Warning

Store your Private Key safely. This will be a second method for you to import your wallet in the event that you lose your Key File or passphrase. However, this is also less secure than the Key File since the Key File is encrypted by your passphrase.

Never reveal your Private Key to anyone. If someone has access to your Private Key, they have full access to all the funds. The only application that should ever need access to your Private Key is a wallet.

Backup Wallet

It is important that you back up your Key File, passphrase, and private key securely. There are two considerations when choosing a backup method:

  • Theft Prevention: make sure no-one else can access your Key File, passphrase, or private key
  • Loss Prevention: make sure you don’t lose access to your Key File, passphrase, or private key

The most secure way to prevent theft is to store your Key File, passphrase, and private key on a USB drive (or other secure external drive), disconnected from any online “cloud” service or internet-connected computer that can be hacked.

Info

POKT will soon have Ledger support, which provides a little more advanced functionality than a USB drive, but there is no ETA on this.

For extra-secure theft prevention, you should split the Key File, passphrase and private key across separate drives and password-protect these drives so that anyone who gets their hands on a drive can’t access the contents. For extra loss prevention, you should make multiple copies of these drives and store them in different locations, such as a personal safe, the safe of a trusted family member, and a bank safety deposit box.

Once you have created your backups, delete all traces of the Key File, passphrase and private key from the hard drive of the computer you used for account setup. To ensure deletion, consider using software such as sDelete (Windows) or shred followed by rm (Linux).

Info

For more convenience, you may consider using a password manager that can store encrypted files. Just be mindful that you risk theft if your master password is compromised and you risk loss if you forget your master password.

Import Wallet

The official wallet web app has two methods of importing your wallet. The Key File is the more secure method of importing your wallet since it is encrypted by your passphrase.

Key File Import

Click Select File then choose your keyfile.json from your local file explorer.

Enter your Key File passphrase, which you specified when creating the wallet.

Click Import.

Private Key Import

Enter your Private Key.

Create a temporary passphrase that will secure your session until you log out of the wallet. This is a measure to prevent anyone with access to your computer from stealing your funds.

Buy POKT

Exchanges

POKT is available to purchase on multiple global exchanges. Follow this DAO proposal for updates on official listings.

Note that you can’t stake POKT from exchanges. To stake your POKT you would need to withdraw to your wallet (see below).

Over-the-Counter (OTC)

Over-the-Counter (OTC) trading desks are white-label markets operated by trusted intermediaries who match buyers and sellers. They are typically used for large volume trades.

The POKT community has a number of OTC desks which can be found here.

Transfer POKT to Your Wallet

To receive POKT, you must use your Address, not your Public Key. The Public Key is used for API transactions, not basic wallet actions.

Stake POKT

There is no many-to-one delegation in Pocket Network. You cannot simply stake POKT from your wallet and then forget about it. A POKT account must be staked on a node that is relaying RPC requests. However, if you do not have the skills to run a node yourself, you still have options.

Run Your Own Node

Running your own node is an option if you possess both of the following:

  • The DevOps skills to run your own node
  • More than 15,000 POKT to meet the minimum node stake

Read our tutorial on how to get started running your node.

Pay Someone to Run Your Node

If you don’t possess the skills to run your own node, but you do have more than 15,000 POKT for the minimum node stake, you can pay someone else to run your node(s). Payment models include a monthly subscription and a revenue share of your node’s POKT earnings.

All third-party node runners can be found here.

Join a Staking Pool

If you possess neither the skills nor more than the 15,000 POKT minimum node stake, you can join a staking pool. Like the third-party node runners above, staking pools are also entirely custodial, so be sure to do your due diligence. You can view the list of staking pools here.

Learn Pocket

Vision

Decentralizing Web3 Access

Web3 is built on incentives.

Blockchains enable unstoppable validation of transactions by incentivizing validator nodes, with mining/staking rewards, to confirm transactions. However, while this ensures an unstoppable history of transactions, it doesn’t ensure unstoppable access to read the history or to write new transactions to the history.

Many blockchain communities have debated incentivizing the RPC nodes that provide this access to the blockchain. Facing quite a complex challenge though, they have rejected on-chain solutions, expecting that altruists would run RPC nodes for the good of the network.

However, in the name of convenience, as RPC nodes have grown more expensive to maintain and developers more specialized, Web3 RPC access has consolidated around centralized gatekeepers. When you use MetaMask to sign transactions in your favorite game or NFT marketplace, assuming you haven’t already switched your custom RPC to Pocket Network, your data is flowing through a centralized cluster of RPC nodes. This means you are vulnerable to outages.

Pocket Network solves this critical flaw in the Web3 stack by incentivizing a network of RPC nodes to relay your data to any blockchain. DApps send their RPC requests to the nodes, who relay the requests and use Zero-Knowledge Range Proofs to validate the Relay Evidence that determines their POKT block reward. As well as making Web3 access unstoppable, this has the side effect of making Web3 infrastructure cheaper, by eliminating rent-seeking intermediaries, and more private, since each RPC node relays only a fraction of your data.

Learn more about Pocket Network’s current protocol.

Learn more about v1, the future of Pocket Network’s protocol.

How POKT Incentivizes RPC Nodes

Pocket Network’s unstoppable Web3 access is powered by the POKT utility token.

Applications stake POKT to lock in an RPC relay allowance, then transfer value to nodes through dilution of their stake proportional to the number of relays they request. Meanwhile, RPC nodes are participating in a perpetual fair-launch economy in which tokens are continuously rewarded to the nodes who do the most work.

This economic model has the following benefits:

  • Minimizes the number of transactions needed to coordinate the network, enabling cheaper RPC access. Per-relay micro-transaction payment models, on the other hand, would needlessly congest block space.
  • Provides extra incentive to apps to be early adopters of Pocket Network. When using Pocket Network, RPC infrastructure becomes an asset, literally. Apps make an upfront investment by staking POKT, which means they don’t need to worry about monthly bills and their cost-per-relay approaches zero the more relays they use. This makes Pocket Network’s RPC service very attractive compared to the competition in the long run.

Once the POKT ecosystem is mature, when apps can frictionlessly top-up their stakes, and we no longer need bootstrapping incentives, the protocol has a dormant burning mechanism that the DAO can activate to burn app stakes proportional to the number of relays they request. This will have the effect of transforming Pocket Network’s business model into a standard credit system and making POKT deflationary.

Learn more about Pocket Network’s economics and also the future of Pocket with v1.

Decentralizing Infrastructure

We posit that application-specific blockchains like Pocket Network have the ability to design greater cost efficiencies at the base protocol layer of the Web3 stack while enhancing security and censorship resistance.

Pocket achieves this through an incentive design that rewards Service Nodes for collectively achieving economies of scale:

  1. Load balancing at the protocol level incentivizes decentralization and minimizes the need for buffers
  2. Staking and inflation enables more efficient resource allocation
  3. Low marginal costs reduce barriers to entry, allowing anyone to participate at any scale

Load balancing at the protocol level

Due to the protocol using pseudo-random mechanisms to load balance work evenly across all nodes in the network, the optimal deployment strategy for node providers is to horizontally scale the number of Service Nodes they run (rather than to scale vertically by increasing the POKT stake of the Service Nodes they already have) to increase the probability that they’ll receive work. By decreasing the average work per Service Node, participants of all scales are encouraged to provision their computing power to Pocket Network. This aspect of Pocket’s system design means Pocket Network’s node counts will increase as it scales.

To minimize the marginal cost of each Service Node, it will ultimately become more profitable to run nodes out of homes and local data centers, which will, over time, create a lower-cost, more efficient decentralized network.

Pocket’s distributed nature makes it redundant-by-design, removing the need for node operators to provision extra infrastructure to handle surges in user traffic. Web2 cloud-powered infrastructure requires large buffers of redundant server capacity, which can increase the costs of coordination borne by Web3 users by up to 50%. Conversely, instead of one entity providing all the work, Pocket Network naturally splits demand up amongst Service Nodes through its Session data structure, tumbling new, pseudo-random nodes every Session to give all Service Nodes the opportunity to provide work. As a result, the buffer that each Service Node must provide is significantly lower. Additionally, because Applications must stake POKT to access the service, Service Nodes can account for all potential requests paid for in aggregate, using Application Stake as a gauge of network capacity.

Staking and inflation

For a decentralized infrastructure service like Pocket Network, on-chain payments via Bitcoin, ETH, or DAI would be inefficient due to the frequency of Relay requests. While state channel implementations do improve the cost of coordination for micropayments, Pocket matches Applications with 5 pseudo-random Service Nodes every 25 blocks for security purposes; creating and breaking on-chain state channels to communicate with each of these nodes would make the cost of coordination impractically high.

Pocket uses Proof-of-Stake (PoS) to secure the state machine and falls under the umbrella of generalized mining or useful proofs of work, where inflation is directly tied to work validated by the network. Applications stake just once to access the protocol (assuming they don’t change their throughput), using the native cryptocurrency POKT which is tied for single-use to the Pocket blockchain. Service Nodes batch all requests received in a Session to one Pocket blockchain transaction, a “Proof-of-Relay” that Applications can validate client-side and other nodes can validate in block production, removing the need for Applications to pay constant transaction fees for this work. Once those Proofs-of-Relays are validated by the network, a new block is confirmed, then POKT is minted and issued to the relevant Service Nodes as a reward for their work.

Pocket’s staking and inflation mechanisms enable a more efficient resource allocation structure by limiting the number of transactions (and thus block validation costs) to one-time staking transactions. All nodes are able to focus primarily on servicing and validating Relay requests by Applications, with minimal energy spent on block validation. By being eventually consistent and tying rewards directly to inflation, Service Nodes are in effect, receiving micropayments for work validated by two parties without the need for constant on-chain fee payments.

Low marginal costs and participation

The marginal cost of running an individual Service Node is only as high as your electricity and bandwidth costs, ensuring a low barrier to entry for new Service Node operators. Because work is load balanced evenly across the protocol, the stake, size, or capabilities of the Service Node does not increase the probability of receiving work, which enables hobbyists and small providers to participate and contribute alongside major infrastructure providers. As smaller Service Node operators scale up, they can then choose to bear the costs of hardware, equipment, and salaries needed to add more Service Nodes to their operation.

While the bulk of work will most likely be serviced by professional infrastructure providers, Pocket also enables a long tail of individuals to participate and increase the resilience of the protocol, with potential for upward mobility for those who choose to purchase more Service Nodes.

Product Comparisons

Indexers

Examples: The Graph, Covalent

Indexers are complementary services.

Indexers organize data, but they still need nodes to communicate with the blockchain. They could either run their own nodes, use a centralized API like Infura or Alchemy, or use Pocket Network’s decentralized API for an extra layer of redundancy. Outsourcing node management to a decentralized API is likely to be more cost-efficient for indexers because it will enable them to focus on optimizing their indexing setups.

For apps, while indexers are useful for more efficiently querying the chain (read), they don’t provide the RPC access needed to submit transactions to the chain (write). Not all apps will need an indexer, but they will need an API (either Pocket’s decentralized API or a centralized alternative).

Centralized APIs

Examples: Infura, Alchemy

Pocket Network is a protocol; centralized API providers are businesses.

Pocket Network connects you to a network of thousands of nodes, run by a variety of operators on a variety of hardware. Centralized API providers connect you to the hardware that they own and operate.

The key differentiator between these arrangements is that Pocket has an inherent diversity at scale that makes its service more resilient and less likely to face downtime.

For example, in November 2020, there was a consensus bug that affected specific versions of Geth, a client that Infura relied on heavily. As a result, Infura “experienced its most severe service interruption in our four years of operation”. Pocket Network, being more inherently diverse in its architecture, experienced no such outage.

Protocol

The Pocket Network is comprised of 3 components: Applications, Nodes and the Network Layer.

An Application submits Relays, or API requests meant to be routed to any public database node. Nodes service these Relays, by submitting them to the public databases they are meant for, and sending the response (if any) back to the Application. The Network Layer is comprised of all the rules, protocols and finality storage that serve as the backbone of the interactions between Applications and Nodes, including (but not limited to), configuration, record tracking, governance and economic policy.

The mechanism the Network uses to regulate the interactions between Applications and Nodes are Sessions. Sessions are a data structure that are generated following the established Session Generation Algorithm, which uses data from the finality storage layer of the network to pseudo-randomly group one Application with a set of Nodes which will provide service to it for a limited timeframe.

To dive deeper, start by learning more about Sessions.

Servicing

Overview

The Pocket Network’s Servicing layer is comprised of 2 main actors: Applications and Servicers. An Application submits a Relay Request, or an API requests to be routed to any Relay Chain. A Servicer ‘services’ the Application, by routing the Relay Request to the Relay Chain and forwarding the response to the Application. This interaction between an Application and a Servicer is the fundamental utility of Pocket Network.

Basic Lifecycle

  1. To register for decentralized infrastructure, an Application must stake the native cryptocurrency POKT in the network.
  2. The amount of the sanctioned throughput (per request) is determined by the amount the Application stakes in the network.
  3. To register to provide decentralized infrastructure, a Servicer must stake the native cryptocurrency POKT in the network.
  4. After the subsequent staking, an Application is paired with Servicer(s), during which time the servicing interaction takes place.
  5. For providing the decentralized infrastructure, Servicer receives an amount of the native cryptocurrency POKT proportional to the amount of throughput (in requests) served.
  6. Once an Application or Servicer unstakes, they are unregistered from Pocket Network and the stake is returned to their account.

Sessions

Distribution

The Servicer(s) that are paired to service an Application in a Session are equally distributed among all of the Servicers in the network.

Meaning that every Servicer theoretically serves the same amount as their peers and every Application theoretically will be evenly serviced by each Servicer over time.

Generation

The generation of a Session is key to the equal distribution property.

Equally distributed sessions are generated with pseudorandom seed data:

  • BlockHash: Hash of the last Session Block
  • AppPubKey: The Application’s public key
  • RelayChain: The identifier of the Relay Chain

The result of using this seed data is unique sessions for every Relay Chain of Application at any given Session period.

The Servicers over time that will serve each Application at any given time are extrapolated using this data, meaning any actor with the following blockchain data is able to generate the proper serving Servicers.

A single Dispatch API call to any full node on Pocket Network will provide an Application client with the ServiceURI of their Session period Servicers.

Tumbling

Tumbling is the act of regenerating a Session with new seed data.

Sessions are tumbled periodically every predetermined (by governance) quantity of blocks.

The tumbling mechanism allows for much greater Application security, as the same Validator(s) will only service the Application for a certain amount of time.

Throughput

The max Application throughput (in number of requests) is proportional to the amount staked.

The maximum a Servicer in a Session can service for a certain Application is determined using the following formula:

max_app_relays = base_throughput / (# of Servicers in Session * # of relay_chains staked for)

Relays

Payload

The request payload is the body of the RPC request

  • Data: The actual request body to be forwarded to the Relay Chain
    • e.g. {"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":67}
  • Method: The HTTP CRUD method
    • e.g. POST
  • Path: Path variable for REST support
    • e.g: "/v1/query/block"
  • Headers: HTTP Headers
    • e.g. Content-Type: application/json

Metadata

The Relay Metadata is Protocol level descriptive information that is needed for servicing.

  • BlockHeight: The Pocket Network block height when the request was made

The metadata mechanism allows for a configurable client syncronization module, enabling the Servicer to reject out of sync clients.

Since the Metadata is grouped into the request hash, this mechanism is a protection against Client level synchronization attacks where the Client is able to challenge single Servicers by requesting chain data at a different time than the majority.

Proof of Relay (Evidence)

A Proof of Relay is the portion of a Relay Request that is used for verification of the atomic work completed.

For each Application of each Session, a Servicer collects Relay Evidence in the form of a Proof of Relay. The amount of Relay Evidence is completely proportional to the amount of Relays serviced, meaning for each Relay successfully completed, the Servicer stores one piece of Relay Evidence.

Structure of the Proof of Relay

  • RequestHash: The SHA3-256 hash of the request payload
    • Connects the specific payload with the proof
    • Needed for the Application Challenge Mechanism
  • Entropy: A unique nonce (random number) that ensures uniqueness
    • Unique Relays are a requirement of Pocket Network for Claim/Proof Submission
    • Collisions are rejected by the Servicers
  • SessionBlockHeight: The block height of the session when the Relay was serviced
    • Needed to verify the participants of Session
  • ServicerPubKey: The ED25519 Public Key of the servicer
    • Needed to identify the servicer
  • RelayChain: The identifier of the ‘relayed to’ blockchain
    • Ex: 0021 (Eth mainnet)
  • AAT: The Application Authentication Token for the client serviced
    • Includes both App Public Key and Client Public Key
    • Needed for protocol level verification (app node pairings, client permissions, etc.)
  • ClientSignature: The Elliptic Curve Digital Signature of the client
    • Preserves the integrity of the Relay data
    • Needed at Proof/Claim verification level

Response

Response Payload

The response payload is the body of the RPC response:

  • Response: String representation of the HTTP response

Servicer Signature

The servicer signature completes the signature exchange needed to verify all parties in the servicing protocol.

  • Signature: preserves the integrity by signing the hash of the Proof of Relay and the response payload.

Claim/Proof Lifecycle

In order to participate in the network economic incentive mechanism, the Servicer must first Claim and then Prove the completed work. For each Application of each Session, after servicing is complete and Relay Evidence is collected, the Servicer must send two subsequent transactions:

  1. Claim Transaction
    • Merkle Root of Relay Evidence
    • Number of Relays serviced
    • Evidence Type (Relay or Challenge)
  2. Proof Transaction
    • Selected Relay
    • Corresponding Merkle Proof for selected Relay
    • Evidence Type (Relay or Challenge)

Upon successful completion of BOTH transactions, the Servicer is minted reward directly to their address.

Merkle Tree

Pocket Network requires a specific Merkle tree implementation that ensures no two leafs of the Merkle tree are identical (for Relay replay protection). Plasma-Core’s Merkle sum tree satisfies this property.

By using the hash of the Relay data (integrity is validated by verifying the Application Client Signature) in conjunction with the replay protection from the Plasma tree, Pocket Network can probabilistically guarantee work completed without the Servicer actually transmitting the entirety of its Relay Evidence to the rest of the network.

A fancier name for this is a Zero Knowledge Range Proof.

Zero Knowledge Range Proof

In order to complete a successful ZKRP in Pocket Network, the following steps must be executed by each Servicer for each Session:

  1. Generate the Merkle Tree using the SHA3-256 hash of the Relay Evidence as the leafs
  2. Submit a Claim Transaction to preserve the integrity of the local Merkle tree and corresponding Relay Evidence, as well as inform the protocol of the range or number of leafs possible to select from
  3. After a protocol wide waiting period (determined by governance), the Servicer generates the selected leaf (using the latest block hash as pseudorandom entropy to prevent knowledge of the selection during claim generation) and subsequently creates a Merkle Proof (branch) for the pseudorandomly selected leaf.
  4. The Servicer submits a Proof Transaction containing the selected leaf (Relay Evidence) and the corresponding Merkle Proof (branch)
  5. The protocol verifies the Merkle proof against the previously submitted Merkle root (in the Claim Transaction), verifies the session (proper app/node pair, not overserviced etc.), and then verifies the client signature against the Proof of Relay (integrity check)
  6. All of the Validators confirm the validity of the Proof Transaction, completing the Zero Knowledge Range Proof
  7. Tokens are minted to the address of the Servicer proportional to the amount of Relays served.

Security

By enforcing POKT to be staked from both the Applications and the Validators, the protocol is able to economically penalize either actor participating in servicing.

Session Security

The probability due to randomized selection without replacement is:

$$ P (A∩B) = P (A) P (B|A) $$

Thus the probability of selecting any combination of Validators at any given Session in Pocket Network is:

$$ 1 / (allvals (allvals-1) (allvals - 2) ... * (allvals - valspersession)) $$

Meaning, the more Validators in the network, the higher level of randomization and by extension security.

The deterministic yet unpredictable properties of the block hash seed data in Session Generation, ensure that no malicious actors will be able to determine Application and Validator pairings. This is a common security mechanism used in Pocket Network.

Application Security

The Application Authentication Token is the key mechanism for Applications to balance the security of their stake and UX of clients during servicing. Through the AAT, the Application is able to sanction clients to access their throughput via Digital Signature. Future implementations of the AAT include enforcing a lifecycle through expiration and other client access configurations such as Relay Chain specification.

Application Distribution Configuration is the recommended practice of distributing an Application’s throughput over multiple Application stakes (or identities) to ensure the highest level of data accuracy, uptime, and data privacy.

Client Side Validation is the recommended practice of redundantly sending the same request to multiple Validators. CSV allows the client to come to a majority consensus on the Relay Responses. This configuration ensures the highest level of data accuracy and enables the Application to use the Application Challenge Mechanism of the protocol, where corresponding minority Validator(s) providing invalid data are economically penalized.

Validator Security

A Validator will not receive mint for any service they provided while breaking the servicing protocol rules.

These rules are enforced by the Validators by verifying all the work reported to the network.

Examples of breaking the Servicing Rules include:

  • Overservicing an Application
  • Incorrect App/Validator Pairing
  • Incorrect Relay Chain
  • Non-Unique Proof of Relays
  • Invalid Merkle Root / Proof pairings
  • Invalid Application Authentication Token
  • A minority Validator in Client-Side Validation
  • Invalid Servicer in Proof
  • Below minimum Relay count

Economics

TL;DR

Pocket Network requires both developers and nodes to stake its native utility token, POKT, to participate in the network. Nodes earn rewards for fulfilling API requests for developers on a per request basis. POKT is permanently inflationary, but total supply will be capped through a burning mechanism put in place by the DAO, who controls the monetary policy. The final total supply of POKT will be dictated by the DAO.

Overview

Pocket Network uses a native cryptocurrency (POKT) to create a permissionless, two-sided market between node providers who run full nodes and developers that want to query data from a blockchain for their application/service. POKT is purchased and staked by both developers and node providers to participate in the network. Due to the unique incentives on each side of the market, staking differs between the parties.

Developers, requiring reliable infrastructure and relay amounts for their applications, stake POKT a single time for a guaranteed amount of relays per session for the life of the stake. The amount of POKT required to be staked is directly proportional to the number of relays required. The number of relays allowed per session can be adjusted for price fluctuations of the POKT token through governance mechanisms.

Info

The current price per relay is called BaseRelaysPerPOKT, and you can find the current value on the Protocol Parameters page.

While paying upfront for infrastructure appears to be burdensome at first glance, it has strong advantages and stickiness that help grow network adoption. The use of a token eliminates recurring payments to legacy infrastructure providers, vastly reducing the cost of infrastructure over the lifecycle of an application - bringing your cost-basis closer to zero the longer the service is used. Further, the upfront purchase of POKT can be viewed as a recoverable expense because the stake can be sold to another user if the service is no longer required helping to recover any costs associated with the network’s use. Instead of recurring payments, developers’ stakes are diluted over time through the inflation of the supply of POKT.

Node Providers also stake POKT but do so on a per-node basis. In exchange for servicing relays for applications, nodes are compensated in POKT. Unlike most traditional block rewards, Pocket Network’s is dynamic; POKT rewards are directly proportional to the number of relays and transaction fees in a given block. A node receives a certain amount of POKT per relay fulfilled and proved, minus certain percentages for both the block producer and the DAO.

Info

The current block producer percentage is called ProposerPercentage, and you can find the current value on the Protocol Parameters page.

Furthermore, the DAO allocation of block rewards is called DAOAllocation, and that also can be found on the Protocol Parameters page.

All nodes in the network have an opportunity to produce a block, but their chances are proportional to their stake.

Because of the way that nodes are incentivized, the Pocket Network economic model is inflationary during the Growth Phase, where the monetary policy is intentionally designed to encourage adoption. At network maturity, the Maturity Phase, a burn rate will initiate for application stakes that will offset the creation of newly minted POKT, stabilizing the total supply of POKT. This economic model encourages early network participation and reduces coordination costs.

At launch, the optimal economic strategy for node operators is to replicate as many nodes as possible with the amount of POKT held. By spreading their stake across multiple nodes, node operators maximize their chances of being chosen in as many sessions as possible, providing them with the most opportunity to serve relays within the network. These incentives promote further decentralization, redundancy, and increase the number of nodes available for each blockchain network supported by Pocket Network.

Maintaining a balance between both sides of the market will be critical to the long-term success of the network. To maintain and secure the future of the protocol, Pocket Network will be run by the Pocket DAO. To accomplish its mission, the DAO receives a certain percentage of block rewards to reinvest in the network. In addition to protocol upgrades, the DAO will dictate the economic policy, making every effort to create sustainable economics that caters to both sides of the market through built-in governance mechanisms. These governance mechanisms allow the DAO to maintain an equilibrium between the two sides of the market and ensure accessibility to new participants.

Token Economics

The Purpose of POKT

POKT is not a transactional cryptocurrency. The Pocket Network blockchain is not meant to have sub-5-second block times, provide 10,000 transactions per second, facilitate direct payments (generally speaking), or act as a smart contract platform. The majority of the transactions occurring will be staking by Applications and Service Nodes, Proof-of-Relay batches by Service Nodes, and block reward payments to Service Nodes for facilitating Relay requests, which all POKT holders will pay for via inflation.

This is in contrast to most layer 1 chains, which will eventually need to rely predominantly on transaction fees. At network maturity, Pocket will become a simple fee market with the demand side (Applications) burning POKT and the supply side (Service Nodes) receiving newly minted POKT via the block reward inflation mechanism. This allows for the transfer of value without using direct fees and incurring further costs of coordination.

By building a set of crypto-economic mechanisms to ensure the validation of Proofs-of-Relays, Pocket’s architecture can provide blockchain infrastructure at an order-of-magnitude lower cost than other options by virtue of being a permissionless, non-rent-seeking, and open marketplace for anyone to participate. Pocket Network uses these validated Proofs-of-Relays to reward Service Nodes through inflation.

Both Applications and Service Nodes must stake POKT to access or provide work to Pocket Network. For Applications utilizing the Pocket network, POKT represents an ongoing right to an allocation of the network’s throughput, whereas, for Service Nodes, POKT represents a right to provide ongoing work on the network and the future inflation rewards for performing that work.

Useful Proofs of Work

Pocket uses Proof-of-Stake (PoS) to secure the state machine and falls under the umbrella of generalized mining or “useful proofs of work.” Submitting proofs of work mints POKT in proportion to the amount of work completed increasing the overall supply of POKT. How this affects the overall supply is determined by the monetary policy.

Our current monetary policy is broken down into two phases: the Growth Phase and the Maturity Phase. During the Growth Phase, applications stake just once to access the protocol (assuming they don’t change their throughput) attracting new applications to use the service due to the low cost of service - only paying through their initial stake and through inflation. At network maturity (the Maturity Phase), Pocket will become a simple fee market with the demand side (Applications) stakes are burned in proportion to the amount of POKT minted by the supply side (Nodes) - eliminating the growth in total supply of POKT. This allows for the transfer of value without using direct fees and incurring further costs of coordination.

For more information, read our page on Pocket monetary policy.

Transactions

Leader-elected nodes are rewarded for facilitating P2P transfers of POKT on the Pocket blockchain via a transaction fee. This is required for the security of the network in order to prevent spam or “dust” attacks. A transaction fee is paid by the individual or entity making a transaction, 99% of which is burned, and the remaining 1% is awarded to the leader-elected node for including transactions in the relevant block. The 1% fee provides an incentive for block producers to include transactions in the next block.

Token Staking

There are two distinct types of stake functions within Pocket: StakeApp() and StakeNode(). Both stake functions use the POKT cryptocurrency.

Application Staking

Applications pay for the service in advance by staking POKT. When they invoke the StakeApp() function, the minimum staking period is 21 days. By incurring the minimum unstaking period, Applications forego the potential of using their resources, POKT in this case, for other alternatives as an opportunity cost. Additionally, Applications pay through dilution, where each time a Relay is serviced and validated by the network, a specific sum of POKT is awarded to the relevant Service Nodes in the next block reward.

The protocol limits the number of Relays an Application may access based on the number of POKT staked in relation to the Protocol Throttling Formula (as defined below). Once an Application stakes POKT, the Maximum Relays (MaxRelays) it can use is locked in perpetuity unless the Application re-stakes that POKT or their stake is burned.

Node Staking

Like with applications, when nodes invoke the StakeNode() function, the minimum staking period is 21 days. The minimum stake at launch required to become a Service Node is 15,000 POKT. This node stake keeps nodes honest and incentivized to provide high quality service. Additionally, a node sufficient stake allows nodes to participate in PoS consensus as a Validator Node. Per the changes in R.C.0.6.0, not all nodes are validators, but all validators are service nodes. To become a Validator Node, you must be in the top 1,000 node stakes (subject to change on DAO parameter vote) on the network. Validator Nodes can claim the block reward for submitting the block which is equal to the value of the ProposerPercentage parameter.

While the Minimum Node Stake is 15,000 POKT, we highly recommend staking an amount greater than 15,000 the minimum in case of slashing that may be caused by misconfiguration. Node runners have reported a stake of 15,100 POKT is a best practice.

POKT Denominations

Info

The current denomination used by the protocol is defined by the StakeDenom parameter. When using the Pocket CLI or PocketJS library to send transactions to the network, you will need to use this denomination.

LevelDenominationLevel
10^24EPOKTExaPOKT
10^21PPOKTPetaPOKT
10^18TPOKTTeraPOKT
10^15GPOKTGigaPOKT
10^12MPOKTMegaPOKT
10^9KPOKTKiloPOKT
10^6POKTPOKT
10^3mPOKTMiliPOKT
10^0uPOKTMicro or ‘you’POKT
Upper Bound = 9,223,372,036,854,775,807,000,000 STAKED uPOKT

App Economics

Important Initial Application Parameters

ItemInitial Parameter
Minimum Application Stake1 POKT
Minimum Unbonding Period (Apps)21 days
BaseRelaysPerPOKT1.67 relays per session
Stability Adjustment0
Participation Rate ActiveFalse
Block Time15 minutes
Session Time4 blocks (60 minutes)
Session Node Count5 nodes
Max Chains per Stake15

Application Economics

Pocket Network is a developer-driven protocol, with demand from Applications driving the rewards the Service Nodes earn. Applications use Pocket Network to retrieve data and write state to and for their blockchain applications. Each Relay that is created by an Application results in the creation of newly-minted POKT as a reward for the Service Nodes facilitating such Relays. Applications stake just once to access the protocol (assuming they don’t change their throughput), using the native cryptocurrency POKT which is tied for single-use to the Pocket blockchain.

The protocol limits the number of Relays an Application may access based on the number of POKT staked in relation to the Protocol Throttling Formula (as defined below). Once an Application stakes POKT, the Maximum Relays (MaxRelays) it can use is locked in perpetuity unless the Application re-stakes that POKT or their stake is burned.

Due to the oracle problem, the protocol cannot infer external factors that might influence the market price of POKT, or therefore account for these factors in the Protocol Throttling Formula. This introduces a risk to the demand side of the protocol, where fluctuations in the market price of POKT may affect the price Applications must pay for Relays.

We aim to allow the market to find a $USDPerRelay Target for POKT, to ensure the real price borne by Applications is within a relatively stable and acceptable range. This $USDPerRelay Target is not an on-chain variable, but a publicly agreed price that the DAO will target with its monetary policy, by adjusting variables in the Protocol Throttling Formula.

Calculating Throughput

When Applications stake POKT, their rate for the number of Relays they may access (MaxRelays) is locked in for the entire length of the stake. Due to the oracle problem, the protocol cannot infer external factors that might influence the market price of POKT, or therefore account for these factors in the Protocol Throttling Formula. This introduces a risk to the demand side of the protocol, where fluctuations in the market price of POKT may affect the price Applications must pay for Relays.

We aim to allow the market to find a $USDPerRelay Target for POKT, to ensure the real price borne by Applications is within a relatively stable and acceptable range. This $USDPerRelay Target is not an on-chain variable, but a publicly agreed price that the DAO will target with its monetary policy, by adjusting variables in the Protocol Throttling Formula.

When Applications stake POKT, their rate for the number of Relays they may access (MaxRelays) is locked in for the entire length of the stake. We use the following simple formula to calculate the amount of Relays Applications are entitled to per Session.

$$ MaxRelays = StabilityAdjustment + (ParticipationRate * BaseThroughput) $$

These three variables, StabilityAdjustment, ParticipationRate, and BaseThroughput aim to dynamically reflect POKT’s usage and ensure that Applications will be able to enter the ecosystem adjusting to changes in the market price of POKT.

To keep the real $USDPerRelay price as close to the $USDPerRelay Target as possible, the Protocol Throttling Formula multiplies BaseThroughput by the total ParticipationRate of the protocol to reflect any changes in demand for Relays, then the DAO will use the StabilityAdjustment in the short-term to correct deviations from the $USDPerRelay Target that are most likely attributed to short-term changes inherent in the random walk of the cryptocurrency/FOREX markets. If the StabilityAdjustment persists above/below zero without resetting, we can attribute the deviation from the $USDPerRelay Target to a more permanent change in POKT’s market value, at which point the DAO will update BaseRelaysPerPOKT and reset StabilityAdjustment to zero.

Learn more about each variable below.

Stability Adjustment

The StabilityAdjustment parameter helps smooth out pricing for applications because there is a menu cost associated with changing BaseRelaysPerPOKT too often. Applications will be reliant on a relatively stable real $USDPerRelay price to access throughput. Community resources and consistent communication will help them make decisions about how much POKT to stake at any given moment.

Pocket’s price target optimization problem will rely on off-chain data about a given currency’s current exchange rate with POKT, e.g. using $USDPerPOKT to measure how close the real $USDPerRelay price is to the DAO’s current $USDPerRelay Target. Short-term fluctuations will therefore be arbitrary depending on which currency has been chosen to anchor the DAO’s price target against and what is happening day-to-day in the crypto and FOREX markets; today $USDPerPOKT might change by 5% but €EURPerPOKT only changes by 1%. It is important that we don’t let short-term fluctuations impact the stability and accessibility of the network.

We can therefore use the StabilityAdjustment to dynamically adjust the MaxRelays computed in the Protocol Throttling Formula, while only changing our “menu price” (BaseRelaysPerPOKT) when there is a long-term deviation that can be more assuredly attributed to long-term changes in POKT’s value.

The StabilityAdjustment will be updated at the discretion of the DAO.

Participation Rate

Not implemented initially, the ParticipationRate is a tool to dynamically adjust max relays for applications without the intervention of the DAO as network usage changes. ParticipationRateacts as a proxy for utilization of the network and is reflected on a block by block basis, adjusting an Application’s MaxRelays dynamically based on the growth or decline in network-wide stake rates. Participation Rate is calculated by:

$$ ParticipationRate = (appStakedPOKT + nodeStakedPOKT) / TotalPOKT $$

The StabilityAdjustment and BaseRelaysPerPOKT help calibrate the natural ParticipationRate. Changes to the $USDPerRelay Target will be made by the Pocket DAO using a proposal system similar to MakerDAO’s Stability fee votes.

As the protocol matures, the market will dictate what price Applications should be paying for Relays, reflected by the Pocket DAO deciding on the $USDPerRelay Target. As the on-chain MaxRelays for Applications adjusts over time, existing Applications with locked-in rates for MaxRelays will be faced with two scenarios:

  • In a downside scenario, where the rate for MaxRelays drops below an Application’s current locked-in rate, Applications are incentivized to keep their POKT staked to continue receiving throughput at an above market rate.
  • In an upside scenario, where the rate for MaxRelays rises above an Application’s current locked-in rate, Applications will be incentivized to unstake and restake their POKT to receive more Relays for the same amount of POKT.

Regardless of the scenario, applications are able to benefit from shifts in the market for POKT making the most of their stake.

Base Throughput

BaseThroughput is the baseline number of Relays we aim for an Application to get per POKT staked, assuming no external factors influencing POKT. This is calculated as:

$$ BaseThroughput = BaseRelaysPerPOKT * StakedPOKT $$

BaseRelaysPerPOKT is a uint64, governed by the Pocket DAO, which describes the baseline number of Relays the Pocket DAO aims for each Application to receive per POKT staked. As a multiplier, changing this number more significantly impacts MaxRelays than changing StabilityAdjustment. For further granularity, BaseRelaysPerPOKT can be expressed as:

$$ BaseRelaysPerPOKT = BaseRelaysPerPOKTNumerator / BaseRelaysPerPOKTDenominator $$

This allows the protocol to express decimals in the form of fractional integers, enabling more granularity for the BaseRelaysPerPOKT number.

Due to the oracle problem, it is not possible to automatically adjust BaseRelaysPerPOKT based on the market price of POKT. The DAO will track indicators (such as ParticipationRate as well as the rate of change of new POKT being staked on the demand side), and adjust Pocket’s economic levers, as necessary, to ensure that Relays remain affordable for Applications.

To keep the real $USDPerRelay price as close to the $USDPerRelay Target as possible, the Protocol Throttling Formula multiplies BaseThroughput by the total ParticipationRate of the protocol to reflect any changes in demand for Relays, then the DAO will use the StabilityAdjustment in the short-term to correct deviations from the $USDPerRelay Target that are most likely attributed to short-term changes inherent in the random walk of the cryptocurrency/FOREX markets. If the StabilityAdjustment persists above/below zero without resetting, we can attribute the deviation from the $USDPerRelay Target to a more permanent change in POKT’s market value, at which point the DAO will update BaseRelaysPerPOKT and reset StabilityAdjustment to zero.

The BaseRelaysPerPOKT will be updated at the discretion of the DAO.

Node Economics

Overview

Pocket uses Proof-of-Stake (PoS) to secure the state machine and falls under the umbrella of generalized mining or useful proofs of work, where inflation is directly tied to work validated by the network.

Service Nodes batch all requests received in a session to one Pocket blockchain transaction, a “Proof-of-Relay” that applications can validate client-side and other nodes can validate in block production, removing the need for applications to pay constant transaction fees for this work. Once those Proofs-of-Relays are validated by the network, a new block is confirmed, then POKT is minted and issued to the relevant Service Nodes as a reward for their work.

Service Nodes are pseudo-randomly assigned to a Session. New Sessions get created every 4 blocks with a new, pseudo-random set of Service Nodes.

Nodes have a better chance of being picked to service relays based on their service quality. Furthermore, nodes that stake more POKT, while not improving their chances of receiving relays, will get a greater reward when serving a relay, compared to a node with less POKT staked. (See the section on Stake-Weighted Servicer Rewards for details.)

Node Staking

Like with applications, when nodes invoke the StakeNode() function, the minimum staking period is 21 days. The minimum stake at launch required to become a Service Node is 15,000 POKT. This node stake keeps nodes honest and incentivized to provide high quality service. Additionally, a node with sufficient stake allows nodes to participate in PoS consensus as a Validator Node. Per the changes in RC-0.7.0, not all nodes are Validator Nodes, but all Validators are Service Nodes. To become a Validator Node, you must be in the top 1,000 node stakes on the network (as determined by the MaxValidators parameter). Validator Nodes can claim a block reward percentage for submitting the block equal to the value of the ProposerPercentage parameter.

Warning

While the Minimum Node Stake is 15,000 POKT, we highly recommend staking an amount greater than the minimum in case of slashing that may be caused by misconfiguration. Node runners have reported a stake of 15,100 POKT is a best practice.

Distribution of Service Nodes

While Pocket Network will depend on professional infrastructure providers to provide the bulk of the infrastructure for applications, due to the low marginal cost of running a full Service Node, we expect there to be a long tail of individuals running Service Nodes. There are two primary objectives that the network will focus on to avoid any stagnation in the number of Service Nodes in the network:

  • Continuing to lower the barrier to entry for non-technical users to run full nodes by providing clear documentation as well as technical support in the bootstrapping days of the network
  • Ensuring that the minimum stake to become a Service Node within Pocket is kept low enough to maximize the number of nodes within the network

Additional efforts to prevent stagnation include supporting distribution channels such as local mining pools through data centers, run-your-own node distribution partners and the Pocket DAO’s R&D efforts.

Incentivizing the long tail of individuals running Service Nodes and keeping barriers to entry low is important to keep large node providers honest, and to minimize the odds of having an entire set of Service Nodes in a Session owned by one entity, which could lead to collusion attempts.

Cost to Nodes

Upfront costs

There are two initial costs to becoming a Service Node:

  • Minimum Node Stake
  • Hardware (if chosen)

Hardware

Pocket Network is neutral to the hardware utilized by Service Nodes, meaning that hardware can be a physical server that is run in a home or a local data center, or computing power can be purchased through popular cloud providers. The specs required for a Service Node’s hardware is dependent on the blockchain(s) that a Service Node chooses to support. For example, if a Service Node were to choose to support Ethereum, the server would need to have at least 1TB of storage (as of writing) to support an archival node for Ethereum.

Stake

The minimum stake at launch required to become a Service Node is 15,000 POKT. This minimum stake also allows Service Nodes to participate in PoS consensus. If a Service Node stake falls below the minimum amount through serving incorrect data or incorrect block validation, 20% of the minimum stake for that Service Node will be slashed and jailed. If a Service Node submits a fraudulent Relay batch, 100% of their stake will be slashed. The initial amount of POKT needed to stake as a Service Node is not dynamic, but can be raised or lowered by the Pocket DAO to ensure a stable barrier to entry.

Once the initial costs of a Service Node are covered, the only additional cost is electricity and bandwidth for providing the computing power to complete Relays. Marginal costs for Service Nodes are extremely low and increase linearly as work increases.

Recurring costs

  • Cloud providers
  • Electricity
  • Bandwidth
  • Data center

Outside of the fixed costs associated with running a node, Service Node operators will also incur costs like electricity, data center fees, and bandwidth costs for physical hardware. Alternatively, if they opt for a cloud-hosted service, they’ll be paying an all-in fee for hosting. Again, these marginal fees are low, but will play a factor in node profitability and total node counts.

Economic Security

The initial amount of POKT needed to stake as a Service Node is not dynamic, but can be raised or lowered by the Pocket DAO to ensure a stable barrier to entry.

Jailing and Slashing

  • Jailing a node removes them from both protocol service and consensus.
  • Slashing a node burns a percentage of the staked tokens.

A node is jailed and subsequently slashed for not signing (or incorrectly signing) block proposals. More often than not, this is the reason why nodes are jailed.

Warning

If a node falls below the minimum stake (due to slashing) it will be forcibly removed by the protocol and all staked tokens burned. This feature of the protocol highlights the importance of staking well above the minimum stake.

Jailing Penalties

A Pocket Validator Node can be jailed for 1 of 2 reasons:

  1. Fails to produce min_signed_per_window amount of blocks over a signed_blocks_window. When jailed because of this reason, a Pocket Validator Node is Slashed a slash_fraction_downtime% of their Stake.
  2. For Double Signing a Block. When jailed because of this reason, a Pocket Validator Node is slashed a slash_fraction_double_sign% of their Stake.

When a Pocket Validator Node becomes Jailed, it remains in the Staked list of Pocket Validator Nodes, however it becomes ineligible to become for Block Production or participating in Sessions. In order to become Unjailed again, and after waiting downtime_jail_duration nano-seconds, a Node Unjail transaction must be sent to the Pocket Network, and upon approval, the Pocket Validator Node will become Unjailed again.

Warning

If a Pocket Validator Node is left jailed for max_jailed_blocks blocks, it will be Force Unstaked.

Double Sign Penalties

0.0001% percentage of the validator’s stake that will be slashed upon reporting of double vote Evidence type from Tendermint, where a double vote on a block is/can be a submission for two differing states, transactions, apphashes, etc. and result in a forked network.

Relay Challenges

In order to participate in the network economic incentive mechanism, the Validator must first Claim and then Prove the completed work.

Burning for Bad Fraud Proofs (Replay Attack)

If a Service Node submits a fraudulent Relay batch by attempting a replay attack, the validator’s stake will be slashed by the factor specified in the ReplayAttackBurnMultiplier parameter.

Economic Incentives

For providing infrastructure access to applications, Validators are rewarded proportional to the work they provide. Pocket Core attempts to send a Claim and subsequent Proof transaction automatically after the proof_waiting_period elapses. If both transactions are successful, Tokens are minted to the address of the Validator.

Info

Read more about Pocket monetary policy.

Optimal Deployment Strategy

The considerations on how to stake your nodes have changed from when Pocket Mainnet was launched.

Initially, there was no incentive to stake more than the minimum amount of POKT. A node with 60,000 POKT staked would earn the same amount of rewards as a node with 15,000 POKT staked (assuming latency and all other aspects of service quality were the same).

Therefore, if a node runner wished to earn more rewards, and had fully optimized their node, they would spin up more nodes. Infrastructure costs scaled linearly with POKT rewards earned.

However, too many nodes can cause network slowdowns and inefficiencies. As of 2022, there were over 40,000 nodes running on the network, more than enough to service the number of relays being requested.

Thus, the community decided that there was a need to reduce the number of nodes on the network, but without negatively affecting existing node runners. This led to PIP-22: Stake-Weighted Servicer Rewards.

Stake-Weighted Servicer Rewards

Stake-Weighted Servicer Rewards incentivizes node runners to stake more POKT on their nodes by giving out a proportionally higher reward for the same service.

For example, this could mean that a node runner who staked twice as much POKT might receive twice the rewards for the same amount of relays serviced. (The details of the multiplier are on-chain parameters controlled by the DAO, and are subject to change.)

Info

Staking more POKT does not affect session selection in any way. A node with a higher stake will be selected in the same way as any other node, but when rewards are earned, they may be at a higher multiplier.

These rewards multipliers are determined by organizing nodes of various stake amounts into one of a few “bins” (or “tranches”). Roughly, the higher the stake, the higher the bin number, and the greater the rewards. All nodes that are in the same bin will have the same reward multiplier, regardless of the specific amount of POKT staked.

There are four on-chain parameters that determine how the reward multipliers are calculated:

  1. ServicerStakeFloorMultiplier
  2. ServicerStakeWeightCeiling
  3. ServicerStakeFloorMultiplierExponent
  4. ServicerStakeWeightMultiplier

While the names may seem cumbersome, they do come together in a fairly straightforward way, as described below.

ServicerStakeFloorMultiplier (“The Width”)

This parameter denotes the size (or width) of the bins. The value here denotes the amount of POKT can vary among nodes to still be considered in the same bin.

When this feature was first implemented, the value was equal to 15,000 POKT, meaning that a node could stake anywhere from (for example) 15,000 POKT to 29,999 POKT and still receive the same reward multiplier.

Info

The actual parameter is denoted in uPOKT, but is listed here in POKT for easier comprehension.

ServicerStakeWeightCeiling (“The Ceiling”)

This parameter denotes the minimum value of the top bin. Any amount staked higher than this value will not incur any greater reward.

Info

If the amount of POKT staked is higher than the Validator Threshold, the node will earn additional rewards due to being a Validator Node. However, that is unrelated to Stake-Weighted Servicer Rewards.

When this feature was first implemented, the value was equal to 60,000 POKT, meaning that a node that staked 60,000 or more POKT would always receive the largest multiplier of rewards.

Info

The actual parameter is denoted in uPOKT, but is listed here in POKT for easier comprehension.

The number of bins isn’t a parameter, but can be inferred from the values of ServicerStakeFloorMultiplier, ServicerStakeWeightCeiling, and StakeMinimum as per the following:

$$ \text{Number of bins} = \frac{(\text{ServicerStakeWeightCeiling} - \text{StakeMinimum})}{\text{ServicerStakeFloorMultiplier}} + 1 $$

Given the initial conditions supplied above, there are 4 bins.

$$ \text{Number of bins} = \frac{(\text{60000} - \text{15000})}{\text{15000}} + 1 = 4 $$

The amounts of staked POKT for each bin can be determined from this as well.

Bin NumberMinimumMaximum
115,00029,999
230,00044,999
345,00059,999
460,000[No maximum]

ServicerStakeFloorMultiplierExponent (“The Exponent”)

The next two parameters determine not the bins, but the multipliers that are applied to those bins to get the final reward multiplier.

This parameter determines how the rewards scale per each bin.

Assuming all else equal, with an exponent of 1 (the initial value when this feature was implemented) the bins would scale linearly:

Bin NumberBin with ExponentReward multiplier
1$1^1$1x
2$2^1$2x
3$3^1$3x
4$4^1$4x

Given the other initial conditions listed above, a node that has 30,000 POKT staked (Bin 2) would earn twice as many rewards for the same number of relays as a node that only has 15,000 POKT staked (Bin 1).

An exponent value of greater than 1 will incentivize node consolidation, as node runners will earn more by staking their POKT on fewer nodes. Similarly, an exponent value of less than 1 will disincentivize consolidation, because of the reduction in rewards.

ServicerStakeWeightMultiplier (“The Multiplier”)

This final parameter exists to offset the inflation caused by Stake-Weighted Servicer Rewards.

With increased rewards for the same amount of POKT staked, the new system of consolidated nodes would encourage inflation. This is an unintended side-effect, so the ServicerStakeWeightMultiplier was added in to offset the inflation, so that the amount of POKT created would be the same regardless of whether Stake-Weighted Servicer Rewards had gone into effect or not.

For example, if the way nodes are positioned in bins leads to an emission rate of 1.8 times of what would have been before, then this parameter would be set to 1.8 which would offset the rewards generated by exactly this amount.

This is the parameter most likely to be changed frequently, since it affects inflation most directly.

Calculating the reward multiplier

We can now calculate the reward multiplier for a single relay on a node, given its amount of staked POKT:

$$ \text{Reward Amount} = \text{RelaysToTokensMultiplier}\times\text{Reward Multiplier} $$ $$ \text{Reward Multiplier} = \frac{\text{Bin Number} ^ \text{ServicerStakeFloorMultiplierExponent}}{\text{ServicerStakeWeightMultiplier}} $$

where:

$$ \text{Number of bins} = \frac{(\text{ServicerStakeWeightCeiling} - \text{StakeMinimum})}{\text{ServicerStakeFloorMultiplier}} + 1 $$

and the minimums of each Bin N ( $\text{Bin } N_\text{min})$ are defined as:

$$ \text{Bin } N_\text{min} = \text{StakeMinimum} + [(N - 1) \times \text{ServicerStakeFloorMultiplier}] $$

so the node’s Bin Number is $N$ when the following is true:

$$ \text{Bin } N_\text{min} <= \text{Amount of POKT staked} < \text{Bin }(N+1)_\text{min} $$

Examples of reward multipliers

The following may be helpful in illustrating how the reward multiplier is calculated, and so will focus on the differences between the bins.

We will also assume for all these examples that the StakeMinimum is 15,000 POKT, as it has always been.

  • ServicerStakeFloorMultiplier = 15,000 POKT
  • ServicerStakeWeightCeiling = 60,000 POKT
  • ServicerStakeFloorMultiplierExponent = 1
  • ServicerStakeWeightMultiplier = 1
$$ \text{Reward multiplier} = \frac{\text{(Bin Position)}^1}{1} $$
BinStaked POKTReward Multiplier
115,000 - 29,999$1^1 / 1 = 1\text{x}$
230,000 - 44,999$2^1 / 1 = 2\text{x}$
345,000 - 59,999$3^1 / 1 = 3\text{x}$
460,000+$4^1 / 1 = 4\text{x}$

If we change the multiplier to 1.5:

  • ServicerStakeFloorMultiplier = 15,000 POKT
  • ServicerStakeWeightCeiling = 60,000 POKT
  • ServicerStakeFloorMultiplierExponent = 1
  • ServicerStakeWeightMultiplier = 1.5
$$ \text{Reward multiplier} = \frac{\text{(Bin Position)}^1}{1.5} $$
BinStaked POKTReward Multiplier
115,000 - 29,999$1^1 / 1.5 = 0.67\text{x}$
230,000 - 44,999$2^1 / 1.5 = 1.33\text{x}$
345,000 - 59,999$3^1 / 1.5 = 2\text{x}$
460,000+$4^1 / 1.5 = 2.67\text{x}$

If we set the multiplier to 1.5 and change the exponent to 0.5:

  • ServicerStakeFloorMultiplier = 15,000 POKT
  • ServicerStakeWeightCeiling = 60,000 POKT
  • ServicerStakeFloorMultiplierExponent = 0.5
  • ServicerStakeWeightMultiplier = 1.5
$$ \text{Reward multiplier} = \frac{\text{(Bin Position)}^{0.5}}{1.5} $$
BinStaked POKTReward Multiplier
115,000 - 29,999$1^{0.5} / 1.5 = 0.67\text{x}$
230,000 - 44,999$2^{0.5} / 1.5 = 0.94\text{x}$
345,000 - 59,999$3^{0.5} / 1.5 = 1.15\text{x}$
460,000+$4^{0.5} / 1.5 = 1.33\text{x}$

Monetary Policy

Pocket’s staking and inflation mechanisms enable a more efficient resource allocation structure by limiting the number of transactions (and thus block validation costs) to one-time staking transactions. All nodes are able to focus primarily on servicing and validating Relay requests by Applications, with minimal energy spent on block validation. By being eventually consistent and tying rewards directly to inflation, Service Nodes are in effect receiving micropayments for work validated by two parties without the need for constant on-chain fee payments.

Allocation of Minted POKT

For each Relay served and validated by the protocol, POKT is added to the next block reward according to the mint rate. The following is a breakdown of each participant’s share of the block reward given no parameter changes.

ParticipantParameter NameCurrent Allocation
Service NodesN/A85%
Block ProducerProposerPercentage5%
DAODAOAllocation10%
Info

Current values of these parameters (and all others) can be found on the Protocol Parameters page.

Info

The value for ProposerPercentage has recently changed. Please see PUP-19 for details.

As part of the Proof-of-Stake consensus, each Service Node has a weighted chance of being selected to be the block producer for any given block based on the total amount staked for that given node. The block producer receives a portion of the entire block reward, as does the Pocket DAO, which provides continuous and sustainable funding for supporting the continued adoption and utility of Pocket Network.

Monetary Phases

As the Pocket Network develops, we envision the POKT monetary policy evolving through three stages: Bootstrapping, Growth, and Maturity. The following sections will discuss each of these phases. Note that some of these ideas are forward-thinking and so are subject to change.

Bootstrapping Phase

During the bootstrapping phase of the network, it is important to build a strong foundation for the service, securing as many individual entities running nodes as possible. We do this by creating an environment where it is simple and inexpensive for initial Applications to access the network, and significantly profitable for Service Nodes to provide infrastructure.

Application usage and traction dictate the initial rewards that the Service Node pool will receive. By decreasing the barrier to entry for Applications (freemium access, low cost), the demand for Relays should be high during the Bootstrapping Phase, providing the initial pool of Service Nodes with ample opportunities to earn the high rate of POKT awarded for Relays serviced in the bootstrapping phase of the network.

As inflation and revenue increase per Service Node, the potential for competition increases, as rational, profit-seeking agents discover the protocol. This creates the flywheel to spur the network effects of Service Nodes purchasing and using POKT to participate until an equilibrium is found.

As the Protocol Throttling Formula adjusts to market demands, Applications being able to purchase more Relays results in more revenue for Service Nodes, further increasing the incentive for existing Service Nodes to re-stake their earned POKT. Increased participation in Pocket Network from Applications and Service Nodes ultimately benefits all parties by providing new revenue opportunities for Service Nodes and improving the service and resilience of the network for Applications. Due to Pocket Network being a permissionless Proof-of-Stake protocol and Service Nodes having an extremely low marginal cost of operation, the barriers to entry are significantly lower compared to Proof-of-Work mining based protocols. Pocket’s economic primitives incentivize a diverse set of entities and individuals such as data centers, existing infrastructure providers and hobbyists to participate as node operators within the network.

Growth Phase

The growth phase is the period from launch which will see the greatest increase in the overall ParticipationRate of the protocol. When Applications stake during the growth phase, they earn more MaxRelays as the network grows (assuming they un-stake and re-stake), and don’t pay for anything else until the network has matured and the Application Burn is activated.

One result of this is inflation. It is a priority of the DAO to manage inflation in a manner that encourages sustainable growth of the Pocket ecosystem, protects rewards against a potential decrease in relays, and sensibly updates rewards as Pocket Network grows.

If both sides of the marketplace (Applications and Service Nodes) grow, there will be continuous demand for Relays resulting in Service Nodes spinning up new Pocket nodes to increase the number of Relays they can service.

Early Applications will receive more infrastructure throughput as the network grows providing an incentive to early adopters of the network. When both the percentage of POKT staked and Service Node margins begin reaching their equilibrium, the protocol will have entered its maturity phase.

See the section below on inflation for more details.

Maturity Phase

While the Growth Phase is inflationary, designed to incentivize active participation and supply-side staking for the security of the network, the Maturity Phase is designed to ensure the long-term sustainability of Pocket. The Maturity Phase is defined as the point in which Pocket Network has crossed equilibrium and the growth in inflation begins outpacing growth in the total staked supply of POKT.

This shift to long-term sustainability revolves around burning POKT to ensure the POKT supply is stable doesn’t lose its value as a form of consideration to Service Nodes. In this phase, Pocket becomes similar to traditional Software as a Service pricing models, where Applications must “top up” their stakes periodically to avoid going below their needed Relay limit.

This should result in a decline in the ParticipationRate and Service Node margins due to an imbalance from more supply than demand for POKT.

In addition, to ensure the continued sustainability of POKT, to retain reasonable margins for Service Nodes, and to eliminate unnecessary overinflation of POKT, the Pocket DAO may activate an Application Burn Rate (ABR) at the Maturity Phase. This means that any POKT minting is balanced out by Application stake being burned at the same rate.

Once activated, the ABR results in a shift from Applications paying through dilution, to Application POKT being burned on a block by block basis to balance the minting of POKT as inflation awards to Service Nodes.

The effect of this is a logarithmic decay until the minimum App stake of 1 POKT is reached. Unless an Application increases the number of POKT they have staked, their holdings will fall under their desired amount causing applications to “top up” their stakes turning the network into a self-sustaining SaaS-like infrastructure protocol.

The rate of Application burn is determined by using indicators such as the decay in the growth of Application and Service Node stake over time.

POKT Inflation

As the number of Nodes grows in the Pocket ecosystem, if we assume a constant per-relay payout, it follows that the total amount of POKT generated by the nodes will increase. While POKT was designed to be permanently inflationary, the high rate of inflation which this situation causes has strong repercussions for the network itself.

There are plenty of benefits to inflation, such as attractive rewards for new and existing participants, near term buying pressure from new node runners, and the ability to bootstrap new chains more easily. And excitement in the marketplace driven by node rewards can lead to increased adoption.

However, there are many drawbacks to excessive inflation, such as sell pressure which may reduce activity on the network, network underutilization and unnecessary hardware costs, and a general perception of long-term unsustainability.

With this in mind, the DAO has voted on implementing and ongoing adjustment to the value of the rewards per relay (in parameter form, known as RelaysToTokensMultiplier).

Info

For more information and to read the actual DAO proposals on inflation management, please see the following:

Inflation management

At the beginning of 2022, the DAO instituted an inflation management framework called the Weighted Annual Gross Max Inflation rate (WAGMI).

A WAGMI target of 100% was implemented on Feb 28, 2022, which corresponds to a per-node reward of 0.008461 POKT/relay. It was originally set to 0.01 POKT/relay.

WAGMI targets were stepped down to 50% over the following five months as follows:

DateWAGMI Target Inflation Rate
Feb 28, 2022100%
Mar 26, 202290%
Apr 25, 202280%
May 25, 202270%
Jun 24, 202260%
Jul 24, 202250%

The per-node reward (also known by its parameter value RelaysToTokensMultiplier is calculated using:

  • The 30-day trailing average of daily relays at the time of each adjustment
  • The total supply at the time of the proposal passing (“Total Supply Baseline”):
$$ \text{Mint rate} = \frac{\text{Total Supply Baseline} \times \text{Inflation rate}}{\text{30-day trailing average of daily relays} \times \text{365 days}} $$

The timestamp of the proposal was Feb 24, 2022, 6:37 GMT (block height: 51909), and the Total Supply Baseline was 945,014,989 POKT.

Further inflation management

Following the successful step-down to 50%, a new proposal, PUP-22, known as FREN (Further Reduction of Emission Numbers), determined additional alterations to the amount of POKT issued.

The proposal extends the reduction of the emission rate over an additional five months, starting with an immediate reduction of target emission to 1,000,000 POKT/day (down from approximately 1,300,000) with a goal of 690,000 POKT/day by the end of 2022 through periodic reductions in the RelaysToTokensMultiplier. This corresponds to an effective inflation rate of 26.8%, decreasing to 18.5%. The first of these reductions went into effect on September 1, 2022.

Reward recalculations by date

DateTarget inflation rateTarget daily emission rateApprox. 30-day trailing avg. of daily relaysMint rateRelaysToTokensMultiplier
[Initial]N/AN/AN/A0.01000010000
Feb 24, 2022100%N/A306,000,0000.0084618461
Mar 25, 202290%N/A311,000,0000.0074987498
Apr 1, 202290%N/A403,000,0000.0057765776
Apr 8, 202290%N/A481,000,0000.0048474847
Apr 25, 202280%N/A693,000,0000.0029882988
May 31, 202270%N/A860,000,0000.0021092109
Jun 30, 202260%N/A879,000,0000.0017681768
Jul 24, 202250%N/A945,000,0000.0013711371
Sep 1, 202226.41%1,000,000963,000,0000.0010381038
Oct 3, 202226.41%1,000,000928,000,0000.0010771077

Pricing & Economics FAQ

What is POKT?

POKT is the native utility token that powers the economics of the protocol. Pocket Network requires both developers and nodes to stake POKT to participate in the network. Nodes earn POKT for fulfilling API requests for apps on a per request basis.

How much does it cost to send a relay?

This is determined by the BaseRelaysPerPOKT parameter.

How much can I earn by running a node?

Pocket is quite a unique blockchain network, because there are two ways for nodes to earn POKT:

  1. Servicing: processing requests to/from blockchains on behalf of apps
  2. Validating: confirming blocks, which contain proofs of the above relays done

Each time a block is validated, POKT is minted according to the RelaysToTokensMultiplier parameter which means, for every relay processed by a node, this amount of POKT is minted.

This mint is then divided according to the following percentages:

So what does this mean in practice?

Check out these charts to view the profitability of nodes over the lifetime of the network.

What is the minimum staking amount for a node?

The minimum staking amount for nodes is determined by the StakeMinimum parameter.

However, as a best practice, we recommend staking an extra 7% to 10% buffer of POKT above the minimum stake per node. This is to account for any unforeseen slashing events due to node misconfiguration, bad behavior, natural disaster, or potential accidents.

What determines my odds of being selected to validate a block?

The following formula:

round down (node stake / avg node stake) = # of tickets in the hat for block producer

Is there an advantage to staking all of my POKT on one node?

Yes, up to a point.

As of version 0.9.0, PIP-22 introduced Stake-Weighted Servicer Rewards. This implementation seeks to reduce the infrastructure costs for node runners by allowing for rewards to be generated roughly proportional to the total amount of POKT staked.

For example, if a node runner has four nodes with 15,000 POKT staked in each, the node runner could instead run one single node with 60,000 POKT and generate four times the previously-generated rewards for each relay served. Thus the node runner can reduce infrastructure costs by 75% while still generating the same rewards.

There is a limit to this benefit though, as determined by the DAO, beyond which, any additional POKT staked will not incur any benefit. This is managed by the ServicerStakeWeightCeiling parameter.

How do I buy POKT?

See the section on managing POKT.

What is the supply of POKT?

Genesis & Circulating Supply

The initial supply of POKT is 650M, which is divided according to the following genesis distribution:

The vast majority of these tokens are non-transferable and subject to use restrictions by the holders, starting from mainnet launch. __

  • Private Sale 1/2: one-year lockup and use restriction from the date of purchase. Those whose year had already expired pre-mainnet also agreed to an additional lockup according to the following schedule: 50% of tokens unlocked after 6 months, 100% of tokens unlocked after 12 months.
  • Founder Vesting: the founders agreed to restart a 3 year vesting schedule upon mainnet launch, with 10% of their allocations immediately vesting upon mainnet launch and subject to a 1-year lockup and use restriction. __
  • Pocket Network, Inc. (PNI):
    • Token Sale Pool: fully unlocked at launch and available for direct sale to users of the network. __
    • Employee/Contractor Pool: already-vested tokens subject to a 1-year lockup and use restriction, with varying vesting agreements per contractor on average of 3-4 years.
    • PNI Reserves: subject to 4 years of vesting and non-transferable for five unbonding periods (105 days total) following mainnet launch. __
  • Foundation/DAO:
    • Foundation Reserves: subject to 4 years of vesting and non-transferable for five unbonding periods (105 days total) following mainnet launch. __
    • DAO Funds: fully unlocked at launch and distributed according to DAO grants.
    • All other genesis addresses (e.g. incentivized testnet participants): non-transferable for five unbonding periods (105 days total) following mainnet launch.

This all results in the following circulating supply schedule:

Fully Diluted Supply

While the initial total supply of POKT is 650M, Pocket Network uses minting to compensate nodes for performing work on the network. For this reason, POKT is permanently inflationary proportional to usage of the network, i.e. proportional to the number of relays being processed by nodes, but the total supply will be capped through a burning mechanism put in place by the DAO (more on this below).

The Growth Phase of the network is characterized by relatively high rewards and an increase in the POKT supply designed to subsidize the bootstrapping of the network from a node and application perspective.

Once the growth rate of relays begins to decrease because Pocket Network has saturated the broader decentralized infrastructure market, Pocket Network will enter the Maturity Phase. It’s at this point that the DAO can choose to institute the Application Burn Rate (ABR) which burns developers’ stake at a rate that offsets future inflation - capping the total supply of POKT. The ABR caps the total amount of POKT and ushers in network equilibrium where mint and burn rate is equal. This is reflected in our model by a flattening in the growth in POKT. In all three scenarios, ABR is instituted at the same time but could happen earlier or later as the DAO sees fit.

You can read more about these topics in the section on Monetary Policy.

Future (v1)

Pocket Network launched on mainnet on July 28th 2020, with the singular goal of providing a utilitarian economy between Web3 applications and the full nodes that provide access to the data they need. Since launching, Pocket Network has demonstrated that a decentralized alternative to full node infrastructure is not only possible, but with the right architecture could provide a service that is unmatched. Further, the lessons we have learned maintaining the network have highlighted a path towards a truly scalable future for Pocket Network’s Web3 infrastructure. These are the possibilities that v1 seeks to achieve.

When we started working on Pocket Network, we were a scrappy startup with months of runway. For our vision to survive, we had to build our concept as lean as possible. This is where Tendermint Core came in, a general-purpose framework for building applications that require their own application specific blockchain. This provided us with the minimum viable networking and BFT consensus stack we needed to build a kickstart our vision. But, as we have grown, we have continued to push the limits of Tendermint’s general-purpose capabilities. We have made so many changes over the years that Pocket Network is now unrecognizable compared to the typical Tendermint ABCI application. These changes have allowed us to scale Pocket Network to the largest Tendermint network out there, exceeding 27,000 nodes while Tendermint was built to handle at most 10,000.

We have come to realize that, to reach our true vision of unstoppable Web3 infrastructure network with millions of nodes serving quadrillions of relays, we need to bid farewell to Tendermint and build our own stack from the ground up using all of the lessons we have learned after 1.5 years of mainnet optimized for Pocket’s use case.

v1 will contain 4 specialized modules that are optimized for Pocket Network’s core utility:

v1 will also be the catalyst for an enhanced engineering process that is more inclusive of the community, with robust laboratory infrastructure for responsive experimentation, QA, visibility, tooling and tighter development feedback loops. This is an R&D project with at least 1 year of work anticipated before the launch of v1.0 mainnet. We are revealing our vision to the community at this stage to empower everyone to get involved in our new development cycle:

  • You can follow along the R&D cycle in GitHub.
  • You can post your research ideas in the Pocket Forum.
  • You can chat about anything v1 in Discord.

Utility

Pocket Network has always been designed to do one thing and do it well: provide a utilitarian economy that coordinates unstoppable Web3 access. In the context of the v1.0 Utility Module, this means we are laser-focused on optimizing the existing utility of the network, not expanding the scope of our utility.

This means optimizing how effectively we coordinate Web3 access, which can be broken down into two categories:

  • Relay Quality: RPC node (Servicer) incentives should be as tightly-coupled as possible to relay quality, so that Pocket Network’s service not only matches centralized providers’ but provides a level of quality, unique to Pocket’s architecture, that can’t be matched
  • Relay Scalability: our protocol should be as scalable as possible, to maximize the number of relays that the network can process and optimize the efficiency (and thus cost) of the service

Relay Quality

Quality Enforcement

v0 – Client-side + Layer-2 Enforcement

When we first designed Pocket Network, we assumed that service quality would be ensured through a Darwinian competitive dynamic. Indeed, there is a weak incentive to perform better on latency/volume to maximize relays processed, though this is insufficient to ensure quality on all metrics.

To address this, we included a simple client-side validation mechanism known as a challenge transaction, which enables Apps to protest the rewards that Servicers earned for low-quality work. However, 1.5 years into mainnet, challenge transactions have never been utilized, likely since the Portal does quality checks before it sends relays. We’ve learned that client-side validation is an insufficient model to rely upon because it 1) results in Apps experiencing quality failures before they are corrected, 2) forces Apps to choose between validating relays and maximizing relay speed.

The Portal is our gateway drug. It is a web application that stakes Pocket Apps on behalf of developers, and allows us to provide the simple RPC endpoints that apps have come to expect from centralized providers. Currently, the Portal administers the majority of the protocol’s App stakes to ensure service quality while we bootstrap new chains. In 2021 we developed various layer-2 cherry-picking methods through the Portal to ensure that Apps receive service from the highest-quality Servicers available in each Session. These methods have laid the groundwork for the on-chain quality enforcement that we will be introducing in v1.0.

Utility v0 High Level Overview

v1.0 – On-chain Enforcement

The Portal is a service that builds on the Pocket Network, managing app stakes on behalf of Apps and providing quality of service checks. Maintaining this core service has shown us how critical quality assurance is to our core utility, so we decided to take these lessons and move them on-chain.

We have considered a world in which other people deploy their own Portals and compete to provide the best layer-2 quality enforcement. However, we realized that Portals would fall to the tragedy of the commons; they are simultaneously expensive to run and inherently altruistic. The only way this could be resolved off-chain is through economies of scale and extractive pricing. Sound familiar? If we went down this route, we would no longer be solving the incentive problem we saw in the full node ecosystem, we’d simply be pushing it further up the stack.

To solve this in a manner compatible with our trustless vision, the protocol needs to directly incentivize actors on-chain to enforce quality according to a standardized ruleset. Enter the Fishermen. These are a new set of actors who can disguise themselves as Apps and sample the quality provided by Servicers.

Fishermen measure the quality of relays across three key metrics according to a standardized sampling protocol:

  • Availability: Since Fishermen, Apps, and Servicers are all time-synced according to the session protocol, time-based sampling can be used to assess the availability of the Servicer. If no signed response can be collected from a Servicer, a null sample is recorded for the sample time slot. The more null samples the worse the Servicer’s availability score.
  • Latency: The time it takes for the Fisherman to receive a signed response from the Servicer (i.e. Round Trip Time) is another metric that is tracked. Due to normal variances in latency to be expected from the varying geographical distance between Apps and Servicers, these metrics are used to disincentivize high-average latency rather than explicitly rewarding the highest-performing Servicers.
  • Consistency: In addition to time-based sampling, it is mandatory for Fishermen to sample all Servicers in a session at once. The Fishermen can then compare responses and measure data consistency without needing their own comparative Web3 datasource.

The Fisherman sends sampling requests to all Servicers to collect data about all 3 quality metrics Fishermen compile these samples into test scores for each Servicer, which are averaged out across Fishermen over time, ultimately determining the proportion of block rewards that Servicers receive. Fishermen are not incentivized to influence test scores because they are paid based on the quantity and completeness of their reports, not the content of the metrics being reported.

Utility V1 High Level Overview

Quality Incentives

v0 – Quantity-based

89% of v0 block rewards are distributed to Servicers proportional to the volume of relays they served. This means Pocket Network’s incentives currently optimize for the quantity of work done, not the quality of work done.

v1.0 – Quality-based

v1.0 prioritizes quality over quantity; block rewards are distributed to Servicers according to the aggregate test scores submitted by Fishermen.

The total salary for Servicers is still proportional to the volume of relays performed on aggregate. However, this is divided between Servicers in proportion to their test scores. Each Servicer above the MinimumReportCardThreshold is eligible for an equal salary from the total pool for their RelayChain or GeoZone but has their allocation burned by the difference between their ReportCard% and 100%.

This diagram illustrates how service rewards are divided equally then burned by the difference between their ReportCard% and 100%, assuming a burn coefficient of 1.

These incentives enable Pocket Network to probabilistically guarantee a Service Level Agreement for applications.

Relay Scalability

Proving Relays

v0 – Pessimistic Proofs of Relays

v0 is pessimistic about proving work done; guilty until proven innocent. To validate the volume of relays they completed, Servicers must generate plasma merkle trees, store relay evidence, and create merkle proofs, which will then be validated by Validators, as part of a multi-step Zero Knowledge Range Proof.

This works very well as secure cryptography but it scales linearly because plasma merkle trees have O(n log(n)) space complexity, where n is the number of relays, and the branch must be included in every proof transaction. In practice, this means proofs get more expensive to process in proportion to relays, which contributes to higher CPU loads and longer block processing times.

If Pocket Network is to grow to serve quadrillions of relays, the relay proof lifecycle must be fundamentally restructured.

v1.0 – Optimistic Proofs of Samples

Work payments in v1.0 are optimistic, more like a salary compared to v0’s unit-based payments.

The total salary pool is still proportional to the volume of relays performed on aggregate. To determine the size of this total available reward, Fishermen probabilistically estimate volume using probabilistic hash collisions rather than counting up (and proving) every relay.

The Fishermen samples themselves are also optimistic. Fishermen only need to submit test scores on a pseudorandom schedule and only need to verify a single pseudorandomly selected non-null sample. Since the Fishermen (and Servicers) can’t predict which test scores will be submitted or which samples will need to be verified, the monitoring system remains a secure deterrent of bad behavior while avoiding the cost that would come from validating every test score.

We only need to submit a subset of test scores and prove a subset of samples By switching to an optimistic model, we reduce both the frequency and size of proofs, which should allow relays to scale exponentially rather than linearly.

Creating & Validating Proofs

v0 – Unified Actors

In v0, until recently, Validators and Servicers were bundled together. This meant that the scalability of Servicers was bound by Validators, for two reasons:

  • Validators are subject to the scalability of the BFT consensus algorithm, which is arguably the least scalable component of our protocol by design
  • Servicers are burdened with performing expensive Validator tasks, even though these aren’t necessary to perform Servicer tasks

We have already begun moving away from this model with the separation of Validators and Servicers in v0.7. Limiting Validators to the top 1,000 by stake has allowed our Servicer count to grow to almost 25,000 without impacting the health of our blockchain. v1.0 will take this a step further.

v1.0 – Task-based Specialization of Actors

We have already agreed that Servicers shouldn’t need to validate proofs. Taking this a step further, why should they need to prove their own work? In v0, Servicers must constantly store claims and proofs if they want to get paid, which presents a computational burden that distracts them from optimizing on their most important tasks: relaying RPC requests.

In v1.0, we are more explicitly separating actors according to their tasks. We are introducing the Fisherman, whose sole responsibility is to prove the quality of work done. This narrows the scope of Servicer work to just performing relays, which should make it cheaper to perform relays and thus dramatically enhance the efficiency of the network’s core task.

v1.0 Utility Roadmap

1. Proto-Fish

We will begin live-testing the Fisherman sampling methods in v0, using the Portal as a low-risk supervised environment.

2. Castaway

When v1.0 launches, we will begin with a single DAO-governed Fisherman. This will enable us to adopt all the benefits of v1.0, with the Fisherman actor being the only trusted actor in the network.

3. Fishermen

We will then transition to a multi-Fisherman model, wherein DAO governance can appoint and remove Fishermen, burning them to penalize bad behavior.

4. Cast-Net

Finally, Fishermen will become truly trustless actors as the monitoring/enforcement of their behavior is moved entirely on-chain.

More Details

Read more details about the v1.0 Utility module spec.

Consensus

The consensus module coordinates Validators to come to agreement that the transactions in a block are legitimate before the block is added to the blockchain. Currently, v0 inherits its consensus implementation from Tendermint. While Tendermint provides a great framework for building applications that can handle arbitrary computation, it is not optimized for Pocket Network’s singular focus of coordinating unstoppable Web3 access.

Some of the major changes to the consensus module for v1.0 include:

  • Replacing Tendermint BFT with HotStuff BFT
  • Migrating from a Round Robin leader selection process to a blind, pseudorandom leader selection process
  • Allowing the Block Proposer to validate transactions against the mempool before including them in a block

For the network as a whole, these changes will enable more consistent block times. For those running nodes, these changes will allow for:

  • Less bandwidth and compute resources spent communicating with other nodes during consensus
  • Less storage usage, as invalid transactions will no longer be included in blocks
  • Block creation rewards proportional to the amount staked.

A Primer on Consensus

The two most popular types of consensus algorithms are Nakamoto and Byzantine Fault Tolerance (BFT).

Nakamoto

In Nakamoto consensus, the network chooses to follow the longest chain. This is the consensus mechanism that Bitcoin, Ethereum 1.0, and most Proof of Work chains currently use. As long as someone can submit a valid proof of work, they can add a block to the chain.

In case the block added was fraudulent, whether maliciously or accidentally, whoever submits the next block can choose to do so from whichever point they wish, creating a fork in the chain. If the network adopts this new chain enough that it becomes the longest, this results in what’s known as a chain reorganization. This is why applications that make transactions on these chains often wait for a number of “confirmations”, because the chain can potentially reorganize at any point. This process of waiting for transactions accomplishes something called probabilistic finality.

Probabilistic finality works well for coming to consensus on events that have already occurred, however, since Pocket Network uses the current state of the blockchain to determine which Servicers to match Apps with, Nakamoto consensus is incompatible with the Utility module.

BFT

In BFT consensus algorithms, Validators must come to agreement before adding any blocks to the chain. The name comes from the “Byzantine generals problem”, a thought experiment that dealt with how a group of military generals, who could not communicate directly with each other, could come to a decision about whether to attack or flee. This issue doesn’t just deal with the case of the general being a malicious actor, but also the case of the messenger being the one who changed the vote, or simply not being able to deliver the message. In a computer system, Byzantine faults are used to describe errors that can occur from an actor either being compromised or faulty. These types of consensus mechanisms, while useful for blockchain consensus, were originally developed to enable aircraft to rely upon their sensor data to make software decisions as long as a certain threshold of their sensors were always in agreement.

Where Nakamoto consensus can probabilistically resolve fraudulent blocks through its longest-chain selection process, BFT instead opts to require consensus on the next block before moving forward with the chain. Since Pocket Network’s Utility module requires a single state from which to maintain coordination between Servicers and Apps, BFT is the obvious choice.

The Consensus Algorithm

v0 – Exponential Communication Complexity

The Tendermint BFT consensus algorithm has served Pocket Network well but will hold us back because communication complexity scales exponentially in proportion to the number of nodes, for two reasons:

  • Network-Wide Random Gossip: Every node in the network must pass on what every other node has told them, including Servicers. The more nodes there are, the more node-node messages must be sent and received, resulting in an exponential volume of messages. If Pocket Network is to continue scaling to hundreds of thousands of nodes, this gossip process must be fundamentally restructured, otherwise the communication bandwidth required will become insurmountable.
  • Pessimistic Responsiveness: When voting on a block, the network must wait for all nodes to vote (or wait a minimum period of time) before moving on, even if enough votes have already been cast to reach consensus. This can make the network more vulnerable to chain halts if not enough nodes can keep up with the voting process.

v1.0 – Linear Communication Complexity

We will be solving these issues in v1.0 by switching to our own implementation of the HotStuff BFT consensus algorithm: HotPocket. The biggest advantage of this algorithm is that it uses validator-specific structured gossip and optimistic responsiveness to significantly reduce communication complexity.

  • Validator-Specific Structured Gossip: HotPocket selects a small group of nodes to be responsible for listening for messages and then broadcasting gossip to everyone. This means instead of sharing messages with everyone, nodes only have to share with the selected listeners, which allows communication bandwidth to scale exponentially with the number of Validators.
  • Optimistic Progress: HotPocket introduces a new phase in the consensus process. During this phase, Validators must acknowledge that they have seen the block proposal going up for a vote. When it comes to the voting phase, any Validators who did not acknowledge the proposal can be dismissed and the chain can move on with majority consensus as long as the present Validators approve it. Along with this, we have a custom pacemaker module that ensures consistent block times, which are critical for the time-synced mechanisms in the Utility module.

The Leader Selection Process

v0 – Round Robin

Tendermint uses Round Robin to determine the next leader who will propose the next block. This makes the blockchain vulnerable to DDoS attacks since we know exactly who the next leaders are going to be and when. We have already modified Tendermint’s Round Robin to use a pseudorandom selection algorithm where the hash of the previous block determines the next leader.

v1.0 – VRF + CDFs

In v1.0, we are leveraging Verifiable Random Functions (VRFs) for more secure pseudo-random leader selection that is unpredictable before the block production, yet deterministic and computationally cheap to verify afterwards. Whereas v0 uses the previous block hash to generate leaders, v1.0 uses the VRF secret keys of other Validators which are impossible for the proposer to know. VRFs are combined with Cumulative Distribution Functions (CDFs) to enable selection to be weighted based on the amount staked by the Validator. Because it is probabilistic, it is possible for the VRF to generate 0 proposers, in which case we fallback to the v0 Round Robin process.

Handling Invalid Transactions

v0 – Block Proposer Can’t Validate

Since Tendermint was designed to support arbitrary computation, there were risks for them allowing the block proposer to validate transactions against the mempool. Since the state of the mempool changes as transactions come in, there is currently no way for the block proposer to know if transactions are valid before proposing them in a block. For chained and dependent transactions that rely on ordering, this can cause problems of unexpected failed transactions. Since transactions aren’t validated until they’re included in the block, this leads to the chain being bloated with meaningless failed transactions, which makes indexing and processing transactions harder, ultimately wasting resources.

v1 – Block Proposer Can Validate

Since Pocket Network isn’t a blockchain built for arbitrary computation, and instead built for a specific purpose, we can make guarantees about what computations would occur if the block proposer tried to validate transactions against the mempool. This means that it is possible for the block proposer to filter invalid transactions before proposing a block. This will greatly help to reduce the storage requirements of the chain as well as making it easier to index and process transactions.

More Details

Read more details about the v1.0 Consensus module spec.

Peer-to-Peer

The Peer-to-Peer (P2P) module is responsible for handling how all the nodes in the network communicate with each other when new transactions need to be added to a block and when the new block gets added to the chain. Currently, v0 pairs peers together randomly. This random pairing was chosen to ensure redundancy across the network, however, as Pocket Network continues to grow, the redundancy and complexity of random pairing require more bandwidth as more nodes come online – with a good chunk of that bandwidth being used to retrieve copies of information the nodes have already seen.

In v1.0, the P2P module will transition from random communication to structured communication. For those running nodes, this transition means a significant reduction in bandwidth usage. For the network as a whole, this means more efficient and scalable communication, while maintaining the required redundancy. This will move the P2P system from having low visibility and a large amount of message duplication to having high visibility and less message duplication.

A Primer on P2P

There are three primary components of the P2P system that all contribute to the reliability and speed of the network. Those components include Event Dissemination which handles how nodes will be paired to communicate with each other, Membership and Churn which handles knowing when nodes either come online or go offline, and the Transport Layer which controls the mechanism used to actually send and receive messages between peers. Some of these problems are problems that can apply to networking across the board, while others are unique to P2P networks specifically. The requirements of building an effective P2P communication network include:

  1. Efficiency and Scalability – making sure that more peers can connect without a major impact to the network performance
  2. Fault and Partition Tolerance – despite any number of breakdowns that happen between nodes, the network can continue to operate
  3. Managing Membership and Churn – effectively communicating when a peer both joins and leaves the network.

While there are a large variety of existing P2P implementations out in the wild, each implementation has made design decisions based on specific needs that don’t translate to the needs of Pocket. In choosing the design for the v1.0 implementation, it was important to understand the fundamental needs of Pocket Network. There are three types of communications that are fundamental to how Pocket Network operates.

  1. Servicers need to be able to inform the network of transactions made
  2. Validators need to be able to communicate with each other during consensus and with the whole network when a new block is created
  3. Archival nodes need to be informed of new blocks, as well as handling and making requests for new blocks.

From these three main types of communication, we can specifically say that the P2P module of Pocket Networks needs to be able to:

  1. Communicate blocks and transactions across the network
  2. Restrict communications to only the groups who are needed for those communications.

Event Dissemination

v0 – Random Gossip

Currently, Pocket Network communicates information about blocks and transactions through random gossip. When a node learns of a new piece of information, they pass that information along randomly to other nodes in the network. This random process ensures that the data can make its way through the network, regardless of failures between certain pairs of nodes. This process, while ensuring redundancy, does so in a way that requires nodes to spend bandwidth and resources receiving the same message multiple times.

Building on this, because nodes randomly select other nodes to share this information with, nodes will share and receive information regardless of whether that is information they need. Gossip about the consensus process is only relevant to nodes who are acting as Validators. Gossiping with every Servicer and Archival node about the validation process not only takes away resources from those nodes but it slows down the gossip phase of the consensus process.

v1.0 – Structured Gossip

RainTree is a gossip protocol that leverages the efficiency that Binary Trees provide for lookups of sorted, randomly-distributed data. RainTree provides the mechanism to ensure delivery, offer redundancy against non-participation without needing retries or acknowledgements, and perform a cleanup to ensure 100% message propagation in all cases.

The process starts with a node that wishes to gossip a message to all other peers in the network. Once the node has a sorted list of all other peers in the network, it needs to:

  1. Build a binary tree based off the sorted list, with the left branch being the peer at 33%, and the right branch being the peer at 66%, with a third branch that points back to itself
  2. Determine its own and max depth of the tree
  3. Gossip messages to all depths of the tree.

The peers on the left and right branches then build their own subsections of the tree using the above, and the process continues. This third branch is there to add redundancy. When the node begins gossiping down the tree, it will, eventually, reach the point where it has to send itself the message. Once it has reached this point, the node is able to send it to not just the left and right as expected but also every other node in the originally sorted list.

Since networks are vulnerable to nodes dropping out at any point, if one of the branches does not acknowledge that it received the message, the node that tried to communicate with them will then readjust and send the message to the children that would have received the message from the unresponsive parent.

A successful transmission to the left and right nodes. An unresponsive right node means that the children of that node need to be notified directly To be 100% certain that all functional nodes received the message, the Double-Daisy-Chain (DDC) cleanup layer provides a reliability mechanism that’s used in other gossip algorithms, including epidemic communications. Once the message propagation has reached the next to last layer of the tree, the nodes in the final layer are sent a special “I Got You Want?” (IGYM) message that expects either a Yes/No answer. If the answer is a Yes, the node is forwarded along the full message and they continue said process. If the answer is No, or there is no answer, that node is skipped and the next node in the chain is selected for the same process.

DDC Cleanup Layer

Gossip Restrictions

v0 – Everyone Communicates Everything

In the current system, all nodes communicate any information to all other nodes regardless of whether the information is relevant to that node. This means that Servicers must actively listen and share information about the consensus process, despite the fact that they are not participating. In networks that primarily consist of Validators, this doesn’t cause many issues, but since Pocket Network contains other specialized actors such as Servicers and Fishermen, scaling these actors should not impact the communication of processes irrelevant to their input. If we don’t scale actor communication independently, scaling Servicers and Fishermen will slow down consensus, resulting in longer block times.

v1.0 – Restricted to Relevant Parties

The gossip protocol in the Consensus module is a specialized version of RainTree designed for that specific case. As Pocket Network already keeps a list of the current Validators, it’s possible to leverage RainTree for this process. This allows the consensus process to take advantage of the optimizations and redundancy of RainTree. Even more importantly, since the tree will be constructed from only the list of Validators, this means that gossip related to consensus can occur only between those that are involved in the process. This means that the consensus process isn’t held up by trying to communicate with the entire network and that other actors are now unburdened from gossip that isn’t relevant to them.

More Details

Read more details about the v1.0 Peer To Peer module spec.

Persistence

The Persistence module is responsible for ensuring that the data continues to persist over time, across deployments, and throughout software changes. Currently, V0 handles data persistence through Tendermint. Tendermint uses a similar mechanism to most other blockchains, storing the different state data that needs to persist in Merkle trees. The roots of these trees are included in the block, and then for each block, each of the trees is stored as a file.

This design simplifies the computational overhead a new client would need to get up to sync with the current block, however, it does so at the cost of storage. While this decision was made to ensure that the barrier to entry of acting as a validator of a network is low, it fails to consider how critical full nodes, nodes that maintain copies of the data to be accessed and queried by applications, are as infrastructure for production applications.

As the core mission of Pocket Network is to provide access to high quality, decentralized infrastructure, the role of the full node needs to be considered as a priority and not an afterthought. Some of the changes that are being made to the persistence layer in V1 include:

  • Moving from a Key Value Filesystem DB to an SQL based Tamper Proof Hybrid Mutable DB
  • Decoupling the persistence layer to allow for a Client Server Architecture between pocket-core and persistence.

For those interacting with the network, these changes will mean significantly faster access to any state data that would have relied on a query to access.

For those running nodes, these changes will not only make the current experience better, but it will also open the door to more control and options when it comes to deployment configurations. These changes will:

  • Drastically reduce the storage needs (80%) for storing the blockchain data.
  • Drastically reduce the amount of resources needed to query state data. (10+ seconds -> milliseconds)
  • Enable better data portability, making it easier to quickly spawn up additional databases as needed
  • Enable individual scalability, making it easier to kill off and replace a failed process.
  • Allow for an additional layer of fault tolerance, since the choice for database engine can be replaced.
  • Enable for multi-process concurrency, making it possible to horizontally scale pocket-core without worrying about the storage cost for doing so.

Underlying Database

V0 – Key Value Filesystem

Currently, at each block, the data that represents the current state is stored as a tree in a file. While this provides some benefits, such as being able to simply move a directory to move the data, and easily being able to store arbitrary data, these benefits come with significant downsides. For one, regardless if anything has changed in the state between blocks, an entire copy of that tree is written again. There is no process for currently managing data deduplication.

The other issues come from using a filesystem as a production database. Out of the box, Linux cannot handle the amount of simultaneously open files needed to manage a system in this manner, hence needing to make sure the ulimit is properly specified before running a node. Using the filesystem also means that data access is almost entirely reliant on the I/O speeds of the system. When you add in how querying through old state would mean opening multiple files, this means that queries dependent on I/O are the slowest part of the system.

V1 – Tamper Proof Hybrid Mutable DB

SQL provides a mature, optimized, battle-hardened solution to the data storage problem. One issue with SQL is it requires a well-defined data schema, and so it’s well suited for arbitrary data storage. Since Pocket Network does not handle arbitrary computation, and instead serves a defined application specific purpose, SQL provides the opportunity for significant storage and speed optimizations.

A Persistence Client Middleware will communicate between pocket-core and a generic database engine, to define what needs to happen to define, persist, update, and query the datasets it stores. This mechanism will define the following to ensure consistency:

  1. Versioning of the state dataset
  2. Byte-perfect consistency of the data encoding
  3. Schema definition mechanism
  4. Deterministic write mechanism
  5. Idempotent Dataset Updates

To ensure that the data is tamper proof, the Patricia Merkle Tree can be stored in the state dataset for each block, and can be used to verify the validity of each block. As the operations on the data are ACID and idempotent, any change to the underlying data is detectable.

System Deployment

V0 – Data Duplication

The current system requires that each pocket-core process needs access to an independent copy of the data to run. If a node needs to increase resources, whether that be to handle more traffic, or more data access, the only option is to start another process that needs a full copy of the data to run.

V1 – Client-Server Architecture

Breaking the core and persistence layers into a client server architecture gives node runners the ability to scale and manage the respective processes more efficiently. While keeping the persistence layer on the same machine as the pocket-core process would allow for the least latency, it also restricts the node runner from configuring their infrastructure in a way that best serves the needed demand.

Some of the examples that node runners now have access to include:

  • Spawning up multiple pocket-core processes on behalf of the same identity to scale to handle more demand.
  • Connecting multiple pocket-core processes that represent at least two nodes in close physical proximity to the same database.
  • Connecting multiple pocket-core process that represent multiple nodes to a database cluster to allow a collection of nodes to efficiently scale-up storage needs

Some example deployment configurations available when allowing for a Client Server architecture Since nodes know the maximum amount of relays that the applications it’s serving can request, this gives node runners the ability to save costs by allocating resources only as needed.

More Details

Read more details about the v1.0 Persistence module spec.

Protocol Parameters

Off-Chain

USDRelayTargetRange

Current Value: $0.00036–0.00059 per relay

The range of USD/relay prices the DAO doesn’t want the real price of a relay to exceed, accounting for the USD price of POKT.

ReturnOnInvestmentTarget

Current Value: 10 months

How long the DAO wants it to take for the USD/relay price to be achieved, since the cost basis of a relay decreases over the lifetime of an app stake.

Application Module

ApplicationStakeMinimum

Current Value: 1000000

The minimum stake required of an app, denominated in StakeDenom. This does not have the same economic security requirements as a node’s minimum stake because an app’s access to the network (relay throughput) is already proportional to the stake.

AppUnstakingTime

Current Value: 1814000000000000

The time, in nanoseconds, that an app must wait after initiating an unstake before they can use the POKT for anything else.

BaseRelaysPerPOKT

Current Value: 200000

The number of relays that an app is entitled to for every POKT it stakes, multiplied by 100.

The formula for calculating the MaxRelays an app is entitled to is

$$ MaxRelays = StabilityAdjustment + (ParticipationRate * BaseThroughput) $$

Where BaseThroughput is

$$ (BaseRelaysPerPOKT/100) * StakedPOKT $$

The /100 is included in the formula to enable the DAO to make more granular adjustments, since the protocol is unable to use decimal numbers.

In practice, this means if the BaseRelaysPerPOKT parameter is 100 then the baseline throughput that apps are entitled to is 1 relay per POKT.

MaxApplications

Current Value: 2295

The number of staked applications that the protocol allows.

MaximumChains

Current Value: 15

An app can only be configured for up to this many chains on one stake.

ParticipationRateOn

Current Value: false

The protocol may adjust an application’s MaxRelays at the time of staking according to network-wide stake rates, where the ParticipationRate acts as a proxy for utilization of the network on a block by block basis.

$$ MaxRelays = StabilityAdjustment + (ParticipationRate * BaseThroughput) $$

This parameter was set to false at genesis and will only be activated if the DAO decides.

StabilityAdjustment

Current Value: 0

The DAO may manually adjust an application’s MaxRelays at the time of staking to correct for short-term fluctuations in the price of POKT, which may not be reflected in ParticipationRate.

$$ MaxRelays = StabilityAdjustment + (ParticipationRate * BaseThroughput) $$

When this parameter is set to 0, no adjustment is being made.

PoS (Node) Module

BlocksPerSession

Current Value: 4

The number of blocks allowed before a Session tumbles.

DAOAllocation

Current Value: 10

The DAO treasury earns this proportion of the total POKT block reward. Value is a percentage. See also ProposerPercentage for another beneficiary of the block reward.

DAOOwner

Current Value: a83172b67b5ffbfcb8acb95acc0fd0466a9d4bc4

The account which has the permission to submit governance transactions on behalf of the DAO.

DowntimeJailDuration

Current Value: 3600000000000

The amount of time (in nanoseconds) before a node can unjail and resume service.

MaxEvidenceAge

Current Value: 120000000000

The amount of time (in nanoseconds) a node has to submit their Tendermint evidence in memory before it expires.

MaximumChains

Current Value: 15

A node can only be configured for up to this many chains on one stake.

MaxJailedBlocks

Current Value: 37960

The amount of time (in blocks) a node has to unjail before being force unstaked and slashed.

Warning: Reaching MaxJailedBlocks will result in a node’s entire stake being slashed.

MaxValidators

Current Value: 1000

The number of staked nodes that are eligible to be selected for producing blocks. Any staked nodes outside of the top MaxValidators staked validators will still be eligible to service relays.

MinSignedPerWindow

Current Value: 0.6

The minimum proportion of the SignedBlocksWindow that a node must sign to stay out of jail.

Info

If SignedBlocksWindow is 10 and MinSignedPerWindow is 0.6, this means a node can miss up to 4 blocks out of every 10 blocks before it is jailed.

ProposerPercentage

Current Value: 5

Block proposers earn this proportion of the total POKT block reward. Value is a percentage. See also DAOAllocation for another beneficiary of the block reward.

RelaysToTokensMultiplier

Current Value: 1077

The amount of POKT, denominated in StakeDenom, that is minted as block rewards per relay.

Note that this value will change over time. Please see the section on POKT inflation for more information.

ServicerStakeFloorMultiplier

Current Value: 15000000000

The “width” of a bin (in uPOKT) used when organizing nodes for Stake-Weighted Servicer Rewards.

All nodes with an amount of POKT staked that is both greater than the StakeMinimum and less than the value of this parameter will have the same reward multiplier. Nodes in subsequent multiples of this parameter (up to and including the ServicerStakeWeightCeiling) will have additionally higher reward multipliers.

ServicerStakeFloorMultiplierExponent

Current Value: 1

Determines how rewards scale for each bin used when organizing nodes for Stake-Weighted Servicer Rewards.

A value of 1 will cause the reward multiplier of the bins to scale linearly. Values greater than 1 will lead to higher bins having a non-linear greater reward multiplier, while values less than 1 will lead to higher bins having a non-linear lower reward multiplier.

ServicerStakeWeightCeiling

Current Value: 60000000000

Denotes the minimum value (in uPOKT) of the top bin, used when organizing nodes for Stake-Weighted Servicer Rewards. Any node with an amount of staked POKT at or above this value will have the highest available reward multiplier. Staking any more POKT will not incur any greater rewards (except as a Validator).

ServicerStakeWeightMultiplier

Current Value: 1.548

Offsets the increased reward emissions generated due to Stake-Weighted Servicer Rewards.

If the DAO determines that the amount of rewards generated is higher than desired, this will be set to an amount such that the reward multipliers of each of the bins are proportionally scaled down.

This parameter will likely change often due to its role in managing inflation.

SignedBlocksWindow

Current Value: 10

The number of consecutive blocks within which the MinSignedPerWindow proportion of blocks must be signed by a node to stay out of jail.

Info

If SignedBlocksWindow is 10 and MinSignedPerWindow is 0.6, this means a node can miss up to 4 blocks out of every 10 blocks before it is jailed.

SlashFractionDoubleSign

Current Value: 0.000001

The % of a node’s stake that is burned for double signing, where 1 is 100%.

SlashFractionDowntime

Current Value: 0.000001

The % of a node’s stake that is burned for downtime, where 1 is 100%.

StakeDenom

Current Value: upokt

POKT amounts are defined by the protocol. Read more about POKT denominations.

StakeMinimum

Current Value: 15000000000

The minimum stake required of a node, denominated in StakeDenom, for the economic security of the protocol.

UnstakingTime

Current Value: 1814000000000000

The time, in nanoseconds, that a node must wait after initiating an unstake before they can use the POKT for anything else.

Pocket Core Module

ClaimExpiration

Current Value: 24

The amount of time (in blocks) a node has to submit a proof for an already existing claim.

ClaimSubmissionWindow

Current Value: 3

The window of time (in Sessions) a node can submit a claimTx for RelayEvidence collected in the most recently ended session, before the claimTx expires. In addition, it is also the minimum amount of time a node must wait to submit a proof for an existing claim.

MinimumNumberOfProofs

Current Value: 10

The minimum number of relays a node must have for a claim and proof to be payable.

ReplayAttackBurnMultiplier

Current Value: 3

The multiplier slash factor for submitting a replay attack. The base slash is directly proportional to the amount of relays claimed.

SessionNodeCount

Current Value: 24

The number of nodes an app will be matched with in a session.

SupportedBlockchains

List of currently supported blockchains

Only blockchains with sybil-resistant demand from apps are whitelisted to generate revenue for nodes.

Auth Module

FeeMultiplier

Current Value: 1

The multiplier factor for each transaction type. The base transaction fee is universally set at 10,000 uPOKT.

MaxMemoCharacters

Current Value: 75

The character limit of transaction memos.

TxSigLimit

Current Value: 8

The maximum number of signatures that a multi-sig account can have.

Glossary

Application

Computer program that needs to read data from and/or send transactions to an external blockchain. Applications stake POKT into the Pocket Network Protocol in order to gain read/send access to the independent blockchain(s) that they need.

Applications are paired with groups of independent blockchain service providers, selected from Pocket’s decentralized network of thousands of service nodes. Applications can submit relays to the Servicers in this group to perform the needed read/send operations.

Application Authentication Token (AAT)

An Application Authentication Token (AAT) is needed for each client to authorize the use of an allocated “throughput”.

Application Authentication Tokens are similar in function to JSON Web Tokens (JWT) and provide security guarantees for the use of the service.

An AAT is generated after a client acquires & stakes POKT for an Application.

There are two design patterns recommended for AAT usage:

  • Optimizing for Safety: __ A simple server that distributes signed AAT’s using the clients Pocket Account. Though this pattern is of higher effort for the Application, it provides the highest security guarantee around their AAT
  • Optimizing for Performance: Embed a token production system within the Application code. This guarantees the smoothest UX for the clients and easiest setup for the Application. However, reverse engineering a source code level token generator can be trivial if obfuscation methods are not applied. The upside to this approach is not having the need to have an additional component in the Application that generates the AAT dynamically while keeping the Application private key secure.

Application Burn Rate (ABR)

Proposed mechanism that would burn developer’s stakes based on Application usage, and at a rate that offsets future inflation of the POKT cryptocurrency. Implementing ABR could help cap the total amount of POKT and promote network equilibrium where mint rate and burn rates are equal. For more information, see Monetary Policy.

Block Hash

SHA3-256 hash of a Block.

Endpoint

In the Pocket Portal, a URL that can receive RPC requests to a blockchain. Pocket allows you to “mint” endpoints that can be used with any of its supported blockchains. An Application can contain multiple endpoints (for multiple chains).

Jail

Situation where a Pocket node is denied the ability to serve relays.

A node can be jailed for one of two reasons:

  1. A node is not actively participating in consensus, for reasons such as being offline. More technically, this may occur if the node fails to produce min_signed_per_window amount of blocks over a signed_blocks_window. When jailed because of this reason, a node is Slashed a slash_fraction_downtime% of their Stake.
  2. A node “double signs” a block. Double signing is when a Validator node submits multiple signatures for the same block, which makes it more difficult for the network to come to consensus. When jailed because of this reason, a node is Slashed a slash_fraction_double_sign% of their Stake.

When a node becomes jailed, it remains in the Staked list of nodes, however it becomes ineligible to be selected for block production or to participate in Sessions. In order to become unjailed, the node must wait downtime_jail_duration nano-seconds, and then submit a Node Unjail transaction, which must then be approved.

If a node is left jailed for max_jailed_blocks blocks, it will be Force Unstaked.

PEP

Pocket Ecosystem Proposal. This is submitted to the Pocket DAO to distribute funds to or form agreements with contributors to the Pocket Network ecosystem. PEP categories include: Imbursements, Reimbursements, Bounties, Transfers, and Agreements. Each PEP is given a unique number as a suffix (such as PEP-13).

PIP

Pocket Improvement Proposal. This is submitted to the Pocket DAO to upgrade any facet of Pocket Network, including protocol and governance updates. Each PIP is given a unique number as a suffix (such as PIP-11).

POKT

Native cryptocurrency that underpins Pocket. Node runners stake POKT in order to earn rewards (also in POKT) from servicing relays from apps that utilize the Pocket Network. For example: “If you stake a Pocket node, you can earn POKT for every successful relay.”

Portal

A browser-based interface where developers can create (“mint”) a Pocket endpoint for use in their applications, utilizing a generous free tier of relays and scaling up as needed. Portal users can also monitor network performance.

Portal ID

Unique identifier for a collection of endpoints generated by the Pocket Portal. It is included as part of the URL of each endpoint.

Private RPC

RPC server that requires credentials for access.

Public Key

Unique identifier for a given Application that will allow you to inspect the Application on-chain.

Public RPC

RPC server that is accessible to the network without requiring credentials for access.

PUP

Parameter Update Proposal. This is submitted to the Pocket DAO to change the value of a given protocol parameter, either on-chain or in various tools or platforms. Each PUP is given a unique number as a suffix (such as PUP-11)

Relay

Blockchain API request and response transmitted through the Pocket Network.

A Relay Request is broken down into 3 sections:

  • Request Payload
  • Metadata
  • Proof (of Relay)

A Relay Response is broken down into 2 sections:

  • Response Payload
  • Servicer Signature

Requests are signed by the client of the Application and responses are signed by the servicing Validator.

This one-to-one signature scheme enables the protocol to validate all parties that participate in the servicing cycle.

Relay Chain

Database instance, typically a blockchain, provided by a Servicer node to serve Applications. Also can refer to both the database and the client that keeps the database updated and can accept read/send operations to that database.

Relay Evidence

Provable evidence of a Relay completed, backed by digital signatures from an Application client.

RelaysToTokensMultiplier

On-chain parameter that signifies the amount of POKT that is awarded to a node for a single successful relay. This value is periodically adjusted in line with Pocket Network’ monetary policy.

Remote Procedure Call (RPC)

Standardized process where one computer on a network is able to send a request to another computer on the network, to execute a command as if it were called locally from the computer. Many blockchains communicate by means of RPC.

Secret Key

Security feature for Applications created in the Pocket Portal. If “Private Secret Key Required” is selected in the Pocket Portal, then the Secret Key will need to be sent along with the request using HTTP Basic Authentication.

Servicer

Any node which is eligible to serve RPC requests for Applications. By default, a node is a Servicer.

ServiceURI

The endpoint that Servicers expose to provide Applications the functionality they need to send relays via the Pocket Network RPC to said Servicer.

Session

A data structure which uses data from the finality storage layer of the network to pseudo-randomly group one Application with a set of nodes to provide service for a limited time. A Session lasts for 4 blocks, for a total of one hour.

Every Application will only have one single Session per relay chain it is staked for. Meaning, following an Application stake event, there will always be a corresponding Session for the Application for each relay chain until it unstakes.

List of Servicers that an Application is able to send requests to for a period of time. The Pocket blockchain periodically updates the Sessions so Applications receive a new, pseudo-randomly selected set of Servicers every four (4) blocks (determined by the BlocksPerSession parameter), or approximately one hour, for each Relay Chain that the Application is staked for. During this period of time, the Servicers will only be rewarded POKT for servicing Applications if they have been matched in a Session. The amount of Servicers in a Session is currently 24 (determined by the SessionNodeCount parameter).

Session Block

Some number of blocks, marking Session beginning/ends.

Stickiness

A feature that lets you connect to the same node for a set period of time. With stickiness all the relays are sent to the same node, ensuring more consistent relays.

Trophy

Achievement earned for proving knowledge of and participation in the Pocket Network ecosystem. These can be collected and used to earn a vote in the Pocket DAO. There are four distinct paths to a vote, each with different trophies: App Developers, Node Runners, Community Shepherds, and Governors/Contributors.

v0

Current active iteration of the Pocket protocol. Often used in contrast to the upcoming v1 update.

v1

Pocket v1 (or just “v1”) is a major planned overhaul of the Pocket Network protocol, including a departure from Tendermint. v1 will allow Pocket to build its own network from the ground up, optimized for its specific use case, rather than being restricted by any limitations that come with building on Tendermint. v1 will bring major changes to four different “modules”: Utility, Consensus, Peer-to-Peer, and Persistence.

Validator

Special nodes that are responsible for committing new blocks in the blockchain, in addition to Servicing. Validators participate in the consensus protocol by broadcasting votes which contain cryptographic signatures signed by each Validator’s private key.

Validators stake POKT into the protocol to participate in Servicing and Consensus, just like Servicers, but because they are able to be block proposers, they can earn a slightly higher reward amount, as determined by the ProposerPercentage parameter.

Only the top 1,000 Servicers ordered by total POKT staked are considered Validators.

WAGMI

Weighted Annual Gross Max Inflation (WAGMI) is an inflation control mechanism for the Pocket Network that was established via PUP-11, and further defined via PUP-13. Together, these proposals established a target annual inflation rate, or WAGMI rate, in POKT, from which the RelaysToTokensMultiplier parameter (which determines the amount of POKT earned per relay serviced) is adjusted dynamically. The proposals also laid out a step-down in target inflation rate from 100% to 50% over a period of time.

Whitelisted Chains

In the Pocket Portal, an exclusive list of the blockchains that an Application can connect to. For example, if four chains are whitelisted, there will be four endpoints generated in that Application.

Whitelisted Contracts

In the Pocket Portal, an exclusive list of smart contract addresses that can access an Application endpoint. Note that this is only available for EVM-compatible chains.

Whitelisted Methods

In the Pocket Portal, an exclusive list of smart contract methods that can be used when accessing an Application endpoint. Note that this is only available for EVM-compatible chains.

Whitelisted Origins

In the Pocket Portal, an exclusive list of the HTTP Origin request headers that are allowed to make requests to the endpoint.

Whitelisted User-Agents

In the Pocket Portal, an exclusive list of HTTP User-Agent request headers that are allowed to make requests to the endpoint.

wPOKT

Wrapped POKT (wPOKT) is a proposed ERC-20 token backed by the native POKT cryptocurrency on the Pocket Network blockchain. Wrapped POKT would standardize POKT to the ERC-20 standard, enabling better interoperability, greater liquidity, and access to smart contracts.

Wrapped POKT is not anticipated to be launched until after the release of the new Pocket v1 architecture.

Use Pocket

Public RPC Endpoints

How to Customize Your Endpoint (e.g. MetaMask)

To change your endpoint in MetaMask, do the following, filling in the fields from the table below:

  1. Click on the Networks drop-down menu, then press Add Network
  2. Under the Network Name field, write <Network Name> Pocket Portal
  3. Within the New RPC URL field, copy and paste <RPC URL>
  4. (Optional) Put <ChainID> in the ChainID field
  5. (Optional) Write <Symbol> as the Symbol
  6. (Optional) Add <Explorer URL> as the Block Explorer URL
  7. Don’t forget to save
Info

If you receive this error message from MetaMask Invalid number. Enter a decimal or '0x'-prefixed hexadecimal number then leave the optional fields blank.

Endpoints

Network NameRPC URLChainIDSymbolExplorer URL
Algorandhttps://algo-mainnet-rpc.gateway.pokt.networkALGOhttps://algoexplorer.io
Avalanchehttps://avax-rpc.gateway.pokt.network43114AVAXhttps://cchain.explorer.avax.network
Binance Smart Chainhttps://bsc-rpc.gateway.pokt.network56BNBhttps://bscscan.com
Binance Smart Chain Archivalhttps://bsc-archival-rpc.gateway.pokt.network56BNB
Bobahttps://boba-rpc.gateway.pokt.network288ETHhttps://blockexplorer.boba.network
DFK Chainhttps://avax-dfk-rpc.gateway.pokt.network53935JEWELhttps://subnets.avax.network/defi-kingdoms/dfk-chain/explorer
Ethereumhttps://eth-rpc.gateway.pokt.network1ETHhttps://etherscan.io
Ethereum Archivalhttps://eth-archival-rpc.gateway.pokt.network1ETH
Ethereum Goerlihttps://eth-goerli-rpc.gateway.pokt.network5ETHhttps://goerli.etherscan.io
Ethereum Kovanhttps://eth-kovan-rpc.gateway.pokt.network42ETHhttps://kovan.etherscan.io
Ethereum Rinkebyhttps://eth-rinkeby-rpc.gateway.pokt.network4ETHhttps://rinkeby.etherscan.io
Ethereum Ropstenhttps://eth-ropsten-rpc.gateway.pokt.network3ETHhttps://ropsten.etherscan.io
Ethereum Tracehttps://eth-trace-rpc.gateway.pokt.network1ETH
Evmoshttps://evmos-rpc.gateway.pokt.network9001EVMOShttps://evm.evmos.org
Fantomhttps://fantom-rpc.gateway.pokt.network250FTMhttps://ftmscan.com
FUSEhttps://fuse-rpc.gateway.pokt.network122FUSEhttps://explorer.fuse.io
FUSE Archivalhttps://fuse-archival-rpc.gateway.pokt.network122FUSE
Gnosis Chainhttps://gnosischain-rpc.gateway.pokt.network100xDAIhttps://blockscout.com/poa/xdai
Gnosis Chain Archivalhttps://gnosischain-archival-rpc.gateway.pokt.network100xDAI
Harmony Shard 0https://harmony-0-rpc.gateway.pokt.network1666600000ONEhttps://explorer.harmony.one
IoTeXhttps://iotex-rpc.gateway.pokt.network4689IOTXhttps://iotexscan.io
Klaytnhttps://klaytn-rpc.gateway.pokt.network8217KLAYhttps://scope.klaytn.com
Moonbeamhttps://moonbeam-rpc.gateway.pokt.network1284GLMRhttps://moonscan.io
Moonriverhttps://moonriver-rpc.gateway.pokt.network1285MOVRhttps://moonriver.moonscan.io
NEARhttps://near-rpc.gateway.pokt.networkNEARhttps://www.nearscan.org
OKXChainhttps://okc-rpc.gateway.pokt.network66OKThttps://www.oklink.com/en/okc
Optimismhttps://optimism-rpc.gateway.pokt.network10ETHhttps://optimistic.etherscan.io
Osmosishttps://osmosis-rpc.gateway.pokt.networkOSMOhttps://www.mintscan.io/osmosis
Pocket Networkhttps://pokt-rpc.gateway.pokt.networkPOKThttps://explorer.pokt.network
Polygonhttps://poly-rpc.gateway.pokt.network137MATIChttps://polygonscan.com
Polygon Archivalhttps://poly-archival-rpc.gateway.pokt.network137MATIC
Polygon Mumbaihttps://polygon-mumbai-rpc.gateway.pokt.network80001MATIC
Solanahttps://solana-mainnet-rpc.gateway.pokt.networkSOL
Swimmer Network Mainnethttps://avax-cra-rpc.gateway.pokt.network73772TUShttps://explorer.swimmer.network

Avalanche (AVAX)

We have created a public Avalanche RPC endpoint with up to 1M requests per day to give people who use Metamask the opportunity to connect to Pocket’s decentralized, censorship-resistant infra.

To get started connecting to Pocket’s infrastructure for Avalanche C-Chain, do the following:

  1. Click on the Networks drop-down menu, then press Custom RPC
  2. Under the Network Name field, write Avalanche Pocket Portal
  3. Within the New RPC URL field, copy and paste this endpoint URL https://avax-mainnet.gateway.pokt.network/v1/lb/605238bf6b986eea7cf36d5e/ext/bc/C/rpc
  4. Put the hexadecimal 0xa86a or decimal 43114 in the ChainID field
  5. Write AVAX as the Symbol
  6. Add https://cchain.explorer.avax.network/ as the Block Explorer URL
  7. Don’t forget to save

Binance Smart Chain (BSC)

We have created a public BSC RPC endpoint with up to 1M requests per day to give people who use Metamask the opportunity to connect to Pocket’s decentralized, censorship-resistant infra.

To get started connecting to Pocket’s infrastructure for BSC, do the following:

  1. Click on the Networks drop-down menu, then press Custom RPC
  2. Under the Network Name field, write BSC Pocket Portal
  3. Within the New RPC URL field, copy and paste this endpoint URLhttps://bsc-mainnet.gateway.pokt.network/v1/lb/6136201a7bad1500343e248d
  4. Put the decimal 56 in the ChainID field
  5. Write BNB as the Symbol
  6. Add https://bscscan.com as the Block Explorer URL
  7. Don’t forget to save

Connecting MetaMask to DFK Chain

For those who play Defi Kingdoms, you can use Pocket’s public RPC endpoint for DFK Chain and take advantage of Pocket’s decentralized infrastructure.

There are two ways to connect your MetaMask wallet to DFK Chain. Choose whichever method you prefer.

Chainlist

  1. Navigate to https://chainlist.org/?search=dfk, or go to Chainlist and search for “dfk”.
  2. Click the down arrow under DFK Chain to expand the entry.
  3. In the row with the URL that begins with htps://avax-dfk.gateway.pokt.network... click Connect Wallet. (You may need to scroll the window to the right to see this.)
  4. Click Add to MetaMask.
  5. When prompted, click Approve in the MetaMask interface.

Add manually

  1. In MetaMask, click the Networks drop-down menu, then select Custom RPC.
  2. Under the Network Name field, type DFK Chain POKT.
  3. Within the New RPC URL field, copy and paste this endpoint URL:
    • https://avax-dfk.gateway.pokt.network/v1/lb/6244818c00b9f0003ad1b619//ext/bc/q2aTwKuyzgs8pynF7UXBZCU7DejbZbZ6EUyHr3JQzYgwNPUPi/rpc
  4. In the ChainID field, type 53935.
  5. For the Symbol, type JEWEL.
  6. For the Block Explorer URL, add https://subnets.avax.network/defi-kingdoms/dfk-chain/explorer.
  7. Save changes.

Ethereum (ETH)

We have created a public Ethereum RPC endpoint with up to 10M requests per day to give people who use Metamask the opportunity to connect to Pocket’s decentralized, censorship-resistant infra.

To get started connecting to Pocket’s infrastructure for Ethereum mainnet, do the following:

  1. Click on the Networks drop-down menu, then press Custom RPC
  2. Under the Network Name field, write Ethereum Pocket Portal
  3. Within the New RPC URL field, copy and paste this endpoint URL https://eth-rpc.gateway.pokt.network
  4. Put the decimal 1 in the ChainID field
  5. Write ETH as the Symbol
  6. Add https://etherscan.io as the Block Explorer URL
  7. Don’t forget to save

Evmos

We have minted a public Evmos RPC endpoint to give people who use Metamask the opportunity to connect to Pocket’s decentralized, censorship-resistant infrastructure.

To get started connecting to Pocket’s infrastructure for Evmos, do the following:

  1. Click on the Networks drop-down menu, then press Custom RPC.
  2. Under the Network Name field, write Evmos Pocket Portal.
  3. Within the New RPC URL field, copy and paste this endpoint URL https://evmos-rpc.gateway.pokt.network.
  4. Put the decimal 9001 in the ChainID field.
  5. Write EVMOS as the Symbol.
  6. Add https://evm.evmos.org/ as the Block Explorer URL.
  7. Don’t forget to save.

Fuse

We have created a public Fuse RPC endpoint with up to 3M requests per day to give people who use Metamask the opportunity to connect to Pocket’s decentralized, censorship-resistant infra.

To get started connecting to Pocket’s infrastructure for Fuse, do the following:

  1. Click on the Networks drop-down menu, then press Custom RPC
  2. Under the Network Name field, write Fuse Pocket Portal
  3. Within the New RPC URL field, copy and paste this endpoint URL https://fuse-rpc.gateway.pokt.network/
  4. Put the hexadecimal 0x7a in the ChainID field
  5. Write FUSE as the Symbol
  6. Add https://explorer.fuse.io as the Block Explorer URL
  7. Don’t forget to save

Gnosis Chain (xDAI)

We have minted a public Gnosis RPC endpoint to give people who use Metamask the opportunity to connect to Pocket’s decentralized, censorship-resistant infra.

To get started connecting to Pocket’s infrastructure for xDAI, do the following:

  1. Click on the Networks drop-down menu, then press Custom RPC
  2. Under the Network Name field, write Gnosis Pocket Portal
  3. Within the New RPC URL field, copy and paste this endpoint URL https://gnosischain-rpc.gateway.pokt.network/
  4. Put the hexadecimal 0x64 in the ChainID field
  5. Write XDAI as the Symbol
  6. Add https://blockscout.com/poa/xdai as the Block Explorer URL
  7. Don’t forget to save

Harmony

We have created a public Harmony RPC endpoint for applications and end-users to utilize!

To get started connecting to Pocket’s infrastructure for Harmony Mainnet Shard 0, do the following:

  1. Click on the Networks drop-down menu, then press Custom RPC
  2. Under the Network Name field, write Harmony Mainnet 0 POKT Portal
  3. Within the New RPC URL field, copy and paste this endpoint URL https://harmony-0-rpc.gateway.pokt.network
  4. Put the decimal 1666600000 in the ChainID field
  5. Write ONE as the Symbol
  6. Add https://explorer.harmony.one as the Block Explorer URL
  7. Don’t forget to save

Use the provided RPC URL of Shard 0 if you want to send/receive transactions from exchanges or do any staking transaction type.

For information on how to use Metamask with Harmony, please reference Harmony’s documentation.

IoTeX

We have minted a public IoTeX RPC endpoint with up to 1M requests per day to give people who use Metamask the opportunity to connect to Pocket’s decentralized, censorship-resistant infra.

To get started connecting to Pocket’s infrastructure for IoTeX, do the following:

  1. Click on the Networks drop-down menu, then press Custom RPC
  2. Under the Network Name field, write IoTeX Pocket Portal
  3. Within the New RPC URL field, copy and paste this endpoint URL https://iotex-mainnet.gateway.pokt.network/v1/lb/6176f902e19001003499f492
  4. Put the decimal 4689 in the ChainID field
  5. Write IOTX as the Symbol
  6. Add https://iotexscan.io as the Block Explorer URL
  7. Don’t forget to save

Polygon

We have created a public Polygon RPC endpoint with up to 5M requests per day to give people who use Metamask the opportunity to connect to Pocket’s decentralized, censorship-resistant infra.

More details here:

https://forum.matic.network/t/pocket-network-creates-free-polygon-rpc-community-endpoints/1597

To get started connecting to Pocket’s infrastructure for Polygon, do the following:

  1. Click on the Networks drop-down menu, then press Custom RPC
  2. Under the Network Name field, write Polygon Pocket Portal
  3. Within the New RPC URL field, copy and paste this endpoint URL https://poly-rpc.gateway.pokt.network/
  4. Put the decimal 137 in the ChainID field
  5. Write MATIC as the Symbol
  6. Add https://polygonscan.com as the Block Explorer URL
  7. Don’t forget to save

Pocket-Powered dApps

Conquest.eth

We have minted a public Görli RPC endpoint with up to 10M requests per day to give players who are exploring the Conquest metaverse the opportunity to connect to Pocket’s decentralized, resilient infra!

To get started connecting to Pocket’s infrastructure for Görli testnet, do the following:

  1. Click on the Networks drop-down menu, then press Custom RPC
  2. Under the Network Name field, write Görli Pocket Portal
  3. Within the New RPC URL field, copy and paste this endpoint URL https://eth-goerli.gateway.pokt.network/v1/lb/619f72f64df71a00392de6d9
  4. Put the decimal 5 in the ChainID field
  5. Don’t forget to save

For instructions on how to get started with Conquest, check out their documentation and video.

Join Etherplay’s discord for early alpha access to the Conquest game!

Dark Forest

We have issued an xDAI RPC endpoint that grants up to 50M requests per day (& 250 nodes per hour) just for Dark Forest players!

To get started connecting to Pocket’s node infrastructure for xDAI in Dark Forest, do the following:

  1. Click on the gear icon to open the settings page
  2. If it doesn’t open automatically, click on “+” icon to expand the settings page
  3. Scroll down until you see the “Change RPC Endpoint” section
  4. Copy and paste this endpoint URL into the text boxhttps://poa-xdai.gateway.pokt.network/v1/lb/60b13899d3279c22da2a444d``
  5. Click “Change RPC URL” to Save
  6. Make a move!

MyCrypto

MyCrypto is an open-source, client-side tool for generating Ethereum wallets, handling ERC-20 tokens, and interacting with the blockchain more easily. Developed by and for the community since 2015, they’re focused on building awesome products that put the power in people’s hands.

This is why we want to give users an opportunity to connect to our own infrastructure!

  1. Open the MyCrypto desktop application, if you don’t have it yet, then download it here: https://download.mycrypto.com
  2. Find “Change Network” on the bottom left-hand side of the menu, then click on it.
  3. Under “Show Other Networks”, click “+Add Custom Node” to bring up the “Set Up Your Custom Node” menu.
  4. In the “Node Name” field, write Pocket Network Gateway
  5. Keep the Network set to ETH (Ethereum)
  6. Then, copy and paste in the Endpoint URL: https://eth-mainnet.gateway.pokt.network/v1/5f46739e2164c49f99af2480
  7. Do not check the HTTP Basic Authentication box
  8. Then, press the “Save & Use Custom Node” button
  9. Use Decentralized Infra

Rotki

Rotki is an open-source portfolio tracker and accounting/analytics tool that protects your privacy.

We’ve sponsored a public Ethereum RPC endpoint for Rotki users in order to add an extra layer of privacy when using the application.

To get started connecting to Pocket’s censorship-resistant infrastructure for Ethereum, do the following:

  1. Open and login into your local application.

2. Toggle to account, then open settings.

3. Scroll down to the Local Nodes section, then delete the default RPC endpoint.

4. Copy & Paste this URL into the Ethereum Node RPC Endpoint field:

https://eth-mainnet.gateway.pokt.network/v1/lb/615541c96ad539003506595e

Reference the Rotki User Guide for additional support.

Run Nodes

In this section, you’ll get information on running a Pocket node.

These details are mostly for “intermediate” node runners, who are familiar with running full nodes and have the knowledge required to avoid getting lost. If you would like a more beginner’s tutorial, visit Zero To Node. You may also want to explore node-hosting services.

Want to understand the economics of running a node before you dive in? Read about Node Economics.

Read our guide to decide whether you want your nodes to be operated with custodial staking or non-custodial staking.

For a no-frills guide to commands, you should head over to Pocket Core on GitHub.

Environment Setup

This section will detail the hardware and software needed to run a Pocket node.

Hardware

Hardware Requirements: 4 CPU’s (or vCPU’s) | 16 GB RAM | 200GB Disk

Info

These are just the hardware requirements for your Pocket node. You’ll also need to run the full nodes of other blockchains, which may have their own hardware requirements that surpass Pocket’s.

Software

There are three ways to install the software you need to run Pocket Network.

Source

Install your dependencies

Create source code directory

mkdir -p $GOPATH/src/github.com/pokt-network && cd $GOPATH/src/github.com/pokt-network

Download the source code

git clone https://github.com/pokt-network/pocket-core.git && cd pocket-core

Checkout the latest release

git checkout tags/<release tag>
git checkout tags/RC-0.8.2

Make sure you have $GOPATH setup

echo $GOPATH
/Users/<your username>/go

Build your binary and put it in the $GOPATH/bin directory

go build -o <$GOPATH/bin directory> <source code directory>/...
go build -o $GOPATH/bin/pocket $GOPATH/src/github.com/pokt-network/pocket-core/app/cmd/pocket_core/main.go

Test your installation

pocket version
> RC-0.8.2
Info

Check your version number against the latest release here.

Homebrew

Install your dependencies

Install using Homebrew

brew tap pokt-network/pocket-core && brew install pokt-network/pocket-core/pocket

Test your installation

pocket version
> RC-0.8.2

Docker

See pokt-network/pocket-core-deployments

Environment

  • Reverse Proxy: For SSL termination and request management
  • Ports: Expose Pocket RPC (Default :8081) and P2P port (Default: 26656)
  • SSL Cert: Required for Validator’s serviceURI

Set your Open Files Limit

ulimit -Sn 16384
Warning

This Open Files Limit is set based on the standard config provided with Pocket Core in <datadir>/config/config.json. If you modify your config, you will need to ensure that you modify your Open Files Limit too, according to the formula below.

The required ulimit can be calculated using this formula:

({ulimit -Sn} >= {MaxNumInboundPeers} + {MaxNumOutboundPeers} + {GRPCMaxOpenConnections} + {MaxOpenConnections} + {Desired Concurrent Pocket RPC connections} + {100 (Constant number of wal, db and other open files)}

Secure your Server

Make sure the server that hosts your node is protected by up-to-date anti-virus and anti-malware software. Protect your node with a firewall but make sure to maintain login access for yourself and keep the above ports open.

Node Setup

Deploy Your Validator & Full Nodes

Create an account

An account is needed to participate at any level of the network.

pocket accounts create
> Enter Passphrase
> Account generated successfully:
> Address: <address>
Info

Alternatively, you can create your account using the Wallet app, then use the encrypted import command to import the account into your node environment:

pocket accounts import-armored </path/to/ppk.json>

Backup the account

Backup your private key to an encrypted and ASCII armored json file, to the specified --path , using the secure export command. After you hit enter, you will be prompted for the decrypt passphrase and an encryption passphrase for the exported account. You will also have the option to add a hint to help remember your passphrase.

pocket accounts export <address> --path <path>
pocket accounts export 59f08710afbad0e20352340780fdbf4e47622a7c --path /$HOME/super-secret-dir
Warning

Do not use your node’s account as your personal account address. Since the node’s private key is stored in plaintext on the server, the key is as secure as your server is. Regularly sweep your node’s rewards and transfer them to a more secure account stored offline.

Learn more about securely managing your POKT accounts.

Fund the account

To stake a Validator in Pocket Network, the account must have a balance above the minimum stake:

15,000 POKT or 15,000,000,000 uPOKT

The absolute minimum node stake (15,000 POKT) is not practical for real-world usage. 15,100 is a reasonable buffer against operational slashes which can occur on seemingly properly configured nodes as well as misconfigured and misbehaving ones.

Send POKT with the following command:

pocket accounts send-tx <fromAddr> <toAddr> <uPOKT amount> mainnet 10000 ""

You won’t be able to send POKT using your CLI until you have a Validator set up. Until then, you can use the Wallet app.

If you’re using the testnet, you can fund your account using the Testnet Faucet.

Set the account as Validator

pocket accounts set-validator <address>
Info

Check that it worked with pocket accounts get-validator

Set Relay Chains

A Relay Chain is the blockchain that Validators are running full nodes for in service of Applications. Apps access Relay Chains through the serviceURI, the endpoint where Validators publicly expose the Pocket API.

pocket util generate-chains
> Enter the chain of the network identifier:
<Relay Chain ID> (Example: 0001)
> Enter the URL of the network identifier:
<Secure URL to Relay Chain>
Would you like to enter another network identifier? (y/n)
n
Info

RelayChainIDs can be found here.

Setup the Genesis Configuration File

Genesis files can be found here:

The appropriate genesis file should be placed at $HOME/.pocket/config/genesis.json

mkdir -p "$HOME"/.pocket/config
curl -o "$HOME"/.pocket/config/genesis.json https://raw.githubusercontent.com/pokt-network/pocket-network-genesis/master/mainnet/genesis.json
mkdir -p "$HOME"/.pocket/config
curl -o "$HOME"/.pocket/config/genesis.json https://raw.githubusercontent.com/pokt-network/pocket-network-genesis/master/testnet/genesis.json

Test your node

Test that your node is configured correctly by simulating a relay.

pocket start --simulateRelay

Then send a curl request to your validator URL http://<your node>:<your pocket rpc port>/v1/client/sim to test if your node responds.

curl -X POST --data '{"relay_network_id":"<relay chain ID from chains.json>","payload":{"data":"{\"jsonrpc\":\"2.0\",\"method\":\"eth_getBalance\",\"params\":[\"0xe7a24E61b2ec77d3663ec785d1110688d2A32ecc\", \"latest\"],\"id\":1}","method":"POST","path":"","headers":{}}}' <your node URL>:8081/v1/client/sim

200 OK – your transaction has gone through

400 Bad Request – you either have incorrect/missing parameters in the request or bad formatting in the data field

Finally, stop your node. If you don’t, you’ll be leaving –simulateRelay running, which means anyone will have unfiltered access to your node.

Download the Latest Snapshot

Downloading from the latest snapshot will drastically shorten the time it takes to sync the blockchain. The easiest way is by downloading with wget and extracting the archive as it downloads.

mkdir -p "$HOME"/.pocket/data
wget -qO- https://snapshot.nodes.pokt.network/latest.tar.gz | tar -xz -C "$HOME"/.pocket/data

Other options for downloading the latest snapshot can be found in the pocket-snapshotter repo.

Sync the blockchain

pocket start --seeds=<seeds> --mainnet
pocket start --seeds="64c91701ea98440bc3674fdb9a99311461cdfd6f@node1.mainnet.pokt.network:21656" --mainnet

See the section on seeds for more details.

Warning

Ensure the node is all the way synced before proceeding to the next step.

Stake the Validator

Stake the account to participate in the Network as a Validator. Staking a Validator locks up POKT tokens that can be burned as a security mechanism for bad acting.

pocket nodes stake custodial <address> <amount> <relay_chains> <serviceURI> mainnet 10000 false
pocket nodes stake custodial 3ee61299d5bbbd2974cddcc194d9b547c7629546 20000000000 0001,0002 https://pokt.rocks:443 mainnet 10000 true

You should leave 1 POKT liquid (unstaked) to pay the transaction fees for your node’s claim and proof transactions.

All node runners must always maintain a liquid (unstaked) balance of at least 0.02 POKT in order to submit the claim and proof transactions (which each have a transaction fee of 0.01 POKT) that generate their rewards. If a node successfully submits both the claim and proof, they will earn enough POKT to submit the next claims and proofs, and so on. However, if a node falls below a liquid balance of 0.02 POKT, their revenue will be halted.

Claim transactions have 3 sessions, the ClaimSubmissionWindow, to be successfully submitted after the conclusion of the session in which the work was done, otherwise they are lost. If a claim transaction fails, Pocket Core will auto-repeat the transaction once in each new session, until the claim is lost. This means your node will automatically take 3 attempts to submit the claim. There is a claim submission window because the global secret key that determines the required proof leaf is revealed once that window closes. Extending the claim submission window would delay the time at which the corresponding proof can be sent and rewards earned.

If you manage to successfully submit the claim transaction, you then have 120 blocks, the ClaimExpiration period, to submit the corresponding proof transaction, otherwise the pending claim expires. There is a claim expiration date because otherwise the claims would remain in the state and bloat the blockchain.

Warning

Bad Behavior Warning: Pre-staking

Pre-staking is the act of a node runner staking on a RelayChainID prior to spinning up the RelayChain node. This behavior has an extremely negative impact on the quality of service for new chains due to apps being matched in sessions with Pocket nodes that don’t actually have RelayChain nodes connected to them. If you do this, your node will be challenged and slashed. You should always deploy your RelayChain node and simulate relays before staking your Pocket node for the RelayChainID.

If your stake falls below 15,000 POKT your node will be force-unstake burned. We recommend having a buffer above the 15,000 minimum (e.g. 15,100-16,000) so that minor slashing doesn’t result in loss of the entire stake.

** Achievement Unlocked**

If you staked your node successfully, you just earned your first trophy, which can help you ultimately earn a vote in the DAO. Learn more about how to claim your vote.

Upgrade Your Node

Release-specific Changes

Each release may have specific modifications you need to make. This is just a general guideline for the steps you’ll typically take to upgrade your node. Check the release notes for release-specific details.

1. Shutdown Pocket Core

Stop your Pocket Core instance running by submitting the shutdown command.

pocket stop
Warning

Once you shutdown Pocket Core, you will have 4 blocks (60 minutes) to complete the upgrade and start Pocket Core again before your node gets jailed for downtime.

2. Backup Your Blockchain Data

Backing up your blockchain data will ensure a faster resync when you restart your node.

Navigate inside your $HOME/.pocket/ dir and save data/ (the entire directory):

cp -r ~/.pocket/data ~/backup/data

In the event of a corrupted database you can delete the bad data rm -r ~/.pocket/data and replace it with your backup cp -r ~/backup/data ~/.pocket/data.

Info

If you don’t have a backup, a temporary backup datadir may be provided alongside a release.

3. Ensure the Latest Golang Version

Check your golang version. The release notes will specify which version it should be.

go version

If you need to upgrade, use this guide.

Alternatively, if you use g, you can just run

sudo apt-get update
g install <version number>

4. Rebuild or Upgrade Your Binary

Source

Navigate into pocket-core directory

cd ~/go/src/github.com/pokt-network/pocket-core

Checkout the latest release

git pull
git checkout tags/<release tag>

Rebuild the binary

go build -o $GOPATH/bin/pocket ./app/cmd/pocket_core/main.go

Homebrew

Pull the latest tap

brew upgrade pokt-network/pocket-core/pocket

Docker

Pull the latest container image

docker pull poktnetwork/pocket-core:RC-0.8.2
docker pull poktnetwork/pocket:RC-0.8.2

5. Upgrade Your config.json

Run the update-configs command, which creates a new config file (DATADIR/config/config.json) and backs up the old config file (DATADIR/config/config.json.bk).

pocket util update-configs

You’ll need to manually compare your backup file with the new file to copy over your personal config details.

6. Start Pocket

Start pocket running again.

pocket start

Earn Trophies, Join the DAO

You can earn a vote in the DAO and help shape the future of Pocket Network, including deciding which ecosystem tooling our treasury supports and how we configure important on-chain parameters such as node revenue.

Once you’ve staked your node successfully, join our Discord and report this in the 🏆trophies channel.

This is your first trophy on the path to earning a vote in the DAO. Learn more on the Node Runners page.

Custodial and non-custodial staking

New in version 0.8.0

Pocket has added the ability for node runners to set up their nodes to run with “non-custodial” staking. This means that the Pocket address that is associated with staking and running the node is not the recipient of the funds once the node is unstaked.

This feature is currently inactive, and will be set to be active at a later date.

Node runners who staked their nodes prior to this activation date will have one opportunity to decide if they want their nodes to have custodial staking or non-custodial staking. After this point, if they wish to switch between the two options, they will need to unstake/restake their node.

Custodial staking

Custodial staking is the process of having the operator of the node be the recipient of the rewards of that node. This is true regardless of whether the node is a servicer or a validator.

In this scenario, only one Pocket account is needed to run a node. This account handles all aspects of node maintenance such as staking, editing the stake, unjailing, and unstaking.

Prior to version 0.8.0, this was the only option that node runners had.

Non-custodial staking

Non-custodial staking is the process of having the operator of the node be a different account from the account that receives the rewards.

In this scenario, there are two Pocket accounts necessary to the staking of a node. One account, the operator account, performs the staking, and can perform any and all node maintenance. The other account, known as the “output” account, is designated to receive the rewards that are unlocked when a node is unstaked. The output account can also initiate the staking.

In addition, this output account has much the same authority over the node as the operator account. The output account can also run node transactions (stake, unstake, unjail, etc.).

Benefits of non-custodial staking

An operator address must reside in a “hot” wallet on the node. This could potentially represent a security risk when the server is operated by a third-party. As third-party node hosting is common, there has arisen a need to have the recipient wallet for rewards not be on the same server as the node.

Non-custodial staking allows for this. All you need to specify is the wallet (“output”) address, which is denoted when staking the node. The wallet can reside off the server.

Another benefit to non-custodial staking is the ability to pool rewards into a single account. Since each node has to have a distinct operator account, this would previously have resulted in rewards being split across multiple wallets, which is inconvenient for a node runner with many nodes.

Commands

The command for staking a node was updated for version 0.8.0 and includes extra parameters. Note that before non-custodial staking becomes active, the custodial command is the only one that will be successful.

Custodial staking:

pocket nodes stake custodial <fromAddr> <amount> <relayChainIDs> <serviceURI> <networkID> <fee> <isBefore8.0>

Non-custodial staking:

pocket nodes stake non-custodial <operatorPublicKey> <outputAddress> <amount> <RelayChainIDs> <serviceURI> <networkID> <fee> <isBefore8.0>

Some notes on these commands:

  • The parameter custodial or non-custodial sets this permanently on your node. You can’t change this later unless you unstake.

  • The flag <isBefore8.0> is boolean. It exists as a transitional variable to denote whether or not the non-custodial activation has occurred. Before activation, you need to set this to true. After activation, you will need to set this to false. Failure to set this correctly will result in the transaction being rejected, with a delay of upwards of one block time to see this rejection.

  • Be aware that the non-custodial command takes the <operatorPublicKey> as the argument, not the operator address (<fromAddr>) like in the custodial command. The reason why the public key is used and not the address is for the situation where the owner of the output address is doing the staking, but does not also have ownership of the operator account. In this case, they may only have the public key for that account.

  • The non-custodial command adds <outputAddress> as the recipient of the staking rewards.

For more information on the full usage of these commands, please see the Pocket Core docs.

Important for existing nodes

If you have a node that was staked prior to the activation of non-custodial staking, you have only one opportunity to switch to non-custodial staking.

Any pocket node command successfully issued (for example, to adjust the stake) will “lock” the node into custodial, unless a non-custodial command is issued with a valid output address. Following this, the only way to switch between custodial and non-custodial is to unstake/restake the node (and recall that there is a 21 day unstake period).

Important for all nodes

Be very careful entering the output address. You cannot change the output address after it is set. If you accidentally mistype the output address, your funds and your stake will be sent to that address and will be lost forever.

If you wish to change your output address, you can first unstake the node, and the rewards will be sent to that address. Then you can restake the node with a new output address.

More information

Seeds

Seed nodes enable newly configured nodes to find peers on the network and store them in their local address book.

Mainnet

  1. 03b74fa3c68356bb40d58ecc10129479b159a145@seed1.mainnet.pokt.network:20656
  2. 64c91701ea98440bc3674fdb9a99311461cdfd6f@seed2.mainnet.pokt.network:21656
  3. 0057ee693f3ce332c4ffcb499ede024c586ae37b@seed3.mainnet.pokt.network:22856
  4. 9fd99b89947c6af57cd0269ad01ecb99960177cd@seed4.mainnet.pokt.network:23856
  5. f2a4d0ec9d50ea61db18452d191687c899c3ca42@seed5.mainnet.pokt.network:24856
  6. f2a9705924e8d0e11fed60484da2c3d22f7daba8@seed6.mainnet.pokt.network:25856
  7. 582177fd65dd03806eeaa2e21c9049e653672c7e@seed7.mainnet.pokt.network:26856
  8. 2ea0b13ab823986cfb44292add51ce8677b899ad@seed8.mainnet.pokt.network:27856
  9. a5f4a4cd88db9fd5def1574a0bffef3c6f354a76@seed9.mainnet.pokt.network:28856
  10. d4039bd71d48def9f9f61f670c098b8956e52a08@seed10.mainnet.pokt.network:29856
  11. 5c133f07ed296bb9e21e3e42d5f26e0f7d2b2832@poktseed100.chainflow.io:26656
  12. 361b1936d3fbe516628ebd6a503920fc4fc0f6a7@seed.pokt.rivet.cloud:26656
pocket start --seeds="03b74fa3c68356bb40d58ecc10129479b159a145@seed1.mainnet.pokt.network:20656,64c91701ea98440bc3674fdb9a99311461cdfd6f@seed2.mainnet.pokt.network:21656,0057ee693f3ce332c4ffcb499ede024c586ae37b@seed3.mainnet.pokt.network:22856,9fd99b89947c6af57cd0269ad01ecb99960177cd@seed4.mainnet.pokt.network:23856,f2a4d0ec9d50ea61db18452d191687c899c3ca42@seed5.mainnet.pokt.network:24856,f2a9705924e8d0e11fed60484da2c3d22f7daba8@seed6.mainnet.pokt.network:25856,582177fd65dd03806eeaa2e21c9049e653672c7e@seed7.mainnet.pokt.network:26856,2ea0b13ab823986cfb44292add51ce8677b899ad@seed8.mainnet.pokt.network:27856,a5f4a4cd88db9fd5def1574a0bffef3c6f354a76@seed9.mainnet.pokt.network:28856,d4039bd71d48def9f9f61f670c098b8956e52a08@seed10.mainnet.pokt.network:29856,5c133f07ed296bb9e21e3e42d5f26e0f7d2b2832@poktseed100.chainflow.io:26656,361b1936d3fbe516628ebd6a503920fc4fc0f6a7@seed.pokt.rivet.cloud:26656" --mainnet

Testnet

  1. 3487f08b9e915f347eb4372b406326ffbf13d82c@testnet-seed-1.nodes.pokt.network:4301
  2. 27f4295d1407d9512a25d7f2ea91d1a415660c16@testnet-seed-2.nodes.pokt.network:4302
  3. 0beb1a93fe9ce2a3b058b98614f1ed0f5ad664d5@testnet-seed-3.nodes.pokt.network:4303
  4. 8fd656162dbbe0402f3cef111d3ad8d2723eef8e@testnet-seed-4.nodes.pokt.network:4304
  5. 80100476b67fea2e94c6b2f72e40cf8f6062ed21@testnet-seed-5.nodes.pokt.network:4305
  6. 370edf0882e094e83d4087d5f8801bbf24f5d931@testnet-seed-6.nodes.pokt.network:4306
  7. 57aff5a049846d14e2dcc06fdcc241d7ebe6a3eb@testnet-seed-7.nodes.pokt.network:4307
  8. 545fb484643cf2efbcf01ee2b7bc793ef275cd84@testnet-seed-8.nodes.pokt.network:4308
pocket start --seeds="3487f08b9e915f347eb4372b406326ffbf13d82c@testnet-seed-1.nodes.pokt.network:4301,27f4295d1407d9512a25d7f2ea91d1a415660c16@testnet-seed-2.nodes.pokt.network:4302,0beb1a93fe9ce2a3b058b98614f1ed0f5ad664d5@testnet-seed-3.nodes.pokt.network:4303,8fd656162dbbe0402f3cef111d3ad8d2723eef8e@testnet-seed-4.nodes.pokt.network:4304,80100476b67fea2e94c6b2f72e40cf8f6062ed21@testnet-seed-5.nodes.pokt.network:4305,370edf0882e094e83d4087d5f8801bbf24f5d931@testnet-seed-6.nodes.pokt.network:4306,57aff5a049846d14e2dcc06fdcc241d7ebe6a3eb@testnet-seed-7.nodes.pokt.network:4307,545fb484643cf2efbcf01ee2b7bc793ef275cd84@testnet-seed-8.nodes.pokt.network:4308" --testnet

Node Tutorials

This section contains tutorials for various actions a typical node user may wish to undertake.

The following tutorial, Zero To Node, wlil show you a step-by-step way to set up a Pocket Node on hosted hardware.

Zero To Node

Welcome to Zero To Node! This is a step-by-step guide for setting up a Pocket node. While there are many different ways to set up a node, the focus of this tutorial is on keeping things simple and with the minimum of steps, while still focusing on security and stability.

This guide is broken down into five parts:

Background

The main utility of a Pocket node is to relay transactions to other blockchains. So, Pocket nodes need access to other nodes for the blockchains they’ll be relaying to. However, the focus of this guide is just on setting up a Pocket node that will relay to the Pocket network, essentially, through itself. Setting up nodes for other blockchains such as Harmony, Ethereum, or any of the other supported blockchains is beyond the scope of this guide.

After completing the steps outlined here, you’ll have a fully functional Pocket node up and running. If you choose, you can also opt to stake your node and earn rewards. We’ll cover that here, but staking is not required unless you want to earn rewards.

Who is this guide for?

This guide is for anyone interested in running Pocket nodes. While the goal is to keep things simple, the assumption is that you have some general blockchain and computer networking knowledge, and some Linux terminal experience.

What you’ll need

In order to complete this guide, you’ll need:

  1. A server connected to the internet
  2. A domain name
  3. The ability to add DNS records for your domain
  4. 15,100 POKT (if you want to stake your node)
  5. About 2-4 hours to complete and test everything

Part 1 – Server setup

This section will help you set up and configure a server to prepare it for being a Pocket node.

Setup a server

The first thing you’ll need to run a Pocket node is a server. For this guide, we’ll be using a virtual machine on the Linode cloud service. But, you could use any cloud service you like.

Info

Pocket has no affiliation with Linode and does not recommend any one provider over another. The general steps outlined here should work for most cloud providers.

Let’s start by creating a Linode instance (a virtual machine).

Creating a Linode instance

To create a Linode instance, do the following:

  1. Get a Linode account and login.
  2. Create a new Linode with the following specifications:
    • Image / Distribution: Ubuntu 20.04 LTS
    • Region: Atlanta, GA
    • Linode Plan: Dedicated 16 GB - 8 CPU, 320 GB Storage, 16 GB RAM
    • Linode Label: pokt001
  3. Wait for the Linode to be created and show up as running in the web interface.
Info

For a more detailed guide on setting up a Linode instance, see the Linode docs. Also, note that the Atlanta, GA region was selected for this guide because it supports NVMe storage which is preferable for running nodes. Check to see which other regions support NVMe storage.

Configure DNS

Now that the Linode instance is created and running, you’ll need to set up a DNS record that points to the IP address of the Linode instance.

Pocket nodes require a DNS name. DNS (Domain Name Service) names are used to map an IP address to more human-friendly names. So rather than referencing a server with an address like 134.23.153.21 we can use a name like pokt001.pokt.run.

Info

Most domain registrars allow you to add DNS records. Please refer to the DNS setup documentation for your provider.

Specifically, you’ll need to add an A record for the domain name. For the exact steps, consult the DNS documentation for your provider. Then create a record with the following information:

  • Name: pokt001
  • Type: A
  • Value: {Linode_IP_Address}
  • TTL: 300

After setting up your DNS record, wait a few minutes for the DNS to propagate. Then use the following command to check that the DNS record is working:

Info

The examples in this tutorial will use pokt001 as the server on the pokt.run domain, so pokt001.pokt.run will be used as the DNS name. Please replace this throughout with your own server and domain name.

ping -c 3 pokt001.pokt.run

You should see a response that looks something like this:

64 bytes from 134.23.153.21: icmp_seq=0 ttl=47 time=92.403 ms
64 bytes from 134.23.153.21: icmp_seq=1 ttl=47 time=142.828 ms
64 bytes from 134.23.153.21: icmp_seq=2 ttl=47 time=182.456 ms

If the IP address matches the IP address of your Linode instance, you’re all set!

Info

It can sometimes take longer than a minute for the DNS to propagate. So, be patient if things don’t seem to work right away.

Login with SSH

Now that we have a DNS record setup, we will look at using SSH to log in and continue the setup process.

The Secure Shell Protocol (SSH) is a secure way to connect to your Linode instance from a remote machine, like your local computer. We’ll be using SSH to complete the remainder of the setup process.

SSH from Mac or Linux

If you’re using a Mac, or Linux, on your local computer, you can SSH into your node by doing the following:

  • Open a terminal

  • SSH into your node using the following command:

    ssh root@pokt001.pokt.run
    
Info

Don’t forget to replace pokt001.pokt.run with your DNS name.

You’ll be prompted for your password. This is the root password that you set when you created your Linode.

SSH from Windows

Windows 10 and later have a built-in SSH client. You can use SSH on Windows by doing the following:

  • Open the Windows terminal

  • SSH into your node using the following command:

    ssh root@pokt001.pokt.run
    
Info

Don’t forget to replace pokt001.pokt.run with your DNS name.

If you’re using an older version of Windows, you might need to install PuTTY or some other SSH client.

Set the hostname

At this point you should be logged into your node as the root user.

In a previous step, we set the DNS name for the node. Now we’ll use the same name for the hostname on the server.

To set the server hostname use the following steps:

  1. Open the /etc/hostname file with the following command:

    nano /etc/hostname
    
  2. Change the localhost value to the fully qualified hostname of your node (for example, pokt001.pokt.run).

  3. Save the file with Ctrl+O and then Enter.

  4. Exit nano with Ctrl+X.

  5. Reboot the server with the following command:

    reboot
    
  6. Wait for the server to reboot then ssh back in as the root user before continuing on.

Create a user

For security reasons it’s best not to use the root user. Instead, it’s better to create a new user and add the user to the sudo group.

Also, by default, the Pocket CLI will place the data directory for the node in the user’s home directory. So, when you create a new user, you’ll want to make sure the home directory is on a volume that has plenty of room for the data directory.

Warning

At the time of writing, Pocket requires approximately 200GB of disk space for its blockchain data. The following user setup steps assumes that the location of your user’s home directory is on a volume with enough room for the pocket data.

Creating a new user

To create a new user and home directory, enter the following commands:

  1. Create a new user named pocket, add it to the sudo group, and set the default shell to bash. If you want to specify the location of the home directory, you can use the -d option followed by the path to the home directory:

    useradd -m -g sudo -s /bin/bash pocket && passwd pocket
    
  2. For the rest of this guide, we’ll be using the pocket user. So now that the pocket user is created, you can switch from using root to the pocket user with the following command:

    su - pocket
    

Configure SSH Key Login (Optional):

While not required, using an SSH key provides a more secure means of accessing your server.

Using an SSH key removes the ability for credentials to be sniffed in the login process, and removes the pitfalls that can often come with user generated passwords since the key will truly be random.

One important thing to understand, is that without access to the ssh key, you won’t be able to log into your node. If you intend on accessing your node from multiple computers, it’s recommended that you repeat the Generate Key and Upload Key steps from each computer that you intend to access your node from before moving on to the Disable Root Login and Password Authentication step.

  1. Log Out

    At the terminal you’ll need to enter the logout command twice. The first logout logs you out of the pocket user, back to the root user, and the second logout logs you out of the server and back to your terminal.

  2. Generate Key

    Next, we’ll generate an ssh key. To do that you’ll run the ssh-keygen command. You’ll be prompted to specify the file you want to save the key to, and for a password. Specifying a password means that if someone has access to your key, they’d still need to know the password to be able to use it to login. To create the key, do the following:

    • Run the ssh-keygen command

      ssh-keygen -t rsa -b 4096
      
    • Enter file in which to save the key (~/.ssh/id_rsa)

    • Enter a passphrase (empty for no passphrase)

    • Enter same passphrase again

    The results should looking something like the following:

    The key fingerprint is:
    SHA256:jr2MLXIha188wYsp/bNflN9BuqQ3LWCAXJNTtHO7sWk
    The key's randomart image is:
    +---[RSA 4096]----+
    |         o+o     |
    |      . oo. .    |
    |       o ..o . . |
    |       .  . o.+  |
    |        S  oo= . |
    |    ...B o..+.B..|
    |    .o=.B  ..E...|
    |    +.o*.o .o o  |
    |   . +o.*+.      |
    +----[SHA256]-----+
    
  3. Upload Key

    Now we’re going to upload the key so that we can use it to log into the pocket user. If you choose a different path for the ssh key, it’s important to replace the ~/.ssh/id_rsa with the key you used.

    ssh-copy-id -i ~/.ssh/id_rsa pocket@pokt001.pokt.run
    
  4. Disable Root Login and Password Authentication

    Now we’re now going to configure ssh to no longer allow root logins, and to not allow any password based login attempts. Meaning without access to the ssh key for the pocket user, no one will be able to log into the server.

    First we’ll need to log back into the server:

    ssh pocket@pokt001.pokt.run
    

    From there, we’ll want to open the /etc/ssh/sshd_config file to make some changes to the default configuration:

    sudo nano /etc/ssh/sshd_config
    

    Once there, we’ll need to find and change the following lines:

    • #PermitRootLogin prohibit-password -> PermitRootLogin no
    • #PubkeyAuthentication yes -> PubkeyAuthentication yes
    • #PasswordAuthentication yes -> PasswordAuthentication no

    Once changed, Ctrl-O followed by Enter will save the changes, and Ctrl-X will exit nano back to the terminal.

    Then we’ll need to restart the ssh server for these changes to take effect:

    sudo systemctl restart sshd.service
    
  5. Verify Everything Works

    The last step is to log out of the server, and try logging back in. If you’re no longer prompted for a password, then everything is working as expected.

That’s it for the server setup! Continue on to install the necessary software.

Part 2 – Software installation

This section will help you install all the necessary software for your node.

Install dependencies

Now let’s move on to the Pocket CLI installation.

At this point you should be logged in via SSH as the pocket user that we set up in a previous step. Before we install the Pocket software, we need to update the existing system packages and add a few dependencies.

Updating system packages

  1. Update the repository index with the following command:
    sudo apt update
    
  2. Update the distribution with the following command:
    sudo apt dist-upgrade -y
    

After the update completes, we’re ready to install the dependencies.

Installing dependencies

There are a handful of dependencies but installing them won’t take long. Also, some might already be installed. So if one of the dependencies exists, you can just move on to the next one.

git

sudo apt-get install git -y

build tools

sudo apt-get install build-essential -y

curl

sudo apt-get install curl -y

file

sudo apt-get install file -y

nginx

sudo apt install nginx -y

certbot

sudo apt install certbot -y

python3-certbot-nginx

sudo apt-get install python3-certbot-nginx -y

jq

sudo apt install jq -y

Install Go

After installing the dependencies, there is one more dependency we’ll need to add, and that’s Go. Go (sometimes known as “Golang”) is the programming language that the Pocket software was written in.

We could install Go using apt, but we want to get the latest stable version which probably isn’t available by default in the apt repository. So, we’ll use the steps below to install Go.

  1. Make sure you’re in the pocket home directory.
    cd ~
    
  2. Find the latest version of Go from https://golang.org/dl/ then download it with the following command. (Make sure to change the link below to point to the correct version of Go.)
    wget https://dl.google.com/go/go1.17.7.linux-amd64.tar.gz
    
  3. Extract the archive:
    sudo tar -xvf go1.17.7.linux-amd64.tar.gz
    
  4. Set permissions on the extracted files:
    sudo chown -R pocket ./go
    
  5. Add Go to the PATH:
    echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.profile
    
  6. Set the GOPATH and GOBIN environment variables:
    echo 'export GOPATH=$HOME/go' >> ~/.profile
    
    echo 'export GOBIN=$HOME/go/bin' >> ~/.profile
    
  7. Reload your .profile:
    source ~/.profile
    
  8. Verify the installation:
    go version
    
    You should see something like this:
    go version go1.17.7 linux/amd64
    
    Make sure the version number matches the version you downloaded. If the go version command doesn’t work, try logging out and logging back in.
  9. Verify the GOPATH and GOBIN variables are set correctly:
    go env
    
    You should see the GOPATH and GOBIN variables set correctly.

Install Pocket

After you can verify that you have the latest stable version of Go, we’re ready to install the Pocket software.

We’ll be downloading Pocket Core from GitHub and then compiling it with Go to get it fully installed.

To download and install Pocket Core, do the following:

  1. Create a project directory:
    sudo mkdir -p $GOPATH/src/github.com/pokt-network
    
  2. Change to the project directory:
    cd $GOPATH/src/github.com/pokt-network
    
  3. Clone the Pocket Core repository:
    sudo git clone https://github.com/pokt-network/pocket-core.git
    
  4. Change to the code directory:
    cd pocket-core
    
  5. Checkout the latest version. You can find the latest tag by going to https://github.com/pokt-network/pocket-core/tags.
    sudo git checkout tags/RC-0.8.2
    
  6. Build project code:
    go build -o $GOPATH/bin/pocket $GOPATH/src/github.com/pokt-network/pocket-core/app/cmd/pocket_core/main.go
    
  7. Test that the build succeeded:
    pocket version
    

That’s it for the software installation. Now let’s move on to the Pocket core configuration.

Part 3 – Pocket configuration

This section will help you configure your instance of Pocket.

Create a Pocket wallet account

Pocket nodes are associated with a Pocket wallet account. This is the account that will be used to send and receive transactions from the node. You can either create a new account using the Pocket CLI we just installed, or you can use an existing account. For this guide, we’ll be creating a new account.

Creating an account

To create an account, run the following command:

pocket accounts create

You’ll be prompted to set a passphrase for the account. You can use any passphrase you like but for security reasons, it’s best to use a passphrase that is at least 12 characters long, preferably longer.

Listing accounts

After you’ve created the account you can use the pocket accounts list command to confirm that the account was added successfully.

pocket accounts list

Setting the validator address

Next, to set the account as the one the node will use, run the following command:

pocket accounts set-validator {YourAccountAddress}

Confirm the validator address

Finally, you can confirm that the validator address was set correctly by running the following command:

 pocket accounts get-validator

Create config.json

The Pocket core software uses a config file to store configuration details. By default the config file is located at ~/.pocket/config/config.json. In this step we’ll look at how to create a new config file.

To create a new config file:

  1. Run the following command, which will create the default config.json file, add the seeds, set port 8081 to 8082, and increase the RPC timeout value:

    echo $(pocket util print-configs) | jq '.tendermint_config.P2P.Seeds = "03b74fa3c68356bb40d58ecc10129479b159a145@seed1.mainnet.pokt.network:20656,64c91701ea98440bc3674fdb9a99311461cdfd6f@seed2.mainnet.pokt.network:21656,0057ee693f3ce332c4ffcb499ede024c586ae37b@seed3.mainnet.pokt.network:22856,9fd99b89947c6af57cd0269ad01ecb99960177cd@seed4.mainnet.pokt.network:23856,1243026603e9073507a3157bc4de99da74a078fc@seed5.mainnet.pokt.network:24856,6282b55feaff460bb35820363f1eb26237cf5ac3@seed6.mainnet.pokt.network:25856,3640ee055889befbc912dd7d3ed27d6791139395@seed7.mainnet.pokt.network:26856,1951cded4489bf51af56f3dbdd6df55c1a952b1a@seed8.mainnet.pokt.network:27856,a5f4a4cd88db9fd5def1574a0bffef3c6f354a76@seed9.mainnet.pokt.network:28856,d4039bd71d48def9f9f61f670c098b8956e52a08@seed10.mainnet.pokt.network:29856,5c133f07ed296bb9e21e3e42d5f26e0f7d2b2832@poktseed100.chainflow.io:26656"' | jq '.pocket_config.rpc_timeout = 15000' | jq '.pocket_config.rpc_port = "8082"' | jq '.pocket_config.remote_cli_url = "http://localhost:8082"' | jq . > ~/.pocket/config/config.json
    
    Warning
    This is a long command! Make sure you've copied it completely.
    
  2. Verify the config.json file setting by viewing the contents of the file:

    cat ~/.pocket/config/config.json
    

Create chains.json

Pocket nodes relay transactions to other blockchains. So, you’ll need to configure the chains your node can relay to. For this guide, we’ll just be setting up our node to relay to the Pocket mainnet blockchain, essentially through itself.

To maximize your rewards, you’ll want to relay to other chains. We’ll cover that in more detail later but here is a list of other blockchains you could relay to.

Generating a chains.json file with the CLI

You can use the Pocket CLI to generate a chains.json file for your node by running the following command:

pocket util generate-chains

This will prompt you for the following information:

  • Enter the ID of the Pocket network identifier:
    0001
    
  • Enter the URL of the network identifier. Use http://127.0.0.1:8081/ if you’re not running a validator node:
    http://127.0.0.1:8082/
    

When you’re prompted to add another chain, enter n for now.

Info

By default the chains.json file will be created in ~/.pocket/config. You can use the --datadir flag to create the chains.json file in an alternate location. For example: pocket util generate-chains --datadir "/mnt/data/.pocket".

Create genesis.json

Now that we have a chains.json file set up, so we can move on to test our node.

When you start a Pocket node for the first time, it will need to find other nodes (peers) to connect with. To do that we use a file named genesis.json with details about peers the node should connect to get on the network.

To create a JSON file with the genesis information:

  1. Change to the .pocket/config directory:
    cd ~/.pocket/config
    
  2. Use the following command to get the genesis.json file from GitHub:
    wget https://raw.githubusercontent.com/pokt-network/pocket-network-genesis/master/mainnet/genesis.json genesis.json
    

Set open file limits

Ubuntu and other UNIX-like systems have a ulimit shell command that’s used to set resource limits for users. One of the limits that can be set is the number of open files a user is allowed to have. Pocket nodes will have a lot of files open at times, so we’ll want to increase the default ulimit for the pocket user account.

Increasing the ulimit

  1. Before increasing the ulimit, you can check the current ulimit with the following command:
    ulimit -n
    
  2. Increase the ulimit to 16384. The -Sn option is for setting the soft limit on the number of open files:
    ulimit -Sn 16384
    
  3. Check the new ulimit to confirm that it was set correctly. The -n option is for getting the limit for just the number of open files:
    ulimit -n
    

Permanent settings

Using the above method for setting the ulimit only keeps the change in effect for the current session. To permanently set the ulimit, you can do the following:

  1. Open the /etc/security/limits.conf file.
    sudo nano /etc/security/limits.conf
    
  2. Add the following line to the bottom of the file:
    pocket           soft    nofile          16384
    
  3. Save the file with Ctrl+O and then Enter.
  4. Exit nano with Ctrl+X.

After permanently setting the ulimit, the next thing we’ll do is download a snapshot of the Pocket blockchain.

Download snapshot

Rather than synchronizing your Pocket node from block zero (which could take weeks), you can use a snapshot. A snapshot of the Pocket blockchain is taken every 12 hours and can be downloaded using the instructions on the Pocket Snapshots Repository README page.

Info

As of this writing, the snapshots are refreshed every 12 hours. In the GitHub repo you can look at when the README.md file was last updated to determine when the last snapshot was taken. It’s best to download the snapshot that is less than a few hours old.

Here are the steps for download the snapshot using the wget command:

  1. Change into the .pocket directory.
    cd ~/.pocket
    
  2. Make a directory named data and change into it.
    mkdir data && cd data
    
  3. Download the latest snapshot using the following command:
    wget -qO- https://snapshot.nodes.pokt.network/latest.tar.gz | tar xvfz -
    
  4. Make the pocket user the owner of the data directory.
    sudo chown -R pocket ~/.pocket/data
    
Warning

This process can take a few hours depending on your internet connection.

Configure systemd

Next, we’ll configure the Pocket service using systemd, a Linux service manager. This will enable the Pocket node to run and restart even when we’re not logged in.

Creating a systemd service in Linux

To setup a systemd service for Pocket, do the following:

  1. Open nano and create a new file called pocket.service:

    sudo nano /etc/systemd/system/pocket.service
    
  2. Add the following lines to the file:

    [Unit]
    Description=Pocket service
    After=network.target
    Wants=network-online.target systemd-networkd-wait-online.service
    
    [Service]
    User=pocket
    Group=sudo
    ExecStart=/home/pocket/go/bin/pocket start
    ExecStop=/home/pocket/go/bin/pocket stop
    
    [Install]
    WantedBy=default.target
    
  3. Make sure the User is set to the user that will run the Pocket service.

  4. Make sure the ExecStart and ExecStop paths are set to the path for the Pocket binary.

  5. Save the file with Ctrl+O and then return.

  6. Exit nano with Ctrl+X.

  7. Reload the service files to include the pocket service:

    sudo systemctl daemon-reload
    
  8. Start the pocket service:

    sudo systemctl start pocket.service
    
  9. Verify the service is running:

    sudo systemctl status pocket.service
    
  10. Stop the pocket service:

    sudo systemctl stop pocket.service
    
  11. Verify the service is stopped:

    sudo systemctl status pocket.service
    
  12. Set the service to start on boot:

    sudo systemctl enable pocket.service
    
  13. Verify the service is set to start on boot:

    sudo systemctl list-unit-files --type=service
    
  14. Start the pocket service:

    sudo systemctl start pocket.service
    

Other systemctl commands

  • To restart the service:

    sudo systemctl restart pocket.service
    
  • To prevent the service from starting on boot:

    sudo systemctl disable pocket.service
    
  • To see mounted volumes:

    sudo systemctl list-units --type=mount
    
    Info
    If your pocket data is on a separate partition, you can use the following command in the `pocket.service` file to mount it before the pocket service starts.
        ```
        After=network.target mnt-data.mount
        ```
    

    This ensures that the network is up and the volume is mounted before the pocket service starts.

Viewing the logs

To view the logs for the pocket service:

sudo journalctl -u pocket.service

To view just the last 100 lines of the logs (equivalent to the tail -f command):

sudo journalctl -u pocket.service -n 100 --no-pager

Finding Errors

You can use grep to find errors in the logs.

sudo journalctl -u pocket.service | grep -i error

Alright, we’re just about done. We just need to setup an HTTP proxy and we’ll be ready to go live. We’ll setup the proxy next.

Part 4 – Proxy configuration

This section will help you set up the proxy setting on your node.

Setup SSL

Pocket requires that nodes have an SSL certificate for secure communications. SSL (Secure Sockets Layer) is a layer of security that sits on top of TCP/IP. It’s used to encrypt the data sent between a client and a server. To use SSL, you need to have a certificate and a key. Thankfully, getting an SSL certificate is straightforward and free.

To get a certificate, we’ll be using Let’s Encrypt which is a service that issues SSL certificates for free. We’ll also be using software called certbot to register, install, and renew the certificate.

Registering an SSL certificate

We installed certbot in a previous step so we just need to use it to request a certificate.

To get a certificate, we’ll need to use the certbot command with the following options:

  • --register-unsafely-without-email: This option is required to get a certificate without an email address.
  • --agree-tos: This option is required to agree to the Let’s Encrypt Terms of Service.
  • --nginx: This option is required to use the nginx plugin.
  • --no-redirect: This option is required to disable the redirect to the Let’s Encrypt website.
  • --domain: This option is required to specify the domain name.

Here’s an example of how to request a certificate. Just replace $HOSTNAME with the DNS name of your node:

sudo certbot --nginx --domain $HOSTNAME --register-unsafely-without-email --no-redirect --agree-tos

The output from this command should confirm that the certificate was successfully registered.

Testing your certificate

To be sure, you’ll also want to test that the certificate is working.

There is a command that certbot provides to test your certificate. It’s used for testing the auto-renewal of the certificate but it also confirms that the certificate is working. You can run it using the following command:

sudo certbot renew --dry-run

The resulting output should confirm that the certificate is working.

Configure Nginx

Nginx is a web server. We installed it in aprevious step but we need to do some additional configuration.

Nginx uses config files to define servers and routes for incoming requests. For Pocket nodes, nginx needs to relay public requests to a local HTTP server that pocket core is running. This is referred to as the proxy. We’ll also need to proxy requests made by the Pocket CLI. For example, when we run the command pocket query height, the CLI makes an http request to the node’s local HTTP server.

Config files

The nginx configuration files we’re interested in are located in the /etc/nginx/sites-available/ directory. In that directory there is a default configuration file named default. This is the configuration that is created when you install nginx, but we’ll be creating our own for our node.

To configure nginx:

  1. Confirm the name of your SSL certificate:
    sudo ls /etc/letsencrypt/live/
    
  2. Create a new config file with nano:
    sudo nano /etc/nginx/sites-available/pocket
    
  3. Add the following code but change the hostname values (pokt001.pokt.run) to your node’s DNS hostname:
    server {
        listen 80 default_server;
        listen [::]:80 default_server;
    
        root /var/www/html;
    
        index index.html index.htm index.nginx-debian.html;
    
        server_name _;
    
        location / {
            try_files $uri $uri/ =404;
        }
    }
    
    server {
        add_header Access-Control-Allow-Origin "*";
        listen 80 ;
        listen [::]:80 ;
        listen 8081 ssl;
        listen [::]:8081 ssl;
    
        root /var/www/html;
    
        index index.html index.htm index.nginx-debian.html;
    
        server_name pokt001.pokt.run;
    
        location / {
            try_files $uri $uri/ =404;
        }
    
        listen [::]:443 ssl ipv6only=on;
        listen 443 ssl;
    
        ssl_certificate /etc/letsencrypt/live/pokt001.pokt.run/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/pokt001.pokt.run/privkey.pem;
    
        include /etc/letsencrypt/options-ssl-nginx.conf;
        ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
    
        access_log /var/log/nginx/reverse-access.log;
        error_log /var/log/nginx/reverse-error.log;
    
        location ~* ^/v1/client/(dispatch|relay|challenge|sim) {
            proxy_pass http://127.0.0.1:8082;
            add_header Access-Control-Allow-Methods "POST, OPTIONS";
            allow all;
        }
    
        location = /v1 {
            add_header Access-Control-Allow-Methods "GET";
            proxy_pass http://127.0.0.1:8082;
            allow all;
        }
    }
    
  4. Save the change with Ctrl+O.
  5. Exit nano with Ctrl+X.
  6. Stop nginx with:
    sudo systemctl stop nginx
    
  7. Disable the default configuration:
    sudo rm /etc/nginx/sites-enabled/default
    
  8. Enable our new configuration:
    sudo ln -s /etc/nginx/sites-available/pocket /etc/nginx/sites-enabled/pocket
    
  9. Start nginx:
    sudo systemctl start nginx
    

Enable UFW

We’re almost done, but before we finish we’ll make our server more secure by setting firewall rules to limit network exposure. The Uncomplicated Firewall (UFW) is a security tool that makes configuring the firewall reasonably simple. We’ll use it to disable unnecessary ports.

Ports you need to open

For running a Pocket node, you’ll need to open the following ports:

  • 22: SSH
  • 80: HTTP
  • 443: HTTPS
  • 8081: For the Pocket HTTP API
  • 26656: For the Pocket RPC API

Use UFW to disable unnecessary ports

To use UFW to configure the firewall:

  1. Enable UFW. When prompted, press y to confirm:

    sudo ufw enable
    
  2. Set the default to deny all incoming connections:

    sudo ufw default deny
    
  3. Allow the SSH port:

    sudo ufw allow ssh
    
  4. Allow port 80:

    sudo ufw allow 80
    
  5. Allow port 443:

    sudo ufw allow 443
    
  6. Allow port 8081:

    sudo ufw allow 8081
    
  7. Allow port 26656:

    sudo ufw allow 26656
    

That’s it for the UFW setup. Let’s just check the status to confirm the ports are open. To do that, run the following command:

sudo ufw status

After confirming only the necessary ports are open, you can move on to the final steps.

Part 5 – Going live

This section will details the final steps in going live with your node.

Test everything

At this point your Pocket node should be up and running!

But you’ll want to test it to confirm. The following are some of the things you can do to test your Pocket Node.

Make sure the Pocket process is running

The first thing to check is that the pocket service is running. You can do that by running the following command:

top -b -n 1 | grep pocket

You should see output similar to the following:

  44871 root      20   0 1018268  33948  21448 S   0.0   0.4   0:00.17 pocket

Block height

You’ll want to check that the node is fully synced with the Pocket blockchain. The easiest way is to run the following command:

pocket query height

The result should look something like the following.

{
    "height": 48161
}

Network status

Another way to see if your node is fully synced is to check the status with the following command:

curl http://127.0.0.1:26657/status

The result should look something like the following. Note the highlighted property catching_up which indicates if the node is catching up with the blockchain or fully synced. In the example below, the node is fully synced.

{
  "jsonrpc": "2.0",
  "id": -1,
  "result": {
    "node_info": {
      "protocol_version": {
        "p2p": "7",
        "block": "10",
        "app": "0"
      },
      "id": "80b80c106115259349df8ef06267cff7bbabd194",
      "listen_addr": "tcp://0.0.0.0:26656",
      "network": "mainnet",
      "version": "0.33.7",
      "channels": "4020212223303800",
      "moniker": "localhost",
      "other": {
        "tx_index": "on",
        "rpc_address": "tcp://127.0.0.1:26657"
      }
    },
    "sync_info": {
      "latest_block_hash": "F39BBF5C64D9E02E28DDBB8640F84A22CFAE1727CFBC72537982EF5914E4BB25",
      "latest_app_hash": "6198835747411135C1F812CB45FA5621D5ADB63342EC0678C20879D7D39F03B5",
      "latest_block_height": "50021",
      "latest_block_time": "2022-02-04T12:16:10.77575197Z",
      "earliest_block_hash": "7D551967CB8BBC9F8C0EAE78797D0576951DDA25CE63DF1801C020478C0B02F8",
      "earliest_app_hash": "",
      "earliest_block_height": "1",
      "earliest_block_time": "2020-07-28T15:00:00Z",
      "catching_up": false
    },
    "validator_info": {
      "address": "80B80C106115259349DF8EF06267CFF7BBABD194",
      "pub_key": {
        "type": "tendermint/PubKeyEd25519",
        "value": "ee+o9bKqCbAO13FgWTLmJdi9hhfYg8AHsif5430uz8A="
      },
      "voting_power": "0"
    }
  }
}

Make sure your node is visible to other nodes

You’ll also want to make sure your node is accessible to other nodes.

To test and confirm your node is visible to other nodes on the public network, you’ll make an HTTP request using the public DNS name for the node. You can use the following command to make that request:

curl https://pokt001.pokt.run:8081/v1
Info

As always, don’t forget to change pokt001.pokt.run to the DNS name for your node.

This should return something like the following. This is the version of pocket-core that is running.

"RC-0.8.2"

Staking your node

To earn POKT rewards, you’ll need to stake at least 15,000 POKT. That said, you should stake at least 15,100 POKT or more to be safe. This provides a little extra room in case your node gets slashed (penalized) for some reason.

Warning

Please make sure that you understand the risks associated with staking POKT and running a Pocket node.

If you’re using the Pocket CLI to fund an account, keep in mind that the CLI uses uPOKT (the smallest unit of POKT) for its calculations. The formula for converting POKT to uPOKT is: uPOKT = POKT * 10^6. So, multiplying 15050 POKT by 10^6 (one million) will result in 15050000000 uPOKT.

Also keep in mind that there is a cost for every transaction you send. At the moment, that cost is a flat fee of 0.01 POKT, or 10000 uPOKT, but this may be subject to change.

  1. List your accounts:
    pocket accounts list
    
  2. Confirm the validator account is set:
    pocket accounts get-validator
    
  3. Confirm the validator account has enough POKT. This should be at least 15,101 POKT. You’ll want 15,100 to stake and a bit more for network fees:
    pocket query balance {YourValidatorAddress}
    
  4. Stake your node, making sure to enter the correct details for your setup:
    pocket nodes stake custodial {YourValidatorAddress} 15100000000 {ChainIDs} https://{hostname}:443 mainnet 10000 true
    
Info

The {ChainIDs} placeholder should be a list of relay chain IDs that are defined in your ~/.pocket/config/chains.json file. In this guide we only set up 0001, but if you were relaying to multiple chains, each id would be separated by a comma. For example, 0001,0022,0040.

Info

As of RC-0.8.2 there are two staking methods: custodial and non-custodial. The custodial method is used in the example above.

After you send the stake command, you’ll be prompted for your passphrase, then you should see something like this:

http://localhost:8082/v1/client/rawtx
{
    "logs": null,
    "txhash": "155D46196C69F75F85791C4190D384B8BAFFBBEFCC5D1311130C54A1C54435A7"
}

The actual time it takes to stake will vary depending on when the last block was processed, but generally, it should take less than 15 minutes.

Confirm your node is live

After you’ve staked your node, you can confirm it’s live by running the following command:

pocket query node {YourValidatorAddress}

If you see something like the following, it just means your node is not live yet:

http://localhost:8082/v1/query/node
the http status code was not okay: 400, and the status was: 400 Bad Request, with a response of {"code":400,"message":"validator not found for 07f5084ab5f5246d747fd1154d5d4387ee5a7111"}

If this happens, please wait a few minutes and try again.

Tutorial complete

Congratulations! You’ve successfully set up a Pocket node.

There’s more to running a Pocket node than this, such as maintenance, upgrades, and other administrative tasks, but hopefully this has gotten you started and on the right path. Thank you for doing your part to help decentralize Web3!

Automated Deployments

The following services can help automate your node deployments:

Warning: Use at your own risk. These links are not directly associated with Pocket Network and do not constitute an endorsement, guarantee, warranty, or recommendation by Pocket Network, Inc., Pocket Network Foundation, or the Pocket DAO. Do conduct your own due diligence before deciding to use any third party services.

Node-Hosting Services

If you are interested in staking your POKT in a node but don’t have the time or technical know-how, below you will find a link to the available options to have your node operated by a third-party.

If you don’t have enough POKT for the minimum node stake, you should consult this Overview of Pooling Services.

Warning: Use at your own risk. The appearance of third party descriptions and hyperlinks on the above linked sites does not constitute an endorsement, guarantee, warranty, or recommendation by Pocket Network, Inc., Pocket Network Foundation, or the Pocket DAO. Do conduct your own due diligence before deciding to use any third party services.

Node FAQ

The following pages contains common questions regarding running nodes.

Node Configuration

Does my blockchain node need to be synced before I start my Pocket node?

Yes. Every node on the Pocket Network needs to have the most up to date information of the blockchain they are supporting. If you start joining sessions before your node has caught up to the current block height, you will be returning incorrect data, and if incorrect data is being returned, your node will be slashed.

How many blockchains can one node support?

Your node can support up to the number of chains defined by the MaximumChains parameter. This limit is not definitive and can be changed by the DAO.

Can I add a load balancer address in my chains.json if I have multiple blockchains under one domain?

Yes you can! Just make sure you have the necessary ports open to be able to successfully send relays to the proper network.

How can I add more blockchains to my node?

Add the new RelayChainIDs to your chains.json file, then run the stake command again for your node. Since you’re already staked, running the command “updates” your staking configuration.

Find the RelayChainIDs here.

Can I continue earning POKT while I’m unstaking?

No, for the duration of the unstaking process as determined by the UnstakingTime parameter, your node will not be eligible for sessions.

Do each of my nodes need a unique IP address?

You need a dedicated domain for each node, but the nodes can be on the same machine, behind the same IP address. It would take properly configuring your Reverse Proxy and Firewall/Router, but it can be done.

How do I set my ulimit?

Where to set the ulimit

As a best practice, do not use root to run the pocket process. When you set the ulimit for your instance, it’s important to set it in the user profile that is running the pocket-core instance.

Warning

Make sure that you’re setting the ulimit for the specific account that’s running the pocket process.

Configuring the ulimit system-wide might vary depending on your OS. Here’s a basic tutorial on increasing the open files limit on Linux.

How to calculate the ulimit

To calculate the ulimit, you will have to define a few parameters as shown below:

({ulimit -Sn} >= {MaxNumInboundPeers} + {MaxNumOutboundPeers} + {GRPCMaxOpenConnections} + {MaxOpenConnections} + {Desired Concurrent Pocket RPC connections} + {100 (Constant number of wal, db and other open files)}

Breakdown:

  • ulimit -Sn: = is a soft number of open files that need to be open
  • GRPCMaxOpenConnections = is the number of RPC connections connections your node can relay
  • MaxOpenConnections = max number of connections you want your node to service

You will need to increase your ulimit to the calculated number. To do so, go into your .bashrc in your $HOME dir and enter:

ulimit -Sn 16384

Once you save your file, enter:

source ~/.bashrc

What do I do if my node needs to go down for an extended period, such as during a machine migration?

To opt out of being selected for work, you should deliberately jail your node, which lets the network know you are not ready to receive any relays. Once the machine is back up and running, you can unjail your node again.

Node Troubleshooting

Why is my node not earning POKT?

See the section below on Maximizing your POKT earnings.

How do I check my Pocket node status?

Make sure your node is connected to the network by executing:

curl http://<your node ip>:26657/status

Lookout for latest_block_height and latest_block_time to make sure it’s updated to the current time in UTC.

Example Output:

{
  "jsonrpc": "2.0",
  "id": "",
  "result": {
    "node_info": {
      "protocol_version": {
        "p2p": "7",
        "block": "10",
        "app": "0"
      },
      "id": "4930289621aefbf9252c91c4c729b7f685e44c4b",
      "listen_addr": "tcp://0.0.0.0:26656",
      "network": "pocket-testet-playground",
      "version": "0.32.7",
      "channels": "4020212223303800",
      "moniker": "pocket-core-testnet-55f59f6c8-5njbx",
      "other": {
        "tx_index": "on",
        "rpc_address": "tcp://0.0.0.0:26657"
      }
    },
    "sync_info": {
      "latest_block_hash": "090C3B9C3B9F1BB10C6825D5230A45759E19A9BCC1503B80314F93B69162C712",
      "latest_app_hash": "AB5838AA434FD36B48B759E62C596F4145F4C086B07FB45D2CCFCFFF21F5F937",
      "latest_block_height": "49",
      "latest_block_time": "2020-02-10T23:17:59.161691821Z",
      "catching_up": false
    },
    "validator_info": {
      "address": "4930289621AEFBF9252C91C4C729B7F685E44C4B",
      "pub_key": {
        "type": "tendermint/PubKeyEd25519",
        "value": "9i9322nUSMG1bzVAxjPylNI8za8AK/azdtBYoAtRz6o="
      },
      "voting_power": "1000"
    }
  }
}

I keep getting “too many open files” when my node is syncing? What does this mean?

This means that your ulimit is set too low on your node. Find instructions on how to set your ulimit above.

Why does my node keep crashing?

Your node can crash due to the following reasons:

  1. Having too many open files
  2. Resource limitations

Too Many Open Files

Make sure your ulimit is set correctly on your user profile. Find instructions on how to set your ulimit above.

Resource Limitations

Make sure your node meets the minimum hardware requirements for both a Pocket node and the blockchain nodes you’re servicing. Details are above on this page.

Will my node be slashed for downtime?

There are negligible burns at this stage of the network, determined by the SlashFractionDowntime parameter. As the network matures, the rate will probably be increased to push for better service.

Maximizing your Pocket earnings

So you’ve spun up your Pocket node but you’re not earning as much as you thought you would. On this page, we debunk some common misconceptions and explain how to maximize your earnings.

My node is functional but doesn’t seem to be earning POKT - is it configured incorrectly?

There are a couple of reasons why your node may not be rewarding you with POKT. There are many great community members and Pocket teammates that are eager to help you triage this, but first, ask yourself, “is your node configured correctly?”. Don’t assume it is. Use the troubleshooting steps listed above.

The next thing to check is if your node is offline or jailed…or both. Reasons include:

  • Returning incorrect data
  • Missing blocks
  • Being offline
  • serviceURI is not publicly reachable

If you suspect that this may be happening to your node, you can do a historical search on your nodes. We have a great community member who created this script to help you determine how long you were jailed for a specific period of time.

Checking your node status is one of the first steps towards maximizing your POKT earnings.

Conversely, how will I know if my node is working correctly?

Checking the block height is the easiest way to know if you’re synced up to the network. You can simply query your node to get this height and compare it to the latest block displayed on the Explorer.

pocket query height

The above command tells you if your Pocket node is synced up, but you’re probably running at least one other node for the external blockchains (referred to on this page as blockchain data nodes) that you’re serving to apps. You should make sure these are also synced up to their respective networks.

For example, you can check the block height of your Geth Ethereum node by submitting this query to your node, which returns the latest height of geth-mainnet known by the node.

curl --request POST --header 'Content-Type: application/json' --data-raw '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":83}' --user [authentication] [GETH NODE URL]

When will I find out if I have made POKT rewards?

To check if you’re earning rewards, you can simply monitor the balance of your node.

pocket query balance <address>

This way is very manual and you would need to track your balance over time to understand the change in the amounts.

The good news is there are several options for tracking your node rewards such as POKT ROKT, which tracks the last 24 hours of earnings in its CLI dashboard, or Sandwalker which tracks historical rewards by day and month.

Why don’t I just connect my Pocket node to [insert third-party provider here]?

On the surface, this seems like a great idea. Use a free tier of another service (e.g. Infura) and you don’t have to pay for any blockchain data node costs.

First off, free tiers by third-party providers are capped, which limits your upside. To make matters worse, if you use a third-party provider instead of running your own blockchain data node, you won’t make enough POKT to cover the server costs of your Pocket node.

Plus, that doesn’t jive with our ethos now, does it?

Why wouldn’t I make enough POKT with a third-party?

Using third-party providers slows you down. Slower nodes make less revenue.

Why does the third-party slow you down? Increasing the distance between your Pocket node and the third-party blockchain data node increases the number and length of hops that an end-user’s request has to make.

Here is an illustration:

In this example, the Pocket nodes (pink) are on the other side of the US from the Blockchain data nodes (orange). The end-user is using the Portal to communicate with the network. The path the end-user’s request must take is: End-user → Portal → Pocket Node → Blockchain Data Node → Pocket Node → Portal → End-user

The end-user’s request must hop back and forth across the US 4 times and that’s not including the hops between the user and the Portal. As a result, it may take up to 1 second for a user to receive something as simple as a balance query. That’s not very good service.

Aren’t there data centers around the world for this exact reason?

Correct. However, this works against you in this scenario.

Most third-party providers will have their servers in standard cloud regions situated around the world labeled such as East, West, EU, and Singapore. Load balancers are standard. For example, if a user is in Australia, they will be redirected to the nearest server in Singapore.

The challenge with using a third-party provider for your blockchain data node is that, by default, your Pocket Node will not always be in the same data center or machine as the third-party blockchain data node. If your Pocket Node is in US West, while you may have lesser latency from users who are hitting those servers, your node will never be as fast as it could be.

Your node will likely be in a different datacenter, where even a couple of hops will add somewhere between 30ms - 50ms. This becomes exacerbated when a user is coming from US East or the EU. With a full node on US West, you’re adding up to 200ms per request for these users.

Why does the latency matter?

While Pocket Network doesn’t discriminate (yet) between the speed of requests, the Portal does. The Portal filters out slow nodes to ensure the protocol is providing the best service possible to apps.

The vast majority of the requests on the network today come through the Portal. This means that faster nodes = more POKT.

In the long run, your setup matters not only for your earnings but also for ensuring a quality service for end-users (which will ultimately be crucial for the growth of the network).

Then how can I maximize my node revenue?

The following are some best practices that will give you an edge over the majority of node runners.

  • Know where the users are located… and locate your nodes accordingly. The Pocket Portal is currently in US-West-2, US-East-2, EU-West-1, AP-SE-1. The most underserved geographic area on Pocket is currently the Asia Pacific region.
  • Minimize the distance between your Pocket Nodes and your blockchain data nodes. Having your blockchain data nodes next to your Pocket nodes in the same rack is ideal.
  • Load-balance your blockchain data nodes.
  • Use a Peering Tower to reduce P2P gossip on the network. Visit the 🤖node-runner channel on Discord for more information.
  • Use physical hardware at home or data centers; you will have faster nodes and lower costs over time by owning your hardware and co-locating it.
  • Monitor your nodes for both health and sync – being online is only the first step, you must keep your blockchain data nodes in sync or they will not service relays.
  • Use services like the Performance Explorer to monitor your node’s performance in comparison to other nodes.

Integrate

SDKs

Here are some SDKs for interacting with Pocket:

  • PocketJS - JavaScript client SDK for interacting with Pocket Network.
  • pypocket - Python client SDK for interacting with Pocket Network.
  • pocket-go - Go client SDK for interacting with Pocket Network.

Accounts and Transactions

The Native POKT Blockchain Token

POKT is the native token of the Pocket Blockchain. Its lowest, indivisible unit is uPOKT.

POKT and uPOKT

POKT is a 6 decimals token: 1*10^6 uPOKT = 1 POKT

All numbers displayed through RPC calls on the Pocket blockchain are displayed in uPOKT, and all transactions use uPOKT.

Generating Accounts and Sending Transactions

Account Generation and Validation

The simplest way to generate new accounts, or addresses, on the POKT blockchain is to use the official Pocket client, PocketJS.

Creating a New Account

To create a new account on the POKT blockchain and export it:

import { Pocket } from '@pokt-network/pocket-js'

// PocketJS must always be initialized with at least one dispatcher.
const POCKET_DISPATCHER = 'https://dispatch-1.nodes.pokt.network:4201'
const pocket = new Pocket(POCKET_DISPATCHER)

// The passphrase used to encrypt the private key while in memory:
const PASSPHRASE = 'foobar'
const account = await pocket.keybase.createAccount(PASSPHRASE)

// The result of successful account creation:
console.log(account)

// Using the exportAccount function, you can obtain a plaintext private key.
const exportedAccountPrivateKey = await pocket.keybase.exportAccount(
  account.address.toString('hex'),
  PASSPHRASE
)

// This plaintext private key should be encrypted before storage.
console.log(exportedAccountPrivateKey.toString('hex'))

// You can also export an encrypted JSON version of the same private key.
// The passphrase used to encrypt this JSON file is separate from the 
// previous PASSPHRASE.
const exportedPPK = await pocket.keybase.exportPPK(
  exportedAccountPrivateKey,
  // The PPK passphrase used to encrypt the JSON file
  'foo',
  // A hint for the PPK passphrase
  'what comes before bar'
)

console.log(exportedPPK)

Importing an Existing Account

To import an existing account using either the raw private key or the encrypted JSON PPK:

import { Pocket } from '@pokt-network/pocket-js'

// PocketJS must always be initialized with at least one dispatcher.
const POCKET_DISPATCHER = 'https://dispatch-1.nodes.pokt.network:4201'
const pocket = new Pocket(POCKET_DISPATCHER)

// The passphrase used to encrypt the private key while in memory:
const PASSPHRASE = 'foobar'
const PRIVATE_KEY = '...'

// Import an existing account using the raw private key:
const importedAccount = await pocket.keybase.importAccount(
  PRIVATEKEY,
  // The passphrase to encrypt the private key while in memory
  PASSPHRASE
)

// Import an account using the encrypted JSON PPK:
const importedPPKAccount = await pocket.keybase.importPPK(
  // The PPK passphrase used when the key was exported
  'foo',
  exportedPPK.salt,
  exportedPPK.secParam,
  exportedPPK.hint,
  exportedPPK.cypherText,
  // The passphrase to encrypt the private key while in memory
  PASSPHRASE,
)

Verifying an Address

To verify a POKT blockchain address, public key, or raw private key:

import { 
  validateAddressHex, 
  validatePrivateKey, 
  validatePublicKey 
} from '@pokt-network/pocket-js'

// Validate a POKT blockchain address: returns undefined if valid.
// This should be wrapped in a try / catch block as it will throw the 
// appropriate error if the address is not valid.
try {
  const isValidAddress = !(
    validateAddressHex(account.addressHex) instanceof Error
  )
} catch (e) {
  // Handle the error
}

// Validate a public key: returns true or false.
const isValidPublicKey = validatePublicKey(account.publicKey.toString('hex'))

// Validate a private key: returns true or false.
const isValidPrivateKey = validatePrivateKey(privateKey)

Transaction Construction

Sending a Transaction

To send a transaction on the POKT blockchain:

import { Pocket } from '@pokt-network/pocket-js'

const RECEIVER_ADDRESS = '...'
const SENDER_ADDRESS = '...'
const SENDER_PRIVATE_KEY = '...'

  // The passphrase used to encrypt the private key while in memory:
const PASSPHRASE = 'foobar'

// PocketJS must always be initialized with at least one dispatcher.
const POCKET_DISPATCHER = 'https://dispatch-1.nodes.pokt.network:4201'

// To send a transaction, you can use one of the public RPCs or
// your own Pocket node.
const POCKET_RPC = 'https://mainnet-1.nodes.pokt.network:4201'

const pocket = new Pocket(POCKET_DISPATCHER, POCKET_RPC)

// If you are using Pocket Mainnet, make sure to disable legacyCodec
pocket.configuration.useLegacyTxCodec = false;

// Create a transaction signer using the `withPrivateKey` method:
const txSigner = pocket.withPrivateKey(
  SENDER_PRIVATE_KEY
)

const transactionResponse = await txSigner.send(
  // Origin address for the send
  SENDER_ADDRESS,
  // Receiver address
  RECEIVER_ADDRESS,
  // 10 POKT
  '10000000'
  ).submit(
    'mainnet',
    // The transaction fee is always 10,000 uPOKT
    '10000'
  )

// Check if the transaction returned an error:
if (typeGuard(transactionResponse, RpcError)) {
  throw new Error(transactionResponse.message)
}

// You will be able to look up this transaction through this hash after the
// next block clears.
const { hash } = transactionResponse

console.log(hash)

Creating a Signed SEND Transaction Offline

To create a signed transaction that can be sent immediately or stored:

import { Pocket } from '@pokt-network/pocket-js'

const RECEIVER_ADDRESS = '...'
const SENDER_ADDRESS = '...'
const SENDER_PRIVATE_KEY = '...'

// The passphrase used to encrypt the private key while in memory:
const PASSPHRASE = 'foobar'

// PocketJS must always be initialized with at least one dispatcher.
const POCKET_DISPATCHER = 'https://dispatch-1.nodes.pokt.network:4201'
const pocket = new Pocket(POCKET_DISPATCHER)

// If you are using Pocket Mainnet, make sure to disable legacyCodec
pocket.configuration.useLegacyTxCodec = false;

// Create a transaction signer using the `withPrivateKey` method:
const txSigner = pocket.withPrivateKey(
  SENDER_PRIVATE_KEY
)

// Now use the transaction signer to create a signed SEND transaction
const txSignerWithSendTransaction = txSigner.send(
  // Origin address for the send
  SENDER_ADDRESS,
  // Receiver address
  RECEIVER_ADDRESS,
  // 10 POKT
  '10000000'
)

// Generate offline signed send transaction
const sendTx = await txSignerWithSendTransaction.createTransaction(
  'mainnet',
  // The transaction fee is always 10,000 uPOKT
  '10000'
)

console.log('Offline signed send transaction:', sendTx)

After calling .sendTransaction(), you will get back a response with this format:

RawTxRequest {
  address: "1e829f34ce5533c913638310408632242f6fbd43",
  txHex: "d1010a4....bf8970d"
}

Calculate transaction hash from raw transaction bytes

const crypto = require('crypto');

// This is the raw transaction bytes obtained from offline signed transaction
const txHex = 'd1010a4....bf8970d'

const txHash = crypto.createHash('sha256').update(Buffer.from(txHex, 'hex')).digest('hex');

console.log(txHash)

Deserialize offline signed SEND transaction

You can also decode the raw transaction bytes generated offline (only works for SEND transactions):


// Only supported for versions >= 0.7.1
const { ProtoTxDecoder } = require('@pokt-network/pocket-js')

const ENCODED_TX_BYTES = Buffer.from('d1010a4....bf8970d', 'hex')

const protoTxDecoder = await pocket.withProtoTxDecoder()

const protoStdTx = await protoTxDecoder.unmarshalStdTx(ENCODED_TX_BYTES)

const data = await protoTxDecoder.decodeStdTxData(protoStdTx)

console.log('Deserialized transaction:', data)

Transaction Verification

Confirming that Funds have been Received

// The 64-character transaction hash is necessary to retrieve the transaction:
const tx = await pocket.query.getTX(hash)

if (typeGuard(tx, RpcError)) {
    throw new Error(tx.message)
  }

// The retrieved transaction object:
console.log(tx)

The return code of the transaction must be 0 — indicating success:

"tx_result": {
  "code": 0,
  "codespace": "",
  "data": null,
  "events": null,
  "info": "",
  "log": "",
  "message_type": "send",
  "recipient": "...",
  "signer": "..."
}

Consult the error types in Pocket Core for information on failed transactions.

Community

Governance

Pocket Network is a pioneer in a new era of democratically-governed digital public goods. Our Decentralized Autonomous Organization (DAO) means that you, our community, will control all aspects of our protocol and ecosystem.

Pocket uses off-chain governance because it’s the most flexible and future-proof way for us to organize our DAO. For more on our reasoning behind this, check out our Lean Governance Thesis.

To learn how to earn a vote in the DAO and decide the future of Pocket Network, see the section on trophies.

Info

You don’t need a vote in the DAO to submit proposals or participate in discussions! Everyone is free to share their opinions. Head over to the forum to see what decisions are being debated.

To learn how to submit a proposal to the DAO, see the section on proposals.

All approved decisions get submitted to the blockchain by the Pocket Network Foundation, which is fully accountable to the DAO. To learn more about how this is, read the DAO Constitution and the Foundation’s Articles of Association.

Proposals

Submitting proposals to the DAO is pretty easy and anyone can do it.

There are 3 types of proposals:

  • PIP: Pocket Improvement Proposal
  • PEP: Pocket Ecosystem Proposal
  • PUP: Parameter Update Proposal

Posting your proposal to Discourse puts it up for consideration and debate by the DAO. To kickstart a vote, you need a voter to submit it to our governance dashboard on your behalf.

PIP – Pocket Improvement Proposal

Pocket Improvement Proposals (PIPs) include any proposals that aim to level up the Pocket Network ecosystem, through:

  • Upgrading the Pocket Network protocol
  • Upgrading the governance of the DAO and the Pocket Network Foundation
  • Adding/removing permission holders within the existing governance structure of the DAO

PIP votes will last 7 days and pass with Majority Approval (50% yes votes by participating voters) unless otherwise specified in the Constitution.

To submit a PIP, head to the forum here, then click New Topic to generate a template for your proposal.

PEP – Pocket Ecosystem Proposal

Pocket Ecosystem Proposals (PEPs) include proposals to distribute funds to or form agreements with Contributors to the Pocket Network ecosystem, in the form of:

  • Imbursements – payments for future work
  • Reimbursements – compensation for previous work
  • Bounties – rewards for work that don’t yet have specified workers
  • Transfers – transferring funds between DAO-owned accounts
  • Agreements – forming new DAO relationships, including non-financial in nature
Info

How is the DAO funded?

The DAO earns continuous revenue in the form of the DAOAllocation, which is a % that the DAO receives for every RelaysToTokensMultiplier minted in the block reward. This is proportional to the number of relays being processed for app developers, which means the more traction Pocket Network gets, the more wealthy the DAO becomes!

PEP votes will last 7 days and pass with Majority Approval (50% yes votes by participating voters) unless otherwise specified in the Constitution.

To submit a PEP, head to the forum here, then click New Topic to generate a template for your proposal.

PUP – Parameter Update Proposal

Parameter Update Proposals (PUPs) include any proposals to modify the value of the protocol parameters.

PUP votes will last 7 days and pass with Majority Approval (50% yes votes by participating voters) unless otherwise specified in the Constitution.

To submit a PUP, head to the forum here, then click New Topic to generate a template for your proposal.

The following parameters are delegated to the Foundation to manage the parameter on the DAO’s behalf:

Contribute

How to Contribute

Submit an RFP – Highlight a Need

An RFP is a Request for Proposal. You would use this when you know that something is needed but you are unsure of exactly what the solution is or are unable to build it yourself. Posting an RFP should serve as a signal to other community members that there might be demand for their contributions.

For example, this Node Deployment Solutions RFP which led to the successful PEP (POKT grant) for an automated deployment tool called Node Pilot.

To submit an RFP, head to the RFP forum category and click New Topic.

Submit a PEP – Earn a POKT Grant for Your Work

A PEP is a type of proposal that requests a POKT grant from the DAO treasury. You could get a POKT grant for contributions to the Pocket Network ecosystem.

Read more about submitting a proposal.

Submit a PR - Become an Active Pocket v1 Contributor

You can become an open-source contributor by submitting contributions to the Pocket protocol specifications or the main v1 Pocket implementation.

All the issues are documented and tagged on Github, and the “starter task” tag can be used to filter for simpler issues to get you acquainted with the codebase.

All of these contributions are under the MIT license but may be partially rewarded by the scholarship fund. Larger contributions from repeat contributors will be evaluated by the DAO through separate proposals.

In addition to contributing to the future of Web3, you will also get mentorship and experience by working with the core Pocket team, as well as present and discuss your work in our weekly contributor hours.

Check out the #v1-research and #v1-dev channels in Discord to connect with the team.

Scholarships

The PEP-31 Scholarship Fund was approved by the DAO in June 2022 to allocate an accumulating monthly allowance of 10,000 POKT per month to contributors, students, learners, speakers, educators and others in the Pocket community.

Recipients

June 2022

Tyler Kell (@relyt29) is the first recipient of the Pocket Scholarship for his presentation Academic Cryptocurrency Research Space - An Overview, Spring 2022 at Infracon 2022 - Pocket’s inaugral conference.

The slides are available online here and a PDF export is available in the repo here. A sum of 10,000 POKT was awarded in for this work via the following transaction: 6F9EA955FBD509E91B7EC38A6474555E846540090197816A634A03486B133C8C!

Trophies

Claim Your Vote!

The DAO onboarding process has been designed to assign governance powers to the most engaged, knowledgeable, and experienced members of the Pocket Network community.

The steps for obtaining a vote are as follows…

1. Get Qualified

First, you need to prove your knowledge of and participation in the Pocket Network by earning trophies.

There are four paths that you can take on this journey:

You will complete a series of quests and report your completion of these quests in the 🏆trophies channel in Discord. Follow the path guides above to see which quests are up next and how many you need to evolve.

Once you have evolved to the 3rd level of any path, you have qualified for a vote in the DAO. Type !qualify in the 🏆trophies channel to obtain the Qualified role.

2. Get Verified

If you want to be verified by our existing Voters, and obtain the Verified role, you must do both of the following:

  1. Post a selfie to the #✅verify channel holding a piece of paper with your Discord username (e.g. username#1234) and the day’s date
  2. Post a message to the #✅verify channel with the following template:

!verify

My favorite thing about Pocket Network:

Why I want to be a Voter:

Once you have done this, if existing Voters are comfortable you are not a malicious agent, they will approve you. If 33% of existing Voters approve you in the next 7 days, you’ll be officially verified and one step closer to obtaining your own vote in our DAO.

3. Claim Your Vote

Type !claim-vote in the 🏆trophies channel. This will only work if you got both the Qualified and Verified roles.

Then DM jackal to claim your POKTDAO token airdrop (our airdrop bot is currently out of commission).

Info

The token is non-transferable so you should choose a MetaMask or WalletConnect wallet that you’re happy holding the token in forever.

4. Vote and Subscribe

  1. Vote in our governance dashboard by connecting the wallet you chose for your POKTDAO airdrop.
  2. Subscribe to 📥proposals (click Follow) to make sure you don’t miss anything!

App Developers

Netizen

So you want to be a full-fledged Cyberpunk? Joining our elite is not for the faint of heart. You must first prove your worth as a Netizen by completing the following bounty and by providing evidence in the 🏆trophies channel on Discord.

To claim your new Netizen role once you’ve done this, type !become-netizen.

Gateway

Get a Pocket Portal endpoint and send at least 1,000 relays. You can sign up for a Pocket Portal endpoint here.

Info

To verify the number of relays sent by you through the Portal, you need to send an email to jack at pokt dot network, using the same email you used to sign up for the Portal, with the subject as “Gateway Quest” and your applicationPublicKey in the body.

Savant

So you aren’t a poser! Now let’s see if you’re worthy to join the ranks of the Savants. To earn this title, you must complete at least 5 out of 9 of the following bounties, once again providing evidence in the 🏆trophies channel on Discord.

To claim your new Savant role once you’ve done this, type !become-savant.

Maintenance

Build your own tooling or have an approved PR on existing Pocket-related open-source application tooling.

Loadtest

Participate in load testing nodes with at least 1m relays in Pocket testnets.

QA

Create or contribute (non-grammatical) improvements to Pocket application technical documentation or open-source application tooling documentation.

Bootcamp-Dev

Create or contribute (non-grammatical) improvements to a guide on how to use Pocket for other app developers.

Mentor

Help another app developer get started using Pocket.

Torrent

This bounty is split into 4 parts, each worth 1 point towards your 5/9 target:

  1. Send 2.5 million relays through Pocket Network.
  2. Send 5 million relays
  3. Send 7.5 million relays
  4. Send 10 million relays

Qualified!

Once you’ve reached Savant, you’re now qualified for a vote in our DAO.

Cyberpunk

Well done Savant, we recognize the trials you have taken on and the skills you have acquired to reach this point. The bounties at this point are the ones that will build lasting resilience and autonomy for the future we seek to create. Complete all bounties from every rank of the App Developer path then submit the !become-cyberpunk command to enter the elite of the elite, the pantheon of Cyberpunks.

Token-Handler

Build tooling for AAT management and have 3 Verified Savants or Pocket core team members vouch for the tool’s quality.

Optimizer

Build tooling for optimizing app stake prices and have 3 Verified Savants or Pocket core team members vouch for the tool’s quality.

Founded

Create or take ownership of an application, SDK, or tool that is vouched for by at least 3 (BrightID) Verified Savants or Pocket core team members.

Ventured

Submit an application-oriented PEP and receive a POKT grant from the DAO.

Node Runners

Nodégé

Greetings aspiring Node Runner, we have heard your call to join us in the battle against the corporate node overlords. In order to earn the Nodégé rank, you must complete 3/3 of the following assignments, providing evidence in the 🏆trophies channel, then submit the !become-nodege command.

Server

Stake your node successfully in Pocket testnet or mainnet.

Info

To verify that you own the account, you must sign a message using the following CLI command, removing the <> and the ""

pocket accounts sign <account address> "account address"

Then send your address, public key, and the signature that was generated by the command to the 🏆trophies channel.

Transmission

Successfully submit a proof transaction in Pocket testnet or mainnet.

Jailbreak

Avoid getting jailed for 7 days (672 consecutive blocks) in Pocket testnet or mainnet.

Nodemad

Congratulations Nodégé, lesser nodes have not made it this far, we are pleased with your progress. To earn the Nodemad rank, you must complete 5/8 of the following assignments, providing evidence in the 🏆trophies channel, then submit the !become-nodemad command.

Datacenter

Avoid getting jailed for 1 month (2880 consecutive blocks) in Pocket mainnet.

Broadcast

Submit successful proof transactions of 50k relays in Pocket mainnet.

Overseer

Help another community member set up their node.

Toolkit

Build and open source your own tooling or have an approved PR on existing Pocket-related open source node tooling.

Betakey

Participate in beta testing for a new Pocket Core version and submit the results of at least one useful test, as vouched for by the Pocket Core developers.

Document

Create or contribute (non-grammatical) improvements to Pocket node technical documentation or open source node tooling documentation.

Bootcamp-Node

Create or contribute (non-grammatical) improvements to a guide on how to run a Pocket node.

Upgrade

Upgrade your node before the DAO’s chosen upgrade height.

Qualified!

Once you’ve reached Nodemad, you’re now qualified for a vote in our DAO.

Node Runner

You’ve proven yourself a key member of our node army. Complete all assignments from every rank of the Node Runner path then submit the !become-node-runner command to cement your legacy in the pantheon of our greatest Node Runners.

Cloud

Avoid getting jailed for 3 months (8640 consecutive blocks), for at least 5 Pocket nodes, in Pocket mainnet.

Livestream

Submit successful proof transactions of 1M relays in Pocket mainnet.

Infrared

Submit an infrastructure-oriented PEP and receive a POKT grant from the DAO.

Testkit

Participate in beta testing for 3 Pocket Core versions (excluding the one you did for the Betakey quest) and submit the results of at least one useful test, as vouched for by the Pocket Core developers.

Satellite

Maintain a dispatch node and have 3 Verified Netizens or Pocket core team members vouch that they have included you in their dispatch list.

Seedbank

Maintain a seed node and have 3 Verified Nodégés or Pocket core team members vouch that they have included you in their seed list.

Relay-Station

Submit successful proof transactions of 50k relays in all whitelisted RelayChainIDs in Pocket Mainnet.

Community Shepherds

Farmer

Namaste aspiring Shepherd, we kindly thank you for your willingness to nurture this community into one that is regenerative and ripe with autonomous agents. While our allies in the Node Runner and App Developer paths are fortifying our outposts and advancing our objectives, the jobs on this ranch serve to replenish our ecosystem. To join the rank of Farmers, complete 6/8 of the following jobs, providing evidence in the 🏆trophies channel, then submit the !become-farmer command.

Seed-Pouch

Swap the RPC endpoints on your wallets with Pocket. (Find your network information here.)

Info

To verify that you used the app, screen record yourself submitting an on-chain action (e.g. submitting a transaction or querying chain data), with your Discord username somewhere on the screen, then share the screen recording to 🏆trophies when you report the quest completion.

Quick-Repair

Highlight (and fix where possible) inconsistencies/bugs or other improvements in Pocket’s website, documentation, social channels or content.

Bird-Seed

Tweet about Pocket in a meaningful way, retweeted by 3 Verified Shepherd’s or Pocket core team members.

Swarm

Identify and share 3 relevant (unshared) tweets that other Farmhands can respond to.

Dogfood

Confirm that you have used two community apps.

Info

To verify that you used the app, screen record yourself submitting an on-chain action (e.g. submitting a transaction or querying chain data), with your Discord username somewhere on the screen, then share the screen recording to 🏆trophies when you report the quest completion.

Seedling

Generate 1 unique idea for future iterations of the trophy system.

Leaflet

Create a Pocket meme and get at least 5 dab reacts from Verified Shepherd’s or Pocket core team members.

Fertilizer

Purchase Discord Nitro and boost Pocket Network’s community server.

Shepherd

At this point you have now familiarized yourself with the ways of the Farmers. Your studies at this level will seek to align you more deeply with the vision and mission that has brought us together. Completing 4/6 of the following jobs will earn you a flight to the Shepherd’s station. Provide proof of your work in the 🏆trophies channel, then submit the !become-shepherd command.

Attend a Pocket workshop or community call.

Biomimicry

Make notes/takeaways from a Pocket workshop or community call.

Nanobee

Help to organize a Pocket workshop or community call.

Foraging

Collect and organize user feedback/questions for the Pocket core team.

Cultivation

Mentor anyone into achieving the Farmer rank.

Path-of-Least-Resistance

Create educational content for Pocket.

Qualified!

Once you’ve reached Shepherd, you’re now qualified for a vote in our DAO.

Regen

“De lo mio”, Shepherd. In our homeland, this term of endearment means “one of mine”. Because you have made it here, we consider you to be one of our closest allies in a mission yet unfulfilled. But there is little time for frivolities, the enemy has expanded into the farthest reaches of Web3 and we must continue to cultivate the lands upon which our node and dev allies will fight them. The work of Shepherds requires the softest of touches, as you will be venturing out to guide others towards the regenerative path of true decentralization. Complete every job in all ranks of the Community Shepherd path then submit the !become-regen command to earn enlightenment in the pantheon of Regens.

Telepathy

Create meaningful content about Pocket Network, vouched for by 3 Verified Shepherd’s or Pocket core team members.

Topographics

Translate content on Pocket’s website, blog or docs.

Wool-Clipper

Successfully onboard an app developer into Pocket Network.

Shepherds-Crook

Successfully onboard a node runner into Pocket Network.

Sheep-Dog

Successfully onboard 5 node runners into Pocket Network.

Seed-Fund

Submit a community-orientated PEP and receive a POKT grant from the DAO.

Assurance

QA and document a Pocket library, product or pre-release.

Governor/Contributors

Biohacker

Greetings fledgling DAOist and aspiring Biohacker. It is now time to augment your skills via the cybernetic system, Pocket DAO, to truly enhance this community’s mission. You will be considered a true Biohacker if you acquire 2/3 of the following augments, providing evidence in the 🏆trophies channel, then submit the !become-biohacker command.

Anode

Author any successful proposal

Successfully claim a vote.

Sentinel

Successfully challenge an action.

Warning

This quest can’t be completed currently because our proposal challenge system isn’t live yet.

Cyborg

We’re impressed with your augmentation capabilities, but to truly become a Cyborg you’ll need to acquire 3/5 of these augments, providing evidence in the 🏆trophies channel, then submit the !become-cyborg command.

Cybernetic-Arm

Author a successful PIP (independent of the Anode quest).

Cybernetic-Leg

Author a successful PUP (independent of the Anode quest).

Implanted-Rebreather

Author a successful PEP (independent of the Anode quest).

Feedback-Loop

Author a successful constitutional amendment.

Regulated-Nervous-System

Join the Aragon Court.

Warning

This quest can’t be completed currently because Aragon Court isn’t live yet.

Singularity

Qualified!

You’re now qualified for a vote in our DAO. Follow the rest of the steps outlined here to claim your vote:

So you have ventured where few still dare to go. Your current augments allow for deeply integrated communications with our cybernetic organization. Acquire every augment from all ranks in the Governor path then submit the !become-singularity command and you may just unlock infinite power… The Singularity is near…

Nanobots

Author 3 successful PEPs (independent of previous quests).

Machine-Learning

Author 3 successful PUPs (independent of previous quests).

Artificial-Intelligence

Author 3 successful PIPs (independent of previous quests).

Quantum-Resistance

Author 3 constitutional amendments (independent of previous quests) or successfully challenge 3 actions.

Warning

The latter option of this quest can’t be done currently because our proposal challenge system isn’t live yet.

Contributing to the Documentation

If you’ve never worked with these kinds of tools before, that’s okay. The following pages are dedicated to walking you through how to accomplish all of these steps without assuming you’ve ever done this before.

We understand that the people who have a lot of valuable insight and information very often aren’t software developers, and we took this into consideration when selecting the technologies we did. We specifically focused on selecting the most accessible tools for someone who has never done any of these steps in the past.

The Short Version

If you do have a basic familiarity around using command line tools and GitHub, then the process can be summarized down to the following steps.

  1. Clone/fork this repository.
  2. Install hugo; Make sure the version is 0.93 or newer.
  3. From the root of the repository, run hugo serve, and open http://127.0.0.1:1313 in a browser.
  4. From a text editor, make any desired changes to the file(s) in content/.
  5. As you edit, save the changes to the file to see the changes in your browser.
  6. When you have the desired result, submit a pull request of the changes.

If this is too condensed, the rest of the pages in this cover all of these steps in more detail.

Initial Setup

Required Installations

There are only 2 tools needed to get started contributing to the documentation:

  1. hugo version 0.93 or newer.
  2. git

Installing Hugo

For this guide, we’re going to cover the easiest way to install hugo, which is downloading an already built executable. If you would prefer to install from a package manager like brew, chocolately, or apt, then you should follow along with the corresponding installation guide from hugo’s documentation.

First you’ll want to navigate to the releases page for hugo. You’ll be greeted with a bunch of text describing the latest release.

Releases Page

Note: the version number might not match.

From there you’ll want to scroll down until you see a heading called Assets.

Assets for download

From here, you’ll want to click on build for your system to download it.

Installing the Executable

If you’re on a Windows computer, you need to know how many bits the operating system is, and what kind of processor you’re running.

If you’re unsure of these things, you can find them by:

  1. Opening the Settings App.
  2. Navigate to System, then About
  3. The details are available under the System type value.

Using those details you should install your corresponding version.

  • 64-bit - x64: hugo_<ver>_Windows-64bit.zip
  • 64-bit - ARM: hugo_<ver>_Windows-ARM64.zip
  • 32-bit - x86: hugo_<ver>_Windows-32bit.zip
  • 32-bit - ARM: hugo_<ver>_Windows-ARM.zip

Then make a new folder called C:\Hugo\bin.

Move the downloaded .zip file into the newly created C:\Hugo\bin folder. Then double click on the .zip file and extract its contents. The folder should now contain the following 3 new files:

  • hugo.exe
  • LICENSE
  • README.md

From here, we’re going to need to add hugo to your Windows PATH settings to know that hugo means to run the hugo.exe program in this folder. To do this in Windows 10, you’ll need to go through the following steps:

  1. Right click on the Start button.
  2. Click on System.
  3. Click on Advanced System Settings
  4. Click on the button that says Environment Variables… on the bottom
  5. Click on the button that says Browse…, and select the C:\Hugo\bin folder.
  6. Click OK on all following windows.

Using Package Managers

Alternatively, you can use the following if you have Chocolately installed.

choco install hugo -confirm

Or the following if you have Scoop installed.

scoop install hugo

Installing the Executable

If you’re on a Mac with an Intel Processor, you should use hugo_<ver>_macOS-64bit.tar.gz.

If you’re on a Mac with an M1/M2 Processor, you should use hugo_<ver>_macOS-ARM64.tar.gz.

Once you’ve downloaded the corresponding release, we’ll need to open up a Terminal, and start by making a folder for the hugo program.

mkdir -p ~/bin

Then we’re going to navigate into it.

cd ~/bin

From here, we’re going to extract the downloaded release into this folder.

tar -xvzf ~/Downloads/hugo_<ver>_macOS-<ARCH>.tar.gz

Where <ver> is going to match the version you downloaded, and <ARCH> will match given then processor in your Mac.

After this, we’re going to check if hugo is in your path by running:

which hugo

If there’s no answer, that means we have to add it to your path.

First we’ll need to see which shell you’re working with by running:

echo $SHELL

If the answer is zsh, you’ll want to run:

echo "export PATH=$PATH:$HOME/bin" >> ~/.zprofile

and if the answer is bash you’ll want to run:

echo "export PATH=$PATH:$HOME/bin" >> ~/.bash_profile

Finally close your terminal. When opening a new terminal, hugo will be ready to use.

Using Package Managers

Alternatively, you can also run the following if you have Homebrew installed.

brew install hugo

Or the following if you have MacPorts installed.

port install hugo

If you’re on Linux/OpenBSD, it’s highly recommended you use a package manager install hugo since it does not require a new install like in Windows and Mac.

Debian, Ubuntu

snap install hugo

Arch

sudo pacman -Syu hugo

Fedora, Red Hat, CentOS

sudo dnf install hugo

openSUSE Tumbleweed

sudo zypper install hugo

OpenBSD

doas pkg_add hugo

Install git

You’ll want to download and install the corresponding Git for Windows Setup, depending on if your system is 32 or 64 bit. Instructions for how to do so can be found in the section above for installing hugo.

From a terminal run

git --version

If it’s not installed, you’ll be prompted with an installer.

Debian, Ubuntu

sudo apt install git

Arch

sudo pacman -Syu git

Fedora, Red Hat, CentOS

sudo dnf install git

openSUSE Tumbleweed

sudo zypper install git

OpenBSD

doas pkg_add git

While this is everything you need to get up and editing the documentation site, if you’re used to working in something like Google Docs or Microsoft Word, I’d recommend getting setup with an environment that will take care of content editing, managing git changes, and running the hugo commands all in one place. If you’d prefer to use your own tools, know that you’ll be expected to do the following:

  • Start and stop the hugo live server from the command line.
  • Manage git changes and commits from the command line.
  • Edit Markdown files directly from a text editor, not a document editor like Word or Docs.

If you already have a text editor of choice, vim, emacs, sublime etc, I recommend checking out the following page for plugins that will help with working with hugo.

If you don’t have a text editor of choice, I’d recommend installing Visual Studio Code. It comes built with the tools we need to work with hugo and git without having to resort to a command line.

Once you have Visual Studio Code installed, you’ll want to launch it and install the following plugins:

More Information

Pocket Network is an open-source multi-stakeholder community. Therefore, the best way to contact us is to join our community in Discourse and Discord.

Discord

You can join our Discord. We recommend doing this if you want to keep your finger on the pulse.

Be sure to start in the #👋welcome channel, where you can choose the topics you’re interested in.

Discourse (Pocket Forum)

Social Media

You can find us on the following sites: