> 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.evently.market/architecture/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.