Skip to main content

Protocol Upgrade Release Procedure

important

This is the step-by-step (almost) 🖨🍝 checklist for core protocol developers to release protocol upgrades.

❗ DO NOT PROCEED if you are not comfortable with Git, GitHub releases, scripting, etc❗

If this is your first time managing an upgrade: ​

Table of Contents ​

0. Communicate​

Start a discord thread similar to this v0.1.21 thread to communicate updates along the way in case of any issues.

gh CLI Telegram Broadcast

If you have the gh CLI installed, you can give exchanges a warning that a release will go out over the next few hours or days.

make telegram_broadcast MSG="📣 Update from Pocket Network: `v0.1.21` is scheduled for release in approximately 1-3 days 📣"

1. Prepare a New Upgrade Handler​

  1. Identify the version of the latest release from the full list of releases (e.g. v0.1.20)

  2. Prepare a new upgrade handler by copying vNEXT.go to the next release (e.g. v0.1.21) like so:

    cp app/upgrades/vNEXT.go app/upgrades/v0.1.21.go

  3. Open v0.1.21.go and replace all instances of vNEXT with v0.1.21.

  4. Remove all the general purpose template comments from v0.1.21.go.

  5. Open app/upgrades.go and:

    • Comment out the old upgrade
    • Add the new upgrade to allUpgrades

  6. Prepare a new vNEXT.go by copying vNEXT_Template.go to vNEXT.go like so:

    cp app/upgrades/vNEXT_Template.go app/upgrades/vNEXT.go

  7. Open vNEXT.go and remove all instances of Template.

  8. Create a PR with these changes and merge it. (Example):

 git commit -am "Adding v0.1.21.go upgrade handler"
 git push

2. Create a GitHub Release​

  1. Tag the release using one of the following and follow on-screen prompts:

    make release_tag_minor
    # OR
    make release_tag_major

  2. Publish the release by:

    • Following the onscreen instructions from make target (e.g. pushing the tag)
    • Drafting a new release
    • Use the tag above to auto-generate the release notes

  3. Set as a pre-release (change to latest release after upgrade completes).

😎 Keep Calm and Wait for CI 😅

Wait for the Release Artifacts CI job to build artifacts for your release.

It'll take ~20 minutes and will be auto-attached to the release under the Assets section once complete.

3. Prepare the Upgrade Transactions​

Generate the new upgrade transaction JSON files like so:

./tools/scripts/upgrades/prepare_upgrade_tx.sh v<YOUR_VERSION>.<YOUR_RELEASE>.<YOUR_PATCH>

For example:

./tools/scripts/upgrades/prepare_upgrade_tx.sh v0.1.21

This will create:

tools/scripts/upgrades/upgrade_tx_v0.1.21_alpha.json
tools/scripts/upgrades/upgrade_tx_v0.1.21_beta.json
tools/scripts/upgrades/upgrade_tx_v0.1.21_local.json
tools/scripts/upgrades/upgrade_tx_v0.1.21_main.json

Note that the height is not populated in the *.json files. This will be updated in subsequent steps below.

Example JSON snippet:
{
  "body": {
    "messages": [
      {
        "@type": "/cosmos.upgrade.v1beta1.MsgSoftwareUpgrade",
        "authority": "pokt10d07y265gmmuvt4z0w9aw880jnsr700j8yv32t",
        "plan": {
          "name": "v0.0.4",
          "height": "30",
          "info": "{\"binaries\":{...}}"
        }
      }
    ]
  }
}
Optional: Validate the Upgrade Binary URLs

Install go-getter if you don't have it:

go install github.com/hashicorp/go-getter/cmd/go-getter@latest

And check all binary URLs:

RELEASE_VERSION=<VERSION> # E.g. "v0.1.11"
for file in ./tools/scripts/upgrades/upgrade_tx_${RELEASE_VERSION}*; do
  echo "Processing $file"
  jq -r '.body.messages[0].plan.info | fromjson | .binaries[]' "$file" | while IFS= read -r url; do
    go-getter "$url" .
  done
