Build a double-entry posting engine that accepts a complete journal or rejects it

When money moves, the books need a complete explanation of what changed. A funding instruction may increase an institution's cash and its liability to a customer. A fee may reduce that liability and increase income. Engineers need to preserve those relationships even when a request has malformed amounts, the wrong account, or a final leg that fails.

This tutorial builds an exact single-currency journal validator, then a portable posting model that returns a complete new snapshot or an unchanged one. The code is intentionally small enough to inspect. Actual database transactions and access controls are the next tutorial's work.

All accounts and events below are synthetic teaching data for fictional Cedar Teaching Bank. Calculations are author-derived. The selected limits and policies are implementation choices, not a banking jurisdiction's accounting rules.

Start with the institution's perspective

In the institution's books, cash is an asset. Customer deposits are liabilities: the institution owes the customers. This perspective matters because a customer's own bank account would be an asset in that customer's books. The Federal Reserve's bank balance-sheet release provides a classification example by displaying deposits among bank liabilities.

Normal account sides tell us how to interpret entries. Assets and expenses normally increase on debit; liabilities, equity and income normally increase on credit. Opposite sides decrease those normal balances. These mechanics are documented in GnuCash's accounting guide. Debit does not universally mean money leaving an account.

Look at both normal balances in this synthetic USD 1,000.00 funding:

Open this diagram at full size.

The journal debits cash 100000 minor units and credits Ada's deposit liability 100000. Raw debit-positive movements are +100000 and -100000. Normal-side movements are both +100000. The cash asset and deposit liability rise together.

State the bounded contract before writing code

The first variant accepts one entity, ledger and currency per journal. USD and EUR each use exponent 2 in the pinned SIX currency list, but they remain separate denominations. A debit of USD 100.00 cannot balance a credit of EUR 100.00 just because both wire strings say 10000.

The journal has exactly ten fields: version, ledger ID, entity ID, journal ID, business-operation ID, currency, effective time, source-availability time, booking period and ordered legs. Each leg has exactly account ID, side and amount. Unknown fields reject rather than silently disappearing. The full data contract specifies every rule and error precedence.

Use positive canonical decimal strings for monetary JSON. The profile permits at most 30 digits per leg and 2–32 ordered legs, involving at least two distinct accounts. Repeated account legs are allowed and retained. Reject 0, -1, 01, 1.00, 1e3, numeric JSON, booleans and null. Posting never guesses whether a number is dollars or cents and never repairs an invalid amount by rounding it.

Trusted account state supplies each account's scope, currency, type, normal side and status. A client cannot declare an account active or supply its own adjustment authority inside the journal.

Preserve the clocks and booking decision

Effective time answers when the instruction is economically effective under the selected convention. Source availability answers when the service had the evidence. Trusted recording time identifies server recording inside the transaction; it is not proof of the physical COMMIT instant.

All use genuine Gregorian UTC timestamps with exactly three fractional digits. Effective and source times must be no later than trusted recording time. Late evidence is supported: an effective date can precede source availability.

Booking period must be open. It normally equals the effective UTC month. If a September-effective instruction is booked into open October, this teaching profile requires trusted adjustment authority and a nonempty reason. Preserve September effective time and the explanation. Changing a month string alone is insufficient.

This makes a policy decision explicit without pretending that a generic engine decides how every accounting framework handles prior-period errors. Full period closing and reopening remain separate work.

Compute exact equality

For leg amount $m_i>0$, measured in minor units of the one currency, set $s_i=+1$ for debit and $-1$ for credit. The exact totals and residual are

The balancing decision is $R=0$. There is no tolerance: a residual of one minor unit is still a rejected candidate.

For a synthetic three-leg allocation:

The independently calculated credit total is 9700+300=10000, equal to the debit total. Normal-side movements are cash +10000, deposit liability +9700, income +300. This example does not establish a real bank tariff or fee eligibility.

Raw movement for account $a$ is $\sum_{i:\operatorname{account}(i)=a}s_i m_i$. Flip its sign for a credit-normal account to display normal-side movement. Negative normal movements are allowed: an ordinary debit to income decreases income. Funds capacity and acceptable account balances require additional product rules.

