Skip to main content

MainNet Release Procedure

Purpose of this document

Operational (non-technical) instructions on releasing an upgrade to MainNet

Table of Contents ​

1. Protocol Upgrade Preparation​

2 Keep Clear Communication​

Keep the following stakeholders in the loop along the way

  1. Pocket Network Discord Server; Beta TestNet and MainNet
  2. Grove Pocketd Discord
  3. Exchanges that support Pocket Network and communicate via telegram

The format of the announcements is always changing so you can reference prior ones below:

3. BEFORE the Day of the Upgrade​

We'll use v0.1.29 as an example for this section.

3.1 Choose a height​

  1. Visit the MainNet Grafana Dashboard to get the current height of the blockchain
  2. Review the latest block times of the network by checking network stats, grove's infra or config.toml; usually 30s per block.
  3. Account for the fact that session tokenomics can take 1-10s as of writing depending on how much traffic the network is managing.
  4. Determine a future height that gives the ecosystem a few days to prepare. See the tip below.
  5. For your particular upgrade (e.g. v0.1.29), update the height in tools/scripts/upgrades/upgrade_tx_v0.1.29_main.json:
Determining future block height

You can ask ChatGPT to help you determine the future block height. For example:

We need to pick the block height for a future release.
- Current block height: 482210
- Block time: 30s
- Session overhead: every 30 minutes, there account for an extra 10 seconds
- Current time: 10:00am PST on 10/27/2025
- Target release time: 10:00am PST on 10/28/2025

What block height should we set?

3.2 Submit the Upgrade on MainNet​

Run the following command:

./tools/scripts/upgrades/submit_upgrade.sh main v0.1.29 --instruction-only

Look for Submit the upgrade transaction. You should end up running a command similar to the following:

pocketd \
    --keyring-backend="test" --home="~/.pocket" \
    --fees=300upokt --network=main  --from=pokt18808wvw0h4t450t06uvauny8lvscsxjfyua7vh \
    tx authz exec tools/scripts/upgrades/upgrade_tx_v0.1.29_main.json

And you can verify it is onchain like so:

pocketd query upgrade plan --network=main -o json | jq

3.3 Broadcast Telegram Announcement​

Firstly, install the gh CLI

Prepare the announcement like so (using a concrete example for v0.1.29)

cat <<'EOF' >> release_prep_announcement.txt
📢 Pocket Network Upgrade Notice 📢

v0.1.29 is scheduled to go live approximately 10:00 PST on Tuesday (09/16/2025) at block height 382,991.

Find all the details here: https://github.com/pokt-network/poktroll/releases/tag/v0.1.29.

EOF

Then, run a test broadcast:

make telegram_test_broadcast_msg MSG_FILE=release_prep_announcement.txt

If it looks good, broadcast it to all exchanges:

make telegram_broadcast_msg MSG_FILE=release_prep_announcement.txt

4. ON the Day of the Upgrade​

4.1 Prepare another snapshot​

See the instruction in Protocol Upgrade Preparation on how to prepare a snapshot.

You can find existing snapshots at snapshots.us-nj.poktroll.com.

4.2 Monitor the Upgrade​

Run the following command for your upgrade version and use the recommended commands and dashboards to monitor the upgrade:

./tools/scripts/upgrades/submit_upgrade.sh main v0.1.29 --instruction-only
warning

Wait for the upgrade to complete before proceeding to the next step.

4.3 Create a post-upgrade announcement​

See the instruction in Protocol Upgrade Preparation to create a post-upgrade snapshot.

4.4 Update the GitHub Release Notes​

Generate a table of the upgrade heights and tx hashes like so:

./tools/scripts/upgrades/prepare_upgrade_release_notes.sh v0.1.29

Insert the table above the auto-generated release notes.

👉 Mark it as latest release 👈

4.5 Update the Documentation Upgrade List​

Update the Upgrade List Documentation with the new upgrade.

Use the release notes to populate the upgrade list.

4.6 Send out an announcement to all exchanges​

Prepare release_prep_announcement.txt
cat <<'EOF' >> release_prep_announcement.txt
📢 Pocket Network Upgrade Update 📢

The network successfully upgraded to `v0.1.29` at height `382,250` around 12pm PST on Tuesday (09/16/2025).

Please make sure update your binaries and full nodes to the latest:
https://github.com/pokt-network/poktroll/releases/tag/v0.1.29

Snapshots are available here: https://snapshots.us-nj.poktroll.com/ 💾

If you need an RPC endpoint, let us know and [Grove](https://www.grove.city/) will happily help out 🌿

❓ What's new ❓
- Improved RelayMiner performance
- Validator reward distribution
- Additional supplier configurations and management
- A lot of quality of life enhancements

EOF

Then, run a test broadcast:

make telegram_test_broadcast_msg MSG_FILE=release_prep_announcement.txt

If it looks good, broadcast it to all exchanges:

make telegram_broadcast_msg MSG_FILE=release_prep_announcement.txt

5. Update the pocketd binary​

Once the upgrade is validated, update the tap so users can install the new CLI.

Run the following steps:

git clone git@github.com:pokt-network/homebrew-pocketd.git
cd homebrew-pocketd
make tap_update_version
git commit -am "Update pocket tap from v.<Previous Version> to v.<New Version>"
git push

Note: Make sure to update v0.1.20 and v0.1.29 in the commit message above.

Reinstall the CLI:

brew reinstall pocketd

OR

curl -sSL https://raw.githubusercontent.com/pokt-network/poktroll/main/tools/scripts/pocketd-install.sh | bash -s -- --upgrade

Alternatively, install it for the first time:

brew tap pocket-network/homebrew-pocketd
brew install pocketd

OR

curl -sSL https://raw.githubusercontent.com/pokt-network/poktroll/main/tools/scripts/pocketd-install.sh | bash

6. How to Cancel an Upgrade​

In emergency situations, you may need to cancel a pending upgrade.

You can run the cancellation command like so:

pocketd \
    --keyring-backend="test" --home="~/.pocket" \
    --fees=300upokt --network=main \
    tx authz exec tools/scripts/upgrades/cancel_upgrade_main.json --from=pokt18808wvw0h4t450t06uvauny8lvscsxjfyua7vh

Verify Upgrade Status​

You can check the current upgrade plan status (whether pending or cancelled) using:

pocketd query upgrade plan --network=main -o json | jq
Emergency Use Only

The upgrade cancellation command should only be used in emergency situations where the upgrade needs to be stopped before it executes.

Make sure to inform Exchanges of the cancellation
cat <<'EOF' >> release_prep_announcement.txt
Reminder that v0.1.29 is still scheduled to go live at approximately 10:00am PST tomorrow, Tuesday (09/16/2025).

Due to some slower blocks, we have updated the upgrade height from 382,991 to 382,250.

Find all the details here: https://github.com/pokt-network/poktroll/releases/tag/v0.1.29.

EOF

Then, run a test broadcast:

make telegram_test_broadcast_msg MSG_FILE=release_prep_announcement.txt

If it looks good, broadcast it to all exchanges:

make telegram_broadcast_msg MSG_FILE=release_prep_announcement.txt