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. Determine a future height that gives the ecosystem a few days to prepare.
  4. For your particular upgrade (e.g. v0.1.29), update the height in tools/scripts/upgrades/upgrade_tx_v0.1.29_main.json:

3.2 Submit the Upgrade on MainNet​

Run the following command and follow the instructions:

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

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​

Assuming you have the gh cli installed, run the following command and verify the message is properly formatted:

make telegram_test_release

You can then broadcast the release to all exchanges by running:

make telegram_release_notify
TODO: Releases that are too long

You might get an error that the message is too long.

If this happens, then:

  1. Remove unnecessary content from the release notes
  2. Run the workflow again
  3. Revert the release with all the details

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