XDCValidator Contract Upgrade: Modernizing Staking for the Next Era of XDC

TL;DR: The XDCValidator contract (0x88) was deployed with Solidity 0.4.21 and has never received a major upgrade. The ecosystem has matured significantly since then. Liquid staking protocols, institutional staking services, and DeFi composability all demand a more flexible validator lifecycle. I'm proposing we use a contract upgrade as an opportunity to modernize the staking/unstaking mechanism, fix accumulated state inefficiencies, and unlock new use cases. Below are three concrete scenarios for community discussion.

Why Now?

The current XDCValidator contract has served the network well, but several realities make an upgrade worth discussing:

1. Compiler vintage. Solidity 0.4.21 predates significant compiler improvements (SafeMath built-ins, custom errors, overflow checks, ABI encoder v2). Newer Solidity versions offer better gas efficiency, security defaults, and developer ergonomics.

2. State hygiene. Over the network's lifetime the contract has accumulated storage artifacts (zeroed-out array entries, stale mappings) that waste gas and complicate on-chain queries. A migration is an opportunity for a clean slate.

3. The "30-day" wall that's actually 35-42 days. The contract uses block-number-based delays set at genesis: candidateWithdrawDelay = 1,296,000 blocks for masternode owners resigning, and voterWithdrawDelay = 432,000 blocks for voters unvoting. These are hardcoded constructor parameters with no governance mechanism to adjust them.

The 2-second block time is a theoretical target, not a guarantee. Real-world data from xdcscan tells a different story:

| Period | Avg block time | Effective owner withdrawal delay |
|---|---|---|
| Theoretical | 2.00s | 30.0 days |
| Last 30 days (Mar 2026) | 2.33s | ~35 days |
| Last 365 days | 2.33s | ~35 days |
| Last 90 days (includes Jan 2026 spikes) | 2.83s | ~42 days |
| Worst days (Jan 11-12, 2026) | 13.6s | Would imply ~204 days if sustained |

In practice, masternode owners resigning today should expect to wait ~35 days under normal conditions, and potentially longer during network congestion events. The block time has never consistently held at 2.00s. The network regularly averages 2.2-2.8s, and periodic spikes (Dec 26: 8.4s, Dec 28-30: 4-5s, Jan 10-12: 5-14s) push the effective delay even further.

For liquid staking protocols, this unpredictability on top of an already long delay is the binding constraint. Protocols must either (a) keep a large idle reserve buffer sized for worst-case timing, (b) force users to wait 35+ days, or (c) route through DEX secondary markets at a discount. All three options erode capital efficiency and hurt adoption.

Important detail: resign() only unlocks the owner's own voter stake, not the full candidacy cap. Other voters who staked on that candidate must separately call unvote() (with a ~12-day effective delay at current block times) to retrieve their funds. withdraw() must be called individually per withdrawal entry (specific blockNumber + index), there is no batch withdrawal.

1. Ecosystem competitiveness. Other networks have already moved to dynamic or queue-based unstaking:
   • Ethereum: epoch-based churn limit (~8 validators/epoch), exit times range from hours to weeks depending on demand
   • Polkadot: RFC-0097 introduces dynamic unbonding from 2 days (empty queue) to 28 days (high demand)
   • Cosmos: 21-day unbonding with per-block queue maturation
   • Avalanche: ACP-273 proposes reducing minimum staking from 14 days to 48 hours

XDC's flat 30 days with zero flexibility is an outlier.

Current Mechanism (Deployed at 0x88)

For context, here's the live on-chain state of the contract, queried via eth_getStorageAt against mainnet RPC and cross-referenced with the verified source on xdcscan:

Contract Parameters (immutable since genesis)

Live Network State (queried March 2026)

Withdrawal Flow Today

1. Owner calls resign(candidateAddress) → isCandidate set to false, owner's own stake scheduled for release at block.number + 1,296,000.
2. Owner waits ~35 days in practice (1.296M blocks at real-world avg of 2.33s/block, can stretch to 40+ days during congestion spikes).
3. Owner calls withdraw(blockNumber, index). Must specify the exact block number and array index. No batch withdrawal.
4. Voters on the same candidate must independently call unvote() → their stake is released after block.number + 432,000 (~12 days actual).

Key Limitations

• Block-count based delays, not timestamp-based. The effective wait drifts with block time fluctuations. At the recent 90-day average of 2.83s/block, the owner delay stretches to ~42 days.
• No parameter governance. candidateWithdrawDelay and voterWithdrawDelay are constructor-set with no admin function to adjust them.
• maxValidatorNumber is stale. Contract says 18, consensus layer uses 108. The parameter serves no active purpose.
• ownerCount only increments. resign() does not decrement ownerCount, meaning it includes all historical owners. This inflates the denominator in any governance calculation that uses it.

The Three Scenarios

Scenario A: Three-Tier Exit Queue (Simple & Predictable)

Concept: The withdrawal lock duration depends on how many masternodes are currently pending withdrawal at the time you resign. Three tiers create a clear incentive structure: exits are fast when the queue is light, moderate at normal load, and fall back to the full 30 days only under heavy exit pressure.

How it works:

1. Validator calls resign().
2. Contract reads pendingWithdrawalCount (number of validators currently in the withdrawal pipeline).
3. If < 5 → assign 3-day lock.
4. If 5-10 → assign 14-day lock.
5. If > 10 → assign 30-day lock.
6. Withdraw after lock expires (unchanged).

Why liquid staking loves this: Under normal network conditions, the exit queue rarely has more than a handful of nodes pending at once. A liquid staking protocol operating 20 masternodes could rotate nodes with just a 3-day turnaround, small enough to serve redemptions from a thin buffer without sacrificing yield. When the queue gets crowded, the longer delays kick in automatically, giving the protocol a clear signal to pause redemptions or route to secondary markets.

