# 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.

{% stepper %}
{% step %}

### 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?
```

{% endstep %}

{% step %}

### 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
```

{% endstep %}

{% step %}

### 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
```

3. Run a test broadcast:

```
make telegram_test_broadcast_msg MSG_FILE=release_prep_announcement.txt
```

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

```
make telegram_broadcast_msg MSG_FILE=release_prep_announcement.txt
```

{% endstep %}
{% endstepper %}

## 4. ON the Day of the Upgrade

{% stepper %}
{% step %}

### 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/>
  {% endstep %}

{% step %}

### 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.

{% hint style="warning" %}
Wait for the upgrade to complete before proceeding to the next step.
{% endhint %}
{% endstep %}

{% step %}

### 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>
  {% endstep %}

{% step %}

### 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".
{% endstep %}

{% step %}

### 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>
  {% endstep %}

{% step %}

### 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
```

{% endstep %}
{% endstepper %}

## 5. Update the `pocketd` binary

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

Run:

```
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 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
```

{% hint style="danger" %}
Emergency Use Only

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

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
```
