release: v2.5.0 - Zanzibar on MainNet at 53155801

CLAUDE.md

@@ -13,7 +13,7 @@ This is the **IoTeX Delegate Manual** repository - configuration and operational
 
 ## Version Alignment
 
-This repository is versioned in sync with [iotex-core](https://github.com/iotexproject/iotex-core). The current release is **v2.4.5**. When iotex-core releases a new version:
+This repository is versioned in sync with [iotex-core](https://github.com/iotexproject/iotex-core). The current release is **v2.5.0-rc2 on TestNet** and **v2.5.0 on MainNet** — Zanzibar is now scheduled on both: TestNet activated it at 46880641, Beta at 47141281, and Gamma at 47468161; MainNet takes all three together at 53155801. MainNet carries its fork heights in the binary rather than in `genesis_mainnet.yaml`, so a MainNet upgrade is a binary roll with no genesis change. When iotex-core releases a new version:
 1. Update version references in README.md, config files, and scripts
 2. Add a release note in `changelog/`
 3. Create a PR but do NOT merge until the final release is tagged in iotex-core
@@ -38,7 +38,7 @@ See `release_flow.md` for the complete release process.
 ## Common Tasks
 
 ### Update for a new iotex-core release
-1. Update `version` references in README.md (search for `v2.4.5`)
+1. Update `version` references in README.md (search for `v2.5.0-rc2`)
 2. Update docker image tags in `scripts/all_in_one_mainnet.sh` and `scripts/all_in_one_testnet.sh`
 3. Add release note in `changelog/vX.Y.Z-release-note.md`
 4. Update `config_mainnet.yaml` and `config_testnet.yaml` if needed
@@ -56,7 +56,7 @@ bash <(curl -s https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/ma
 ### Non-interactive upgrade (AI agent / CI)
 ```bash
 bash setup_fullnode.sh --auto --home=/path/to/iotex-var
-bash setup_fullnode.sh --auto --home=/path/to/iotex-var --version=v2.4.5
+bash setup_fullnode.sh --auto --home=/path/to/iotex-var --version=v2.5.0-rc2
 bash setup_fullnode.sh --auto --home=/path/to/iotex-var --force  # reinstall same version
 ```
 Flags: `--auto` (skip prompts), `--home=` (IOTEX_HOME), `--version=` (target version), `--force` (bypass same-version check), `--monitor` (enable monitoring), `plugin=gateway` (enable gateway).

README.md

@@ -16,11 +16,34 @@
 - [Agent Guide](AGENT.md)
 - [Q&A](#qa)
 
+> ### ⚠️ Zanzibar hardfork — MainNet block 53155801 (estimated 2026-10-08 02:00 UTC / 10:00 CST)
+>
+> Upgrade to `v2.5.0` before that block. A node left on `v2.4.4` will fork off
+> the network.
+>
+> **`genesis_mainnet.yaml` does not change.** MainNet carries its fork heights
+> in the binary, not in the genesis file, so there is nothing to re-download —
+> unlike the TestNet rollout, where the genesis had to be replaced. Pull the
+> image, restart, done. `config_mainnet.yaml` is unchanged as well.
+>
+> Zanzibar activates IIP-59 on-chain voter reward distribution. Beta and Gamma
+> ride the same block: MainNet has activated none of them, so it takes all
+> three corrections from the first block IIP-59 is live rather than scheduling
+> a window that knowingly runs behaviour already found to be wrong.
+>
+> **Delegates distributing through Hermes:** at that block the protocol
+> auto-migrates every candidate whose reward address is a Hermes vault, but
+> only if its DelegateProfile carries both reward-portion fields. A candidate
+> missing either one is left on the Hermes path — nothing breaks, but it does
+> not get on-chain distribution, and the migration runs in that one block and
+> never again. Check yours before the fork. See the
+> [v2.5.0 release note](changelog/v2.5.0-release-note.md).
+
 ## <a name="status"/>Release Status
 
 Here are the software versions we use:
 
-- MainNet: v2.4.5
+- MainNet: v2.5.0
 
 ## <a name="testnet"/>Join TestNet
 To start and run a testnet node, please click [**Join Testnet**](https://github.com/iotexproject/iotex-bootstrap/blob/master/README_testnet.md)
@@ -33,7 +56,7 @@ This is the recommended way to start an IoTeX node
 1. Pull the docker image:
 
 ```
-docker pull iotex/iotex-core:v2.4.5
+docker pull iotex/iotex-core:v2.5.0
 ```
 
 2. Set the environment with the following commands:
@@ -48,9 +71,9 @@ mkdir -p $IOTEX_HOME/data
 mkdir -p $IOTEX_HOME/log
 mkdir -p $IOTEX_HOME/etc
 
-curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.4.5/config_mainnet.yaml > $IOTEX_HOME/etc/config.yaml
-curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.4.5/genesis_mainnet.yaml > $IOTEX_HOME/etc/genesis.yaml
-curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.4.5/trie.db.patch > $IOTEX_HOME/data/trie.db.patch
+curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.5.0/config_mainnet.yaml > $IOTEX_HOME/etc/config.yaml
+curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.5.0/genesis_mainnet.yaml > $IOTEX_HOME/etc/genesis.yaml
+curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.5.0/trie.db.patch > $IOTEX_HOME/data/trie.db.patch
 ```
 
 3. Edit `$IOTEX_HOME/etc/config.yaml`, look for `externalHost` and `producerPrivKey`, uncomment the lines and fill in your external IP and private key. If you leave `producerPrivKey` empty, your node will be assgined with a random key.
@@ -105,7 +128,7 @@ docker run -d --restart on-failure --name iotex \
         -v=$IOTEX_HOME/log:/var/log:rw \
         -v=$IOTEX_HOME/etc/config.yaml:/etc/iotex/config_override.yaml:ro \
         -v=$IOTEX_HOME/etc/genesis.yaml:/etc/iotex/genesis.yaml:ro \
-        iotex/iotex-core:v2.4.5 \
+        iotex/iotex-core:v2.5.0 \
         iotex-server \
         -config-path=/etc/iotex/config_override.yaml \
         -genesis-path=/etc/iotex/genesis.yaml
@@ -126,7 +149,7 @@ docker run -d --restart on-failure --name iotex \
         -v=$IOTEX_HOME/log:/var/log:rw \
         -v=$IOTEX_HOME/etc/config.yaml:/etc/iotex/config_override.yaml:ro \
         -v=$IOTEX_HOME/etc/genesis.yaml:/etc/iotex/genesis.yaml:ro \
-        iotex/iotex-core:v2.4.5 \
+        iotex/iotex-core:v2.5.0 \
         iotex-server \
         -config-path=/etc/iotex/config_override.yaml \
         -genesis-path=/etc/iotex/genesis.yaml \
@@ -150,7 +173,7 @@ Same as [Join MainNet](#mainnet) step 2
 ```
 git clone https://github.com/iotexproject/iotex-core.git
 cd iotex-core
-git checkout v2.4.5
+git checkout v2.5.0
 
 // optional
 export GOPROXY=https://goproxy.io
@@ -312,7 +335,7 @@ The upgrade script supports a non-interactive mode for use with AI agents, CI/CD
 |---|---|
 | `--auto` | Non-interactive mode, skip all prompts |
 | `--home=/path` | Set `$IOTEX_HOME` directory |
-| `--version=v2.4.5` | Target version (default: latest release) |
+| `--version=v2.5.0` | Target version (default: latest release) |
 | `--force` | Reinstall even if already running the same version |
 | `--snapshot` | Download blockchain snapshot (recommended for fresh install) |
 | `--monitor` | Enable monitoring |
@@ -326,7 +349,7 @@ bash setup_fullnode.sh --auto --home=/path/to/iotex-var --snapshot
 bash setup_fullnode.sh --auto --home=/path/to/iotex-var
 
 # Upgrade to a specific version
-bash setup_fullnode.sh --auto --home=/path/to/iotex-var --version=v2.4.5
+bash setup_fullnode.sh --auto --home=/path/to/iotex-var --version=v2.5.0
 ```
 
 **Notes:**
@@ -339,12 +362,12 @@ Node with gateway plugin enabled will perform extra indexing to serve API reques
 
 ### Transaction-log patch (gateway / API / archive nodes)
 
-Nodes that **serve transaction-log queries** (`GetTransactionLogByActionHash`, `GetTransactionLogByBlockHeight`) should apply the transaction-log patch shipped with v2.4.4, which corrects a set of historical in-contract-transfer records. Delegate / fullnodes that do not serve these queries do not need it.
+Nodes that **serve transaction-log queries** (`GetTransactionLogByActionHash`, `GetTransactionLogByBlockHeight`) should apply the transaction-log patch shipped with v2.5.0, which corrects a set of historical in-contract-transfer records. Delegate / fullnodes that do not serve these queries do not need it.
 
 1. Download the patch file into the node's data directory and verify its checksum:
 
 ```
-curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.4.5/txlog.db.patch > $IOTEX_HOME/data/txlog.db.patch
+curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.5.0/txlog.db.patch > $IOTEX_HOME/data/txlog.db.patch
 echo "dee9406afc991d5439ab4c27bc85fa658e1fb241ddabe1cc5fef18f27d728986  $IOTEX_HOME/data/txlog.db.patch" | sha256sum -c
 ```
 
@@ -357,7 +380,7 @@ chain:
 
 3. Restart the node.
 
-> **Important:** only set `patchTransactionLogPath` if the patch file exists at that path — a node configured with a missing patch file will **fail to start**. The patch is read-only and does not change balances, receipts, or block hashes. See the [v2.4.4 release note](changelog/v2.4.4-release-note.md) for details.
+> **Important:** only set `patchTransactionLogPath` if the patch file exists at that path — a node configured with a missing patch file will **fail to start**. The patch is read-only and does not change balances, receipts, or block hashes. See the [v2.5.0 release note](changelog/v2.5.0-release-note.md) for details.
 
 ## <a name="qa"/>Q&A
 Please refer [here](https://github.com/iotexproject/iotex-bootstrap/wiki/Q&A) for Q&A.

README_CN.md

@@ -14,11 +14,29 @@
 - [网关插件](#gateway)
 - [常见问题](#qa)
 
+> ### ⚠️ Zanzibar 硬分叉 — 主网 53155801 块（预计 2026-10-08 02:00 UTC / 10:00 CST）
+>
+> 必须在该高度之前升级到 `v2.5.0`。停留在 `v2.4.4` 的节点会从网络分叉出去。
+>
+> **`genesis_mainnet.yaml` 不变。** 主网的分叉高度写在二进制里、不在 genesis 文件中，
+> 所以没有需要重新下载的东西——这与测试网那次不同（测试网必须替换 genesis）。
+> 拉镜像、重启，就完成了。`config_mainnet.yaml` 同样不变。
+>
+> Zanzibar 启用 IIP-59 链上投票人奖励发放。Beta 和 Gamma 与它同一个高度：主网三者
+> 都未激活过，所以从 IIP-59 生效的第一个块起就带上全部修正，而不是安排一段明知
+> 行为有误的窗口。
+>
+> **通过 Hermes 分发的 delegate 请注意：** 该高度上协议会自动迁移所有 reward
+> address 指向 Hermes vault 的候选人，但**前提是其 DelegateProfile 已配置两个
+> 分成字段**。缺任一字段的候选人会被留在 Hermes 老路径——不会出错，但拿不到链上
+> 分发，而且这个迁移只在那一个块执行、之后不再重来。请在分叉前检查。
+> 详见 [v2.5.0 release note](changelog/v2.5.0-release-note.md)。
+
 ## <a name="status"/>发布状态
 
 以下是当前我们使用的软件版本：
 
-- 主网：v2.4.5
+- 主网：v2.5.0
 
 ## <a name="testnet"/>加入测试网
 如果你要启动节点加入测试网，请点击[**加入测试网**](https://github.com/iotexproject/iotex-bootstrap/blob/master/README_CN_testnet.md)
@@ -32,7 +50,7 @@
 1. 提取(pull) docker镜像
 
 ```
-docker pull iotex/iotex-core:v2.4.5
+docker pull iotex/iotex-core:v2.5.0
 ```
 
 2. 使用以下命令设置运行环境
@@ -47,9 +65,9 @@ mkdir -p $IOTEX_HOME/data
 mkdir -p $IOTEX_HOME/log
 mkdir -p $IOTEX_HOME/etc
 
-curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.4.5/config_mainnet.yaml > $IOTEX_HOME/etc/config.yaml
-curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.4.5/genesis_mainnet.yaml > $IOTEX_HOME/etc/genesis.yaml
-curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.4.5/trie.db.patch > $IOTEX_HOME/data/trie.db.patch
+curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.5.0/config_mainnet.yaml > $IOTEX_HOME/etc/config.yaml
+curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.5.0/genesis_mainnet.yaml > $IOTEX_HOME/etc/genesis.yaml
+curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.5.0/trie.db.patch > $IOTEX_HOME/data/trie.db.patch
 ```
 
 3. 编辑 `$IOTEX_HOME/etc/config.yaml`, 查找 `externalHost` 和 `producerPrivKey`, 取消注释行并填写您的外部 IP 和私钥。如果`producerPrivKey`放空，你的节点将被分配一个随机密钥。
@@ -103,7 +121,7 @@ docker run -d --restart on-failure --name iotex \
         -v=$IOTEX_HOME/log:/var/log:rw \
         -v=$IOTEX_HOME/etc/config.yaml:/etc/iotex/config_override.yaml:ro \
         -v=$IOTEX_HOME/etc/genesis.yaml:/etc/iotex/genesis.yaml:ro \
-        iotex/iotex-core:v2.4.5 \
+        iotex/iotex-core:v2.5.0 \
         iotex-server \
         -config-path=/etc/iotex/config_override.yaml \
         -genesis-path=/etc/iotex/genesis.yaml
@@ -121,7 +139,7 @@ docker run -d --restart on-failure --name iotex \
         -v=$IOTEX_HOME/log:/var/log:rw \
         -v=$IOTEX_HOME/etc/config.yaml:/etc/iotex/config_override.yaml:ro \
         -v=$IOTEX_HOME/etc/genesis.yaml:/etc/iotex/genesis.yaml:ro \
-        iotex/iotex-core:v2.4.5 \
+        iotex/iotex-core:v2.5.0 \
         iotex-server \
         -config-path=/etc/iotex/config_override.yaml \
         -genesis-path=/etc/iotex/genesis.yaml \
@@ -141,7 +159,7 @@ docker run -d --restart on-failure --name iotex \
 ```
 git clone https://github.com/iotexproject/iotex-core.git
 cd iotex-core
-git checkout v2.4.5
+git checkout v2.5.0
 
 // optional
 export GOPROXY=https://goproxy.io
@@ -281,12 +299,12 @@ bash <(curl -s https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/ma
 
 ### 交易日志补丁（网关 / API / 归档节点）
 
-**对外提供交易日志查询**（`GetTransactionLogByActionHash`、`GetTransactionLogByBlockHeight`）的节点应安装 v2.4.4 引入的交易日志补丁，它会修正一组历史合约内转账记录。不对外提供这些查询的 delegate / 全节点无需安装。
+**对外提供交易日志查询**（`GetTransactionLogByActionHash`、`GetTransactionLogByBlockHeight`）的节点应安装 v2.5.0 引入的交易日志补丁，它会修正一组历史合约内转账记录。不对外提供这些查询的 delegate / 全节点无需安装。
 
 1. 将补丁文件下载到节点的 data 目录，并校验其 checksum：
 
 ```
-curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.4.5/txlog.db.patch > $IOTEX_HOME/data/txlog.db.patch
+curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.5.0/txlog.db.patch > $IOTEX_HOME/data/txlog.db.patch
 echo "dee9406afc991d5439ab4c27bc85fa658e1fb241ddabe1cc5fef18f27d728986  $IOTEX_HOME/data/txlog.db.patch" | sha256sum -c
 ```
 
@@ -299,7 +317,7 @@ chain:
 
 3. 重启节点。
 
-> **重要：** 仅当补丁文件确实存在于该路径时才设置 `patchTransactionLogPath` —— 若配置了该路径但文件缺失，节点将**无法启动**。该补丁为只读，不会改变余额、收据或区块哈希。详见 [v2.4.4 release note](changelog/v2.4.4-release-note.md)。
+> **重要：** 仅当补丁文件确实存在于该路径时才设置 `patchTransactionLogPath` —— 若配置了该路径但文件缺失，节点将**无法启动**。该补丁为只读，不会改变余额、收据或区块哈希。详见 [v2.5.0 release note](changelog/v2.5.0-release-note.md)。
 
 ## <a name="qa"/>常见问题
 

README_CN_testnet.md

@@ -2,6 +2,23 @@
 
 *最新版本请参考 https://github.com/iotexproject/iotex-bootstrap/blob/master/README.md*
 
+
+> ### ⚠️ Zanzibar Gamma 硬分叉 — 测试网 47468161 块（已于 2026-09-07 10:00 UTC / 18:00 CST 激活）
+>
+> 测试网节点必须运行 `v2.5.0-rc2` 并使用当前的 `genesis_testnet.yaml`。
+> 停留在旧二进制或旧 genesis 的节点会继续执行 Gamma 之前的规则。
+>
+> **先升级二进制，再换 genesis。** `v2.5.0-rc1` 无法识别当前 genesis 中的
+> `zanzibarGammaHeight`，会直接启动失败。请先拉取 `v2.5.0-rc2` 并重启，
+> 然后再替换 genesis。`config_testnet.yaml` 本次没有变化，可以沿用。
+>
+> Zanzibar 已在 46880641 块激活，Beta 已在 47141281 块激活。Gamma 包含另外四项
+> 修正；由于测试网已经按较早规则确认了区块，因此需要单独的激活高度。
+>
+> 希望启用 IIP-59 链上投票人奖励发放的 delegate，需要用
+> `ioctl stake2 voterrewardoptin` 开启，并在 DelegateProfile 合约中设置分成比例。
+> 详见 [v2.5.0 release note](changelog/v2.5.0-release-note.md)。
+
 ## 索引
 
 - [发布状态](#status)
@@ -17,7 +34,7 @@
 
 以下是当前我们使用的软件版本：
 
-- 测试网：v2.4.5
+- 测试网：v2.5.0-rc2
 
 **Note**
 如果你要启动节点加入主网，请点击[**加入主网**](https://github.com/iotexproject/iotex-bootstrap/blob/master/README_CN.md)
@@ -31,7 +48,7 @@
 1. 提取(pull) docker镜像
 
 ```
-docker pull iotex/iotex-core:v2.4.5
+docker pull iotex/iotex-core:v2.5.0-rc2
 ```
 
 2. 使用以下命令设置运行环境
@@ -46,8 +63,8 @@ mkdir -p $IOTEX_HOME/data
 mkdir -p $IOTEX_HOME/log
 mkdir -p $IOTEX_HOME/etc
 
-curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.4.5/config_testnet.yaml > $IOTEX_HOME/etc/config.yaml
-curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.4.5/genesis_testnet.yaml > $IOTEX_HOME/etc/genesis.yaml
+curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.5.0-rc2/config_testnet.yaml > $IOTEX_HOME/etc/config.yaml
+curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.5.0-rc2/genesis_testnet.yaml > $IOTEX_HOME/etc/genesis.yaml
 ```
 
 3. 编辑 `$IOTEX_HOME/etc/config.yaml`, 查找 `externalHost` 和 `producerPrivKey`, 取消注释行并填写您的外部 IP 和私钥。如果`producerPrivKey`放空，你的节点将被分配一个随机密钥。
@@ -100,7 +117,7 @@ docker run -d --restart on-failure --name iotex \
         -v=$IOTEX_HOME/log:/var/log:rw \
         -v=$IOTEX_HOME/etc/config.yaml:/etc/iotex/config_override.yaml:ro \
         -v=$IOTEX_HOME/etc/genesis.yaml:/etc/iotex/genesis.yaml:ro \
-        iotex/iotex-core:v2.4.5 \
+        iotex/iotex-core:v2.5.0-rc2 \
         iotex-server \
         -config-path=/etc/iotex/config_override.yaml \
         -genesis-path=/etc/iotex/genesis.yaml
@@ -118,7 +135,7 @@ docker run -d --restart on-failure --name iotex \
         -v=$IOTEX_HOME/log:/var/log:rw \
         -v=$IOTEX_HOME/etc/config.yaml:/etc/iotex/config_override.yaml:ro \
         -v=$IOTEX_HOME/etc/genesis.yaml:/etc/iotex/genesis.yaml:ro \
-        iotex/iotex-core:v2.4.5 \
+        iotex/iotex-core:v2.5.0-rc2 \
         iotex-server \
         -config-path=/etc/iotex/config_override.yaml \
         -genesis-path=/etc/iotex/genesis.yaml \
@@ -138,7 +155,7 @@ docker run -d --restart on-failure --name iotex \
 ```
 git clone https://github.com/iotexproject/iotex-core.git
 cd iotex-core
-git checkout v2.4.5
+git checkout v2.5.0-rc2
 
 // optional
 export GOPROXY=https://goproxy.io