Puzzle Reward Pool Staking Contract

[Mkalbani]

Location: contracts/puzzle_pool_staking
Estimated Time: 7 hours
Difficulty: Hard

Description

Allow players to stake tokens into a shared puzzle reward pool. Each week, a portion of the pool is distributed proportionally among players who solved puzzles that week, weighted by their solve count and difficulty. Stakers also earn a passive yield share from the pool's weekly allocation.

Tasks

• Design StakePosition struct: staker, amount, staked_at, last_claim_epoch
• Design Epoch struct: epoch_id, start_at, end_at, total_solves, reward_budget, distributed
• Implement stake(amount) — deposits tokens into pool, records position
• Implement unstake(amount) — withdraws stake after 7-day lock; partial unstake supported
• Implement record_solve(player, puzzle_difficulty) — callable by oracle; adds weighted solve credit for current epoch
• Implement close_epoch() — admin closes epoch, sets reward distribution amounts
• Implement claim_epoch_reward(epoch_id) — player claims their proportional reward for that epoch
• get_stake(player) — returns current stake and unclaimed epochs
• Emit Staked, Unstaked, EpochClosed, RewardClaimed(player, epoch_id, amount) events
• Write tests: stake, unstake lock enforcement, solve recording, epoch close, claim calculation

Acceptance Criteria

• Staking and unstaking work with lock period
• Solve credits weighted by difficulty
• Epoch rewards distributed proportionally
• Claims idempotent per player per epoch
• Contract deployed to testnet

[yinkscss]

@yinkscss has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

Hi, senior dev here, please can i work on this issue?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @yinkscss to this issue.

[drips-wave]

Congratulations, @yinkscss! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on March 30, 2026.

🧑‍💻 @yinkscss: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