Governance Parameters

Overview

Every network needs rules. In traditional companies, executives decide the rules. In Pocket Network, the community decides through governance — a transparent, on-chain process where changes are proposed, reviewed, and executed.

Think of parameters like the settings on a thermostat. You do not need to rebuild your heating system to change the temperature — you just turn the dial. Similarly, Pocket Network’s parameters let the community adjust how the network operates without rewriting the underlying code.

All parameters live on the blockchain itself, which means they are public, auditable, and tamper-proof. Anyone can see what the current settings are at any time.

Who Can Change Parameters?

Parameter changes must be authorized by the governance authority — essentially the DAO (Decentralized Autonomous Organization) that oversees the network. On MainNet, the Pocket Network Foundation (PNF) acts as the authorized agent to execute parameter changes on behalf of the DAO.

There are two ways parameters get updated:

• One at a time — A single setting is adjusted while everything else stays the same.
• All at once for a module — Every setting in a particular area is submitted together. This requires extra care because any setting left out could be accidentally reset to zero.

For the technical details of how parameter updates are submitted, see the developer documentation.

Application Module Parameters

Applications are the actors that pay for data access. They stake POKT tokens to use the network’s API services. These parameters control the rules for applications.

Gateway Module Parameters

Gateways sit between applications and suppliers, providing a quality-of-service layer. They are especially useful for enterprises that want reliable, managed access to blockchain data without running their own infrastructure.

Supplier Module Parameters

Suppliers are the backbone of Pocket Network — they are the node operators who actually serve the data. When an application requests blockchain data, it is a supplier that answers. These parameters define the entry requirements for suppliers.

Service Module Parameters

Services represent the specific APIs and blockchains available through Pocket Network — for example, Ethereum Mainnet, Polygon, or POKT itself. These parameters govern how services are registered and how the network manages relay traffic.

Session Module Parameters

Sessions are time-bounded windows during which a specific group of suppliers is paired with an application to serve data requests. Sessions are how Pocket Network organizes its permissionless marketplace of data providers.

Proof Module Parameters

The proof system is how Pocket Network verifies that suppliers actually did the work they claim they did. Rather than checking every single relay (which would be prohibitively expensive), the network uses a probabilistic approach — it randomly audits a fraction of sessions to keep suppliers honest. These parameters control that auditing process.

Shared Module Parameters

The shared module contains settings that affect multiple parts of the network. These are the fundamental timing and pricing parameters that coordinate how sessions, claims, proofs, and unbonding all work together.

Session Timing

Claim and Proof Windows

After a session ends, there is a structured sequence for suppliers to submit their work claims and proofs:

Think of this sequence like filing an expense report at work: you have a deadline to submit the report (claim window), and then a deadline to submit receipts if audited (proof window).

Unbonding Periods

When a participant decides to leave the network, their staked tokens are not returned immediately. There is a waiting period called “unbonding” to ensure all outstanding claims and proofs are settled first.

Pricing

Together, these two parameters determine the price of each relay using a simple formula: the multiplier divided by the granularity gives the cost per compute unit. The community can adjust both values to fine-tune the economics of the network.

Tokenomics Module Parameters

Tokenomics parameters control the economic engine of Pocket Network — how tokens are minted, distributed, and potentially burned. These are among the most impactful settings in the entire protocol.

These parameters give the community powerful tools to manage the network’s economy. By adjusting inflation, distribution, and the mint ratio, the DAO can steer Pocket Network toward sustainability and growth.

Migration Module Parameters

These parameters specifically control the Morse-to-Shannon migration process — the transition from the old version of Pocket Network to the new one. For a full explanation of the migration itself, see the Migration section.

Parameter Update Workflow

When a parameter change is needed, it follows a structured, transparent process:

1. Review current settings — The current values are checked to understand the starting point.
2. Propose changes — The proposed update is documented publicly (typically as a proposal or pull request) so the community can review it.
3. Community review — Stakeholders discuss the proposed change and its potential impact.
4. Execute the change — Once approved, PNF (acting on behalf of the DAO) submits the update transaction to the blockchain.
5. Verify the result — The new parameter values are confirmed on-chain to ensure the change took effect correctly.
6. Record the change — The transaction is documented for the permanent audit trail.

