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 Environments.

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
• Explore the Portal
• Test Your Endpoint

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

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.

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).

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.

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

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

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

Smart Contract Environments

POKT Wallets

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

In this section, we’ll describe some different wallets that can store and manage POKT:

• Pocket Wallet (Official)
• SendWallet

Pocket Wallet

You can use the official wallet web app to create and manage your wallet.

Create wallet

To create a POKT wallet with the official Pocket wallet web app You can use the official wallet web app to create your wallet.

1. Click “Create”.

2. Enter a unique passphrase.

3. 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.

4. Click “Reveal Private Key” then enter your passphrase again to reveal the Private Key for your 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.

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).

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.

Now supporting Unstoppable Domains in the POKT Wallet.

Users can now send transactions to an Unstoppable Domain from a POKT Wallet address. Create an Unstoppable Domain for your wallet here.

For guidance on how to send a transaction with a UD, check out this video:

SendWallet

SendWallet is a browser-based Pocket Network wallet built by SendNodes.

SendWallet features:

• Import using the Key File from a Pocket Wallet
• Import using a private key
• Generate multiple wallet addresses with one account
• Recovery phrase to recover wallet
• Full screen option

You can try SendWallet by downloading the browser extension for Chrome or Firefox.

For more information on how to use SendWallet, see the SendWallet documentation.

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.

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.

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.

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.

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.

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:

• Utility
• Consensus
• Peer-to-Peer
• Persistence

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.

Protocol Parameters

This page contains a listing of all the on-chain parameters for Pocket Network and their current values, as well as some relevant off-chain parameters.

These parameters are sorted by module. You can find a description of each parameter by clicking on the parameter name.

Parameter values

Application Module (details)

PoS (Node) Module (details)

Pocket Core Module (details)

Auth Module (details)

Governance Module (details)

Off-chain parameters (details)

Application Module

These parameters control staked applications on the network.

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.

For example, if this parameter is 200000 then the throughput that apps are entitled to is 2,000 relays per POKT staked.

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.

The ParticipationRate is a proposed tool to dynamically adjust maximum relays for applications without the intervention of the DAO as network usage changes. ParticipationRate would act as a proxy for utilization of the network and would adjust an application’s MaxRelays dynamically based on the growth or decline in network-wide stake rates.

The ParticipationRate is not currently implemented, and as such, ParticiapationRateOn is set to false.

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. When this parameter is set to 0, no adjustment is being made.

PoS (Node) Module

These parameters relate to staked nodes on the networ, including how rewards are calculated.

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.

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.

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.600000000000000000

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

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: 485

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.000000000000000000

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: 2.735000000000000000

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.

SlashFractionDoubleSign

Current Value: 0.000001000000000000

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

SlashFractionDowntime

Current Value: 0.000001000000000000

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

These parameters control the logic that has to do with how the proof and claim cycles for servicers operate.

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 the RelayChainIDs for all of the supported blockchains.

Auth Module

These parameters control how transactions are constructed.

FeeMultipliers

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.

Governance Module

These parameters control governance on the Pocket Network.

ACL

Access control list for updating the on-chain parameters. Currently all parameters are owned and managed by the DAOOwner address.

DAOOwner

Current Value: a83172b67b5ffbfcb8acb95acc0fd0466a9d4bc4

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

Upgrade

Current Value:

• Height: 74616

• Version: 0.9.1.1

• OldUpgradeHeight: 74540

• Features:

  • MREL: 69232
  • NCUST: 74620
  • REDUP: 57620
  • RSCAL: 69232

An object describing the details of a protocol upgrade, consisting of the following fields:

• Height: Specifies when the upgrade was applied
• Version: Version that the upgrade brought
• OldUpgradeHeight: Block height when the previous upgrade was last applied
• Features: List of feature flags and the block heights at which they should be activated

Off-Chain parameters

These parameters are not on-chain, but are relevant off-chain values that are targeted by the Pocket DAO.

