Building a reconciliation job against an EVM chain

What the job has to guarantee

Three properties, in this order: it never double-counts, it never silently skips, and it can be re-run over any window without changing the result. Everything below is in service of those, and a job that has not been tested by re-running it over a window it has already processed does not have the third.

Reading events safely

Read to a confirmation depth, never to head. The depth comes from the finality analysis done at chain selection, not from a constant someone picked. Record the block you have processed to, and treat the gap between that block and head as normal rather than as lag to be minimised.

Idempotency at the write

INSERT INTO ledger_postings (event_key, account, amount, block)
VALUES ($1, $2, $3, $4)
ON CONFLICT (event_key) DO NOTHING;
-- event_key = txHash:logIndex. Stable across a re-run,
-- and stable across a reorg that reinstates the same log.

The event key must be derived from the chain’s own identifiers rather than from a sequence the job maintains, because the job will be restarted and the sequence will not survive it.

Handling a reorg

Below the confirmation depth a reorg is invisible to the job, which is the point of the depth. Above it, a reorg is an incident, not an edge case: the job stops, raises, and waits for a person. Automatic unwinding of postings that an accounting system has already consumed is a class of bug that is discovered at audit, and the correct behaviour is to stop.

Raising a break

• Compare at a fixed pointThe close is taken at a stated block and a stated timestamp on the off-chain side. Comparing moving targets produces breaks that resolve themselves and train the team to ignore them.
• Apply the toleranceDifferences inside the agreed tolerance are logged, not raised. The tolerance is finance’s number.
• Raise with the evidence attachedBlock, timestamp, both balances, and the last ten postings on each side. A break that arrives without evidence becomes a two-day investigation.