IIP-59: v3 rewrite matching shipped era-based implementation

[envestcc]

Summary

Rewrite the IIP-59 specification to match the era-based drain design that actually shipped in iotex-core#4953. The v2 amendment (merged as #75) sketched the direction; this v3 revision captures the final protocol surface exposed to delegates, voters, and off-chain verifiers.

What changed vs. v2

• Reward era replaces per-epoch payout. Voter distribution runs over a run of EpochsPerRewardEra (default 24) epochs. Era boundary = Phase A (freeze work list into a persistent cursor + immediate commission); every non-boundary block = Phase B (GrantVoterRewardChunk system action drains the cursor).
• Two per-block caps parameterize Phase B: VoterBudgetPerBlock (default 2000 payouts/block) and CompoundBatchSize (default 500 compounds/block). Both live in genesis config.
• SetVoterRewardOptIn action envelope — the sole delegate-facing mutation for the VoterRewardOnchainOptIn flag. Two-field payload: bytes candidate_identifier, bool opt_in. Commission rates continue to come from DelegateProfile, so no rate fields on this action.
• New receipt log types: EPOCH_DRAIN_OVERRUN (per-item graceful degrade if a stale cursor is present at Phase A entry — residue rolls into the next era) and CURSOR_PROGRESS (per-chunk observability for off-chain cursor pile-up monitoring).
• Commission rates read from DelegateProfile at each era boundary and frozen into the poll snapshot for the entire drain. No new on-chain rate storage.
• Feature gate stays a single flag (NoVoterRewardDistribution); no sub-flag decomposition.

Why v3, not another amendment to iip-59-era-distribution

The v2 amendment is already merged onto master (PR #75). This is a full rewrite of the spec text — headers reorganized, edge cases documented, receipt-log catalog added — not an incremental delta. A fresh PR onto master is clearer than layering another amendment on top of a merged one.

Alignment with shipped code

Cross-checked against the shipped commits on iotex-core#4953:

• Chunk size / era length / budget defaults match blockchain/genesis/genesis.go.
• Phase A / Phase B split matches action/protocol/rewarding/reward.go and voter_reward_chunk.go.
• SetVoterRewardOptIn handler + validation live in action/protocol/staking/handler_set_voter_reward_opt_in.go and validations.go.
• Feature gate matches protocol.FeatureCtx.NoVoterRewardDistribution.

Test plan

• Editorial review: read for clarity, terminology consistency, missing edge cases.
• Cross-check every parameter default cited in the spec against blockchain/genesis/genesis.go.
• Cross-check every receipt log type cited in the spec against action/protocol/rewarding/rewardingpb/rewarding.proto.
• Confirm the Supersedes: header captures the correct prior-revision lineage.

🤖 Generated with Claude Code