V4 Upgrade Guide
This guide covers the key changes and upgrade steps for StakeWise Operator V4, including Pectra upgrade support.
Prerequisites
Ensure your Vault is updated to version 5 for Ethereum network or version 3 for Gnosis network for full Pectra compatibility. See Prerequisites → for details on checking and upgrading your Vault version.
Additionally, ensure your Operator Service wallet has the Validators Manager → role assigned in your Vault settings for proper operation.
Validator Changes
Registration
After the Pectra upgrade:
- Validator balances are no longer limited to 32 ETH or 1 GNO
0x02validators are registered by default- To register
0x01validators, add the flag--validators-type=0x01
Consolidations
To migrate 0x01 validators to 0x02, use the consolidate command. Read more about it here →.
When funding validators:
- Funds first top up existing
0x02validators up to 2048 ETH or 64 GNO before registering new validators - New validators are registered once the Vault accumulates another 32 ETH or 1 GNO
Note
Funding will be disabled when using 0x01 validator type.
Withdrawals
The Pectra upgrade introduces significantly improved withdrawal mechanisms:
Partial Withdrawals (New!)
- Supported for
0x02validators only, enabling withdrawal of excess balance without exiting the validator - Automated execution every 12 hours by default (configurable via
WITHDRAWALS_INTERVALenvironment variable) - Triggers partial withdrawals for validators with balances exceeding 32 ETH or 1 GNO, prioritizing those with higher balances first
- Significantly faster than full validator exits, improving withdrawal queue processing times
More Efficient Full Validator Exits
- Full validator exits are now processed via execution request calls instead of the traditional oracle-based method
- Automatic fallback: If the Operator Service does not initiate partial or full withdrawals, the Oracle network will automatically execute a full withdrawal after 24 hours using the exit signatures they have received during validator registration
Withdrawal Logic & Prioritization
When processing withdrawal requests:
- First Priority: Partial withdrawals from
0x02validators with excess balance (>32 ETH/1 GNO) - Second Priority: Full validator exits if partial withdrawal capacity is insufficient
- Fallback: Oracle-triggered full exits after 24 hours if operator is inactive
Configuration Options
- Disable partial withdrawals: Use
--disable-withdrawalsflag to process all withdrawals via full validator exits using oracles - Adjust frequency: Set
WITHDRAWALS_INTERVALenvironment variable to change the default 12-hour interval - Minimum thresholds: Partial withdrawals only occur when validator balance exceeds 32 ETH or 1 GNO
Important for 0x01 Validators
Partial withdrawals are not supported for 0x01 validators. These will always require full validator exits for withdrawals.
Simplified Start Commands
The launch process has been simplified by separating setup flows into dedicated commands:
- Default Mode
- Remote Signer
- Hashi Vault
- Relayer
# No changes needed for default mode
start-remote-signer
start-hashi-vault
start-relayer
Reference
For detailed information about start commands, see Start Operator Service →.
No More Deposit Data File
V4 Operator no longer requires pre-uploaded deposit data for validator registration — it generates deposit data automatically during registration.
Important
To support this new flow, you must assign your operator wallet as the Validators Manager in the Vault settings.
🔗 Setup Guide: How to Set Up Validators Manager →.
Automated Rewards Withdrawals
It is now possible to periodically withdraw rewards for the Vault's fee shareholders.
Deep Dive
For detailed instructions on fee claiming, see Fee Claiming →.
Parameter Changes
Updated Parameters
| Old Parameter | New Parameter | Notes |
|---|---|---|
HOT_WALLET_FILE | WALLET_FILE | Environment variable renamed |
HOT_WALLET_PASSWORD_FILE | WALLET_PASSWORD_FILE | Environment variable renamed |
Removed Parameters
- ❌
--deposit-data-file- No longer needed (automatic generation)