# Overview Non-custodial XDC staking infrastructure. No principal-stake slashing. {% hint style="info" %} PrimeStaking runs on the **`PrimeStakedXDC_V3_2`** vault, a fully non-custodial, ERC-4626 share-based design with self-service withdrawals. In July 2026 the vault was redeployed as V3.2 and **every V3.1 holder's balance was mirrored 1:1 via a snapshot airdrop; no user action was needed**. The XDC NFT vault was repointed to the V3.2 token in the same operation and gained multiple lock tiers. V2 holders who never migrated can still do so through the [migration bridge](/products/xdc-liquid-staking/staking-guide/migration); legacy NFTs migrate via [Migrate XDC NFTs to V3](/products/xdc-staking-nfts/migrate-nfts-v2-to-v3). {% endhint %} ## Overview **PrimeStaking** is a non-custodial staking platform and infrastructure provider on the XDC Network, built in collaboration with **Nethermind** and the **XDC Core team**. The platform is live at [primestaking.xyz](https://primestaking.xyz). *** ### Who Is This For? | Audience | What You'll Find | Go To | | --------------------------- | ----------------------------------------------- | ------------------------------------------- | | **Users** | Stake XDC, earn rewards, explore NFTs | [For Users](#for-users) | | **Partners & Institutions** | Integrate XDC liquid staking into your platform | [For Partners](#for-partners--institutions) | *** *** ## For Users Earn rewards on XDC without giving up control of your assets. ### Products | Product | Token | Yield | How It Works | | ---------------------- | ----- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | **XDC Liquid Staking** | XDC | \~5.5% APY | Stake XDC, receive psXDC vault shares. Share price grows as validator rewards accrue. | | **XDC NFTs** | psXDC | \~5.5% base + boost slice → up to \~7% locked | Deposit psXDC shares into NFTs. Earn the underlying NAV plus a rarity- and lock-weighted boost slice. | #### XDC Liquid Staking The simplest way to earn on your XDC. No NFT required. No minimum amount. 1. **Stake XDC** - Deposit any amount into the V3 vault. 2. **Receive psXDC shares** - You receive psXDC at the current vault exchange rate. There is no fixed 1:1 ratio; share price rises as rewards accrue. 3. **Earn rewards** - Rewards are embedded directly in the share price (\~5.5% APY). There is no claim button; your shares simply become worth more XDC over time. Rewards accrue continuously at any backing level (the V3.2 permanent-ledger model). 4. **Stay liquid** - psXDC is a standard ERC-20 on the XDC Network. Hold it, transfer it, use it as DeFi collateral, or deposit it into XDC NFTs. 5. **Withdraw anytime** - Burn psXDC shares. If the vault has enough unencumbered liquidity, you receive XDC instantly in the same transaction. Otherwise your request enters an automatic FIFO queue and you claim once masternode payouts return. 6. **Refer friends** - Share your invite link; when someone stakes for the first time through it, you earn a share of the protocol fee their staking generates. See [Referral Program](/products/xdc-liquid-staking/referral-program). → [Learn more about XDC Liquid Staking](/products/xdc-liquid-staking) → [V3 Architecture](/products/xdc-liquid-staking/v3-architecture) #### XDC NFTs A gamified staking layer on top of liquid staking. Deposit psXDC shares into collectible NFTs to earn two stacked yields. * Each NFT has a **rarity** (Plentiful → Handcrafted) that determines its weight in the boost accumulator. * **Base yield** comes from the underlying psXDC share price growing over time (\~5.5% APY). * **Boost yield** comes from a Synthetix-style accumulator. The protocol's [`XdcNftBoostHarvester`](/products/xdc-staking-nfts/boost-harvester) calls `notifyBoost` and the resulting slice is distributed pro-rata to NFT weights. * **Level up** by merging two same-rarity NFTs into a higher tier. * **Lock** your NFT for a fixed period to add a lock bonus to its weight. Four tiers are available - **30, 90, 180 or 365 days** - with progressively larger boosts. The boost applies for the whole lock and **ends when the lock expires**; you can re-lock afterwards. Floor is the **\~5.5% base NAV** (always earned, no claim); with the boost stream flowing, combined APY ranges from **\~5.75% (unlocked)** up to **\~7% (365-day lock)**. * You only claim the **boost slice** from the app. Base NAV is automatically inside the shares you get back on withdraw. → [Learn more about XDC NFTs](/products/xdc-staking-nfts) → [Migrate XDC NFTs to V3](/products/xdc-staking-nfts/migrate-nfts-v2-to-v3) #### How Rewards Reach You | Product | What you earn | How you receive it | | ---------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------- | | **XDC Liquid Staking** | Higher psXDC share price | Automatic: your shares are worth more XDC over time. No claim button. | | **XDC NFTs** | Underlying NAV growth + boost slice (in XDC) | NAV is automatic; **claim boost** from the NFT detail page. Withdraw burns shares back to XDC. | #### The psXDC Ecosystem ``` XDC → psXDC shares → NFT → Boost slice ``` | Step | What Happens | | ----------- | ------------------------------------------------------------------------------- | | **Stake** | Deposit XDC into the V3 vault. | | **Receive** | Get psXDC shares at the current exchange rate. NAV starts accruing immediately. | | **Use** | Hold psXDC, trade it on a DEX, or deposit it into an XDC NFT. | | **Boost** | NFT rarity, level, and lock add weight to your slice of the boost accumulator. | *** *** ## For Partners & Institutions PrimeStaking is **XDC liquid staking infrastructure** - built for exchanges, custodians, and institutional partners who want to offer XDC staking to their customers without building from scratch. ### Three Partner Models | Model | Description | Best For | | -------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | **White Label** | Your brand, our infrastructure. | Exchanges, large custodians | | **Powered by Prime** | Co-branded widget. Minimal integration effort. | Wallets, aggregators, regional platforms | | **Partner Staking** | Deploy and self-manage **your own** liquid staking pool, listed in the PrimeStaking app. Flat 15% protocol fee. | Communities, validators, regional platforms | White Label and Powered by Prime are integration tracks where you embed the flagship PrimeStaking vault (see [For Partners](#for-partners--institutions) below). **Partner Staking** is a distinct, self-service product where you run your own vault (see [Partner Staking](/partner-staking/partner-staking)). ### Why Partners Choose PrimeStaking * **No principal-stake slashing** - XDC's slashing mechanism penalizes downtime via temporary exclusion from block production (\~2h) and missed rewards; principal stake is never burned, unlike ETH-based protocols. * **ERC-4626 vault** - psXDC v3 conforms to the same standard used by major DeFi protocols, making integration straightforward. * **Non-custodial** - smart contract-based validator custody, no third-party key management, no admin mint or `ownerWithdraw`. * **Audited infrastructure** - QuillAudits (98.8%) on the V1 liquid staking contracts; **Nethermind Security NM-0843** (published May 08, 2026) on the psXDC V3 vault and V3 Migration Bridge. * **Nethermind Security** - trusted auditing partner for Lido, EtherFi, Optimism, and Worldcoin. * **Battle-tested** - live since 2024 with $6M+ TVL. * **Revenue sharing** - transparent, on-chain fee model. ### Partner Documentation | Section | What It Covers | | ------------------------------------------------------ | ---------------------------------------------------------- | | [Institutional Overview](/for-partners/institutional) | What we offer, why PrimeStaking, why XDC Network | | [Architecture](/for-partners/architecture) | System design, contract topology, validator infrastructure | | [Custody Model](/for-partners/custody-model) | Permissionless smart contract-based key management | | [Integration Models](/for-partners/integration-models) | White Label vs. Powered by Prime | | [Revenue Model](/for-partners/revenue-model) | Revenue generation, partner sharing, settlement | | [Reward Mechanics](/for-partners/reward-mechanics) | How staking rewards are generated and distributed | | [Liquidity Model](/for-partners/liquidity-model) | psXDC liquidity, share price, redemption mechanics | | [Governance](/for-partners/governance) | Role separation, delayed governance, what is upgradeable | | [Risk & Compliance](/for-partners/risk-and-compliance) | Risk framework, audit history, regulatory posture | | [SLA & Support](/for-partners/sla-and-support) | Uptime commitments, incident response, partner support | **Contact:** *** *** ### Security * `PrimeStakedXDC_V3_2` is **non-upgradeable**, deployed with a regular constructor and no proxy. The vault logic cannot be modified after deployment. The referral contracts (`ReferralRegistry`, `ReferralRewards`) are likewise non-upgradeable satellites; they never hold user principal. * The XDC NFT staking vault is a `TransparentUpgradeableProxy` controlled by the protocol multisig, with namespaced ERC-7201 storage. All other NFT-stack contracts (collection, migrator, harvester, bypass facet) are non-upgradeable. * Validator custody is **smart contract-based** - permissionless and trustless, no third-party custodian. * The protocol is **non-custodial** - users retain full ownership of their assets at all times. * Infrastructure developed with **Nethermind** and the **XDC Core team**. → [Audits & Security](/security/audits-1) → [Custody & Key Management](/security/custody-and-key-management) → [Deployed Contracts & Addresses](/products/contract-addresses) *** ### Quick Links | Resource | Link | | ----------------------- | ------------------------------------------------------------------------------------------------------ | | App | [primestaking.xyz](https://primestaking.xyz) | | XDC Liquid Staking | [primestaking.xyz/xdc-liquid-staking/overview](https://primestaking.xyz/xdc-liquid-staking/overview) | | XDC NFTs | [primestaking.xyz/xdc-nfts/overview](https://primestaking.xyz/xdc-nfts/overview) | | Migrate XDC NFTs | [primestaking.xyz/xdc-nfts/migrate](https://primestaking.xyz/xdc-nfts/migrate) | | Migrate psXDC V2 → V3 | [primestaking.xyz/xdc-liquid-staking/migration](https://primestaking.xyz/xdc-liquid-staking/migration) | | Referral Program | [primestaking.xyz/xdc-liquid-staking/referral](https://primestaking.xyz/xdc-liquid-staking/referral) | | Institutional Solutions | [Institutional & Exchange Solutions](/for-partners/institutional) | | Partner Staking | [Run your own staking pool](/partner-staking/partner-staking) | | psXDC V3.2 vault | [XDCScan](https://xdcscan.com/address/0xDc74c0DaED82ae94486DeeF22991d2F54173c734) | | Deployed addresses | [Contract Addresses](/products/contract-addresses) | | Contact | | # XDC Liquid Staking XDC Liquid Staking lets you earn staking rewards on any amount of XDC, without running a node, meeting a minimum threshold, or locking your funds permanently. PrimeStaking V3 is a fully non-custodial, ERC-4626 vault: rewards accrue directly to the share price and withdrawals are self-service. *** ## Key Facts | | | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **APY** | \~5.5% (accrued automatically through share price growth) | | **Reward cadence** | The XDC Network pays masternode rewards **\~monthly** (typically the first days of the month); the psXDC rate steps up when each payment lands — a flat rate between payouts is normal | | **Minimum stake** | None | | **Token received** | psXDC, an ERC-4626 vault share (not a fixed 1:1 receipt) | | **Reward mechanism** | Share price (`totalAssets / totalShares`) grows as validator rewards accrue | | **Claiming** | No claim button; your shares are worth more XDC over time | | **Withdrawal** | Self-service. **Instant** when the buffer is sufficient, otherwise **queued** with self-claim via `claimQueuedAssets` | | **DEX exit** | Any DEX pool holding the live V3.2 token: sell psXDC for XDC at market | | **Smart contract** | `PrimeStakedXDC_V3_2` (non-upgradeable, audited) | | **Address** | [`0xDc74c0DaED82ae94486DeeF22991d2F54173c734`](https://xdcscan.com/address/0xDc74c0DaED82ae94486DeeF22991d2F54173c734) | *** ## How It Works ### 1. Stake Deposit XDC through the staking interface at [primestaking.xyz](https://primestaking.xyz/xdc-liquid-staking/overview). No account setup or KYC required, just connect your wallet. The vault mints psXDC shares for you at the current exchange rate. The app previews exactly how many shares you will receive before you sign. ### 2. Receive psXDC Shares psXDC is an ERC-4626 vault share. There is no fixed 1:1 ratio: * At launch, **1 psXDC ≈ 1 XDC**. * After rewards accrue, **1 psXDC > 1 XDC** (e.g. 1 psXDC redeems for 1.05 XDC once the exchange rate has grown). You don't need to manage two balances. The share is the only thing you hold, and it carries its value with it wherever you send it. ### 3. Earn Rewards Automatically Validator rewards flow back into the vault and become part of `totalAssets`. Because the share supply doesn't change, each share is worth more XDC. This is the same pattern Aave aTokens, Compound cTokens, and Lido wstETH use. **There is no "Claim Rewards" button for liquid staking**; your shares simply appreciate. ### 4. Use psXDC psXDC is a standard ERC-20 on the XDC Network. While the vault earns yield, you can: * **Hold** to accumulate rewards passively (the share price keeps rising). * **Trade** on DEXs (typically paired with XDC). * **Deposit into XDC NFTs** to layer the boost slice on top of your NAV. * **Use as collateral** in DeFi protocols that support ERC-4626 vault tokens. * **Bridge to Base, Arbitrum, BNB Chain, or HyperEVM** ([guide](/products/xdc-liquid-staking/bridge)) and lend it on PrimeFi or LP it there — the staking yield keeps accruing the whole time ([opportunities](/products/xdc-liquid-staking/multichain-opportunities)). * **Transfer** to any wallet; the recipient inherits the appreciating share automatically. ### 5. Withdraw To convert back to XDC you have three options: * **Instant redeem**: when the vault's liquid buffer holds enough XDC to cover your request, the redemption settles in the same transaction. No queue, no waiting. * **Queued redeem**: when liquidity is constrained, your shares are escrowed and your request joins an automatic FIFO queue. As soon as new deposits or masternode payouts top up the buffer, the queue is processed and you call `claimQueuedAssets` to collect your XDC. You can also `cancelQueuedWithdrawal` at any time before settlement. * **DEX exit**: swap psXDC for XDC on a DEX (verify the pool holds the live V3.2 token) for immediate liquidity (subject to pool depth and market rate). The app calls `redeemWithQueue` for you, which automatically picks the instant path when possible and falls back to the queue when not. You always see in advance which path your transaction will take. {% hint style="info" %} **When a queue backlog exists** (for example right after a migration, while masternodes unwind at the validator contract), free liquidity is usually thin and most withdrawals take the **queued** path — during those periods instant service is the exception, not the rule. The DEX exit remains available for immediate liquidity at market price. {% endhint %} → [Withdrawals: Instant vs Queued](/products/xdc-liquid-staking/staking-guide/withdrawals-instant-vs-queued) → [Request Withdrawal walkthrough](/products/xdc-liquid-staking/staking-guide/request-withdrawal) *** ## Reward Distribution | Detail | Explanation | | -------------------- | ----------------------------------------------------------------------------------------------------------------- | | **Source** | Staking rewards generated by the protocol's XDC Network masternode operators | | **Distribution** | Reward XDC enters the vault → `totalAssets` increases → exchange rate rises → every psXDC share is worth more XDC | | **Claiming** | No claim; accrual is embedded in the share price | | **Partial holdings** | Any amount of psXDC earns yield; nothing is forfeited if you transfer or split balances | *** ## Getting psXDC Two ways to obtain psXDC: 1. **Stake XDC**: deposit through the staking interface to mint psXDC shares directly at the current exchange rate. 2. **Buy on a DEX**: purchase psXDC on a decentralized exchange. Holding psXDC from any source benefits from the appreciating share price. *** ## Migrating from V2 If you already hold the V2 psXDC token, the new vault is a separate contract and your V2 balance does not automatically appear in V3. You need to migrate through the dedicated bridge: 1. Approve [`PrimeStakedXDC_V3MigrationBridge`](/products/contract-addresses) to spend your V2 psXDC. 2. Call `migrate(amount, minSharesOut)`. The bridge burns V2 and mints V3 shares. 3. The migration page in the app calls this for you and lets you tune slippage (defaults to 0.5%). → [Migrate V2 psXDC → V3](/products/xdc-liquid-staking/staking-guide/migration) *** ## Technical Details * **Smart contract-driven**: every stake, redemption, and validator action is on-chain. * **Validator-driven rewards**: share price reflects the protocol's actual masternode performance, not an admin-set APY. * **Non-upgradeable vault**: `PrimeStakedXDC_V3_2` has no proxy. The logic that holds your XDC can never be modified. → [V3 Architecture](/products/xdc-liquid-staking/v3-architecture) → [V2 vs V3: What Changed](/products/xdc-liquid-staking/v2-vs-v3) → [Smart Contract Reference](/products/xdc-liquid-staking/smart-contract-functions) *** ## Benefits * **No infrastructure**: the protocol runs the masternodes. * **No minimum**: stake any amount of XDC. * **Full liquidity**: psXDC keeps your position liquid while earning rewards. * **Composable**: ERC-4626 makes psXDC drop-in compatible with DeFi protocols. * **Non-custodial**: no admin mint, no admin withdraw, no third-party custodian. * **No principal-stake slashing**: XDC's slashing penalizes downtime via temporary exclusion from block production (\~2h) and missed rewards, but never burns principal, so staked capital is never at risk from validator behavior. # V3 Architecture {% hint style="info" %} The live vault is **`PrimeStakedXDC_V3_2`** at [`0xDc74c0DaED82ae94486DeeF22991d2F54173c734`](https://xdcscan.com/address/0xDc74c0DaED82ae94486DeeF22991d2F54173c734), the July 2026 redeployment of the V3 architecture, with every V3.1 balance carried over 1:1 via snapshot airdrop. V2 contracts remain available for stragglers to migrate. {% endhint %} psXDC V3 is a complete rebuild of the liquid staking contract, moving from a custodial model to a fully non-custodial, ERC-4626 tokenized vault. This is the architecture underpinning every new psXDC stake. V3.2 keeps this architecture and makes the partially-backed state the **permanent operating model** (the "permanent ledger"): rewards accrue at any backing level through a manager-only reward lane, NAV is protected against write-downs, and the withdrawal queue is settled from ring-fenced funding lanes so fresh deposits are never consumed by the redemption backlog and user exits keep working throughout. *** ## Overview | | | | ----------------------- | --------------------------------------------------------- | | **Standard** | ERC-4626 (OpenZeppelin tokenized vault) | | **Token** | psXDC, a yield-bearing share token | | **Pricing** | Exchange rate increases as rewards accrue (not fixed 1:1) | | **Withdrawals** | Self-service; no admin approval required | | **Staking** | Direct masternode integration via XDC validator contract | | **Governance** | Role separation with mandatory time-locked delays | | **Admin mint/withdraw** | Disabled (not possible in V3) | *** ## How It Works ### 1. Stake Deposit XDC through the staking interface. The contract mints psXDC shares based on the current exchange rate. The more rewards the vault accumulates, the more XDC each psXDC share is worth. There is no minimum deposit. Staking is permissionless: no account, no KYC, just connect your wallet. ### 2. Earn Rewards Your staked XDC is pooled and delegated to KYC-verified masternode operators on the XDC Network. Validator rewards flow back into the contract automatically, increasing the total assets backing all psXDC shares. You don't need to claim rewards. They are embedded in the share price, so your psXDC simply becomes worth more XDC over time. ### 3. Withdraw You have full self-service access to your XDC: * **Instant withdrawal**: if the contract has sufficient liquid XDC, you redeem shares and receive XDC in the same transaction. No admin approval. No waiting. * **Queued withdrawal**: if most XDC is staked in masternodes and liquidity is temporarily low, your request enters an automatic FIFO queue. It processes as soon as liquidity returns from new deposits, reward inflows, or masternode resignations. * **DEX swap**: sell psXDC directly on a DEX (verify the pool holds the live V3.2 token) for immediate exit at market rate. ### 4. Use psXDC psXDC is a standard ERC-20 token on the XDC Network. While your XDC earns yield in the background, you can: * **Hold** to accumulate rewards passively * **Trade** on DEXs * **Stake inside XDC NFTs** to boost your yield up to 6% * **Use as collateral** in DeFi protocols that support ERC-4626 vault tokens * **Transfer** to any wallet; the recipient inherits the yield automatically *** ## Share-Based Pricing Unlike V2 where 1 psXDC always equals 1 XDC, V3 uses a **share model**: | Concept | How it works | | ----------------- | ------------------------------------------------------------------------------ | | **Deposit** | You deposit XDC, receive psXDC shares based on the current exchange rate | | **Exchange rate** | `totalAssets / totalShares`, which rises over time as rewards accrue | | **Withdrawal** | You burn psXDC shares and receive XDC at the current rate | | **Rewards** | No claiming needed; rewards increase the exchange rate for all holders equally | **Example:** If the exchange rate is 1.05, burning 100 psXDC returns 105 XDC. The rate only goes up (assuming no validator losses). This is the same model used by major DeFi protocols (Aave aTokens, Compound cTokens, Lido wstETH). *** ## Masternode Integration V3 directly stakes XDC with masternodes via the on-chain XDC validator contract. This is what makes psXDC productive: your XDC is not sitting idle. ### How masternodes are managed | Step | What happens | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | **Operator onboarding** | Admin adds KYC-verified masternode operators | | **Auto-propose** | When excess liquid XDC exceeds the threshold, the contract automatically proposes a new masternode using round-robin operator selection | | **Manual propose** | Proposer role can also trigger masternode proposals directly | | **Rewards** | Validator rewards flow back into the contract, increasing the exchange rate | | **Resignation** | Proposer/Admin can resign a masternode; after the network cooldown (\~35 days), the XDC is withdrawn back | | **Principal tracking** | The contract tracks exactly how much XDC is locked per operator, globally and individually | ### Liquidity buffer The contract keeps a configurable percentage of total assets liquid (default 5%) to serve instant withdrawals. This means: * Most XDC is working in masternodes earning yield * A buffer remains in the contract for immediate redemptions * If the buffer is depleted, the withdrawal queue handles the overflow automatically *** ## Governance & Roles V3 separates responsibilities across five roles. No single key can make unilateral changes. | Role | Responsibility | | ---------------------- | ----------------------------------------------------------------- | | **Admin (Owner)** | Governance changes, operator management, KYC | | **Operations Manager** | Day-to-day parameters: buffer %, scan limits, auto-propose config | | **Risk Manager** | Report validator losses (capped per-report and per-day) | | **Proposer** | Propose and resign masternodes | | **Migration Manager** | Control the V2→V3 migration window | ### Time-locked changes Every sensitive parameter change follows a three-step pattern: 1. **Schedule** the change → mandatory governance delay begins (default 1 day) 2. **Wait**, during which anyone can see the pending change on-chain 3. **Execute** the change after the delay expires, or **cancel** it at any time This applies to: role changes, loss caps, governance delay itself, ownership transfer, and migration bridge configuration. *** ## Risk Controls | Control | Detail | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **No admin mint** | `mint()` is disabled; shares can only be created through genuine XDC deposits | | **No admin withdraw** | There is no `ownerWithdraw()`; XDC only leaves through user redemptions or validator operations | | **Loss caps** | `reportValidatorLoss()` is capped at 10% per report and 20% per day (configurable via time-lock) | | **Principal separation** | Returning masternode principal is not counted as yield, which prevents artificial exchange rate inflation | | **Reentrancy protection** | All external state-changing functions are protected | | **Reward threshold** | Reward inflows below 1,000 XDC are not immediately synced, preventing dust manipulation | | **No principal-stake slashing** | XDC's slashing mechanism penalizes downtime via \~2h exclusion and missed rewards, but never burns principal stake | *** ## Smart Contract Details | Property | Detail | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Contract** | `PrimeStakedXDC_V3_2.sol` | | **Address** | [`0xDc74c0DaED82ae94486DeeF22991d2F54173c734`](https://xdcscan.com/address/0xDc74c0DaED82ae94486DeeF22991d2F54173c734) | | **Standard** | ERC-4626 (OpenZeppelin) + AccessControl | | **Upgradeability** | **None. Deployed with a regular constructor, no proxy.** The vault logic cannot be modified after deployment. | | **Decimals offset** | 9 (extra share precision) | | **Default masternode stake** | 10,000,000 XDC | | **Default buffer** | 5% of total assets | | **Default governance delay** | 1 day (min 1 minute, max 30 days) | | **Audits** | QuillAudits + Nethermind Security | *** ## Withdrawal Queue Internals When liquidity is constrained the queue absorbs the overflow without disrupting validator operations: * Queued requests **escrow shares** inside the vault. They are not burned until settlement. * Settlement value is computed at processing time, not at enqueue time. The user redeems at the live share rate, not a stale snapshot. * Failed receiver payouts (rare; e.g. contract receivers that revert on payment) are deferred into `pendingQueuedAssets`. Users collect their XDC via `claimQueuedAssets(receiver)` later. * Auto-propose is **blocked while the queue has a backlog**, so the vault doesn't lock more XDC in masternodes while users are waiting to withdraw. * Operator and queue scans are bounded by `operatorScanLimit` and `queueScanLimit` to prevent gas-griefing. → [Withdrawals: Instant vs Queued (user guide)](/products/xdc-liquid-staking/staking-guide/withdrawals-instant-vs-queued) *** ## Migration from V2 Existing V2 psXDC holders migrate to V3 through a dedicated [`PrimeStakedXDC_V3MigrationBridge`](/products/contract-addresses): 1. Approve the bridge to spend your V2 psXDC. 2. Call `migrate(amount, minSharesOut)`. The bridge burns your V2 tokens and the vault mints V3 shares. 3. Slippage protection (`minSharesOut`) prevents unfavourable exchange rates between signing and execution. The migration bridge has its own security controls: time-locked admin handoff, daily withdrawal caps on excess treasury, and disabled direct role changes. On the vault side, migration is gated by `setMigrationBridge(address)` (admin) and `setMigrationInProgress(bool)` (`MIGRATION_MANAGER_ROLE`). Liquidity to back migrated shares is contributed by the migration manager via `fundMigrationLiquidity()`; direct native sends to the vault while migration is in progress are accepted only from the migration manager and are tagged as migration liquidity (they do not inflate `totalAssets`). → [Migration Guide (user-facing)](/products/xdc-liquid-staking/staking-guide/migration) → [Deployed Contracts & Addresses](/products/contract-addresses) # V2 vs V3: What Changed {% hint style="info" %} The live vault is **`PrimeStakedXDC_V3_2`** (`0xDc74…c734`). V2 remains available for stragglers to migrate via [the migration bridge](/products/xdc-liquid-staking/staking-guide/migration). {% endhint %} psXDC has moved from its original custodial contract (V2) to a fully non-custodial, ERC-4626 vault architecture (V3). This page explains what changed, why, and what it means for users and partners. *** ## July 2026: the V3.1 redeploy In July 2026 the V3 vault was redeployed as **V3.1** to restructure how masternode collateral moves into the vault. What users need to know: * **Balances carried over automatically.** A snapshot captured every V3 holder's balance (including psXDC inside XDC NFTs, DEX pools, lending markets, and open limit orders) and the `V31AirdropDistributor` minted the same balances on V3.1. No user action was required. * **Staking, withdrawals, and NFTs work exactly the same.** V3.1 keeps the full ERC-4626 share design, self-service withdrawals, and the FIFO queue. * **Masternode collateral migrates progressively.** The XDC backing the vault is being moved from the legacy masternode fleet into the V3.1 vault on a rolling schedule (roughly one masternode per week). While this completes, the vault serves withdrawals from its on-hand liquidity plus dedicated team funding lanes; larger withdrawals may queue until the next liquidity tranche arrives. Share price (NAV) is protected during this phase; it cannot be written down by the transition mechanics. * **The old V3 token is retired.** Its bridge was cut to a dead address; the token has no remaining function. Everywhere else in this page, "V3" refers to the live V3.1 architecture. The design is identical. *** ## Why Migrate V2 was the first generation of psXDC. It works, but its custodial design creates trust dependencies that limit adoption, particularly as collateral in DeFi lending markets. The core issues: * **Withdrawals require admin approval**: a user requests to withdraw, then the owner must manually approve each request before XDC is released * **Custodial validator staking**: the admin withdrew XDC from the contract and staked it into validators; staking happened on-chain but was entirely admin-controlled, so users had to trust the team to manage their funds * **Owner can mint and withdraw**: the contract has `mint()` and `ownerWithdraw()` functions that give the owner broad control over user funds * **Rewards are manual**: the owner must call `notifyRewardAmount()` to distribute rewards These properties make V2 unsuitable for institutional use or as DeFi collateral, because a single admin key can unilaterally move funds. V3 eliminates all of these trust assumptions. *** ## Architecture Comparison | Aspect | V2 (Custodial) | V3 (Non-Custodial) | | -------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | **Standard** | Custom staking + APY rewards | ERC-4626 tokenized vault | | **Token model** | 1:1 fixed ratio (1 psXDC = 1 XDC) | Share-based exchange rate (increases over time) | | **Reward distribution** | Manual: owner calls `notifyRewardAmount()` | Automatic: exchange rate rises as validator rewards flow in | | **Reward claiming** | Users must manually claim accrued rewards | No claiming; rewards are embedded in share price | | **XDC utilization** | Custodial: admin withdrew XDC and staked with validators manually | Non-custodial: vault stakes directly with masternodes via smart contract, fully verifiable | | **Masternode integration** | Custodial: admin managed validators manually | Direct non-custodial integration with XDC validator contract | | **Upgradeability** | UUPS (owner-controlled upgrades) | **None. `PrimeStakedXDC_V3_2` is non-upgradeable.** Deployed with a regular constructor, no proxy. The vault logic can never be modified. | *** ## Withdrawal Comparison | Aspect | V2 | V3 | | ---------------------- | ---------------------------------------------------- | -------------------------------------------------------- | | **User action** | Call `requestWithdraw()` | Call `redeem()` or `redeemWithQueue()` | | **Admin approval** | Required; owner must call `approveWithdrawRequest()` | Not required; self-service | | **Instant withdrawal** | Not available | Yes, if sufficient liquid XDC exists in the buffer | | **Queue** | Manual admin-managed | Automatic FIFO queue that processes as liquidity returns | | **Queue cancellation** | Not available | Users can cancel pending requests at any time | | **DEX exit** | Available (same in both versions) | Available (same in both versions) | **V2 flow:** Request → Wait for admin approval → Withdraw **V3 flow:** Redeem → Receive XDC instantly (or enter automatic queue if liquidity is low) *** ## Admin Privilege Comparison This is the most significant change. V2 gives the owner sweeping powers. V3 eliminates them. | Capability | V2 | V3 | | ---------------------------------- | ----------------------------------- | ------------------------------------------- | | **Mint new tokens** | Yes, via `mint(address, amount)` | Disabled; `mint()` reverts | | **Withdraw contract funds** | Yes, via `ownerWithdraw(amount)` | No such function exists | | **Set reward rate** | Yes, via `setRewardApy()` | No manual rate; exchange rate is automatic | | **Approve individual withdrawals** | Yes, via `approveWithdrawRequest()` | Not needed; withdrawals are self-service | | **Transfer ownership** | Instant via `transferOwnership()` | Time-locked: schedule → wait → execute | | **Change roles** | N/A (single owner) | Time-locked; all role changes require delay | | **Pause/unpause** | Owner | Admin role | *** ## Reward Model Comparison | Aspect | V2 | V3 | | ---------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | **How rewards enter** | Owner calls `notifyRewardAmount(reward)` with XDC | Validator rewards flow directly into the vault | | **Distribution logic** | Time-based APY: `rewardRate * elapsed / totalStaked` | Asset-based: exchange rate = `totalAssets / totalShares` | | **User experience** | Claim rewards manually from Rewards tab | No claim; share value increases automatically | | **Transparency** | Owner-controlled reward injection | Validator rewards verifiable on-chain via masternode contract | | **Risk** | Owner sets APY and reward duration manually | Exchange rate driven by actual validator performance | | **NFT boost stream** | N/A | `XdcNftBoostHarvester.notifyBoost` feeds a Synthetix-style accumulator inside the NFT vault, claimable separately | *** ## Security Comparison | Feature | V2 | V3 | | ------------------------------- | ----------------------------------------- | ------------------------------------------------------------------ | | **Audit** | QuillAudits | QuillAudits + Nethermind Security | | **Reentrancy protection** | Yes | Yes (OpenZeppelin ReentrancyGuard) | | **Single point of failure** | Yes (single owner key) | No (5 roles + time-locks) | | **Upgradeability** | UUPS proxy | **None; non-upgradeable** | | **Governance delay** | None | 1-day minimum (configurable, max 30 days) | | **Loss caps** | None | Configurable per-report + per-day caps, set via delayed governance | | **Principal tracking** | None | Per-operator and global tracking | | **Admin can drain funds** | Technically yes (`ownerWithdraw`, `mint`) | No; no such functions exist | | **No principal-stake slashing** | Yes (XDC model) | Yes (XDC model) | *** ## Feature-by-Feature Summary | Feature | V2 | V3 | | ---------------------------- | ----------------- | ------------------------------------------- | | Stake XDC | Yes | Yes | | Receive psXDC | Yes (1:1) | Yes (at exchange rate) | | Self-service withdrawal | No | Yes | | Withdrawal queue | Manual | Automatic (FIFO) | | Cancel queued withdrawal | No | Yes | | Masternode staking | Off-chain | On-chain | | Auto-propose masternodes | No | Yes | | Resign masternodes | N/A | Yes (with cooldown) | | Share-based pricing | No | Yes | | Liquidity buffer | No | Yes (configurable, default 5%) | | Time-locked governance | No | Yes (all sensitive changes) | | Role-based access control | No (single owner) | Yes (5 distinct roles) | | Validator loss reporting | No | Yes (capped, operator-aware) | | ERC-4626 compatible | No | Yes | | DeFi composable (collateral) | Limited | Full | | Migration bridge | N/A | Dedicated contract with slippage protection | *** ## What This Means for Users | | Before (V2) | After (V3) | | ------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | **Deposit** | Same: stake XDC, get psXDC | Same, but psXDC is now a yield-bearing vault share | | **Rewards** | Claim manually from Rewards tab | Automatic: no action needed, share value grows | | **Withdraw** | Request and wait for admin approval | Self-service: instant if liquidity available, queued otherwise | | **Trust** | Trust the admin not to misuse `mint()` or `ownerWithdraw()` | Trust the code: no admin can move your funds, and the contract itself cannot be upgraded | | **DeFi use** | Hold, trade, or stake in NFTs | Same + usable as collateral in lending protocols | | **Migration** | N/A | One-time: approve + migrate via the [V3 migration bridge](/products/xdc-liquid-staking/staking-guide/migration) | *** ## What This Means for Partners * **psXDC becomes viable as DeFi collateral**: the non-custodial design and ERC-4626 compliance make it suitable for lending markets and institutional integration * **Reduced counterparty risk**: no single admin key can affect user balances * **Transparent validator economics**: masternode operations are verifiable on-chain * **Predictable governance**: all changes are time-locked and visible before they take effect * **Standard interface**: ERC-4626 is the same vault interface used by major DeFi protocols, reducing integration effort → [V3 Architecture Details](/products/xdc-liquid-staking/v3-architecture) → [Institutional Overview](/for-partners/institutional) # How Rewards Work (NAV / share price) PrimeStaking V3 is a fully on-chain, ERC-4626 staking vault. Rewards are not paid through a manual `claim` flow. They are embedded directly in the **psXDC share price**. This page explains how the rate accrues and how the NFT boost layer sits on top. *** ## Two layers of yield ``` base yield (~5.5%) boost slice (up to ~1.5%) │ │ ▼ ▼ shares × NAV(t) appreciation + Synthetix-style accumulator (every psXDC holder gets this) (only XDC NFT holders get this) ``` | Layer | Where it lives | Who earns it | How you receive it | | ------------- | ------------------------------------------ | --------------------------------------------------- | ------------------------------------------------------------------- | | **Base NAV** | `PrimeStakedXDC_V3_2` vault share price | Every psXDC holder | Automatic: share price rises as validator rewards accrue. No claim. | | **NFT Boost** | `XdcNftStakingVault` Synthetix accumulator | Only NFTs that have psXDC shares staked inside them | Claimed from the NFT detail page in the app. | *** ## Base layer: share-price growth When XDC validator rewards flow back into the vault, `totalAssets()` increases while the total share supply stays the same. The vault's exchange rate (`totalAssets / totalShares`) goes up, so every psXDC share becomes worth more XDC. {% hint style="info" %} **V3.2 permanent-ledger model.** In V3.2 the operations manager credits rewards through a dedicated reward lane (`distributeRewards`), which raises the share price for every holder. Rewards accrue **at any backing level** - there is no "fully backed" gate. An optional, hard-capped protocol fee (0% by default, max 20%) can be skimmed per distribution. The share price only ever moves up through this lane; there is no code path that writes it down outside of a rate-limited, risk-manager-only validator-loss report. {% endhint %} | Aspect | Detail | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Target APY | \~5.5% | | Mechanism | Exchange rate appreciation | | When you receive it | The rate **steps up when the XDC Network pays masternode rewards into the vault** — typically the first days of each month, on the network's own schedule | | User action required | None. There is no "claim rewards" button | {% hint style="warning" %} **A flat exchange rate between payouts is normal.** The XDC Network pays masternode rewards roughly **once a month** (usually within the first days of the month), not block-by-block. Between those payments the psXDC rate stays flat — that is the network's payment cadence, not missing rewards. The \~5.5% APY is the annualized result of those monthly steps. Immediately after a migration or while masternodes are in the network's standby/proposal cycle, the first step-up lands on the **next** monthly payment run after the nodes are active. {% endhint %} **Example.** Stake 1,000 XDC when the exchange rate is `1.00`. You receive 1,000 psXDC shares. Six months later the rate is `1.025`. You burn your 1,000 shares and the vault returns **1,025 XDC**. Your 25 XDC of yield was inside the price the whole time. This is the same model used by Aave aTokens, Compound cTokens, and Lido wstETH. *** ## NFT boost: additional slice for stakers XDC NFTs stack a second yield on top of the base NAV. The protocol's [`XdcNftBoostHarvester`](/products/xdc-staking-nfts/boost-harvester) periodically pushes XDC into the NFT vault via `notifyBoost`. That XDC is converted to psXDC v3 shares inside the vault and parked as `boostReserve`. A Synthetix-style accumulator distributes the reserve to staked NFTs in proportion to their **weight**: ``` weight = stakedShares × (rarityMultiplier + level + lockBonus) ``` | Component | Effect on weight | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `stakedShares` | More psXDC staked inside the NFT → bigger slice | | `rarityMultiplier` | Plentiful (lowest) → Handcrafted (highest); set at mint, immutable | | `level` | Increases when the NFT levels up via merge | | `lockBonus` | Added when the NFT is locked, sized by the chosen lock tier (30/90/180/365 days). **Ends automatically when the lock expires** and can be renewed by re-locking. | When you `claim` from an NFT, the accumulator settles your pending boost and pays it out in XDC. | Aspect | Detail | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Target APR band | \~0.25% (Plentiful unlocked) → \~1.5% (Handcrafted locked) | | Mechanism | `notifyBoost(x)` increments `rewardPerWeightStored`; each NFT's `earned = info.shares × (rewardPerWeightStored − info.rewardIndex) × weight / 1e18` | | When you receive it | When you call `claim` on the NFT | | User action required | Yes: claim from the NFT detail page, or it settles automatically on any other state-changing action (stake more, lock, merge, withdraw) | The boost cadence depends on how often the harvester feeds the accumulator; see [Boost Harvester (technical)](/products/xdc-staking-nfts/boost-harvester) for the full picture. *** ## Combined targets | Position | Base NAV (floor) | + Boost slice (when flowing) | Combined target | | ---------------------------- | ---------------- | ---------------------------- | ----------------------- | | Plain psXDC (no NFT) | \~5.5% | None | **\~5.5%** | | psXDC inside an unlocked NFT | **\~5.5%** | \~0.25% | **\~5.5% → \~5.75%** | | psXDC inside a locked NFT | **\~5.5%** | up to \~1.5% | **\~5.5% → up to \~7%** | {% hint style="info" %} The floor for every staked psXDC (whether you hold it directly, in an unlocked NFT, or in a locked NFT) is the **base \~5.5%**. That layer is automatic. The boost slice (`~0.25%` → `~1.5%`) is an additional stream that depends on harvester cadence and your NFT's weight; when the stream is paused or sparse, you continue to earn the base. {% endhint %} The exact boost slice depends on your NFT's rarity, level, and lock status relative to the rest of the vault, and on how much XDC the harvester has fed recently. The vault publishes `BoostNotified` events so the UI can show a trailing 30-day boost APR alongside the static targets. *** ## Why no claim button for liquid staking The V2 product distributed rewards by having the owner periodically call `notifyRewardAmount` and required users to call `claim` to collect their share. V3 removes both: * **No `notifyRewardAmount`**: validator rewards flow directly into the vault, so the exchange rate updates automatically. * **No `claim`**: your reward is *already inside the share*. When you redeem the share, you receive both the principal and the accrued reward in one transaction. The boost layer keeps its `claim` flow because it is a **separate** XDC stream layered on top of the share, not an internal accrual. → [Understanding Share Price](/products/xdc-liquid-staking/staking-guide/how-to-claim-rewards) → [V2 vs V3: What Changed](/products/xdc-liquid-staking/v2-vs-v3) # Staking Guide Step-by-step instructions for using XDC Liquid Staking V3 on [primestaking.xyz](https://primestaking.xyz). | Guide | What You'll Learn | | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | [How to Stake XDC](/products/xdc-liquid-staking/staking-guide/how-to-stake-usdxdc) | Connect your wallet, deposit XDC, receive psXDC shares | | [Withdrawals: Instant vs Queued](/products/xdc-liquid-staking/staking-guide/withdrawals-instant-vs-queued) | When `redeem` is instant, when it goes through the FIFO queue, and how to `claimQueuedAssets` | | [Request Withdrawal](/products/xdc-liquid-staking/staking-guide/request-withdrawal) | Step-by-step UX for burning psXDC shares back into XDC | | [Migrate V2 psXDC → V3](/products/xdc-liquid-staking/staking-guide/migration) | Move your V2 psXDC balance into V3 shares via the migration bridge | | [Position & Rewards History](/products/xdc-liquid-staking/staking-guide/rewards-history) | Read your position, the share price timeline, and your stake/withdraw history | | [Understanding Share Price](/products/xdc-liquid-staking/staking-guide/how-to-claim-rewards) | Why there is no "Claim Rewards" button in V3 and how to read your accrued value | > Migrating from the legacy **pstXDC** token (not V2 psXDC)? That migration was completed years ago and is now archived under [Legacy (V2, historical)](/legacy-v2-historical/pstxdc-migration). # How to Stake XDC ### Prerequisites * An XDC-compatible wallet (e.g., MetaMask configured for XDC Network). * XDC tokens in your wallet. *** ### Step 1 - Connect Your Wallet Go to [primestaking.xyz](https://primestaking.xyz) and click **Connect Wallet**. Approve the connection in your wallet.
*** ### Step 2 - Navigate to XDC Liquid Staking Open [primestaking.xyz/xdc-liquid-staking](https://primestaking.xyz/xdc-liquid-staking/overview) and enter the amount of XDC you want to stake. The app previews how many psXDC shares you will receive at the current exchange rate. This is **not** a fixed 1:1; once the vault has accrued rewards, each share is worth more than 1 XDC.
*** ### Step 3 - Confirm the Transaction Review the previewed share amount and click **Stake**. The app calls `stake()` on the V3 vault with your XDC as `msg.value`. Confirm the on-chain transaction in your wallet. *** ### Step 4 - Receive psXDC Shares Once confirmed, psXDC shares are minted to your wallet at the live exchange rate. From this moment your shares are appreciating: rewards accrue automatically through the share price, with no claim button to press. You can now hold psXDC, transfer it, trade it on a DEX, use it as DeFi collateral, or deposit it into an [XDC NFT](/products/xdc-staking-nfts) for the additional boost slice. *** ### Adding psXDC to Your Wallet If psXDC doesn't appear in your wallet automatically, click the **Add psXDC Token** button in the app.
Alternatively, add it manually as a custom token: **Contract address (V3):** [`0xDc74c0DaED82ae94486DeeF22991d2F54173c734`](https://xdcscan.com/address/0xDc74c0DaED82ae94486DeeF22991d2F54173c734) > Note: the **V2** psXDC token address (`0x9B8e12b0BAC165B86967E771d98B520Ec3F665A6`) is different. If you stake fresh XDC you will receive V3 shares only. If you still hold V2 tokens, see [Migrate V2 psXDC → V3](/products/xdc-liquid-staking/staking-guide/migration). ![](https://3449129859-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaNL9MtQF319bzNT2KTNC%2Fuploads%2Fgit-blob-b6d75611a6c7eed3d2080af11ba28f3720a6f417%2Fimage.png?alt=media) ![](https://3449129859-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaNL9MtQF319bzNT2KTNC%2Fuploads%2Fgit-blob-142cb7b2b4981602bee83219c8ca0484feb27c4f%2Fimage.png?alt=media) ![](https://3449129859-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaNL9MtQF319bzNT2KTNC%2Fuploads%2Fgit-blob-0783723a92a0b927cebde00a25f12a1702fde508%2Fimage.png?alt=media)
# Withdrawals: Instant vs Queued Every withdrawal on V3 goes through `redeemWithQueue` (or `withdrawWithQueue`). The vault automatically picks the **fastest path your balance and the buffer allow**: no admin approval, no per-user setting to flip. {% hint style="info" %} **During the V3.1 collateral transition** (masternodes moving into the vault roughly weekly), instant withdrawals are served from the vault's free liquidity, and the FIFO queue is backed by dedicated team funding that is ring-fenced for queued requests. New stakers' deposits are never trapped, and queued users are paid as each liquidity tranche arrives. Once the transition completes, the standard buffer model below applies in full. {% endhint %} {% hint style="warning" %} **If your request is queued right now:** several masternodes are unstaking at the XDC validator contract specifically to cover every queued withdrawal. The network enforces its own unbonding period (`candidateWithdrawDelay`, \~35 days from resignation under typical block times); as that XDC lands in the vault, the FIFO pays requests out **in order** and your request becomes claimable in the app. Every queued request is fully backed on-chain — no action is needed from you while you wait, and you can cancel at any time to get your psXDC back. {% endhint %} *** ## The choice the vault makes for you ``` User calls redeemWithQueue(shares, receiver) │ ▼ ┌────────────────────────┐ │ Does the buffer hold │ yes ◄───┤ enough XDC to cover ├───► no │ shares × NAV? │ └────────────────────────┘ │ │ ▼ ▼ Instant redeem in this tx Escrow shares, enqueue FIFO │ │ ▼ ▼ Receive XDC immediately Wait → call claimQueuedAssets later ``` "Enough XDC" means the vault's **unencumbered liquidity**: its native balance minus what is already earmarked for the queue and for failed payouts (V3.2 removed the old percentage-based `bufferBps` buffer). When `maxRedeem(you)` covers the shares you're redeeming, the path is instant; otherwise the queue kicks in. Practically: while a queue backlog exists, most free liquidity is earmarked, so expect the queued path during those periods. *** ## Path A: Instant redeem When liquidity is sufficient: * Your psXDC shares are **burned immediately**. * XDC is sent to your `receiver` in the same transaction. * No queue entry is created. Use cases: routine withdrawals while the vault has free liquidity, partner integrations expecting synchronous settlement. *** ## Path B: Queued redeem When liquidity is constrained: * Your psXDC shares are **escrowed inside the vault** (not burned). * A `WithdrawalQueued(requestId, owner, shares)` event is emitted. * The request enters the global FIFO queue, ordered by enqueue timestamp. ### How the queue is drained Anyone can call `processWithdrawalQueue(maxRequests)`, which: 1. Walks the FIFO, oldest first. 2. For each request, checks the current liquid XDC against the request's share value at the **current** exchange rate. 3. If the vault can pay, it does: it burns the escrowed shares and sends XDC to the original receiver. 4. If the receiver payout fails (e.g. a smart contract receiver that reverts on payment), the XDC is deferred into `pendingQueuedAssets[receiver]`. The user collects it later via `claimQueuedAssets`. Auto-propose (the function that pushes new XDC into masternodes) is **blocked while there is any backlog**, so the protocol prioritizes outgoing user redemptions over locking up more XDC. ### What replenishes liquidity The vault's liquid balance grows from: * **New user deposits** (any `stake` adds XDC to the buffer). * **Validator reward inflows** (rewards flow back into the vault and bump tracked assets). * **Masternode resignation**: when a proposer resigns a masternode, the XDC returns to the vault after the network's `candidateWithdrawDelay` (\~35 days under typical block times). * **Collateral-transition funding** (V3.1): while the legacy masternode fleet is being moved over, the team injects liquidity tranches on a rolling schedule; funding earmarked for the withdrawal queue is reserved for queued requests and cannot be consumed by instant withdrawals. For very large withdrawals where the protocol doesn't already have a buffer + recent rewards sufficient to cover, the resignation timeline is the upper bound on settlement. ### Queued amounts are fixed — they don't earn while waiting The XDC amount of a queued request is locked in at the exchange rate of the moment you queued (`previewRedeem` at enqueue time). Reward distributions that land while you wait do **not** increase your payout — from the vault's perspective your exit price is already settled; only the timing of payment is pending. This is standard exit-queue design: fixing the liability at request time keeps the vault's solvency accounting exact. Because `cancelQueuedWithdrawal` returns your **shares** (not the fixed amount), cancelling after a rate increase and re-queueing captures the appreciation — but it sends you to the back of the FIFO. At \~5.5% APY that trade-off is roughly 0.45% per month of queue time, so it is rarely worth it unless you were far from the head anyway. ### The queue is public — and has an ETA Every queued request is public on-chain data, and the app's **Queue Explorer** (My Positions page) shows the whole FIFO: each request's position, size, and owner wallet, plus the total queued. Your own requests are highlighted. The explorer also shows an **expected completion date** and, when the team has published the unbonding schedule, a per-request **estimated payout date**. XDC masternodes return principal in **10M XDC lumps**, so the queue drains in steps: each request's estimate is the arrival date of the lump that covers its position. **How the team dates each step**: the XDC validator contract enforces `candidateWithdrawDelay` = 1,296,000 blocks after a resignation. At the nominal 2-second block time that is 30–31 days, but real block times stretch it to roughly **35–38 days**, so published dates include a \~+5 day buffer on top of the nominal figure. These are good-faith estimates for planning, **not** on-chain guarantees. What the contract does guarantee: requests are paid strictly first-in-first-out as XDC arrives, and every request is fully backed. ### Cancelling You can call `cancelQueuedWithdrawal(requestId)` at any time before settlement. The escrowed psXDC shares are returned to your wallet; no XDC moves and nothing is lost. ### Self-claim with `claimQueuedAssets` If you ever see a queued request that says "ready to claim" in the app, that means the queue processed your request but the XDC ended up in `pendingQueuedAssets` (e.g. your receiver bounced). Calling `claimQueuedAssets(receiver)` sweeps every XDC waiting for you into your wallet. *** ## How the app uses these paths The PrimeStaking UI always calls `redeemWithQueue`; it never picks the path manually. Instead it shows you, before you sign, whether the transaction will: * **"Withdraw complete"**: buffer is enough, this will settle now. * **"Withdrawal queued, claim from My Positions when ready"**: buffer is not enough; the request will go into the FIFO. In Lite Mode the **withdraw tab** uses the same logic. The **queue list** on the Withdraw and My Positions pages shows your active queued requests with cancel / claim controls. *** ## Why this design | V2 behaviour | V3 behaviour | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | Every withdrawal required admin approval | No admin approval at any point | | The owner picked which requests to honor | FIFO is enforced on-chain: first in, first out | | Withdrawals could be paused unilaterally by the admin | Auto-propose is blocked while the queue is non-empty, prioritizing exits over new validator locks | | You had to wait the full validator-queue time even when liquidity was available | Instant when possible, queued only when the buffer is insufficient | | Failed payouts could lose XDC | Failed payouts defer into `pendingQueuedAssets` and the user self-claims with `claimQueuedAssets` | → [Request Withdrawal (walkthrough)](/products/xdc-liquid-staking/staking-guide/request-withdrawal) → [Smart Contract Reference](/products/xdc-liquid-staking/smart-contract-functions) → [V3 Architecture](/products/xdc-liquid-staking/v3-architecture) # Request Withdrawal (walkthrough) V3 withdrawals are self-service: there is no admin approval step and no fixed queue time. Every withdrawal goes through `redeemWithQueue`, which automatically picks the fastest path your balance and the vault's liquidity allow. {% hint style="info" %} For the full breakdown of how the instant vs queued paths choose themselves, see [Withdrawals: Instant vs Queued](/products/xdc-liquid-staking/staking-guide/withdrawals-instant-vs-queued). {% endhint %} *** ## Steps 1. Go to [primestaking.xyz/xdc-liquid-staking](https://primestaking.xyz/xdc-liquid-staking/overview). 2. Open the **Withdraw** section (or use the **Lite Mode** withdraw tab). 3. Enter the amount of **psXDC shares** you want to redeem. The app shows you, in real time: * The XDC you will receive based on the current exchange rate. * Whether the withdrawal will settle **instantly** or **enter the queue**, based on the vault's liquid buffer. 4. Click **Withdraw** and confirm the transaction. Under the hood the app calls `redeemWithQueue(shares, receiver)`. *** ## What happens next ### If the vault has enough buffer liquidity The redemption settles in the **same transaction**. You receive XDC immediately. No queue entry is created, nothing else for you to do. ### If buffer liquidity is constrained Your psXDC shares are escrowed inside the vault and a request is added to the FIFO queue. The withdrawal **does not have a fixed time**. It is settled as soon as enough liquidity returns from: * New user deposits, * Validator reward inflows, or * Masternode resignation principal returning to the vault after the XDC Network's `candidateWithdrawDelay` (\~35 days under normal block times). You can monitor the queue at any time from the **My Positions** page. When your request is processed, your XDC lands either directly in your wallet or in the vault's `pendingQueuedAssets` bucket. If it lands in `pendingQueuedAssets` (because the original payout failed for any reason), you collect it by calling `claimQueuedAssets`. The app exposes this as a **Claim** button on the queued withdrawal entry. You can also cancel a queued request before it settles. The vault returns the escrowed psXDC shares to your wallet, and no XDC moves. *** ## Why a queue exists at all The vault keeps most of the XDC working in masternodes earning yield, and only holds a small percentage (the **buffer**, default 5%) liquid for instant redemptions. When demand to withdraw exceeds the buffer, the queue ensures that everyone is served fairly in FIFO order without forcing the protocol to disrupt active validators. The queue is preferred over the previous "request and wait for admin approval" model because: * No admin signature is needed at any point. * You can cancel at any time and get your shares back. * Settlement is automatic: anyone can call `processWithdrawalQueue` to push the queue forward. → [Withdrawals: Instant vs Queued](/products/xdc-liquid-staking/staking-guide/withdrawals-instant-vs-queued) → [Smart Contract Reference](/products/xdc-liquid-staking/smart-contract-functions)
# Migrate V2 psXDC → V3 {% hint style="success" %} **Held psXDC (V3 or V3.1) before the July 2026 V3.2 upgrade? You're already done.** Each redeployment mirrored every holder's balance 1:1 onto the new contract via a snapshot airdrop, including balances inside XDC NFTs, DEX liquidity pools, and lending markets, which were credited to their underlying owners. No transaction, claim, or approval was needed. The app already shows your V3.2 balance. {% endhint %} This page is for users who still hold **V2 psXDC** (the original 1:1 token at [`0x9B8e…65A6`](https://xdcscan.com/address/0x9B8e12b0BAC165B86967E771d98B520Ec3F665A6)). Your V2 balance does **not** automatically appear in V3.2. You migrate by sending V2 tokens through the dedicated migration bridge, which burns the V2 and mints V3.2 shares in one transaction. {% hint style="info" %} Migration is optional at any individual point in time, but V3.2 is the only version with self-service withdrawals, share-price reward accrual, and NFT-boost compatibility. See [Legacy (V2, historical)](/legacy-v2-historical/legacy). {% endhint %} *** ## What the bridge does ``` User v2 → V3.2 Migration Bridge psXDC V3.2 vault │ │ │ │ approve(bridge, amount) │ │ │ ───────────────────────────►│ │ │ │ │ │ migrate(amount, minSharesOut) │ │ ───────────────────────────►│ │ │ │ burns V2 psXDC │ │ │ vault.migrate(receiver, …) ──►│ │ │ │ mints V3.2 shares │ ◄─────────────────── V3.2 shares (≥ minSharesOut) ◄───────────│ ``` * **Burns your V2 psXDC** so each V2 token can only be migrated once. * **Mints V3.2 shares** to your address using the vault's `migrate(...)` function, which is restricted to the configured bridge. * **Slippage protection** via `minSharesOut` so the migration reverts if the exchange rate changed unfavourably between the time you signed and the time the transaction settled. * **Atomic**: if any step fails (slippage exceeded, etc.) the whole transaction reverts and you keep your V2 tokens. The V2 → V3.2 bridge is [`0x313e8d6Ad3D16be6318dF2AF5a54A87Aea42c280`](https://xdcscan.com/address/0x313e8d6Ad3D16be6318dF2AF5a54A87Aea42c280). Prior-generation bridges are retired; the app never routes to them. Right after a major upgrade the vault's `migrationBridge` is re-pointed behind a 24-hour governance timelock, so V2 migration can be briefly unavailable until that matures - the app shows a notice and disables the button in the meantime. *** ## Steps 1. Go to the migration page at [primestaking.xyz/xdc-liquid-staking/migration](https://primestaking.xyz/xdc-liquid-staking/migration). (The app also shows a migration banner on the main staking dashboard.) 2. Enter the amount of V2 psXDC you want to migrate. The app previews the V3.2 shares you will receive and applies a default slippage tolerance of **0.5%**, which you can adjust. 3. Click **Approve** to allow the bridge to spend that amount of V2 psXDC. Confirm in your wallet. 4. Click **Migrate**. The app calls `migrate(amount, minSharesOut)` on the bridge. Confirm the transaction. 5. After the transaction settles, your V3.2 share balance increases by at least `minSharesOut`, your V2 balance decreases by `amount`, and you can use the shares like any newly-staked position (transfer, redeem instantly or via the queue, deposit into a V3 NFT). *** ## Exchange rate and slippage The V3.2 vault uses share-based pricing (`totalAssets / totalShares`), so each migrated V2 psXDC mints a share count proportional to the current exchange rate: * If the exchange rate is `1.00`, migrating `1,000` V2 psXDC mints `1,000` V3.2 shares. * If the exchange rate has appreciated to `1.05`, the same migration mints `~952.38` shares (each share is now worth more XDC). The default 0.5% slippage tolerance covers small mid-transaction movement. If you set `minSharesOut` too high (e.g. expecting yesterday's rate) and the rate has since grown, the migration will revert. Adjust slippage and retry. *** ## What happened to old V3 psXDC? The pre-July-2026 V3 token ([`0x98D9…C4Ba`](https://xdcscan.com/address/0x98D916F5773Ac0482b49856f2659d6c32114C4Ba)) was superseded in full: * A **snapshot** captured every holder's balance, with special handling so nothing was missed: psXDC held inside XDC NFTs stayed with the NFT vault, DEX LP positions were unwound pro-rata to the liquidity providers, lending-market deposits were credited to depositors, and open limit orders were returned to their makers. * The **`V31AirdropDistributor`** minted those exact balances on V3.2 in the vault's final state, then was permanently finalized. * The old V3 contract's bridge was cut to a dead address; old V3 tokens have no remaining function and cannot be migrated or redeemed. Your value lives in V3.2. If you believe a balance was missed, contact ; the full snapshot and airdrop are auditable on-chain via the distributor contract. *** ## What happens to V2 after you migrate * The V2 contract continues to exist for users who have not migrated. * Your migrated V2 tokens are **burned** and cannot be re-issued. * V2-side actions only apply to whatever V2 balance you have left. → [Withdrawals: Instant vs Queued (V3.2)](/products/xdc-liquid-staking/staking-guide/withdrawals-instant-vs-queued) → [V2 vs V3: What Changed](/products/xdc-liquid-staking/v2-vs-v3) → [Historical pstXDC → psXDC migration (legacy)](/legacy-v2-historical/pstxdc-migration) # Position & Rewards History V3 does not have a "rewards claim" history in the V2 sense, because rewards are baked into the share price and don't need to be claimed. Instead the app shows you the **history of your position**: every stake / migrate / withdraw event, and the exchange-rate trajectory over time so you can see your accrued value. *** ## How to View 1. Go to [primestaking.xyz/xdc-liquid-staking](https://primestaking.xyz/xdc-liquid-staking/overview). 2. Open the **My Positions** section. You'll see: * Your current psXDC share balance. * The current XDC value of that balance at the live exchange rate. * The cumulative XDC you've earned since your first stake (computed as `convertToAssets(balance) − netDeposits`). 3. Open the **Activity Log** for the per-transaction history: stakes, deposits, queued withdrawals, claims, and migrations. Each row links to the underlying transaction on XDCScan.
*** ## NFT boost history If you also hold XDC NFTs, the boost slice (which **is** claimed) appears separately: * The NFT detail page shows the pending boost amount. * The Activity Log lists every `ClaimEvent`, `BoostNotification`, and weight-changing action (stake, lock, merge, withdraw). → [Understanding Share Price](/products/xdc-liquid-staking/staking-guide/how-to-claim-rewards) → [Reward Model: Base NAV + Boost](/products/xdc-staking-nfts/xdc-nft-staking-reward-system) # Understanding Share Price {% hint style="info" %} There is **no "Claim Rewards" button** for XDC Liquid Staking in V3. Rewards accrue automatically through the psXDC share price: your shares simply become worth more XDC over time. This page explains why and how to read the value of your position. {% endhint %} If you are looking for the **NFT boost** claim flow (a separate XDC stream layered on top of the share), see [Reward Model: Base NAV + Boost](/products/xdc-staking-nfts/xdc-nft-staking-reward-system). If you are looking for the legacy V2 manual claim flow, see [Legacy (V2, historical)](/legacy-v2-historical/legacy). *** ## How rewards accrue in V3 The V3 vault is an ERC-4626 share contract. When validator rewards flow in, the vault's `totalAssets` increases but the total psXDC share supply does not, so the exchange rate `totalAssets / totalShares` goes up. ``` Day 0: 1,000 XDC deposited → 1,000 psXDC minted (rate = 1.000) Day 30: validator rewards flow in → totalAssets increases → rate = 1.0037 Day 365: cumulative rewards ≈ 5.5% → rate = 1.045 Burn 1,000 psXDC on day 365 → receive 1,045 XDC ``` Your psXDC balance never changes from rewards. The **value** of your psXDC changes. This is exactly the same model Aave aTokens, Compound cTokens, and Lido wstETH use. {% hint style="warning" %} **The rate moves in monthly steps, not continuously.** The XDC Network pays masternode rewards roughly once a month — usually within the first days of the month. The psXDC rate stays flat between those payments and steps up when each one lands in the vault. Seeing `1.00000` for days or weeks after staking (or after a migration, while nodes complete the network's standby/proposal cycle) is expected behavior, not a missed payout. {% endhint %} *** ## Where to see your accrued value The app surfaces this in two places: * **Overview / Lite dashboard:** shows your psXDC share balance, its current XDC value at the live exchange rate, and the implied amount earned since you staked. * **Position & Rewards History:** shows the exchange-rate timeline and your individual stake/withdraw events. You can also read it directly from the vault contract: ``` sharesYouHold = balanceOf(yourAddress) xdcYouCouldRedeemNow = convertToAssets(sharesYouHold) ``` The difference between `xdcYouCouldRedeemNow` and the XDC you originally deposited is your accrued yield. There is nothing to claim; it is already inside the share. *** ## Realizing your rewards Because rewards are baked into the share, you realize them whenever you do **any** of the following: * **Redeem** psXDC for XDC: you receive XDC at the current (higher) exchange rate. * **Sell** psXDC on a DEX: the market price reflects the appreciating NAV. * **Transfer** psXDC to another wallet: the recipient inherits the appreciated share and any future appreciation. There is no "leave rewards on the table" risk, because rewards belong to whoever holds the share at the moment of redemption. *** ## What if I'm using my psXDC inside an XDC NFT? The base NAV continues to accrue while your psXDC is staked inside an NFT. When you withdraw shares from the NFT, you get back the same share count, but each share is worth more XDC than when you deposited. The **boost slice** is the additional XDC the NFT vault distributes via the `XdcNftBoostHarvester`. That stream **does** have a claim button: it accumulates inside the NFT and you collect it from the NFT detail page (or it settles automatically on any state-changing NFT action). → [Reward Model: Base NAV + Boost](/products/xdc-staking-nfts/xdc-nft-staking-reward-system) → [Position & Rewards History](/products/xdc-liquid-staking/staking-guide/rewards-history) # Referral Program Earn a share of the protocol fee generated by the people you invite to stake. Share your invite link. When someone stakes XDC for the first time through your link, they become your referral - permanently and on-chain - and you earn a share of the protocol fee their staking generates, for as long as they stay staked. *** ## How it works 1. **Get your link.** Connect your wallet on the [Referral page](https://primestaking.xyz/xdc-liquid-staking/referral) and copy your personal invite link (`primestaking.xyz/xdc-liquid-staking?ref=`). 2. **They stake through it.** When an invitee opens your link and makes their **first** stake (at least the minimum bind amount, currently **100 XDC**), the `ReferralRegistry` binds you as their referrer in the same transaction that deposits their XDC. The binding is one-time and immutable. 3. **You earn a fee share.** Each epoch, your reward is a share of the protocol fee generated by your referees' staked balances, proportional to how much they staked and for how long. 4. **You claim.** Epoch rewards are published as an on-chain Merkle distribution (`ReferralRewards`); claim yours from the Referral page whenever you like. There is no expiry. *** ## How earnings are calculated For each epoch: ``` your payout = referralShare × protocolFeeCollected × (your referees' time-weighted psXDC balance ÷ total time-weighted supply) ``` * **Time-weighted** means balance multiplied by how long it was held during the epoch - more staked, longer staked, more earned. * The payout table is computed from on-chain data and published as a Merkle root; the contract only ever pays what the posted root says and can never be posted underfunded. *** ## Why extra wallets gain nothing Referral payouts scale with **referred capital and time only**. Splitting the same capital across many wallets earns exactly what one wallet earns - there are no signup or per-wallet bonuses anywhere. Referring your own second wallet just returns a small slice of the fee your own stake generated (always less than the fee itself), so the protocol never pays out more than it collected. This makes the program safe to run openly. *** ## Contracts | Contract | Address | Role | | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `ReferralRegistry` | [`0x9765BE3fd9e0d450bD46Ef2A30A0Feb4B15616B3`](https://xdcscan.com/address/0x9765BE3fd9e0d450bD46Ef2A30A0Feb4B15616B3) | Binds one immutable referrer per wallet on the first stake; forwards the stake to the vault. Minimum bind: 100 XDC. | | `ReferralRewards` | [`0xD910E7E0dC457Ccd425E9a5cF716b0F6B7045549`](https://xdcscan.com/address/0xD910E7E0dC457Ccd425E9a5cF716b0F6B7045549) | Epoch Merkle distributor. Roots are immutable per epoch and must be fully funded before posting; unclaimed liability can never be swept. | Both contracts are **non-upgradeable** and never custody user principal - the registry forwards deposits straight to the vault (shares mint to the staker), and the distributor only holds each epoch's referral-fee allocation. → [How Rewards Work](/products/xdc-liquid-staking/xdc-staking-rewards) → [Deployed Contracts & Addresses](/products/contract-addresses) # Bridge psXDC to Other Chains psXDC is native to the XDC Network, but you can bridge it to **Base**, **Arbitrum**, **BNB Chain**, and **HyperEVM** to put it to work in DeFi there — lending it on [PrimeFi](https://primefi.xyz), providing liquidity, or simply holding it on the chain where the rest of your portfolio lives. Bridging uses [LayerZero V2](https://layerzero.network), not a third-party custodian. See [Multichain psXDC: DeFi Opportunities](/products/xdc-liquid-staking/multichain-opportunities) for what you can do with psXDC once it is bridged. {% hint style="success" %} **Your stake keeps earning while it is bridged.** psXDC is non-rebasing: your balance stays the same number, but each psXDC is redeemable for more XDC over time as validator rewards compound into the vault share price. Bridging does not pause or forfeit that yield — you capture it when you bridge back. {% endhint %} ## How to bridge (step by step) The Bridge page is at [primestaking.xyz/xdc-liquid-staking/bridge](https://primestaking.xyz/xdc-liquid-staking/bridge). 1. **Connect your wallet.** The page works from any of the five supported networks; it will ask your wallet to switch when needed. 2. **Pick the route.** Choose the source chain under *From* and the destination under *To* (routes always run through XDC: XDC ↔ Base/Arbitrum/BNB/HyperEVM). The circular arrow button flips the direction. Clicking a chain card in the balance strip below also selects it as the source. 3. **Enter the amount** (or press *Max*). The LayerZero fee quotes itself automatically and is shown in the route details, along with the estimated delivery time. 4. **Press Bridge.** * Bridging *out of XDC* for the first time asks for one extra approval transaction (the lockbox needs permission to hold your psXDC). * The bridge transaction itself carries the LayerZero fee as native gas (XDC when leaving XDC; ETH/BNB/HYPE when coming back). 5. **Track delivery.** A tracker card appears with a progress bar and a *LayerZero Scan* link. Delivery normally takes **2–5 minutes** (four independent verifiers must each confirm 20 source-chain blocks). The page detects arrival automatically and refreshes your balances. ### Fees | What | Who charges it | Rough size | | --------------------- | ------------------------------------- | --------------------------------------------------- | | LayerZero message fee | LayerZero (DVNs + executor) | a few XDC leaving XDC; small ETH/BNB/HYPE returning | | Bridge fee / spread | **None** — PrimeStaking takes nothing | 0 | | Amount received | 1:1 | what you send is what arrives | ## How it works (lockbox) psXDC has a single, canonical supply. When you bridge out, your real psXDC is **locked** in the `PsxdcOFTAdapter` on XDC and an equal amount of psXDC is **minted** on the destination chain. Bridging back **burns** the destination psXDC and **unlocks** the original on XDC. Total psXDC across all chains never changes. ``` XDC: [ your psXDC ] --lock--> PsxdcOFTAdapter (holds the real shares) | LayerZero message (4 DVNs verify) Base/Arb/BSC/HyperEVM: v PsxdcOFT --mint 1:1--> [ your psXDC ] ``` The psXDC token contract is the **same address on every destination chain**: `0x98D916F5773Ac0482b49856f2659d6c32114C4Ba`. ## What you can and cannot do with bridged psXDC | On XDC | On Base / Arbitrum / BSC / HyperEVM | | --------------------------------- | -------------------------------------------------------------------------- | | Stake / unstake through the vault | No — bridge back to XDC to unstake | | Deposit into XDC NFTs for boosts | No — NFTs are XDC-only by design | | Count toward the referral program | No — referral reads balances on XDC | | Hold, transfer, DEX-LP | Hold, transfer, DEX-LP, **use as collateral on PrimeFi** (Base & HyperEVM) | To use any PrimeStaking feature (unstaking, NFT boosts, referrals), bridge your psXDC back to XDC first. ## Seeing your yield on other chains A wallet on Base/Arbitrum/BSC/HyperEVM shows a fixed psXDC balance — the growth is in the **redemption rate**, not the count. PrimeStaking publishes that rate to each chain through the [psXDC rate oracle](/products/xdc-liquid-staking/psxdc-rate-oracle); the app's Bridge page shows the current XDC value of your bridged balance. ## Security * Every pathway is verified by **four independent DVNs** (Canary, LayerZero Labs, Horizen, and Nethermind) — a single compromised verifier cannot forge a bridge message. * The adapter meters the **unlock path** with a per-source-chain rate limit. Because the lockbox only ever releases funds when psXDC is bridged *back*, the limit is applied there (keyed by the origin chain): even if one destination chain were fully compromised, it could unlock at most the configured burst immediately and a fixed rate thereafter, giving operators time to pause — while the other chains' pathways are unaffected. * Total bridged psXDC across all chains always equals psXDC locked in the adapter — verified by an on-chain conservation test across multi-hop routes (XDC to Base to Arbitrum and back), including sub-1e12 dust round trips. * Contracts use two-step ownership transfer (nominate + accept), so ownership cannot be fat-fingered to an address that cannot operate the lockbox. ## Troubleshooting * **Transfer not arrived after 10+ minutes?** Open the *LayerZero Scan* link from the tracker card (or paste your transaction hash at [layerzeroscan.com](https://layerzeroscan.com)). Messages are never lost — delivery is retried automatically once verification completes. * **"Insufficient balance" on the fee?** The LayerZero fee is paid in the source chain's gas token, on top of gas. Leaving XDC needs a few extra XDC; returning needs a small amount of ETH (Base/Arbitrum), BNB, or HYPE. * **Wrong network in the wallet?** The page requests the switch automatically when you press Bridge; approve the prompt in your wallet. ## Addresses See [Deployed Contracts & Addresses](/products/contract-addresses) for the adapter (XDC) and the psXDC OFT + rate oracle on each destination chain. # Multichain psXDC: DeFi Opportunities Bridging psXDC is not just about moving tokens — it turns your staked XDC into **productive collateral** on other ecosystems while it keeps earning XDC staking rewards underneath. This page lists what is live today and how the yield stacks. {% hint style="info" %} psXDC is the same asset everywhere: one canonical supply, locked 1:1 on XDC, minted at the same address `0x98D916F5773Ac0482b49856f2659d6c32114C4Ba` on Base, Arbitrum, BNB Chain, and HyperEVM. See [Bridge psXDC](/products/xdc-liquid-staking/bridge) for how to move it. {% endhint %} ## Live today: lend and borrow on PrimeFi (Base & HyperEVM) psXDC is listed as **collateral** on [PrimeFi](https://primefi.xyz), the Aave-style money market, on both **Base** and **HyperEVM**. What that unlocks: * **Supply psXDC, earn supply APY** on top of the XDC staking yield already accruing inside the token. Two yields, one asset. * **Borrow against your stake without unstaking.** Supply psXDC as collateral and borrow stablecoins or other listed assets — keep your XDC staking exposure and rewards while freeing liquidity for anything else. * **No lock-up interaction.** Withdrawing supplied psXDC from PrimeFi is instant (subject to pool utilisation); your underlying stake on XDC is never touched. How psXDC is priced there: PrimeFi consumes an XDC/USD feed and treats psXDC conservatively at the XDC price. Because the psXDC redemption rate only grows, your collateral is if anything slightly *under*-valued — a safety margin, not a risk. The on-chain [psXDC rate oracle](/products/xdc-liquid-staking/psxdc-rate-oracle) is available for integrators who want to credit the full redemption value. {% hint style="warning" %} **Borrowing carries liquidation risk.** Collateral parameters (LTV, liquidation threshold and bonus) are set by PrimeFi and shown live in the PrimeFi app — always size loans against those numbers, not this page. Start conservative; borrowing stablecoins against a yield-bearing asset is a strategy, not free money. {% endhint %} ### The yield stack, concretely | Layer | Source | Where it shows up | | ---------------------- | --------------------------- | --------------------------------------------------------------------------------- | | \~5.5% APY XDC staking | validator rewards on XDC | psXDC redemption rate (steps up when the network pays monthly masternode rewards) | | Supply APY | PrimeFi lenders' market | claimable on PrimeFi | | Borrowed capital | whatever you deploy it into | your strategy | Example: bridge psXDC to Base → supply on PrimeFi → borrow a stablecoin at a conservative loan-to-value → deploy the stablecoin (LP, yield, or simply hold as dry powder). Your XDC stake keeps compounding the entire time, and you can unwind any moment: repay → withdraw → bridge back → unstake or sell on [Spot](/products/dex-liquidity). ## Also available on every destination chain * **Hold & transfer** — psXDC is a plain ERC-20 on Base, Arbitrum, BNB Chain, and HyperEVM. Self-custody it, move it between your own wallets, or pay another psXDC holder, all with the yield still accruing. * **DEX liquidity** — anyone can seed a psXDC pair on a destination-chain DEX. Pricing helpers can read the [psXDC rate oracle](/products/xdc-liquid-staking/psxdc-rate-oracle) (same address on every chain: `0x2927630dfDd66433DbA9370b316EF5a8408d5dD2`). ## For protocols who want to integrate psXDC Money markets, DEXes, and vaults on any of the four destination chains can list psXDC with two addresses and one page of reading: * Token (all chains): `0x98D916F5773Ac0482b49856f2659d6c32114C4Ba` * Rate oracle, Chainlink `AggregatorV3Interface`, answer = XDC per psXDC, 18 decimals (all chains): `0x2927630dfDd66433DbA9370b316EF5a8408d5dD2` * Integrator guide: [psXDC Rate Oracle](/products/xdc-liquid-staking/psxdc-rate-oracle) The oracle is monotonic, step-capped, and refreshed daily — designed specifically so lending protocols can treat psXDC like a wstETH-class liquid-staking collateral. ## Where the yield ultimately comes from Nothing on this page changes how rewards are generated: XDC validator rewards flow into the vault on XDC and raise the psXDC share price ([how rewards work](/products/xdc-liquid-staking/xdc-staking-rewards)). Bridging, lending, and LP-ing are layers *on top* of that base yield — every bridged psXDC remains a claim on the same appreciating vault share, redeemable the moment it returns to XDC. # psXDC Rate Oracle (integrators) For money markets and other integrators that want to price **bridged psXDC** on Base, Arbitrum, or BNB Chain. psXDC is a yield-bearing vault share: its fair value is `XDC price × psXDC/XDC exchange rate`. This oracle publishes that exchange rate cross-chain from XDC so you can price psXDC exactly like a wstETH/rETH rate provider. ## Interface `PsxdcRateOracle` implements the Chainlink `AggregatorV3Interface`: ```solidity function decimals() external view returns (uint8); // 18 function latestRoundData() external view returns ( uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound ); function isStale() external view returns (bool); // true past the staleness window ``` `answer` = XDC redeemable per **1e18** psXDC (18 decimals). Compose it with your existing XDC/USD feed: ``` psXDC/USD = latestRoundData().answer * (XDC/USD) / 1e18 ``` ## Safety guarantees The rate can only be written by the wired XDC publisher (LayerZero peer auth, 2 required DVNs). Each update is additionally guarded on the destination: * **Monotonic** — the rate cannot decrease (share price only grows). A rare validator-loss writedown requires an explicit, one-shot owner override, so a spurious downward push is rejected by default. * **Step-capped** — each update may rise by at most `maxStepBps` (default 1%), blunting a bad or manipulated push. * **Staleness** — `updatedAt` plus `isStale()` let you reject data older than the configured window (default 2 days). PrimeStaking pushes the rate at least daily, and the push is permissionless so it cannot be censored. If pushes lapse long enough that legitimate cumulative growth would exceed the per-update step cap, the bridged update is rejected and the feed goes stale (safe: integrators see `isStale()` and pause) rather than jumping. The owner restores liveness with a break-glass `adminSetRate`, which still enforces non-zero and (unless explicitly armed) monotonicity — so it can never silently mark psXDC down. ## Recommended usage Treat the oracle as the **exchange-rate** leg only; keep your own market XDC/USD feed for the base asset. For collateral, apply your standard loan-to-value and liquidation parameters to the composed psXDC/USD price, and reject updates when `isStale()` is true. ## Addresses Per-chain oracle addresses are in [Deployed Contracts & Addresses](/products/contract-addresses). Reach out at for listing support. # Smart Contract Reference (V3) Technical reference for [`PrimeStakedXDC_V3_2`](/products/contract-addresses), the V3 liquid staking vault. The contract is an ERC-4626-style native-XDC vault with self-service withdrawals, a buffer-aware queue, on-chain masternode integration, and time-locked governance. {% hint style="info" %} Address: [`0xDc74c0DaED82ae94486DeeF22991d2F54173c734`](https://xdcscan.com/address/0xDc74c0DaED82ae94486DeeF22991d2F54173c734). **Non-upgradeable**: deployed with a regular constructor, no proxy. {% endhint %} *** ## User functions ### `stake() payable` Deposits native XDC and mints psXDC shares to the sender at the current exchange rate. | Parameter | Detail | | ----------- | ------------------------------- | | `msg.value` | Amount of native XDC to deposit | | Returns | psXDC shares minted | ### `depositNative(uint256 assets, address receiver) payable` Same as `stake` but lets you specify a separate `receiver`. `msg.value` must equal `assets`. ### `withdraw(uint256 assets, address receiver, address owner)` / `redeem(uint256 shares, address receiver, address owner)` Standard ERC-4626 instant redemption. Reverts if the vault's liquid buffer cannot cover the request. ### `withdrawWithQueue(uint256 assets, address receiver, address owner)` / `redeemWithQueue(uint256 shares, address receiver, address owner)` The "smart" redemption used by the app. Settles **instantly** when the buffer is sufficient, otherwise **escrows the shares** and adds a request to the FIFO queue. ### `claimQueuedAssets(address receiver)` Pays out any XDC parked in `pendingQueuedAssets` for the caller (e.g. from previously failed receiver payouts or processed queue requests where the receiver could not receive directly). ### `cancelQueuedWithdrawal(uint256 requestId)` Cancels a pending queued withdrawal you previously created and returns the escrowed shares to your wallet. ### `migrate(address receiver, uint256 assets, uint256 minSharesOut)` (bridge-only) Mints V3 shares to `receiver` against `assets` of XDC contributed by the migration bridge. Only callable by the configured `PrimeStakedXDC_V3MigrationBridge` while the migration window is open. `minSharesOut` protects callers from unfavorable exchange-rate movement. *** ## Read-only helpers | Function | Returns | | --------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `totalAssets()` | Total XDC tracked by the vault (includes principal staked with masternodes) | | `convertToShares(uint256 assets)` / `convertToAssets(uint256 shares)` | Exchange-rate conversions | | `previewDeposit` / `previewWithdraw` / `previewRedeem` | UI-friendly previews using the current rate | | `maxWithdraw(address)` / `maxRedeem(address)` | Liquidity-aware caps that reflect the buffer | | `outstandingValidatorPrincipalByOperator(address operator)` | Principal currently staked with a specific masternode operator | *** ## Operator functions (validator management) Anyone with the appropriate role can call these; users do not call them directly. | Function | Role | Purpose | | --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `proposeMasternode(...)` | `PROPOSER_ROLE` | Manually propose a new masternode | | `triggerAutoPropose(uint256 maxNodes)` | anyone | Trigger the bounded auto-propose loop. Always blocked while there is a withdrawal queue backlog so user redemptions are prioritized over new proposals | | `processWithdrawalQueue(uint256 maxRequests)` | anyone | Process up to `maxRequests` FIFO entries | | `syncTrackedAssets()` | anyone | Reconcile `trackedTotalAssets` with the contract's native balance after unexpected inflows | *** ## Operations & risk These are gated by the V3 role split. They never let an admin move user funds; they only tune parameters and report validator outcomes. | Function | Role | Notes | | -------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------- | | `setBufferBps(uint256)` | `OPERATIONS_MANAGER_ROLE` | Sets the percentage of total assets kept liquid for instant redeem | | `setOperatorScanLimit(uint256)` / `setQueueScanLimit(uint256)` | `OPERATIONS_MANAGER_ROLE` | Bounded scan limits used by auto-propose and queue processing | | `setMinStake(uint256)` | `OPERATIONS_MANAGER_ROLE` | Minimum XDC required to attempt a masternode propose | | `setValidator(address)` | `OPERATIONS_MANAGER_ROLE` | Configures the XDC validator contract address | | `reportValidatorLoss(address operator, uint256 assets)` | `RISK_MANAGER_ROLE` | Reports a validator loss; capped per-report (`maxLossBpsPerReport`) and per-day (`maxDailyLossBps`) | | `reportMasternodeResignPrincipal(address operator)` | `PROPOSER_ROLE` | Accounts for masternode principal that has been returned to the vault after resignation cooldown | `grantRole`, `revokeRole`, and `renounceRole` are intentionally **disabled**. Sensitive role rotations must go through the delayed governance path below to prevent bypassing the time-lock. *** ## Delayed governance Every sensitive change is a **schedule → wait → execute** flow gated by `governanceDelay`: | Schedule | Execute | Cancel | | ------------------------------- | ------------------------------ | ----------------------------------- | | `setGovernanceDelay(delay_)` | `executeGovernanceDelay()` | `cancelGovernanceDelayChange()` | | `setOperationsManager(account)` | `executeOperationsManager()` | `cancelOperationsManagerChange()` | | `setRiskManager(account)` | `executeRiskManager()` | `cancelRiskManagerChange()` | | `setMaxLossBpsPerReport(bps)` | `executeMaxLossBpsPerReport()` | `cancelMaxLossBpsPerReportChange()` | | `setMaxDailyLossBps(bps)` | `executeMaxDailyLossBps()` | `cancelMaxDailyLossBpsChange()` | The owner handoff itself uses the same pattern: * `scheduleOwnerTransfer(newOwner)` → wait `governanceDelay` → `executeOwnerTransfer()`. Cancel any time with `cancelOwnerTransfer()`. `transferOwnership` and `renounceOwnership` are **disabled** so ownership can never change without the delay. *** ## Migration controls | Function | Role | Purpose | | ---------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------- | | `setMigrationBridge(address)` | admin | Configures the address allowed to call `migrate(...)` | | `setMigrationInProgress(bool)` | `MIGRATION_MANAGER_ROLE` | Opens or closes the migration window | | `fundMigrationLiquidity()` payable | `MIGRATION_MANAGER_ROLE` | Tops up backing liquidity for migrated shares. Only callable while the migration window is open | Direct native sends to the vault while migration is in progress are accepted **only** from the migration manager and are treated as migration liquidity (they do not inflate `totalAssets` or `convertToShares`). *** ## V3.1 additions: under-backed mode V3.1 adds a single mechanism on top of the audited V3 design so the vault could launch while the legacy masternode collateral is still being transferred in: | Surface | Detail | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `underBackedMode` (public bool) | Set once at go-live if the vault's liquid + tracked backing was below its share liability. **Auto-clears** inside `syncTrackedAssets()` when real backing catches up; no admin can force it back on. | | `queueBackingBudget` (public uint) | A ring-fenced budget, active only while under-backed. Migration-manager funding and returned masternode principal accrue here and are reserved for the FIFO withdrawal queue. | | Withdrawal behaviour | Immediate withdrawals draw only from unencumbered surplus liquidity (new stakes stay withdrawable); queued requests are paid from `queueBackingBudget` as funding tranches arrive. | | NAV protection | While under-backed, `syncTrackedAssets()` cannot write NAV down, so the transition mechanics can never reduce the value of existing shares. | | `fundMigrationLiquidity()` | Callable by the `MIGRATION_MANAGER_ROLE` during under-backed mode to inject collateral tranches (roughly one masternode's worth per week) without minting shares or inflating NAV. | Once the full collateral has been transferred, `underBackedMode` clears itself and the contract behaves exactly like the audited V3. *** ## Events worth indexing | Event | When | | ---------------------------------------------------------- | --------------------------------------------------------------------------- | | `Deposit(sender, owner, assets, shares)` | Stake / deposit | | `Withdraw(sender, receiver, owner, assets, shares)` | Instant or queued payout | | `WithdrawalQueued(requestId, owner, shares)` | A request entered the FIFO queue | | `WithdrawalProcessed(requestId, receiver, assets, shares)` | The queue processed a request | | `WithdrawalCanceled(requestId, owner, shares)` | User cancelled their own queued request | | `AutoProposeFailed(reason)` | Auto-propose was attempted but didn't execute; never reverts the stake flow | | `ValidatorLossReported(operator, assets, reporter)` | Risk manager recorded a loss | | `MigrationLiquidityFunded(amount)` | Migration manager topped up bridge liquidity | *** ## Security properties * Non-blocking auto-propose path: stake never reverts because of a failed propose. * Deferred payout fallback for rejecting receivers via `pendingQueuedAssets` + `claimQueuedAssets`. * Liquidity-aware `maxWithdraw` / `maxRedeem`. * Bounded scans (`operatorScanLimit`, `queueScanLimit`) to prevent gas-griefing. * AccessControl role split (proposer / operations / risk / migration). * Delayed execution for every sensitive role / risk parameter change. * Per-report and cumulative per-day loss caps. * Direct role mutation (`grantRole`, `revokeRole`) disabled to prevent delayed-governance bypass. → [V3 Architecture](/products/xdc-liquid-staking/v3-architecture) → [Deployed Contracts & Addresses](/products/contract-addresses) # XDC NFTs XDC Staking NFTs are gamified staking positions on the XDC Network. Each NFT holds **psXDC v3 vault shares** and earns two stacked yields: a **base \~5.5%** from the underlying share-price appreciation (always earned, no claim, no rarity dependency) and an additional **boost slice up to \~1.5%** from a Synthetix-style accumulator funded by the protocol's reward harvester, weighted by rarity, level, and lock status. {% hint style="info" %} The XDC NFT stack has been rebuilt around the psXDC v3 vault. New contract addresses: [`XdcStakedNFT`](/products/contract-addresses), [`XdcNftStakingVault`](/products/contract-addresses), [`XdcNftMigrator`](/products/contract-addresses), [`XdcNftBoostHarvester`](/products/contract-addresses), [`LegacyMigratorBypassFacet`](/products/contract-addresses). The legacy V2 collection at `0x9D45…76a0` remains operational for any holder who has not yet migrated; see [Migrate XDC NFTs to V3](/products/xdc-staking-nfts/migrate-nfts-v2-to-v3). {% endhint %} *** ## Key Facts | | | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Collection size** | 5,557 NFTs (5,542 generative + 15 handcrafted), preserved across V2 → V3 | | **Token staked** | **psXDC v3 vault shares** (not raw XDC) | | **Max stake per NFT** | **100,000 psXDC** (share count). Stake more by holding more NFTs. See [Per-NFT stake cap](/products/xdc-staking-nfts/xdc-staking-nfts-mechanics#per-nft-stake-cap). | | **Base yield** | \~5.5%, from share-price appreciation of the underlying psXDC | | **Boost slice** | Up to \~1.5%: Synthetix accumulator, weighted by rarity / level / lock | | **Floor APY** | **\~5.5%** (the base NAV), automatic, always earned regardless of rarity / lock / boost cadence | | **Target APY band (with boost)** | \~5.75% (unlocked) → \~7% (locked) when boost stream is steady | | **Reward token (boost)** | XDC. `notifyBoost` mints shares, claim unwraps to native XDC | | **Locked yield** | Additive `lockBoost` term added to NFT weight when locked | | **Merge** | Two same-rarity NFTs → one higher-rarity NFT (originals burned) | | **Marketplace** | [PrimePort.xyz](https://primeport.xyz) | *** ## How It Works 1. **Get psXDC shares.** Stake XDC in [`PrimeStakedXDC_V3_2`](/products/xdc-liquid-staking) or buy psXDC on a DEX. (Already hold V2 psXDC? [Migrate to V3 first](/products/xdc-liquid-staking/staking-guide/migration).) 2. **Get an NFT.** Buy one on [PrimePort](https://primeport.xyz), or migrate a legacy V2 NFT through [`XdcNftMigratorV2`](/products/xdc-staking-nfts/migrate-nfts-v2-to-v3) (preserves your rarity and any active lock, and your `tokenId` for legacy ids below `10000`; ids ≥ `10000` are remapped). 3. **Stake psXDC shares into your NFT.** The vault records the shares against the NFT's `tokenId`. The NFT's **weight** in the boost accumulator becomes `stakedShares × (rarityMultiplier + level + lockBoost)`. Each NFT holds up to **100,000 psXDC**; to stake more, spread it across multiple NFTs. 4. **Earn two stacked yields**: * **Base NAV**: your staked shares keep appreciating; you receive them back at the higher value when you withdraw. * **Boost**: every `notifyBoost` push from the harvester increments `rewardPerWeightStored`; your earned slice grows in proportion to your weight. 5. **Claim boost** from the NFT detail page whenever you want. It is paid in XDC. Base NAV is automatic and needs no claim. 6. **Upgrade** by merging two same-rarity NFTs into a higher-tier one for a larger `rarityMultiplier`. 7. **Lock (optional)**: locking adds `lockBoost` to the weight calculation. Lock expiry is preserved across migration so users can't dodge the lock by routing through the migrator. 8. **`burnAndRedeem`** burns the NFT and returns the underlying psXDC shares (or, optionally, redeems them to XDC in one transaction). *** ## Rarity Tiers Each NFT has a rarity that determines its `rarityMultiplier`, which feeds into the weight formula: | Rarity | Base Multiplier | | --------- | --------------- | | Plentiful | 0.3 | | Common | 0.4 | | Uncommon | 0.5 | | Rare | 0.7 | | Epic | 0.9 | | Legendary | 1.2 | | Mythic | 1.5 | | Godly | 1.9 |
Higher rarity = higher `rarityMultiplier` = higher weight = larger slice of every `notifyBoost`. {% hint style="warning" %} `rarityMultiplier` values are **immutable** on the V3 vault. Changing them would invalidate `totalWeight` for every staked NFT, so the vault has no setter. A future change would require deploying a new vault and migrating. {% endhint %} *** ## Merge System Combine two NFTs of the **same rarity** to mint one NFT of the **next rarity tier**. * Both original NFTs are burned (their psXDC shares are released back to you so you can re-stake into the new NFT, depending on the merge mode). * A new, higher-rarity NFT is minted via `XdcStakedNFT.mintMerged` (token IDs ≥ `10000`). * **Godly** is the highest rarity achievable through merging. The merge system makes the collection **deflationary by design**: every merge permanently reduces the total supply. Over time, remaining NFTs become increasingly scarce and carry higher multipliers. *** ## Handcrafted NFTs The collection includes 15 exclusive, handcrafted NFTs by the Art Director. Owners receive three additional XDC Staking NFTs. These NFTs have the **highest `rarityMultiplier`** in the collection. *** ## V3 contract stack | Contract | Address | Role | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `XdcStakedNFT` | [`0xf3eB62F0Daf98ab65f0696630621A6ecECDB898E`](https://xdcscan.com/address/0xf3eB62F0Daf98ab65f0696630621A6ecECDB898E) | Fresh ERC-721 collection. Non-upgradeable. | | `XdcNftStakingVault` (proxy) | [`0x9f38dF64eeC71e2408B24217b8D621c6B07E4Da8`](https://xdcscan.com/address/0x9f38dF64eeC71e2408B24217b8D621c6B07E4Da8) | Staking engine that holds psXDC shares under each NFT and runs the accumulator. TransparentUpgradeableProxy, ERC-7201 namespaced storage. | | `XdcNftMigratorV2` | [`0x69DE30161ec0f2e0Dc0649190dB9b93F4c492ea8`](https://xdcscan.com/address/0x69DE30161ec0f2e0Dc0649190dB9b93F4c492ea8) | Live one-shot V2 → V3 migrator. Remaps legacy ids ≥ `10000` to `5558–9999`. Non-upgradeable. (Supersedes the paused `XdcNftMigrator` `0x45e2…7dFb`.) | | `XdcNftBoostHarvester` | [`0x6a319528111E5e50712Fd2D3d2db8323b119821D`](https://xdcscan.com/address/0x6a319528111E5e50712Fd2D3d2db8323b119821D) | Funds the boost accumulator via `notifyBoost`. Non-upgradeable. | | `LegacyMigratorBypassFacet` | [`0x2786D8Df1C38c9D4eD642B84c073349b0f0B5e13`](https://xdcscan.com/address/0x2786D8Df1C38c9D4eD642B84c073349b0f0B5e13) | Diamond facet on the legacy diamond enabling locked-NFT migration. Clears `tokenLocked`; the diamond pays the psXDC (no v2-staker call). | → [Staking Mechanics (V3)](/products/xdc-staking-nfts/xdc-staking-nfts-mechanics) → [Reward Model: Base NAV + Boost](/products/xdc-staking-nfts/xdc-nft-staking-reward-system) → [Migrate XDC NFTs to V3](/products/xdc-staking-nfts/migrate-nfts-v2-to-v3) → [Locked NFTs & Legacy Diamond Bypass](/products/xdc-staking-nfts/locked-nft-migration) → [Boost Harvester (technical)](/products/xdc-staking-nfts/boost-harvester) → [Smart Contract Reference (V3)](/products/xdc-staking-nfts/smart-contract-functions) # Staking Mechanics (V3) XDC NFTs in V3 use a **weight-based** model rather than the V2 "monthly reward pool × multiplier" model. Your slice of the boost stream is proportional to your NFT's weight in the global accumulator, where weight is a function of staked shares, rarity, level, and lock status. *** ## The weight formula ``` weight(tokenId) = stakedShares × (rarityMultiplier + level + lockBonus) ``` | Term | What it represents | | ------------------ | ------------------------------------------------------------------------------------------------------------------- | | `stakedShares` | psXDC v3 shares currently deposited into this NFT | | `rarityMultiplier` | Per-rarity constant set at mint (see [README](/products/xdc-staking-nfts#rarity-tiers)). Immutable on the V3 vault. | | `level` | Increases as you stake more psXDC into the NFT, up to per-rarity caps | | `lockBonus` | Additive integer applied while the NFT is locked, zeroed when unlocked | All four terms are stored on-chain; the vault keeps `totalWeight` in sync so reward distribution stays consistent. *** ## The Synthetix-style accumulator Boost rewards aren't distributed in monthly batches. Instead the vault uses a Synthetix-style accumulator that runs continuously: ``` on notifyBoost(x): sharesMinted = psXDC_v3.depositNative{value: x}(x, vault) rewardPerWeightStored += sharesMinted * 1e18 / totalWeight reverts if totalWeight == 0 earned(tokenId) = info.shares * (rewardPerWeightStored − info.rewardIndex) * weight / 1e18 ``` What this means in practice: * Whenever the harvester pushes XDC via `notifyBoost`, **every staked NFT's pending reward grows immediately** in proportion to its weight at that moment. * `_settle(tokenId)` is called before any weight-changing operation (stake more, lock, unlock, merge, withdraw) so pending boost is captured against the **old** weight. You never overpay or underpay because of mid-stream changes. * `notifyBoost` reverts if `totalWeight == 0`, since pushing boost into an empty vault is a no-op. *** ## Interface Actions | Action | Function | What it does | | ------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Stake** | `stake(tokenId, shares)` | Deposit psXDC v3 shares against this NFT. Settles pending boost, updates weight, increments `level` if thresholds are crossed. Reverts if the resulting balance would exceed the [per-NFT cap](#per-nft-stake-cap). | | **Withdraw shares** | `withdraw(tokenId, shares)` | Remove psXDC shares without burning the NFT. Settles pending boost first. | | **Lock** | `lock(tokenId, duration)` | Locks for a chosen tier duration (30/90/180/365 days), freezing that tier's `lockBonus` into the NFT and adding it to weight. Disables `withdraw`, `merge`, `burnAndRedeem` until the lock ends. | | **Poke expired** | `pokeExpired(tokenIds)` | Permissionless keeper hook: retires the boost of any NFT whose lock has ended, so `totalWeight` stays accurate even for untouched NFTs. | | **Merge** | `merge(tokenIdA, tokenIdB)` | Two same-rarity NFTs → one higher-rarity NFT. Burns originals and shares are released for restaking. Reverts if the combined shares would exceed the [per-NFT cap](#per-nft-stake-cap). | | **Claim boost** | `claim(tokenId)` | Pays out earned boost in XDC. Can also unwrap to native XDC or keep as shares depending on the call. | | **`burnAndRedeem`** | `burnAndRedeem(tokenId)` | Burns the NFT and returns the underlying psXDC v3 shares (or redeems them to XDC) in one transaction. | | **Transfer** | ERC-721 `transferFrom` | NFT changes hands. The new owner inherits staked shares, weight, pending boost, and lock status. | `mintAndStake` / `mintAndStakeLocked` are restricted to the migrator and are not directly callable by users. *** ## Locking Locking an NFT does two things: 1. Sets `lockEnd = now + duration`. Until that timestamp passes, `withdraw`, `merge`, and `burnAndRedeem` revert. 2. Freezes the chosen tier's `lockBonus` into the NFT's weight, increasing its slice of every subsequent `notifyBoost`. There are **four lock tiers** - 30, 90, 180 and 365 days - each granting a progressively larger boost. The boost you get is fixed at lock time (later tier-table changes don't affect an existing lock). **Boost expiry.** Unlike earlier versions, the lock bonus **ends when the lock ends**. From the moment `lockEnd` passes, the NFT's effective weight drops back to its unlocked value, and the stale bonus is cleared on the next interaction (any user action, or a permissionless `pokeExpired` keeper call). Rewards already earned are never clawed back - the boost simply stops going forward. You can **re-lock** at any tier once a lock has expired. The lock **does not change `stakedShares`**; the bonus is purely additive on the weight side. Lock expiry is **preserved across migration** from V2; see [Locked NFTs & Legacy Diamond Bypass](/products/xdc-staking-nfts/locked-nft-migration). *** ## Per-NFT stake cap A single XDC NFT can hold at most **100,000 psXDC shares**. To stake more than that, hold additional NFTs — one NFT is one capped "slot". * Enforced on-chain in both `stake()` and `merge()`: any action whose **result** would push an NFT above `maxStakePerNft` reverts with `ExceedsMaxStakePerNft`. * **Merge respects the cap too.** Two NFTs whose combined staked shares exceed the cap cannot be merged — otherwise merging would be a way to hold more than the cap in one NFT. They stay as separate NFTs and keep earning independently. * **The cap is on share count, not XDC value.** psXDC is an ERC-4626 share; a maxed NFT's XDC value still grows over time as the share price appreciates (that's the base yield). The 100,000 limit is on psXDC shares held. * **Rewards are never blocked by the cap.** Base yield accrues in the share price and boost accrues in a separate `pendingBoost` bucket claimed via `claim()` — neither increases `stakedShares`, so a maxed NFT keeps earning and claiming normally. * **Grandfathering.** NFTs that already hold more than the cap (e.g. migrated from a large V2 position) keep their full balance and can still `withdraw`/`claim`; they simply can't be topped up or used as a merge input that would exceed the cap. * **Migrator mint paths are exempt** (`mintAndStake` / `mintAndStakeLocked`) so pre-existing V2 positions migrate intact. * **Configurable by governance** via `setMaxStakePerNft(uint256 maxShares)` (`DEFAULT_ADMIN_ROLE`). Setting `0` disables the cap (unlimited). Changing it only affects future `stake`/`merge`; it never touches existing balances. ## Caps and tuning * `setLevelStakedNeeded` and `setLockBoost` can only be changed while `totalWeight == 0` (i.e. before any NFT is staked). Once the vault has live positions these setters revert, which prevents silent weight drift. Lock tiers are enabled/adjusted post-launch through the governance-gated `setLockBoostPostLaunch`, which only affects **future** locks - already-locked NFTs keep the boost they froze at lock time. * `setMaxStakePerNft` (the [per-NFT stake cap](#per-nft-stake-cap)) is settable at any time by `DEFAULT_ADMIN_ROLE`, unlike the pre-staking-only setters above; it only gates future `stake`/`merge`. * `rarityMultiplier` has **no setter** on the V3 vault. Updating multipliers would require deploying a new vault and migrating. * `setRarityMultiplier` does **not** exist on the live vault by design. * The vault is paused with `PAUSER_ROLE`. Pausing halts stake/withdraw/claim; boost can still be received (intentional, to keep the stream flowing). → [Reward Model: Base NAV + Boost](/products/xdc-staking-nfts/xdc-nft-staking-reward-system) → [Smart Contract Reference](/products/xdc-staking-nfts/smart-contract-functions) → [Boost Harvester (technical)](/products/xdc-staking-nfts/boost-harvester) # Reward Model: Base NAV + Boost XDC NFTs in V3 earn from **two stacked sources**. There is no monthly XDC pool and no "PrimeFi ecosystem profit share" math. Both layers are fully on-chain and continuously accruing. *** ## The two layers ``` base APY (~5.5%) boost APY (up to ~1.5%) │ │ ▼ ▼ shares × NAV(t) appreciation + Synthetix accumulator slice (the psXDC v3 share price) (rarityMult + level + lockBonus weighted) ``` ### 1. Base NAV: psXDC v3 share-price appreciation Every psXDC v3 share grows in value as validator rewards flow into the underlying vault. When your NFT holds `stakedShares` of psXDC, the **same share count** is returned on `withdraw`, but each share is worth more XDC than it was on `stake`. This layer requires **no action and no claim**; it's already inside the shares. | Aspect | Detail | | ------------------- | ---------------------------------------------------------------------------- | | Target APY | \~5.5% | | How it accrues | Via [`PrimeStakedXDC_V3_1`](/products/contract-addresses) share-price growth | | When you realize it | When you `withdraw` shares from the NFT or `burnAndRedeem` | ### 2. Boost: Synthetix accumulator inside the NFT vault The protocol's [`XdcNftBoostHarvester`](/products/xdc-staking-nfts/boost-harvester) periodically pushes XDC into the NFT vault via `notifyBoost`. The vault converts that XDC to psXDC v3 shares and credits the accumulator. Every staked NFT earns a slice proportional to its **weight**: ``` weight = stakedShares × (rarityMultiplier + level + lockBonus) ``` | Aspect | Detail | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Target APR band | \~0.25% (Plentiful unlocked) → \~1.5% (Handcrafted locked) | | How it accrues | `rewardPerWeightStored` increments on every `notifyBoost`; per-NFT `earned` is computed Synthetix-style | | When you realize it | When you call `claim(tokenId)` from the NFT detail page (or automatically on any other state-changing action like stake/lock/merge/withdraw, which `_settle` first) | | Reward asset | XDC (the harvester's payload is native XDC) | *** ## Combined target ranges | Position | Base NAV (floor) | + Boost slice (when flowing) | Combined target | | ------------------------------- | ---------------- | ---------------------------- | ----------------------- | | Plain psXDC, no NFT | \~5.5% | none | **\~5.5%** | | psXDC staked in an unlocked NFT | **\~5.5%** | \~0.25% | **\~5.5% → \~5.75%** | | psXDC staked in a locked NFT | **\~5.5%** | up to \~1.5% | **\~5.5% → up to \~7%** | {% hint style="info" %} **The floor for every staked NFT is the base \~5.5%.** That layer is purely psXDC v3 share-price growth. It accrues automatically and does not depend on rarity, level, lock status, or harvester cadence. Even if `notifyBoost` hasn't been called in a while, you still earn the base. The boost slice is an **additional** stream on top. {% endhint %} Your individual boost APR depends on: * Your NFT's `rarityMultiplier`, `level`, and whether it's locked. * How much psXDC you have staked (more shares → more weight → more slice). * How active the harvester's `notifyBoost` stream has been recently. The UI surfaces a trailing 30-day boost APR alongside the static targets so you can see what the stream has actually paid. *** ## Why no monthly pool The V2 NFT system distributed rewards in a monthly batch process driven off-chain. V3 replaces this with a **continuous, on-chain Synthetix accumulator** for three reasons: * **Trust-minimized**: the boost rate is a function of harvester pushes, not a manually-set monthly figure. * **Granular**: earnings update on every `notifyBoost`, not once per month. * **Composable**: partner integrations can read `earned(tokenId)` directly on-chain at any time. There is no longer a "10% of PrimeFi profits" framing; the harvester's funding model is described in [Boost Harvester (technical)](/products/xdc-staking-nfts/boost-harvester). *** ## Maximizing Your Rewards | Strategy | Effect | | -------------------------- | -------------------------------------------------------------------------------------- | | Stake more psXDC shares | More `stakedShares` → linear increase in weight | | Merge two same-rarity NFTs | Higher `rarityMultiplier` on the result | | Level the NFT | Higher `level` term, additive to the multiplier | | Lock the NFT | Adds `lockBonus` to the weight, but disables withdraw/merge/burnAndRedeem until expiry | | Hold higher-rarity NFTs | Higher base `rarityMultiplier` = larger slice for the same staked shares | → [Staking Mechanics](/products/xdc-staking-nfts/xdc-staking-nfts-mechanics) → [Boost Harvester (technical)](/products/xdc-staking-nfts/boost-harvester) → [Smart Contract Reference](/products/xdc-staking-nfts/smart-contract-functions) # Migrate XDC NFTs to V3 The V3 XDC NFT stack is a fresh set of contracts. Your legacy V2 NFTs continue to work, but to earn under the new reward model (psXDC v3 NAV + Synthetix boost slice) you migrate them through [`XdcNftMigratorV2`](/products/contract-addresses). Migration preserves your **rarity** and any active **lock expiry**, and preserves your **tokenId** for every legacy id below `10000`. {% hint style="info" %} Migration is **one-shot per NFT**, **atomic** (all-or-nothing), and never holds your funds across transactions. For legacy ids below `10000` the `tokenId` is identical end-to-end, so your social presence, links, and OpenSea / PrimePort references keep working. {% endhint %} {% hint style="success" %} **Already migrated to a V3 NFT before July 2026?** Nothing to do. When the liquid-staking vault was redeployed as V3.1, the NFT vault was upgraded in place and the psXDC staked inside every V3 NFT was carried over 1:1 automatically. Your NFT, its rarity, lock, and staked balance are unchanged. {% endhint %} {% hint style="warning" %} **Legacy ids ≥ `10000` are remapped.** The V3 collection reserves token ids `≥ 10000` for merged NFTs, so a legacy NFT minted in that band cannot keep its number. `XdcNftMigratorV2` automatically assigns such an NFT a **new** id in the `5558–9999` range (emitting `LegacyIdRemapped`) and migrates everything else (rarity, staked value, lock) unchanged. Only \~21 legacy NFTs are affected; all other ids are preserved 1:1. {% endhint %} *** ## What the migrator does ``` User XdcNftMigrator Old Façade Bridge / psXDC v3 New Vault + NFT │ │ │ │ │ │ approve(migrator, id) ──►│ │ │ │ │ migrate(id, minOut) ──►│ │ │ │ │ │ ownerOf, getNFTData ►│ │ │ │ │ transferFrom(user→me)│ │ │ │ │ burnAndRedeem(id) ──►│ │ │ │ │ ◄────────────────── receives psXDC v2 OR native XDC │ │ │ │ │ │ bridge.migrate(amount) OR depositNative{value} ───────────────────────►│ │ │ ◄──────────────────────────────────── receives v3 shares ──────────────│ │ │ approve(vault, shares) │ │ │ mintAndStake(user, tokenId, rarity, shares) ─────────────────────────►│ │ │ │ │ ◄──── new tokenId on XdcStakedNFT, staked under XdcNftStakingVault ─────────────────────────────┘ ``` For locked NFTs the flow is identical except it also routes through the [`LegacyMigratorBypassFacet`](/products/xdc-staking-nfts/locked-nft-migration) to clear `tokenLocked` and preserve the original `lockEnd`. ### Properties that always hold * **Same `tokenId`** end-to-end for legacy ids below `10000` (wallets, social, marketplaces keep working). Legacy ids ≥ `10000` are remapped to a fresh `5558–9999` id (see the warning above). * **Same rarity**: the migrator reads `getNFTData` on the legacy NFT and mints with the matching `rarityMultiplier`. * **Atomic**: every step reverts together. If any leg of the migration fails (slippage exceeded, bridge inactive, locked NFT but bypass facet missing, etc.) the whole transaction reverts and you keep your legacy NFT untouched. * **No reward forfeiture**: for locked NFTs, the migrator calls `try oldFacade.claim(tokenId)` before burning so any V2-pending rewards are folded into the staked balance and survive into V3. (Vanilla `burnAndRedeem` on V2 would otherwise silently drop them.) * **No custodial risk**: the migrator never holds funds across transactions. Any rounding dust is recoverable only by the dedicated `RESCUER_ROLE` (multisig). *** ## Steps ### 1. Open the migrate page Go to [primestaking.xyz/xdc-nfts/migrate](https://primestaking.xyz/xdc-nfts/migrate). The page shows your **legacy** XDC NFT balance and your existing **V3** NFT balance side by side. A yellow banner also appears on `/xdc-nfts/my-nfts` if your wallet still holds legacy NFTs. ### 2. Approve the migrator For each legacy NFT you want to migrate, approve [`XdcNftMigratorV2`](/products/contract-addresses) to pull it. The migrate page issues one `approve(migrator, tokenId)` per NFT. ### 3. Set slippage The migrator passes a `minSharesOut` value through to the underlying [`PrimeStakedXDC_V3MigrationBridge`](/products/xdc-liquid-staking/staking-guide/migration) so the migration reverts if the V3 share rate moves unfavourably during execution. The default is **50 bps** (0.5%). Adjust it in the page header if conditions warrant. ### 4. Migrate Click **Migrate** to send a single NFT, or **Migrate All** to batch through `migrateBatch(tokenIds[], minSharesOuts[])`. Confirm the transaction in your wallet. After the transaction lands: * Your **legacy** NFT count drops by the number of NFTs you migrated. * Your **V3** NFT count increases by the same number, with the same `tokenId`s and rarities. * The legacy NFTs are **burned** on the old façade; there is no rollback. * The V3 NFTs are immediately staked in [`XdcNftStakingVault`](/products/contract-addresses) and earning both NAV (from the underlying psXDC v3 shares) and the boost slice (from the Synthetix accumulator). The migrate banner disappears from `/xdc-nfts/my-nfts` once your legacy balance reaches zero. *** ## Locked legacy NFTs If you have a locked legacy NFT, the migrator handles it in the **same** call. Behind the scenes it talks to the [`LegacyMigratorBypassFacet`](/products/xdc-staking-nfts/locked-nft-migration) (added to the legacy Diamond via `diamondCut`) to clear the `tokenLocked` flag, then performs the standard burn + bridge + mint + stake flow. The original `lockEnd` is written to the new NFT so you can't dodge the lock by routing through migration. If the migrator was deployed before the bypass facet was cut in, locked migrations revert with `LegacyDiamondRequiredForLockedNft(tokenId)`. The live deployment has the facet cut in. Unlocked migrations are completely unaffected either way. *** ## What you see in the app afterwards | Surface | What changes | | --------------------- | ---------------------------------------------------------------------------------------------- | | `/xdc-nfts/my-nfts` | The migrated NFT appears in the V3 list with its original `tokenId`. | | `/xdc-nfts/[tokenId]` | The detail page reads from the V3 vault: `stakedShares`, `weight`, pending boost, lock status. | | Migrate page | Migrated NFTs appear under "Your v3 NFTs" with a **Migrated** badge for traceability. | | Activity Log | A `Migrated(user, tokenId, rarity, …)` entry per NFT. | You can interact with your V3 NFT immediately: stake more shares, lock, merge, claim boost, or `burnAndRedeem`. *** ## FAQ **Can I migrate part of an NFT?** No. Migration is one tokenId at a time. You can batch multiple NFTs in a single tx via `migrateBatch`. **Can I roll back?** No. Legacy NFTs are **burned** when migrated. The V3 NFT is functionally equivalent (same rarity, same lock expiry; same `tokenId` unless your legacy id was ≥ `10000`, in which case it is remapped to a `5558–9999` id). **Do I need to claim V2 rewards first?** No. The migrator handles the V2-side claim automatically (best-effort `try claim(tokenId)`) so pending V2 rewards are folded into the staked balance. **What happens to my V2 psXDC staked inside the NFT?** It's redeemed from the old façade, bridged into V3 shares through the [`PrimeStakedXDC_V3MigrationBridge`](/products/xdc-liquid-staking/staking-guide/migration), and staked into the new vault under your new NFT, with the same `tokenId` and rarity. → [Locked NFTs & Legacy Diamond Bypass](/products/xdc-staking-nfts/locked-nft-migration) → [Boost Harvester (technical)](/products/xdc-staking-nfts/boost-harvester) → [Smart Contract Reference (V3)](/products/xdc-staking-nfts/smart-contract-functions) → [Deployed Contracts & Addresses](/products/contract-addresses) # Locked NFTs & Legacy Diamond Bypass Locked legacy XDC NFTs cannot be burnt-and-redeemed through the standard V2 façade, because the `tokenLocked` flag blocks the burn. Without intervention, every locked NFT would be unmigratable until its lock expires. The V3 stack solves this with a tiny facet, [`LegacyMigratorBypassFacet`](/products/contract-addresses), added to the legacy Diamond via `diamondCut`. The facet exposes a single mutator that only the V3 migrator can call, which clears the diamond's `tokenLocked` flag so the standard `burnAndRedeem` succeeds inside the same atomic migration transaction. The diamond custodies the psXDC backing every NFT and pays the redemption from its own reserve; the facet makes **no** external call. {% hint style="info" %} The bypass facet is **live** on the legacy Diamond. The current facet is `0x2786…5e13`, bound to the current migrator `XdcNftMigratorV2` (`0x69DE…2ea8`). Locked migrations work end-to-end through [`/xdc-nfts/migrate`](https://primestaking.xyz/xdc-nfts/migrate) with no extra steps required from the user. {% endhint %} {% hint style="warning" %} **Why the facet was updated.** There are three generations of contracts: the original **v2 staker** (`PrimeStakerV2XDC` `0x2204…B293`), the **legacy Diamond** (the system we migrate *from*), and **V3**. Some Diamond NFTs were themselves migrated v2 → Diamond while locked and carry a historical `lockedFromV2 == true` marker. The original facet treated that marker as *"the funds are still in v2, pull them back via `primeV2.burnToRedeem`."* On-chain inspection (June 2026) showed that is false: the v2 staker has been **drained to \~0**, so `burnToRedeem` reverted, while the Diamond already holds the psXDC. The current facet **removes the v2-staker call entirely**: it just enforces any still-active v2 unlock window, clears `tokenLocked`, and lets the Diamond pay. {% endhint %} *** ## End-to-end flow (locked NFT) ``` User Migrator Old Façade Legacy Diamond (with bypass facet) Vault psXDC v3 │ │ │ │ │ │ │ migrate ─────►│ │ │ │ │ │ │ ownerOf, getNFTData ─►│ │ │ │ │ │ transferFrom(user→me)─► │ │ │ │ │ try claim(tokenId) ──►│ │ // best-effort: folds pending v2 rewards into staked │ │ migratorPrepareForBurn(asset, id) ────────►│ // enforces any live v2 unlock window, then clears tokenLocked │ │ burnAndRedeem(id) ──►│ │ │ │ │ │ …bridge → v3 shares (via PrimeStakedXDC_V3MigrationBridge)… │ │ │ mintAndStakeLocked(user, id, rarity, shares, lockEnd, lockBoost) ────────────►│ │ │ │ MigratedLocked(user, id, …) ⏎ │ │ │ ◄──── user owns new tokenId with original v2 lockEnd preserved on the v3 vault ────────────────┘ ``` All the standard migration guarantees still hold: same `tokenId`, atomic execution, no reward forfeiture, no custodial risk. The only additional step is the `migratorPrepareForBurn` call. *** ## What `migratorPrepareForBurn` actually does The facet has exactly one mutator: ```solidity function migratorPrepareForBurn(address asset, uint256 tokenId) external; ``` * **Caller restriction**: only the configured migrator (`XdcNftMigratorV2`) can call it. The migrator address is baked into the facet at deployment. * **Effect**: clears the `tokenLocked[asset][tokenId]` flag in the legacy Diamond's storage. If the NFT is `lockedFromV2`, it **first** checks the real v2 `unlockTimestamp` and reverts `V2NftStillLocked` if the lock is still active; otherwise it clears the flag. It makes **no** external call (no `primeV2.burnToRedeem`); the Diamond already custodies the psXDC and pays it on `burnAndRedeem`. * **No new privileges**: the facet does not enable anything else. Once `tokenLocked` is cleared, the legacy `burnAndRedeem` flow runs normally. Two informational view selectors are also added in the same cut so the migrator (and indexers) can introspect lock state without storage tricks: | Function | Returns | | ------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `isMigratorBypassNeeded(address asset, uint256 tokenId)` | true if the migrator needs to call `migratorPrepareForBurn` before burning | | `lockedFromV2UnlockTimestamp(address asset, uint256 tokenId)` | the real `lockedFromV2` unlock time (reads storage directly, not via the legacy view) | *** ## The legacy `getNFTData` caveat This is the most important thing to know if you're auditing or debugging the bypass: > The legacy `StakerGetterFacet.getNFTData(asset, tokenId)` view function **synthesises** the returned struct's `lockedData.lockedFromV2` field from the **separate** `tokenLocked[asset][tokenId]` mapping. It does **not** report the storage `lockedFromV2` flag. So a token whose view-returned `lockedFromV2 == true` may actually have been locked via `lockNFT` (storage `lockedFromV2 == false`). The facet reads the **real** storage flag via `LegacyAppStorageMirror`, so its behaviour is independent of the façade aliasing: * For both lock origins it **clears `tokenLocked`** so the burn succeeds. * For genuine storage-`lockedFromV2` tokens it **additionally enforces the original v2 unlock window** (reverting `V2NftStillLocked` if the lock has not yet expired). * In **neither** case does it touch the v2 staker; the Diamond already holds the underlying psXDC and pays it on `burnAndRedeem`. Indexers and integrators that need to know the actual lock origin should use the facet's view functions instead of the legacy `getNFTData` field. *** ## What happens on the V3 side Once the legacy burn succeeds the migrator continues exactly as for an unlocked NFT: bridge the redeemed psXDC into V3 shares, then call: ```solidity mintAndStakeLocked( address to, uint256 tokenId, uint8 rarity, uint256 shares, uint64 lockEnd, // copied from the legacy NFT uint256 lockBoost // configured on the V3 vault ); ``` `lockEnd` is the **original** V2 unlock timestamp. This is the key property: a user cannot dodge the lock by routing through the migrator. On the V3 side, the NFT remains locked (`withdraw`, `merge`, `burnAndRedeem` revert) until the same time it would have unlocked on V2. *** ## What if I migrate a locked NFT *before* `lockEnd`? That's the supported case. The migrator preserves the lock and the V3 vault honours it. You won't be able to `withdraw`, `merge`, or `burnAndRedeem` your V3 NFT until `lockEnd` passes, but you will: * Earn the boost slice on the locked weight (which is higher than the unlocked weight) the entire time. * Earn the base NAV through the underlying psXDC v3 shares. * Be able to `claim` the boost at any time during the lock. After `lockEnd` you can call `unlock(tokenId)` on the V3 vault to remove the lock bonus from the weight, or leave it locked indefinitely to keep the boost slice. *** ## Failure modes (handled by revert) | Condition | Revert | | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Migrator deployed but bypass facet not yet cut into the Diamond | `LegacyDiamondRequiredForLockedNft(tokenId)`; the user keeps the legacy NFT | | A genuine `lockedFromV2` NFT whose original v2 lock has **not** yet expired | `V2NftStillLocked(tokenId, unlockTs)`. The facet refuses to clear the lock early; user keeps the legacy NFT until the lock expires | | Slippage exceeded on the V3 bridge | Whole migration reverts, user keeps the legacy NFT | Every failure mode is "fail closed": the user's legacy NFT remains in place. No mid-state outcomes. *** ## Live deployment | Component | Address | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | Legacy Diamond | [`0x7a5d364b97126600C0AdDFD5C339230748bcaA17`](https://xdcscan.com/address/0x7a5d364b97126600C0AdDFD5C339230748bcaA17) | | Bypass facet (**live**) | [`0x2786D8Df1C38c9D4eD642B84c073349b0f0B5e13`](https://xdcscan.com/address/0x2786D8Df1C38c9D4eD642B84c073349b0f0B5e13) | | Migrator (bound to bypass facet, **live**) | [`0x69DE30161ec0f2e0Dc0649190dB9b93F4c492ea8`](https://xdcscan.com/address/0x69DE30161ec0f2e0Dc0649190dB9b93F4c492ea8) | | Bypass facet (original, superseded) | [`0x275641d5bA81786A7e60352F990F0c203e7D1836`](https://xdcscan.com/address/0x275641d5bA81786A7e60352F990F0c203e7D1836) | | Migrator (original, paused) | [`0x45e2e91098A8451EA450754784e043bb3F8C7dFb`](https://xdcscan.com/address/0x45e2e91098A8451EA450754784e043bb3F8C7dFb) | The original cut was executed by the legacy Diamond's `defaultAdmin` (the protocol multisig). The remediation (June 2026) was rolled out as a `diamondCut` **Replace** swapping the original facet's `migratorPrepareForBurn` implementation for the v2-staker-free version above, a new `XdcNftMigratorV2` with id-remapping, the corresponding role swap (granting `MIGRATOR_ROLE`/`MINTER_ROLE` to the new migrator and revoking the old), and pausing the original migrator. The cut adds only `migratorPrepareForBurn(address,uint256)` (with `isMigratorBypassNeeded` and `lockedFromV2UnlockTimestamp` as informational view selectors). Storage layout is unaffected; no existing selector was modified. → [Migrate XDC NFTs to V3](/products/xdc-staking-nfts/migrate-nfts-v2-to-v3) → [Smart Contract Reference (V3)](/products/xdc-staking-nfts/smart-contract-functions) → [Deployed Contracts & Addresses](/products/contract-addresses) # Boost Harvester (technical) [`XdcNftBoostHarvester`](/products/contract-addresses) is the small, non-upgradeable contract that funds the XDC NFT vault's Synthetix-style boost accumulator. It exists because the underlying [`PrimeStakedXDC_V3_1`](/products/contract-addresses) vault is non-upgradeable, so the boost stream had to live in an external pump rather than being routed inside the V3 vault itself. {% hint style="info" %} Live address: [`0x6a319528111E5e50712Fd2D3d2db8323b119821D`](https://xdcscan.com/address/0x6a319528111E5e50712Fd2D3d2db8323b119821D). The harvester holds the **only** address granted `FEE_ROUTER_ROLE` on the NFT vault, i.e. it's the only contract allowed to call `notifyBoost`. Arbitrary XDC sends to the NFT vault cannot corrupt boost accounting. {% endhint %} *** ## What the harvester does ``` ┌────────────────────────────────────────────────────────────────────────┐ │ XDC sources (treasury / NAV) │ │ │ │ feed(amount) ────────► forwards native XDC directly to notifyBoost │ │ │ │ harvest(sharesToRedeem) ──► redeemWithQueue on psXDC v3 vault ──► │ │ …queued or instant XDC payout… │ │ forwardPending() picks up the XDC and pushes notifyBoost │ └────────────────────────────────────────────────────────────────────────┘ │ ▼ XdcNftStakingVault.notifyBoost(amount) payable - converts XDC → psXDC v3 shares via depositNative - bumps rewardPerWeightStored += sharesMinted * 1e18 / totalWeight - reverts if totalWeight == 0 ``` ### Two funding paths | Path | Function | When to use it | | ----------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Direct push** | `feed(uint256 amount)` payable | Treasury wants to push native XDC straight into the boost stream. Fastest path, no queue involved. | | **NAV harvest** | `harvest(uint256 sharesToRedeem)` | The treasury seeded the harvester with psXDC v3 shares as principal; redeeming those shares captures the NAV gain over time. The XDC may arrive instantly (buffer covers it) or via the queue. | | **Drain pending** | `forwardPending()` | Anyone can call this. Any native XDC sitting on the harvester (e.g. from a queued harvest that just settled) is forwarded into `notifyBoost`. | *** ## How the boost reaches NFT holders When `notifyBoost(x)` runs on the NFT vault: 1. The vault calls `psXDC_v3.depositNative{value: x}(x, vault)` and receives `sharesMinted` of psXDC v3. 2. `rewardPerWeightStored += sharesMinted * 1e18 / totalWeight`. 3. Every staked NFT's pending boost immediately reflects the new value, proportional to the NFT's weight: `earned = info.shares * (rewardPerWeightStored - info.rewardIndex) * weight / 1e18`. 4. `notifyBoost` reverts if `totalWeight == 0`; pushing boost into an empty vault is a no-op so the value can't be wasted. The Synthetix-style accumulator means **timing doesn't matter** as long as your NFT was staked when the push happened. You can claim now, later, or never; the value stays attributed to you. *** ## Why an external harvester The original idea was to fund boost from psXDC v3's own NAV. That would have required adding a "fee skim" feature to the V3 vault. But the V3 vault is deliberately **non-upgradeable** (regular constructor, no proxy) so there is no way to change its logic after deployment. The harvester sidesteps this: * Treasury seeds the harvester with psXDC v3 shares (or directly with XDC). * When NAV has grown, the harvester redeems a portion via `redeemWithQueue` (going through the same instant-vs-queued path every user sees) and the resulting XDC funds the boost. * The V3 vault itself never needs to know about boost; the harvester is the chokepoint. The trade-off is that the harvester needs to be funded by an operator. The cadence is an operational choice: typically a weekly batch is cheapest gas-wise, daily is the friendliest UX. Either way, every `notifyBoost` emits a public event indexed by the subgraph so the UI can derive a trailing 30-day boost APR. *** ## Roles & safety | Role | Holder | Why | | ---------------------------- | ---------------------- | ---------------------------------------------- | | `DEFAULT_ADMIN_ROLE` (vault) | Protocol multisig | Master switch; can grant/revoke other roles | | `FEE_ROUTER_ROLE` (vault) | `XdcNftBoostHarvester` | The only address allowed to call `notifyBoost` | | `PAUSER_ROLE` (harvester) | Protocol multisig | Emergency stop | The NFT vault deliberately has **no `receive()` function**, so there is no way to "donate" XDC into the boost accumulator outside `notifyBoost`. This means random XDC sent to the vault cannot corrupt the accounting; only the harvester's `notifyBoost` calls move `rewardPerWeightStored`. *** ## What integrators can read The harvester is a no-secret contract: every operation is on-chain and emits events. Useful read paths: * **`BoostNotified(uint256 amountIn, uint256 sharesMinted, uint256 rewardPerWeightStored, uint256 totalWeight)`** on the NFT vault, emitted on each push. * **`BoostFed` / `BoostHarvested` / `BoostForwarded`** on the harvester (or equivalent): operational events. * **`earned(tokenId)` view on the NFT vault**: pending boost for a specific NFT. The subgraph at [`xdc-nft-v3-indexer`](https://github.com/PrimeNumbersLabs/xdc-nft-v3-indexer) provides aggregated entities including `BoostNotification`, per-NFT boost stats, and the `DailyProtocolSnapshot` series used by the UI. *** ## Pause behaviour When the NFT vault is paused (`PAUSER_ROLE`), `stake` / `withdraw` / `claim` revert, but **`notifyBoost` continues to work**. This is intentional: boost flow keeps accruing even during an emergency pause, so users don't lose value during ops windows. When the harvester itself is paused, no new pushes happen but pending value on the NFT vault is unaffected. → [Reward Model: Base NAV + Boost](/products/xdc-staking-nfts/xdc-nft-staking-reward-system) → [Staking Mechanics](/products/xdc-staking-nfts/xdc-staking-nfts-mechanics) → [Smart Contract Reference](/products/xdc-staking-nfts/smart-contract-functions) # How to Buy an XDC NFT XDC Staking NFTs are available on the [PrimePort marketplace](https://primeport.xyz). *** ## Step 1 - Set Up Your Wallet Ensure your wallet (e.g., MetaMask) is configured for the XDC Network. If not already set up, add XDC Network as a custom network in your wallet settings. ## Step 2 - Fund Your Wallet Make sure you have enough XDC tokens to cover the NFT price plus gas fees. You can purchase XDC on exchanges like Bitrue or KuCoin. ## Step 3 - Browse the Collection Go to [PrimePort.xyz](https://primeport.xyz) and find the **XDC Staking NFTs** collection. Review each NFT's rarity, staking potential, and price. {% hint style="info" %} Secondary listings may include both **legacy V2** NFTs (collection `0x9D45…76a0`) and **V3** NFTs (collection [`0xf3eB…898E`](https://xdcscan.com/address/0xf3eB62F0Daf98ab65f0696630621A6ecECDB898E)). Both are valid; V2 NFTs can be migrated to V3 at any time. The `tokenId` is preserved across the migration for legacy ids below `10000`; ids ≥ `10000` are remapped into the `5558–9999` band. See [Migrate XDC NFTs to V3](/products/xdc-staking-nfts/migrate-nfts-v2-to-v3). {% endhint %} ## Step 4 - Purchase Connect your wallet, select the NFT you want, click **Buy**, and confirm the transaction. After confirmation, the NFT appears in your profile. *** ## What's Next? Once you own an XDC Staking NFT, deposit psXDC v3 shares into it to start earning the boost slice on top of the underlying NAV. See the [Staking Mechanics](/products/xdc-staking-nfts/xdc-staking-nfts-mechanics) guide for details. If you bought a legacy V2 NFT and want the V3 reward model, run it through the [migrator](/products/xdc-staking-nfts/migrate-nfts-v2-to-v3). It's a one-tx, same-`tokenId` upgrade. *** ## Additional Resources {% embed url="" %} {% embed url="" %} # Trading XDC NFTs XDC Staking NFTs are tradeable on [PrimePort.xyz](https://primeport.xyz). When you sell or transfer an NFT, the buyer inherits all staked psXDC v3 shares, weight, pending boost, and lock status. *** ## Selling 1. Go to [PrimePort.xyz](https://primeport.xyz) and connect your wallet. 2. Select the NFT you want to sell. 3. Set a price or start an auction. 4. Confirm the listing transaction. Unlike the V2 model, V3 does **not** require you to first own 100% of the underlying psXDC. Staked shares live inside the vault under the NFT's `tokenId` and travel with the NFT to the buyer automatically. *** ## Buying 1. Browse the XDC Staking NFTs collection on PrimePort. 2. Review the NFT's rarity, currently staked psXDC v3 shares, current weight, and price. 3. Click **Buy** and confirm the transaction. After purchase, the NFT and its full staking state (`stakedShares`, `level`, `lockEnd`, `rewardIndex`, pending boost) transfer to your wallet. {% hint style="warning" %} Both V2 (legacy) and V3 NFTs may be listed. **V2 NFTs follow the legacy reward model** until they are migrated; **V3 NFTs immediately participate in the boost accumulator**. The collection address is the easiest way to tell them apart: * V2 collection: `0x9D458330e458f11fd1cE7E44B3a66568af8076a0` * V3 collection: [`0xf3eB62F0Daf98ab65f0696630621A6ecECDB898E`](https://xdcscan.com/address/0xf3eB62F0Daf98ab65f0696630621A6ecECDB898E) After buying a V2 NFT you can migrate it to V3 in a single transaction, keeping the same `tokenId` and rarity with lock state preserved. See [Migrate XDC NFTs to V3](/products/xdc-staking-nfts/migrate-nfts-v2-to-v3). {% endhint %} *** ## Transferring 1. Use the standard ERC-721 **Transfer** function on PrimePort or in the PrimeStaking app. 2. Confirm the transaction. In V3 there is **no requirement to hold the underlying psXDC** before transferring; the shares are escrowed inside the vault, not in your wallet. *** ## Important Notes * **Locked NFTs cannot be merged or burnt-and-redeemed** until `lockEnd` has passed, but they **can** still be transferred and traded. * **Pending boost** travels with the NFT. When you transfer, the new owner can call `claim(tokenId)` to settle anything earned up to that point. * **Fees**: PrimePort may charge a small marketplace fee. * **Pricing**: NFT value depends on rarity, staked psXDC shares, level, lock status, and market demand. # Smart Contract Reference (V3) Technical reference for the V3 XDC NFT stack. There are five distinct contracts; users only interact with the **`XdcNftStakingVault`** proxy and (during the migration window) the **`XdcNftMigrator`**. | Contract | Address | Type | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `XdcStakedNFT` | [`0xf3eB62F0Daf98ab65f0696630621A6ecECDB898E`](https://xdcscan.com/address/0xf3eB62F0Daf98ab65f0696630621A6ecECDB898E) | ERC-721 collection, non-upgradeable | | `XdcNftStakingVault` (proxy) | [`0x9f38dF64eeC71e2408B24217b8D621c6B07E4Da8`](https://xdcscan.com/address/0x9f38dF64eeC71e2408B24217b8D621c6B07E4Da8) | TransparentUpgradeableProxy, ERC-7201 storage | | `XdcNftMigratorV2` | [`0x69DE30161ec0f2e0Dc0649190dB9b93F4c492ea8`](https://xdcscan.com/address/0x69DE30161ec0f2e0Dc0649190dB9b93F4c492ea8) | Live one-shot migrator (remaps ids ≥ `10000`), non-upgradeable. Supersedes the paused `XdcNftMigrator` `0x45e2…7dFb`. | | `XdcNftBoostHarvester` | [`0x6a319528111E5e50712Fd2D3d2db8323b119821D`](https://xdcscan.com/address/0x6a319528111E5e50712Fd2D3d2db8323b119821D) | Boost feeder, non-upgradeable | | `LegacyMigratorBypassFacet` | [`0x2786D8Df1C38c9D4eD642B84c073349b0f0B5e13`](https://xdcscan.com/address/0x2786D8Df1C38c9D4eD642B84c073349b0f0B5e13) | Facet added to legacy Diamond `0x7a5d…aA17` | *** ## `XdcNftStakingVault`: the staking engine ### User functions | Function | What it does | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `stake(uint256 tokenId, uint256 shares)` | Pulls `shares` of psXDC v3 from `msg.sender` and stakes them against `tokenId`. Settles pending boost first. Reverts `ExceedsMaxStakePerNft` if the resulting balance would exceed `maxStakePerNft` (default 100,000 psXDC). | | `withdraw(uint256 tokenId, uint256 shares)` | Returns `shares` of psXDC v3 from the NFT to `msg.sender`. Reverts if the NFT is locked. | | `claim(uint256 tokenId, bool unwrap)` | Pays out the NFT's earned boost. If `unwrap == true`, redeems the boost shares to native XDC; otherwise transfers shares. | | `lock(uint256 tokenId, uint64 until)` | Sets `lockEnd`, adds `lockBonus` to the NFT's weight. Disables `withdraw`/`merge`/`burnAndRedeem`. | | `unlock(uint256 tokenId)` | Removes `lockBonus` once `lockEnd` has passed. | | `merge(uint256 tokenIdA, uint256 tokenIdB)` | Burns two same-rarity NFTs, mints one higher-rarity NFT via `XdcStakedNFT.mintMerged`, settles boost on both. Reverts `ExceedsMaxStakePerNft` if the two NFTs' combined shares would exceed `maxStakePerNft`. | | `burnAndRedeem(uint256 tokenId, bool unwrap)` | Burns the NFT and returns the underlying shares (or unwraps them to XDC) in one transaction. | | `notifyBoost(uint256 amount) payable` | **`FEE_ROUTER_ROLE` only** (granted to the harvester). Receives `amount` native XDC, mints psXDC v3 shares, bumps `rewardPerWeightStored`. Reverts if `totalWeight == 0`. | ### Migrator-only functions | Function | Role | What it does | | ------------------------------------------------------------------------------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------ | | `mintAndStake(address to, uint256 tokenId, uint8 rarity, uint256 shares)` | `MIGRATOR_ROLE` | Mints `tokenId` on the collection with the given rarity and immediately stakes `shares` against it for `to`. | | `mintAndStakeLocked(address to, uint256 tokenId, uint8 rarity, uint256 shares, uint64 lockEnd, uint256 lockBoost)` | `MIGRATOR_ROLE` | Same, but preserves the legacy NFT's lock state. | ### Read-only helpers | Function | Returns | | --------------------------- | ---------------------------------------------------------------------------------------- | | `nftState(uint256 tokenId)` | Full state bundle: rarity, stakedShares, level, lockEnd, lockBoost, rewardIndex, weight | | `earned(uint256 tokenId)` | Pending boost earned by the NFT (not yet claimed) | | `totalWeight()` | Global weight across every staked NFT | | `rewardPerWeightStored()` | The Synthetix accumulator's running total | | `maxStakePerNft()` | Per-NFT staked-shares cap in wei (`0` = unlimited). Default 100,000 psXDC = `100000e18`. | | `VAULT_STORAGE_SLOT()` | ERC-7201 namespaced storage slot (constant, for upgrade verification) | ### Admin * `pause()` / `unpause()`: `PAUSER_ROLE`. Halts stake/withdraw/claim; boost can still be received. * `recoverOrphanedShares(uint256 tokenId, address to)`: `DEFAULT_ADMIN_ROLE`, only `whenPaused` and only for burned NFTs. * `setLevelStakedNeeded(...)` / `setLockBoost(...)`: only callable while `totalWeight == 0`. * `setMaxStakePerNft(uint256 maxShares)`: `DEFAULT_ADMIN_ROLE`. Sets the per-NFT stake cap (`0` disables it). Settable at any time; only gates future `stake`/`merge` and never touches existing balances (over-cap NFTs are grandfathered). Migrator mint paths are exempt. See [Per-NFT stake cap](/products/xdc-staking-nfts/xdc-staking-nfts-mechanics#per-nft-stake-cap). *** ## `XdcStakedNFT`: the collection | Function | Role | Purpose | | ------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mintWithId(address to, uint256 tokenId, uint8 rarity)` | `MINTER_ROLE` (granted to migrator) | Mints a legacy-tokenId NFT. **Reverts `TokenIdOutOfRange` for `tokenId == 0` or `tokenId ≥ 10000`**, since the `≥ 10000` band is reserved for merges. This is exactly why `XdcNftMigratorV2` remaps high legacy ids before minting. | | `mintMerged(address to, uint8 rarity)` | `MINTER_ROLE` (granted to vault) | Mints a fresh higher-rarity NFT (10000+ range). | | `burn(uint256 tokenId)` | `MINTER_ROLE` | Used by `merge` and `burnAndRedeem` flows. | | `setRarityURI(uint8 rarity, string uri)` | `URI_SETTER_ROLE` | Updates the per-rarity `tokenURI` | | `rarityOf(uint256 tokenId)` | view | Per-token rarity | The collection is **non-upgradeable**. *** ## `XdcNftMigratorV2`: the live V2 → V3 migrator The live migrator is **`XdcNftMigratorV2`** (`0x69DE…2ea8`). It is a drop-in successor to the original `XdcNftMigrator` (now paused) that adds **legacy-id remapping**. Same `migrate` / `migrateBatch` surface; the only behavioural change is for legacy ids ≥ `10000`. | Function | Notes | | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `migrate(uint256 oldTokenId, uint256 minSharesOut)` | One-shot migration of a single legacy NFT. Caller must `approve(migrator, oldTokenId)` first. | | `migrateBatch(uint256[] tokenIds, uint256[] minSharesOuts)` | Loop wrapper. `msg.sender` stays the user (audit fix C-3). | | `legacyDiamond()` | The legacy Diamond address (`0x7a5d…aA17`), required for locked-NFT migration. | | `oldFacade()` | The legacy ERC-721 façade address (`0x9D45…76a0`). | **Id remapping.** `XdcStakedNFT.mintWithId` rejects ids ≥ `10000` (reserved for merges), so a legacy NFT minted in that band could never be minted 1:1. `XdcNftMigratorV2` detects `oldTokenId ≥ 10000`, allocates a free id in the `5558–9999` reserve band, mints the v3 NFT under that **new** id, and emits `LegacyIdRemapped(oldTokenId, newTokenId)`. Rarity, staked value, and lock state are preserved; only the numeric id changes, and only for the \~21 affected legacy NFTs. Every legacy id below `10000` is still preserved 1:1. Locked NFTs revert with `LegacyDiamondRequiredForLockedNft(tokenId)` if `legacyDiamond == address(0)` (i.e. the migrator was deployed before the bypass facet was cut in). Migration mechanics in detail: [Migrate XDC NFTs to V3](/products/xdc-staking-nfts/migrate-nfts-v2-to-v3). Locked-NFT specifics: [Locked NFTs & Legacy Diamond Bypass](/products/xdc-staking-nfts/locked-nft-migration). *** ## `XdcNftBoostHarvester`: the boost pipe | Function | Role | Purpose | | --------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `feed(uint256 amount) payable` | treasury | Directly forwards `amount` native XDC into `vault.notifyBoost`. | | `harvest(uint256 sharesToRedeem)` | treasury | Redeems `sharesToRedeem` of psXDC v3 through `redeemWithQueue`; the resulting XDC is forwarded to `notifyBoost`. | | `forwardPending()` | anyone | Pushes any XDC sitting in the harvester (e.g. from queued redemption settling) into `notifyBoost`. | Full design write-up: [Boost Harvester (technical)](/products/xdc-staking-nfts/boost-harvester). *** ## `LegacyMigratorBypassFacet`: diamond facet Added to the legacy Diamond via `diamondCut`. Only one mutator, only callable by the migrator: | Function | Caller | Purpose | | ------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `migratorPrepareForBurn(address asset, uint256 tokenId)` | migrator only | Clears the diamond's `tokenLocked` flag so `burnAndRedeem` succeeds on a locked NFT. For `lockedFromV2` NFTs it first enforces the original v2 `unlockTimestamp` guard (a still-active lock cannot escape), then clears the flag. It makes **no** external call: the diamond custodies the psXDC and pays from its own reserve. *(The original facet called `primeV2.burnToRedeem` here; that path was removed because the v2 staker is drained to \~0, so the call reverted and was never needed.)* | | `isMigratorBypassNeeded(address asset, uint256 tokenId)` | view | Informational. Returns true if the migrator needs to call `migratorPrepareForBurn` before burning. | | `lockedFromV2UnlockTimestamp(address asset, uint256 tokenId)` | view | Reads the real `lockedFromV2` unlock time from legacy storage. | The facet reads via `LegacyAppStorageMirror`, which exposes the **actual** storage flag rather than the façade-synthesised view. This matters because the legacy `StakerGetterFacet.getNFTData` view can misreport `lockedFromV2`. See [Locked NFTs & Legacy Diamond Bypass](/products/xdc-staking-nfts/locked-nft-migration) for the full caveat. *** ## Events worth indexing | Event | Contract | When | | ----------------------------------------------------------------------------------------------------------- | -------------------------- | ----------------------------------------------------------- | | `Staked` / `Withdrawn` / `Claimed` / `Locked` / `Merged` / `BurnedAndRedeemed` | vault | Standard user actions | | `MaxStakePerNftSet(uint256 maxShares)` | vault | Per-NFT stake cap changed (`0` = disabled) | | `BoostNotified(uint256 amountIn, uint256 sharesMinted, uint256 rewardPerWeightStored, uint256 totalWeight)` | vault | Each `notifyBoost`; drives boost APR calculation | | `MintedAndStaked` / `MintedAndStakedLocked` | vault | Migrator created a new NFT | | `Migrated` / `MigratedLocked` | migrator | One-shot migration completed | | `LegacyIdRemapped(uint256 oldTokenId, uint256 newTokenId)` | migrator (V2) | A legacy id ≥ `10000` was remapped to a free `5558–9999` id | | `MigratorBypassPrepared` | legacy diamond (via facet) | Confirms the bypass facet routed the call | → [Deployed Contracts & Addresses](/products/contract-addresses) → [Staking Mechanics](/products/xdc-staking-nfts/xdc-staking-nfts-mechanics) → [Reward Model](/products/xdc-staking-nfts/xdc-nft-staking-reward-system) # Deployed Contracts & Addresses Canonical address book for PrimeStaking V3.2, covering the psXDC vault, airdrop distributor, referral program, XDC NFT v3 stack, spot venue, and legacy contracts. {% hint style="info" %} All V3.2 contracts are live on **XDC Mainnet (chain ID `50`)**. In July 2026 the protocol redeployed the liquid-staking vault as **`PrimeStakedXDC_V3_2`** and mirrored every V3.1 holder's balance into it 1:1 via a snapshot airdrop; no user action was required. The XDC NFT vault was repointed to the V3.2 token in the same operation. See [V2 vs V3: What Changed](/products/xdc-liquid-staking/v2-vs-v3). {% endhint %} This page is the single source of truth for every address the V3.2 stack interacts with. The UI, indexer, and partner integrations are all wired against the addresses listed here. *** ## V3.2: XDC Liquid Staking (psXDC) | Contract | Address | Type | Notes | | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`PrimeStakedXDC_V3_2`** | [`0xDc74c0DaED82ae94486DeeF22991d2F54173c734`](https://xdcscan.com/address/0xDc74c0DaED82ae94486DeeF22991d2F54173c734) | ERC-4626 vault (native XDC) | **The live psXDC token and vault.** Non-upgradeable, deployed with a regular constructor, no proxy. All staking, withdrawals, and share-price reads go here. Permanent-ledger model: rewards accrue at any backing level via the manager reward lane. | | **`V32AirdropDistributor`** | [`0x9ADb9Dfc340375113042b4722e780D34B1123e47`](https://xdcscan.com/address/0x9ADb9Dfc340375113042b4722e780D34B1123e47) | Airdrop distributor (**finalized**) | Batch-minted the snapshot balances of every V3.1 holder onto V3.2 at launch. Permanently finalized; it can never mint again. Kept for on-chain audit trail. | | **`PrimeStakedXDC_V3_2MigrationBridge`** (v2 → V3.2) | [`0x313e8d6Ad3D16be6318dF2AF5a54A87Aea42c280`](https://xdcscan.com/address/0x313e8d6Ad3D16be6318dF2AF5a54A87Aea42c280) | Migration bridge | For V2 stragglers only: burns V2 psXDC and mints V3.2 shares 1:1. It never accepts V3.1 (the airdrop already credited every V3.1 holder 1:1). The vault's `migrationBridge` repoint to this address is scheduled behind the 24h governance timelock; migration reopens in the app once it executes. | ## Referral program | Contract | Address | Type | Notes | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`ReferralRegistry`** | [`0x9765BE3fd9e0d450bD46Ef2A30A0Feb4B15616B3`](https://xdcscan.com/address/0x9765BE3fd9e0d450bD46Ef2A30A0Feb4B15616B3) | Referral binder | `stakeWithReferral(referrer)` binds one immutable referrer to the caller and forwards the stake to the vault in one transaction. Minimum bind stake: 100 XDC. | | **`ReferralRewards`** | [`0xD910E7E0dC457Ccd425E9a5cF716b0F6B7045549`](https://xdcscan.com/address/0xD910E7E0dC457Ccd425E9a5cF716b0F6B7045549) | Epoch Merkle distributor | Pays referrer fee-share per epoch against a posted Merkle root. Roots are immutable per epoch and can never be posted underfunded. | ## Superseded liquid-staking vaults (do not use) | Contract | Address | Status | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PrimeStakedXDC_V3_1` (prior vault) | [`0xa7FD1c5601348633018003C90aE568d1ff7973e4`](https://xdcscan.com/address/0xa7FD1c5601348633018003C90aE568d1ff7973e4) | **Superseded and paused.** Every holder balance at the snapshot was mirrored 1:1 onto V3.2. The V3.1 token is frozen and has no further function. | | `PrimeStakedXDC_V3` (original vault) | [`0x98D916F5773Ac0482b49856f2659d6c32114C4Ba`](https://xdcscan.com/address/0x98D916F5773Ac0482b49856f2659d6c32114C4Ba) | **Superseded and paused** (July 8, 2026: transfers frozen after residual dead-token trading was observed on abandoned pools). Every V3 balance was mirrored 1:1 onto the live token at the snapshot. On XDC this address is the retired token — do not confuse it with the psXDC OFT, which uses the same address on **other** chains. | | `V31AirdropDistributor` | [`0x3b7185844451a57CC45807243477e442ff1A3553`](https://xdcscan.com/address/0x3b7185844451a57CC45807243477e442ff1A3553) | The prior (V3 → V3.1) airdrop distributor, finalized. | *** ## V3: XDC NFTs The NFT vault proxy was upgraded in place during the V3.2 cutover, so the user-facing addresses (collection + vault proxy) are unchanged. The vault now holds psXDC V3.2 shares and supports multiple lock tiers with expiring boosts. | Contract | Address | Type | Notes | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`XdcStakedNFT`** | [`0xf3eB62F0Daf98ab65f0696630621A6ecECDB898E`](https://xdcscan.com/address/0xf3eB62F0Daf98ab65f0696630621A6ecECDB898E) | ERC-721 collection | **Non-upgradeable**. Stores rarity on-chain; migrated NFTs preserve their legacy `tokenId` (except legacy ids ≥ `10000`, which the migrator remaps into the `5558–9999` band). | | **`XdcNftStakingVault`** (proxy) | [`0x9f38dF64eeC71e2408B24217b8D621c6B07E4Da8`](https://xdcscan.com/address/0x9f38dF64eeC71e2408B24217b8D621c6B07E4Da8) | TransparentUpgradeableProxy | User-facing vault for stake / withdraw / claim / lock / merge / `burnAndRedeem`. Uses ERC-7201 namespaced storage. Now holds psXDC **V3.2** shares. | | `XdcNftStakingVault` implementation | [`0xF39b759c03B593C34d2905E0991F2cf45d8D148B`](https://xdcscan.com/address/0xF39b759c03B593C34d2905E0991F2cf45d8D148B) | Vault logic | Upgraded July 2026 for the V3.2 cutover: repoints psXDC via `migrateV3Token`, adds multi-tier locks (30/90/180/365 days) with **boost expiry**, and a permissionless `pokeExpired` keeper hook. Always interact with the proxy above, not this address. | | Vault `ProxyAdmin` | [`0xCE17925533C570B3EE5621Df39019b1a5785fb3d`](https://xdcscan.com/address/0xCE17925533C570B3EE5621Df39019b1a5785fb3d) | Proxy admin | Owned by the protocol multisig. | | **`XdcNftMigratorV2`** (V3.1 wiring) | [`0x69DE30161ec0f2e0Dc0649190dB9b93F4c492ea8`](https://xdcscan.com/address/0x69DE30161ec0f2e0Dc0649190dB9b93F4c492ea8) | Migrator (**live**) | The active one-shot migrator: burns legacy NFT → bridges psXDC through the v2 → V3.1 bridge → mints + stakes new NFT. Remaps legacy ids ≥ `10000` into `5558–9999`, emitting `LegacyIdRemapped`. **Non-upgradeable**. | | **`XdcNftBoostHarvester`** (V3.1 wiring) | [`0x6a319528111E5e50712Fd2D3d2db8323b119821D`](https://xdcscan.com/address/0x6a319528111E5e50712Fd2D3d2db8323b119821D) | Boost pipe | Funds the Synthetix-style boost accumulator via `notifyBoost`. **Non-upgradeable**. | | **`LegacyMigratorBypassFacet`** (V3.1 wiring) | [`0x2786D8Df1C38c9D4eD642B84c073349b0f0B5e13`](https://xdcscan.com/address/0x2786D8Df1C38c9D4eD642B84c073349b0f0B5e13) | Diamond facet (**live**) | Added to the legacy Diamond via `diamondCut` so locked legacy NFTs migrate in a single transaction. Clears the diamond's `tokenLocked` flag and lets the diamond's own `burnAndRedeem` pay the psXDC. | ### Superseded NFT-stack contracts (roles revoked, do not use) | Contract | Address | Status | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | Old `XdcNftMigratorV2` (V3 wiring) | [`0x36Fe37Ca1FEF0e409977a1c28d191B55333cf026`](https://xdcscan.com/address/0x36Fe37Ca1FEF0e409977a1c28d191B55333cf026) | `MINTER_ROLE` / `MIGRATOR_ROLE` revoked at the V3.1 cutover. | | Old `XdcNftBoostHarvester` | [`0x3bEdb37FC873F64BEeFCA551b3A836e59fc18DeA`](https://xdcscan.com/address/0x3bEdb37FC873F64BEeFCA551b3A836e59fc18DeA) | `FEE_ROUTER_ROLE` revoked at the V3.1 cutover. | | Old `LegacyMigratorBypassFacet` | [`0x64413bAD206b5D90a5010cc683F50086407F25C6`](https://xdcscan.com/address/0x64413bAD206b5D90a5010cc683F50086407F25C6) | Replaced on the legacy Diamond via `diamondCut`. | | Original `XdcNftMigrator` | [`0x45e2e91098A8451EA450754784e043bb3F8C7dFb`](https://xdcscan.com/address/0x45e2e91098A8451EA450754784e043bb3F8C7dFb) | Paused and replaced in June 2026. | *** ## Spot Trading (psXDC/XDC DEX) The protocol-owned spot venue behind [primestaking.xyz/spot](https://primestaking.xyz/spot). The factory and router are token-agnostic and carried over from the original deployment; the pair and limit-order book were redeployed against V3.2 in July 2026. | Contract | Address | Type | Notes | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **psXDC/WXDC pair (V3.2)** | [`0x60189924A43947bE7Bf0350E81be0D2f00D95034`](https://xdcscan.com/address/0x60189924A43947bE7Bf0350E81be0D2f00D95034) | UniswapV2Pair | The live trading pool, seeded at NAV (1:1). Holds V3.2 psXDC and canonical WXDC. | | **`SpotLimitOrders`** (V3.2) | [`0xcd81d7d83101884D0B070153A0EBC9cD6C14f6B9`](https://xdcscan.com/address/0xcd81d7d83101884D0B070153A0EBC9cD6C14f6B9) | Limit-order book | Non-custodial on-chain limit orders settled against the pair. Makers can always cancel for a full refund of unfilled escrow. | | `UniswapV2Router02` | [`0xf77440C4Dc3Dcd5Bb93DaA863BF93Fc306EC0791`](https://xdcscan.com/address/0xf77440C4Dc3Dcd5Bb93DaA863BF93Fc306EC0791) | Router | Swap and liquidity entry point; wired to the canonical WXDC. | | `UniswapV2Factory` | [`0x3a718EB1b4b06968F78a0a3b7e3dF07037E83f5d`](https://xdcscan.com/address/0x3a718EB1b4b06968F78a0a3b7e3dF07037E83f5d) | Factory | PrimeStaking-owned; created every pair. | | `WXDC` (canonical) | [`0x951857744785E80e2De051c32EE7b25f9c458C42`](https://xdcscan.com/address/0x951857744785E80e2De051c32EE7b25f9c458C42) | Wrapped XDC | Shared network-wide wrapper, not operated by PrimeStaking. | ### Superseded spot contracts (do not use) | Contract | Address | Status | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | psXDC/WXDC pair (V3.1) | [`0x14A11af8980ea7e18B18cAbf4721B61586Bab087`](https://xdcscan.com/address/0x14A11af8980ea7e18B18cAbf4721B61586Bab087) | Holds the now-frozen V3.1 token. LPs were credited their psXDC side in the V3.2 snapshot airdrop; because V3.1 is frozen the pool can no longer be unwound on-chain, so the remaining WXDC leg is refunded manually via the migration-exit page. | | `SpotLimitOrders` (V3.1) | [`0x89dB7715fFc5B8b2C4A604BdD49b006df201247a`](https://xdcscan.com/address/0x89dB7715fFc5B8b2C4A604BdD49b006df201247a) | **Paused.** SELL escrow (psXDC) was migrated to V3.2 in the airdrop; BUY orders escrow native XDC and can still be cancelled for a full refund. | | Old psXDC/WXDC pair (V3) | [`0x43a4557d0AF08929680387B2A6edae8068C02FE6`](https://xdcscan.com/address/0x43a4557d0AF08929680387B2A6edae8068C02FE6) | Retired original-V3 pool. | *** ## Partner Staking These power the white-label [Partner Staking](/partner-staking/partner-staking) product. The registry is shared; each partner pool is its own independent `PartnerStakedXDC_V3` deployment, so pool addresses are discovered dynamically via the registry rather than hard-coded here. | Contract | Address | Type | Notes | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`PartnerVaultRegistry`** | [`0x325DEEA5C7c0Ce0D774c4A67EcCaAf1cF8953a67`](https://xdcscan.com/address/0x325DEEA5C7c0Ce0D774c4A67EcCaAf1cF8953a67) | Registry (`Ownable2Step`) | On-chain directory of partner pools. Codehash-gated registration; PrimeStaking curates which pools are **Verified**. Enumerate pools via `allVaults()` / `verifiedVaults()`. | | `PartnerStakedXDC_V3` (per partner) | *discover via registry* | ERC-4626 vault (native XDC) | Each partner deploys their own pool. Identical runtime bytecode (15% fee constant) so the registry can verify it by `codehash`. | *** ## Multi-chain: psXDC OFT bridge + rate oracle psXDC bridges to Base, Arbitrum, and BNB Chain via LayerZero V2. The [bridge](/products/xdc-liquid-staking/bridge) uses a lockbox on XDC; the [rate oracle](/products/xdc-liquid-staking/psxdc-rate-oracle) publishes the psXDC/XDC exchange rate to each chain for lending integrations. | Contract | Chain | Address | Notes | | ----------------- | --------- | -------------------------------------------- | ------------------------------------------------------------------------------------- | | `PsxdcOFTAdapter` | XDC | `0xefbb71078cba6425EB6fd957ac1F8a235502D71a` | Lockbox: locks/unlocks real psXDC. One canonical adapter for the whole mesh. | | `PsxdcRateSender` | XDC | `0x7215e3a0a1F385127eAC1E84D2F30dBF00c76b04` | Broadcasts `previewRedeem(1e18)` to all destination oracles. Permissionless `push()`. | | `PsxdcOFT` | Base | `0x98D916F5773Ac0482b49856f2659d6c32114C4Ba` | Mint/burn psXDC representation. | | `PsxdcOFT` | Arbitrum | `0x98D916F5773Ac0482b49856f2659d6c32114C4Ba` | Same address (deployed at matching nonce). | | `PsxdcOFT` | BNB Chain | `0x98D916F5773Ac0482b49856f2659d6c32114C4Ba` | Same address. | | `PsxdcOFT` | HyperEVM | `0x98D916F5773Ac0482b49856f2659d6c32114C4Ba` | Same address. | | `PsxdcRateOracle` | Base | `0x2927630dfDd66433DbA9370b316EF5a8408d5dD2` | `AggregatorV3Interface` psXDC/XDC rate for money markets. | | `PsxdcRateOracle` | Arbitrum | `0x2927630dfDd66433DbA9370b316EF5a8408d5dD2` | Same address. | | `PsxdcRateOracle` | BNB Chain | `0x2927630dfDd66433DbA9370b316EF5a8408d5dD2` | Same address. | | `PsxdcRateOracle` | HyperEVM | `0x2927630dfDd66433DbA9370b316EF5a8408d5dD2` | Same address. | Every pathway is verified by four required DVNs (Canary, LayerZero Labs, Horizen, Nethermind) — the same operator set that services the live XDC lanes. LayerZero endpoint IDs: XDC 30365, Base 30184, Arbitrum 30110, BNB Chain 30102, HyperEVM 30367. *** ## Legacy (V2) | Contract | Address | Role | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Legacy Diamond (ERC-2535) | [`0x7a5d364b97126600C0AdDFD5C339230748bcaA17`](https://xdcscan.com/address/0x7a5d364b97126600C0AdDFD5C339230748bcaA17) | Host of all legacy XDC NFT facets. Also hosts the live `LegacyMigratorBypassFacet` (`0x2786…5e13`) for one-tx migration. | | Drained v2 staker (`PrimeStakerV2XDC`) | [`0x2204E4Db4D45A290e284daa6f6fb52273593B293`](https://xdcscan.com/address/0x2204E4Db4D45A290e284daa6f6fb52273593B293) | The original v2 XDC staker. Drained to \~0; retained for reference only. | | Legacy ERC-721 façade | [`0x9D458330e458f11fd1cE7E44B3a66568af8076a0`](https://xdcscan.com/address/0x9D458330e458f11fd1cE7E44B3a66568af8076a0) | The user-visible NFT contract behind the V2 XDC NFTs. | | Legacy psXDC v2 (proxy) | [`0x9B8e12b0BAC165B86967E771d98B520Ec3F665A6`](https://xdcscan.com/address/0x9B8e12b0BAC165B86967E771d98B520Ec3F665A6) | The V2 psXDC ERC-20 token. Use this address when approving the v2 → V3.1 migration bridge. | *** ## Quick reference for integrators If you are integrating PrimeStaking from a partner application, the only contracts you ever call directly are: * `PrimeStakedXDC_V3_2` (`0xDc74…c734`) to stake, withdraw, redeem, or read the share price. * `PrimeStakedXDC_V3_2MigrationBridge` (`0x313e…c280`), only if your users hold V2 psXDC and want to migrate. * `ReferralRegistry` (`0x9765…16B3`), only if you want a first stake to bind a referrer (`stakeWithReferral`). * `XdcNftStakingVault` (proxy, `0x9f38…4da8`) for any NFT-side action. * `XdcNftMigratorV2` (`0x69DE…2ea8`), only for migrating legacy V2 NFTs. The harvester, bypass facet, distributor, vault implementation, and ProxyAdmin are operated by the protocol and do not need to be called from partner code. → [V3 Architecture](/products/xdc-liquid-staking/v3-architecture) → [Smart Contract Reference (psXDC v3)](/products/xdc-liquid-staking/smart-contract-functions) → [Smart Contract Reference (XDC NFT v3)](/products/xdc-staking-nfts/smart-contract-functions) # DEX Liquidity & Spot Trading psXDC can be traded against XDC on-chain, and liquidity providers can earn fees by supplying both sides of the pool. The primary venue is **PrimeStaking Spot** at [primestaking.xyz/spot](https://primestaking.xyz/spot). It runs on a protocol-owned Uniswap V2 style pool holding the live V3.2 psXDC and wrapped XDC, with market swaps and on-chain limit orders settled by a keeper. {% hint style="warning" %} **Post-V3.1 note (July 2026):** DEX pools created before the V3.1 redeployment hold the retired old-V3 token and are no longer valid. LP positions in those pools were credited in the snapshot airdrop, so LPs received their share of the pool's psXDC directly on V3.1. Before trading or LPing anywhere, verify the pool's psXDC address is the live V3.2 token: [`0xDc74c0DaED82ae94486DeeF22991d2F54173c734`](https://xdcscan.com/address/0xDc74c0DaED82ae94486DeeF22991d2F54173c734). {% endhint %} {% hint style="info" %} The psXDC share token is **NAV-based**, not a fixed 1:1 receipt. The market price on a DEX is set by AMM dynamics and may sit at, above, or below the vault's current exchange rate (`totalAssets / totalShares`). Long-term it tracks NAV; short-term it reflects supply, demand, and pool depth. {% endhint %} *** ## The Spot venue at a glance | Contract | Address | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | psXDC/WXDC pair (V3.1) | [`0x14A11af8980ea7e18B18cAbf4721B61586Bab087`](https://xdcscan.com/address/0x14A11af8980ea7e18B18cAbf4721B61586Bab087) | | SpotLimitOrders (V3.1) | [`0x89dB7715fFc5B8b2C4A604BdD49b006df201247a`](https://xdcscan.com/address/0x89dB7715fFc5B8b2C4A604BdD49b006df201247a) | | Router (UniswapV2Router02) | [`0xf77440C4Dc3Dcd5Bb93DaA863BF93Fc306EC0791`](https://xdcscan.com/address/0xf77440C4Dc3Dcd5Bb93DaA863BF93Fc306EC0791) | | Factory (UniswapV2Factory) | [`0x3a718EB1b4b06968F78a0a3b7e3dF07037E83f5d`](https://xdcscan.com/address/0x3a718EB1b4b06968F78a0a3b7e3dF07037E83f5d) | The pool was seeded at NAV (1 psXDC : 1 XDC at launch of V3.1). Limit orders are non-custodial: makers escrow only their unfilled input, the contract enforces the maker's price on every fill, and orders can always be cancelled for a full refund of the remaining escrow. *** ## Why Provide Liquidity? | Reason | Detail | | ------------------------------ | --------------------------------------------------------------------------------------------------------- | | **Enable trading** | A liquid psXDC/XDC pool allows seamless swaps between the two tokens. | | **Earn fees** | Liquidity providers earn trading fees on every swap in the pool. | | **Support the ecosystem** | Deep liquidity strengthens psXDC utility and adoption, including as DeFi collateral. | | **Earn appreciating exposure** | Half of your LP position is psXDC, whose NAV grows over time as the V3.1 vault accrues validator rewards. | *** ## How to Trade on PrimeStaking Spot 1. Go to [primestaking.xyz/spot](https://primestaking.xyz/spot) and connect your wallet. 2. **Market orders** swap immediately against the pool at the current price. 3. **Limit orders** rest on-chain until the pool price reaches your limit; a keeper then settles them automatically. You can cancel an open order at any time and the unfilled escrow is refunded in full. ## How to Add Liquidity Liquidity for the psXDC/WXDC pair is added through the router contract. If you use a third-party DEX UI instead, verify the pool's `psXDC` token address matches the live V3.2 vault ([`0xa7FD…73e4`](https://xdcscan.com/address/0xDc74c0DaED82ae94486DeeF22991d2F54173c734)) before depositing. Older pools hold the retired old-V3 token (`0x98D9…C4Ba`) or the legacy V2 token (`0x9B8e…65A6`). When adding liquidity, remember that the **value** of 1 psXDC is not 1 XDC; it equals the current vault exchange rate, and pool ratios follow the market price. *** ## Managing Your Position * **Monitor NAV vs market price.** psXDC's protocol NAV grows over time. The DEX pool may not always track NAV in real-time; sustained gaps create arbitrage opportunities. * **Impermanent loss.** Be aware of IL risk if the NAV and pool ratio diverge significantly. * **Rebalance.** Add or withdraw liquidity periodically to maintain an optimal position. * **Trading fees** accrue automatically in your LP position. Withdraw LP tokens to claim. *** ## Withdrawing Liquidity Burn your LP tokens through the router (or the DEX UI you used to deposit) to receive your share of psXDC and WXDC plus accrued fees. {% hint style="info" %} **Held LP tokens in the old (pre-V3.1) pool?** Your psXDC side was already credited in the snapshot airdrop. The WXDC side is still yours: remove liquidity from the old pair to recover it. The old psXDC you receive alongside it is the retired token and can be ignored. {% endhint %} *** ## Protocol vs DEX exit: when to use which | Path | When to use | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | **DEX swap (psXDC → XDC)** | You need XDC immediately and are willing to accept the current market price (which may include a small discount or premium to NAV). | | **Protocol redeem (`redeemWithQueue`)** | You want the exact NAV value; settles instantly when the vault buffer covers it, otherwise via the on-chain FIFO queue. | See [Withdrawals: Instant vs Queued](/products/xdc-liquid-staking/staking-guide/withdrawals-instant-vs-queued) for how the protocol path chooses between instant and queued settlement. *** ## Best Practices * Stay informed on staking rewards and market activity. * Diversify across pools to mitigate risk. * Compound returns by reinvesting trading fees. * Follow [PrimeStaking](https://primestaking.xyz) for pool parameter changes. # FAQs ### General Questions #### What is XDC Liquid Staking? **XDC Liquid Staking** enables you to stake XDC **while retaining full liquidity**. Instead of locking up your tokens, you receive psXDC (Prime Staked XDC), an ERC-4626 vault share that can be freely used or traded in DeFi. * **XDC Liquid Staking:** A straightforward way to stake XDC and receive psXDC vault shares, with no minimum required. Earns \~5.5% APY through share-price appreciation. * **XDC NFTs:** Deposit psXDC shares inside XDC NFTs to layer a boost slice on top of the base NAV. **Floor stays at the base \~5.5%** (always earned, regardless of rarity / lock / boost cadence); when the boost stream is flowing, the combined APY ranges from **\~5.75% (unlocked)** up to **\~7% (locked)**. #### What is psXDC? psXDC is an **ERC-4626 vault share** representing your position in the V3 staking vault. You don't claim rewards separately. The share grows in value over time (`totalAssets / totalShares` increases as validator rewards accrue), so each psXDC is worth more XDC the longer you hold it. #### Where can I trade psXDC? psXDC can be traded on DEXs on the XDC Network, paired with XDC. **After the July 2026 V3.1 redeployment, verify any pool holds the live token** ([`0xDc74…c734`](https://xdcscan.com/address/0xDc74c0DaED82ae94486DeeF22991d2F54173c734)); pools created before the redeployment hold retired tokens. Purchasing psXDC directly also benefits you, since holding it means owning the appreciating share. #### Can I use psXDC outside the XDC Network? Yes. psXDC bridges to **Base, Arbitrum, BNB Chain, and HyperEVM** via LayerZero from the [Bridge page](https://primestaking.xyz/xdc-liquid-staking/bridge) — no third-party custodian, no bridge fee beyond the LayerZero message cost, and your staking yield keeps accruing while bridged. On Base and HyperEVM it is already listed as collateral on [PrimeFi](https://primefi.xyz), so you can lend it or borrow against it without unstaking. See [Bridge psXDC](/products/xdc-liquid-staking/bridge) and [Multichain Opportunities](/products/xdc-liquid-staking/multichain-opportunities). #### I held psXDC V3 before July 2026. Do I need to do anything? No. The vault was redeployed as **V3.1** and every V3 balance was mirrored 1:1 via an on-chain snapshot airdrop, including psXDC inside XDC NFTs, DEX pools, lending markets, and open limit orders, which were credited to their underlying owners. Your balance appears automatically in the app. The old V3 token is retired and has no remaining function. #### Why were migrations briefly unavailable during the V3.1 cutover (July 3-4, 2026)? By design. During the cutover the V2 token was paused and the final activation steps (retiring the old V3 bridge and pointing the V3.1 vault at the new migration bridge) sat behind a 24-hour on-chain timelock, a deliberate safety window that made it impossible for anyone to migrate into the retired old V3 token by mistake. Once the timelock matured on July 4 the bridge was activated, V2 was unpaused, and both token and NFT migrations reopened. No funds were ever at risk and nothing expired during the window. #### What happens when I unstake? When you decide to unstake, you burn the corresponding psXDC shares. The app calls `redeemWithQueue` which: * **Settles instantly** when the vault's unencumbered liquidity covers your request. XDC returns to your wallet in the same transaction. * **Enters a permissionless FIFO queue** otherwise: your shares are escrowed and a request is created. As soon as liquidity is replenished (new deposits, reward inflows, masternode resignations) the queue settles your request. For very large redemptions the upper bound is the network's `candidateWithdrawDelay`, approximately **\~35 days** under typical block times. Expectation-setting: when a queue backlog exists (e.g. right after a migration, while masternodes unwind), free liquidity is usually thin and **most withdrawals will take the queued path** — instant service is the exception during those periods, not the rule. For an immediate exit at market price you can always sell psXDC on a DEX instead. You can cancel queued requests any time, and if a payout ever fails the XDC lands in `pendingQueuedAssets` so you can collect it via `claimQueuedAssets`. Note that a queued request's XDC amount is **fixed at the moment you queue** (at that day's exchange rate) — reward distributions that land while you wait don't increase the payout. Cancelling returns your shares (which do carry appreciation), at the cost of your queue position. → [Withdrawals: Instant vs Queued](/products/xdc-liquid-staking/staking-guide/withdrawals-instant-vs-queued) #### Can I transfer my staking position? Yes. * **Liquid Staking:** Send psXDC to another address; the recipient inherits the appreciating share. No further action needed. * **XDC NFTs:** If your psXDC is staked inside an XDC NFT, you can sell or transfer the NFT via [PrimePort.xyz](https://primeport.xyz). The new owner inherits the staked shares, pending boost, and any lock status. #### How are rewards distributed? | Product | Base reward | How you receive it | | ---------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | | **XDC Liquid Staking** | \~5.5% via psXDC share-price growth | **Automatic**, with no claim button. Rewards are realized when you redeem or transfer the share. | | **XDC NFTs** | Base \~5.5% (NAV) + boost slice (up to \~1.5% via Synthetix accumulator) | **Base is automatic** (same as liquid). **Boost is claimed** from the NFT detail page in the app, paid in XDC. | → [How Rewards Work](/products/xdc-liquid-staking/xdc-staking-rewards) → [Reward Model: Base NAV + Boost](/products/xdc-staking-nfts/xdc-nft-staking-reward-system) #### Is there any risk of slashing? XDC Network does have a slashing mechanism, but it differs fundamentally from Ethereum's. A masternode that fails to sign any block during one full epoch (900 blocks, \~30 minutes) is excluded from block production for the next 4 epochs (\~2 hours) and forfeits rewards during that window. **Crucially, principal stake is not burned**: staked capital is never destroyed by validator behavior. For psXDC holders this means a slashing event on a protocol masternode would only briefly slow the rate at which the share price grows during the exclusion window; it cannot reduce the value of the shares themselves. This is structurally different from Ethereum-based liquid staking, where slashing can permanently destroy a portion of staked ETH. *** ### XDC NFTs #### What are XDC Staking NFTs? **XDC Staking NFTs** offer a gamified approach to staking. You deposit psXDC shares into an NFT, and the NFT's rarity, level, and lock status determine its weight in the boost accumulator. Higher weight = larger slice of every boost push. #### How do XDC NFTs work? 1. **Deposit psXDC shares:** acquire psXDC (by staking XDC or buying on a DEX) and deposit it into your NFT. 2. **Earn base NAV:** the underlying psXDC shares keep appreciating as the vault accrues validator rewards, the same \~5.5% you'd get without the NFT. 3. **Earn boost:** each `notifyBoost` push from the protocol's harvester credits the Synthetix accumulator; your NFT's pending boost grows proportionally to its weight. 4. **Claim boost:** from the NFT detail page, in XDC. 5. **Merge:** combine two NFTs of the same rarity to create a higher-rarity NFT with a bigger weight. 6. **Lock (optional):** locking adds `lockBonus` to the weight, which can push the combined APY toward the \~7% top of the band, but disables withdraw / merge / `burnAndRedeem` until expiry. The base \~5.5% applies whether you lock or not. #### What is the Merge System? If you have two NFTs of the same rarity, you can **merge** them into one NFT of the next rarity tier. Both originals are burned and a new one is minted. Higher rarity means a bigger `rarityMultiplier` and a bigger slice of every boost push. Because merging burns NFTs, the collection becomes **more scarce over time**, making remaining NFTs increasingly valuable. #### How do I sell my XDC NFT? List or auction your XDC NFT on [**PrimePort.xyz**](https://primeport.xyz). When purchased, the buyer gains the NFT itself plus the full staking position attached to it: staked psXDC shares, pending boost, weight, and any lock status all travel with the NFT. #### I still hold a legacy XDC NFT. What should I do? You can keep it (the legacy contracts remain operational) or migrate it to V3 in a single transaction via [`/xdc-nfts/migrate`](https://primestaking.xyz/xdc-nfts/migrate). Migration preserves your **rarity** and any active **lock expiry**, and your **tokenId** for legacy ids below `10000` (ids ≥ `10000` are remapped into the `5558–9999` band because that range is reserved for merged NFTs). It immediately starts earning under the V3 reward model. → [Migrate XDC NFTs to V3](/products/xdc-staking-nfts/migrate-nfts-v2-to-v3) → [Locked NFTs & Legacy Diamond Bypass](/products/xdc-staking-nfts/locked-nft-migration) *** ### XDC Liquid Staking #### How does Liquid Staking work? 1. **Stake XDC** through the V3 vault (`stake()` payable, or `depositNative(assets, receiver)`). 2. **Receive psXDC shares** at the current exchange rate. 3. **Watch the share price grow.** Rewards are embedded in the share. No claim needed. 4. **Withdraw** by calling `redeemWithQueue`: instant when the buffer covers it, queued FIFO otherwise. Or swap on a DEX for an immediate market exit (verify the pool holds the live V3.2 token). #### Who can participate? Anyone. There is **no minimum XDC required**. It's accessible to all XDC holders. #### How do I withdraw my staked XDC? You have two options: * **Protocol redemption** (`redeemWithQueue`): burns the equivalent psXDC shares. **Instant** when the vault's liquid buffer permits, otherwise enters the on-chain **FIFO queue** with self-claim via `claimQueuedAssets`. You can cancel queued requests at any time before settlement. * **Instant DEX exit**: swap psXDC for XDC on a DEX (verify the pool holds the live V3.2 token) for immediate liquidity at market price. #### Can I transfer my Liquid Staking position? Yes. Send psXDC to another address; whoever holds the share owns the appreciating position. No NFT required. #### I still hold V2 psXDC. How do I get V3? Use the [V2 → V3 migration bridge](/products/xdc-liquid-staking/staking-guide/migration). Approve [`PrimeStakedXDC_V3MigrationBridge`](/products/contract-addresses), call `migrate(amount, minSharesOut)`, and your V2 tokens are burned and V3 shares minted in the same transaction with slippage protection. # Partner Staking White-label XDC liquid staking pools that partners deploy and fully self-manage, powered by the PrimeStaking app. Each pool charges a 15% protocol fee to PrimeStaking. {% hint style="info" %} **Status: live on XDC Mainnet.** The [`PartnerVaultRegistry`](/partner-staking/partner-staking/registry-and-verification) is deployed at [`0x325DEEA5C7c0Ce0D774c4A67EcCaAf1cF8953a67`](https://xdcscan.com/address/0x325DEEA5C7c0Ce0D774c4A67EcCaAf1cF8953a67) and partner pools are already being registered. Pools appear in the app's directory once PrimeStaking marks them **Verified**. {% endhint %} **Partner Staking** lets a community, validator, exchange, or institution run its **own** XDC liquid staking pool — its own branded token, its own masternode operators, its own admin keys, and (new in V3.2) its own **on-chain partner fee** — while plugging into the PrimeStaking app, UI, and tooling. PrimeStaking does not custody the pool or operate its validators; it provides the audited vault design and the directory, and earns a flat **15% protocol fee** on the pool's staking rewards. Each pool is a deployment of [`PartnerStakedXDC_V3_2`](/partner-staking/partner-staking/smart-contract-reference) — a self-contained, fee-bearing copy of the PrimeStaking flagship [`PrimeStakedXDC_V3_1`](/products/xdc-liquid-staking/v3-architecture) vault. It is a fully independent contract: separate state, separate token, separate admin keys, separate masternode operators. It shares no storage, funds, or permissions with the flagship vault. On top of the protocol fee, the operator can set a partner fee (0–85% of rewards) whose every change waits out a public 24-hour timelock — see [How It Works](/partner-staking/partner-staking/how-it-works). *** ## Partner Staking vs. Institutional Integration PrimeStaking offers two different partner tracks. Don't confuse them: | | **Partner Staking** (this section) | **Institutional Integration** ([For Partners](/for-partners/institutional)) | | ------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | What it is | The partner **deploys and runs their own vault** (`PartnerStakedXDC_V3_2`) and lists it in the PrimeStaking directory | The partner **integrates the flagship PrimeStaking vault** into their own product (White Label / Powered by Prime) | | Who custodies validators | The **partner's** masternode operators | PrimeStaking's infrastructure | | Token | The partner's own branded share token (e.g. `acXDC`) | psXDC (the flagship share token) | | PrimeStaking's cut | Flat **15% protocol fee** skimmed on-chain from rewards | Negotiated revenue share (see [Revenue Model](/for-partners/revenue-model)) | | Best for | Communities, validators, regional platforms that want their own pool | Exchanges and custodians embedding XDC staking into an existing app | *** ## Why it's built this way * **Self-service & self-managed.** The partner deploys the vault, holds the admin keys, registers their own masternode operators, and covers their own masternode hosting costs. PrimeStaking never holds the keys or the funds. * **Non-custodial & ERC-4626.** Same share-based, native-XDC design as the flagship V3 vault — instant withdrawals against a liquidity buffer, an automatic FIFO queue when the buffer is empty, masternode delegation, time-locked governance, and per-report / daily loss caps. * **Trust-minimized listing.** The protocol fee rate (15%) and recipient (PrimeStaking treasury) are **compile-time constants**, so every genuine partner vault shares identical runtime bytecode. The [`PartnerVaultRegistry`](/partner-staking/partner-staking/registry-and-verification) only lists a vault whose `codehash` matches an allow-listed canonical hash — a partner cannot deploy a 0%-fee fork and have it appear in the PrimeStaking UI. The partner fee lives in storage, so it never fragments the canonical codehash. * **Operator revenue, without rug risk.** The partner fee is bounded (protocol + partner can never exceed 100% of yield, principal is untouchable) and every change goes through a public 24-hour timelock that the app surfaces to stakers as an exit window. * **Curated visibility.** Registration is open, but the app shows only pools PrimeStaking has marked **Verified**, so the branded directory can never be flooded with spam pools. *** ## How a pool comes to life 1. **Deploy** a `PartnerStakedXDC_V3_2` with a name, symbol, the XDC validator contract, a minimum masternode stake, and (optionally) a partner fee + recipient. The deployer becomes the vault admin. → [Deploy & List a Pool](/partner-staking/partner-staking/deploy-and-list) 2. **Configure** operators, KYC, buffer, and governance parameters from the partner admin dashboard. 3. **Register** the vault in `PartnerVaultRegistry` (requires the canonical codehash and the vault admin role), then set presentation metadata. → [Registry & Verification](/partner-staking/partner-staking/registry-and-verification) 4. **Get verified** by PrimeStaking to earn the "Verified by PrimeStaking" badge and appear in the default directory. 5. **Users stake** native XDC into the pool and earn rewards via NAV growth, net of the 15% protocol fee and the pool's partner fee (shown as one total fee in the app). → [How It Works](/partner-staking/partner-staking/how-it-works) *** ## In this section | Page | What it covers | | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | [How It Works](/partner-staking/partner-staking/how-it-works) | The economic model, the fee chokepoint (protocol + partner fee), the 24h fee timelock, what the partner manages vs. what PrimeStaking provides | | [Deploy & List a Pool](/partner-staking/partner-staking/deploy-and-list) | Deploying `PartnerStakedXDC_V3_2`, roles & governance, registering and getting verified | | [Registry & Verification](/partner-staking/partner-staking/registry-and-verification) | `PartnerVaultRegistry` — codehash gating, verification badge, metadata, delisting | | [Smart Contract Reference](/partner-staking/partner-staking/smart-contract-reference) | Function-level reference for both partner contracts | **Contact:** # How It Works A partner pool is an independent ERC-4626 liquid staking vault. Stakers deposit native XDC and receive the pool's share token; the share price (NAV) grows as the pool's masternodes earn validator rewards. The economic difference from the flagship [`PrimeStakedXDC_V3_1`](/products/xdc-liquid-staking/v3-architecture) vault is a **15% protocol fee** — plus, on current-generation (V3.2) pools, an optional **partner fee** set by the pool operator — skimmed from rewards before they reach stakers. *** ## The 15% protocol fee | Parameter | Value | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `PLATFORM_FEE_BPS` | `1500` (**15%**) | | `PLATFORM_FEE_RECIPIENT` | [`0x1658b14Cb483B96E7e10227fF00f438858089127`](https://xdcscan.com/address/0x1658b14Cb483B96E7e10227fF00f438858089127) (PrimeStaking treasury) | Both are **compile-time constants**, not constructor arguments. That is deliberate: it means every genuine partner vault compiles to **identical runtime bytecode**, which is what lets the [`PartnerVaultRegistry`](/partner-staking/partner-staking/registry-and-verification) verify a pool by its `codehash`. Changing the fee or recipient would require a recompile and a fresh allow-list entry, so a partner can't quietly run a 0%-fee fork and still get listed. The fee applies only to **rewards** (yield), never to principal: * Staker deposits and returned masternode principal are **not** taxed. * Only the growth of managed assets above the tracked NAV (i.e. validator rewards) is subject to the 15%. ### Path-independent fee chokepoint The fee is not charged on a single "rewards in" function that a partner could route around. Instead, every balance-changing operation reconciles through one internal chokepoint (`_syncTrackedAssetsExcludingInflow`). Whenever that reconciliation detects that the pool's assets have grown beyond the tracked NAV (excluding deposits and principal returns), it: 1. Computes the surplus (the yield), 2. Skims 15% of it to the PrimeStaking treasury, and 3. Credits the remaining 85% to stakers via NAV appreciation. ``` validator rewards arrive ─► reconcile assets ─► surplus detected │ ┌────────────────────┴───────────────────┐ ▼ ▼ 15% skimmed to PrimeStaking 85% credited to stakers (NAV ↑) ``` Because of this design the fee is unavoidable: force-sending XDC (`selfdestruct` / direct transfer), routing rewards around the `receive()` path, or delivering yield through a masternode-resignation are all taxed identically on the next reconciliation. The recipient is a protocol-controlled address that always accepts native XDC, so the skim cannot be made to revert to grief stakers. *** ## The partner fee (V3.2 pools) Pools deployed on the current `PartnerStakedXDC_V3_2` template additionally support an **on-chain partner fee**: the operator's own revenue share, taken from the same gross yield at the same chokepoint as the protocol fee. | Property | Value | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Range | `0` – `8500` bps (0–85% of rewards) | | Hard bound | `PLATFORM_FEE_BPS + MAX_PARTNER_FEE_BPS = 100%` — the combined skim can never exceed the yield surplus, and **principal is never touched** | | Set at | Deploy time (constructor) and adjustable afterwards | | Changes | `setPartnerFee` schedules; `executePartnerFee` applies after the vault's `governanceDelay` (default **24 hours**); `cancelPartnerFeeChange` aborts. The fee **recipient** has the same schedule/execute/cancel flow | | Transparency | Every scheduled change emits a public event, and the pool page in the app shows stakers a warning with the exact activation time | Key properties: * **No surprise fees.** Every change — increase *or* decrease — waits out the timelock and is publicly visible first. The timelock is the staker's exit window: anyone who disagrees with a scheduled fee can withdraw before it activates. * **Storage, not bytecode.** Unlike the protocol fee, the partner fee lives in storage, so every V3.2 pool still shares one canonical codehash and the registry's authenticity check keeps working regardless of each pool's fee. * **Cannot brick the pool.** The partner fee is pushed with a bounded gas stipend; if the recipient rejects the transfer, the fee is parked in the vault's claimable lane (`claimQueuedAssets`) instead of reverting — a broken recipient can never block staking, withdrawals, or the protocol fee. * **Settled at the old rate.** Executing a fee change first reconciles any yield accrued so far at the previous rate, so a change never retroactively re-prices earlier rewards. Legacy V3 pools (deployed before the V3.2 template) have no partner fee and keep their original immutable behavior. *** ## Who does what | Responsibility | Owner | | ------------------------------------------------- | ------------ | | Deploy the vault & hold admin keys | **Partner** | | Register & run masternode operators | **Partner** | | Cover masternode hosting / infrastructure cost | **Partner** | | Set buffer, min stake, KYC, governance parameters | **Partner** | | Set (and timelock-change) the partner fee | **Partner** | | Vault contract design (audited flagship V3 logic) | PrimeStaking | | App, UI, directory & verification badge | PrimeStaking | | Receives the 15% protocol fee | PrimeStaking | PrimeStaking provides the infrastructure and the storefront; the partner runs the pool. PrimeStaking is **non-custodial** with respect to partner pools: it never holds a pool's keys or funds and only ever receives the on-chain protocol fee. *** ## What stakers experience Identical to flagship psXDC, minus the reward haircut (15% protocol fee plus the pool's partner fee, both shown as one total fee in the app): * **Stake** native XDC via `stake` / `depositNative`, receive the pool's share token at the current exchange rate. * **NAV growth.** No claim button; shares simply become worth more XDC as net (post-fee) rewards accrue. * **Withdraw.** Instant if the liquidity buffer covers it (`withdraw` / `redeem`), otherwise the request enters an automatic FIFO queue (`withdrawWithQueue` / `redeemWithQueue`) and is claimed once masternode payouts return. Queued requests can be cancelled before they're processed. * **Same safety rails** as flagship V3: time-locked governance changes, per-report and daily validator-loss caps, pausable, reentrancy-guarded, and role-separated operations. → [Deploy & List a Pool](/partner-staking/partner-staking/deploy-and-list) → [Registry & Verification](/partner-staking/partner-staking/registry-and-verification) → [Smart Contract Reference](/partner-staking/partner-staking/smart-contract-reference) # Deploy & List a Pool Bringing a partner pool online is a two-stage process: **deploy** your own `PartnerStakedXDC_V3_2`, then **register** it in the `PartnerVaultRegistry` so it appears in the PrimeStaking app. Both stages are self-service from the partner dashboard. {% hint style="info" %} Live on XDC Mainnet: the registry ([`0x325D…3a67`](https://xdcscan.com/address/0x325DEEA5C7c0Ce0D774c4A67EcCaAf1cF8953a67)) and its canonical codehash allow-list are deployed, and pools are already registering through the flow below. {% endhint %} *** ## 1. Deploy the vault `PartnerStakedXDC_V3_2` is deployed with a regular constructor: ```solidity constructor( string name_, // ERC-20 name shown in wallets/UI, e.g. "Acme Staked XDC" string symbol_, // ERC-20 symbol, e.g. "acXDC" address initialValidator, // the XDC validator contract the vault delegates to uint256 initialMinStake, // minimum masternode proposal size uint256 initialPartnerFeeBps, // your partner fee on gross rewards (0-8500 bps) address initialPartnerFeeRecipient // fee payee; zero address defaults to the deployer ) payable ``` The deploying address (`msg.sender`) becomes the vault **admin** and is also granted the proposer, operations-manager, and risk-manager roles. Any XDC sent with deployment is seeded as the initial stake. The partner fee is public from block one — setting it in the constructor bypasses no timelock, because nobody has staked yet. To stay eligible for listing, deploy the **canonical, unmodified** `PartnerStakedXDC_V3_2` bytecode that PrimeStaking has allow-listed — the protocol fee rate and recipient are constants baked into that bytecode, so a custom build will not match the registry's codehash and cannot be listed. Your partner fee is storage (a constructor argument), so any fee choice keeps the canonical codehash. *** ## 2. Configure the pool From the partner admin dashboard (or directly against the contract), the admin sets the pool up: | Action | Function | Role | | ------------------------------------- | ------------------------------------------------------------------ | ------------------------- | | Register a masternode operator | `addOperator(address)` / `removeOperator(address)` | `DEFAULT_ADMIN_ROLE` | | Submit pool KYC to the validator | `submitKYC(string)` | `DEFAULT_ADMIN_ROLE` | | Set liquidity buffer (≤ 50%) | `setBufferBps(uint256)` | `OPERATIONS_MANAGER_ROLE` | | Set minimum masternode stake | `setMinStake(uint256)` | `OPERATIONS_MANAGER_ROLE` | | Set / change validator | `setValidator(address)` | `OPERATIONS_MANAGER_ROLE` | | Configure auto-propose | `setAutoProposeConfig(bool,uint256)` | `OPERATIONS_MANAGER_ROLE` | | Pause / unpause | `pause()` / `unpause()` | `DEFAULT_ADMIN_ROLE` | | Change the partner fee (timelocked) | `setPartnerFee(uint256)` → `executePartnerFee()` | `DEFAULT_ADMIN_ROLE` | | Change the fee recipient (timelocked) | `setPartnerFeeRecipient(address)` → `executePartnerFeeRecipient()` | `DEFAULT_ADMIN_ROLE` | Masternode proposals require the vault itself to be KYC-verified on the validator, and only registered operators can be proposed. Auto-propose round-robins across operators once the available balance crosses the threshold. *** ## 3. Governance & roles The pool ships with the same hardened governance model as the flagship V3 vault: * **Direct role and ownership changes are disabled.** `grantRole`, `revokeRole`, `renounceRole`, `transferOwnership`, and `renounceOwnership` all revert. Privileged changes must go through the **schedule → wait → execute** flow. * **Time-locked changes.** Changing the proposer, operations manager, risk manager, loss caps, the governance delay itself, the partner fee, the fee recipient, or transferring admin ownership are each two-phase: `set…` schedules the change, and after `governanceDelay` has elapsed `execute…` applies it. Pending changes can be cancelled. * **Governance delay**: default **1 day**, configurable between **1 minute** and **30 days** (itself time-locked). * **Loss caps**: `reportValidatorLoss` (RISK\_MANAGER only) is bounded by a per-report cap (default **10%**) and a rolling daily cap (default **20%**), both expressed in bps of tracked assets. | Role | Powers | | ------------------------- | --------------------------------------------------------------------------- | | `DEFAULT_ADMIN_ROLE` | Operators, KYC, pause, partner fee, schedule/execute all governance changes | | `PROPOSER_ROLE` | Propose / resign masternodes | | `OPERATIONS_MANAGER_ROLE` | Buffer, min stake, validator, auto-propose, scan limits | | `RISK_MANAGER_ROLE` | Report validator losses (within caps) | *** ## 4. Register in the directory Once deployed and configured, list the pool so it shows up in PrimeStaking: ```solidity PartnerVaultRegistry.register(address vault) ``` `register` succeeds only if **both** of the following hold: 1. The vault's `codehash` is an **allow-listed canonical hash** (`isCanonicalCodeHash[vault.codehash] == true`) — proving it's a genuine, unmodified partner vault that charges the 15% protocol fee. Both generations (V3 and V3.2) are allow-listed side by side, so existing pools stay registered. 2. The caller **holds the vault's `DEFAULT_ADMIN_ROLE`** — proving they actually control the pool. It then records the registrant and emits `VaultRegistered(vault, registrant, name, symbol)`. ### Set presentation metadata The vault's admin can attach off-chain-style presentation data (kept in the registry because the vault bytecode is codehash-locked and must not change): ```solidity PartnerVaultRegistry.setMetadata(address vault, PoolMeta { description, website, logoURI, twitter, telegram }) ``` *** ## 5. Get verified Registration is **open**, but visibility is **curated**. By default the app reads `verifiedVaults()` and shows only pools PrimeStaking has marked verified: ```solidity PartnerVaultRegistry.setVerified(address vault, bool verified) // PrimeStaking (registry owner) only ``` Verified pools earn the **"Verified by PrimeStaking"** badge and appear in the default directory. Unverified pools remain reachable by direct address, so a pool is usable the moment it's registered, but the branded directory can't be spammed. PrimeStaking can also `unregister` an abusive or abandoned pool entirely (the vault contract itself is untouched; it can be re-registered later by its admin). → [How It Works](/partner-staking/partner-staking/how-it-works) → [Registry & Verification](/partner-staking/partner-staking/registry-and-verification) → [Smart Contract Reference](/partner-staking/partner-staking/smart-contract-reference) # Registry & Verification `PartnerVaultRegistry` is the on-chain directory that powers the PrimeStaking app's partner pool listing. It answers one question trust-minimally: *"is this address a genuine, unmodified partner vault that charges the 15% protocol fee, controlled by the person registering it?"* It is an `Ownable2Step` contract (two-phase ownership handoff so control can't be lost to a mistyped address). The owner is PrimeStaking. *** ## Codehash gating Because the partner vault bakes the protocol fee rate and recipient in as constants (the V3.2 partner fee is storage, so it does not affect the bytecode), every genuine partner vault of a generation has **identical runtime bytecode** and therefore one canonical `codehash` per generation. PrimeStaking allow-lists those hashes: ```solidity setCanonicalCodeHash(bytes32 codeHash, bool allowed) // owner only, once per published vault bytecode version ``` `register(vault)` then enforces: * `isCanonicalCodeHash[vault.codehash] == true`, else `NotCanonicalBytecode` * caller holds `vault`'s `DEFAULT_ADMIN_ROLE`, else `NotVaultAdmin` * `vault != address(0)` and not already registered, else `ZeroAddress` / `AlreadyRegistered` This makes it impossible to list a fork with a different protocol fee, a different recipient, or hidden modifications. If the vault bytecode is ever revised, PrimeStaking publishes and allow-lists the new codehash; older deployments stay valid under their own hash unless explicitly revoked. That is exactly how the V3 → V3.2 upgrade (partner fees) shipped: both codehashes are allow-listed, existing V3 pools stayed registered, and new deploys use V3.2. *** ## Verification & visibility | State | Meaning | Shown in default directory? | | ------------ | ------------------------------------------------------------- | --------------------------------------------------------- | | Registered | Passed codehash + admin checks | No (reachable by direct address) | | Verified | PrimeStaking has vetted the pool (`setVerified(vault, true)`) | **Yes**, and carries the "Verified by PrimeStaking" badge | | Unregistered | Never listed, or delisted via `unregister` | No | The app reads `verifiedVaults()` for the curated listing, so the directory can never be flooded with unverified spam pools, while registration itself stays permissionless. `setVerified` and `unregister` are **owner-only** (PrimeStaking); `unregister` clears all registry state for a vault but does not touch the vault contract; its admin can register it again later. *** ## Metadata Presentation data lives in the registry (not the vault, whose bytecode is codehash-locked) and is editable only by the vault's admin: ```solidity struct PoolMeta { string description; string website; string logoURI; string twitter; string telegram; } setMetadata(address vault, PoolMeta meta) // vault DEFAULT_ADMIN_ROLE only ``` *** ## Read API (used by the app & indexers) | Function | Returns | | ----------------------------------------------- | ------------------------------------------------ | | `allVaults()` | Every registered vault address | | `verifiedVaults()` | Only the verified subset (the default directory) | | `vaultsLength()` / `vaultAt(uint256)` | Enumerate the global list | | `vaultsByAdmin(address)` | Pools registered by a given admin | | `isRegistered(address)` / `isVerified(address)` | Status flags | | `registrantOf(address)` | Who registered a vault | | `metadata(address)` | The `PoolMeta` for a vault | ## Events | Event | When | | -------------------------------------------------- | ---------------------------------------------------- | | `CanonicalCodeHashSet(codeHash, allowed)` | A canonical bytecode hash is allow-listed or revoked | | `VaultRegistered(vault, registrant, name, symbol)` | A pool is added to the directory | | `VaultVerifiedSet(vault, verified)` | A pool's verified badge is toggled | | `VaultUnregistered(vault, registrant)` | A pool is delisted | | `MetadataUpdated(vault, admin)` | A pool's presentation metadata changes | → [How It Works](/partner-staking/partner-staking/how-it-works) → [Deploy & List a Pool](/partner-staking/partner-staking/deploy-and-list) → [Smart Contract Reference](/partner-staking/partner-staking/smart-contract-reference) # Smart Contract Reference Two contracts make up Partner Staking: **`PartnerStakedXDC_V3_2`** (the per-partner vault; legacy pools run `PartnerStakedXDC_V3`) and **`PartnerVaultRegistry`** (the shared directory). {% hint style="info" %} Live on XDC Mainnet. The shared [`PartnerVaultRegistry`](https://xdcscan.com/address/0x325DEEA5C7c0Ce0D774c4A67EcCaAf1cF8953a67) is at `0x325DEEA5C7c0Ce0D774c4A67EcCaAf1cF8953a67`. Each partner vault is a separate per-partner deployment; discover live pools via the registry's `allVaults()` / `verifiedVaults()`. See [Deployed Contracts & Addresses](/products/contract-addresses). {% endhint %} *** ## `PartnerStakedXDC_V3_2` — the partner vault An ERC-4626, native-XDC, share-based liquid staking vault (`ReentrancyGuard`, `ERC4626`, `Pausable`, `AccessControl`). It is a fee-bearing copy of the flagship `PrimeStakedXDC_V3_1` with separate state, token, keys, and operators. `asset()` is the zero address because the underlying is native XDC; `totalAssets()` returns `trackedTotalAssets`. V3.2 adds the timelocked **partner fee** (see below); everything else matches the audited V3 template. ### Constants | Constant | Value | Meaning | | --------------------------------- | ---------------- | ---------------------------------------------------------------------- | | `PLATFORM_FEE_BPS` | `1500` | 15% protocol fee on reward inflows | | `PLATFORM_FEE_RECIPIENT` | `0x1658…9127` | PrimeStaking treasury (fee recipient) | | `MAX_PARTNER_FEE_BPS` | `8500` | Partner fee ceiling: protocol + partner can never exceed 100% of yield | | `PARTNER_FEE_PUSH_GAS_LIMIT` | `100,000` | Gas stipend for the partner fee push (failure defers to the pull lane) | | `DEFAULT_MASTERNODE_STAKE` | `10,000,000 XDC` | Default masternode size | | `MIN_REWARD_DISTRIBUTION` | `1000 XDC` | Minimum non-privileged reward push via `receive()` | | `MAX_BUFFER_BPS` | `5000` | Max liquidity buffer (50%) | | `DEFAULT_MAX_LOSS_BPS_PER_REPORT` | `1000` | 10% per-report validator-loss cap | | `DEFAULT_MAX_DAILY_LOSS_BPS` | `2000` | 20% rolling daily loss cap | | `DEFAULT_GOVERNANCE_DELAY` | `1 day` | Default timelock (range 1 min – 30 days) | ### Partner fee (V3.2) | Item | Detail | | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `partnerFeeBps` / `partnerFeeRecipient` | Current fee (bps of gross yield) and payee. Set in the constructor (`initialPartnerFeeBps`, `initialPartnerFeeRecipient`; zero recipient defaults to the deployer). | | `setPartnerFee(bps)` → `executePartnerFee()` / `cancelPartnerFeeChange()` | Timelocked rate change (admin only, waits `governanceDelay`). Executing first settles accrued yield at the old rate. | | `setPartnerFeeRecipient(addr)` → `executePartnerFeeRecipient()` / `cancelPartnerFeeRecipientChange()` | Timelocked recipient change (admin only). | | `pendingPartnerFee()` / `pendingPartnerFeeRecipient()` | Views exposing any scheduled change + its `executeAfter` timestamp (drives the app's staker warnings). | | Failure mode | If the recipient rejects the push, the fee parks in `pendingQueuedAssets[recipient]` and is pulled via `claimQueuedAssets` — the pool never bricks. | ### Stake & withdraw | Function | Notes | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | `stake(uint256 assets) payable` | Native-XDC stake; `msg.value` must equal `assets`. Mints shares at the current rate. | | `depositNative(uint256 assets, address receiver) payable` | Same, crediting `receiver`. | | `deposit(...)` / `mint(...)` | **Disabled.** Revert `NativeDepositRequired` (deposits must be native, via the payable wrappers). | | `withdraw(uint256 shares)` | Legacy-compatible redeem-by-shares. | | `withdraw(uint256 assets, address receiver, address owner)` / `redeem(...)` | Standard ERC-4626 exits; revert if the liquid buffer can't cover them. | | `withdrawWithQueue(uint256 assets, address receiver)` | Instant if liquid, else queues a FIFO request. | | `redeemWithQueue(uint256 shares, address receiver)` | Same, by shares. | | `cancelQueuedWithdrawal(uint256 requestId)` | Cancel an unprocessed queued request; shares returned. | | `processWithdrawalQueue(uint256 maxRequests)` | Anyone can advance the queue once liquidity returns. | | `claimQueuedAssets(address payable receiver)` | Claim a deferred payout (if a queued transfer failed). | | `maxWithdraw` / `maxRedeem` | Clamped to what the buffer can pay immediately. | ### Masternodes & operators | Function | Role | | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | `addOperator` / `removeOperator` | `DEFAULT_ADMIN_ROLE` | | `submitKYC(string)` | `DEFAULT_ADMIN_ROLE` | | `proposeMasternode(address candidate, uint256 amount)` | proposer or admin | | `triggerAutoPropose(uint256 maxNodes)` | anyone (round-robins operators when funded) | | `resignMasternode(address)` / `withdrawResignedMasternode(uint256)` | proposer or admin | | `setValidator` / `setMinStake` / `setBufferBps` / `setAutoProposeConfig` / `setOperatorScanLimit` / `setQueueScanLimit` | `OPERATIONS_MANAGER_ROLE` | | `reportValidatorLoss(address operator, uint256 assets)` | `RISK_MANAGER_ROLE`, within per-report & daily caps | ### Governance (timelocked, two-phase) Direct `grantRole` / `revokeRole` / `renounceRole` / `transferOwnership` / `renounceOwnership` all **revert**. Use the scheduled flow instead: | Schedule | Execute | Cancel | | ------------------------ | ---------------------------- | --------------------------------- | | `setProposer` | `executeProposer` | `cancelProposerChange` | | `setOperationsManager` | `executeOperationsManager` | `cancelOperationsManagerChange` | | `setRiskManager` | `executeRiskManager` | `cancelRiskManagerChange` | | `setMaxLossBpsPerReport` | `executeMaxLossBpsPerReport` | `cancelMaxLossBpsPerReportChange` | | `setMaxDailyLossBps` | `executeMaxDailyLossBps` | `cancelMaxDailyLossBpsChange` | | `setGovernanceDelay` | `executeGovernanceDelay` | `cancelGovernanceDelayChange` | | `setPartnerFee` | `executePartnerFee` | `cancelPartnerFeeChange` | | `setPartnerFeeRecipient` | `executePartnerFeeRecipient` | `cancelPartnerFeeRecipientChange` | | `scheduleOwnerTransfer` | `executeOwnerTransfer` | `cancelOwnerTransfer` | Each executes only after `governanceDelay` has elapsed. ### Key views & marker | Function | Returns | | ----------------------------------- | ---------------------------------------------------------------------------------------------------- | | `isPartnerStakedXDCV3()` | `true` — marker the registry/UI use to identify partner vaults (kept in V3.2) | | `partnerVaultVersion()` | `2` on V3.2 pools; the call reverts on legacy V3 pools, which is how the app tells generations apart | | `name()` / `symbol()` | The partner's branded name/symbol | | `totalAssets()` / `desiredBuffer()` | Tracked NAV and target buffer | | `isKYCVerified(address)` | Whether an address is KYC'd on the validator | ### Notable events `Staked`, `Withdrawn`, `WithdrawalQueued` / `WithdrawalQueueProcessed` / `WithdrawalQueueCancelled`, `MasternodeProposed`, `ValidatorLossReported`, **`PlatformFeeSkimmed(recipient, amount)`** (every protocol fee skim), and on V3.2: **`PartnerFeeSkimmed`** / **`PartnerFeeDeferred`** (partner fee payouts) plus **`PartnerFeeChangeScheduled`** / **`PartnerFeeUpdated`** / **`PartnerFeeChangeCancelled`** and the recipient-change equivalents (timelock transparency). *** ## `PartnerVaultRegistry`: the directory `Ownable2Step`; owner is PrimeStaking. See [Registry & Verification](/partner-staking/partner-staking/registry-and-verification) for the full write-up. | Function | Caller | Purpose | | ----------------------------------------------------------------------------- | ----------- | ------------------------------------------------------- | | `setCanonicalCodeHash(bytes32, bool)` | owner | Allow-list / revoke a canonical vault bytecode hash | | `register(address vault)` | vault admin | List a vault (requires canonical codehash + admin role) | | `setVerified(address, bool)` | owner | Toggle the "Verified by PrimeStaking" badge | | `unregister(address)` | owner | Delist an abusive/abandoned pool | | `setMetadata(address, PoolMeta)` | vault admin | Set description / website / logo / socials | | `allVaults` / `verifiedVaults` / `vaultsByAdmin` / `vaultAt` / `vaultsLength` | view | Enumerate the directory | | `isRegistered` / `isVerified` / `registrantOf` / `metadata` | view | Per-vault status & data | Events: `CanonicalCodeHashSet`, `VaultRegistered`, `VaultVerifiedSet`, `VaultUnregistered`, `MetadataUpdated`. → [Partner Staking overview](/partner-staking/partner-staking) → [How It Works](/partner-staking/partner-staking/how-it-works) → [Deploy & List a Pool](/partner-staking/partner-staking/deploy-and-list) # Institutional Overview PrimeStaking is more than a retail staking app, it is **staking infrastructure for the XDC Network**, designed to serve exchanges, custodians, and institutional partners at scale. Built in collaboration with **Nethermind** and the **XDC Core team**, PrimeStaking provides production-grade liquid staking infrastructure with no principal-stake slashing, audited smart contracts, and non-custodial architecture. *** ## What We Offer PrimeStaking provides turnkey XDC staking infrastructure that exchanges and institutions can integrate or white-label. Our stack handles: * **Validator operations** - masternode management, uptime, performance monitoring, on-chain delegation * **Liquid staking contracts** - the non-upgradeable, ERC-4626 [`PrimeStakedXDC_V3_1`](/products/contract-addresses) vault for minting and redeeming psXDC shares * **NAV-based reward accrual** - reward XDC flows back into the vault, share price rises automatically; no manual reward distribution path * **Self-service withdrawals** - instant when the buffer permits, otherwise a permissionless FIFO queue with `claimQueuedAssets` self-claim * **V2 → V3 migration** - dedicated bridge with slippage protection for any psXDC v2 balance partners may already hold * **Reporting** - on-chain settlement data and portfolio-level analytics via the [`staking-v3-indexer`](https://github.com/PrimeNumbersLabs/staking-v3-indexer) and [`xdc-nft-v3-indexer`](https://github.com/PrimeNumbersLabs/xdc-nft-v3-indexer) *** ## Why PrimeStaking | Advantage | Detail | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Non-custodial** | Users retain full ownership of assets at all times | | **Audited by QuillAudits** | XDC Staking Contract, 98.8%. [Published](https://docs.primestaking.xyz/security/audits-1) | | **Audited by Nethermind** | Security audit of custody contracts conducted by Nethermind Security, trusted auditing partner for Lido, EtherFi, Optimism, and Worldcoin | | **No principal-stake slashing** | XDC's slashing penalizes downtime via temporary exclusion (\~2h) and missed rewards; staked capital is never burned - unlike ETH liquid staking | | **Permissionless custody** | Smart contract-based validator key management - no human custody | | **Battle-tested** | Live since 2024, grown to $6M+ TVL | | **XDC-native** | Purpose-built for the XDC Network ecosystem | *** ## Why XDC Network | Property | Detail | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Consensus** | XDPoS (Delegated Proof of Stake) with masternode validators | | **No stake-burning slashing** | XDC slashing excludes underperforming masternodes from block production for \~2h and forfeits their rewards, but never burns principal, so stakers face no risk of capital loss from validator behavior | | **Fast finality** | 2-second target block time (real-world average \~2.33s) with near-instant transaction confirmation | | **Low fees** | Negligible gas costs compared to Ethereum and most L2s | | **Enterprise adoption** | XDC Network is used for trade finance, tokenized assets, and institutional applications | | **Growing ecosystem** | Active DeFi protocols, NFT marketplaces, and developer tooling | For partners evaluating which networks to support, XDC offers a unique combination of institutional-grade infrastructure, no principal-stake slashing, and growing adoption. *** ## Why Institutions Prefer Delegated Infrastructure ### Why Institutions Choose PrimeStaking Running an independent XDC validator requires: * 10,000,000 XDC locked per validator * 24/7 infrastructure monitoring * Validator maintenance and upgrades * Security and key management * Internal operational risk controls PrimeStaking abstracts this complexity into a managed institutional staking layer, allowing partners to access XDC staking rewards without operating validator infrastructure internally. This enables faster deployment, lower operational overhead, and scalable staking infrastructure for exchanges and institutional partners. *** ## Integration Models PrimeStaking offers two integration paths for exchanges and institutional partners: ### Model A - White Label Your brand, our infrastructure. Operate XDC staking under your own brand using PrimeStaking's architecture. → [White Label Details](/for-partners/integration-models#model-a--white-label) ### Model B - Powered by Prime Integrate PrimeStaking with visible co-branding. Lower integration effort, same underlying infrastructure. → [Powered by Prime Details](/for-partners/integration-models#model-b--powered-by-prime) *** ## Documentation Map | Section | What It Covers | | -------------------------------------------------------------- | ----------------------------------------------------------------------- | | [Architecture Overview](/for-partners/architecture) | System design, V3 contract topology, validator infrastructure | | [Custody Model](/for-partners/custody-model) | Permissionless smart contract-based key management | | [Integration Models](/for-partners/integration-models) | White Label vs. Powered by Prime - scope, requirements | | [Revenue Model](/for-partners/revenue-model) | Revenue generation, partner sharing, settlement | | [Reward Mechanics](/for-partners/reward-mechanics) | NAV-based reward accrual; NFT boost stream | | [Liquidity Model](/for-partners/liquidity-model) | psXDC share semantics, buffer / queue redemption, DEX vs protocol price | | [Governance](/for-partners/governance) | Role separation, delayed governance, what is upgradeable vs immutable | | [Risk & Compliance](/for-partners/risk-and-compliance) | Risk framework, audit history, regulatory posture | | [SLA & Support](/for-partners/sla-and-support) | Uptime commitments, incident response, partner support | | [Deployed Contracts & Addresses](/products/contract-addresses) | Canonical address book for V3 and legacy V2 contracts | *** ## Get in Touch For integration inquiries, partnership proposals, or technical due diligence: * **Email:** * **Website:** [primestaking.xyz](https://primestaking.xyz) # Architecture PrimeStaking V3 runs entirely on audited, on-chain smart contracts deployed on the XDC Network. The architecture is split into two non-upgradeable cores (the psXDC vault and the migration bridge) plus an upgradeable NFT-staking layer with namespaced storage. Infrastructure is developed in collaboration with **Nethermind** (smart contract engineering and security) and the **XDC Core team** (network-level validator integration). *** ## System Design ``` User / Partner API │ ▼ ┌──────────────────────────────┐ │ Frontend / SDK / API │ └──────────────┬───────────────┘ │ ┌──────────────────────────┼───────────────────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐ │ PrimeStaked │ │ XdcNftStaking │ │ V3 Migration │ │ XDC_V3 │◄────────┤ Vault (proxy) │ │ Bridge │ │ (ERC-4626, │ shares │ + XdcStakedNFT │ │ (V2 → V3) │ │ immutable) │ │ + Migrator │ │ │ └──────┬───────┘ │ + Harvester │ └──────┬────────┘ │ │ + Bypass facet │ │ │ stake / redeem └────────┬─────────┘ │ burns V2 psXDC ▼ │ ▼ ┌──────────────────────────────────────────────────────────────────────┐ │ XDC Network masternodes (on-chain validator contract) │ └──────────────────────────────────────────────────────────────────────┘ ``` *** ## Contract Topology | Contract | Function | Upgradeability | Address | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `PrimeStakedXDC_V3_2` | ERC-4626 native-XDC vault. Mints/burns psXDC shares, manages liquidity buffer, processes withdrawals, interfaces with masternodes. | **None** (regular constructor, no proxy) | [`0xa7FD…73e4`](https://xdcscan.com/address/0xDc74c0DaED82ae94486DeeF22991d2F54173c734) | | `PrimeStakedXDC_V3MigrationBridge` | One-way V2 psXDC → V3 share migration. Time-locked admin, daily withdrawal caps. | **None** | [`0x6c57…373C`](https://xdcscan.com/address/0x6c57075c7A157113D369109B78738A798d41373C) | | `XdcStakedNFT` | ERC-721 NFT collection for staking positions. Rarity stored on-chain. | **None** | [`0xf3eB…898E`](https://xdcscan.com/address/0xf3eB62F0Daf98ab65f0696630621A6ecECDB898E) | | `XdcNftStakingVault` | Holds psXDC v3 shares per NFT; runs Synthetix-style boost accumulator; handles stake/withdraw/claim/lock/merge/burnAndRedeem; enforces a governance-configurable per-NFT stake cap (default 100,000 psXDC). | **TransparentUpgradeableProxy** (ERC-7201 namespaced storage) | [`0x9f38…4Da8`](https://xdcscan.com/address/0x9f38dF64eeC71e2408B24217b8D621c6B07E4Da8) | | `XdcNftMigratorV2` | Atomic V2 → V3 NFT migration. Preserves `tokenId`/rarity/lock, and remaps legacy ids ≥ `10000` into the free `5558–9999` band. | **None** | [`0x69DE…2ea8`](https://xdcscan.com/address/0x69DE30161ec0f2e0Dc0649190dB9b93F4c492ea8) | | `XdcNftBoostHarvester` | Funds the NFT vault's boost accumulator via `notifyBoost`. Only holder of `FEE_ROUTER_ROLE`. | **None** | [`0x6a31…821D`](https://xdcscan.com/address/0x6a319528111E5e50712Fd2D3d2db8323b119821D) | | `LegacyMigratorBypassFacet` | Diamond facet on the legacy Diamond `0x7a5d…aA17` enabling locked-NFT migration (clears `tokenLocked`; the diamond pays the psXDC). | Facet, added via `diamondCut` | [`0x2786…5e13`](https://xdcscan.com/address/0x2786D8Df1C38c9D4eD642B84c073349b0f0B5e13) | Full inventory in [Deployed Contracts & Addresses](/products/contract-addresses). *** ## Validator Infrastructure PrimeStaking operates XDC Network masternodes that generate the underlying staking yield: * **Validator delegation** is performed by `PrimeStakedXDC_V3_2` directly against the on-chain XDC validator contract. No off-chain custodian. * **Operator onboarding** is admin-controlled (KYC-verified masternode operators); operator scans are bounded by `operatorScanLimit` to prevent gas-griefing. * **Auto-propose** runs opportunistically during stake or via `triggerAutoPropose(maxNodes)`. It is **blocked whenever the withdrawal queue has a backlog**, so user redemptions are prioritised over new validator locks. * **Resignation** returns principal to the vault after the network `candidateWithdrawDelay` (\~35 days under typical block times). `reportMasternodeResignPrincipal(operator)` accounts for the returned principal without inflating the reward share. * **Per-operator tracking** of outstanding principal both globally and per operator (`outstandingValidatorPrincipalByOperator`). * **No principal-stake slashing.** XDC penalizes underperforming masternodes via temporary exclusion (\~2h) and missed rewards, but never burns staked capital. → [Custody Model](/for-partners/custody-model) *** ## Security Layers | Layer | Implementation | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Smart contract audits** | QuillAudits (98.8% on liquid staking) + Nethermind Security (custody / V3 surface) | | **Permissionless custody** | Validator keys and treasury secured by on-chain contracts | | **On-chain transparency** | Every stake, queued withdrawal, claim, boost notification, migration, and loss report emits a public event | | **Non-upgradeable cores** | `PrimeStakedXDC_V3_2`, migration bridge, NFT collection, migrator, harvester, and bypass facet are all deployed with regular constructors | | **Controlled NFT vault upgrades** | Only `XdcNftStakingVault` is upgradeable, via TransparentUpgradeableProxy controlled by the protocol multisig; storage is ERC-7201 namespaced to remain collision-proof | | **Reentrancy protection** | OpenZeppelin `ReentrancyGuard` on every state-changing function | | **Pausable surfaces** | Vault, migrator, and harvester each expose `pause()`/`unpause()` under `PAUSER_ROLE` | | **Delayed governance** | Every sensitive parameter change (role rotations, loss caps, governance delay itself, ownership transfer) is a schedule → wait → execute flow | | **Loss caps** | `reportValidatorLoss` is bounded by `maxLossBpsPerReport` and `maxDailyLossBps`, both governed via delayed changes | *** ## Data Flow ### Staking 1. User calls `stake()` or `depositNative(assets, receiver)` on `PrimeStakedXDC_V3_2` with native XDC as `msg.value`. 2. Vault mints psXDC shares at the current exchange rate (`totalAssets / totalShares`). 3. Excess liquidity above the buffer triggers auto-propose if no queue backlog exists; XDC is delegated to a masternode through the XDC validator contract. ### Reward Accrual 1. Validator rewards flow back into the vault. 2. `totalAssets` increases; share supply does not. 3. Exchange rate rises automatically, so every psXDC share is worth more XDC. There is no manual `claim` step for the base layer. ### Withdrawal 1. User calls `redeemWithQueue(shares, receiver)` (or `withdrawWithQueue(assets, ...)`). 2. If `maxRedeem(user) >= shares`, the redemption settles **instantly** in the same transaction. 3. Otherwise the request enters the FIFO queue; shares are escrowed inside the vault. Settlement uses the live exchange rate at processing time. 4. `processWithdrawalQueue(maxRequests)` is permissionless; anyone can push the queue forward. 5. Failed receiver payouts defer into `pendingQueuedAssets`; the user claims later via `claimQueuedAssets`. ### Boost (NFT layer) 1. Treasury / harvester pushes XDC into `XdcNftStakingVault.notifyBoost(amount)`. 2. The vault converts XDC to psXDC v3 shares and increments `rewardPerWeightStored`. 3. Each staked NFT's pending boost grows proportionally to its weight (`stakedShares × (rarityMultiplier + level + lockBonus)`). 4. NFT holder calls `claim(tokenId, unwrap)` from the app to settle their slice in XDC or shares. ### V2 → V3 Migration 1. **psXDC**: user approves the bridge, calls `migrate(amount, minSharesOut)`. Bridge burns V2 → vault mints V3 shares while migration window is open. 2. **NFTs**: user approves the migrator, calls `migrate(tokenId, minSharesOut)`. Migrator pulls legacy NFT → claims pending V2 rewards (best-effort) → calls `migratorPrepareForBurn` on the legacy Diamond if locked → `burnAndRedeem` on the legacy façade → bridges redeemed psXDC into V3 shares → `mintAndStake[Locked]` on the new vault under the same `tokenId`. *** ## Integration Points | Integration Level | Description | Use Case | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- | | **Frontend** | Embed PrimeStaking widgets or build a custom frontend on top of the contracts | White-label web integration | | **Smart Contract** | Call `PrimeStakedXDC_V3_2` directly for stake/withdraw, or `migrate` on the bridge. ERC-4626 standard means partner contracts can wrap psXDC as collateral. | Backend / API integration | | **Data / Reporting** | On-chain event indexing via [`staking-v3-indexer`](https://github.com/PrimeNumbersLabs/staking-v3-indexer) and [`xdc-nft-v3-indexer`](https://github.com/PrimeNumbersLabs/xdc-nft-v3-indexer) for portfolio and settlement reporting | Compliance and reconciliation | → [Integration Models](/for-partners/integration-models) → [Custody Model](/for-partners/custody-model) → [Governance](/for-partners/governance) # Custody Model PrimeStaking operates a **non-custodial, smart contract-based** custody model. Validator keys and staked assets are managed entirely by audited on-chain contracts - no human interaction in custody flows. *** ## Design Principles | Principle | Implementation | | ------------------ | ------------------------------------------------------------------------------------------- | | **Non-custodial** | Users retain full ownership of assets at all times | | **Permissionless** | Anyone can verify validator state and staked assets on-chain | | **Trustless** | No single entity controls validator keys - the protocol enforces custody rules through code | | **Transparent** | All custody operations are logged on the blockchain | *** ## How It Works ### Validator Key Management * Validator keys are generated and secured by on-chain smart contracts * No human operator has direct access to private keys * Key rotation and management are governed by contract logic ### Staked Asset Custody * User XDC deposits are held in the [`PrimeStakedXDC_V3_2`](/products/contract-addresses) vault. It is **non-upgradeable**, so the logic that holds your XDC can never be modified * The vault keeps a tunable **liquid buffer** (default 5% of total assets); excess is auto-delegated to KYC-verified masternode operators on the XDC Network * Withdrawal requests use `redeemWithQueue`: instant when the buffer covers them, queued FIFO otherwise. Failed payouts defer into `pendingQueuedAssets` and the user collects them via `claimQueuedAssets`. There is no admin approval step at any point. * The vault has **no `mint` and no `ownerWithdraw`**; these were removed in V3. Even the protocol admin cannot move user funds. *** ## Two Distinct Layers It is important to distinguish between **asset custody** and **contract governance**: | Layer | Mechanism | Human Involvement | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | **Validator key custody** | Fully on-chain, smart contract-managed | None - trustless by design | | **psXDC v3 vault** | Non-upgradeable, deployed with a regular constructor, no proxy | None - cannot be modified | | **NFT staking vault upgrades** | TransparentUpgradeableProxy with ERC-7201 namespaced storage, controlled by the protocol multisig with delayed governance | Yes - multi-party approval required for vault implementation changes | | **Parameter changes (psXDC v3)** | Role-gated + delayed governance (schedule → wait → execute) | Yes - multi-party approval, but cannot move user funds | User funds are secured by code with zero human access. The psXDC vault itself cannot be upgraded. Only the NFT staking vault is upgradeable, and only through the multisig + delayed-governance path. → [Governance Details](/for-partners/governance) *** ## Institutional Considerations | Question | Answer | | --------------------------------- | ------------------------------------------------------------------------------ | | **Who controls the masternodes?** | Smart contracts manage validator operations programmatically | | **Who signs upgrades?** | Multisig governance with timelock (see [Governance](/for-partners/governance)) | | **Is there a multisig?** | Yes - contract upgrades require multi-party approval | | **Is there a timelock?** | Yes - upgrade execution is delayed to allow review | | **Who controls the treasury?** | Protocol treasury is governed by multisig with transparent on-chain operations | | **Is there automated reporting?** | Yes - all staking, reward, and withdrawal events are indexed on-chain | *** ## Audit & Collaboration The custody model is developed in collaboration with: * **Nethermind** - smart contract development and security review * **XDC Core team** - network-level validator integration * **QuillAudits** - independent external audit (98.8% score on staking contracts) The custody substrate (the `PrimeStakedXDC_V3` vault design + `PrimeStakedXDC_V3MigrationBridge`) was independently audited by **Nethermind Security** in **NM-0843, XDC Prime Stake** (final report **May 08, 2026**). All Critical, High, and Medium findings are Fixed. The live vault, `PrimeStakedXDC_V3_2`, is a redeployment of this audited codebase. See the [Audits page](/security/audits-1) for the V3.2 delta. [Full report (PDF)](https://github.com/PrimeNumbersLabs/primestaking-gitbook/tree/main/NM_0843_xdc_prime_stake_FINAL_updated_tests.pdf). *** ## Risk Mitigation | Risk | Mitigation | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Smart contract exploit** | Independent audits, reentrancy guards, pausable contracts | | **Validator downtime** | Multi-validator delegation, performance monitoring | | **Unauthorized upgrades** | psXDC v3 vault is **non-upgradeable** (cannot happen); NFT vault upgrades require multisig + delayed governance | | **Key compromise** | On-chain key management - no human access to private keys | | **Delayed withdrawals** | Transparent FIFO queue; instant when the buffer permits, otherwise bounded by the network's `candidateWithdrawDelay` (\~35 days under typical block times) | *** ## What This Means for Partners * **No third-party custodian risk** - assets are secured by code, not by an institution * **Verifiable at any time** - on-chain state is the single source of truth * **No operational dependency** - the protocol operates autonomously once deployed * **Institutional-grade transparency** - full auditability aligned with exchange compliance requirements # Integration Models PrimeStaking offers two integration models for exchanges, custodians, and institutional partners. Both leverage the same audited, battle-tested infrastructure. *** ## Model A - White Label **Your brand. Our infrastructure.** The partner operates XDC staking under their own brand, powered by PrimeStaking's architecture. End users interact with the partner's interface and never see PrimeStaking branding. ### What We Provide * Full access to the liquid staking contract suite * Managed validator infrastructure with SLA * Settlement reconciliation data and on-chain proof of reserves * Dedicated partner support during and after integration ### Partner Responsibilities * Frontend development and UX under their own brand * User onboarding, KYC/AML (if applicable) * Customer support (Tier 1) * Regulatory compliance in their jurisdiction *** ## Model B - Powered by Prime **Co-branded integration. Minimal technical lift.** The partner integrates PrimeStaking with visible "Powered by PrimeStaking" branding. This model requires significantly less development effort. ### What We Provide * Drop-in staking UI that partners can embed directly * Co-branded experience with partner logo alongside PrimeStaking branding * Managed infrastructure including validator operations, reward distribution, and withdrawal processing * Standard on-chain reporting ### Partner Responsibilities * Embed the PrimeStaking widget in their platform * Direct users to the staking interface * Optional: provide supplementary user support *** ## Comparison | | White Label (Model A) | Powered by Prime (Model B) | | ---------------------- | --------------------------- | ---------------------------------------- | | **Branding** | Partner's brand only | Co-branded | | **Integration effort** | Higher (custom frontend) | Low (embed widget) | | **Customization** | Full control over UX | Widget configuration | | **Infrastructure** | Managed by PrimeStaking | Managed by PrimeStaking | | **SLA** | Custom SLA | Standard SLA | | **Best for** | Exchanges, large custodians | Wallets, aggregators, regional platforms | Commercial terms - including fees, revenue share, and SLA specifics - are discussed during the partnership process. Contact us for a tailored proposal. *** ## Integration Process | Phase | Activities | | --------------- | --------------------------------------------------------------- | | **Discovery** | Requirements gathering, technical scoping, commercial alignment | | **Integration** | Technical setup, frontend development (if applicable), testing | | **UAT** | User acceptance testing in staging environment | | **Go-live** | Production deployment, monitoring, launch support | Timelines vary depending on the integration model and partner's technical readiness. *** ## Next Steps Contact us to discuss which model fits your needs: * **Email:** * **Website:** [primestaking.xyz](https://primestaking.xyz) # Revenue Model PrimeStaking generates revenue from staking operations on the XDC Network. Partners participate in this revenue through transparent, on-chain mechanisms. *** ## How Revenue Is Generated PrimeStaking generates revenue through staking operations on the XDC Network. Masternodes operated by the protocol participate in the XDC consensus mechanism and earn block rewards. These rewards form the basis of all revenue and yield distribution across the protocol. Revenue allocation between PrimeStaking, institutional partners, and end users is defined contractually for each integration. The specific split depends on the partner's TVL contribution, integration model, and distribution strategy. *** ## Partner Revenue Model Partners earn a share of the protocol fees generated through their integration. Revenue share terms are negotiated as part of the partnership agreement and depend on: * Expected TVL contribution * Integration model (White Label vs. Powered by Prime) * Operational and support commitments For specific commercial terms, contact us at . *** ## Settlement & Reporting | Component | Description | | ------------------------ | ------------------------------------------------- | | **Settlement frequency** | Monthly | | **Data source** | On-chain events (staking, rewards, withdrawals) | | **Reconciliation** | Automated reporting with transaction-level detail | | **Proof of reserves** | On-chain verifiable at any time | Partners receive monthly settlement reports covering TVL, gross rewards, protocol fees, partner revenue share, and net user distributions. *** ## Revenue Sustainability PrimeStaking's revenue model is tied to real validator economics on the XDC Network: * **Validator rewards** are generated by the XDC Network consensus mechanism * **No token emissions** are required to sustain yield - rewards come from network staking * **Protocol fees** are a percentage of actual rewards, not inflationary tokenomics * **Scalable** - revenue grows linearly with TVL without additional infrastructure cost per user # Reward Mechanics This section explains how XDC liquid staking rewards are generated and distributed under V3. The model is **NAV-based**: rewards are not handed out via a manual `claim` flow; they are embedded in the psXDC vault share price. *** ## Reward Source PrimeStaking generates yield through XDC Network masternode operations. Validators participate in the XDPoS consensus process and receive protocol rewards derived from block production and network activity. Unlike ETH-based liquid staking protocols, XDC Network **does not implement punitive principal-slashing mechanisms comparable to Ethereum Casper**. XDC's slashing instead penalizes downtime: a masternode that fails to sign any block during one full epoch (900 blocks, \~30 minutes) is excluded from block production for the next 4 epochs (\~2 hours) and forfeits rewards during that window. Validator penalties are therefore limited to operational demotion and reward impacts, without destruction of the underlying staked capital. This creates a materially lower staking risk profile for institutional partners and end users. *** ## Why Use PrimeStaking vs. Direct Staking Direct XDC staking requires running a masternode (10M XDC minimum, infrastructure management, uptime obligations). PrimeStaking removes all of these barriers: | | Direct Staking | PrimeStaking V3 | | ---------------------------- | ------------------------------ | --------------------------------------------------- | | **Minimum** | 10,000,000 XDC | None | | **Infrastructure** | Run and maintain a masternode | Fully managed | | **Liquidity** | Locked until unstake | Liquid (psXDC is ERC-4626, transferable, tradeable) | | **Principal-stake slashing** | None (XDC model) | None (XDC model) | | **Reward rate** | Depends on your node's uptime | Pooled across optimized validators | | **Composability** | None | psXDC usable as ERC-4626 collateral in DeFi | | **Withdrawal UX** | Wait the network unstake delay | Instant when buffer allows; FIFO queue otherwise | *** ## How rewards reach holders ``` XDC validators │ block rewards ▼ PrimeStakedXDC_V3_2 vault │ totalAssets += rewards │ totalShares unchanged ▼ exchange rate (totalAssets / totalShares) ↑ │ ▼ every psXDC share is worth more XDC ``` | Aspect | Detail | | -------------------------- | ------------------------------------------------------------------------------------------------------------ | | **Source** | XDC Network masternode block rewards | | **Accrual mechanism** | Reward XDC enters the vault → `totalAssets` rises → exchange rate rises automatically | | **User claiming** | None; value is already inside each share | | **Settlement event** | When the user redeems shares (instant or queued), the higher rate translates directly into more XDC returned | | **On-chain verifiability** | Yes. Every reward inflow event and the exchange rate are public | There is **no `notifyRewardAmount` admin call** in V3 (V2-era behaviour). There is **no per-user `claim` flow** for the base reward layer. Both were removed when V3 replaced the time-based APY model with the share-based NAV model. *** ## Calculation | Parameter | Detail | | ---------------------- | ------------------------------------------------------------------------------------------------------------------- | | **Gross APY** | Determined by XDC Network masternode economics (network staking ratio, validator performance, operator throughput) | | **Protocol fee** | Percentage of gross validator rewards retained by the protocol (exact figure available under partner due diligence) | | **Net user APY** | \~5.5% net (variable; depends on the above) | | **Distribution basis** | Pro-rata over psXDC shares **automatically through share price**, not at claim time | Net APY is variable and depends on: * **Network staking ratio.** Total XDC staked across the network affects per-validator rewards. * **Validator performance.** Uptime and block production efficiency for the operators the vault is delegating to. * **Protocol fee.** Retained percentage before reward XDC is reflected in `totalAssets`. *** ## NFT boost layer (separate from base APY) XDC NFTs earn an **additional** XDC stream on top of base NAV via the Synthetix-style accumulator inside `XdcNftStakingVault`. The boost is **separate** from validator rewards and follows its own funding model: * Boost is pushed into the NFT vault by [`XdcNftBoostHarvester`](/products/xdc-staking-nfts/boost-harvester) via `notifyBoost(amount)`. * The boost slice is distributed pro-rata to each NFT's weight (`stakedShares × (rarityMultiplier + level + lockBonus)`). * Boost **is** claimed (`claim(tokenId)`) and paid in XDC. Boost is a product-side reward stream, not validator economics. The **floor** for every NFT position is the **base \~5.5%** (psXDC v3 NAV appreciation, automatic, never goes away regardless of rarity / lock / boost cadence). When the harvester is feeding the accumulator, the combined APY ranges from **\~5.75% (Plentiful unlocked)** up to **\~7% (Handcrafted locked)**; the delta over the floor is the boost slice. → [Reward Model: Base NAV + Boost](/products/xdc-staking-nfts/xdc-nft-staking-reward-system) *** ## Key Parameters for Partners | Parameter | Detail | | ---------------------------------- | --------------------------------------------------------------------------------------- | | **Reward asset (base layer)** | XDC, accruing as share-price appreciation of psXDC | | **Reward asset (NFT boost)** | XDC, accruing into the NFT vault's Synthetix accumulator | | **Distribution frequency (base)** | Continuous via share-price growth (no batches) | | **Distribution frequency (boost)** | Each `notifyBoost` event; cadence is an operational choice (typically weekly or daily) | | **Claim flow (base)** | None. Rewards are realized on redemption | | **Claim flow (boost)** | User-initiated `claim(tokenId)` from the NFT detail page | | **On-chain verifiability** | Yes, both layers emit events indexed by the public subgraphs | | **Principal-stake slashing** | None. XDC penalizes downtime via \~2h exclusion + missed rewards, never burns principal | *** ## Loss Reporting Validator outcomes can be reported via `reportValidatorLoss(operator, assets)` (gated by `RISK_MANAGER_ROLE`). The function is bounded by: * `maxLossBpsPerReport`: cap per individual report. * `maxDailyLossBps`: cap over a rolling 24h window. Both caps are themselves governed by **delayed governance**: changes are scheduled, wait for `governanceDelay`, then execute. Reports emit the attributed operator (`outstandingValidatorPrincipalByOperator` is updated atomically). This bounds the blast radius of any single risk-management call. *** ## Transparency & Verification * Every reward event is logged on the XDC blockchain. * Exchange rate is a deterministic function of `totalAssets` and `totalShares`, auditable at any block. * Historical exchange-rate data is available via the public subgraph for forecasting and reporting. * psXDC v3 supply and total assets are verifiable on-chain at any time on [XDCScan](https://xdcscan.com/address/0xDc74c0DaED82ae94486DeeF22991d2F54173c734). → [Liquidity Model](/for-partners/liquidity-model) → [Risk & Compliance](/for-partners/risk-and-compliance) → [How Rewards Work (user-facing)](/products/xdc-liquid-staking/xdc-staking-rewards) # Liquidity Model PrimeStaking V3 separates **protocol redemption** (burning shares for XDC against the vault) from **market price** (psXDC on a DEX). Both stay healthy for partner integrations, but they behave differently and the difference is important. *** ## psXDC V3 Token Properties | Property | Detail | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Name** | psXDC (Prime Staked XDC) | | **Standard** | ERC-4626 vault share | | **Pricing** | Exchange rate `totalAssets / totalShares`, which grows over time as validator rewards accrue. **Not a fixed 1:1.** | | **Network** | XDC Network (chain ID `50`) | | **Address** | [`0xDc74c0DaED82ae94486DeeF22991d2F54173c734`](https://xdcscan.com/address/0xDc74c0DaED82ae94486DeeF22991d2F54173c734) | | **Transferable** | Yes (standard XRC-20 token) | | **Yield mechanism** | Share-price appreciation; rewards are already inside the share, so there is no manual `claim` | | **Redeemable against the protocol** | Yes: `withdraw` / `redeem` (instant when buffer suffices) or `redeemWithQueue` (instant or queued) | | **Market-tradeable** | Yes, on XSWAP and other DEXs | *** ## Two distinct exit paths ### 1. Protocol redemption (NAV-based) When you burn psXDC against the vault, you receive XDC at the **current exchange rate**, not a fixed 1:1. The amount is `convertToAssets(shares)`. * **Instant** when the vault's liquid buffer (default 5% of total assets, configurable via `setBufferBps`) covers your request, settled in the same transaction. * **Queued** when the buffer is insufficient: escrows the shares, adds you to the FIFO queue. Processed as new deposits / reward inflows / masternode resignations replenish liquidity. * **No partial fills.** Each request settles in full when its turn comes. * **Free cancellation.** You can `cancelQueuedWithdrawal` any time before settlement and get your shares back unchanged. For very large redemptions where the vault doesn't have a sufficient buffer + recent rewards, the upper bound on settlement is the XDC Network's `candidateWithdrawDelay`, about 35 days under typical real-world block times. This delay is a network-level property of XDC's masternode unstaking flow, not a PrimeStaking-specific gate. → [Withdrawals: Instant vs Queued](/products/xdc-liquid-staking/staking-guide/withdrawals-instant-vs-queued) ### 2. Market exit (DEX swap) Holders can swap psXDC for XDC on a DEX (always verify the pool holds the live V3.2 token, `0xa7FD…73e4`). Market price is set by the AMM and is influenced by: * The vault's current NAV (`totalAssets / totalShares`), the long-run anchor. * Pool depth and recent volume. * Demand for immediate liquidity vs willingness to wait for protocol redemption. The market price can sit **at, above, or below NAV** depending on these factors. Arbitrageurs can close large gaps using the protocol's instant redemption path when liquidity is available, but small NAV/market deltas are normal. | Concept | NAV (protocol) | Market price (DEX) | | -------------- | --------------------------------------------------- | ------------------------- | | **Reference** | `totalAssets / totalShares` | AMM pool ratio | | **Updates** | When rewards or losses are reflected on-chain | Continuously via trades | | **Slippage** | None for amounts within the buffer; queue otherwise | Subject to pool depth | | **Settlement** | Instant or queued by the vault | Atomic at trade execution | *** ## Implications for Partners | Consideration | Detail | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Two value references** | A user's psXDC balance can be valued either at NAV (`convertToAssets`) or at DEX market price. Use NAV for accounting and partner reporting; DEX price for synchronous trading flows. | | **Self-service withdrawals** | Partners do not need to operate any approval flow; users can redeem on their own through `redeemWithQueue`. | | **Buffer planning** | If you expect bursty user withdrawal patterns, coordinate with PrimeStaking on buffer sizing (`setBufferBps`); this affects how often partner users hit the queue. | | **Queue UX** | Partners surfacing psXDC redemption should distinguish "complete" from "queued, self-claim later" outcomes. The contract makes this explicit through events. | | **DEX integration** | psXDC pools provide an instant exit, but the protocol's NAV is the canonical value and is what should drive any institutional reporting. | *** ## Liquidity Risk Assessment | Risk | Likelihood | Impact | Mitigation | | ---------------------------------------------- | ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | psXDC trades at a discount to NAV on a DEX | Medium | Low | Arbitrageurs can buy on the DEX and redeem at NAV when the queue allows; the protocol cannot guarantee zero discount in all conditions. | | Mass redemption event | Low | Medium | FIFO queue ensures fair sequencing; the protocol cannot become insolvent because each redemption settles at the live share rate against on-chain assets. | | Buffer is too small for normal partner traffic | Low | Medium | `setBufferBps` is governed by `OPERATIONS_MANAGER_ROLE` and can be tuned through the standard ops process. | | Failed receiver payout | Very low | Low | Deferred into `pendingQueuedAssets` and claimable via `claimQueuedAssets`. No XDC is lost. | *** ## Key Metrics for Partners All metrics below are verifiable on-chain via the [staking-v3-indexer](https://github.com/PrimeNumbersLabs/staking-v3-indexer) or direct calls to `PrimeStakedXDC_V3_2`. | Metric | Description | Source | | -------------------------- | -------------------------------------------------------- | --------------------------------------------------- | | **psXDC total supply** | Outstanding V3 shares | `PrimeStakedXDC_V3_2.totalSupply()` | | **Total assets** | XDC tracked by the vault (buffer + delegated) | `PrimeStakedXDC_V3_2.totalAssets()` | | **Exchange rate** | `totalAssets / totalShares` (or `convertToAssets(1e18)`) | Vault view | | **Buffer ratio** | Current liquid XDC vs target buffer | Computed from `getBalance` + `bufferBps` | | **Queue depth** | Outstanding `WithdrawalQueued` requests | Subgraph | | **Per-operator principal** | XDC delegated per masternode operator | `outstandingValidatorPrincipalByOperator(operator)` | | **DEX market price** | psXDC/XDC pool quote | XSWAP price feed | Partners evaluating large position sizes should review the **buffer** and **queue depth** in parallel with DEX pool depth, and reach out to discuss sizing. → [Reward Mechanics](/for-partners/reward-mechanics) → [Risk & Compliance](/for-partners/risk-and-compliance) → [Deployed Contracts & Addresses](/products/contract-addresses) # Governance PrimeStaking V3 splits operational, risk, and governance responsibilities across **five roles** with mandatory delayed execution on every sensitive change. The psXDC vault itself is non-upgradeable; only the NFT staking vault is upgradeable, and only through a delayed-governance path. *** ## What governance can and cannot do | Action | Possible under governance? | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Mint psXDC to anyone | **No.** `mint()` is disabled in V3 | | Withdraw user XDC from the vault | **No.** There is no `ownerWithdraw` function | | Upgrade `PrimeStakedXDC_V3_2` | **No.** Non-upgradeable, deployed with a regular constructor | | Upgrade `XdcNftStakingVault` implementation | Yes, through a TransparentUpgradeableProxy controlled by the protocol multisig with delayed handover | | Rotate operational / risk roles | Yes, via the delayed-governance path | | Change loss caps (`maxLossBpsPerReport`, `maxDailyLossBps`) | Yes: schedule → wait `governanceDelay` → execute | | Pause vault / migrator / harvester | Yes; `PAUSER_ROLE` (multisig) can pause immediately | | Bypass the time-lock | **No.** Direct `grantRole`/`revokeRole`/`renounceRole` are disabled to prevent bypass | → [Custody Model](/for-partners/custody-model) for details on what the validator and asset layer guarantees. *** ## Role Separation (psXDC v3 vault) | Role | Holder | Scope | | ------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------- | | `DEFAULT_ADMIN_ROLE` | Protocol multisig | Master switch; schedules and executes delayed role/risk changes | | `OPERATIONS_MANAGER_ROLE` | Designated operations multisig/manager | `setBufferBps`, scan-limit tuning, auto-propose config, masternode parameter tuning | | `RISK_MANAGER_ROLE` | Designated risk operator | `reportValidatorLoss` (bounded by per-report and per-day caps) | | `PROPOSER_ROLE` | Designated proposer(s) | `proposeMasternode`, `reportMasternodeResignPrincipal` | | `MIGRATION_MANAGER_ROLE` | Migration manager | Opens/closes the V2→V3 migration window, tops up backing liquidity via `fundMigrationLiquidity` | No single key can both move funds and modify roles. Role rotations themselves require delayed execution. *** ## Delayed Governance: schedule → wait → execute Every sensitive change in `PrimeStakedXDC_V3_2` follows the same pattern: | Schedule | Execute (after `governanceDelay`) | Cancel | | ------------------------------- | --------------------------------- | ----------------------------------- | | `setGovernanceDelay(delay_)` | `executeGovernanceDelay()` | `cancelGovernanceDelayChange()` | | `setOperationsManager(account)` | `executeOperationsManager()` | `cancelOperationsManagerChange()` | | `setRiskManager(account)` | `executeRiskManager()` | `cancelRiskManagerChange()` | | `setMaxLossBpsPerReport(bps)` | `executeMaxLossBpsPerReport()` | `cancelMaxLossBpsPerReportChange()` | | `setMaxDailyLossBps(bps)` | `executeMaxDailyLossBps()` | `cancelMaxDailyLossBpsChange()` | Ownership handoff uses the same pattern: `scheduleOwnerTransfer(newOwner)` → wait → `executeOwnerTransfer()` (or `cancelOwnerTransfer()`). `transferOwnership` and `renounceOwnership` are **disabled** so ownership can never change without the delay. `governanceDelay` itself is bounded between `MIN_GOVERNANCE_DELAY` and `MAX_GOVERNANCE_DELAY` (default 1 day; min 1 minute, max 30 days). *** ## Upgrade Policy | Component | Upgrade path | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PrimeStakedXDC_V3_2` | **None.** Non-upgradeable. Replacing the vault requires deploying a new contract and migrating. | | `PrimeStakedXDC_V3MigrationBridge` | **None.** Non-upgradeable. Treasury operations are delayed and capped. | | `XdcStakedNFT` (collection) | **None** (non-upgradeable). | | `XdcNftMigrator` | **None** (non-upgradeable). | | `XdcNftBoostHarvester` | **None** (non-upgradeable). | | `XdcNftStakingVault` (implementation) | TransparentUpgradeableProxy. Implementation changes are executed by the proxy admin, which is owned by the protocol multisig. ERC-7201 namespaced storage prevents accidental slot collisions on future upgrades. | | `LegacyMigratorBypassFacet` | Replacement requires a new `diamondCut` on the legacy Diamond (multisig). | *** ## Treasury & Bridge controls The V3 migration bridge has its own delayed-governance and rate-limit machinery: | Control | Detail | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Excess treasury withdrawal | Two-step: `withdrawExcessNative(recipient, amount)` (schedule) → `executeExcessNativeWithdrawal()` (after delay). Cancel any time with `cancelExcessNativeWithdrawal()`. | | Daily outflow guard | `setDailyWithdrawalCap(amount)` bounds total daily outflows. | | Owner handoff | Two-step delayed transfer, same shape as the vault. | *** ## Pause / Emergency | Surface | Pause role | Effect | | ---------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | `PrimeStakedXDC_V3_2` | `PAUSER_ROLE` (multisig) | Halts stake/redeem flows for incident response | | `XdcNftStakingVault` | `PAUSER_ROLE` (multisig) | Halts stake/withdraw/claim; `notifyBoost` is **intentionally** still allowed so boost flow continues during ops windows | | `XdcNftMigrator` | `PAUSER_ROLE` (multisig) | Halts new V2→V3 NFT migrations | | `XdcNftBoostHarvester` | `PAUSER_ROLE` (multisig) | Halts new boost pushes | Pauses are immediate (no delay) so the multisig can react to incidents. **Resuming** requires a multisig `unpause()` call; no parameter changes happen during a pause beyond what the underlying role functions allow. *** ## Decision-Making Framework | Decision Type | Process | | ----------------------------------- | ------------------------------------------------------------- | | Routine masternode propose / resign | `PROPOSER_ROLE` execution; bounded by on-chain limits | | Buffer / scan-limit tuning | `OPERATIONS_MANAGER_ROLE` execution | | Loss caps / role rotations | Schedule → wait `governanceDelay` → execute | | NFT vault upgrade | Multisig proxy admin call, after audit + partner notification | | Migration window open / close | `MIGRATION_MANAGER_ROLE` | | Emergency pause | Multisig (immediate) | | New audit / partner agreement | Team + legal review | *** ## What this means for Partners * **No unilateral changes.** Every sensitive change is publicly scheduled before it can take effect. * **Predictable execution.** `governanceDelay` is on-chain; partners can monitor pending changes through events without privileged access. * **No admin path to user funds.** The V3 vault's design (no `mint`, no `ownerWithdraw`, no upgrade) means governance literally cannot move staker XDC. * **Auditability.** All role grants, schedules, executions, and parameter updates emit events indexed by the public subgraph. → [Custody Model](/for-partners/custody-model) → [Architecture Overview](/for-partners/architecture) → [Risk & Compliance](/for-partners/risk-and-compliance) # Risk & Compliance PrimeStaking maintains a comprehensive risk framework and compliance posture designed for institutional partners and regulated environments. *** ## Risk Framework ### Smart Contract Risk | Risk | Severity | Mitigation | | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Contract vulnerability | High | Independent external audits (QuillAudits - 98.8% score on V1 liquid staking; Nethermind Security NM-0843 on V3 vault + V3 Migration Bridge, all Critical/High/Medium findings Fixed), reentrancy guards, emergency pause on the V3 vault | | Upgrade error | Medium | psXDC v3 vault is **non-upgradeable**; only the NFT staking vault is upgradeable, and only via multisig + delayed governance | | Dependency failure | Medium | Minimal external dependencies; core logic is self-contained | | Economic attack | Medium | Buffer + FIFO queue design, bounded scans, per-report and per-day loss caps | | Migration risk | Low | One-shot atomic migration with `minSharesOut` slippage protection; migration window is gated; failure modes always revert | ### Validator Risk | Risk | Severity | Mitigation | | -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Validator downtime | Medium | Multi-validator delegation, automated failover monitoring | | Slashing (principal-stake) | **None** | XDC's slashing mechanism penalizes downtime via temporary exclusion from block production (\~2h, 4 epochs) and missed rewards, but never burns principal. This is structurally different from ETH-based liquid staking, where slashing can permanently destroy a portion of staked ETH | | Reward rate change | Low | Dynamic APY calculation; transparent communication to partners | ### Network Risk | Risk | Severity | Mitigation | | ------------------ | -------- | --------------------------------------------------------------- | | XDC Network halt | Low | Protocol pauses automatically; no loss of funds | | Fork / chain split | Low | Protocol follows canonical chain; manual intervention if needed | | Congestion | Low | Transaction prioritization; gas optimization in contracts | ### Operational Risk | Risk | Severity | Mitigation | | -------------------- | -------- | -------------------------------------------------------------- | | Key compromise | High | On-chain smart contract custody - no human key access | | Unauthorized upgrade | High | Multisig + timelock governance | | Team dependency | Medium | Open-source contracts; protocol operates autonomously on-chain | *** ## Audit History | Module | Auditor | Findings / Score | Status | | --------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------- | | **XDC Staking Contract (V1 liquid)** | QuillAudits | 98.8% score | Published | | **psXDC V3 vault + V3 Migration Bridge** (NM-0843) | Nethermind Security | 21 findings (1C / 2H / 1M / 6L / 9I / 2BP): **18 Fixed / 3 Acknowledged** | **Published May 8, 2026** | | **XDC NFT V3 stack** (vault, collection, migrator, harvester, bypass facet) | Internal; Nethermind planned | 46 unit tests + 17-test audit-fix regression battery | Internal review complete; external review planned | **Nethermind Security NM-0843, XDC Prime Stake** (final report, May 08, 2026) covered `PrimeStakedXDC_V3.sol` and `PrimeStakedXDC_V3MigrationBridge.sol` (1,391 LoC). All Critical, High, and Medium findings are Fixed. The three Acknowledged findings are operationally mitigated (loss caps for risk-manager front-running, pre-deployment seed enforcement, and two-call workaround for partial-fill queue redemption). The live vault, `PrimeStakedXDC_V3_2`, is a redeployment of this audited codebase with a scoped delta for the staged collateral transition; a follow-up external audit of the delta is in progress; see [Audits](/security/audits-1). [→ Read the full NM-0843 report (PDF)](https://github.com/PrimeNumbersLabs/primestaking-gitbook/tree/main/NM_0843_xdc_prime_stake_FINAL_updated_tests.pdf) All audit reports are published publicly. Target: **>= 95% score** on every audit, with findings of Medium severity or higher resolved within **72 hours**. → [Full Audit Reports](/security/audits-1) *** ## Compliance Posture ### Protocol Level * **Non-custodial** - PrimeStaking never takes custody of user funds * **Permissionless** - no KYC/AML at the protocol level (open smart contracts) * **Transparent** - all operations verifiable on-chain * **Jurisdiction-agnostic** - smart contracts operate globally without geographic restriction ### Partner Level Partners integrating PrimeStaking are responsible for: * KYC/AML compliance in their jurisdiction * Sanctions screening for their users * Tax reporting and regulatory filings * Data privacy (GDPR, CCPA, etc.) for their user base PrimeStaking provides the technical infrastructure; regulatory compliance is handled by the partner at the integration layer. *** ## Incident Response | SLA | Target | | -------------------------- | -------------------------------------------------------- | | **Critical vulnerability** | Pause contracts within 1 hour; patch within 24 hours | | **Medium severity issue** | Assess within 4 hours; resolve within 72 hours | | **Low severity issue** | Assess within 24 hours; resolve in next scheduled update | → [SLA & Support](/for-partners/sla-and-support) *** ## Liability Framework ### In Case of a Bug or Exploit * PrimeStaking contracts are audited but not guaranteed to be vulnerability-free * In the event of an exploit, the protocol will pause operations, assess damage, and work to recover funds * Partners should carry their own insurance and implement user-facing risk disclosures ### In Case of Delayed Withdrawals * In V3, withdrawals settle **instantly** when the vault buffer covers them; otherwise they enter the on-chain FIFO queue and settle as new deposits, reward inflows, or masternode resignations replenish liquidity. * For redemptions that depend on a masternode resignation, the upper bound is the XDC Network's `candidateWithdrawDelay`, approximately **35 days** under typical real-world block times (longer under network congestion). * PrimeStaking does not guarantee specific withdrawal timelines; the queue is FIFO and depends on network conditions and protocol-level cash flow. * Partners should communicate **both paths** (instant-when-possible and queued-with-self-claim) to their users. ### In Case of Reward Rate Changes * APY is variable and depends on validator performance and network conditions * PrimeStaking communicates material changes to partners with reasonable notice * Historical reward data is available on-chain for forecasting → [Full Disclaimer](/security/audits-1/disclaimer) # SLA & Support PrimeStaking provides differentiated support and uptime commitments based on the partner's integration model. *** ## Uptime SLA | Component | Target | Measurement | | ------------------------------- | ------ | ------------------------------------------------------- | | **Smart contracts** | 99.9% | On-chain availability (dependent on XDC Network uptime) | | **Validator operations** | 99.5% | Validator uptime and reward generation | | **API / SDK** | 99.5% | Availability of off-chain integration endpoints | | **Frontend (Powered by Prime)** | 99.0% | Widget / embedded UI availability | Uptime is measured monthly. Downtime due to XDC Network-level issues is excluded from SLA calculations. *** ## Incident Response | Severity | Response Time | Resolution Target | | ----------------------------------------------- | ------------- | ----------------------------- | | **Critical** (fund loss risk, contract exploit) | < 1 hour | Pause + patch within 24 hours | | **High** (degraded service, delayed rewards) | < 4 hours | Resolution within 48 hours | | **Medium** (non-critical bug, UI issue) | < 24 hours | Resolution within 72 hours | | **Low** (cosmetic, documentation) | < 48 hours | Next scheduled release | *** ## Support Tiers ### White Label Partners (Model A) | Feature | Included | | --------------------------------- | --------------------------------- | | **Dedicated partner manager** | Yes | | **Technical integration support** | Yes (during onboarding + ongoing) | | **Priority incident response** | Yes | | **Custom SLA negotiation** | Available | | **Monthly performance review** | Yes | | **Slack / Telegram channel** | Dedicated private channel | ### Powered by Prime Partners (Model B) | Feature | Included | | ------------------------------ | -------------------------- | | **Integration support** | Yes (during onboarding) | | **Standard incident response** | Yes | | **Email support** | Yes | | **Monthly reporting** | Standard automated reports | *** ## Monitoring & Reporting | Capability | Description | | ------------------------------ | ------------------------------------------------------------- | | **On-chain monitoring** | Real-time tracking of staking, rewards, and withdrawal events | | **Validator health dashboard** | Uptime, reward rate, and performance metrics | | **Monthly settlement reports** | TVL, rewards generated, fees, revenue share | | **Incident post-mortems** | Published within 7 days of any critical incident | *** ## Upgrade Policy * The **psXDC v3 vault is non-upgradeable**; its logic can never be modified. The same holds for the V3 migration bridge, NFT collection, NFT migrator, and boost harvester. Any change to these contracts requires deploying new ones and migrating. * Only the **`XdcNftStakingVault`** is upgradeable (TransparentUpgradeableProxy controlled by the protocol multisig, with ERC-7201 namespaced storage). Implementation changes go through **multisig governance + delayed handover**. * Parameter changes on the psXDC v3 vault (loss caps, role rotations, governance delay) follow the on-chain **delayed governance** pattern: schedule → wait `governanceDelay` → execute. Partners can monitor pending changes via on-chain events. * Partners are notified **at least 7 days** before any material NFT vault upgrade or psXDC governance change. * Emergency pauses (vault, migrator, harvester) are immediate and require multisig approval. Resuming requires a separate multisig `unpause` call. * Upgrade history and changelogs are published in documentation. *** ## Contact For support inquiries: * **Email:** # Audits ## Security Audits All PrimeStaking smart contracts undergo independent external audits before deployment and whenever significant updates are introduced. *** ### Methodology 1. **Reputable external auditor** - We partner with leading firms (e.g., QuillAudits) that review every line of code and validate the economic logic of the contracts. 2. **Two-phase process** * *Preliminary report:* Identification of findings. * *Fix & Verify:* The engineering team resolves issues and the auditor performs final verification. 3. **Transparent disclosure** - Full reports are published so the community can verify the scope and applied fixes. *** ### Published Reports | Module | Auditor | Findings | Link | | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | [**XDC Staking Contract (V1 / liquid staking)**](https://www.quillaudits.com/leaderboard/prime-numbers/prime-numbers-staking-contract) | QuillAudits | 98.8% score | [Report](https://www.quillaudits.com/leaderboard/prime-numbers/prime-numbers-staking-contract) | | **psXDC V3 vault + V3 Migration Bridge** (NM-0843) | Nethermind Security | 1 Critical · 2 High · 1 Medium · 6 Low · 9 Info · 2 Best Practices (**18 Fixed / 3 Acknowledged**) | [Report (PDF)](https://github.com/PrimeNumbersLabs/primestaking-gitbook/tree/main/NM_0843_xdc_prime_stake_FINAL_updated_tests.pdf) | {% embed url="" %} > Our target is to keep every audit score **>= 95%** and close findings of Medium severity or higher within **72 hours**. *** ### Nethermind Security: NM-0843, XDC Prime Stake (May 08, 2026) **Scope (1,391 LoC):** * `PrimeStakedXDC_V3.sol`: ERC-4626 native-XDC vault, non-upgradeable, with the buffer / FIFO queue / `claimQueuedAssets` flow, masternode round-robin auto-propose, delayed governance, role split, and per-report / per-day loss caps. * `PrimeStakedXDC_V3MigrationBridge.sol`: V2 psXDC → V3 share migration with `minSharesOut` slippage protection, time-locked excess withdrawals, daily withdrawal cap, and delayed owner transfer. **Process:** initial review (commit `f92b803`, March 26, 2026) → fix verification → final commit `2d97d9b` (May 08, 2026). Documentation Assessment: Medium. Test Suite Assessment: Medium. **Findings, by severity and status:** | Severity | Count | Fixed | Acknowledged | | -------------- | ------ | ------ | ------------ | | Critical | 1 | 1 | 0 | | High | 2 | 2 | 0 | | Medium | 1 | 1 | 0 | | Low | 6 | 5 | 1 | | Informational | 9 | 8 | 1 | | Best Practices | 2 | 2 | 0 | | **Total** | **21** | **18** | **3** | **Acknowledged findings (no functional fix shipped):** | Finding | Severity | Why acknowledged | | ---------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Users can frontrun `reportValidatorLoss(...)` to evade slashing penalties | Info | Mitigated operationally via the per-report and per-day loss caps; routing all exits through the queue would degrade UX. | | Constructor does not enforce a non-zero seed at deployment | Low | Operational pre-deployment requirement; the deployment script seeds the vault. | | `redeemWithQueue` / `withdrawWithQueue` use all-or-nothing logic (no partial fill) | Info | Two-call pattern (`redeem(maxRedeem)` + `redeemWithQueue(rest)`) gives the same outcome; partial fill considered for a future revision. | **All Critical, High, and Medium findings are Fixed.** Highlights: * *Critical*: returned masternode stakes were double-counted in `trackedTotalAssets`; resolved by routing principal returns through `resignMasternode(...)` instead of the unprivileged `receive()` path. * *High*: receivers could trigger a gas-bomb in `_processWithdrawalQueueInternal(...)` to brick the queue; resolved by enforcing a strict gas limit on the external call. * *High*: permissionless `syncTrackedAssets()` during migration could let early migrators steal funded liquidity; resolved by gating `syncTrackedAssets` with `whenMigrationFinished`. * *Medium*: deferred queued payouts were not ring-fenced from the protocol's accounting; resolved by introducing a `totalDeferredPayouts` accumulator and excluding it from `_availableForImmediateWithdrawal`, `_availableForQueuePayout`, and `_syncTrackedAssetsExcludingInflow`. The full per-finding write-up, recommendations, and per-fix verification is in the [PDF report](https://github.com/PrimeNumbersLabs/primestaking-gitbook/tree/main/NM_0843_xdc_prime_stake_FINAL_updated_tests.pdf). *** ### V3.1 redeployment (July 2026) The live vault, [`PrimeStakedXDC_V3_2`](https://xdcscan.com/address/0xDc74c0DaED82ae94486DeeF22991d2F54173c734), is a redeployment of the NM-0843-audited V3 codebase with a scoped set of changes to support the staged masternode-collateral transition: an under-backed launch mode with NAV write-down protection, ring-fenced funding lanes for the withdrawal queue, and the one-time `V31AirdropDistributor` mint path used to mirror V3 balances. The V3 architecture, roles, time-locks, and withdrawal design are otherwise unchanged. **A follow-up external audit of the V3.1 delta is in progress and will be published on this page.** *** ### Other V3 stack components The XDC NFT V3 surface (`XdcStakedNFT`, `XdcNftStakingVault`, `XdcNftMigrator`, `XdcNftBoostHarvester`, `LegacyMigratorBypassFacet`) ships with an internal 46-test suite plus a 17-test audit-fix regression battery covering every C/H/M finding from the internal review. External audit of this surface is planned and any future report will be published on this page. *** **Note:** The core PRFI Token contract was fully audited. Although not part of this staking documentation, the report is publicly available. # Disclaimer ### Risk Disclosure & Disclaimer **Applies to:** PrimeStaking smart contracts, interfaces, and related documentation operated by **Prime Numbers Labs** (or its affiliates) ("PrimeStaking", "we", "us", "our"). > **Summary:** Using blockchain protocols is risky. **You can lose some or all of your assets.** Smart contracts may have bugs or be exploited. Network conditions, third-party services, markets, or protocol updates can change outcomes. **There are no guaranteed returns.** Proceed only if you understand and accept these risks. *** #### 1. No Warranties; As-Is PrimeStaking and all related smart contracts, interfaces, tokens (including psXDC), NFTs, rewards, and documentation are provided **"as is" and "as available"** without warranties of any kind. To the maximum extent permitted by law, we disclaim all warranties. #### 2. Smart Contract & Security Risks Interacting with smart contracts involves risks including bugs, design flaws, upgrade errors, dependency failures, and economic attacks. Even audited contracts do **not guarantee** absence of vulnerabilities. You may lose funds due to exploits or unexpected behavior. #### 3. Network & Validator Risks Rewards and redemptions depend on third-party networks (e.g., XDC Network). Network halts, forks, validator downtime, or congestion can reduce yields, delay queue-based withdrawal processing (subject to the network's `candidateWithdrawDelay`, approximately 35 days under typical block times, longer under congestion), or impair liquidity. #### 4. Derivative & Peg Risks psXDC v3 is an ERC-4626 vault share whose value tracks a vault exchange rate (`totalAssets / totalShares`), not a fixed 1:1 ratio with XDC. The share's market price on a DEX may trade below, at, or above its current NAV and may not be redeemable immediately when the protocol's liquid buffer is insufficient. #### 5. Smart Contract Custody Validator key management and staked assets are managed by on-chain smart contracts. While these contracts are audited, they may contain undiscovered vulnerabilities. We do not guarantee the absence of bugs or exploits in custody contracts. #### 6. Variable Rewards Any APY, multiplier, or reward figure is **illustrative only, subject to change, and not guaranteed**. Rewards can fluctuate to zero. Historical performance does not indicate future results. #### 7. User Responsibilities You are solely responsible for private keys, wallet security, address accuracy, transaction review, and understanding contract addresses. #### 8. Regulatory & Tax You are responsible for complying with applicable laws, including sanctions, AML/CTF, and tax reporting. Access may be restricted in certain jurisdictions. #### 9. No Investment Advice Nothing herein constitutes financial, investment, legal, or tax advice. #### 10. Limitation of Liability To the maximum extent permitted by law, we are not liable for any indirect, incidental, special, consequential, or punitive damages, or for lost profits, data, or assets. #### 11. Indemnity You agree to indemnify and hold harmless PrimeStaking and its contributors from claims arising from your use or violation of these terms. *** > **Binding by Use:** By connecting a wallet, interacting with our interfaces, staking XDC (including receiving psXDC or staking via NFTs), or otherwise using PrimeStaking, you acknowledge and accept this Risk Disclosure & Disclaimer. # Custody & Key Management PrimeStaking uses a **permissionless, smart contract-based** validator custody model - eliminating human interaction from custody flows entirely. *** ## How It Works * **Smart contract-based execution** - validator keys and staked XDC are managed entirely by audited smart contracts, with no human interaction in custody flows. * **Permissionless** - anyone can verify the state of validators and staked assets on-chain. No centralized approval required. * **Trustless** - no single entity controls the keys. The protocol enforces custody rules through code, not operational trust. * **Institutional-grade transparency** - full operational transparency aligned with institutional security standards. *** ## Audit & Collaboration PrimeStaking's custody infrastructure is developed in collaboration with: * Nethermind: smart contract development and security review * XDC Core team: network-level validator integration The custody substrate (the `PrimeStakedXDC_V3` vault design + `PrimeStakedXDC_V3MigrationBridge`) was independently audited by **Nethermind Security** in audit **NM-0843, XDC Prime Stake** (final report **May 08, 2026**). All Critical, High, and Medium findings are Fixed; the three Acknowledged findings are operationally mitigated. The live vault, `PrimeStakedXDC_V3_2`, is a redeployment of this audited codebase. See the [Audits page](/security/audits-1) for the V3.2 delta and per-finding breakdown, or [read the full report (PDF)](https://github.com/PrimeNumbersLabs/primestaking-gitbook/tree/main/NM_0843_xdc_prime_stake_FINAL_updated_tests.pdf). *** ## What This Means for Users | Property | Detail | | ------------------------ | ------------------------------------------------- | | **Custody model** | Smart contract-based (no third-party custodian) | | **Key management** | Validator keys secured by on-chain contracts | | **Human interaction** | Eliminated from custody flows | | **Verifiability** | Fully transparent and auditable on the blockchain | | **User action required** | None - fully seamless | *** ## Impact on Users * Users retain **full ownership** of their assets at all times. * Smart contract-based custody eliminates reliance on any centralized custodian, strengthening the protocol's decentralization. * In V3, **withdrawal UX has improved**: redemptions settle instantly when the vault's liquid buffer permits, and otherwise enter a permissionless FIFO queue users can [self-claim](/products/xdc-liquid-staking/staking-guide/withdrawals-instant-vs-queued) (`claimQueuedAssets`). The upper bound for queue settlement is the XDC Network's `candidateWithdrawDelay`, approximately **35 days** under typical block times. * The psXDC v3 vault is **non-upgradeable**, so the contract that holds your XDC cannot be modified by anyone. Only the NFT staking vault is upgradeable, and only through multisig + delayed governance. # Legacy Overview Reference material for users still on V2 contracts. Not recommended for new users; migrate to V3. The V2 stack remains operational so users who have not migrated can continue to use the product. Every new deposit, the official UI, and all partner integrations are wired against the **V3** contracts described in the main documentation. The pages in this section exist for historical context and to support users finishing their migration. {% hint style="warning" %} New users should always use V3. The V2 contracts described here do not implement self-service withdrawals, share-price reward accrual, or the boost accumulator, and are not part of the active reward roadmap. {% endhint %} *** ## Legacy contract addresses | Contract | Address | Role | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Legacy psXDC v2 (proxy) | [`0x9B8e12b0BAC165B86967E771d98B520Ec3F665A6`](https://xdcscan.com/address/0x9B8e12b0BAC165B86967E771d98B520Ec3F665A6) | V2 psXDC ERC-20 token. Use this address when approving the [V2 → V3 migration bridge](/products/xdc-liquid-staking/staking-guide/migration). | | Legacy Diamond (ERC-2535) | [`0x7a5d364b97126600C0AdDFD5C339230748bcaA17`](https://xdcscan.com/address/0x7a5d364b97126600C0AdDFD5C339230748bcaA17) | Hosts all legacy XDC NFT facets. Now also hosts [`LegacyMigratorBypassFacet`](/products/xdc-staking-nfts/locked-nft-migration) so locked NFTs can be migrated in one transaction. | | Legacy ERC-721 façade | [`0x9D458330e458f11fd1cE7E44B3a66568af8076a0`](https://xdcscan.com/address/0x9D458330e458f11fd1cE7E44B3a66568af8076a0) | The user-visible NFT contract behind V2 XDC NFTs. | *** ## How V2 still behaves | Surface | V2 behaviour | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Liquid staking deposit | Mints V2 psXDC at a fixed 1:1 ratio with XDC. | | Liquid staking rewards | Distributed via the legacy `notifyRewardAmount` flow; users manually claim from the legacy Rewards tab. | | Liquid staking withdrawal | Submitted as a request and processed via the validator queue under the legacy operational flow. | | XDC NFTs | Continue to function under the V2 reward model (monthly reward pool driven by NFT multipliers). | | Migration | Both psXDC v2 → V3.1 shares (via the [v2 → V3.1 bridge](/products/xdc-liquid-staking/staking-guide/migration)) and legacy NFTs → V3 NFTs are available; see the V3 documentation for current migration UX. | There is no plan to deprecate V2 forcibly, so users can take their time migrating. *** ## Pages in this section * [Historical: pstXDC → psXDC migration](/legacy-v2-historical/pstxdc-migration): the original migration from the **pstXDC** token to **psXDC** (V1 → V2). Closed out years ago; kept here for any historical user still on pstXDC. → [Migrate V2 psXDC → V3 (current)](/products/xdc-liquid-staking/staking-guide/migration) → [Migrate XDC NFTs to V3 (current)](/products/xdc-staking-nfts/migrate-nfts-v2-to-v3) # Historical: pstXDC → psXDC migration {% hint style="warning" %} This page describes the **historical** migration from the original **pstXDC** token to **psXDC** (V1 → V2). The migration completed long ago and is kept here for archival reference only. If you still hold pstXDC, contact . For the **current** migration from **V2 psXDC to V3 psXDC shares**, see [Migrate V2 psXDC → V3](/products/xdc-liquid-staking/staking-guide/migration). {% endhint %} If you hold the legacy **pstXDC** token, you can migrate it to the **psXDC** token. *** ### Steps 1. Go to the **Migration** section in the app. 2. Click **Migrate** and confirm the transaction. 3. Your pstXDC will be converted to psXDC at a 1:1 ratio.
{% hint style="info" %} Migration is only required for users who staked before the psXDC upgrade. New users receive psXDC directly. Once on psXDC, you can subsequently migrate to V3; see the [V2 → V3 migration guide](/products/xdc-liquid-staking/staking-guide/migration). {% endhint %}