ReturnOnInvestmentTarget

Current Value: 24 months

The desired time it takes for the USDRelayTargetRange price to be achieved, since the cost basis of a relay decreases over the lifetime of an app stake.

USDRelayTargetRange

Current Value: $0.00000361 per relay

The target price per relay after a certain amount of usage (equal to the ReturnOnInvestmentTarget. After usage for this amount of time, your cost per relay will equal this amount. This parameter is set by the DAO.

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.

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

Endpoints

Pocket-Powered dApps

Environment Setup

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

Hardware

Hardware Requirements: 4 CPUs/vCPUs | 16 GB RAM | 500GB Disk

Software

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

• Source
• Homebrew
• Docker

Source

Install your dependencies:

• go, plus go environment environment variables GOPATH and GOBIN
• git

Create source code directory:

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

Download the source code of Pocket core:

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

Checkout the latest release of Pocket core:

git checkout tags/<release tag>

git checkout tags/RC-0.9.2

Make sure you have your $GOPATH environment variable set correctly:

echo $GOPATH

/home/<username>/go

Build from source and place the build in the $GOPATH/bin directory:

go build -o $GOPATH/bin/pocket <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

AppVersion: RC-0.9.2

Homebrew

You can also use Homebrew to build Pocket Core instead of building from source.

Install your dependencies:

• go, plus the go environment and the environment variables GOPATH and GOBIN
• Homebrew (Mac or Linux)

Install using Homebrew:

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

Test your installation:

pocket version

AppVersion: RC-0.9.2

Docker

See Pocket Core Deployments on GitHub for details on how to install using Docker.

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 open files limit

ulimit -Sn 16384

Secure your server

Make sure the server that hosts your node is protected by up-to-date anti-virus and anti-malware software, as well as a firewall.

Your node’s private key will be available in plaintext on the server, so your key is only as secure as your server.

Pocket Node Setup

Once you have your environment set up, you are now ready to deploy your node.

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>

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 export option. 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

Learn more about securely managing your POKT accounts.

Fund the account

To stake a node in Pocket Network, the account must have a balance above the minimum stake, which is 15,000 POKT (or 15,000,000,000 uPOKT).

Send POKT with the following command:

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

You won’t be able to send POKT using the command line until you have your node 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 operator

pocket accounts set-validator <address>

Set Relay Chains

A Relay Chain is a blockchain that a Pocket node connects to or runs in order to service applications. Applications access Relay Chains through the serviceURI, the endpoint where nodes publicly expose the Pocket API. You can view a list of all the Relay Chains that Pocket supports.

Once you have your Relay Chains properly configured, you can set up your node to serve requests to those Relay Chains via the generate-chains command. Relay Chains are referenced through a four digit ID (example: 0021 for Ethereum Mainnet).

pocket util generate-chains

A wizard will step you through the process of adding each Relay Chain ID, and will output a $HOME/.pocket/config/chains.json file when done.

If you were only servicing Pocket nodes, the response would look like this:

> 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

Setup the Genesis Configuration File

Genesis files can be found here:

• Mainnet Genesis File
• Testnet Genesis File

The appropriate genesis file should be placed at .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

If successful, you’ll see a 200 OK response. If you see a 400 Bad Request, you either have incorrect/missing parameters in the request or bad formatting in the data field.

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

Download 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.

Stake the node

Stake the account to participate in the network. Staking as a servicer node 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 at least 1 POKT 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.

Custodial and Non-Custodial Staking

Pocket has 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 was activated as of version 0.9.1.3.

Node runners who staked their nodes prior to activation of non-custodial staking will have one opportunity to decide if they want their nodes to have custodial 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 activation of non-custodial staking, this was the only option that node runners had.

Non-custodial staking

Non-custodial staking allows for the separation of the node operator and reward recipient accounts. There are two Pocket accounts involved in the process: the operator account and the output account.

The operator account is responsible for signing claims and proofs, as well as block proposals and attestations. It needs to have some unstaked POKT to pay for these transactions.

The output account receives all rewards generated by the node. It also receives the original stake once the node is unstaked.

Non-custodial staking can be initiated by any operator or output account with sufficient POKT balance. The staked POKT will be taken from the account that initiates staking, and sent to the output account when unstaked.

Both the operator and output accounts can perform the staking and also any and all node maintenance (unstake, unjail, update relay chains, 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 scenario. 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 when non-custodial staking was activated. Please see below for the updated command syntax.

Custodial staking:

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

pocket nodes stake custodial 0123456789012345678901234567890123456789 15100000000 0001,0021 https://pokt.rocks:443 mainnet 10000 false

Non-custodial staking:

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

pocket nodes stake non-custodial 0123456789012345678901234567890123456789012345678901234567890123 0123456789012345678901234567890123456789 15100000000 0001,0021 https://pokt.rocks:443 mainnet 10000 false

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 parameter <isBefore8.0> is boolean. It was set to be a transitional variable to denote whether or not the non-custodial activation has occurred. As this feature is now active, you will need to set this to false.
• Be aware that the non-custodial command takes the operator public key as the argument (<operatorPublicKey>), not the operator wallet address 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, including all parameters, 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.

Unstaking

The unstaking process is the same using custodial or non-custodial staking.

pocket nodes unstake <operatorAddr> <fromAddr> <networkID> <fee> <isBefore8.0>

pocket nodes unstake 0123456789012345678901234567890123456789 0123456789012345678901234567890123456789 mainnet 10000 false

During the unstaking process, a transaction is not generated when sending the staked POKT to the output address. This is intended behavior, and is similar to how proofs work on the blockchain.

In order to verify that your POKT is where it should be, we recommend querying the blockchain directly, instead of relying on a block explorer service that may not interpret the results accurately.

You can use the interactive API Docs to query the balance for an address at a given block height. Try it here.

More information

• PIP-9 Consensus Rule Change
• Pocket Core docs
• Pocket Core releases

Trustless Third Party Staking

Trustless Third Party Staking utilizes the protocol’s non-custodial staking feature to stake POKT without handing over custody of tokens to the Node Operator at any stage. With this method, Node Operators have no ability to steal either the stake or the rewards. Clients can also unstake without any intervention of the node operator and get their funds back.

Before proceeding, consult with your preferred Node Operator to verify if they support this method of staking.

This document demonstrates how to stake a node with 15k tokens and later upstake it to 60k. Initially staking with 15k minimizes potential losses resulting from mistakes (e.g., typing incorrect output addresses or public keys).

The Non-Custodial Staking method requires the following addresses/wallets

Output Address This is a wallet address that holds your funds and where staking rewards will be sent. It is also known as the non-custodial address because you retain full control over it. It is crucial never to share the private key associated with your output address and to make ample backups to ensure its security. Output wallet can be created and accessed here: https://wallet.pokt.network

Operator Address Created by the Node Operator, this address is used to manage and run your node. The Node Operator, using the key of the operator address, shares the responsibility for editing the Domain and Chains with the Output Address. However, the Operator Address cannot control the funds; only the Output Address has this capability

The very first stake initiated from the output address establishes a link between the operator address and the output address.The Node Operator can then start running your node using the operator address. Any node rewards will be sent to the output address. Additionally, if unstaked, the unstaked funds will also go to the output address. An output address can be linked to multiple operator addresses

Introduction

Staking Bins: You can stake 15k, 30k, 45k, or 60k+ tokens per node. Stake-Weighted Servicer Rewards is a mechanism that offers higher rewards to node runners who stake more POKT on their nodes, with rewards determined by organizing nodes into bins based on their stake amount. The higher the stake, the greater the reward multiplier. A 30k pocket node will earn the same as two 15k nodes for instance. It is a good practice to stake 10 tokens on top of that.

More Info: stake-weighted-servicer-rewards

Viewing Non-Custodial Staking on POKTScan

https://poktscan.com/node/bab0bc034cbf4ae82a5069b677e8c2f39098e361

Note the stake type is “Non-Custodial”. Also note that the address of the node is different from the output address. In the example above:

Operator Address: bab0bc034cbf4ae82a5069b677e8c2f39098e361
Operator Address Public Key: d7a3f683341a5fd82adf4f4411544527ba15726d9558c5b83b9a2c6946b4df44
Output Address: 3574ca25de8744aa167cff234b69b8a4eef97711

Notice there is a balance of 36.57 present. The node requires some POKT to pay for claiming rewards and also any staking operations(edit domain/chain) the node operator will perform. Either the output address owner or the node operator can keep the operator account topped up periodically.

IMPORTANT: Any balance in the operator address is accessible by the node operator. Do not send any amount other than what is intended to be used for fees, or better yet, let your node operators manage reward transaction fees.

Output Address Checklist

• I know my output address and I want my staked funds (when unstaked) and rewards to be sent here. I have backed it up safely and I will not share the private keys/keyfile of this address ever.

Information to get from your Node Operator:

Node Operator Checklist

• Operator Address
• Operator Public Key
• Chains your Nodes Operator will support
• Domain

Preparing the Output Address

1. Login to your output address using the pocket official wallet below. Note down the password used to create the wallet. https://wallet.pokt.network/
2. IMPORTANT: Backup the keyfile.json using “export keyfile” and the password. Lose this and you will lose your funds. Then send 15011 tokens to this address. 15010 will be staked, leaving one for transaction fees.(Each transaction costs 0.01 POKT at the time this doc is written)

Staking Non-Custodial

1. Login to your output address wallet
2. Go to the staking Tab: https://wallet.pokt.network/staking
3. Fill in the operator public key, output address, chains, and domain from the above checklists.

4. Hit the Stake Node Button and verify your stake on POKTScan in 15-20 minutes.

Checklist

• I verified that the node is staked non-custodial on POKTScan at the url https://poktscan.com/node/<myoperatoraddress> and it is showing the correct output address.

Managing Non-Custodial Nodes (Upstake)

1. Ensure you have correctly staked your node.
2. Login to your output address wallet, which must have a minimum balance of 45,001 POKT.
3. Complete the same staking form, but enter 60,010 instead of 15,010 to upstake (60010-15010 = 45000 is the amount to “upstake”)

Managing Non-Custodial Nodes (Unstake)

1. Login to your output address wallet
2. Go to manage non custodial Nodes
3. Enter Operator Address
4. Hit Unstake

FAQs

If the node operator unstakes from the operator keys where will the staked funds go? Unstaking by either account sends staked funds to the output address at the end of the 21 day unbonding period.

Can the output address be changed once staked? The output address cannot be changed once staked; ensure it’s correct and backed up.

How to verify that the output address is receiving the rewards? Verify the output address is receiving rewards by checking its balance increase on POKTScan.

Can the operator change the chains or service url? The operator can change chains or the service URL; consult your node operator or POKTScan for the latest information before upstaking.

Can I reuse the output address for another operator address? You can reuse the output address for another operator address; rewards and unstaked funds from both operators will be sent to the output address.

If all rewards end up in the output account, how does the node operator get their reward share? Node operators can’t access your rewards; you must send their share manually.

LeanPocket

LeanPocket (sometimes stylized as “LeanPOKT”) is a configuration that enables multiple Pocket instances to run on a single process, allowing node runners to consolidate resources, resulting in better scalability and reduced hardware costs.

LeanPocket is a feature available from version 0.9.2 and above.

Background

Pocket Core is a multi-threaded application, however, historically it has only allowed for one node per process. This means that if you wanted to run multiple Pocket nodes on the same server, each node, running its own isolated process, would each use their own resources: RAM, disk space, network throughput, etc. As many aspects of nodes use shared resources (copies of the blockchain, most notably) this was deemed very inefficient.

For example, at the time of writing, a Pocket node requires a minimum of 500GB of disk space and 16GB of RAM, and that’s not including the requirements of the other chains the node may be servicing.

LeanPocket is an optimization to the core client to allow nodes to share resources, significantly reducing resource requirements. This is a non-consensus-breaking change to the client.

The following charts show the benefits of implementing LeanPocket in your node fleet, though individual results will vary.

Setup

To enable LeanPocket:

1. Create a new lean_nodes_keys.json file inside your Pocket configuration directory (typically .pocket).

2. Format the file with a JSON array of your node’s private keys:

   [
     { "priv_key": "<PRIVATE_KEY_1>" },
     { "priv_key": "<PRIVATE_KEY_2>" }
   ]
   

3. Set/update your validators:

   pocket accounts set-validators <path/to/lean_nodes_keys.json>
   

   Info

   Note the plural form in the command. The option set-validators is distinct from set-validator and is only relevant for LeanPocket.

4. Edit your node’s config.json file to add lean_pocket: "true"; in the pocket_config block.

   Info

   In some cases, the lean_pocket option may already be added to your config.json file, so make sure to search for it before potentially adding a duplicate value. If you find lean_pocket: "false"; change it to "true".

5. If you run a script that starts the Pocket service, add --keybase=false to the pocket start command.

6. Edit your proxy settings such that the /v1 endpoint is publicly accessible for every one of your nodes.

   Warning

   Failure to do this will prevent your nodes from broadcasting the correct version, which will interfere with consensus-related upgrades. When properly configured, all of your nodes should output the current version of Pocket Core on the /v1 endpoint.

7. Restart your Pocket service, making sure to add the --keybase=false option.

Tips

• Using --forceSetValidators as an argument when starting Pocket will ensure that your validators are updated every time the process starts. If using this argument, you won’t have to use the set-validators command when you update your lean_node_keys.json file.

• Do not use --useCache as an argument when starting Pocket, as it can delay restarting your node.

• You can get a list of node with the get-validators command:

  pocket accounts get-validators
  

• You can add metadata to your lean_node_keys.json file for organizational purposes:

  [
    {
        "priv_key": "<PRIVATE_KEY_1>",
        "node_name": "first example"
    }
  ]
  

Testing

When the Pocket Core process first starts, if LeanPocket is activated, it will try to initialize an evidence and session cache for each node.

Therefore, you will see output like this in the logs:

Initializing {node address 1} session and evidence cache
Initializing {node address 2} session and evidence cache
Initializing {node address 3} session and evidence cache
Initializing {node address 4} session and evidence cache

Considerations and Risks

• Because your nodes are commingling resources with LeanPocket, there is a risk of downtime on all of your nodes simultaneously. Depending on your risk for downtime, we recommend that you institute some form of failover system for your nodes, or perhaps divide your nodes into multiple LeanPocket-managed groups.
• Since all LeanPocket nodes use the same configuration, it is not possible to serve different groups of chains on each individual node. Each node uses the same chains.json file.
• If you are converting your node fleet into using fewer servers (or just one), you will want to ensure that your server open file limit (ulimit and fd on Linux-based systems) is sufficient, as these values still scale linearly with each additional node.
• We don’t recommend running Validator nodes via LeanPocket at this time, because of the increased importance of the consensus state on the network.
• Be aware that without LeanPocket, there is a one-to-one correlation between a node and its Peering ID, so when you use set validator, it will set the Peering ID to be the validator. However, with LeanPocket, the first node in the list is your Peering ID for every node managed by LeanPocket.

Updating Your Node

It is very important, both for network security and for performance of your own node, to keep your Pocket node up-to-date with the latest version of the Pocket software. The following steps will show you how to update your Pocket 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 update your node. Check the release notes for release-specific details.

Shutdown Pocket Core

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

pocket stop

Backup 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.

Ensure the latest Go version

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

go version

If you need to update Go, use this guide.

Alternatively, if you use g, you can just run

sudo apt-get update
g install <version number>

Checkout latest Pocket Core

Source

Navigate into pocket-core directory

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

Check out the latest release:

git pull
git checkout tags/RC-0.9.2

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.9.2

docker pull poktnetwork/pocket:RC-0.9.2

Update config.json

Run the update-configs command, which creates a new config file ($HOME/.pocket/config/config.json) and backs up the old config file ($HOME/.pocket/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.

Start Pocket

Start pocket running again.

pocket start

You can then test your node.

Automated Deployments

The following services can help automate your node deployments:

• Node Pilot
• DAppNode
• PoktRokt

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.

• List of Node-Hosting Services

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.

Seeds

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

You can use the --seeds flag when starting the Pocket process to set the seeds for your Pocket node. Alternatively, you can set the seeds in your config.json file under the "P2P" block.

Mainnet

1. 7c0d7ec36db6594c1ffaa99724e1f8300bbd52d0@seed1.mainnet.pokt.network:26662
   

2. cdcf936d70726dd724e0e6a8353d8e5ba5abdd20@seed2.mainnet.pokt.network:26663
   

3. 74b4322a91c4a7f3e774648d0730c1e610494691@seed3.mainnet.pokt.network:26662
   

4. b3235089ff302c9615ba661e13e601d9d6265b15@seed4.mainnet.pokt.network:26663
   

To start Pocket Core on mainnet, using all the above seeds:

pocket start --seeds="7c0d7ec36db6594c1ffaa99724e1f8300bbd52d0@seed1.mainnet.pokt.network:26662,cdcf936d70726dd724e0e6a8353d8e5ba5abdd20@seed2.mainnet.pokt.network:26663,74b4322a91c4a7f3e774648d0730c1e610494691@seed3.mainnet.pokt.network:26662,b3235089ff302c9615ba661e13e601d9d6265b15@seed4.mainnet.pokt.network:26663" --mainnet

Testnet

1. d90094952a3a67a99243cca645cdd5bd55fe8d27@seed1.testnet.pokt.network:26668
   

2. 2a5258dcdbaa5ca6fd882451f5a725587427a793@seed2.testnet.pokt.network:26669
   

3. a37baa84a53f2aab1243986c1cd4eff1591e50d0@seed3.testnet.pokt.network:26668
   

4. fb18401cf435bd24a2e8bf75ea7041afcf122acf@seed4.testnet.pokt.network:26669
   

To start Pocket Core on testnet, using all the above seeds:

pocket start --seeds="d90094952a3a67a99243cca645cdd5bd55fe8d27@seed1.testnet.pokt.network:26668,2a5258dcdbaa5ca6fd882451f5a725587427a793@seed2.testnet.pokt.network:26669,a37baa84a53f2aab1243986c1cd4eff1591e50d0@seed3.testnet.pokt.network:26668,fb18401cf435bd24a2e8bf75ea7041afcf122acf@seed4.testnet.pokt.network:26669" --testnet

Pocket Node FAQ

The following sections contain common questions regarding running Pocket nodes.

Node Configuration

• Does my blockchain node need to be synced before I start my Pocket node?
• How many blockchains can one node support?
• Can I add a load balancer address in my chains.json if I have multiple blockchains under one domain?
• How can I add more blockchains to my node?
• Can I continue earning POKT while I’m unstaking?
• Do each of my nodes need a unique IP address?
• How do I set my ulimit?
• What do I do if my node needs to go down for an extended period, such as during a machine migration?
• Can I change the output address for my node when doing non-custodial staking?
• Why don’t I see a transaction on the blockchain when I unstake my non-custodial node? How do I know my POKT is being sent to the output address?
• Where do my staked funds go when I send a stake command?

Node Troubleshooting

• Why is my node not earning POKT?
• How do I check my Pocket node status?
• I keep getting “too many open files” when my node is syncing? What does this mean?
• Why does my node keep crashing?
• Will my node be slashed for downtime?

Maximizing your Pocket rewards

• My node is functional but doesn’t seem to be earning POKT - is it configured incorrectly?
• Conversely, how will I know if my node is working correctly?
• When will I find out if I have made POKT rewards?
• Why don’t I just connect my Pocket node to [insert third-party provider here]?
• Why wouldn’t I make enough POKT with a third-party?
• Aren’t there data centers around the world for this exact reason?
• Why does the latency matter?
• Then how can I maximize my node revenue?

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?

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.

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.

Can I change the output address for my node when doing non-custodial staking?

You can’t edit an existing output address for your node stake. You will have to instead unstake your node and then restake with a different output address. Keep in mind that when you unstake, your staked POKT will be sent to the output address you originally set when staking your node, so make sure you have access to that account. Learn more about non-custodial staking.

Why don’t I see a transaction on the blockchain when I unstake my non-custodial node? How do I know my POKT is being sent to the output address?

Unstaking a node will not yield a separate transaction on the blockchain, so to verify that the POKT was sent to the output address, you will need to query the blockchain manually. Learn more.

Where do my staked funds go when I send a stake command?

When you send a stake command, your funds are moved to one of the protocol-owned account addresses responsible for managing aggregated staked funds, known as pools. There are separate pool addresses for staked nodes and apps.

Staked Nodes Pool Address:

• Pool Name: nodeTypes.StakedPoolName
• Address: 8ef97b488e66a2b2e89a3b4999549816768910fb

Staked Apps Pool Address:

• Pool Name: appTypes.StakedPoolName
• Address: 63533fb8f43b4883a1f37265f1561ce7b1c6c307

Example of a pool:

{
    "app_staked": "6115776140835",
    "dao": "85404378779681",
    "node_staked": "888675724041371",
    "total": "1577387511505541",
    "total_staked": "980195878961887",
    "total_unstaked": "597191632543654"
}

The funds remain in the pool during the staking period. When you initiate an unstaking process, the funds are moved back from the pool to your staking account.

To check the pool balances, query pocket query supply using the CLI.

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: Make sure your ulimit is set correctly on your user profile. Find instructions on how to set your ulimit above.
2. 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 rewards

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.

Why does the balance of an address change when there are no transactions in a given block?

This happens when an address is also a Validator. Validators earn block rewards when they are a proposer for a given block. Block rewards aren’t claimed through transactions, but instead are sent directly to the address.

This is inherited behavior from Tendermint and the Cosmos SDK, from which Pocket was originally derived. It is considered “core business logic” for the chain, and therefore does not need to be a transaction. That said, there are plans to change this behavior in v1 to increase transparency and visibility into block rewards.

To see how this works, take the address 85efd04b9bad9da612ee2f80db9b62bb413e32fb. At block height 4406, the balance for that address was 1848.257793 POKT, as you can test below using cURL (or using the API docs):

curl -H "Content-Type: application/json" -d '{"height": 4406, "address": "85efd04b9bad9da612ee2f80db9b62bb413e32fb"}' -X POST https://mainnet-1.nodes.pokt.network:4201/v1/query/balance

{
 "balance": 1848257793
}

But for the subsequent block, the balance was 1853.342684 POKT:

curl -H "Content-Type: application/json" -d '{"height": 4407, "address": "85efd04b9bad9da612ee2f80db9b62bb413e32fb"}' -X POST https://mainnet-1.nodes.pokt.network:4201/v1/query/balance

{
 "balance": 1853342684
}

You can verify that there are no transactions associated with that address in block 4406.

Finally, you can see that this address was the proposer for block 4406:

curl -H "Content-Type: application/json" -d '{"height": 4406}' -X POST https://mainnet-1.nodes.pokt.network:4201/v1/query/block | jq '.block.header.proposer_address'

"85EFD04B9BAD9DA612EE2F80DB9B62BB413E32FB"

So in this case, the balance of the address is altered, but without a visible transaction.

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.