Skip to main content

​
Smart Contracts Suite (learnway_onchain_infrastructure/)

LearnWay deploys an interconnected suite of Solidity smart contracts on Lisk L2 (OP Stack rollup). The contracts operate under a unified Role-Based Access Control (RBAC) governance layer managed by LearnWayAdmin.sol. Unlike typical token projects, XPContract and GemContract are custom UUPS-upgradeable gamification state and leaderboard engines (not standard ERC-20 tokens). They maintain verifiable on-chain player progression, transaction ledgers, activity cooldowns, and contest leaderboards directly on Lisk L2.

​
Inter-Contract Relationship & Hierarchy

​
Contract Deep Dive

​
1. LearnWayAdmin.sol (RBAC & Emergency Circuit Breaker)

  • Standard: OpenZeppelin AccessControlDefaultAdminRules and Pausable.
  • Central Source of Truth: All other contracts query LearnWayAdmin to check caller permissions.
  • Roles:
    • DEFAULT_ADMIN_ROLE: High-security multi-sig treasury key for role assignments and contract upgrades.
    • MANAGER_ROLE: Granted strictly to LearnWayManager.sol so it can trigger state changes across all domain contracts.
    • MINTER_ROLE / BURNER_ROLE: Granular roles for authorized token minting/burning.
    • EMERGENCY_ROLE: Circuit breaker capable of instantly pausing all state changes across the entire suite during security events.

​
2. LearnWayManager.sol (Business Orchestrator)

  • Purpose: Master coordinator called by the backend relayer (learnway-transaction-processor).
  • Core Functions:
    • completeLesson(address student, uint256 lessonId, uint256 xpEarned, uint256 gemsEarned): Atomically updates XP level progression, records gem rewards, and checks milestone criteria.
    • completeBattle(address winner, address loser, uint256 stakeAmount): Validates PvP quiz battle outcomes and transfers wagered gems to the winner.
    • addAchievement(...) & unlockAchievement(address user, uint256 achievementId): Registers achievements and triggers NFT badge mints.
    • mintCertificate(address student, uint256 courseId, string metadataUri): Issues a verifiable ERC-1155 completion certificate.

​
3. XPContract.sol (Custom On-Chain XP & Leaderboard Engine)

  • Architecture: UUPS-upgradeable state contract (not ERC-20).
  • On-Chain Accounting & Scoring Rules:
    • Point Allocations: Configurable constants for battleWinXP, battleLossXP, contestParticipationXP, correctAnswerXP, and incorrectAnswerXP.
    • Player Level Progression: Tracks totalXP, currentLevel, xpInCurrentLevel, xpRequiredForNextLevel, and emits LevelUpEvent.
    • Contest Leaderboards: Computes and stores on-chain contest rankings via getContestLeaderboard(contestId) and getTopUsers(count).
    • Seasonal Resets: Supports periodic leaderboard season rollover via SeasonResetEvent.
    • Batch Processing: Exposes batchUpdateXP for high-throughput multi-user reward distribution.

​
4. GemContract.sol (In-Game Gems Accounting & Transaction Ledger)

  • Architecture: UUPS-upgradeable utility accounting contract (not ERC-20).
  • On-Chain Ledger & Balances:
    • Balance Management: Tracks player gem balances, spending cooldown periods (COOLDOWN_PERIOD), and emits GemsRewardedEvent.
    • Verifiable Transaction Ledger: Emits indexed TransactionRecorded events (txIndex, txType, gems, xp, timestamp) for immutable on-chain audit trails.
    • High-Volume Updates: Exposes batchUpdateGems for multi-user reward distribution and contest payouts.
    • Access Controlled: Only authorized managers (with MANAGER_ROLE verified by LearnWayAdmin) can mint or deduct gems.

​
5. BadgesNFT.sol (Achievement NFTs)

  • Standard: ERC-721 with soulbound attribute support.
  • Behavior: Mints unique badge tokens for milestones (7-Day Streak, Solidity Master, Contest Champion) pointing to verifiable IPFS/ImageKit metadata.

​
6. LearnWayCertificate.sol (Course Completion Credentials)

  • Standard: ERC-1155 Multi-Token.
  • Behavior: Issues cryptographically verifiable course credentials containing student name, completion timestamp, instructor credential signature, and course ID.

​
7. VerifyingPaymaster.sol (Client Gas Sponsorship)

  • Standard: ERC-4337 Paymaster contract.
  • Behavior: Subsidizes gas exclusively for mobile client UserOperations executed through /alto. Validates server signatures generated by PaymasterSignerService.