Staking Contract Guide
The Staking Contract Guide explains how developers can interact directly with GenLayer staking smart contracts for consensus-level staking operations. It includes Solidity code examples for both validator and delegator operations. The examples use genStaking for the Staking contract on GenLayer Chain and validatorWallet for a validator's ValidatorWallet contract.
To understand the concepts behind staking, including the epoch system, shares vs stake, validator selection weights, and reward distribution, see Staking in GenLayer.
For CLI-based staking operations (recommended for most users), see the GenLayer CLI Staking Commands. The CLI and genlayer-js also build the operator key proof that joining requires.
Stake is denominated in GEN, the native token of GenLayer Chain, so staking calls send GEN as msg.value. The minimums, unbonding periods, and epoch durations below are current defaults that governance can change. Read the minimums from the Staking contract with validatorMinStake() and delegatorMinStake() instead of hardcoding them.
Validator Operations
Joining as a Validator
Requirements:
- Minimum stake: 42,000 GEN tokens
- Must run a validator node for consensus participation
- An operator key whose possession you can prove
- A single address can create multiple validators
The caller becomes the validator owner. The operator is derived from the public key you register, and the possession proof shows that you control that key:
uint256[2] memory operatorPubKey = [pubKeyX, pubKeyY]; // operator public key
bytes memory possessionProof = ...; // signature by the operator key over its possession message
address validatorWallet = genStaking.validatorJoin{value: 42000 ether}(
operatorPubKey,
possessionProof
);Use your own key to operate the node yourself, or a separate hot key for cold/hot separation (recommended). The possession message is bound to the wallet factory and the caller; generate the key and proof with the GenLayer CLI (genlayer staking validator-join or the wizard) or with validatorJoin({ amount, registration }) in genlayer-js.
Save the returned ValidatorWallet address - you'll need it for all future operations.
Important Notes:
- Deposits activate 2 epochs after joining
validatorPrime()is automatically called by your validator node each epoch- Monitor priming for proper activation within 2 epochs
- The operator must be a nonzero address. If you register a separate hot key, it must be unused by any validator wallet, including your own. If you register the caller's own key, that address can operate multiple wallets.
- To rotate the operator later, the owner calls
initiateOperatorTransferon the ValidatorWallet. After the operator-transfer delay, the owner or the pending operator callscompleteOperatorTransfer. Only the owner can callcancelOperatorTransfer.
Post-Join Steps:
- Save the
validatorWalletaddress - Start your validator node using the operator key
- Monitor that
validatorPrime(validatorWallet)executes each epoch - Wait 2 epochs and verify activation
Depositing as a Validator
validatorWallet.validatorDeposit{value: 10000 ether}();Key Points:
- Call through the ValidatorWallet contract only; only the wallet owner can call it
- Deposits follow the epoch +2 activation rule
- Your validator node automatically calls
validatorPrime()to commit the deposit - No minimum for additional deposits
- Cannot deposit zero value
- Deposits revert while a slash against the validator is being settled
Activation Timeline:
Epoch N: validatorDeposit() called
Epoch N+1: validatorPrime() → deposit staged
Epoch N+2: validatorPrime() → deposit activatedWithdrawing as a Validator
Step 1: Calculate Shares
uint256 currentShares = genStaking.validatorSelfSharesOf(validatorWallet);
uint256 sharesToExit = (currentShares * 30) / 100; // Exit 30%genStaking.validatorView(validatorWallet) returns a ValidatorView struct with the validator's stake (vStake, dStake), pool shares (vShares, dShares), pending operations, and ban and priming state.
Step 2: Initiate Exit
validatorWallet.validatorExit(sharesToExit);You must specify shares, not token amounts. Cannot exit more shares than owned.
Important Notes:
- After epoch 0, an exit immediately removes the shares from the owner's available balance and queues the withdrawal. When priming processes that withdrawal, it prices the shares and updates active stake and selection weight.
- The withdrawal still receives its share of rewards for the epochs it served and remains exposed to slashing for those epochs.
- Tokens are locked for 7 epochs before claiming
- Each exit creates a separate withdrawal
Unbonding Timeline:
Epoch 10: validatorExit() called → unbonding starts
Epochs 11-16: Locked period
Epoch 17: earliest validatorClaim()Claiming Withdrawn Funds as a Validator
The owner claims through the ValidatorWallet, which collects the matured withdrawals and forwards them to the owner:
validatorWallet.validatorClaim();Important Notes:
- Must wait 7 full epochs after calling
validatorExit() - Staking pays only withdrawals that have matured, have been priced, and have cleared the slash-settlement window. If none qualify, the Staking call returns zero.
- If a slash is actively being processed for the validator, the claim reverts with
ValidatorSlashInProgress. Retry after priming finishes processing the slash. - Multiple exits can be claimed in a single call
genStaking.validatorClaim(validatorWallet)is permissionless, but it pays the ValidatorWallet, not the owner; the owner still callsvalidatorWallet.validatorClaim()to receive the funds
Checking Claim Availability:
uint256 exitEpoch = 10;
uint256 claimableAtEpoch = exitEpoch + 7; // current default unbonding period
if (genStaking.epoch() >= claimableAtEpoch) {
validatorWallet.validatorClaim();
}Delegator Operations
In these Solidity examples, the contract calling genStaking owns the delegation. It uses address(this) to look up its shares and claim its GEN. Give it a payable receive() function so it can accept the payout. If you delegated directly from a wallet, submit the claim from that wallet and pass its address as the delegator.
Joining as a Delegator
Requirements:
- Minimum delegation: 42 GEN per validator (your total delegation to that validator)
- Target validator must be a registered validator; otherwise the call reverts with
ValidatorNotActive - Can delegate to multiple validators
Basic Delegation:
address validatorWallet = 0x...;
genStaking.delegatorJoin{value: 1000 ether}(validatorWallet);Multi-Validator Delegation:
genStaking.delegatorJoin{value: 500 ether}(validator1);
genStaking.delegatorJoin{value: 500 ether}(validator2);
genStaking.delegatorJoin{value: 500 ether}(validator3);Important Notes:
- Follows the epoch +2 activation rule
- The validator's node automatically calls
validatorPrime()to commit your delegation - Delegating to a validator that is below its own minimum stake is allowed, but that validator is not selected until it meets the minimum
- Choose validators with good uptime
- Smaller validators often provide higher returns
- Cannot delegate zero value
Delegation Strategy Tips:
- Diversify across multiple validators
- Check validator performance and uptime
- Monitor validator quarantine/ban status
Depositing as a Delegator
To add to an existing delegation, call delegatorJoin() again for the same validator:
genStaking.delegatorJoin{value: 500 ether}(validatorWallet);Important Notes:
- Follows the epoch +2 activation rule
- The validator's node automatically calls
validatorPrime() - Any non-zero top-up is accepted as long as your total delegation to that validator meets the minimum
- Rewards automatically compound
Withdrawing as a Delegator
Step 1: Calculate Shares
The v0.6 IGenLayerStaking interface returns a Shares value. Import Shares from the consensus contracts' contracts/types/Quantities.sol and unwrap it before doing arithmetic.
uint256 currentShares = Shares.unwrap(genStaking.sharesOf(address(this), validatorWallet));
uint256 sharesToExit = (currentShares * 50) / 100; // Exit 50%Step 2: Initiate Exit
genStaking.delegatorExit(validatorWallet, sharesToExit);You must specify shares, not token amounts.
Important Notes:
- Can exit partial amounts, but a partial exit cannot leave the delegation below the minimum; exit all shares instead
- After epoch 0, an exit immediately removes the shares from your available balance. When priming processes the withdrawal, it prices the shares and updates the validator's active delegated stake and selection weight.
- Tokens are locked for 7 epochs
- Exit each validator separately if delegating to multiple
Unbonding Timeline:
Epoch 5: delegatorExit() called
Epochs 6-11: Locked period
Epoch 12: earliest delegatorClaim()Claiming Withdrawn Funds as a Delegator
uint256 tokensReceived = genStaking.delegatorClaim(address(this), validatorWallet);Important Notes:
- Must wait 7 full epochs after calling
delegatorExit() - Only the delegator can claim; calls from any other address revert with
UnauthorizedDelegatorClaim - Tokens are sent to the delegator's address
- A withdrawal is claimable only after it has been priced and any slashing for the epochs it served has been settled
- Claim from each validator separately if delegated to multiple
Multi-Validator Claim Example:
genStaking.delegatorClaim(address(this), validator1);
genStaking.delegatorClaim(address(this), validator2);
genStaking.delegatorClaim(address(this), validator3);Genesis Epoch 0
Epoch 0 is the genesis bootstrapping period with special rules designed to facilitate network launch. The normal staking rules are relaxed to allow rapid network bootstrapping.
What is Epoch 0?
Epoch 0 is the bootstrapping period before the network becomes operational. During epoch 0:
- No transactions are processed - the network accepts Intelligent Contract transactions only from epoch 2
- No consensus occurs - validators are not yet participating
- Stakes are registered and prepared for activation in epoch 2
- The epoch lasts at least its configured minimum duration (14 days by default; later epochs last at least 1 day)
Important: When epoch 0 ends, the network normally moves directly to epoch 2 (epoch 1 is skipped). The skip requires the inflation for epoch 2 to have been delivered from Ethereum; otherwise the network waits in epoch 1 until it arrives. Validators and delegators who stake in epoch 0 become active in epoch 2.
Special Rules for Epoch 0
| Rule | Normal Epochs (2+) | Epoch 0 |
|---|---|---|
| Validator minimum stake | 42,000 GEN | No minimum to join |
| Delegator minimum stake | 42 GEN | No minimum |
| Activation delay | +2 epochs | Active in epoch 2 |
| validatorPrime required | Yes, each epoch | Not required |
| Share calculation | Based on existing ratio | 1:1 (shares = input) |
| Transaction processing | Yes | No (bootstrapping only) |
Validator activation requires the validator minimum: While validators can join with any amount during epoch 0, a validator is only eligible in epoch 2 if its own stake meets the validator minimum (42,000 GEN). Validators below it remain registered but inactive. Epoch 0 delegations of any amount are recorded and priced immediately; whether they earn depends on the validator they back being eligible.
Validators in Epoch 0
Joining:
// In epoch 0, any non-zero amount is accepted (no 42,000 GEN minimum)
address validatorWallet = genStaking.validatorJoin{value: 1000 ether}(
operatorPubKey,
possessionProof
);
// Stake is registered for activation in epoch 2
// No need to call validatorPrime() in epoch 0Key behaviors:
- No minimum stake: Validators can join with any non-zero amount
- Registered for epoch 2: Stakes are recorded and will become active when epoch 2 begins
- No priming required:
validatorPrime()is not needed during epoch 0 - No consensus participation: Validators do not process transactions in epoch 0
Do validators need to take any action in epoch 0 to be active in epoch 2?
No. Validators who join in epoch 0:
- Have their stake registered during epoch 0
- Become active automatically in epoch 2 only if they have at least 42,000 GEN staked
- Must start calling
validatorPrime()in epoch 2 for continued participation in epoch 4+
Critical: Validators who joined in epoch 0 with less than 42,000 GEN will not be active in epoch 2. They must deposit additional funds to meet the minimum requirement before epoch 2 begins.
Delegators in Epoch 0
Joining:
// In epoch 0, any non-zero amount is accepted (no 42 GEN minimum)
genStaking.delegatorJoin{value: 10 ether}(validatorWallet);
// Delegation is registered for activation in epoch 2Key behaviors:
- No minimum delegation: Any non-zero amount accepted
- Recorded immediately: The delegation is recorded and priced in the validator's pool when you join, and is not rechecked against the 42 GEN minimum when epoch 2 begins. It takes part from epoch 2 if its validator is eligible
- No rewards in epoch 0: Since no transactions are processed, no rewards are earned during epoch 0
Is a delegation made in epoch 0 active in epoch 2?
Yes. Delegations made in epoch 0 become active in epoch 2. Unlike normal epochs where you wait +2 epochs, epoch 0 delegations activate as soon as the network becomes operational.
Activation Timeline Comparison
Normal Epochs (2+):
Epoch N: validatorJoin() or delegatorJoin() called
Epoch N+1: validatorPrime() stages the deposit
Epoch N+2: validatorPrime() activates the deposit → NOW ACTIVEEpoch 0 (Bootstrapping):
Epoch 0: validatorJoin() or delegatorJoin() called → stake registered (not yet active)
No transactions processed, no consensus
Epoch 2: Validators meeting the validator minimum and their delegations become active, network operational, validatorPrime() requiredShare Calculation in Epoch 0
In epoch 0, shares are calculated at a 1:1 ratio with the input amount:
// Epoch 0: 1,000 GEN deposit = 1,000 shares (1:1 ratio)
genStaking.delegatorJoin{value: 1000 ether}(validatorWallet);
// Result: delegator receives exactly 1,000 shares
// Normal epochs: shares depend on pool ratio
// new_shares = deposit_amount × (total_shares / total_stake)This is because there's no existing stake pool to calculate a ratio against. Starting from epoch 2, shares are calculated based on the current stake-to-share ratio.
Transitioning from Epoch 0 to Epoch 2
When the network advances from epoch 0 to epoch 2:
- Epoch 0 validators that meet the validator minimum (42,000 GEN) become active, together with the delegations to them. Epoch 0 delegations are not rechecked against the 42 GEN minimum
- Normal minimum requirements apply for new joins/deposits, including the 42 GEN delegator minimum
- +2 epoch activation delay applies to all new deposits
- validatorPrime() becomes mandatory for validators to remain in the selection pool
- Existing validators must ensure their nodes begin calling
validatorPrime()in epoch 2
FAQ: Epoch 0 Special Cases
Q: Can I join as a validator with less than 42,000 GEN in epoch 0? A: Yes, any non-zero amount is accepted during epoch 0. However, you will not be active in epoch 2 unless you have at least 42,000 GEN staked by then.
Q: If I delegate in epoch 0, when does it become active? A: In epoch 2. Unlike normal epochs with a +2 delay, epoch 0 delegations activate when the network becomes operational.
Q: Do I need to call validatorPrime() in epoch 0? A: No. Priming is not required during epoch 0. Your node should start calling it automatically when epoch 2 begins.
Q: Will my epoch 0 stake still be active after epoch 0 ends? A: Yes, if you meet the minimum requirements. Stakes from epoch 0 carry forward and remain active in all subsequent epochs.
Q: What happens to my stake if I joined in epoch 0 but my node doesn't call validatorPrime() in epoch 2? A: You'll be excluded from validator selection in epoch 4, but your stake remains. Once priming resumes, you'll be eligible for selection again.
Common Scenarios
Scenario 1: Becoming a Validator
address validatorWallet = genStaking.validatorJoin{value: 42000 ether}(
operatorPubKey,
possessionProof
);
// Start validator node with the operator key
// Monitor: Epoch N joined, N+1 staged, N+2 activeScenario 2: Delegating to Multiple Validators
genStaking.delegatorJoin{value: 1000 ether}(validator1);
genStaking.delegatorJoin{value: 2000 ether}(validator2);
genStaking.delegatorJoin{value: 1500 ether}(validator3);
// Later, exit from one validator
uint256 shares = Shares.unwrap(genStaking.sharesOf(address(this), validator1));
genStaking.delegatorExit(validator1, shares);
// Once the withdrawal is claimable:
genStaking.delegatorClaim(address(this), validator1);Scenario 3: Partial Validator Exit
uint256 currentShares = genStaking.validatorSelfSharesOf(validatorWallet);
uint256 sharesToExit = (currentShares * 25) / 100; // Exit 25%
validatorWallet.validatorExit(sharesToExit);
// After 7 epochs:
validatorWallet.validatorClaim();Best Practices
For Validators
- Ensure node health: Your validator node automatically calls
validatorPrime() - Use separate keys: Cold wallet for owner, hot key for operator
- Monitor priming: Verify deposit activation occurs as expected
- Monitor quarantine status: Check if your validator is quarantined
- Maintain high uptime: Downtime leads to idleness strikes
- Set up backup monitoring: Alert if priming fails
For Delegators
- Diversify: Spread stake across multiple validators
- Select carefully: Choose validators with good uptime records
- Verify priming: Ensure validators are consistently primed
- Consider smaller validators: They often provide higher returns
- Monitor health: Regularly check validator status
- Use shares for exits: Calculate percentages, not absolute amounts
For Both
- Account for unbonding: Plan for the 7-epoch wait when exiting
- Monitor epochs: Track current epoch for claim eligibility
- Calculate exits carefully: Always use share percentages
- Understand compounding: Rewards automatically increase stake-per-share
- Watch governance: Parameter changes can affect staking dynamics
Troubleshooting
| Error | Cause | Solution |
|---|---|---|
ValidatorBelowMinimumStake | Stake below 42,000 GEN | Deposit at least 42,000 GEN when joining |
InvalidOperatorAddress | Zero operator, or deposit not sent from a factory ValidatorWallet | Register a valid operator key; deposit through validatorWallet.validatorDeposit() |
ValidatorNotJoined | Deposit from a factory ValidatorWallet that never joined | Join with validatorJoin() first |
ValidatorNotActive | Delegation to an address that is not a registered validator | Check the ValidatorWallet address |
OperatorAlreadyAssigned | The separate hot key already operates a validator wallet | Use an unused hot key, or register the caller's own key for self-operation |
ValidatorMayNotDepositZeroValue | Zero deposit amount | Deposit a non-zero amount |
ValidatorSlashInProgress | A deposit, exit or claim reverted during an active slash | Retry after priming finishes processing the slash |
ValidatorExitExceedsShares | Exiting more shares than owned | Check shares with validatorSelfSharesOf() |
DelegatorExitWouldBeBelowMinimum | Partial exit would leave less than the minimum delegation | Exit all shares or keep at least the minimum |
UnauthorizedDelegatorClaim | Claim sent by an address other than the delegator | Send delegatorClaim() from the delegator's address |
| Validator not selected | Node not priming | Ensure node runs and calls validatorPrime() |
| Stake not activating | Priming not occurring | Monitor node for automatic validatorPrime() calls |
| Claim returns 0 | Unbonding not complete, withdrawal not yet priced, or slashing not yet settled | Verify the unbonding period has passed with genStaking.epoch() and that the validator has been primed |
| Delegation not earning | Validator issues | Check if validator is quarantined/banned; consider switching |
Related Resources
- Staking Concepts - How staking works in GenLayer
- Unstaking - Unstaking process details
- Slashing - Slashing penalties and conditions
- GenLayer CLI Staking Commands - CLI reference for staking
- genlayer-js staking methods - SDK reference for staking