Role: live implementation guide
Audience: protocol implementers and auditors
Authority: executable types and reducers; this guide explains their ordering
This document traces value through the nested Runtime → Entity → Account cascade. Read the cascade architecture first.
user / peer / J watcher
│
▼
RuntimeInput
├─ RuntimeTx[]
└─ routed EntityInput[]
│
▼
EntityInput
├─ EntityTx[]
└─ Entity consensus evidence
│
▼
AccountInput
└─ frame | ack | ack_frame | dispute | board_hanko_refresh
│
▼
AccountFrame
│ bilateral ACK
▼
EntityOutput
│
▼
RuntimeFrame → WAL → external delivery
An EntityTx is not an AccountTx. It may deterministically produce local
AccountTx[] admission, or it may carry one exact AccountInput as
EntityTx.accountInput. Both enter applyAccountInput; neither bypasses the
Account machine, and only the latter is an Account input on the wire.
directPayment is the immediate, non-conditional operation for a trusted
delivery route. The wallet emits it only when the user explicitly selects
trusted delivery and the route has a recipient gateway:
type DirectPaymentIntent = Extract<EntityTx, { type: 'directPayment' }>;
The Entity handler validates the route and converts the next hop into an
Account-owned direct_payment transaction. The Account reducer:
deriveDelta;The counterparty replays those exact transactions against its matching committed Account state. It ACKs only the byte-identical frame and state root. Forwarding to a later hop is created from the committed child frame, never from an uncommitted proposal.
source Entity
└─ Account(source, hop 1)
└─ committed forward
└─ hop 1 Entity
└─ Account(hop 1, hop 2)
└─ ...
directPayment, which creates Account direct_payment.instant and async payments use htlcPayment, which creates Account htlc_lock along a prepared encrypted route.placeSwapOffer, which creates Account
swap_offer; canonical matching commits Account swap_resolve fills. There
is no separate public hashlock-swap transaction.prepareCrossJurisdictionSwap, followed by
proposer materialization and one registerCrossJurisdictionSwap at each
hub. Those registrations create the exact source and target Account
cross_pull_lock legs together. The exact paired Runtime cohort is the only
opening path, and cross_pull_close is the only terminal path; there is no
generic pull product or public raw pull Entity command.extendCredit, which creates the Account set_credit_limit.lendingOffer → lending_fund, lendingBorrow → lending_borrow_request,
lendingRepay → lending_repay, and
lendingClosePosition → lending_close_request. Account follow-ups grant or
revoke loan credit and pay out a closed lender position only after the
corresponding bilateral commit.Cross-jurisdiction swaps never enter the user-payment handler. Their source and target legs bind the order, route, jurisdiction evidence, and hash ladder in the Account state where settlement is enforced.
Each hop commits an htlc_lock Account transaction containing:
The lock immediately reduces spendable capacity through Account holds. No separate balance cache is authoritative.
1. User commits a lock toward H1.
2. H1 commits the next lock toward H2.
3. H2 commits the final lock toward the recipient.
4. Recipient returns the secret through its Account with H2.
5. H2 resolves backward through its Account with H1.
6. H1 resolves backward through its Account with the user.
Every unlock is an htlc_resolve inside a committed bilateral Account frame.
A self-payment follows the same six logical edges; co-located Runtime replicas
may deliver them quickly, but may not skip certification or WAL visibility.
The raw secret is not guessed, polled, or read from a contract. It becomes usable only after the exact encrypted offer and Account acknowledgement make the reveal deterministic.
Deadlines are frame/J-height data, not local timers. A timeout transaction may release a lock only when the committed deterministic height permits it. Transport retries resend the exact signed input; they never create a new proposal with a different payload.
Account proposals do not expire locally. Once a Hanko leaves a replica, that proposal is final and is resent unchanged until the protocol advances.
Both peers may propose the same next height. The lower Entity id is canonical LEFT, and the valid LEFT frame wins the collision at equal height. RIGHT:
This is not a timeout, leader election, or retry heuristic. It matches the unconditional LEFT tie-break enforced by the jurisdiction contract, so the off-chain winner is also the dispute winner.
Account settlement and dispute requests become deterministic outputs. Runtime submits them after its enclosing frame is durable. The reducer never reads a live contract nonce or balance.
Finalized contract evidence follows one canonical path:
transport log
→ JEventIngress
→ JEvent
→ JurisdictionEvent
→ certified JurisdictionEventBlock
→ RuntimeInput
→ EntityTx
→ AccountTx
Authenticated events update Account jurisdiction state, including collateral, settlement, dispute, and nonce facts. Malformed financial evidence fails loud in development and tests. Production drops malformed uncommitted ingress; it does not publish it in a Runtime frame.
Rebalance is an Account protocol, not a faucet side effect:
request_collateral with the exact fee-policy version;A request is never silently topped up or inferred from a live contract read. Missing fee state rejects the batch before any reserve or Account mutation.
core/types/entity-tx.ts — user and peer Entity intents.core/types/account.ts — Account Input, Tx, Frame, State, and Replica.core/entity/tx/handlers/payments/direct-payment.ts — direct intent routing.core/entity/tx/handlers/htlc/payment.ts — prepared onion admission.core/account/consensus/index.ts — the single Account input boundary.core/account/tx/apply.ts — validation dispatch.core/account/tx/mutation.ts — Account-owned mutation dispatch.core/account/consensus/ — proposal, ACK, collision, and commit.core/runtime/frame/ — enclosing Runtime frame and WAL boundary.For executable evidence, start with:
core/__tests__/finance/state/derive-delta-property.test.ts;core/__tests__/account/consensus/account-frame-integrity.test.ts;core/scripts/operations/persistence/persistence-simultaneous-proposal-smoke.ts;core/__tests__/runtime/commit/runtime-frame-atomicity.test.ts;