Double-entry from chain data

The right journal entry from a raw onchain action, when the chain never states intent.

What it is

You know what double-entry is. What’s new is what the chain does to it.

Every accounting system ever built quietly assumes a source document. An invoice, a trade confirmation, a line on a bank statement. Something that already tells you who the counterparty was, how much it was for, when it happened and what it was meant to be. Bookkeeping, in that world, is mostly the work of classifying a thing that has already explained itself to you.

A blockchain transaction explains nothing at all. It’s a record that state changed. What it actually meant is written down precisely nowhere, and it has to be reconstructed from what moved, where it moved, and in what order. So the journal isn’t read off the transaction. It’s derived from it, and that derivation is the whole job.

Why chain data makes it hard

There’s often no counterparty to speak of. The address you transacted with is a router, which called a contract, which called four more. The party you’re economically facing may not appear in the transaction anywhere.

One transaction is frequently not one event. A single atomic call can bundle a borrow, two swaps, a deposit and a fee. That’s six accounting events hiding behind one opaque top-level call, and all of their transfers land in the same undifferentiated pool. Nothing in the data marks which transfer belongs to which event. Attribute them wrong and every entry downstream inherits the mistake, quietly.

The amount is not the amount. Value moves with no transfer event at all, which is what a rebase is. Value gets charged with no instruction anywhere, in fees paid to system addresses your wallet never touches. A transaction that failed still moved money. And yield you’ve earned but haven’t claimed is on your balance sheet right now, while appearing in no transaction until the day you finally claim it, at which point a naive ledger books a year of income in a single afternoon and puts it in the wrong period.

The unit of account drifts under you. Shares are not the underlying. A wrapped token is not the asset. And two things with the same ticker are very often not the same thing.

Here’s what makes all of this dangerous rather than merely annoying. A wrong journal still balances. Debits equal credits, nothing errors, and the entry sits there being internally consistent and completely false. A leveraged position booked against the wrong asset. A receivable that will never clear. A fee line that got invented to make the numbers close.

Your books balancing tells you almost nothing, because wrong books balance too. A system that only checks that one thing will cheerfully tell you everything is fine, right up until your audit.

What correct output looks like

A journal where every entry traces back to the transaction that produced it, and a balance sheet that ties out to the chain rather than merely to itself.

The test isn’t whether the books balance. The test is whether the position you’ve recorded is the position you actually hold, denominated in the asset you actually hold it in, and whether you can show your working when somebody eventually asks. They will ask.

That means reconciling the journal against chain state continuously, and explaining the differences instead of absorbing them. Which is what the rest of these pages are about.