Trade-offs:

• Simple to implement and reason about, just two if checks.
• Tier boundaries (5 / 10) need tuning based on network size; could be made governance-adjustable.
• Lock is fixed at resign time, so a validator who resigns at queue depth 4 gets 3 days even if 20 more resign in the next block.

Scenario B: Continuous Dynamic Duration Based on Queue Depth (Polkadot-Inspired)

Concept: Instead of hard tiers, the lock duration scales smoothly between a floor and ceiling based on the number of masternodes currently pending withdrawal. Below 5 nodes the lock approaches its minimum; above 10 it ramps toward the maximum; and it caps at 30 days.

Formula:

if pendingNodes < 5:
    lockDays = 2 + (pendingNodes * 1)            // 2d → 6d
else if pendingNodes <= 10:
    lockDays = 7 + (pendingNodes - 5) * 4.6      // 7d → 30d
else:
    lockDays = 30                                  // hard cap

How it works:

1. Validator calls resign().
2. Contract reads pendingWithdrawalCount.
3. Lock duration is computed from the formula above.
4. Assign lockDuration to this withdrawal entry.
5. Withdraw after lock expires (unchanged).

Example at current network size (~108 active masternodes):

Why liquid staking loves this: In the common case (1-3 nodes cycling out), the lock is 2-5 days. A liquid staking protocol can keep a minimal reserve buffer and serve redemptions almost in real-time. The smooth curve also means there's no "cliff" at a tier boundary. Protocols can forecast lock times with a simple view function call before deciding whether to initiate a withdrawal.

Trade-offs:

• Slightly more complex than tiered (requires on-chain math), but still a single storage read + arithmetic.
• Lock duration isn't known until the moment of resignation (though a previewLockDuration() view function makes this transparent).
• Elegant security guarantee: if many nodes rush to exit, the lock automatically stretches to 30 days, protecting the network without any governance intervention.

Scenario C: Adaptive Churn Limit with FIFO Queue (Ethereum-Inspired)

Concept: Validators enter a FIFO exit queue on resign(). The network processes exits at each epoch boundary, but the processing speed adapts based on queue depth: fast when the queue is short, throttled when it's deep.

How it works:

1. Validator calls resign() → enters the exit queue with a sequence number. Post-lock duration is assigned at this point based on current queue depth.
2. At each epoch boundary, the contract reads the current queue depth and processes exits accordingly.
3. If queue < 5 → process up to 5 exits this epoch. Post-lock for new resignations: 48 hours.
4. If queue 5-10 → process up to 2 exits this epoch. Post-lock for new resignations: 48 hours.
5. If queue > 10 → process only 1 exit this epoch. Post-lock for new resignations: 7 days.
6. Withdraw after post-lock expires.

Note: the churn rate adapts as the queue drains. A queue of 25 doesn't process at 1/epoch the whole time. Once it drops below 10, it speeds up to 2/epoch, then 5/epoch below 5.

Example queue scenarios (traced through adaptive processing):

Why liquid staking loves this: Under normal conditions (1-4 nodes exiting), the entire queue flushes in a single epoch and exit time is just 2 days. The protocol can predict its exact queue position and calculate withdrawal timing deterministically. When exit pressure rises, the system automatically shifts to a more conservative pace, giving protocols a clear signal to adjust their redemption flow.

Trade-offs:

• Most complex to implement (requires epoch hooks or a keeper-based trigger + adaptive rate logic).
• The dual lever (churn rate + post-lock duration) gives fine-grained control but adds cognitive overhead.
• When the queue is deep (> 10), exit times are still dramatically better than the current 30 days, but the 7-day post-lock provides a meaningful security buffer.
• Churn rate boundaries (5 / 10) should be governance-adjustable as the network grows.

Additional Upgrade Opportunities

Since we'd be touching the contract anyway, it would be worth bundling other improvements:

• Compiler upgrade to Solidity ≥0.8.x (built-in overflow protection, custom errors, gas optimizations)
• Array compaction for the candidates list (eliminate zeroed entries, reduce gas for enumeration)
• Event coverage for all state-changing operations (currently some paths emit no events)
• ownerCount bookkeeping to accurately reflect the active validator set
• Withdrawal batching. Currently withdraw(blockNumber, index) requires one call per entry; a withdrawAll() that claims all mature entries in a single transaction would drastically improve UX
• View functions for queue position, estimated lock duration, pending withdrawal count, and total exiting stake
• Timestamp-based delays instead of block-count, decoupling the lock period from block time fluctuations
• KYC flow improvements with proper access control and state management
• SafeMath / overflow protection for all arithmetic (native with 0.8.x)

Comparison Matrix

What I'd Like to Hear From the Community

1. Which scenario resonates most with how you think XDC should evolve?
2. Are there hybrid approaches? For example, Scenario B (dynamic duration) + Scenario C (churn limit) combined.
3. What's the right security floor? Is 48 hours too aggressive for the minimum lock? Should it be 7 days?
4. Upgrade mechanism. Should this be a full contract migration with state transfer, or an upgradeable proxy pattern going forward?
5. Backwards compatibility. How do we handle existing stakers and pending withdrawals during migration?

The 30-day fixed lock was a reasonable default at launch, but the XDC ecosystem has outgrown it. Liquid staking, institutional staking services, and DeFi protocols all need a more dynamic validator lifecycle. Let's design it together.

References:

• XDCValidator.sol (current)
• XDC 2.0 Unstaking & Withdrawal Process
• Ethereum EIP-7922: Dynamic exit queue rate limit
• Polkadot RFC-0097: Unbonding Queue
• Avalanche ACP-273: Reduce Minimum Staking Duration