Skip to main content

Regen Staker

The Regen Staker system enables Dragon communities to create customizable token staking mechanisms with rewards distribution. Built on battle-tested staking primitives from UniStaker and Tally, the system provides flexible configuration for different token economics models while maintaining security and upgradeability.

Architecture Overview​

Core Components​

┌─────────────────────────────────────────────────────┐
│                  RegenStakerFactory                 │
│  • Deploys variant-specific staker contracts        │
│  • Ensures bytecode integrity via validation        │
│  • Provides deterministic deployment addresses      │
└─────────────────────┬───────────────────────────────┘
                      │ Creates
                      ▼
┌─────────────────────────────────────────────────────┐
│              RegenStaker (2 Variants)               │
├─────────────────────────────────────────────────────┤
│ WITH_DELEGATION:        │ WITHOUT_DELEGATION:       │
│ • IERC20Staking tokens  │ • Standard ERC20 tokens   │
│ • Surrogate delegation  │ • No delegation support   │
│ • Higher gas costs      │ • Lower gas costs         │
│ • Governance voting     │ • Simple staking only     │
└─────────────────────────────────────────────────────┘
                      │ Uses
                      ▼
┌─────────────────────────────────────────────────────┐
│           RegenEarningPowerCalculator               │
│  • Calculates user rewards based on staked amount   │
│  • Implements whitelist-based earning modifiers     │
│  • Configurable earning power rules                 │
└─────────────────────────────────────────────────────┘
                      │ Controls Access
                      ▼
┌─────────────────────────────────────────────────────┐
│                    Whitelists (3 Types)             │
├─────────────────────────────────────────────────────┤
│ • Staker Whitelist: Who can stake tokens            │
│ • Contribution Whitelist: Who can contribute rewards│
│ • Allocation Mechanism: Approved reward destinations│
└─────────────────────────────────────────────────────┘

Deployment Process​

Step 1: Pre-Deployment Planning​

