feat(action,staking,state): commissionRate schema + SetCommissionRate (IIP-59 PR 1/6)

First PR of the IIP-59 protocol-native voter reward distribution
series (spec: iotexproject/iips#73).

Introduces the on-chain delegate opt-in surface — a commissionRate
field on the candidate schema plus the SetCommissionRate action
delegates use to change it. No reward-distribution logic yet: that
lands in PR 3, gated on the same feature flag as this PR. Chain
behavior is unchanged pre-flag.

Schema
------

- stakingpb.Candidate gains commissionRate=11; Go Candidate struct
  mirrors it. Equal / Clone / toProto / fromProto updated (the PoC
  at iotexproject#4811 missed Equal — flagged in review #2 there).
- state.Candidate gains CommissionRate. Populated per epoch from
  staking.Candidate by PutPollResult in PR 2; the latest user-set
  value lives on staking.Candidate, and state.Candidate holds the
  frozen per-epoch value consumed by GrantEpochReward in PR 3.
- iotextypes.Candidate.commissionRate is set/read in candidateToPb /
  pbToCandidate so the field travels through poll snapshots and RPC.

Feature flag
------------

- FeatureCtx.NoVoterRewardDistribution, bound to
  !g.IsToBeEnabled(height) per AGENTS.md convention for WIP features
  (the gate will be swapped for a real hardfork height at release).
- Named so the bool zero value (false) corresponds to the post-fork
  activated behavior, matching NoCandidateExitQueue /
  NotSlashUnproductiveDelegates.

Action (SetCommissionRate)
--------------------------

- action/set_commission_rate.go: SetCommissionRate{rate uint64} with
  IntrinsicGas (10000) and SanityCheck (rate in [0, 10000]).
- Full Proto / LoadProto / FillAction wiring for the iotex-proto
  oneof slot (setCommissionRate = 56) shipped in iotex-proto v0.6.7
  (iotexproject/iotex-proto#174).
- EthCompatibleAction + NewSetCommissionRateFromABIBinary so
  MetaMask / hardhat can submit via the same path as
  candidateActivate / candidateDeactivate.
- PackCommissionRateSetEvent helper producing keccak-anchored topic-0
  + indexed candidate address for the receipt log indexers subscribe
  to.
- action/native_staking_contract_interface.sol +
  native_staking_contract_abi.json: declare
  \`function setCommissionRate(uint64 rate)\` and
  \`event CommissionRateSet(address indexed candidate, uint64 newRate)\`
  so external tooling has an ABI to bind against.

Handler (staking)
-----------------

- action/protocol/staking/handler_set_commission_rate.go: resolves
  the caller to a registered candidate by owner, writes
  candidate.CommissionRate, emits CommissionRateSet on the receipt.
  No cooldown enforcement — voters already get a ~1.5 epoch reaction
  window from the PutPollResult snapshot (§3.4 of the IIP), so a
  separate per-rate-change gate is not required.
- validations.go: rejects SetCommissionRate at Validate when the
  feature flag is off, so pre-flag the action never leaves mempool.
- protocol.go: registers the action in the handler switch.

Tests
-----

- candidate_test.go / state/candidate_test.go: proto roundtrip +
  Equal / Clone coverage for the new field.
- set_commission_rate_test.go: SanityCheck bounds, IntrinsicGas, ABI
  encode/decode roundtrip.
- handler_set_commission_rate_test.go: owner check, rate cap,
  successful write path, pre-flag Validate rejection, receipt event
  encoding.

go.mod
------

- Bumps github.com/iotexproject/iotex-proto to v0.6.7 for the new
  SetCommissionRate action + Candidate.commissionRate fields.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: envestcc

action/envelope.go

@@ -453,6 +453,12 @@ func (elp *envelope) loadProtoActionPayload(pbAct *iotextypes.ActionCore) error
 			return err
 		}
 		elp.payload = act
+	case pbAct.GetSetCommissionRate() != nil:
+		act := &SetCommissionRate{}
+		if err := act.LoadProto(pbAct.GetSetCommissionRate()); err != nil {
+			return err
+		}
+		elp.payload = act
 	default:
 		return errors.Errorf("no applicable action to handle proto type %T", pbAct.Action)
 	}

action/native_staking_contract_abi.json

@@ -31,6 +31,25 @@
     "name": "CandidateDeactivated",
     "type": "event"
   },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "candidate",
+        "type": "address"
+      },
+      {
+        "indexed": false,
+        "internalType": "uint64",
+        "name": "newRate",
+        "type": "uint64"
+      }
+    ],
+    "name": "CommissionRateSet",
+    "type": "event"
+  },
   {
     "anonymous": false,
     "inputs": [
@@ -212,6 +231,19 @@
     "stateMutability": "nonpayable",
     "type": "function"
   },
+  {
+    "inputs": [
+      {
+        "internalType": "uint64",
+        "name": "rate",
+        "type": "uint64"
+      }
+    ],
+    "name": "setCommissionRate",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
   {
     "inputs": [
       {

action/native_staking_contract_interface.sol

@@ -41,6 +41,13 @@ interface INativeStakingContract {
         address rewardAddress,
         bytes blsPubKey
     );
+    // IIP-59: emitted when a delegate updates its voter reward commission
+    // rate via setCommissionRate. The new rate takes effect at the next
+    // epoch boundary (poll PutPollResult snapshot).
+    event CommissionRateSet(
+        address indexed candidate,
+        uint64 newRate
+    );
 
     function candidateRegister(
         string memory name,
@@ -82,6 +89,11 @@ interface INativeStakingContract {
 
     function revokeEndorsement(uint64 bucketIndex) external;
 
+    // IIP-59: set the voter reward commission rate (basis points, 0-10000).
+    // Only the candidate owner can call. Takes effect at the next epoch
+    // boundary via the existing poll snapshot machinery.
+    function setCommissionRate(uint64 rate) external;
+
     // Candidate Transfer Ownership
     function candidateTransferOwnership(
         address newOwner,

action/protocol/context.go

@@ -172,6 +172,20 @@ type (
 		// contracts are committed and written back
 		AlwaysWriteCachedContract bool
 		NoCandidateExitQueue      bool
+		// 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
 	}
 
 	// FeatureWithHeightCtx provides feature check functions.
@@ -346,6 +360,7 @@ func WithFeatureCtx(ctx context.Context) context.Context {
 			PrePectraEVM:                            !g.IsYap(height),
 			AlwaysWriteCachedContract:               !g.IsYap(height),
 			NoCandidateExitQueue:                    !g.IsYap(height),
+			NoVoterRewardDistribution:               !g.IsToBeEnabled(height),
 		},
 	)
 }

action/protocol/staking/candidate.go

@@ -35,6 +35,10 @@ type (
 		Votes              *big.Int
 		SelfStakeBucketIdx uint64
 		SelfStake          *big.Int
+		// CommissionRate is IIP-59's voter reward commission rate in basis points
+		// (0-10000). 0 means legacy behavior (the full epoch reward goes to the
+		// delegate's reward account; no auto-distribution to voters).
+		CommissionRate uint64
 	}
 
 	// CandidateList is a list of candidates which is sortable
@@ -65,6 +69,7 @@ func (d *Candidate) Clone() *Candidate {
 		SelfStakeBucketIdx: d.SelfStakeBucketIdx,
 		SelfStake:          new(big.Int).Set(d.SelfStake),
 		BLSPubKey:          blsPubKey,
+		CommissionRate:     d.CommissionRate,
 	}
 }
 
@@ -79,7 +84,8 @@ func (d *Candidate) Equal(c *Candidate) bool {
 		d.Votes.Cmp(c.Votes) == 0 &&
 		d.SelfStake.Cmp(c.SelfStake) == 0 &&
 		d.DeactivatedAt == c.DeactivatedAt &&
-		bytes.Equal(d.BLSPubKey, c.BLSPubKey)
+		bytes.Equal(d.BLSPubKey, c.BLSPubKey) &&
+		d.CommissionRate == c.CommissionRate
 }
 
 // Validate does the sanity check
@@ -274,6 +280,7 @@ func (d *Candidate) toProto() (*stakingpb.Candidate, error) {
 		SelfStake:          d.SelfStake.String(),
 		Pubkey:             pubkey,
 		DeactivatedAt:      d.DeactivatedAt,
+		CommissionRate:     d.CommissionRate,
 	}, nil
 }
 
@@ -324,6 +331,7 @@ func (d *Candidate) fromProto(pb *stakingpb.Candidate) error {
 		d.BLSPubKey = nil
 	}
 	d.DeactivatedAt = pb.GetDeactivatedAt()
+	d.CommissionRate = pb.GetCommissionRate()
 	return nil
 }
 
@@ -341,6 +349,7 @@ func (d *Candidate) toIoTeXTypes() *iotextypes.CandidateV2 {
 		Id:                 d.GetIdentifier().String(),
 		BlsPubKey:          blsPubKey,
 		DeactivatedAt:      d.DeactivatedAt,
+		CommissionRate:     d.CommissionRate,
 	}
 }
 

action/protocol/staking/candidate_test.go

@@ -180,6 +180,48 @@ func TestCloneWithDeactivation(t *testing.T) {
 	r.Equal(uint64(12345), original.DeactivatedAt)
 }
 
+// TestCandidateCommissionRate verifies IIP-59's CommissionRate field
+// survives Equal, Clone, and proto roundtrip — the missing-Equal-update
+// was a bug in the original PoC.
+func TestCandidateCommissionRate(t *testing.T) {
+	r := require.New(t)
+
+	original := &Candidate{
+		Owner:              identityset.Address(1),
+		Operator:           identityset.Address(2),
+		Reward:             identityset.Address(3),
+		Name:               "test_candidate",
+		Votes:              big.NewInt(100),
+		SelfStake:          big.NewInt(1000),
+		SelfStakeBucketIdx: 1,
+		CommissionRate:     1500, // 15%
+	}
+
+	clone := original.Clone()
+	r.True(original.Equal(clone))
+	r.Equal(uint64(1500), clone.CommissionRate)
+
+	// Differing CommissionRate must compare not-equal (PoC missed this).
+	clone.CommissionRate = 1000
+	r.False(original.Equal(clone))
+	clone.CommissionRate = 1500
+	r.True(original.Equal(clone))
+
+	// Mutation isolation: changing clone does not affect original.
+	clone.CommissionRate = 2000
+	r.Equal(uint64(1500), original.CommissionRate)
+
+	// Proto roundtrip.
+	pb, err := original.toProto()
+	r.NoError(err)
+	r.Equal(uint64(1500), pb.GetCommissionRate())
+
+	restored := &Candidate{}
+	r.NoError(restored.fromProto(pb))
+	r.Equal(uint64(1500), restored.CommissionRate)
+	r.True(original.Equal(restored))
+}
+
 var (
 	testCandidates = []struct {
 		d     *Candidate

action/protocol/staking/handler_set_commission_rate.go

@@ -0,0 +1,53 @@
+// Copyright (c) 2026 IoTeX Foundation
+// This source code is provided 'as is' and no warranties are given as to title or non-infringement, merchantability
+// or fitness for purpose and, to the extent permitted by law, all liability for your use of the code is disclaimed.
+// This source code is governed by Apache License 2.0 that can be found in the LICENSE file.
+
+package staking
+
+import (
+	"context"
+
+	"github.com/iotexproject/iotex-core/v2/action"
+	"github.com/iotexproject/iotex-core/v2/action/protocol"
+)
+
+// handleSetCommissionRate handles IIP-59's SetCommissionRate action.
+//
+// Semantics:
+//   - Only the candidate's owner may set the rate.
+//   - The new rate is stored on the staking candidate immediately. It only
+//     takes effect at distribution time after the next PutPollResult
+//     snapshots it into the per-epoch state.Candidate, which gives voters
+//     ~1.5 epochs of reaction time. No separate cooldown field is needed —
+//     IIP-59 doesn't prescribe one.
+//   - The rate-range check happens at Validate (validateSetCommissionRate)
+//     so out-of-range values never reach the handler.
+//   - A non-owner caller returns a handleError so the tx receipt is marked
+//     failed; block production continues.
+func (p *Protocol) handleSetCommissionRate(
+	ctx context.Context,
+	act *action.SetCommissionRate,
+	csm CandidateStateManager,
+) (*receiptLog, error) {
+	actCtx := protocol.MustGetActionCtx(ctx)
+	rLog := newReceiptLog(p.addr.String())
+
+	cand := csm.GetByOwner(actCtx.Caller)
+	if cand == nil {
+		return rLog, errCandNotExist
+	}
+
+	cand.CommissionRate = act.Rate()
+	if err := csm.Upsert(cand); err != nil {
+		return rLog, csmErrorToHandleError(cand.GetIdentifier().String(), err)
+	}
+
+	topics, eventData, err := action.PackCommissionRateSetEvent(cand.GetIdentifier(), act.Rate())
+	if err != nil {
+		return rLog, err
+	}
+	rLog.AddEvent(topics, eventData)
+	return rLog, nil
+}
+