LOAR: Decentralized Narrative Control Suite

Create AI-powered cinematic universes. Own them on-chain. Monetize them.

</div>

---

What is LOAR?

LOAR is a platform where creators deploy cinematic universes as smart contracts, generate AI video/image content, build branching narratives, and set up multiple revenue streams — all governed by token holders.

One-liner: "YouTube meets DAO meets AI studio" — creators own the IP, communities govern the canon, tokens capture the value.

Live testnet demo: loar.fun (Sepolia)

---

Honest Feature Status

We classify every feature by what actually works end-to-end today, not what has backend code or UI shells.

LIVE (Working end-to-end)

PARTIAL (Backend + contracts exist, frontend not fully wired)

These have working smart contracts deployed on Sepolia AND fully implemented backend APIs (tRPC), but the marketplace frontend is informational UI — it shows stats and explains how things work, without interactive buy/sell/bid transaction flows.

PLANNED (Not implemented)

---

Architecture

                 ┌─────────────────────────────────────────────────┐  
                 │                    Frontend                      │  
                 │  React 18 + Vite + TanStack Router + wagmi       │  
                 │  Port 3001                                       │  
                 └──────────┬──────────────────┬───────────────────┘  
                            │ tRPC              │ wagmi  
                            ▼                   ▼  
              ┌─────────────────────┐  ┌──────────────────────┐  
              │   API Server        │  │  Sepolia/Base (EVM)  │  
              │   Hono + tRPC       │  │  48 contracts        │  
              │   44 routers        │  │  (proxied +          │  
              │   400+ procedures   │  │  upgradeable)        │  
              │   Port 3000         │  └──────────┬───────────┘  
              │                     │             │ events  
              └──────────┬──────────┘             ▼  
                         │               ┌──────────────────┐  
                         ▼               │  Ponder Indexer   │  
              ┌──────────────────┐       │  29 tables        │  
              │  Firestore       │       │  GraphQL API      │  
              │  (user data,     │       │  Port 42069       │  
              │   content meta,  │       └──────────────────┘  
              │   analytics)     │  
              └──────────────────┘  

Key Flows

Auth: thirdweb Wallet (EVM) > SIWE Signature > Server JWT > Bearer Token > protectedProcedure

Content Creation: AI Generate > Decentralized Storage (SHA-256 dedup) > On-Chain Hash > Ponder Index

Universe Deployment (Atomic): UniverseManager.createUniverseWithToken() > Deploy GovernanceERC20 + Governor + TimelockController > Initialize Uniswap v4 Pool > Lock LP > Mint IdentityNFT (single tx)

Universe Deployment (Two-Step): createUniverse() (pays mint fee) > deployUniverseToken() (deploys token, pool, locker — mint fee WETH seeds the LP)

LP Yield: Uniswap v4 Swaps > LoarHookStaticFee (collects fees) > LoarLpLockerMultiple (distributes by BPS splits) > LoarFeeLocker (recipients claim ETH)

---

Smart Contracts (Sepolia)

48 EVM contracts are deployed on Sepolia testnet (chain ID 11155111) with multi-chain support for Base Sepolia (84532) and Base Mainnet (8453). Revenue contracts use an upgradeable proxy pattern: UUPS for singletons and Beacon Proxy for per-universe NFTs.

Multi-chain roadmap: Solana (8 Anchor programs) and Sui (8 Move modules) contract ports are code-complete but not yet deployed. Cross-chain token bridging via Wormhole NTT v3 is configured for testnet.

Core Protocol

Plus per-universe: Universe, GovernanceERC20, UniverseGovernor, UniverseTimelockGovernor, IdentityNFT contracts.

Additional Contracts

Revenue Infrastructure (UUPS Proxies)

These are upgradeable singleton contracts behind ERC1967 proxies. Upgrade via proxy.upgradeToAndCall(newImpl, "").

NFT Beacons & Factory

Per-universe NFT instances are deployed as Beacon Proxies. Upgrading a beacon upgrades ALL universe instances of that NFT type simultaneously.

Upgradeability

• UUPS Singletons: Deploy new implementation, call proxy.upgradeToAndCall(newImpl, ""). Only the contract owner can upgrade.
• Beacon NFTs: Deploy new implementation, call beacon.upgradeTo(newImpl). All universe instances upgrade at once.
• All contracts use OpenZeppelin Upgradeable v5.0.2 with Initializable + ReentrancyGuardUpgradeable.

---

How to Run Locally

Prerequisites

Quick Start

BASH
git clone <repo-url>  
cd loar  
bash setup.sh          # checks prereqs, copies .env.example → .env, installs deps  
# Edit .env — at minimum set SIWE_JWT_SECRET and FIREBASE_SERVICE_ACCOUNT  
pnpm dev               # starts web (3001) + server (3000) + indexer (42069)  

