xln — Cross-Local Network

Provable bilateral credit with on-chain finality.

xln is a Reserve-Credit Provable Account Network (RCPAN). Independent Account machines exchange signed state off-chain; Entity authority governs those Accounts; Runtime provides deterministic orchestration and durable delivery; Jurisdictions provide collateral, settlement, disputes, and adversarial exit.

Start here

1. Architecture comparison — adoption-independent architecture matrix, DA analysis, scoring rubric, and falsification tests.
2. Unavoidable constraints — why scalable finance needs bilateral unicast, credit, proofs, and enforceable settlement.
3. RCPAN invariant — the bilateral financial bound.
4. Runtime → Entity → Account → Jurisdiction — the canonical implementation model.
5. Documentation index — theory, specs, runtime, security, operations, and release evidence.

Architecture evaluation, audit-evidence freshness, and launch readiness are independent. Current operational status is linked separately below and does not change the architecture rubric.

Repository map

xln/
├── core/             deterministic Runtime, Entity, Account, and boundaries
├── brainvault/       standalone deterministic wallet-derivation package
├── jurisdictions/    Solidity settlement and dispute contracts
├── frontend/         xln.finance client; presentation and user input
├── tests/            browser and full-stack E2E evidence
├── docs/             canonical documentation and immutable release evidence
├── scripts/          build, release, and operator tools
└── .archive/         historical source implementations; never live authority

core/runtime.ts is the narrow public facade. Core behavior belongs to its owning Runtime, Entity, or Account module; physical I/O remains outside the deterministic state-machine transitions.

BrainVault: standalone module used by XLN

BrainVault V1 is an independently packable, installable, and auditable memory-hard wallet-derivation module. It has its own package, frozen byte specification, vectors, native sources, binaries, manifest, CLI, and tests entirely inside brainvault/; it does not import XLN runtime, storage, network, frontend, or consensus code.

XLN is one consumer. Its terminal onboarding, browser wallet creation, remote runtime adapter, and recovery tests call BrainVault's public derivation and worker interfaces. Engine choice and XLN state never enter the frozen root.

Run and audit only BrainVault without starting XLN:

cd brainvault
bun install --frozen-lockfile --ignore-scripts
bun ./brainvault --smoke
bun ./brainvault

The exact minimal and expanded reading paths are in BrainVault's audit surface. Coding agents must also load its package-local contract.

Quick start

bun install
bun run dev
open https://localhost:8080

The canonical release identity is VERSION, mirrored by package.json. Do not infer the current version from prose or historical changelog entries.

Architecture

RuntimeInput
  └─ RuntimeTx[]
      └─ EntityInput
          └─ EntityTx[]
              └─ AccountInput
                  └─ AccountTx[]

Each live replica follows one deterministic transition law:

(previous replica, input) → { next replica, outputs }

• Runtime is the single writer and owns WAL commitment before external effects.
• Entity certifies organization-level state and routes exact child inputs.
• Account owns bilateral financial mutation, proposals, ACKs, and dispute proof.
• Jurisdiction observes finalized chain facts and enforces exceptional exits.
• Outputs move upward as deterministic data; network and chain I/O begin only after the enclosing Runtime frame is durable.

The complete vocabulary and ownership rules are in the canonical cascade guide.

Key commands

bun run dev                 # full local stack
bun run check               # repository verification gate
bun run build               # browser runtime bundle
bun run test:e2e:fast       # focused browser/full-stack bar
bun run test:e2e:full       # complete E2E suite
bun run test:contracts      # Solidity tests

Use Bun throughout the repository. Solidity and frozen-core changes have separate owner-controlled integrity gates.

Auditor reading path

1. Architecture comparison
2. Canonical cascade
3. Payment and HTLC flow
4. core/runtime/frame/process.ts — Runtime transition and WAL ordering
5. core/entity/consensus/input/consensus.ts — Entity transition entry
6. core/account/consensus/index.ts — bilateral Account consensus
7. core/account/tx/apply.ts — financial validation and mutation dispatch
8. core/storage/commit/commit.ts — durable Runtime commit boundary

Audit reports and release artifacts are evidence about particular bytes and dates. They are not live architecture documents and are not a substitute for reading the current canonical path.

Release and operational status

• Active work and blockers
• Current status
• Mainnet release bar
• Mainnet acceptance gate
• Signed release manifest
• Security evidence

These sources intentionally remain separate from the architecture verdict.

License

AGPL-3.0 · xln.finance