feat(staking,state): IIP-59 commissionRate fields + feature flag (PR 1/5)

[envestcc]

Summary

PR 1 of the IIP-59 series (protocol-native voter reward distribution; replaces the centralized Hermes service). This PR adds the schema fields and feature gate; no runtime behavior changes — fields are populated as zero on existing chain data and default behavior matches today exactly.

Series

#	PR	Status
0	iotex-proto: SetCommissionRate + Candidate.commissionRate	iotexproject/iotex-proto#174 (draft, prerequisite)
1	This PR — fields + feature flag	here
2	per-voter weight view (incremental, in-memory)	TODO
3	SetCommissionRate action + handler	TODO
4	distributeVoterReward + PutPollResult snapshot	TODO
5	multi-node stress test + e2e harness	TODO

Changes

Schema:

• stakingpb.Candidate gains commissionRate = 11 + commissionRateLastEpoch = 12; Go staking.Candidate mirrors them. Equal/Clone/toProto/fromProto all updated (the original PoC at feat(iip-59): protocol-native voter reward distribution #4811 missed Equal — flagged in review Batch update 2019-04-27 6PM PDT #2 of that PR).
• state.Candidate gains CommissionRate. The latest user-set value lives on staking.Candidate (mutable); state.Candidate.CommissionRate is the per-epoch frozen snapshot consumed by GrantEpochReward (set by PutPollResult in PR 4).
• iotextypes.Candidate.commissionRate is set/read in candidateToPb / pbToCandidate so the new field travels through poll snapshots and over the wire.

Feature flag:

• FeatureCtx.EnableVoterRewardDistribution, bound to g.IsToBeEnabled(height) per AGENTS.md convention for WIP features. The gate will be swapped for a real hardfork height at release time.

Toolchain:

• stakingpb regenerated with protoc-gen-go v1.26.0 to match the version recorded in the existing staking.pb.go header (minimizes diff noise).

Local dev (transient):

• go.mod replace pointing at ../iotex-proto so the build resolves the new iotextypes fields prior to iotex-proto PR add validation to minicluster integrate test #174 being merged/tagged. Remove the replace before final merge once iotex-proto cuts a release containing the SetCommissionRate + Candidate.commissionRate additions.

Why these fields, not more

The original PoC (#4811) used three rate fields on staking.Candidate: commissionRate + pendingCommissionRate + commissionRateLastEpoch, with explicit pending→active promotion logic. This PR instead uses only two fields on staking.Candidate (latest value + cooldown metadata) and lets the existing poll Cur/Nxt snapshot machinery handle the current-vs-next epoch separation naturally — current epoch's rate lives on the state.Candidate snapshot in CurCandidateKey, the latest user-set value lives on staking.Candidate. No new promotion code paths.

Test plan

• go build ./... passes with the new go.mod replace pointing at the local iotex-proto branch
• go test ./action/protocol/... ./state/... — 935 tests pass
• New TestCandidateCommissionRate in state/candidate_test.go verifies Equal/Clone/Proto roundtrip for state.Candidate.CommissionRate
• New TestCandidateCommissionRate in action/protocol/staking/candidate_test.go verifies Equal/Clone/toProto/fromProto for staking.Candidate.CommissionRate + CommissionRateLastEpoch, including the explicit assertion that Equal reflects both new fields (regression test for the PoC bug)
• Existing TestClone, TestCloneWithDeactivation, and TestCandidate* continue to pass — no regression in the existing schema

Behavior gating

• Pre-flag (today): EnableVoterRewardDistribution = false. Fields exist as zero. No code path reads them. Behavior identical to current master.
• Post-flag: subsequent PRs (Batch update 2019-04-27 6PM PDT #2-Implement IoTeX blockchain explorer API MVP #4) hang behavior off the flag.

🤖 Generated with Claude Code

[envestcc]

why commissionRateLastEpoch is needed, and what it will be used for?

[envestcc]

It is best for feature flags to default to indicating the activation status of a new feature. Since the default value of bool is false, it is advisable to rename the flag to something like NoVoterRewardDistribution and document this rule in the comments, so that AI will avoid making the same mistake in the future.

[envestcc]

Good catch — IIP-59 doesn't actually prescribe a per-rate-change cooldown. Re-reading the spec:

Why Epoch-Boundary Rate Changes: Commission rate changes take effect at the next epoch boundary, not immediately. This prevents a delegate from setting 0% commission to attract voters, switching to 100% right before epoch reward distribution, switching back to 0%. Epoch-boundary enforcement gives voters time to react to rate changes.

The IIP's only protection against rapid manipulation is epoch-boundary activation. In our design, the existing poll Cur/Nxt snapshot machinery already gives us that for free: a SetCommissionRate call at any moment only affects rewards in the epoch after the next PutPollResult snapshot (~1.5 epoch reaction window). No commissionRateLastEpoch needed.

The 168-epoch cooldown in the PoC (#4811 commit fbe52e7) was production hardening the author added beyond the spec, but it's a policy decision that can land later as an additive proto change if the protocol decides it wants stronger limits.

I've dropped the field from both PRs and force-pushed:

• feat(action,state): add SetCommissionRate + commissionRate for IIP-59 iotex-proto#174 — removed CandidateV2.commissionRateLastEpoch = 12
• this PR — removed stakingpb.Candidate.commissionRateLastEpoch = 12, plus the Go struct field, Clone/Equal/proto roundtrip, and test assertion

Stacked PR #4860 (VoterWeightView) is rebased on the updated PR 1 head.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[envestcc]

Good convention — adopted. Looking at the existing flags in context.go (NoCandidateExitQueue, NotSlashUnproductiveDelegates, NotUseMinSelfStakeToBeActive, CandidateBLSPublicKeyNotCopied, etc.), they all follow the rule you're describing: name the field so the bool zero value (false) is the post-fork activated behavior, and let the explicit !g.IsXxx(height) initializer clamp it to true only during the pre-fork window. My Enable* form was inconsistent with that.

Renamed EnableVoterRewardDistribution → NoVoterRewardDistribution, flipped the initializer to !g.IsToBeEnabled(height), flipped the read sites in PR #4860 to if !featureCtx.NoVoterRewardDistribution { ... }, and added a docstring on the field explaining the convention so this is captured for future AI/human readers:

// NoVoterRewardDistribution gates IIP-59: protocol-native voter reward
// distribution. When false (the post-fork / activated state, which is also
// the bool zero value), GrantEpochReward auto-splits each delegate's
// epoch reward between the delegate's commission and a proportional
// distribution to voters, and SetCommissionRate actions are accepted.
// When true (the pre-fork legacy state), the protocol keeps today's
// behavior of granting the full epoch reward to the delegate.
//
// Naming convention: feature flags should be named such that the bool
// zero value (false) corresponds to the post-fork activated behavior.
// This matches NoCandidateExitQueue / NotSlashUnproductiveDelegates and
// makes a missing / partially-initialized FeatureCtx default to the
// long-term mainnet behavior rather than the temporary pre-fork state.
NoVoterRewardDistribution bool

Both branches force-pushed:

• this PR: f52ee5957
• stacked PR feat(staking): IIP-59 VoterWeightView infrastructure (PR 2/5) #4860 rebased: 0cc2d30dc

[envestcc]

Closing as part of IIP-59 PR reorganization. The proposal was amended (iotexproject/iips#73) to cover both block reward + epoch reward and to base voter distribution on a per-epoch snapshot. The new PR split is:

• PR 1 (new): commissionRate schema + SetCommissionRate action (merges the old feat(staking,state): IIP-59 commissionRate fields + feature flag (PR 1/5) #4859 + feat(action,staking): IIP-59 SetCommissionRate action + handler (PR 3/5) #4862)
• PR 2: snapshot layer at PutPollResult (commission rate + voter weight blob)
• PR 3: voter reward distribution (epoch path)
• PR 4: block reward folding (pending pool + orphan drain)
• PR 5: stress test + e2e determinism harness
• PR 6: mainnet fork activation

The incremental voter weight view (old #4860 + #4863) is dropped in favor of a per-PutPollResult full scan; ~40k buckets sorted+encoded once per epoch fits well inside the mint budget and eliminates the 13-handler-hook consensus-safety surface. Old #4864 (voter reward distribution) is replaced by new PR 3 which reads the snapshot instead of the live view.

Superseded by new PRs — will link once opened.