> For the complete documentation index, see [llms.txt](https://docs.evently.market/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.evently.market/architecture/overview.md).

# System Architecture Overview

> Evently — The Pulse of Truth. Built on MegaETH.

***

## Stack

| Layer               | Technology                                                        |
| ------------------- | ----------------------------------------------------------------- |
| Smart contracts     | Solidity 0.8.20, Hardhat, MegaETH Chain ID 4326                   |
| Auth & wallets      | Privy (email, social, embedded wallets, smart accounts)           |
| Account abstraction | ERC-4337 (Privy Kernel smart wallets + Pimlico bundler/paymaster) |
| Session keys        | MetaMask Delegation Toolkit pattern (EIP-712 delegations)         |
| Real-time           | MegaETH WebSocket (`eth_subscribe`, `eth_sendRawTransactionSync`) |
| Frontend            | Next.js 14, Tailwind CSS, wagmi, viem, Supabase                   |
| Base token          | USDM (`0xFAfDdbb3FC7688494971a79cc65DCa3EF82079E7`)               |

***

## Architecture Diagram

```
┌───────────────────────────────────────────────────────┐
│                    USER                                │
│         (browser — no wallet extension needed)         │
└──────────────────────┬────────────────────────────────┘
                       │ email / Google / Twitter / Discord
                       ▼
┌──────────────────────────────────────────────────────┐
│               PRIVY AUTH LAYER                        │
│  Email OTP · Google · Twitter · Discord · GitHub      │
│                                                       │
│  Auto-creates:  Embedded Wallet (EOA)                 │
│  Wraps in:      Kernel Smart Account (ERC-4337)        │
└──────────────────────┬───────────────────────────────┘
                       │
       ┌───────────────┼───────────────┐
       │               │               │
       ▼               ▼               ▼
 READ PATH       WRITE PATH      SESSION PATH
(multicall)     (gasless tx)    (no popup/trade)
       │               │               │
       ▼               ▼               ▼
 HTTP+Multicall3  UserOperation   Session Key Tx
 2s TTL cache      via Bundler    (pre-delegated)
       │               │               │
       └───────┬───────┘───────────────┘
               ▼
      ┌──────────────────┐
      │    PAYMASTER     │
      │   (Pimlico)      │
      │  sponsors gas    │
      │  rate-limited    │
      └────────┬─────────┘
               ▼
      ┌───────────────────────────────────┐
      │     EventlyMarkets.sol          │
      │     MegaETH Chain ID 4326         │
      │                                   │
      │  placeOrder / sellToAMM           │
      │  createMarket / resolveMarket      │
      │  claimRewards / cancelOrder       │
      └──────────────────┬────────────────┘
                         │ events
                         ▼
      ┌────────────────────────────────────┐
      │   MegaETH WebSocket               │
      │   wss://mainnet.megaeth.com/ws     │
      │                                   │
      │   mini-blocks ~10 ms              │
      │   eth_sendRawTransactionSync      │
      │   watchContractEvent              │
      └──────────────────┬────────────────┘
                         │
                         ▼
      ┌────────────────────────────────────┐
      │   FRONTEND REALTIME ENGINE        │
      │   Instant confirmation (~10 ms)   │
      │   Live odds · Live order book     │
      │   No page refresh                 │
      └────────────────────────────────────┘
```

***

## Gas Sponsorship Flow

```
User triggers trade
  → sendGasless() checks shouldSponsor()
  → Privy packs UserOperation
  → Pimlico Paymaster signs (verifies whitelist + rate limit)
  → Pimlico Bundler submits to MegaETH
  → EventlyMarkets executes
  → Receipt returned synchronously via eth_sendRawTransactionSync
  → UI updates within ~10 ms
```

**Sponsored functions:** `placeOrder`, `sellToAMM`, `createMarket`, `resolveMarket`, `claimRewards`, `approve` (USDM)

***

## Session Key Flow

```
User clicks "Session" → one wallet popup
  → generatePrivateKey() — ephemeral key
  → smartWallet.signMessage(delegation)
    { sessionKey, selectors, contract, expiresAt, maxCalls }
  → stored in sessionStorage

Per trade (no popup):
  → tradeWithSession() — validates session
  → submits with session key context
  → up to 100 trades before session expires
```

***

## Security Controls

| Control                      | Value                            |
| ---------------------------- | -------------------------------- |
| Paymaster contract whitelist | EventlyMarkets + USDM only       |
| Sponsored selectors          | 6 core functions only            |
| Rate limit                   | 20 user ops / min / wallet       |
| Spend cap                    | 1 ETH equivalent / hour / wallet |
| Spam threshold               | 15 ops in 10 s → blocked         |
| RPC failover                 | 2 endpoints, health-checked      |

***

## Smart Contract Audit Result

`EventlyMarkets.sol` — **no changes required for ERC-4337 compatibility.**

* No `tx.origin`
* No `extcodesize` / EOA checks
* `msg.sender` used generically
* Compatible with smart account callers