done

Expected output should look like the following:

2025/04/16 12:11:36 success!
2025/04/16 12:11:40 success!
2025/04/16 12:11:44 success!
2025/04/16 12:11:48 success!

4. [Complex Upgrades Only] Test the New Release Locally​

Chain Halt Risk

If your upgrade handle had complex business logic, you MUST test it locally to avoid a chain halt.

Follow Testing Protocol Upgrades BEFORE submitting any transactions.

If you find an issue, you'll need to:

  1. Delete the previous release
  2. Delete the previous tag
  3. Implement and merge in the fix
  4. Prepare a new release
  5. Regenerate the artifacts
  6. Repeat the process above

5. Submit the Upgrade on each network​

Familiarize yourself with the playbook

If this is your first time submitting a tx upgrade, run the following command and familiarize yourself with the playbook that gets generated before procedding:

./tools/scripts/upgrades/submit_upgrade.sh beta v0.1.21

Then proceed to generate the real commands.

If you are submitting the upgrade for v0.1.21, follow the instructions generated by the prepare_upgrade_tx.sh script for each environment.

./tools/scripts/upgrades/submit_upgrade.sh alpha v0.1.21
./tools/scripts/upgrades/submit_upgrade.sh beta v0.1.21
./tools/scripts/upgrades/submit_upgrade.sh main v0.1.21

Make sure to ONLY move to the next network after the prior one finished successfully.

6. Prepare Snapshots​

Generate new snapshots for each network and ensure they are available here.

MANUAL PROCESS

This is currently a manual process maintained by the team at Grove.

The instructions are currently maintained in an internal Notion document.

7. Update the release notes​

7.1 Update the GitHub Release Notes​

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

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

  2. Insert the table above the auto-generated release notes.

  3. Mark it as latest release.

7.2 Update the Documentation Upgrade List​

Update the Upgrade List Documentation with the new upgrade.

Use the release notes to populate the upgrade list.

8. Update the homebrew-tap Formula​

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

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.0.1.20 to v.0.1.21"
git push

Note: Make sure to update v0.1.20 and v0.1.21 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

9. Communicate the Update​

9.1 Community Discord Server​

Use the template below as a starting point for your release announcement.

In particular, call out:

  • Call to action to the community with the new release
  • Major new features or changes
  • Thank everyone for their support and whoever was involved

Publish the announcement in the following channels:

9.2 Update the GitHub Release​

Use the template below as a start point for your release announcement. In particular, call out:

  • Any other upcoming releases in the near future
  • Provide support if they need help running a node

Once you've updated the GitHub release notes, set it as latest release.

v0.1.22 Example

For a full example see the release notes for v0.1.22.

Example Release Template

Quick Summary

❓ What changed: Minor onchain changes to support Morse to Shannon migration and many client changes to improve RelayMiner performance.

💾 The latest snapshot is available here.

❗️ If you encounter any issues or bugs, please open up a GitHub issue or just ping the team!

🙏 As always, thank you for your support, cooperation and feedback!

🔜 As of writing this release, v0.1.23 is planned for sometime early next week.

Endpoint Reminder - As a reminder, you can use our public endpoint which is always up to date: https://shannon-grove-rpc.mainnet.poktroll.com.

If you use the Cosmos SDK cosmovisor, or the full node script built by Grove, your nodes should have automatically upgraded.

🌿 Open Offer from Grove - As a close partner, we’re also happy to spin up a dedicated endpoint for your exchange specifically. Just let us know if you ever need this in the future!

9.3 Telegram Release Bot​

gh CLI Release Notification

If you have the gh CLI installed, you can simply run:

make telegram_release_notify

You can also test the release notification by running:

make telegram_test_release

After setting it as latest release, use the GitHub workflow to automatically notify the Telegram groups.

Go to this link and click Run workflow.

This will send the details in the GitHub release to all exchanges.

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

10. Troubleshooting & Canceling an Upgrade​