Validate everything before the commit boundary

The order matters. First validate trusted account/context structures, then the exact command, identifiers, currency, clocks and period. Next inspect each ordered leg, including positive string amount and account eligibility. Only after all legs pass should the validator return exact totals and accepted account movements.

A valid first leg does not authorize a partial write. The final leg might name an unknown account:

Open this diagram at full size.

A real database transaction must group the journal's effects all-or-nothing. Current account/period policy and counter allocation must be protected in that same boundary. The pure function here demonstrates the output/state contract without claiming to exercise database races or storage durability.

Read the Python and TypeScript core

The full reference modules include strict schemas and typed rejections. Their central arithmetic is deliberately explicit:

amount = int(leg["amount_minor"])
if leg["side"] == "debit":
    debit += amount
    signed = amount
else:
    credit += amount
    signed = -amount
raw[leg["account_id"]] = raw.get(leg["account_id"], 0) + signed

This runs after the amount has passed the positive canonical-string rule. Python's integer arithmetic retains all digits.

const amount = BigInt(leg.amount_minor);
if (leg.side === 'debit') debit += amount;
else credit += amount;
raw.set(
  leg.account_id,
  (raw.get(leg.account_id) ?? 0n) +
    (leg.side === 'debit' ? amount : -amount)
);

Do not insert Number(leg.amount_minor) before BigInt. The boundary case is 9007199254740000+993=9007199254740993. The result exceeds the safe Number integer range. Once a Number conversion loses a unit, converting that rounded value to BigInt cannot recover the instruction.

The APIs return complete JSON-safe decisions:

• Valid candidate: accepted / VALID_JOURNAL, exact totals, ordered movements and a preserved copied command.
• Rejected candidate: typed reason, null journal and no accepted movements. An unbalanced candidate includes its exact residual.
• Portable append: committed / POSTED with a new snapshot, string sequence and server recording metadata, or rejected with unchanged state.

The Python and TypeScript modules have no sibling or external runtime imports. See usage instructions.

Test the boundaries that change the answer

The fixture matrix includes independently specified funding, transfer, fee, multi-leg and huge-string expectations. Failure cases cover malformed amounts, unknown/closed accounts, mixed currencies, cross-entity scope, invalid dates, future source availability and closed periods.

The 32-leg case accepts sixteen debit-one and sixteen credit-one legs. The 33-leg case rejects before aggregate balancing. A four-leg case sums two maximum 30-digit legs on each side; its exact total exceeds the per-leg limit and must still be retained.

Snapshot tests show an invalid final leg leaves the previous state unchanged. They also test no input mutation, no aliasing between the returned journal and stored result, original leg order, duplicate journal ID and recording-time regression. Full-output parity compares Python and TypeScript values, nulls, errors, ordering, complete commands and resulting states.

Run python tests/test_posting.py and python tests/run_parity.py from the package. Their results are recorded with the package. Pure-model acceptance remains distinct from actual database integration evidence.

Use the guided comparison

Open the self-contained lab. It begins with the complete three-leg allocation and exact totals visible. Step through its guided checks, then switch to the one-unit imbalance, wrong currency, unknown final account or authorized booking adjustment.

Change the first-leg amount from 10000 to 10001. The residual becomes 1 immediately; the modeled committed count remains zero. Reset restores the canonical scenario, amount, playback stage and speed. Static figures above retain the explanation when scripts are unavailable.

What this engine proves

It proves conformance to the selected posting contract and exact debit/credit equality. It does not prove business legitimacy, source authenticity, available funds, durable database behavior, repeated-business-request identity, regulatory recognition or independent tamper evidence.

Historical-example decision: not useful for these deterministic mechanics. Synthetic cases expose the relevant boundaries directly without inventing a real bank's customer event.

You can now construct a complete journal, validate its accounts, preserve its clocks and interpret the result. Continue with Append-Only Journal Enforcement to place this contract behind a controlled storage boundary. Idempotent Journal Posting and Correcting and Reversing Entry Algorithm then address retries and preserved corrections.

The canonical technical contract and primary references remain the factual source for this article.