Skip to content

feat(contracts): implement achievement points ledger module (#402) - #406

Open
nuvoraxis wants to merge 1 commit into
MindFlowInteractive:mainfrom
nuvoraxis:feat/402-points-ledger-contract
Open

nuvoraxis wants to merge 1 commit into
MindFlowInteractive:mainfrom
nuvoraxis:feat/402-points-ledger-contract

Conversation

@nuvoraxis

Copy link
Copy Markdown
Contributor

Summary of Changes

This pull request implements the Achievement Points Ledger module for the Quest Contract ecosystem as requested in #402.

Key Features & Architecture

  • Location: contracts/points_ledger
  • Access Control: authorize_caller / deauthorize_caller admin-gated functions allow whitelisting specific game engines or verified contracts to award points.
  • Auditable Ledger: PlayerLedger persistently tracks both the aggregated balance and a full historical log (Vec<PointsEntry>) recording the player, awarded amount, reason code (Symbol), block timestamp, and caller address.
  • Strict Invariant: Every point award ensures that balance strictly reflects the sum of all historical earn entries.
  • Earn API: earn(caller, player, amount, reason_code) verifies caller authorization and records points atomically.
  • Public Read Methods: Exposes zero-cost queries get_balance(player) and get_history(player).
  • Event Logging: Emits Soroban events on every point award: topic: (earn, player), data: (amount, reason_code, caller).
  • Admin Governance: Enables secure admin transfer via transfer_admin.
  • Unit Test Suite: Thorough test coverage in contracts/points_ledger/src/test.rs verifying initialization, direct admin awards, authorized caller awards, rejection of unauthorized callers, balance-history equality invariant, and admin transfers.
  • Documentation: Complete README.md with architecture, interface specifications, and integration examples.

Verification

  • cargo check --package points_ledger passed with 0 errors.
  • Added to root Cargo.toml workspace members.

Closes #402

…Interactive#402)

- Add reusable Soroban smart contract in contracts/points_ledger
- Implement points balance and full historical ledger structure
- Support authorized caller access control (admin and whitelisted game contracts)
- Implement earn function recording amount, player, caller, reason code, and timestamp
- Ensure strict invariant: balance strictly equals sum of all history entries
- Expose read functions for get_balance and get_history
- Emit standard Soroban events on earn operations
- Support secure admin transfer via transfer_admin
- Add comprehensive unit test suite in src/test.rs
- Add detailed README.md documentation and workspace entry in Cargo.toml

Closes MindFlowInteractive#402
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Achievement Points Ledger

1 participant