Environment

All apps read from a single .env at the repo root. Copy .env.example and fill in values.

Required for server:

• SIWE_JWT_SECRET — JWT signing (openssl rand -hex 32)
• FIREBASE_SERVICE_ACCOUNT — Firestore access (JSON string or file path)

Required for indexer:

• PONDER_RPC_URL_2 — Sepolia RPC endpoint

Required for payments (testnet):

• TREASURY_ADDRESS — Wallet address that receives ETH/$LOAR payments
• LOAR_TOKEN_ADDRESS — $LOAR ERC-20 contract address
• RPC_URL — Sepolia RPC for on-chain payment verification

Optional (server starts without these):

• FAL_KEY — AI generation
• GOOGLE_API_KEY — Gemini wiki generation
• OPENAI_API_KEY — GPT-4o-mini storyline generation
• STRIPE_SECRET_KEY — Enables card payments (card tab disabled without this)
• REDIS_URL — Distributed rate limiting (in-memory if unset, fine for single-instance)

See docs/environment.md for the full reference.

Individual Services

BASH
pnpm dev:web           # web only (port 3001)  
pnpm dev:server        # server only (port 3000)  
pnpm -F indexer dev    # indexer only (port 42069)  

---

How to Deploy

Architecture

                    ┌─────────────────┐  
                    │   Vercel (CDN)   │  ← apps/web (static SPA)  
                    │    loar.fun      │  
                    └────────┬────────┘  
                             │ HTTPS  
        ┌────────────────────┼────────────────────┐  
        │                    │                     │  
┌───────▼────────┐   ┌──────▼───────┐   ┌────────▼────────┐  
│  loar-server   │   │ loar-indexer │   │    Firebase      │  
│  Railway :3000 │   │ Railway:42069│   │    Firestore     │  
│  Hono + tRPC   │   │ Ponder v0.15 │   │   (data store)   │  
└───────┬────────┘   └──────┬───────┘   └─────────────────┘  
        │                    │  
  Storage providers   Sepolia / Base RPC  

Web → Vercel

1. Connect the repo to Vercel
2. Set env vars in Vercel dashboard: VITE_SERVER_URL, VITE_PONDER_URL
3. Build config is in vercel.json — SPA rewrites included

Server + Indexer → Railway (recommended)

1. Create a Railway project and connect your GitHub repo
2. Add two services from the same repo:
   • loar-server — root directory: apps/server (picks up railway.toml)
   • loar-indexer — root directory: apps/indexer (picks up railway.toml)
3. Set env vars in each service's Railway dashboard (see deployment docs)
4. Add custom domains: api.loar.fun → server, idx.loar.fun → indexer
5. Update Vercel env vars: VITE_SERVER_URL and VITE_PONDER_URL to your Railway URLs

Server + Indexer → VPS (Docker, alternative)

BASH
# On the VPS:  
git clone <repo-url> && cd loar  
cp .env.example .env   # fill in production values (CORS_ORIGIN = your Vercel URL)  
docker compose build  
docker compose up -d  

CI/CD: deploy.yml SSHs to VPS on push to main and runs docker compose build && up -d.
Required GitHub secrets: SSH_HOST, SSH_USER, SSH_PRIVATE_KEY, WORK_DIR.

Health Checks

---

Documentation

---

Web App Routes (62 pages)

Core

Universe & Creation

Marketplace & Commerce

Tokens & DeFi

Content & Wiki

Social & Community

Revenue & Licensing

Admin & Legal

---

Project Structure

loar/  
├── apps/  
│   ├── web/             # React 18 SPA (Vite + TanStack Router, 62 routes)  
│   ├── server/          # Hono + tRPC API (44 routers, 400+ procedures)  
│   ├── indexer/         # Ponder v0.15 blockchain indexer (29 tables)  
│   ├── contracts/       # Foundry/Solidity EVM (48 contracts, upgradeable, Sepolia/Base)  
│   ├── contracts-sol/   # Solana Anchor smart contracts (8 programs, planned)  
│   ├── contracts-sui/   # Sui Move smart contracts (8 modules, planned)  
│   ├── bridge/          # Wormhole NTT v3 cross-chain bridge config (planned)  
│   ├── mcp/             # MCP server — AI agent gateway (24 tools)  
│   └── mobile/          # Expo 52 / React Native (iOS + Android)  
├── packages/  
│   └── abis/            # Generated wagmi hooks + contract ABIs + addresses  
├── docs/                # Product + technical documentation (28 docs)  
├── .env.example         # Environment variable template  
├── setup.sh             # First-time setup script  
├── Makefile             # Command shortcuts  
└── turbo.json           # Turbo build config  

Common Commands

License

MIT

Source: https://github.com/EcosystemNetwork/loar