IIP-59: contract-backed rates, native compound, batched log, opt-in migration

[envestcc]

Summary

Four amendments to the IIP-59 draft that override the earlier all-native design (superseding parts of pending PR #73). None affect the goal — protocol-native voter reward distribution replacing the centralized Hermes service — but each closes a UX regression or migration gap in the original spec.

1. Commission-rate source: reuse DelegateProfile contract

• Removed: native SetCommissionRate action + on-chain rate storage.
• Added: read voter-take portions from the existing DelegateProfile contract at PutPollResult via getEncodedProfile(delegate); invert to commission (10000 − portion × 100); snapshot both BlockCommissionRate and EpochCommissionRate separately.
• Contracts: mainnet 0xfa7f50866ac45d84adf54bc767c885f92750e258, testnet 0xd19ffB48a5C18B77c541D32c1B1ac2440c287774.
• Semantic invariant: DelegateProfile stores the analyser-format voter-take portion (analyser/common/rewards/hermes.go:60-67). The bridge MUST invert. A regression here would silently swap voter and delegate shares; guarded by unit test against an oracle Hermes distribution over 100 mainnet delegates.
• Empty profile → legacy path (full amount to delegate's RewardAddress), matching today's Hermes behavior for unconfigured delegates.
• Hard prerequisite: DelegateProfile contract owner is currently a single EOA (0x68c12a8c5d5f0a1fd13319ba4840301b0c93bd4f). Before the fork, ownership MUST move to a multisig / burn / delta-cap + delay scheme. Documented in §5 Step 1 and Security Considerations.

2. Native compound via existing auto-deposit contract

• Reuses the existing compound-registration contract (mainnet io108ckwzlzpkhva7cnfceajlu7wu6ql5kq95uat9, testnet 0xB575DfA55d9Cd04841567Fe8461BFC79D068B9Cf).
• Per-voter routing at epoch drain: if bucketId != 0 && bucket.Owner == voter && AutoStake && status == active → AddDeposit(bucketId, amount); else accrue to unclaimedBalance for pull-claim.
• LSD (contract-staking) holders can't compound (parity with today's Hermes behavior).
• Preserves today's passive-user compound UX. Without this, opt-in delegates would break every compounder in their voter set on flip day.

3. Batched DelegateDistributed log

Replaces per-voter VOTER_REWARD receipt events with a single log per opted-in delegate per epoch:

DelegateDistributed{
  epoch, delegate,
  voters[], amounts[],
  commissionAmount,
  snapshotHash,           // hash of frozen voter weight snapshot
  blockRewardComponent,   // pre-commission block reward pool
  epochRewardComponent,   // pre-commission epoch reward pool
}

• Log volume: 10k-50k/epoch → ~24-100/epoch.
• snapshotHash gives off-chain verifiers a single anchor to check the batched arrays against the frozen voter weight snapshot.
• Auto-splits at MaxLogPayloadBytes (200 KB default) with {seq, seqTotal} for delegates that ever exceed the cap.

4. Per-delegate opt-in transition

• New Candidate.VoterRewardOnchainOptIn: bool.
• New SetVoterRewardOptIn(bool) action (protobuf tag 60, ioctl stake2 optin [--off]).
• Default post-fork: opt-out — legacy Hermes service continues to distribute the full amount from the delegate's RewardAddress.
• Delegates must send an explicit opt-in tx; effect delayed one epoch via the poll snapshot. Bidirectional.
• Hermes off-chain service MUST filter opted-in delegates from distributeRewards at the same snapshot boundary to prevent double-spend. Documented in Security Considerations.

Rollout is now per-delegate rather than a fork-wide flip; delegates who need more time (compound registration, voter comms, sub-tooling) don't block the rest.

What the amendment file changes

• §1 Candidate Registration Extension: adds VoterRewardOnchainOptIn, BlockCommissionRate, EpochCommissionRate to the Candidate struct.
• §2 New Actions: replaces SetCommissionRate with SetVoterRewardOptIn.
• §3 Modified Reward Distribution: splits effectiveTip from base block reward (§3.1), dual-rate epoch split (§3.2), synthetic *state.Candidate for orphan drain (§3.3), 3-item PutPollResult snapshotting (§3.4), NEW §3.5 DelegateProfile contract rate source, NEW §3.6 AutoDeposit compound, NEW §3.7 per-delegate opt-in gate.
• §4 Voter Claim Flow: ASCII diagram extended with AutoDeposit routing.
• §5 Migration Plan: 8-step, with DelegateProfile ownership handover as Step 1.
• §6 ioctl Integration: ioctl stake2 optin [--off].
• §7 Skeleton Implementation: handleSetVoterRewardOptIn with idempotency + pre-fork guard, dual-rate split code, newDelegateDistributedLog emitter, NEW §7.9 SnapshotCommissionRates bridge (evm.SimulateExecution + invertToCommission), NEW §7.10 compoundOrCredit bridge with 4-precondition check + graceful degradation.
• Rationale: adds "Why Reuse DelegateProfile", "Why Native Compound", "Why a Single Batched Log"; extends Performance Impact.
• Backwards Compatibility: rewritten as 9 items covering all new state, RPC surface, Hermes filter requirement, contract compat, iotex-hub, restart safety.
• Test Cases: adds need an XRC-20 contract interface and ABI #12 opt-in delay, Propose IIP-10 #13 compound routing preconditions, Propose IIP-11 #14 empty-profile fallback, update IIP-10/11 #15 batched log format, iip-12: Support staking action via Web3 #16 Hermes double-spend prevention.
• Security Considerations: adds contract-owner governance (hard prerequisite), semantic inversion invariant, opt-in coexistence, compound reentrancy, log payload bound, contract-read determinism.
• Protocol Changes Required: dropped handleSetCommissionRate; added handler_voter_reward_optin.go, delegate_profile_bridge.go, auto_deposit_bridge.go, stake2optin.go, SetVoterRewardOptIn action registration.

Why now, before more code work

The original design (implemented across draft PRs 1–4 in iotex-core) broke Hermes UX in four places (push→pull, compound gap, service fee removal, log volume) and had no per-delegate migration ramp. Amending the IIP first — before rewriting or extending those PRs — is cheaper than shipping code that gets rolled back after review.

Test plan

• Verify amendment renders correctly on GitHub (headings, table, code blocks).
• Confirm all 16 test cases are unambiguously specified against §3 and §7 (no undefined identifiers).
• Confirm §5 Migration Plan Step 1 (DelegateProfile owner governance) is called out as blocking.
• Confirm Security Considerations flag the Hermes off-chain filter requirement as a launch-critical dependency.
• Confirm §7.9 bridge inverts portion → commission (not raw carry-through).

Related: supersedes portions of #73.

🤖 Generated with Claude Code