XDC Network – Unstaking & Withdrawal Process (XDC 2.0)
This document provides a technical overview of the XDC Network's unstaking and withdrawal process under the XDC 2.0 protocol. It explains how the 30-day lock period is implemented and enforced within the smart contract, with code references to illustrate each step. It also addresses how unstaking timing interacts with block and epoch boundaries.
1. Overview of Unstaking and Withdrawal
In XDC 2.0, when a validator or delegator initiates an unstake, the XDC tokens are not immediately available for withdrawal. Instead, they enter a 30-day time-locked state. After this period elapses, the user must manually invoke a withdrawal function to retrieve their tokens.
2. Definition of the 30-Day Lock
The lock duration is defined in the smart contract as a constant using Solidity's time literal. The relevant line is:
uint256 public constant UNSTAKING_LOCK_TIME = 30 days;
This line defines the lock period using Solidity's built-in time unit. The value translates to 2,592,000 seconds (30 * 24 * 60 * 60).
3. Unstaking Logic – Where the Lock Is Set
When a user unstakes, the contract schedules a future withdrawal by creating an entry with a calculated unlock time:
pendingWithdrawals[msg.sender].push(WithdrawEntry({
amount: _amount,
unlockTime: block.timestamp + UNSTAKING_LOCK_TIME,
withdrawn: false
}));
This entry is stored in a mapping of arrays and marks the amount, unlock timestamp, and withdrawal status.
4. Withdrawal Execution – How Tokens Are Claimed
After 30 days have passed, the user can call the withdrawStaking() function. The contract checks each entry in the user's withdrawal queue:
if (!entries[i].withdrawn && block.timestamp >= entries[i].unlockTime) {
total = total.add(entries[i].amount);
entries[i].withdrawn = true;
}
Only entries that have not yet been claimed and whose unlockTime has been reached are processed for withdrawal. The total eligible amount is then transferred back to the user's wallet.
5. What Happens if You Unstake Mid-Epoch or Mid-Block?
In XDC 2.0, the unstaking lock period is based purely on wall-clock time using block timestamps — not block height or epoch cycles. This means that it doesn't matter whether you unstake at the beginning, middle, or end of an epoch or block; the 30-day timer begins the exact moment the unstake transaction is mined (i.e., when the block.timestamp is recorded).
Unstaking halfway through an epoch does not shorten or lengthen the lock period. The unlock time is deterministic and tied to when the transaction was processed, not the structure of the network’s epoch system.
6. Summary (Plain Explanation)
When you unstake your XDC tokens, they are locked for a full 30 days. This waiting period begins immediately when the unstake transaction is mined. It doesn’t matter what point within the network’s epoch you unstake — the countdown is fixed based on real time. After 30 days, you must manually call the withdraw function to receive your tokens via your wallet. If you don’t withdraw right away, the tokens remain safely locked in the contract until you do.
Reference:
Discussion (1)