CoreVault contract

Purpose

CoreVault is Magma’s pooled staking engine. It distributes deposits across the active validator set, manages undelegations to satisfy redemptions, and performs periodic rebalancing to keep validator weights aligned.

How it works

• Pooled delegation: Incoming deposits are distributed across validators, favoring the least‑staked first and applying per‑step throttles to avoid over‑concentration.

• Withdrawal orchestration: For user redemptions, CoreVault creates undelegations across validators with a per‑validator cap (≈5% of total active stake) to minimize disruption. Withdrawals are completed later once they mature.

• Two‑phase rebalancing:

  • Phase 1 (initiate): Undelegate excess from over‑target validators.

  • Phase 2 (redistribute): Complete matured withdrawals, then re‑delegate to under‑target validators.

• Epoch guard: Prevents initiating another rebalance too soon; ensures operations respect timing.

• Rewards handling: Claims rewards across validators, applies the rewards fee, and compounds back into stake.

Key features

• Deposit distribution:

  • Targets the lowest‑staked validators first.

  • Applies a per‑validator throttle (up to ~1/20 of total active stake at a time) for balanced growth.

• User undelegations (for redemptions):

  • Splits undelegations across highest‑stake validators first.

  • Caps per‑validator pulls to ~5% of the total active stake to avoid large single‑validator drains.

  • Tracks pending undelegations and completes them when matured; applies the withdrawal fee on completion.

• Admin rebalancing:

  • Initiation computes a target stake per validator from cached data and undelegates only the excess.

  • Redistribution completes admin withdrawals and re‑stakes to under‑target validators.

  • Uses a reserved “admin withdrawal ID” to avoid colliding with user withdrawal IDs. Please notice the following: "For each (validator, delegator) tuple, there can be a maximum of 256 in-flight withdrawal requests". https://docs.monad.xyz/developer-essentials/staking/staking-precompile#undelegate.

• Validator lifecycle:

  • Add validator(s) (with batch size guard).

  • Pause/remove a validator via a multi‑step flow (initiate → undelegate → complete withdrawal).

  • Disallows removal if it would leave too few validators.

Fees and parameters

• rewardsFee (bps): Taken from claimed rewards before compounding.

• withdrawalFee (bps): Taken upon completing user withdrawals.

• feeReceiver: Recipient of both fees.

• Epoch timing: A configurable epoch interval gates rebalances.

• mevRewardsInjector: Authorized source of additional rewards to compound.

Compatibility

• Executes delegations, undelegations, withdrawals, and reward claims via Monad’s staking precompile; end‑to‑end behavior follows Monad’s epoch‑based lifecycle. See Monad Staking.