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.

Core:
  /vibepaper/           Philosophy, architecture, eternal specs
  /runtime/             Consensus engine (BFT entity + bilateral account state machines)
  /jurisdictions/       Solidity contracts (Ethereum, Polygon, Arbitrum, ...)
  /worlds/              Economic simulations (.xln.js scenario files)
  /view/                Panel UI components (Graph3D, Entities, Depository, Architect)
  /frontend/            Main xln.finance app (uses /view)
  /simnet/              BrowserVM genesis configs (offline blockchain)
  /proofs/              Validation tests (Playwright E2E + smoke tests)

Dev:
  bootstrap.sh          One-command setup
  workflow.md           Daily commands
  claude.md             AI instructions
  .archive/             Old implementations (never deleted)

---

## 🚀 Quick Start

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

# Open browser
open http://localhost:8080

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

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.

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

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

• 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

# 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 proofs                  # Playwright E2E tests
bun test-ethereumjs-vm.ts       # BrowserVM smoke test

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

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)

• 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: /view/ + /vibepaper/xlnview.md

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

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

Config: /simnet/genesis.json

Demo:

bun test-ethereumjs-vm.ts
# ✅ Deploys contract, funds entities, executes transfers

• 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

• xlnview.md - Panel architecture + BrowserVM integration
• jea.md - Jurisdiction-Entity-Account model
• governance-architecture.md - Multi-sig voting system
• sessions/ - Technical deep-dives

• workflow.md - Daily dev commands
• restructure.md - Migration notes (Oct 2025 - delete later)
• claude.md - AI assistant instructions

• ✅ Repository restructure - Essence-driven naming (vibepaper, runtime, jurisdictions, worlds)
• ✅ BrowserVM integration - Offline simnet with @ethereumjs/vm
• ✅ Panel workspace - Dockview-based Bloomberg Terminal UX
• ✅ WebGPU/WebGL switch - Runtime renderer toggle (future-proof)
• ✅ IDepository interface - Standardizable ERC for reserve management
• ✅ DepositoryV1 - 69% smaller, self-contained (6.6KB vs 21KB)

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

Browser-only simulation. Zero infrastructure.

• Engine: @ethereumjs/vm (in-browser blockchain)
• Contracts: DepositoryV1.sol (6.6KB, implements IDepository)
• State: 500 prefunded entities, USDC + ETH
• Reset: Refresh page = new universe
• Use: Scenario rehearsals, VR demos, tutorials

Shared PoA network. Multi-user coordination.

• Network: Arrakis (custom PoA chain)
• Contracts: Full suite (EntityProvider, Depository, SubcontractProvider)
• Validators: 5 trusted nodes
• Use: Integration testing, onboarding flows, load testing

Production deployment. Real value.

• Chains: Ethereum (L1), Polygon/Arbitrum (L2s)
• Governance: Multi-sig + timelock
• Audits: Trail of Bits + OpenZeppelin
• Use: Live settlement network

Start here:

1. workflow.md - Daily dev commands
2. /vibepaper/xlnview.md - Panel architecture + BrowserVM
3. /vibepaper/jea.md - Jurisdiction-Entity-Account model
4. /simnet/readme.md - Offline blockchain setup

For deep dives: /vibepaper/sessions/

License: AGPL-3.0 Status: Active development (2025) Website: xln.finance (coming soon)