MainNet Release Procedure

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

1. Protocol Upgrade Preparation

(See linked preparation docs where applicable.)

2. Keep Clear Communication

Keep the following stakeholders in the loop along the way:

  • Pocket Network Discord Server; Beta TestNet and MainNet

    • Beta TestNet: https://discord.com/channels/553741558869131266/1384591252758200330

    • MainNet: https://discord.com/channels/553741558869131266/1234943674903953529

  • Grove Pocketd Discord: https://discord.com/channels/824324475256438814/1138895490331705354

  • Exchanges that support Pocket Network and communicate via telegram:

    • https://github.com/pokt-network/poktroll/blob/main/.github/workflows/telegram-send-message.yml

Reference previous announcements:

  • Beta TestNet Announcement Channel: https://discord.com/channels/553741558869131266/1384589692355477696

  • MainNet Announcement Channel: https://discord.com/channels/553741558869131266/1384589604153331732

3. BEFORE the Day of the Upgrade

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

1

Choose a height

  1. Visit the MainNet Grafana Dashboard to get the current height of the blockchain:

    • https://grafana.poktroll.com/goto/8MB3RPRDg?orgId=1

  2. Review the latest block times of the network by checking network stats, Grove's infra, or config.toml:

    • Grove infra: https://github.com/buildwithgrove/infrastructure/blob/dfbc02c57bbc5e61ae860393ec35d45b6a6fc3d5/environments/protocol/vultr-sgp/kubernetes-manifests/mainnet/config-files.yaml#L505

    • config.toml: https://github.com/pokt-network/pocket-network-genesis/blob/master/shannon/mainnet/config.toml

    • Typical block time: usually ~30s per block.

  3. Account for session tokenomics overhead (can add ~1–10s depending on network traffic).

  4. Determine a future height that gives the ecosystem a few days to prepare.

  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 — example prompt you can use with ChatGPT:

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?
2

Submit the Upgrade on MainNet

Run:

./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:

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

Verify it is on-chain:

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

Broadcast Telegram Announcement

  1. Install the GitHub CLI: https://cli.github.com/

  2. Prepare the announcement (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

  1. Run a test broadcast:

make telegram_test_broadcast_msg MSG_FILE=release_prep_announcement.txt

  1. If it looks good, broadcast to all exchanges:

make telegram_broadcast_msg MSG_FILE=release_prep_announcement.txt

4. ON the Day of the Upgrade

1

Prepare another snapshot

See Protocol Upgrade Preparation for snapshot instructions:

  • https://dev.poktroll.com/develop/upgrades/upgrade_preparation

Existing snapshots:

  • https://snapshots.us-nj.poktroll.com/

2

Monitor the Upgrade

Run:

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

Use recommended dashboards and commands to monitor the upgrade progress.

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

3

Create a post-upgrade announcement

See Protocol Upgrade Preparation for instructions to create a post-upgrade snapshot:

  • https://dev.poktroll.com/develop/upgrades/upgrade_preparation

4

Update the GitHub Release Notes

Generate a table of the upgrade heights and tx hashes:

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

Insert the generated table above the auto-generated release notes:

  • https://github.com/pokt-network/poktroll/releases

Mark the release as "latest release".

5

Update the Documentation Upgrade List

Update the Upgrade List Documentation with the new upgrade:

  • https://dev.poktroll.com/develop/upgrades/upgrade_list

Use the release notes to populate the upgrade list:

  • https://github.com/pokt-network/poktroll/releases/latest

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

Test broadcast:

make telegram_test_broadcast_msg MSG_FILE=release_prep_announcement.txt

If it looks good, broadcast 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 Homebrew tap so users can install the new CLI.

Run:

git clone [email protected]: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 the versions in the commit message accordingly.

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 (first-time install):

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.

Run the cancellation command:

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

Check the current upgrade plan status (whether pending or cancelled):

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. Example announcement:

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

Test broadcast:

make telegram_test_broadcast_msg MSG_FILE=release_prep_announcement.txt

If it looks good, broadcast:

make telegram_broadcast_msg MSG_FILE=release_prep_announcement.txt
PreviousUpgrade PreparationNextLocalNet Upgrade Testing

Was this helpful?