As a Dragon preparing to integrate the RegenStaker with your Octant v2 vault strategy, determine your requirements:

  1. Token Selection
    • Stake Token: The token users will stake (e.g., your community's governance token).
    • Reward Token: The token distributed as rewards (could be stablecoins from vault yield).
    • Important: Both must be standard ERC20 tokens. Fee-on-transfer, rebasing, or deflationary tokens are NOT supported.
  2. Delegation Requirements
    • WITH_DELEGATION: Choose if your stake token implements. IERC20Staking interface and you need voting delegation.
    • WITHOUT_DELEGATION: Choose for standard ERC20 tokens or if delegation isn't needed.
  3. Access Control Strategy
    • Decide if you want open participation or whitelist-controlled access.
    • Plan your admin structure (consider multisig for production).
  4. Yield Distribution Strategy
    • Determine what portion of Octant vault yield goes to Stakers.
    • Decide on reward distribution frequency.
    • Plan integration with your vault's yield claiming mechanism.

Step 2: Deploy Supporting Infrastructure​

2.1 Deploy Whitelists (Optional)​

If you want to control access, you can deploy whitelist contracts:

// Deploy whitelists (can use address(0) to disable any whitelist)
Whitelist stakerWhitelist = new Whitelist();
Whitelist contributionWhitelist = new Whitelist();
Whitelist allocationMechanismWhitelist = new Whitelist();

// Add initial allowed addresses
stakerWhitelist.addToWhitelist(address(user1));
contributionWhitelist.addToWhitelist(address(rewardsProvider));
allocationMechanismWhitelist.addToWhitelist(address(votingMechanism));

Whitelist Purposes:

  • Staker Whitelist: Controls who can stake tokens (use address(0) for open access).
  • Contribution Whitelist: Controls who can add rewards to the pool (use address(0) for open access).
  • Allocation Mechanism Whitelist: Controls which mechanisms users can contribute rewards to (consider the audit status and security of any allocation mechanism before adding it to your whitelist).

2.2 Deploy Earning Power Calculator​

RegenEarningPowerCalculator calculator = new RegenEarningPowerCalculator(
    adminAddress,           // Admin who can update whitelist
    earningPowerWhitelist   // Optional whitelist for earning power modifiers
);

Step 3: Deploy via Factory​

3.1 Prepare Configuration Parameters​

RegenStakerFactory.CreateStakerParams memory params = CreateStakerParams({
    rewardsToken: IERC20(rewardTokenAddress),
    stakeToken: IERC20(stakeTokenAddress),
    admin: multiSigAddress,  // Use multisig in production
    stakerWhitelist: IWhitelist(stakerWhitelistAddress), // or address(0)
    contributionWhitelist: IWhitelist(contributionWhitelistAddress), // or address(0)
    allocationMechanismWhitelist: IWhitelist(allocationMechanismWhitelistAddress), // Required
    earningPowerCalculator: IEarningPowerCalculator(calculatorAddress),
    maxBumpTip: 1e18,        // Max tip for queue position bumping (in reward token units)
    maxClaimFee: 1e17,       // Max fee for claims (10% = 1e17 for 18 decimal token)
    minimumStakeAmount: 1e18, // Minimum stake amount (1 token for 18 decimal)
    rewardDuration: 30 days   // Distribution period (recommended: ≥30 days for precision)
});

Parameter Guidelines:

  • rewardDuration: 7-3000 days allowed, but <30 days may have ~1% precision loss.
  • maxClaimFee: Cannot be changed after deployment, consider to set conservatively.
  • minimumStakeAmount: Set based on your token's decimals and desired minimum.
  • maxBumpTip: Allows users to pay for priority in claim queue (set to 0 to disable).

3.2 Deploy the Regen Staker Contract​

// Get factory instance (deployed by Octant)
RegenStakerFactory factory = RegenStakerFactory(factoryAddress);

// Generate deployment salt (use something unique and deterministic)
bytes32 salt = keccak256(abi.encodePacked("Dragon", "V1", block.timestamp));

// Deploy based on your token type
address regenStakerAddress;

if (supportsDelegation) {
    // For IERC20Staking tokens with delegation
    regenStakerAddress = factory.createStakerWithDelegation(
        params,
        salt,
        regenStakerBytecode  // Provided by Octant
    );
} else {
    // For standard ERC20 tokens
    regenStakerAddress = factory.createStakerWithoutDelegation(
        params,
        salt,
        noDelegationBytecode  // Provided by Octant
    );
}

Step 4: Post-Deployment Configuration​

4.1 Configure Reward Notifiers​

// Set who can add rewards to the pool
RegenStaker regenStaker = RegenStaker(regenStakerAddress);
regenStaker.setRewardNotifier(rewardsNotifier, true);

4.2 Set Claim Fee Parameters (Optional)​

ClaimFeeParameters memory feeParams = ClaimFeeParameters({
    feeAmount: 5e16,           // 5% fee (for 18 decimal token)
    feeCollector: treasuryAddress  // Where fees go
});

regenStaker.setClaimFeeParameters(feeParams);

4.3 Initial Reward Distribution​

// Approve staker contract to spend reward tokens
rewardToken.approve(regenStakerAddress, rewardAmount);

// Notify staker of new rewards (must be done by authorized notifier)
regenStaker.notifyRewardAmount(rewardAmount);

User Operations​

For End Users (Stakers)​

// 1. Stake tokens
stakeToken.approve(regenStakerAddress, amount);
DepositIdentifier depositId = regenStaker.stake(
    amount,
    delegatee,    // Address to delegate to (only for WITH_DELEGATION variant)
    claimer       // Optional: address that can claim on user's behalf
);

// 2. Add more to existing stake
regenStaker.stakeMore(depositId, additionalAmount);

// 3. Claim rewards
uint256 rewardsClaimed = regenStaker.claimReward(depositId);

// 4. Compound rewards (only if reward token == stake token)
uint256 compounded = regenStaker.compoundRewards(depositId);

// 5. Withdraw staked tokens
regenStaker.withdraw(depositId, amount);

// 6. Contribute rewards to public goods (with signature)
regenStaker.contribute(
    depositId,
    allocationMechanism,
    amount,
    deadline,
    v, r, s  // EIP-712 signature
);

For Administrators​

// Update whitelists
regenStasker.setStakerWhitelist(newWhitelistAddress);
regenStasker.setContributionWhitelist(newWhitelistAddress);

// Emergency controls
regenStasker.pause();    // Pause user operations
regenStasker.unpause();  // Resume operations

// Note: Pausing does NOT stop reward accrual calculations

Security Considerations​

The following security considerations highlight common technical patterns in DeFi vault operations and are provided for informational purposes only. They are neither comprehensive nor prescriptive. Each organization must conduct its own security assessment and implement measures appropriate to its specific requirements and risk tolerance.

Critical Security Points​

  1. Allocation Mechanism Trust: Consider whitelisting only audited mechanisms. Users send rewards here and cannot recover them if the mechanisms are malicious.
  2. Token Compatibility: The system does NOT support:
    • Fee-on-transfer tokens
    • Rebasing tokens
    • Deflationary tokens
    • Tokens with non-standard transfer semantics.
  3. Whitelist Management: Changes take effect immediately and can lock out users. Plan transitions carefully.
  4. Pause Limitations: Pausing stops user actions, but rewards continue accruing. Plan pause durations accordingly.
  5. Delegation Variant Security: Tokens move to surrogate contracts. Verify by checking totalStaked() not contract balance.
  1. Use Multisig Admin: Deploy with multisig as admin for all production deployments.
  2. Audit Custom Code: Have any custom calculators or mechanisms audited.
  3. Test on Testnet: Thoroughly test your specific configuration before mainnet.
  4. Monitor Events: Set up monitoring for key events (stakes, withdrawals, reward notifications).
  5. Gradual Rollout: Start with limited rewards and gradually increase as confidence grows.

Example Configuration Patterns​

Pattern 1: Simple Staking Pool​

  • Use WITHOUT_DELEGATION variant.
  • Set all whitelists to address(0) for open access.
  • Same token for staking and rewards.
  • Enable compounding for auto-reinvestment.

Pattern 2: Governance Token Stake​

  • Use WITH_DELEGATION variant for voting.
  • Implement staker whitelist for controlled access.
  • Different reward token (e.g., stablecoin rewards).
  • Integrate with governance voting contracts.

Pattern 3: Public Goods Funding​

  • Either delegation variant, depending on token type.
  • Strict allocation mechanism whitelist.
  • Enable contribution whitelist for approved funders.
  • Connect to quadratic funding allocation mechanism.

Troubleshooting Guide​

Issue: "MinimumStakeAmountNotMet"​

Solution: Ensure stake amount meets the configured minimum. Check token decimals.

Issue: "NotWhitelisted"​

Solution: Add address to appropriate whitelist or set whitelist to address(0) to disable.

Issue: "InsufficientRewardBalance"​

Solution: Ensure contract has enough reward tokens before calling notifyRewardAmount.

Issue: "CompoundingNotSupported"​

Solution: Compounding only works when reward token equals stake token.

Issue: Transaction Reverts on Delegation Variant​

Solution: Verify your token implements IERC20Staking interface with delegation support.

Appendix: Gas Optimization Tips​

  1. Batch Operations: Use stakeMore instead of multiple stake calls.
  2. Variant Selection: WITHOUT_DELEGATION uses ~30% less gas.
  3. Claim Timing: Batch claims during low gas periods.
  4. Whitelist Consideration: Open access (no whitelist) saves gas on checks.