xln

Runtime code map

Role: source-reading guide Audience: protocol implementers and auditors Authority: current source paths, enforced by check:runtime-doc-paths

The core/ tree contains three nested state machines and the infrastructure that drives them. Read the cascade before the services around it.

The 90-minute path

1. Vocabulary and commitments

  1. core/runtime/types.ts — Runtime Input, Tx, Frame, and live replica.
  2. core/entity/types.ts — Entity State, candidate, Frame, and replica.
  3. core/types/account.ts — Account State, replica, Input, Tx, and Frame.
  4. core/account/commitment/state-root.ts — the exact bilateral commitment.
  5. core/entity/consensus/state-root.ts — Entity commitment, including the deterministic Account-replica projection.

2. One input through all three machines

  1. core/runtime/frame/process.ts — the visible Runtime coordinator.
  2. core/runtime/frame/lifecycle/prepare.ts — detach one immutable Runtime input.
  3. core/runtime/frame/apply.ts — apply Runtime and routed Entity work.
  4. core/entity/consensus/input/consensus.ts — the Entity entry point.
  5. core/entity/consensus/frame/application.ts — replay a candidate.
  6. core/account/consensus/index.ts — the Account entry point.
  7. core/account/tx/apply.ts — validate one Account transaction.
  8. core/account/tx/mutation.ts — mutate Account-owned financial state.

3. Certification and failure

  1. core/entity/consensus/proposal/start.ts — one canonical proposal builder; a one-member board certifies its own quorum without a second implementation.
  2. core/entity/consensus/proposal/precommit-input.ts — multi-validator precommit collection and threshold certification.
  3. core/account/consensus/incoming/collision.ts — deterministic same-height LEFT-wins rollback.
  4. core/account/consensus/incoming/ack-commit.ts — bilateral commit.
  5. core/runtime/frame/lifecycle/storage-failure.ts — pre/post-WAL failure rules.
  6. core/storage/commit/commit.ts — the only durable Runtime commit point.
  7. core/storage/recovery/journal/replay.ts — rebuild from durable truth.

4. External settlement

  1. core/jurisdiction/machine/history-consensus/index.ts — certified J-prefix facts.
  2. core/jurisdiction/adapter/events/ingress-transform.ts — external evidence boundary.
  3. core/entity/tx/j-events.ts — certified J effects enter Entity.
  4. core/account/settlement/j-finality.ts — Account-owned settlement finality.
  5. core/runtime/j-submit/j-submit.ts — durable post-frame submission lifecycle.

Folder ownership

Folder Owns Must not own
core/runtime/ Runtime input, frame, WAL ordering, routing Entity/Account financial rules
core/entity/ Entity transactions, candidates, Hanko consensus physical storage or transport
core/account/ bilateral consensus and every money mutation Entity/Runtime orchestration
core/jurisdiction/machine/ deterministic J protocol facts RPC/provider behavior
core/jurisdiction/adapter/ chain reads, authenticated receipts, submissions consensus authority
core/storage/ current state, WAL, history views, replay protocol decisions
core/network/p2p/ Runtime-to-Runtime delivery financial state
core/network/relay/ discovery and market relay services Runtime consensus
core/api/public/ public typed Runtime surface service lifecycle
core/api/server/ HTTP/WebSocket delivery process orchestration
core/orchestrator/ process startup and service composition reducer logic
core/api/runtime-adapter/ frontend projections and commands direct state mutation
core/watchtower/ encrypted appointments and chain action spend-capable user keys
core/qa/ diagnostics and human-readable state dumps protocol behavior

The three commit boundaries

Runtime
  one local writer
  Input → apply owned state → WAL → publish → effects

Entity
  validator set
  Input → isolated candidate → Hanko certificate → install → outputs

Account
  two peers
  Input → isolated candidate → bilateral ACK → install → outputs

*State is frame-committed deterministic data. *Replica is the live instance that also owns the next candidate, mempool, certification, retry, or delivery metadata. *Machine describes transition logic; it is not a data type.

Runtime is locally single-writer, not concurrent consensus. Entity consensus may be single-signer or multi-signer. Account consensus is always bilateral. The common vocabulary must not hide these different trust boundaries behind a generic base class.

Visibility and failure

Executable reading traces

Supporting guides

Generated bindings live under jurisdictions/typechain-types/. Scenario, benchmark, QA, and archived files are valuable evidence but are not protocol authority.