This process ensures that every parameter change is public, auditable, and traceable. No one can silently change the rules of the network.

All Parameters Reference Table

Below is a complete summary of every governance parameter in Pocket Network Shannon, organized by module.

This document covers every governance-controlled parameter in the Pocket Network Shannon protocol, organized by module. It explains how parameters are queried, updated, and managed through the on-chain governance process.

Overview

Pocket Network Shannon uses a parameter governance system built on the Cosmos SDK x/authz module. On-chain parameters control the behavior of the protocol — from session lengths to tokenomics distributions. All parameter changes must be authorized by the governance authority (the x/gov module account) or an authorized grantee such as PNF.

The governance authority address is deterministic across all Pocket networks:

pokt10d07y265gmmuvt4z0w9aw880jnsr700j8yv32t

On MainNet, PNF acts as the authorized grantee to execute parameter changes on behalf of the DAO.

Updating Parameters: MsgUpdateParams vs MsgUpdateParam

Pocket Network provides two mechanisms for parameter updates:

When using MsgUpdateParams, always query the current parameters first and include all values in the update message. Only modify the parameters you intend to change.

Querying Current Parameters

Before making changes, query the current values:

pocketd query shared params --network=main

Submitting a Single Parameter Update

To update a single parameter, create a JSON transaction file:

{
  "body": {
    "messages": [
      {
        "@type": "/pocket.session.MsgUpdateParam",
        "authority": "pokt10d07y265gmmuvt4z0w9aw880jnsr700j8yv32t",
        "name": "num_suppliers_per_session",
        "as_uint64": "50"
      }
    ]
  }
}

Then submit it using authz exec:

pocketd tx authz exec /tmp/update_param.json \
  --from pnf \
  --yes \
  --network=main \
  --fees 200upokt

Submitting a Full Module Parameter Update

For MsgUpdateParams, create a JSON file with all parameters included:

{
  "body": {
    "messages": [
      {
        "@type": "/pocket.tokenomics.MsgUpdateParams",
        "authority": "pokt10d07y265gmmuvt4z0w9aw880jnsr700j8yv32t",
        "params": {
          "mint_equals_burn_claim_distribution": {
            "dao": "0.1",
            "proposer": "0",
            "supplier": "0.8",
            "source_owner": "0.1",
            "application": "0"
          },
          "dao_reward_address": "pokt1f0c9y7mahf2ya8tymy8g4rr75ezh3pkklu4c3e",
          "global_inflation_per_claim": "0.000001",
          "mint_equals_burn_claim_distribution": {
            "dao": "0.045",
            "proposer": "0.14",
            "supplier": "0.79",
            "source_owner": "0.025",
            "application": "0"
          },
          "mint_ratio": "0.975"
        }
      }
    ]
  }
}

Submit the transaction:

pocketd tx authz exec /tmp/update_all_tokenomics_params.json \
  --from pnf \
  --keyring-backend test \
  --chain-id pocket-lego-testnet \
  --node https://shannon-testnet-grove-rpc.beta.poktroll.com \
  --fees 200upokt \
  --yes

Authorization and Access Control

Checking Grants

To see what authorizations the governance account has granted:

# Grants issued by the x/gov module account
pocketd query authz grants-by-granter pokt10d07y265gmmuvt4z0w9aw880jnsr700j8yv32t --network=main

# Grants received by the PNF grantee
pocketd query authz grants-by-grantee pokt1hv3xrylxvwd7hfv03j50ql0ttp3s5hqqelegmv --network=main

Adding a New Authorization

To authorize a new grantee for a specific message type:

pocketd tx authz grant \
  pokt1newgrantee... \
  "pocket.migration.MsgUpdateParams" \
  --from pnf \
  --expiration 16725225600 \
  --network=main \
  --gas auto

Application Module Parameters

Query with: pocketd query application params --network=main

Live values (fetched at build time):

params:
  max_delegated_gateways: "7"
  min_stake:
    denom: "upokt"
    amount: "1000000000"

Gateway Module Parameters

Query with: pocketd query gateway params --network=main

Live values (fetched at build time):

