Skip to main content

​
ERC-4337 Account Abstraction & Paymaster

LearnWay provides a 100% gasless on-chain experience on the client side using ERC-4337 Account Abstraction. Learners interact through smart accounts without holding native ETH for gas.

​
Client-to-Paymaster Data Flow

​
The VerifyingPaymaster Policy Engine (PaymasterPolicyService)

The backend enforces strict cryptographic and security policies before signing any UserOperation:

​
1. Supported EntryPoints

  • 0x0000000071727De22E5E9d8BAf0edAc6f37da032 (ERC-4337 EntryPoint v0.7 — Recommended)
  • 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789 (ERC-4337 EntryPoint v0.6)

​
2. User Registration Verification

The sender address must be a registered smart account belonging to an active user in PostgreSQL:

​
3. Allowed Target Token Contracts

Only specific whitelisted tokens configured in environment variables are sponsored:
  • USDT_CONTRACT_ADDRESS (Tether USD on Lisk L2)
  • FUSD_CONTRACT_ADDRESS (Fonbnk USD stablecoin)

​
4. Allowed Method Selectors

The policy service unpacks standard smart account execution envelopes:
  • Single call wrapper: 0xb61d27f6 (execute(address dest, uint256 value, bytes func))
  • Batch call wrapper: 0x47e1da2a (executeBatch(address[] dests, uint256[] values, bytes[] funcs))
Inside the execution envelope, the inner call must strictly match one of the following ERC-20 selectors:

​
5. Rate Limiting & Sliding Windows

  • Rate Limit: Maximum of 10 sponsored requests per 60-second window per user address.
  • Window Resets: Sliding in-memory window (RATE_WINDOW_MS = 60000) protecting against flood attacks.

​
Cryptographic Signing Specification (PaymasterSignerService)

  • Supported Networks:
    • Chain ID 1135: Lisk Mainnet
    • Chain ID 4202: Lisk Sepolia Testnet
  • Validity Horizon:
    • validAfter: 0 (Immediately valid)
    • validUntil: Current timestamp + 300 seconds (5 minutes)
  • Packed paymasterData Structure:
  • Signing Key: Signed via ECDSA by the server’s private key (PAYMASTER_SIGNER_PRIVATE_KEY), which matches the authorized signer configured on VerifyingPaymaster.sol.

​
The Hosted Alto Bundler (/alto)

  • Role: Self-hosted Pimlico Alto ERC-4337 bundler.
  • Function: Receives completed UserOps from the mobile app via standard JSON-RPC (eth_sendUserOperation), simulates execution against Lisk L2 RPC nodes, batches valid operations, and submits handleOps transactions to the EntryPoint contract.

​
Client-Side Key Management & SLIP-39 MPC Security

To sign ERC-4337 UserOperations without requiring manual 12-word seed phrases, the mobile client implements a SLIP-39 2-of-3 threshold secret sharing scheme (SecretSharingService):
  1. Share Splitting: The master private key is generated client-side and split into 3 cryptographic shares:
    • Share 1 (localShare): Stored on the mobile device inside hardware-backed secure storage (iOS Keychain / Android Keystore), encrypted with the user’s passphrase.
    • Share 2 (backendShare1): Encrypted client-side with Argon2id + AES-GCM and stored in the backend database.
    • Share 3 (backendShare2): Encrypted client-side with Argon2id + AES-GCM as an independent backup share and stored in the backend database.
  2. 2-of-3 Threshold Reconstruction:
    • Any 2 shares can reconstruct the master signing key in memory. A single share reveals zero information.
    • Even though the server stores two remote shares, both are encrypted with the user’s secret passphrase before leaving the device, guaranteeing a zero-knowledge non-custodial model.
  3. Seedless Account Recovery:
    • When switching devices, the user logs in, retrieves the two encrypted remote shares, and decrypts them with their passphrase to restore wallet signing capabilities instantly.