feat(rewarding): fold block reward into IIP-59 pending pool + drain (IIP-59 PR 4/6)

[envestcc]

Summary

Fourth PR of the IIP-59 protocol-native voter reward distribution series (spec: iotexproject/iips#73). Stacked on #4880 — PR 3 built distributeVoterReward for the epoch stream; this PR folds the block reward into the same split. The block reward accrues to a per-delegate pending pool during the epoch and drains through distributeVoterReward at epoch close, mirroring the epoch-reward math. Priority tip (effectiveTip) still credits the producer directly — it's tx-inclusion incentive, not delegate compensation.

• No behavior change pre-flag. Gated on the same FeatureCtx.NoVoterRewardDistribution predicate as PRs 1–3, with the same fallback triggers as distributeVoterReward. Legacy path — grantToAccount(rewardAddr, totalReward) + BLOCK_REWARD log — still runs when the flag is set, the candidate is missing/unresolvable, or commission rate is zero.
• What's new:
  • Per-delegate pending pool in the rewarding namespace, keyed by candidate identity; and a sorted index for deterministic drain ordering.
  • GrantBlockReward routes eligible producers into the pool; GrantEpochReward drains it via distributeVoterReward after slashing and before the existing epoch-reward loop.
  • BLOCK_REWARD / PRIORITY_BONUS receipt logs unchanged — the routing decision is internal accounting. Per-voter distribution surfaces in the epoch receipt via PR 3's VOTER_REWARD / DELEGATE_COMMISSION logs.

Why a pool?

voter_weight_snapshot is only written at PutPollResult (epoch boundary). Between snapshots the on-chain state has no authoritative per-voter share, so block-time splitting isn't well-defined. Accumulating block rewards per-delegate and settling them at the next snapshot boundary is the cleanest fix: same voters, same weights, same math as the epoch stream.

Storage layout

Two new state entries in state.RewardingNamespace, matching the existing 3-byte prefix convention ("adm" / "fnd" / "acc" / "xpt"):

Key	Value	Purpose
"pbr" || candIdentity.Bytes()	pendingBlockReward { amount, rewardAddr, commissionRate }	per-delegate pool entry
"pbi"	pendingBlockRewardIndex { identities []address.Address }	sorted index of delegates with balance

Fields captured at credit time. rewardAddr and commissionRate are refreshed on every credit so mid-epoch commission-rate changes are captured, and orphan drains (delegate churned out of top-N) still have everything needed to split — no dependency on a stale poll snapshot at drain time.

Sorted index for determinism. Insertion is binary-search insert-if-absent; drain iterates in bytes.Compare order. Avoids a prefix scan on the underlying KV store and pins receipt-log ordering.

Both structs get Serialize/Deserialize via new proto messages in the existing rewardingpb/rewarding.proto; no new .proto file. Regen with protoc-gen-go v1.26.0 from repo root:

protoc --go_out=. --go_opt=paths=source_relative action/protocol/rewarding/rewardingpb/rewarding.proto

GrantBlockReward — route based on eligibility

Prologue (assertNoRewardYet / calculateTotalRewardAndTip / updateAvailableBalance) is untouched — the fund invariant unclaimedBalance ≤ totalBalance and the per-height idempotency sentinel don't change. Only the "credit" step is routed:

if p.blockRewardEligibleForVoterSplit(fCtx, producerCand) {
    if !isZero(effectiveTip) {
        if err := p.grantToAccount(ctx, sm, rewardAddr, effectiveTip); err != nil {
            return nil, err
        }
    }
    if err := p.creditPendingBlockReward(ctx, sm, producerCand, blockReward); err != nil {
        return nil, err
    }
} else {
    // legacy — unchanged
    if err := p.grantToAccount(ctx, sm, rewardAddr, totalReward); err != nil {
        return nil, err
    }
}

Eligibility predicate mirrors PR 3's distributeVoterReward fallback triggers exactly, so "am I eligible" gives the same answer at block time and epoch time:

func (p *Protocol) blockRewardEligibleForVoterSplit(fCtx protocol.FeatureCtx, cand *state.Candidate) bool {
    return !fCtx.NoVoterRewardDistribution &&
        cand != nil &&
        cand.Identity != "" &&
        cand.CommissionRate > 0
}

GrantEpochReward — drain phase

New drainPendingBlockRewards(ctx, sm, candidates, blkHeight, actionHash) ([]*action.Log, error) runs after slashing and before the existing epoch-reward split loop — slashing still operates on the current-epoch active list without pool interference.

For each identity in the pool index (sorted):

1. Read pool entry {amount, rewardAddr, commissionRate}. amount == 0 → delete entry, continue (defensive).
2. If identity is in the current-epoch top-N (map[identity]*state.Candidate built from the poll snapshot) → use the fresh *state.Candidate from the map. Picks up mid-epoch rate/rewardAddr changes captured at credit time and re-frozen by PutPollResult.
3. Else (orphan) → construct a synthetic *state.Candidate from the pool entry's frozen rewardAddr + commissionRate.
4. Call PR 3's distributeVoterReward(ctx, sm, cand, entry.rewardAddr, entry.amount, blkHeight, actionHash):
   • handled=true → append logs to output.
   • handled=false → belt-and-suspenders legacy fallback (grantToAccount + EPOCH_REWARD log). Unreachable under the current predicate (pre-flag never credited the entry) but retained in case the flag ever re-flips mid-epoch.
5. Delete the pool entry.

Finally delete the pool index.

Fund accounting. unclaimedBalance was already debited at block-credit time via the original updateAvailableBalance(totalReward). The drain phase only moves money between subaccounts (pool → voter / delegate) via grantToAccount; no additional fund debit or credit. The existing epoch loop's actualTotalReward accumulator is NOT bumped by drained amounts — those were accounted for at block time. The final updateAvailableBalance(actualTotalReward) stays unchanged.

Idempotency. GrantEpochReward is already guarded by assertNoRewardYet(_epochRewardHistoryKeyPrefix, epochNum). Re-execution is blocked upstream, so the drain phase is naturally one-shot per epoch.

Orphan handling (concrete)

Scenario: delegate D produces N blocks in epoch E, rotates out for E+1.

1. D's identity is in the pool index (was inserted during E).
2. Drain at close of E+1 finds D → not in top-N map → synthesize *state.Candidate from D's frozen pool-entry fields.
3. distributeVoterReward calls staking.VoterWeightsFromSnapshot(sm, identity):
   • If D was in E's PutPollResult top-N (i.e. snapshot exists) → normal voter split with D's last-known voter set.
   • If not (D never made it into a snapshot) → PR 3's (nil, nil) branch: full amount to D as a single DELEGATE_COMMISSION log.
4. Pool entry deleted.

Voters are never stranded — accrued block rewards flow to whoever the last snapshot deemed them owed to, or fall back to the delegate.

Determinism guardrails

• Pool index sorted by identityAddr.Bytes(); drain iterates in that order.
• distributeVoterReward (PR 3) iterates its voter list in sorted order.
• All map accesses in the drain phase are lookups only; no for k := range m iteration reaches receipt-log or state-write order.
• sort.Slice with bytes.Compare(a.Bytes(), b.Bytes()) — same comparator as PR 2's snapshot helper.

Tests

pending_block_reward_test.go — 14 functions / 19 subcases:

• Struct roundtrip for both pendingBlockReward and pendingBlockRewardIndex (zero, small, large amount; nil rewardAddr; malformed amount rejected on decode).
• Index insert semantics (sort order preserved, dedup on repeat).
• creditPendingBlockReward create + accumulate; second credit refreshes commissionRate (mid-epoch rate change captured); multi-delegate case verifies index stays sorted; zero-amount is a no-op.
• Eligibility predicate matrix (all fallback triggers × the pass-through case).
• Drain:
  • Empty pool → no-op.
  • Top-N with snapshot: fresh 20% commission rate preferred over entry's frozen 10%; math asserted to the wei — commission=200_000, voterPool=800_000, per-voter 266_666, dust=2, delegate = 200_002; 4 logs in canonical order.
  • Orphan with snapshot: delegate not in current-epoch top-N but snapshot exists → normal split using frozen 10% rate from entry.
  • Orphan without snapshot: no snapshot → full amount to delegate as DELEGATE_COMMISSION.
  • Legacy fallback branch: fresh candidate has CommissionRate=0 → drain routes to belt-and-suspenders grantToAccount + EPOCH_REWARD path.
• Index and pool entries verified deleted after each drain scenario.

Test plan

• go build ./...
• go vet ./action/protocol/rewarding/...
• go test ./action/protocol/rewarding/... -count=1 — 55/55 green (existing 36 + new 19 subcases).
• Verified pre-existing blockchain/blockdao failures (Test_blockDAO_Start, TestBlockIndexerChecker_CheckIndexer/.../FailedToGetAddress) reproduce on PR 3 baseline and on master. Unrelated to this PR.
• Cross-flag matrix at real block heights — deferred to PR 5's e2e determinism harness.
• Multi-epoch fund conservation under mixed producers — deferred to PR 5.

Series roadmap

• PR 1: feat(action,staking,state): commissionRate schema + SetCommissionRate (IIP-59 PR 1/6) #4865 — commissionRate schema + SetCommissionRate action
• PR 2: feat(staking,poll): incremental voter weight view + snapshot at PutPollResult (IIP-59 PR 2/6) #4866 — incremental voter weight view + snapshot @ PutPollResult
• PR 3: feat(rewarding,staking): distribute epoch voter reward at GrantEpochReward (IIP-59 PR 3/6) #4880 — voter reward distribution (epoch path)
• PR 4 (this PR): block reward folding
• PR 5: stress test + e2e determinism harness
• PR 6: mainnet fork activation (flip NoVoterRewardDistribution gate)

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
9 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[envestcc]

Closing in favor of a redesigned stack based on the IIP-59 amendment: iotexproject/iips#74.

Four design pivots supersede this PR:

1. Commission rate source — Read from the existing DelegateProfile contract at PutPollResult (via getEncodedProfile), not stored via a native SetCommissionRate action. Split into BlockCommissionRate + EpochCommissionRate; portion → commission inversion at the bridge.
2. Voter compound — Reuse the existing AutoDeposit contract to route each voter's share to AddDeposit when the voter has a registered active bucket; else credit unclaimedBalance. Preserves today's passive-user compound UX.
3. Batched receipt log — Single DelegateDistributed{epoch, delegate, voters[], amounts[], snapshotHash, ...} per opted-in delegate per epoch, replacing per-voter VOTER_REWARD logs (~24-100 logs/epoch vs 10k-50k).
4. Per-delegate opt-in — New Candidate.VoterRewardOnchainOptIn + SetVoterRewardOptIn action. Default is opt-out (legacy Hermes continues). Effect delayed 1 epoch via PutPollResult snapshot. Bidirectional. Hermes off-chain service filters opted-in delegates to prevent double-spend.

Rationale: original design broke Hermes UX in four places (push→pull, compound gap, service fee removal, log volume) and had no per-delegate migration ramp. Contract-backed rate + native compound restore feature parity; opt-in makes rollout per-delegate rather than a fork-wide flip.

New draft stack will be opened as Draft PRs until iotexproject/iips#74 lands. Branch preserved locally for reference.