Skip to content

Reconciling the book to the chain

Your book tied to the onchain snapshot, with the difference explained rather than hidden.

Position by position Every balance in the book compared against the chain, per account, not netted into one total
A named difference Where the two disagree, the difference and its reason, rather than a rounding into a fee line
Unknown stated as unknown A position that could not be read comes back unknown, never as agreeing
In-flight value held A bridge leg between two chains carried as a placeholder instead of dropped
Checked before you see it The differences investigated at the sign-off that precedes delivery

The rest of this page is the argument for why that is worth doing, worked through one real position to the cent. It is the longest page in this section on purpose: every claim on it is checked against the engine, and two of them were wrong when we first wrote them.

An address can be read two ways.

Read the balance. Ask the chain what the address owns right now. Fast and simple, but it is one number from one source. It agrees with itself by construction, so a wrong one reads exactly like a right one.

Build the book. Take every transaction, work out what it did, and post both sides. Now the position is not handed to you, it is derived from evidence.

Most tools do one of these well. The value isn’t in doing one of them better. It’s in doing both, and then comparing them.

A reconciliation compares two numbers that were arrived at independently. It is only as good as the weaker of the two.

A balance gives you one number. A reconciliation needs two, arrived at independently, so a snapshot leaves you reporting a figure and watching it move.

A ledger keyed on the address gives you the second number, in a form the chain cannot answer for. The entries can be immaculate and still roll into a total whose parts a node was never asked about.

THE CHAIN SNAPSHOT THE BOOK LEDGER DIFFERENCE wallet USDC 0 wallet RLUSD 0 Euler collateral 0 Aave USDC debt interest
Snapshot on the left, ledger on the right, compared per account. They agree to zero everywhere except the debt, and there the difference has an explanation.

We key a position inside a protocol on the wallet, the protocol, the symbol, the contract and the sub-account. That is the address of a question rather than a label: it names a specific contract holding a specific position, which is exactly what gets handed to a node when something asks what is in there. Tokens you simply hold are keyed on the token, because the token answers the whole question to ask about them.

That is our argument, not a law of nature: an address tells the chain where to look, and an account tells it what to look for. An address is a location; an account is a position.

Our own parser proved it. We keyed the Aave debt in a hard transaction, decoded on the underlying reserve, which for a USDC debt is the USDC contract. It read fine, and the balance fetch blew up, because the USDC contract answers for USDC balances while the debt lives on the debt token. Re-key it onto the debt token and the question lands: same transaction, same amounts, same book. The difference between checkable and not was one field in an account name.

Reconciling both ways is not symmetry for its own sake. Each direction answers a question the other cannot.

Income with no transaction behind it A position earns continuously. The chain balance carries that income; your journal only carries what a transaction said. The gap between them is the accrual, measured rather than estimated
Every transaction accounted for A plain token balance has no index to absorb a mistake, so its account lands on exact zero or a transaction is missing. A missed transfer has nowhere to hide

The second one is why the check runs per account rather than on a total. A balance can agree with the chain and still be made of the wrong things: book a borrow at the wrong number and the debt total can still match, because the error is in what the total is made of. The cash leg beside it lands on exact zero or it does not, and that is what catches it.

We walked into exactly that ourselves, on an Aave borrow where the event’s number and the amount received differ by 1,970.18. The full anatomy of it, with the figures, is in one hard transaction, taken apart.

On a vault position, your share count only moves when you deposit or withdraw, and both of those are transactions you booked. Your shares minus the chain’s shares should therefore be zero. Not close to zero. Zero. A missed transaction has nowhere to hide, because interest does not mint shares.

On a debt position you lose that zero. A debt token rebases, so what comes back is one number that grows every block with no share count next to it. A small booking error and a little accrued interest move the same number, and only a stable unit underneath tells them apart.

It would be flattering to blame the instrument. Aave keeps an index-normalized balance internally, a scaled quantity that only moves when you borrow or repay, exactly like a vault share, because the protocol needs a stable unit to allocate interest against. The anchor is right there on the chain. We do not read it yet. Reading it would make a debt position provable to the penny; it needs a change in the parser and a change in reconciliation, and it is work we have not done. Today’s numbers reconcile without it, but we are not going to tell you a thing we have not built is a thing that cannot be built.

A few more honest limits.

A gap does not shout. It gets computed, recorded against the account, counted, and put in front of a person. That is deliberate, for the same reason booking the interest is a manual step, and it differs from failing loudly.

Coverage depends on the chain. On EVM and on Sui we read the balance at a point in time, which is a genuinely independent second source. On Solana we do not: we carry a balance forward from the transactions we ingested, so the chain-side number is derived from our own data, and a transfer we never ingested cannot be caught by comparing our book to a number computed from what we ingested. We’d rather call out the chain than hide behind the word “reconciled”.

Funds in transit are not tracked. Mid-bridge, your value has left the wallet and has not arrived, so we hold a placeholder and expect it back.

When we cannot read a position at all, we record it as unknown. We don’t quietly fall back to the number in our own book, because a reconciliation whose two sides become the same number can’t fail, and a check that can’t fail isn’t a check.

Every serious tool in this market will tell you it reconciles, and most of them mean something by it. The question is not do you reconcile. It is what are the two things you are comparing, and could both of them be wrong in the same direction at once?

A top-line attestation compares a total to a total. It cannot tell you a position got modelled as a token count instead of a debt, because both sides of that comparison carry the same mistake, and they will agree with each other all day long.

Two numbers that were wrong together aren’t a reconciliation. They’re a coincidence with a tick next to it.