XLN - Cross-Local Network

Instant off-chain settlement with on-chain finality.

Byzantine consensus meets Bloomberg Terminal meets VR. Run complete economic simulations in your browser—no backend needed.

---

🌐 Directory Structure

Core:
  /docs/                Philosophy, architecture, eternal specs
  /runtime/             Consensus engine (BFT entity + bilateral account state machines)
    /account-tx/        Account transaction handlers
    /entity-tx/         Entity transaction handlers
    /scenarios/         Economic simulations (ahb.ts, grid.ts, etc.)
    /evms/              EVM integrations (BrowserVM, remote)
  /jurisdictions/       Solidity contracts (Ethereum, Polygon, Arbitrum, ...)
  /frontend/            Main xln.finance app + 3D visualization
    /src/lib/components/   UI panels (Entity, Network, TimeMachine, etc.)
  /tests/               E2E tests (Playwright)

Dev:
  /scripts/             Utilities (playwright helpers, deployment, debug)
  /ai/                  AI integrations (STT server, telegram bot, council)
  bootstrap.sh          One-command setup
  CLAUDE.md             AI instructions
  .archive/             Old implementations (historical reference)

---

## 🚀 Quick Start

```bash
# Install + start everything
bun run dev

# Open browser
open http://localhost:8080

First run: ~2-3min (installs Foundry) After: ~10sec

---

🎯 What is XLN?

Cross-Local Network enables entities to:

• Exchange value instantly off-chain (BFT consensus)
• Anchor final state on-chain (Ethereum, Polygon, Arbitrum)
• Run complete economic simulations in browser (BrowserVM - no backend!)
• Visualize in VR (Quest/Vision Pro compatible)

Think: Lightning Network + Byzantine consensus + Bloomberg Terminal + Blender.

Finance is physics of trust

---

🏗️ Architecture (J-E-A Layers)

J - Jurisdiction Layer (On-Chain)

• What: Solidity contracts managing reserves, collateral, settlements
• Where: /jurisdictions/contracts/
• Contracts:
  • Depository.sol - Implements IDepository (future ERC standard)
  • EntityProvider.sol - Entity registration + quorum verification
• Deploy: Ethereum, Polygon, Arbitrum, any EVM chain

E - Entity Layer (Off-Chain BFT Consensus)

• What: Distributed organizations with threshold signatures
• Flow: ADD_TX → PROPOSE → SIGN → COMMIT
• Source: /runtime/entity-consensus.ts
• Deterministic: Nonce-based ordering, Merkle state roots

A - Account Layer (Bilateral Channels)

• What: Payment channels between entity pairs
• Perspective: Left/right with canonical ordering (entityA < entityB)
• Source: /runtime/account-consensus.ts
• Settlement: Bilateral state verification with Merkle proofs

---

💻 Key Commands

# Development
bun run dev              # Full stack (jurisdictions + runtime + frontend)
bun run check            # TypeScript + Svelte validation
bun run build            # Build runtime.js for browser

# Jurisdictions (Contracts)
bun run env:build        # Compile Solidity
bun run env:deploy       # Deploy to local network
bun run dev:reset        # Reset all networks + redeploy

# Frontend
cd frontend && bun run dev      # Vite dev server
cd frontend && bun run build    # Production build

# Testing
bun run test:e2e          # Fast E2E: 8 core scenarios in parallel
bun run test:e2e:fast     # Same fast bar, explicit name
bun run test:e2e:full     # Full E2E: every tests/e2e*.spec.ts target
bun run test:e2e:parallel:isolated  # Raw isolated E2E runner for custom targets

# Production-scale runtime adapter benchmarks
bun run bench:radapter:hub1m         # 1M saved hub accounts, 1% hot set, real /rpc WebSocket
bun run bench:radapter:hub1m:allmem  # Same, but materialize all 1M accounts into runtime memory

---

🎨 XLNView Panel System

Bloomberg Terminal-style workspace. Drag, dock, float, tab - full Chrome DevTools UX.

Core 4 Panels (Open by Default)

1. 🌐 Graph3D - Force-directed network viz (WebGL/WebGPU toggle)
2. 🏢 Entities - Live entity list (reserves, accounts, activity)
3. 💰 Depository - On-chain J-state viewer (BrowserVM queries)
4. 🎬 Architect - God-mode controls (5 modes: Explore/Build/Economy/Governance/Resolve)

Layouts

• Default: 4-panel workspace
• Analyst: Graph3D + Depository + Console (research mode)
• Builder: Architect + Graph3D + Entities (creation mode)
• Embed: Graph3D only (for docs/blog posts)

Tech: Dockview (2.8k stars), Svelte reactivity, localStorage persistence

Source: /frontend/src/lib/components/ + /docs/xlnview.md

---

🧪 Simnet (Offline Blockchain in Browser)

No localhost:8545. No cloud RPC. Pure browser.

• Engine: @ethereumjs/vm v10 (official Ethereum Foundation implementation)
• Deployed: Depository.sol + 500 prefunded entities
• Tokens: USDC (id=1), ETH (id=2)
• Reset: Refresh page = new universe
• Persistent: Optional IndexedDB (resume sessions)

Config: Genesis configs in runtime/evms/browser-evm.ts

Demo: Load any scenario (AHB, Grid) - BrowserVM deploys contracts automatically

---

🎮 VR/Quest Support

• WebXR: Enabled by default (WebGL renderer)
• Offline: Simnet works without network (perfect for VR demos)
• Performance: 72fps in Quest 3
• Future: Hand tracking, voice commands, spatial UI

---

📚 Documentation Tree

Root:
  readme.md              This file - project overview
  todo.md                Active TODO/NEXT backlog
  CLAUDE.md              AI assistant instructions
  CHANGELOG.md           Version history

/docs/
  ├── contributing/      How to develop on XLN
  │   ├── workflow.md           Daily commands (bun run dev, etc)
  │   ├── bug-prevention.md     Pre-commit checklist
  │   ├── agentic.md            AI autonomous execution (80% rule)
  │   └── adhd-format.md        Response formatting guide
  │
  ├── research/          Explorations & specifications
  │   ├── insurance/            Insurance layer designs
  │   │   ├── claude-analysis.md
  │   │   ├── codex-analysis.md
  │   │   └── gemini-analysis.md
  │   ├── depository-core.md    Contract logic summary
  │   └── rollups-position.md   XLN vs rollups comparison
  │
  ├── status.md          Current launch state and blocker order
  ├── mainnet.md         Real-user-fund release bar
  ├── roadmap.md         Strategic rollout plan
  ├── recovery-watchtower-protocol.md
  │                       Recovery, tower backup, and last-resort dispute spec
  ├── deployment/        Deploy and ops runbooks
  ├── archive/           Historical snapshots only
  │
  ├── about/             Philosophy & origin
  │   ├── homakov.md            Founder's vision
  │   └── repo-structure.md     Private vs public repos
  │
  ├── testing/           Test procedures
  │   └── ahb-demo.md           AHB demo steps
  │
  └── docs/              Core architecture (existing)
      ├── rjea.md               R→E→A→J flow explanation
      ├── xlnview.md            Panel architecture
      ├── flow.md               Transaction flow
      └── ...                   (eternal specs)

Quick links:

• New to XLN? Start with docs/readme.md
• Current priorities? Check todo.md
• Current launch state? Read docs/status.md
• Mainnet bar? Read docs/mainnet.md

---

🔥 Recent Updates (0.1.5 - May 2026)

• ✅ Official watchtower - Same-origin /api/tower/*, standalone daemon, scheduled sweep, and no public /api/watchtower/* sweep exposure
• ✅ Encrypted recovery - Tower backup bundles and delayed-last-resort active remedies are encrypted; plaintext active remedies are rejected
• ✅ Recovery E2E - Wiped-browser tower restore and post-restore channel payments are covered by browser tests
• ✅ Prod health - Market maker/reset recovery and prod payment smoke passed in the 0.1.5 release pass
• ✅ Planning cleanup - Live TODO/NEXT work is consolidated into todo.md

---

🛠️ Tech Stack

Runtime: TypeScript + Bun Frontend: Svelte + Vite + Three.js Contracts: Solidity + Hardhat Blockchain: @ethereumjs/vm (simnet) → Hardhat (local) → Ethereum/L2s (prod) Panels: Dockview (2.8k⭐) Tests: Playwright

---

🗺️ Network Roadmap

The current release line is production-demo/public-testnet grade, not mainnet-ready. The active blocker order is in todo.md, current status is in docs/status.md, and the real-user-fund bar is in docs/mainnet.md.

Current focus:

• keep local and prod-like E2E green for payments, swaps, disputes, recovery, and watchtower action;
• finish Peer State Refresh and account-level recovery coverage UX;
• run release-duration soak/gates before any mainnet-candidate claim;
• make chain/RPC, operator keys, tower gas policy, and monitoring explicit;
• prepare external audit material before real funds.

---

📖 Learn More

Start here:

1. docs/readme.md - Documentation index
2. todo.md - Active TODO/NEXT backlog
3. docs/status.md - Current launch state
4. docs/mainnet.md - Mainnet release bar
5. docs/recovery-watchtower-protocol.md - Recovery and watchtower protocol

For deep dives: docs/readme.md

---

License: AGPL-3.0 Status: Active development, pre-mainnet 0.1.5 Website: https://xln.finance