diff --git a/pages/_meta.json b/pages/_meta.json index ec4c2a1bc..9d1fd0d75 100644 --- a/pages/_meta.json +++ b/pages/_meta.json @@ -3,8 +3,8 @@ "understand-genlayer-protocol": "Discover the Protocol", "developers": "Build on GenLayer", "validators": "Run a Validator", - "partners": "Partners", "api-references": "API References", + "partners": "Partners", "FAQ": "FAQ", "blog": { "title": "Blog 📚", diff --git a/pages/developers/_meta.json b/pages/developers/_meta.json index 73e494523..00af89038 100644 --- a/pages/developers/_meta.json +++ b/pages/developers/_meta.json @@ -1,4 +1,5 @@ { "intelligent-contracts": "Intelligent Contracts", - "decentralized-applications": "Decentralized Applications" + "decentralized-applications": "Decentralized Applications", + "staking-guide": "Staking Contract Guide" } diff --git a/pages/developers/staking-guide.mdx b/pages/developers/staking-guide.mdx new file mode 100644 index 000000000..7383345ad --- /dev/null +++ b/pages/developers/staking-guide.mdx @@ -0,0 +1,469 @@ +import { Callout } from "nextra-theme-docs"; + +# Staking Contract Guide + +This guide covers consensus-level staking operations for developers who want to interact directly with the GenLayer staking smart contracts. It includes Solidity code examples for both validator and delegator operations. + +To understand the concepts behind staking—including the epoch system, shares vs stake, validator selection weights, and reward distribution—see [Staking in GenLayer](/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking). + + + For CLI-based staking operations (recommended for most users), see the [GenLayer CLI Staking Commands](/api-references/genlayer-cli#staking-operations-testnet). + + +## Validator Operations + +### Joining as a Validator + +**Requirements:** +- Minimum stake: **42,000 GEN** tokens +- Must run a validator node for consensus participation +- A single address can create multiple validators + +**Method 1: Owner as Operator** + +```solidity +address validatorWallet = genStaking.validatorJoin{value: 42000 ether}(); +``` + +**Method 2: Separate Operator Address (Recommended)** + +```solidity +address operatorAddress = 0x...; +address validatorWallet = genStaking.validatorJoin{value: 42000 ether}(operatorAddress); +``` + + + 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 +- Operator address cannot be reused or be the zero address +- If the operator is already assigned to another validator, the transaction reverts + +**Post-Join Steps:** +1. Save the `validatorWallet` address +2. Start your validator node using the operator address +3. Monitor that `validatorPrime(validatorWallet)` executes each epoch +4. Wait 2 epochs and verify activation + +### Depositing as a Validator + +```solidity +validatorWallet.validatorDeposit{value: 10000 ether}(); +``` + +**Key Points:** +- Call through the ValidatorWallet contract only +- 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 + +**Activation Timeline:** +``` +Epoch N: validatorDeposit() called +Epoch N+1: validatorPrime() → deposit staged +Epoch N+2: validatorPrime() → deposit activated +``` + +### Withdrawing as a Validator + +**Step 1: Calculate Shares** + +```solidity +uint256[8] memory validatorState = genStaking.validatorView(validatorWallet); +uint256 currentShares = validatorState[1]; +uint256 currentStake = validatorState[0]; +uint256 sharesToExit = (currentShares * 30) / 100; // Exit 30% +``` + +**Step 2: Initiate Exit** + +```solidity +validatorWallet.validatorExit(sharesToExit); +``` + + + You must specify **shares**, not token amounts. Cannot exit more shares than owned. + + +**Important Notes:** +- Exited tokens stop earning rewards immediately +- 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: validatorClaim() available +``` + +### Claiming Withdrawn Funds as a Validator + +```solidity +uint256 tokensReceived = genStaking.validatorClaim(validatorWallet); +``` + +**Important Notes:** +- Must wait **7 full epochs** after calling `validatorExit()` +- Claims are permissionless - anyone can trigger them +- Tokens are sent to the validator wallet's owner address +- Multiple exits can be claimed in a single call +- Returns the total GEN received + +**Checking Claim Availability:** + +```solidity +uint256 exitEpoch = 10; +uint256 claimableAtEpoch = exitEpoch + 7; +uint256 currentEpoch = genStaking.epoch(); +if (currentEpoch >= claimableAtEpoch) { + genStaking.validatorClaim(validatorWallet); +} +``` + +--- + +## Delegator Operations + +### Joining as a Delegator + +**Requirements:** +- Minimum delegation: **42 GEN** per validator +- Target validator must exist and be active +- Can delegate to multiple validators + +**Basic Delegation:** + +```solidity +address validatorWallet = 0x...; +genStaking.delegatorJoin{value: 1000 ether}(validatorWallet); +``` + +**Multi-Validator Delegation:** + +```solidity +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 +- 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 + +```solidity +genStaking.delegatorDeposit{value: 500 ether}(validatorWallet); +``` + +**Important Notes:** +- Use `delegatorDeposit()` to add to existing delegations +- Follows the **epoch +2 activation rule** +- The validator's node automatically calls `validatorPrime()` +- No minimum for additional deposits +- Rewards automatically compound + +### Withdrawing as a Delegator + +**Step 1: Calculate Shares** + +```solidity +uint256 currentShares = genStaking.sharesOf(msg.sender, validatorWallet); +uint256 sharesToExit = (currentShares * 50) / 100; // Exit 50% +``` + +**Step 2: Initiate Exit** + +```solidity +genStaking.delegatorExit(validatorWallet, sharesToExit); +``` + + + You must specify **shares**, not token amounts. + + +**Important Notes:** +- Can exit partial amounts +- Stop earning rewards immediately after exit +- 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: delegatorClaim() available +``` + +### Claiming Withdrawn Funds as a Delegator + +```solidity +uint256 tokensReceived = genStaking.delegatorClaim( + delegatorAddress, + validatorWallet +); +``` + +**Important Notes:** +- Must wait **7 full epochs** after calling `delegatorExit()` +- Claims are permissionless - anyone can trigger them +- Tokens are sent to the delegator's address +- Claim from each validator separately if delegated to multiple + +**Multi-Validator Claim Example:** + +```solidity +genStaking.delegatorClaim(msg.sender, validator1); +genStaking.delegatorClaim(msg.sender, validator2); +genStaking.delegatorClaim(msg.sender, 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 is not yet active +- **No consensus occurs** - validators are not yet participating +- Stakes are registered and prepared for activation in epoch 2 + +**Important**: The network transitions directly from epoch 0 to epoch 2 (epoch 1 is skipped). 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 to join | +| 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) | + + + **Activation requires meeting minimums**: While you can join with any amount during epoch 0, your stake will only be **activated in epoch 2** if it meets the minimum requirements (42,000 GEN for validators, 42 GEN for delegators). Stakes below the minimum remain registered but inactive. + + +### Validators in Epoch 0 + +**Joining:** + +```solidity +// In epoch 0, any amount is accepted (no 42,000 GEN minimum) +address validatorWallet = genStaking.validatorJoin{value: 1000 ether}(operatorAddress); + +// Stake is registered for activation in epoch 2 +// No need to call validatorPrime() in epoch 0 +``` + +**Key behaviors:** + +1. **No minimum stake**: Validators can join with any non-zero amount +2. **Registered for epoch 2**: Stakes are recorded and will become active when epoch 2 begins +3. **No priming required**: `validatorPrime()` is not needed during epoch 0 +4. **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 (epoch 1 is skipped) **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:** + +```solidity +// In epoch 0, any amount is accepted (no 42 GEN minimum) +genStaking.delegatorJoin{value: 10 ether}(validatorWallet); + +// Delegation is registered for activation in epoch 2 +``` + +**Key behaviors:** + +1. **No minimum delegation**: Any non-zero amount accepted +2. **Registered for epoch 2**: Delegation is recorded and will become active when epoch 2 begins +3. **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 (epoch 1 is skipped). 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 ACTIVE +``` + +**Epoch 0 (Bootstrapping):** + +``` +Epoch 0: validatorJoin() or delegatorJoin() called → stake registered (not yet active) + No transactions processed, no consensus +Epoch 2: Stakes become active (if minimum met), network operational, validatorPrime() required +``` + +### Share Calculation in Epoch 0 + +In epoch 0, shares are calculated at a 1:1 ratio with the input amount: + +```solidity +// 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 1 is skipped): + +1. **Epoch 0 stakes that meet minimums become active** - validators need 42,000 GEN, delegators need 42 GEN +2. **Normal minimum requirements apply** for new joins/deposits +3. **+2 epoch activation delay** applies to all new deposits +4. **validatorPrime() becomes mandatory** for validators to remain in the selection pool +5. **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 (epoch 1 is skipped). + +**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 + +```solidity +address validatorWallet = genStaking.validatorJoin{value: 42000 ether}(operatorAddress); +// Start validator node with operator address +// Monitor: Epoch N joined, N+1 staged, N+2 active +``` + +### Scenario 2: Delegating to Multiple Validators + +```solidity +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 = genStaking.sharesOf(msg.sender, validator1); +genStaking.delegatorExit(validator1, shares); + +// After 7 epochs: +genStaking.delegatorClaim(msg.sender, validator1); +``` + +### Scenario 3: Partial Validator Exit + +```solidity +uint256[8] memory state = genStaking.validatorView(validatorWallet); +uint256 currentShares = state[1]; +uint256 sharesToExit = (currentShares * 25) / 100; // Exit 25% +validatorWallet.validatorExit(sharesToExit); + +// After 7 epochs: +genStaking.validatorClaim(validatorWallet); +``` + +--- + +## Best Practices + +### For Validators + +1. **Ensure node health**: Your validator node automatically calls `validatorPrime()` +2. **Use separate keys**: Cold wallet for owner, hot wallet for operator +3. **Monitor priming**: Verify deposit activation occurs as expected +4. **Monitor quarantine status**: Check if your validator is quarantined +5. **Maintain high uptime**: Downtime leads to idleness strikes +6. **Set up backup monitoring**: Alert if priming fails + +### For Delegators + +1. **Diversify**: Spread stake across multiple validators +2. **Select carefully**: Choose validators with good uptime records +3. **Verify priming**: Ensure validators are consistently primed +4. **Consider smaller validators**: They often provide higher returns +5. **Monitor health**: Regularly check validator status +6. **Use shares for exits**: Calculate percentages, not absolute amounts + +### For Both + +1. **Account for unbonding**: Plan for the 7-epoch wait when exiting +2. **Monitor epochs**: Track current epoch for claim eligibility +3. **Calculate exits carefully**: Always use share percentages +4. **Understand compounding**: Rewards automatically increase stake-per-share +5. **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 | +| `OperatorAlreadyAssigned` | Operator address in use | Choose a different operator address | +| `ValidatorMayNotDepositZeroValue` | Zero deposit amount | Deposit a non-zero amount | +| `ValidatorExitExceedsShares` | Exiting more shares than owned | Check shares with `validatorView()` | +| Validator not selected | Node not priming | Ensure node runs and calls `validatorPrime()` | +| Stake not activating | Priming not occurring | Monitor node for automatic `validatorPrime()` calls | +| Cannot claim withdrawn funds | Unbonding not complete | Verify 7 epochs have passed with `genStaking.epoch()` | +| Delegation not earning | Validator issues | Check if validator is quarantined/banned; consider switching | + +--- + +## Related Resources + +- [Staking Concepts](/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking) - How staking works in GenLayer +- [Unstaking](/understand-genlayer-protocol/core-concepts/optimistic-democracy/unstaking) - Unstaking process details +- [Slashing](/understand-genlayer-protocol/core-concepts/optimistic-democracy/slashing) - Slashing penalties and conditions +- [GenLayer CLI Staking Commands](/api-references/genlayer-cli#staking-operations-testnet) - CLI reference for staking diff --git a/pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking.mdx b/pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking.mdx index d596b5add..f46491339 100644 --- a/pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking.mdx +++ b/pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking.mdx @@ -2,18 +2,279 @@ Participants, known as validators, commit a specified amount of tokens to the network by locking them up on the rollup layer. This commitment supports the network's consensus mechanism and enables validators to actively participate in processing transactions and managing the network. +## Validators vs Delegators + +| Role | Minimum Stake | Infrastructure | Rewards | +|------|--------------|----------------|---------| +| **Validator** | 42,000 GEN | Must run a node | 10% operational fee + stake rewards | +| **Delegator** | 42 GEN | None required | Passive stake rewards | + +**Validators** run the consensus infrastructure and are responsible for executing intelligent contracts and validating transactions. They receive a 10% operational fee from rewards before distribution. + +**Delegators** stake their tokens with validators without running infrastructure. They earn passive rewards proportional to their stake, minus the validator's operational fee. + ## How Staking Works - **Stake Deposit**: To become a validator on GenLayer, participants must deposit GEN tokens on the rollup layer. This deposit acts as a security bond and qualifies them to join the pool of active validators. -- **Validator Participation**: Only a certain number of validators, typically between 100 and 1000, with the highest stakes can be part of the active validator set. Once staked, validators take on the responsibility of validating transactions and executing Intelligent Contracts. Their role is crucial for ensuring the network’s reliability and achieving consensus on transaction outcomes. +- **Validator Participation**: Only a maximum of 1000 validators with the highest stakes can be part of the active validator set. Once staked, validators take on the responsibility of validating transactions and executing Intelligent Contracts. Their role is crucial for ensuring the network's reliability and achieving consensus on transaction outcomes. - **Delegated Proof of Stake (DPoS)**: GenLayer enhances accessibility and network security through a Delegated Proof of Stake system. This allows token holders who are not active validators themselves to delegate their tokens to trusted validators. By delegating their tokens, users increase the total stake of the validator and share in the rewards. Typically, the validator takes a configurable fee (around 10%), with the remaining rewards (90%) going to the delegating user. - **Earning Rewards**: Validators, and those who delegate their tokens to them, earn rewards for their contributions to validating transactions, paid in GEN tokens. These rewards are proportional to the amount of tokens staked and the transaction volume processed. -- **Risk of Slashing**: Validators, and by extension their delegators, face the risk of having a portion of their staked tokens [slashed](/core-concepts/optimistic-democracy/slashing) if they fail to comply with network rules or if the validator supports fraudulent transactions. +- **Risk of Slashing**: Validators, and by extension their delegators, face the risk of having a portion of their staked tokens [slashed](/understand-genlayer-protocol/core-concepts/optimistic-democracy/slashing) if they fail to comply with network rules or if the validator supports fraudulent transactions. + +## Owner, Operator, and ValidatorWallet + +When a validator joins, the system creates three distinct entities: + +**ValidatorWallet**: A separate smart contract wallet created automatically on `validatorJoin()`. This is the primary validator identifier and holds staked GEN tokens. + +**Owner Address**: The address that creates the validator (msg.sender). It controls staking operations and can change the operator address. Should use a cold wallet for security. + +**Operator Address**: Used for consensus operations. Can differ from the owner (hot wallet recommended). It can be changed by the owner but cannot be the zero address or reused across validators. + +## Epoch System + +The network operates in epochs (1 day): + +- **Epoch +2 Activation Rule**: All deposits become active 2 epochs after they are made +- Epoch finalization requires all transactions to be finalized +- Cannot advance to epoch N+1 until epoch N-1 is finalized +- Validators are "primed" via `validatorPrime()` each epoch (permissionless - anyone can call it) + +**Critical**: If `validatorPrime()` isn't called, the validator is excluded from the next epoch's selection. + +### 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 is not yet active +- **No consensus occurs** - validators are not yet participating +- Stakes are registered and prepared for activation in epoch 2 + +**Important**: The network transitions directly from epoch 0 to epoch 2 (epoch 1 is skipped). Validators and delegators who stake in epoch 0 become active in epoch 2, but only if they meet the minimum stake requirements. + +#### 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 to join | +| 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) | + +**Activation requires meeting minimums**: While you can join with any amount during epoch 0, your stake will only be **activated in epoch 2** if it meets the minimum requirements (42,000 GEN for validators, 42 GEN for delegators). Stakes below the minimum remain registered but inactive. + +#### Validators in Epoch 0 + +**Key behaviors:** + +1. **No minimum stake to join**: Validators can join with any non-zero amount during epoch 0 +2. **Registered for epoch 2**: Stakes are recorded and will become active when epoch 2 begins +3. **No priming required**: `validatorPrime()` is not needed during epoch 0 +4. **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 (epoch 1 is skipped) **only if they have at least 42,000 GEN staked** +- Must start calling `validatorPrime()` in epoch 2 for continued participation in epoch 4+ + +**Important**: 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 + +**Key behaviors:** + +1. **No minimum delegation**: Any non-zero amount accepted during epoch 0 +2. **Registered for epoch 2**: Delegation is recorded and will become active when epoch 2 begins +3. **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 (epoch 1 is skipped). 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 ACTIVE +``` + +**Epoch 0 (Bootstrapping):** +``` +Epoch 0: validatorJoin() or delegatorJoin() called → stake registered (not yet active) + No transactions processed, no consensus +Epoch 2: Stakes become active (if minimum met), network operational, validatorPrime() required +``` + +#### Share Calculation in Epoch 0 + +In epoch 0, shares are calculated at a 1:1 ratio with the input amount: + +``` +Shares = Input Amount + +Example: Deposit 1,000 GEN → Receive 1,000 shares +``` + +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 1 is skipped): + +1. **Epoch 0 stakes that meet minimums become active** - validators need 42,000 GEN, delegators need 42 GEN +2. **Normal minimum requirements apply** for new joins/deposits +3. **+2 epoch activation delay** applies to all new deposits +4. **validatorPrime() becomes mandatory** for validators to remain in the selection pool +5. **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. + +## Shares vs Stake + +The staking system uses shares to track ownership: + +**Shares** are fixed quantities that never change. You receive shares when depositing and exit by burning shares. They represent immutable claims on the stake pool. + +**Stake** is the dynamic GEN token amount. It increases with rewards/fees and decreases with slashing. The exchange rate is calculated as: + +``` +stake_per_share = total_stake / total_shares +``` + +**Example**: 100 shares representing 1,000 GEN (10 GEN per share). After rewards are distributed, the same 100 shares might represent 1,050 GEN (10.5 GEN per share). Rewards automatically compound without user action. + +## Validator Selection and Weight + +Validators are selected for consensus based on their weight, calculated using: + +``` +Weight = (ALPHA × Self_Stake + (1-ALPHA) × Delegated_Stake)^BETA +``` + +**Parameters:** +- **ALPHA = 0.6**: Self-stake counts 50% more than delegated stake +- **BETA = 0.5**: Square-root damping prevents whale dominance + +**Effects:** +- Higher stake leads to higher weight and higher selection probability +- Doubling stake only increases weight by approximately 41% +- Encourages distribution across validators +- Smaller validators often provide higher returns per GEN staked + +## Reward Distribution + +**Sources:** +1. Transaction Fees +2. Inflation (starting at 15% APR, decreasing to 4% APR over time) + +**Distribution Pattern:** +- **10%** → Validator owners (operational fee) +- **75%** → Total validator stake (validators + delegators) +- **10%** → Developers +- **5%** → Locked future allocation for the DeepThought AI-DAO + +Within the 75% stake allocation: +- Self-stake receives a portion based on the validator's own staked amount +- Delegated stake is split among delegators proportionally to their shares + +Rewards automatically increase the stake-per-share ratio without requiring user action. + +## Unbonding Period + +Both validators and delegators face a **7-epoch unbonding period** when withdrawing: + +- Prevents rapid stake movements that could destabilize the network +- Tokens stop earning rewards immediately upon exit +- Countdown starts from the exit epoch +- Funds become claimable when: `current_epoch >= exit_epoch + 7` + +## Validator Priming + +`validatorPrime(address validator)` is a critical function that: + +- Activates pending deposits +- Processes pending withdrawals +- Distributes previous epoch rewards +- Applies pending slashing penalties +- Sorts the validator into the selection tree + +**Key Properties:** +- **Monitoring Required**: Ensure correct execution +- **Permissionless**: Anyone can call it +- **Incentivized**: Caller receives 1% of any slashed amount +- **Critical**: If the node fails to prime, the validator is excluded from the next epoch +- **No Loss**: Missing priming doesn't lose rewards, but the validator can't be selected ## Unstaking and Withdrawing -To stop validating or to retrieve staked tokens, validators must initiate an [unstaking](/core-concepts/optimistic-democracy/unstaking) process, which includes a cooldown period to finalize all pending transactions. This ensures the network remains secure and all obligations are fulfilled before the withdrawal. +Both validators and delegators can withdraw their staked tokens, but must follow the unbonding process. + +### For Validators + +To stop validating or retrieve staked tokens, validators must: + +1. **Calculate shares to exit**: Determine how many shares to withdraw (partial or full) +2. **Call `validatorExit(shares)`**: Initiate the unbonding process +3. **Wait 7 epochs**: Tokens are locked during the unbonding period +4. **Call `validatorClaim()`**: Retrieve tokens after unbonding completes + +Validators can perform partial exits while remaining active, as long as their stake stays above the 42,000 GEN minimum. + +### For Delegators + +Delegators follow a similar process: + +1. **Calculate shares to exit**: Use `sharesOf(delegator, validator)` to check current shares +2. **Call `delegatorExit(validator, shares)`**: Initiate unbonding for a specific validator +3. **Wait 7 epochs**: Tokens are locked during the unbonding period +4. **Call `delegatorClaim(delegator, validator)`**: Retrieve tokens after unbonding + +**Important for delegators:** +- Exit each validator separately if delegating to multiple validators +- Claims are permissionless—anyone can trigger them on your behalf +- Tokens stop earning rewards immediately upon calling exit +- Multiple exits create separate withdrawals that can be claimed together + +For detailed step-by-step instructions and code examples, see the [Staking Guide](/validators/staking-guide). + +## Governance and Safeguards + +- **24-Hour Delay**: All slashing actions have a governance delay period +- Parameters like ALPHA, BETA, minimum stakes, and unbonding periods are adjustable through governance +- Maximum 1,000 active validators per epoch (adjustable) + +## Next Steps + +- [Staking Guide](/validators/staking-guide) - Practical guide for staking operations +- [Unstaking](/understand-genlayer-protocol/core-concepts/optimistic-democracy/unstaking) - Detailed unstaking process +- [Slashing](/understand-genlayer-protocol/core-concepts/optimistic-democracy/slashing) - Slashing conditions and penalties