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.
| 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 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
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.
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.
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 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.
The RJEA cascade is replayable:
(previous machine, exact input) → byte-identical next machine and outputs
core/runtime/: Runtime machine, WAL boundary and output planning.core/entity/: Entity transactions, candidate execution and validator
consensus.core/account/: Account transactions, bilateral consensus and financial
state roots.Money moves only through Account-owned transaction handlers. Entity authorizes and routes; Runtime orchestrates and persists.