Add key staking so holders can lock keys to signal commitment and earn a loyalty tier

[Chucks1093]

Summary

Holding keys and staking keys are different levels of commitment. A holder who locks their keys for a period signals they are not selling — which is valuable information for creators and other buyers. The contract should track staked vs liquid balances per holder and expose the staking status so the client can display loyalty tiers based on how long and how many keys a wallet has staked.

Scope

• Add stake_keys(creator_id, amount: u32, lock_ledgers: u32) function
  • Moves amount from the holder's liquid balance to their staked balance
  • Records unlock_ledger = current_ledger + lock_ledgers
  • lock_ledgers must be at least a configurable minimum (e.g. 1000 ledgers ≈ 83 minutes)
  • A holder can have multiple stake positions for the same creator
• Add unstake_keys(creator_id, stake_id) function
  • Reverts with StillLocked if current ledger is before unlock_ledger
  • Returns keys to liquid balance on success
• Staked keys cannot be transferred or sold — attempts revert with KeysStaked
• Add get_stake_positions(creator_id, wallet) -> Vec<StakePosition> view returning each position: { stake_id, amount, unlock_ledger }
• Add get_liquid_balance(creator_id, wallet) -> u32 view returning only the unstaked balance

Acceptance Criteria

• Staked keys deducted from liquid balance immediately
• Unstake before unlock_ledger reverts with StillLocked
• Unstake after unlock_ledger returns keys to liquid balance
• Sell of staked keys reverts with KeysStaked
• Transfer of staked keys reverts with KeysStaked
• get_stake_positions returns all active positions for a wallet
• get_liquid_balance returns only unstaked keys

ETA: 24 hours

---

Coordinate on Telegram

[zoffunjunior381-jpg]

I'd like to take this. I build Soroban and Rust contracts, so staking with per-position lock tracking and liquid/staked balance enforcement is straightforward ground.

The data model is the core decision: each stake position needs a unique stake_id, the holder's wallet, creator_id, amount, and unlock_ledger, stored so a wallet can hold multiple concurrent positions for the same creator. The liquid balance is then always total_held minus sum of active staked amounts, which get_liquid_balance reads directly rather than maintaining a separate counter that could drift.

From there: stake_keys moves amount from liquid (reverting if insufficient), records the position with unlock_ledger = current_ledger + lock_ledgers, and enforces the configurable minimum. unstake_keys checks current_ledger >= unlock_ledger (StillLocked otherwise), removes the position, and credits liquid balance. sell and transfer check liquid balance only and revert with KeysStaked if the amount would dip into staked keys. get_stake_positions returns the Vec of active positions for a wallet and creator.

Tests cover the full acceptance list: early unstake reverts, late unstake succeeds, sell and transfer of staked keys revert, multiple concurrent positions per wallet, and the minimum lock_ledgers guard. cargo fmt and cargo clippy clean, WASM build verified.

I'll coordinate on Telegram as requested. Please assign this to me and I'll start with the data model and the stake/unstake entrypoints.

[grantfox-oss]

🦊 GrantFox — @zoffunjunior381-jpg has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #519)
2. Your PR will be reviewed by the accesslayerorg maintainers

Good luck! Track your progress on GrantFox.