> ## 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.

# Transaction Processor (Backend Relayer)

> On-chain transaction execution engine (learnway-transaction-processor/), LearnWayManager interaction, nonce management, and gas escalation.

# Transaction Processor (`learnway-transaction-processor/`)

The **LearnWay Transaction Processor** is the backend's dedicated blockchain relayer. It processes, signs, queues, and submits all platform-driven smart contract transactions (`LearnWayManager`, `XPContract`, `GemContract`, `BadgesNFT`, `CertificatesNFT`) on **Lisk L2**.

***

## Relayer Architecture & Flow

```mermaid theme={null}
graph TD
    Backend["Core Backend (learnway-backend)"] -->|Contract Action Job| TxQueue["Redis BullMQ Relayer Queue"]
    
    TxQueue --> Worker["Relayer Worker Process"]
    
    Worker --> NonceManager["Distributed Nonce Lock (Redis)"]
    NonceManager --> GasEstimator["Lisk L2 RPC Gas Estimator"]
    
    GasEstimator --> Signer["Relayer KMS / Server Wallet Key"]
    Signer --> Submit["Broadcast Tx to LearnWayManager"]
    
    Submit --> ReceiptPoller["Transaction Receipt Poller"]
    
    ReceiptPoller -->|Success - Confirmed| Webhook["Dispatch Success Webhook to Backend"]
    ReceiptPoller -->|Stuck / Timeout| Escalator["Bump Gas 15% and Re-broadcast with Same Nonce"]
```

***

## Key Modules & Responsibilities

### 1. Interacting with `LearnWayManager.sol`

* Submits atomic administrative transactions:
  * Awarding XP and Gems upon lesson or battle completion.
  * Distributing contest and tournament prize pools.
  * Minting ERC-721 milestone badges and ERC-1155 course certificates.

### 2. High-Concurrency Nonce Management

* Uses atomic Redis locks per relayer address to eliminate nonce collisions (`nonce too low` or `replacement transaction underpriced`).
* Automatically resynchronizes nonces against Lisk L2 RPC nodes in case of process restarts.

### 3. Automated 15-Second Gas Escalation

* Actively monitors transaction receipts on Lisk L2.
* If a transaction is unconfirmed after 15 seconds, the relayer bumps `maxPriorityFeePerGas` by 15% and re-broadcasts with the exact same nonce to ensure sub-minute finality.

### 4. Architectural Separation

* **`learnway-transaction-processor`**: Dedicated exclusively to **backend-relayed** platform contract executions on `LearnWayManager`.
* **ERC-4337 Account Abstraction (`/alto`)**: Dedicated exclusively to **mobile client** user operations.