params:
  min_stake:
    denom: "upokt"
    amount: "5000000000"

Supplier Module Parameters

Query with: pocketd query supplier params --network=main

Live values (fetched at build time):

params:
  min_stake:
    denom: "upokt"
    amount: "59500000000"
  staking_fee:
    denom: "upokt"
    amount: "1"

Service Module Parameters

Query with: pocketd query service params --network=main

Live values (fetched at build time):

params:
  add_service_fee:
    denom: "upokt"
    amount: "3500000000"
  target_num_relays: "100000"

Session Module Parameters

Query with: pocketd query session params --network=main

Live values (fetched at build time):

params:
  num_suppliers_per_session: "50"

Proof Module Parameters

Query with: pocketd query proof params --network=main

Live values (fetched at build time):

params:
  proof_request_probability: 0.001
  proof_requirement_threshold:
    denom: "upokt"
    amount: "10000000"
  proof_missing_penalty:
    denom: "upokt"
    amount: "1"
  proof_submission_fee:
    denom: "upokt"
    amount: "1"

Shared Module Parameters

Query with: pocketd query shared params --network=main

The shared module contains cross-module parameters that affect session timing, unbonding periods, and compute unit pricing.

The compute_unit_cost_granularity works with compute_units_to_tokens_multiplier to determine per-relay cost:

compute_unit_cost_in_uPOKT = compute_units_to_tokens_multiplier / compute_unit_cost_granularity

Live values (fetched at build time):

params:
  num_blocks_per_session: "60"
  grace_period_end_offset_blocks: "10"
  claim_window_open_offset_blocks: "11"
  claim_window_close_offset_blocks: "10"
  proof_window_open_offset_blocks: "1"
  proof_window_close_offset_blocks: "10"
  supplier_unbonding_period_sessions: "504"
  application_unbonding_period_sessions: "1"
  compute_units_to_tokens_multiplier: "77033"
  gateway_unbonding_period_sessions: "1"
  compute_unit_cost_granularity: "1000000"

Tokenomics Module Parameters

Query with: pocketd query tokenomics params --network=main

New in v0.1.31: The mint_ratio parameter was introduced via PIP-41 to enable deflationary tokenomics. When set below 1.0, a fraction of each settlement is permanently burned, gradually reducing total supply.

Live values (fetched at build time):

params:
  dao_reward_address: "pokt1dr5jtqaaz4wk8wevl33e7vkxsjlphljnjhyq2l"
  mint_allocation_percentages:
    dao: 0.1
    proposer: 0
    supplier: 0.8
    source_owner: 0.1
    application: 0
  global_inflation_per_claim: 0.000001
  mint_equals_burn_claim_distribution:
    dao: 0.045
    proposer: 0.14
    supplier: 0.79
    source_owner: 0.025
    application: 0
  mint_ratio: 0.975

Migration Module Parameters

Query with: pocketd query migration params --network=main

These parameters control the Morse-to-Shannon migration process.

Live values (fetched at build time):

params:
  waive_morse_claim_gas_fees: true
  allow_morse_account_import_overwrite: false
  morse_account_claiming_enabled: true

Parameter Update Workflow

A complete governance parameter update follows these steps:

1. Query current values to understand the existing state.
2. Create a PR with the proposed changes documented (for audit trail).
3. Generate an update template using the governance scripts or manually.
4. Modify the parameters in the generated JSON file.
5. Submit the transaction via pocketd tx authz exec.
6. Verify the changes by re-querying the module parameters.
7. Merge the PR with the transaction hash recorded.

Batch Updates Across All Modules

The repository provides helper scripts for managing parameters at scale:

# Query all parameters across all modules
./tools/scripts/params/gov_params.sh query-all --env main

# Update parameters for a specific module
./tools/scripts/params/gov_params.sh update tokenomics --env main

# Batch update all modules from JSON config files
./tools/scripts/params/update_all_params.sh main

Verifying a Transaction

After submitting a parameter update, verify the transaction result:

pocketd query tx --type=hash <TRANSACTION_HASH> --network=main

Then confirm the updated parameter values:

pocketd query tokenomics params --network=main

All Parameters Reference Table