feat: XDC Network Protocol Upgrade Proposal - Reward Mechanism & Node Tiers#36
feat: XDC Network Protocol Upgrade Proposal - Reward Mechanism & Node Tiers#36AnilChinchawale wants to merge 3 commits intomainfrom
Conversation
- Three-tier node system (Master, Protector, Observer) - Unlimited staking with fixed per-node rewards - Fee burning mechanism (30% base fee) - Gas redistribution model - Technical V2Config implementation - Timeline and security considerations Author: Community Proposal Date: February 2026
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📝 WalkthroughWalkthroughA comprehensive protocol upgrade proposal document is added for the XDC Network, detailing a three-tier node system with staking mechanisms, fee distribution models, implementation specifications, and deployment timeline. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (1)
docs/xdcchain/governance/proposal-reward-mechanism-upgrade.md (1)
56-62: Proposal does not address the ~7.8× increase in annual token issuance.Under the new model, total annual block rewards are:
Tier Nodes Annual/Node Annual Total Master 108 1,000,000 XDC 108,000,000 XDC Protector 216 800,000 XDC 172,800,000 XDC Observer 1,000 400,000 XDC 400,000,000 XDC Total ~680,800,000 XDC/year Current annual issuance (5,000 XDC/epoch × ~17,532 epochs/year) is approximately 87,700,000 XDC/year. The proposal would increase block-reward emissions by approximately 7.8×. The 30% base-fee burn provides only partial offset and is volume-dependent. The Conclusion section lists "sustainable reward model" as a benefit without any quantitative justification. A tokenomics section quantifying net inflation, total supply trajectory, and the break-even burn volume required for net-deflationary operation is necessary for community governance review.
Also applies to: 172-180
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/xdcchain/governance/proposal-reward-mechanism-upgrade.md` around lines 56 - 62, The proposal must explicitly quantify the ~7.8× increase in annual issuance and show net-token effects: add a new "Tokenomics" subsection (referencing the existing "2.2 Proposed Per-Epoch Rewards" table and the Conclusion section) that (1) computes total annual block rewards by tier (use the Master/Protector/Observer counts and per-node annual rewards shown), (2) compares that to current annual issuance (5,000 XDC/epoch × ~17,532 epochs/year) to show the multiplication factor, (3) models net inflation under the proposed 30% base-fee burn (show required burn volume to reach break-even and include a supply trajectory table/graph over a multi-year horizon), and (4) include the same quantitative analysis for the other referenced lines (172–180) so the proposal provides a clear, numeric justification for the claim of a "sustainable reward model."
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/xdcchain/governance/proposal-reward-mechanism-upgrade.md`:
- Around line 116-120: The "3.3 Penalty & Inactivity" section uses vague terms
("Serve few epochs before starting rewards") and lacks concrete slashing rules;
replace that text with precise, implementable parameters: specify an exact
number of warm-up epochs (e.g., N epochs) before rewards begin for a node,
define "inactive" quantitatively (e.g., contribution threshold T per epoch),
enumerate clear malicious-behavior criteria for slashing (e.g., double-signing,
equivocation, prolonged downtime > M consecutive epochs, or incorrect state
submissions), state exact slashing percentages for each offense category (e.g.,
X% bond for minor offenses, Y% + temporary ban for major offenses), define
recovery/appeal mechanics (how to submit appeals, evidence window in epochs,
conditions for partial/full bond restoration and unstaking delay), and include
the authoritative labels used in the implementation (reference the section
header "3.3 Penalty & Inactivity", the phrase "Serve few epochs before starting
rewards", and "Slashing mechanism") so authors can replace placeholders with
these concrete thresholds, percentages, and procedural steps for the hard-fork
spec.
- Around line 107-114: Step 6 in the "Implementation Steps" list contradicts the
three-tier fixed per-node reward model described in Section 2.2; update the
"Apply 90/10 split with Foundation Wallet" line in the Implementation Steps (the
numbered list under "3.2 Implementation Steps") to either remove it entirely or
replace it with an explicit statement of the Foundation Wallet treatment under
the new scheme (e.g., "No additional Foundation Wallet split; rewards are fixed
per-node across Master/Protector/Observer tiers as defined in Section 2.2" or an
explicit percent if intended), and ensure the revised line clearly references
the three-tier distribution so readers see it does not stack with the per-node
rewards.
- Around line 95-104: The V2Config struct uses float64 for monetary fields which
is unsafe; change MasternodeReward, ProtectorReward, ObserverReward, FeeBurnRate
(and MinStakeAmount if representing token amounts) to integer/fixed-point types
used elsewhere (e.g., *big.Int for token amounts via math/big, and an integer
scaled unit for FeeBurnRate such as parts-per-billion or basis points) to ensure
exact arithmetic and consensus safety; also add the missing MaxMasternodeNodes
int field (to represent the 108-node cap) alongside MaxProtectorNodes and
MaxObserverNodes. Ensure constructors/JSON (un)marshalling logic and any code
using V2Config (references to V2Config, MasternodeReward, ProtectorReward,
ObserverReward, FeeBurnRate, MinStakeAmount, MaxProtectorNodes,
MaxObserverNodes) are updated to handle the new types and scaling convention.
- Around line 185-189: Update the three broken internal markdown links in the
listed bullet items: change "../whitepaper.md" to "../../whitepaper.md", change
"xdpos.md" to "../xdpos.md", and change "../learn/xdc-architecture.md" to
"../../learn/xdc-architecture.md" so the links in the block containing "[XDC
Whitepaper]", "[XDPoS Documentation]", and "[XDC Architecture]" resolve to the
correct files.
---
Nitpick comments:
In `@docs/xdcchain/governance/proposal-reward-mechanism-upgrade.md`:
- Around line 56-62: The proposal must explicitly quantify the ~7.8× increase in
annual issuance and show net-token effects: add a new "Tokenomics" subsection
(referencing the existing "2.2 Proposed Per-Epoch Rewards" table and the
Conclusion section) that (1) computes total annual block rewards by tier (use
the Master/Protector/Observer counts and per-node annual rewards shown), (2)
compares that to current annual issuance (5,000 XDC/epoch × ~17,532 epochs/year)
to show the multiplication factor, (3) models net inflation under the proposed
30% base-fee burn (show required burn volume to reach break-even and include a
supply trajectory table/graph over a multi-year horizon), and (4) include the
same quantitative analysis for the other referenced lines (172–180) so the
proposal provides a clear, numeric justification for the claim of a "sustainable
reward model."
| ### 2.4 Fee Burning & Gas Enhancement | ||
|
|
||
| #### Base Fee Burning (EIP-1559 Style) | ||
|
|
||
| - A portion of gas fees is burned from each transaction | ||
| - Base fee varies based on network congestion | ||
| - Burn rate: 30% of base fee | ||
|
|
||
| #### Priority Fee Redistribution | ||
|
|
||
| - 70% of priority fees go to the block proposer | ||
| - 30% distributed to Protector and Observer nodes | ||
|
|
There was a problem hiding this comment.
Fee model is internally inconsistent between Section 2.4 and Section 4.1.
Two separate issues:
-
Disposition of the non-burned base fee is never specified. Section 2.4 states 30% of the base fee is burned. Section 4.1's table echoes this. Neither explains what happens to the remaining 70% of the base fee (burned entirely? returned to validators? added to the network fee pool?).
-
"Network Fee" in the Section 4.1 table appears to be a third, distinct fee component, but Section 2.4 describes only two fee types (base fee + priority fee). The 30% figure in the "Network Fee" row matches the 30% priority-fee redistribution from Section 2.4, but presenting it as a separate row in a table alongside "Base Fee" and "Priority Fee" implies it is an additional charge, inflating the perceived total fee burden and misleading implementers.
The table should be restructured to clearly show that the 30% "Network Fee" is a subset of the priority fee, not an additive component, and the fate of the 70% of base fee that is not burned must be specified.
🔧 Suggested restructured fee table for Section 4.1
-| Component | Description |
-|-----------|-------------|
-| Base Fee | Dynamic, burned (30%) |
-| Priority Fee | Goes to validator (70%) |
-| Network Fee | Distributed to Protector/Observer nodes (30%) |
+| Component | Split | Destination |
+|----------------|-----------------|----------------------------------------------|
+| Base Fee (30%) | Burned | Deflationary burn |
+| Base Fee (70%) | [TBD] | [Specify: e.g., burned, treasury, validator] |
+| Priority Fee | 70% / 30% | Block proposer / Protector + Observer nodes |Also applies to: 128-132
| ```go | ||
| type V2Config struct { | ||
| MasternodeReward float64 `json:"masternodeReward"` | ||
| ProtectorReward float64 `json:"protectorReward"` | ||
| ObserverReward float64 `json:"observerReward"` | ||
| MaxProtectorNodes int `json:"maxProtectorNodes"` | ||
| MaxObserverNodes int `json:"maxObserverNodes"` | ||
| FeeBurnRate float64 `json:"feeBurnRate"` | ||
| MinStakeAmount uint64 `json:"minStakeAmount"` | ||
| } |
There was a problem hiding this comment.
float64 is unsafe for token reward amounts — use integer/fixed-point types.
Blockchain financial values must be represented with exact arithmetic. float64 fields for MasternodeReward, ProtectorReward, ObserverReward, and FeeBurnRate introduce floating-point rounding errors that will produce non-deterministic results across nodes, causing consensus failures. The XDC codebase already uses *big.Int (via the Go math/big package) for all token denominations. Additionally, there is no MaxMasternodeNodes field for the 108-node cap, while MaxProtectorNodes and MaxObserverNodes are both present.
🔧 Proposed fix for V2Config struct
type V2Config struct {
- MasternodeReward float64 `json:"masternodeReward"`
- ProtectorReward float64 `json:"protectorReward"`
- ObserverReward float64 `json:"observerReward"`
- MaxProtectorNodes int `json:"maxProtectorNodes"`
- MaxObserverNodes int `json:"maxObserverNodes"`
- FeeBurnRate float64 `json:"feeBurnRate"`
- MinStakeAmount uint64 `json:"minStakeAmount"`
+ MasternodeReward *big.Int `json:"masternodeReward"`
+ ProtectorReward *big.Int `json:"protectorReward"`
+ ObserverReward *big.Int `json:"observerReward"`
+ MaxMasternodeNodes int `json:"maxMasternodeNodes"`
+ MaxProtectorNodes int `json:"maxProtectorNodes"`
+ MaxObserverNodes int `json:"maxObserverNodes"`
+ // FeeBurnRate stored as basis points (e.g., 3000 = 30%)
+ FeeBurnRate uint64 `json:"feeBurnRate"`
+ MinStakeAmount *big.Int `json:"minStakeAmount"`
}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/xdcchain/governance/proposal-reward-mechanism-upgrade.md` around lines
95 - 104, The V2Config struct uses float64 for monetary fields which is unsafe;
change MasternodeReward, ProtectorReward, ObserverReward, FeeBurnRate (and
MinStakeAmount if representing token amounts) to integer/fixed-point types used
elsewhere (e.g., *big.Int for token amounts via math/big, and an integer scaled
unit for FeeBurnRate such as parts-per-billion or basis points) to ensure exact
arithmetic and consensus safety; also add the missing MaxMasternodeNodes int
field (to represent the 108-node cap) alongside MaxProtectorNodes and
MaxObserverNodes. Ensure constructors/JSON (un)marshalling logic and any code
using V2Config (references to V2Config, MasternodeReward, ProtectorReward,
ObserverReward, FeeBurnRate, MinStakeAmount, MaxProtectorNodes,
MaxObserverNodes) are updated to handle the new types and scaling convention.
| ### 3.2 Implementation Steps | ||
|
|
||
| 1. Pull candidates from parent state of epoch switch block | ||
| 2. Rank by Candidate Cap (stake from owner + voters) | ||
| 3. Assign roles (Master, Protector, Observer) | ||
| 4. Calculate fixed rewards per contributing node | ||
| 5. Distribute rewards to node owners | ||
| 6. Apply 90/10 split with Foundation Wallet |
There was a problem hiding this comment.
Step 6 ("Apply 90/10 split with Foundation Wallet") contradicts the proposed new reward model.
The new model replaces the flat 90/10 split with fixed per-node rewards across three tiers. Retaining Step 6 verbatim implies the Foundation Wallet split is applied on top of the three-tier distribution, which conflicts with the reward table in Section 2.2. This needs to either be removed or replaced with an explicit statement of what — if anything — the Foundation Wallet receives under the new scheme.
🔧 Suggested replacement for Step 6
-6. Apply 90/10 split with Foundation Wallet
+6. Distribute remaining epoch emissions: [specify Foundation Wallet allocation under new model,
+ e.g., fixed allocation, percentage of total, or zero]🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/xdcchain/governance/proposal-reward-mechanism-upgrade.md` around lines
107 - 114, Step 6 in the "Implementation Steps" list contradicts the three-tier
fixed per-node reward model described in Section 2.2; update the "Apply 90/10
split with Foundation Wallet" line in the Implementation Steps (the numbered
list under "3.2 Implementation Steps") to either remove it entirely or replace
it with an explicit statement of the Foundation Wallet treatment under the new
scheme (e.g., "No additional Foundation Wallet split; rewards are fixed per-node
across Master/Protector/Observer tiers as defined in Section 2.2" or an explicit
percent if intended), and ensure the revised line clearly references the
three-tier distribution so readers see it does not stack with the per-node
rewards.
| ### 3.3 Penalty & Inactivity | ||
|
|
||
| - Inactive nodes (no contribution during epoch) receive no rewards | ||
| - Penalty provision: Serve few epochs before starting rewards | ||
| - Slashing mechanism for malicious behavior |
There was a problem hiding this comment.
Penalty mechanism lacks quantitative specifics.
"Serve few epochs before starting rewards" is not actionable for implementation — "few" is undefined. Similarly, the slashing mechanism has no stated criteria (what constitutes malicious behavior?), no slashing percentage, and no appeal/recovery process. For a governance proposal that will drive a hard-fork implementation, these must be precisely specified.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/xdcchain/governance/proposal-reward-mechanism-upgrade.md` around lines
116 - 120, The "3.3 Penalty & Inactivity" section uses vague terms ("Serve few
epochs before starting rewards") and lacks concrete slashing rules; replace that
text with precise, implementable parameters: specify an exact number of warm-up
epochs (e.g., N epochs) before rewards begin for a node, define "inactive"
quantitatively (e.g., contribution threshold T per epoch), enumerate clear
malicious-behavior criteria for slashing (e.g., double-signing, equivocation,
prolonged downtime > M consecutive epochs, or incorrect state submissions),
state exact slashing percentages for each offense category (e.g., X% bond for
minor offenses, Y% + temporary ban for major offenses), define recovery/appeal
mechanics (how to submit appeals, evidence window in epochs, conditions for
partial/full bond restoration and unstaking delay), and include the
authoritative labels used in the implementation (reference the section header
"3.3 Penalty & Inactivity", the phrase "Serve few epochs before starting
rewards", and "Slashing mechanism") so authors can replace placeholders with
these concrete thresholds, percentages, and procedural steps for the hard-fork
spec.
|
|
||
| - [Original Proposal](https://www.xdc.dev/gary/proposal-xdc-network-reward-mechanism-upgrade-3kkc) | ||
| - [XDC Whitepaper](../whitepaper.md) | ||
| - [XDPoS Documentation](xdpos.md) | ||
| - [XDC Architecture](../learn/xdc-architecture.md) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# First, locate the proposal file to confirm its directory
echo "=== Locating proposal file ==="
fd -t f "proposal-reward-mechanism-upgrade.md"
echo ""
echo "=== Checking for whitepaper.md ==="
fd -t f "whitepaper.md"
echo ""
echo "=== Checking for xdpos.md ==="
fd -t f "xdpos.md"
echo ""
echo "=== Checking for xdc-architecture.md ==="
fd -t f "xdc-architecture.md"
echo ""
echo "=== Listing docs/xdcchain directory structure ==="
tree -L 2 docs/xdcchain/ 2>/dev/null || find docs/xdcchain -type f -name "*.md" | head -20Repository: XinFinOrg/Docs
Length of output: 1439
🌐 Web query:
site:xdc.dev proposal-xdc-network-reward-mechanism-upgrade
💡 Result:
The query matches this XDC Developers Forum post:
- “Proposal: XDC Network Reward Mechanism Upgrade” (Gary) — posted Apr 21, 2025; updated Apr 25, 2025. It proposes changing XDC’s epoch-based rewards (epoch = 900 blocks/rounds; fixed 5000 XDC/epoch in the current config) into a tiered, fixed per-node reward model across Master (1–108), Protector (109–324), and Observer (325–1324) nodes, with distribution still described as 90% to contributing node owners / 10% to the Foundation wallet, and notes the upgrade would require a hard fork and an activation block parameter. [1]
Fix broken internal documentation links.
All three internal links have incorrect relative paths and will not resolve:
../whitepaper.mdshould be../../whitepaper.md(file is atdocs/whitepaper.md, notdocs/xdcchain/whitepaper.md)xdpos.mdshould be../xdpos.md(file is atdocs/xdcchain/xdpos.md, notdocs/xdcchain/governance/xdpos.md)../learn/xdc-architecture.mdshould be../../learn/xdc-architecture.md(file is atdocs/learn/xdc-architecture.md, notdocs/xdcchain/learn/xdc-architecture.md)
The external link to the XDC Developers Forum post is live and accessible.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/xdcchain/governance/proposal-reward-mechanism-upgrade.md` around lines
185 - 189, Update the three broken internal markdown links in the listed bullet
items: change "../whitepaper.md" to "../../whitepaper.md", change "xdpos.md" to
"../xdpos.md", and change "../learn/xdc-architecture.md" to
"../../learn/xdc-architecture.md" so the links in the block containing "[XDC
Whitepaper]", "[XDPoS Documentation]", and "[XDC Architecture]" resolve to the
correct files.
- Add proposal to Governance nav section - Update proposal with proper metadata PR: #36
- Add upcoming protocol upgrades section - Link to new reward mechanism proposal
1 participant
Summary
This PR adds a comprehensive proposal for XDC Network Protocol Upgrade including:
New Features
Technical Changes
Files Changed
References
Status: Draft - Ready for community review
Summary by CodeRabbit