xln

Runtime → Entity → Account → Jurisdiction

Role: canonical architecture reference Status: live Audience: core protocol implementers and auditors

xln is a hierarchy of deterministic financial state machines. Every layer uses the same nouns and transition direction, but each layer has a different trust and commit boundary.

The financial model is Jurisdiction → Entity → Account (J/E/A): existing settlement authorities, people/organizations, and their bilateral relationships. Runtime hosts and coordinates E/A replicas; it is the implementation envelope. The MML goal is provable accounts supporting 51% of world GDP by 2050. The implementation advances that goal through usable account proofs, chosen credit/collateral backing and enforceable Delta Transformers. Ordinary account activity need not be submitted individually to J to be covered.

Canonical vocabulary

Layer Live replica Committed state Input Transaction Frame Output
Runtime RuntimeReplica RuntimeState RuntimeInput RuntimeTx RuntimeFrame RuntimeOutput
Entity EntityReplica EntityState EntityInput EntityTx EntityFrame EntityOutput
Account AccountReplica AccountState AccountInput AccountTx AccountFrame AccountOutput
Jurisdiction J adapter/replica J state JInput JTx J block J event

The common shape is:

(replica, input) → { replica, outputs }

Entity application outputs commit destination Entity plus payload, not validator topology. Runtime converts them to exact signer-addressed EntityInput values inside the Runtime candidate and publishes them only after the WAL commit. Validator-consensus messages that already target a specific replica keep that exact signer.

The shared vocabulary does not imply a shared base class or generic reducer. Runtime, Entity and Account have different consensus and failure boundaries.

State is not the machine

*State is deterministic data committed by the corresponding frame.

The replica envelope owns everything required to build, certify, deliver or retry the next frame:

These envelope fields must not silently enter a state root.

Target ownership:

RuntimeReplica
  committed: RuntimeState
  mempool: RuntimeInput
  WAL / outbox / lifecycle

EntityReplica
  committed: EntityState
  mempool: EntityTx[]
  candidate / precommits / certificate

AccountReplica
  committed: AccountState
  mempool: AccountTx[]
  candidate / pending ACK / resend metadata

Nested input cascade

RuntimeInput
  ├─ RuntimeTx[]
  └─ routed EntityInput[]

EntityInput
  ├─ EntityTx[]
  └─ Entity consensus evidence

EntityTx
  ├─ Entity-owned operation
  ├─ accountInput
  │    └─ exact child AccountInput
  │         └─ frame | ack | ack_frame | dispute | board_hanko_refresh
  └─ financial intent
       └─ produces AccountTx[] locally for a future AccountFrame

The Account wire entrypoint is one union:

type AccountInput =
  | { kind: 'frame' /* exact proposal */ }
  | { kind: 'ack' /* exact acknowledgement */ }
  | { kind: 'ack_frame' /* ACK first, then proposal */ }
  | { kind: 'dispute' /* exact dispute Hanko */ }
  | { kind: 'board_hanko_refresh' /* exact certified refresh */ };

Every branch enters applyAccountInput. Local AccountTx[] admission and jurisdiction finality use the same transition but are never serialized as an EntityTx.accountInput. AccountInput preserves the exact signed bilateral payload.

*Replica names live data. *Machine names deterministic transition logic or its module; it is never a state interface.

Commit models

Runtime

Runtime has one writer and no external proposer consensus. It snapshots one live mempool, applies one deterministic frame and commits at WAL.

take input → apply → WAL commit → install/publish → dispatch effects

Before WAL, a failed mutation may only be discarded or followed by halt-and-reload. After WAL, delivery is retryable but the frame is committed.

Entity

The proposer executes a candidate without replacing committed EntityState. Validators replay the exact transactions and sign the exact frame and secondary hash manifest. The candidate installs only after certification.

Single-signer Entity uses the same pipeline with an immediate local certificate. It is not a separate transition semantics.

Account

Account is bilateral. A proposer builds an AccountFrame from local AccountTx[]; the peer independently replays and validates it. Committed AccountState changes only when the bilateral frame/ACK protocol allows it.

An AccountInput may acknowledge one frame and propose the next frame in the same message. The ACK and proposal bind different state epochs and therefore retain separate commitments.

Determinism and performance

The RJEA cascade is replayable:

(previous machine, exact input) → byte-identical next machine and outputs

Folder ownership

Money moves only through Account-owned transaction handlers. Entity authorizes and routes; Runtime orchestrates and persists.