> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learnway.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Blockchain Architecture Overview

> High-level architecture of LearnWay on-chain ecosystem: Dual execution model, Smart Contracts on Lisk L2, Account Abstraction, Relayer, and Goldsky Indexer.

# Blockchain Architecture Overview

LearnWay operates a high-throughput, gasless Web3 infrastructure built on **Lisk L2** (OP Stack rollup). The blockchain subsystem is split into two distinct, decoupled pipelines:

1. **Backend Platform Execution (Relayer Path)**: Platform-triggered state changes (XP points, Gem rewards, NFT badges, Course certificates) are orchestrated by `learnway-backend` via the **`LearnWayManager`** contract, with `learnway-transaction-processor` acting as the relayer.
2. **Client-Side Account Abstraction (ERC-4337 Path)**: Mobile learners interact through embedded Smart Accounts. Transactions (such as USDT/fUSD transfers and approvals) are sponsored via the backend's **`VerifyingPaymaster`** and dispatched to the self-hosted **Alto Bundler (`/alto`)**.

```mermaid theme={null}
graph TD
    subgraph ClientLayer["📱 Mobile Client (ai_mentor)"]
        MobileApp["Learner Smart Account (ERC-4337)"]
    end

    subgraph BackendPaymaster["🛡️ Verifying Paymaster Service"]
        PaymasterAPI["POST /paymaster/rpc/:chainId<br/>• User Registration Check<br/>• Whitelist: USDT / fUSD<br/>• Allowed: transfer / approve<br/>• Rate Limit: 10 req / 60s"]
    end

    subgraph AAStack["⚙️ ERC-4337 Bundler Stack"]
        Alto["Alto Bundler (/alto)<br/>• Simulates UserOp<br/>• Batches handleOps"]
    end

    subgraph BackendRelayerFlow["⚡ Backend Platform Relayer"]
        Backend["learnway-backend"] --> Relayer["learnway-transaction-processor<br/>• Redis Nonce Locks<br/>• 15s Gas Escalation"]
    end

    subgraph OnChainSuite["⛓️ Lisk L2 Smart Contracts"]
        AdminContract["LearnWayAdmin (RBAC & Pausable)"]
        ManagerContract["LearnWayManager (Master Coordinator)"]
        EntryPoint["ERC-4337 EntryPoint 0.7"]
        PaymasterContract["VerifyingPaymaster Contract"]
        
        ManagerContract --> XP["XPContract (Gamification & Levels)"]
        ManagerContract --> Gems["GemContract (Gems Ledger & Rewards)"]
        ManagerContract --> Badges["BadgesNFT (ERC-721)"]
        ManagerContract --> Certs["LearnWayCertificate (ERC-1155)"]
        
        AdminContract -.->|RBAC Roles| ManagerContract
        AdminContract -.->|RBAC Roles| XP
        AdminContract -.->|RBAC Roles| Gems
        AdminContract -.->|RBAC Roles| Badges
        AdminContract -.->|RBAC Roles| Certs
    end

    subgraph IndexerLayer["📊 Subgraph Indexer"]
        Goldsky["Goldsky Subgraph Engine"] --> API["transactions_apiv2 Service"]
    end

    %% Mobile AA Flow
    MobileApp -->|1. Request Sponsorship| PaymasterAPI
    PaymasterAPI -->|2. Signed paymasterAndData| MobileApp
    MobileApp -->|3. eth_sendUserOperation| Alto
    Alto -->|4. handleOps| EntryPoint
    EntryPoint --> PaymasterContract
    EntryPoint -->|5. Gasless Execution| TargetTokens["USDT / fUSD Contracts"]

    %% Backend Relayer Flow
    Relayer -->|Submits Platform Tx| ManagerContract

    %% Indexing Flow
    Goldsky -->|Index Blocks & Events| OnChainSuite
    MobileApp -->|Query Wallet History| API
```

***

## Blockchain Subsystem Architecture Guides

* [Account Abstraction & Paymaster](/architecture/blockchain/account-abstraction): Client-side smart accounts, VerifyingPaymaster policy engine, allowed selectors, whitelist tokens, and `/alto` bundler.
* [Smart Contracts Suite](/architecture/blockchain/smart-contracts): Detailed specifications for `LearnWayAdmin.sol`, `LearnWayManager.sol`, `XPContract.sol`, `GemContract.sol`, `BadgesNFT.sol`, and `LearnWayCertificate.sol`.
* [Transaction Processor (Relayer)](/architecture/blockchain/transaction-processor): Server wallet nonce locks, BullMQ queue, 15-second automated gas escalation, and block confirmation webhooks.
* [Goldsky Indexer & Subgraphs](/architecture/blockchain/indexer-goldsky): Real-time event ingestion from Lisk L2, wallet balance history, and GraphQL query APIs.