DEV Community: Am0MuK

The First Bugs My Reconciliation Tool Caught Were Its Own

Am0MuK — Sun, 27 Sep 2026 10:35:32 +0000

I wrote a small open-source tool, onchain-tieout, to answer one question: does the balance you reconstruct from a wallet's transaction history match the balance the chain actually reports, at the same block?

That check exists because data pipelines fail silently. An explorer API returns HTTP 200 with an error inside the body, a page of results is capped without notice, a transaction that reverted still shows a non-zero value. Everything "succeeds", and the number is wrong.

The first implementation came from an AI coding agent working from my specification. The offline test suite was green. Then I pointed the tool at a real mainnet wallet, and the first things it found were bugs in itself.

1. The page size I specified was wrong, and every test agreed with me

Etherscan's documentation describes a 10,000-row result window, and I had written about that cap myself. So the client requested offset=10000 and treated any page shorter than that as the last one.

In reality, Etherscan V2 returned 1,000 rows per page, even when 10,000 were requested. The client saw 1,000 < 10,000, concluded it had reached the end of the history, and stopped. That is silent truncation, the failure class the tool exists to catch.

The tie-out itself caught it: the reconstructed ETH balance was far off the on-chain balance at the same block. The tool did its job on its own code.

The tests missed it because every offline test used a mocked API, and the mocks were written from the same wrong assumption as the code. A mock can only confirm what you already believe about the system behind it.

2. A single block with more than one page of rows

The standard way to paginate an explorer is by block: take the last block of a full page, drop its rows, and request again from that block, so the boundary block is fetched whole.

The real wallet had more than 1,000 token transfers in one block (a spam airdrop). A block-based cursor cannot move past a block that alone fills a whole page. The fix reads such a block on its own with page numbers, up to the API's 10,000-row window, and fails loudly beyond that instead of guessing. Before the fix, that wallet's balances came out wrong.

3. Rate limits reported as data

The next run marked about 9,700 tokens as "balance could not be read". That label is meant for spam or non-standard token contracts whose balanceOf call reverts.

Sampling the failures showed most of them were HTTP 429 responses from the RPC provider. The tool was turning "the provider is busy" into "this token is unreadable", a network problem reported as a fact about the data.

The fix separates the two. Transport problems (429, 5xx, timeouts) are retried with back-off and, if they persist, abort the run. Only a real revert or an empty result is reported as an unreadable balance.

4. Two bugs found by reading, not running

Reading the agent's code line by line turned up two more:

A response with status: "1" but a result that was not a list was silently turned into an empty history.
De-duplicating token transfers across page boundaries by a key without the log index could merge two genuinely identical transfers in the same transaction into one.

Both have the same shape as the bugs above: an ambiguous input turned into a plausible answer.

5. What "complete" looks like on a real wallet

With the fixes in place, the full run on that wallet (vitalik.eth) produced 10,476 balance rows. 8,281 tied out exactly. Almost all of the rest were airdropped spam: contracts that emit Transfer events inconsistent with their own balanceOf, many reusing real symbols such as USDC or WETH on other addresses. 175 of them had a history in which the wallet sent more than it ever received, impossible for a standard ERC-20, now labelled negative_history.

On the assets that matter, the result is clean. ETH, DAI, USDC and USDT tie out to the last unit. stETH differs because it rebases without transfers. The WETH difference equals the wallet's own deposit() minus withdraw() calls exactly, because WETH wraps emit no Transfer event.

One more silent failure turned up in the output formatting: Python's Decimal rounds to 28 significant digits by default, so very large spam amounts were printed rounded and tiny ones as 2.2E-7. Amounts are now formatted with integer arithmetic only.

What I took from it

Offline tests prove the code matches your assumptions. Only a run against the real system tests the assumptions. A reconciliation check is also worth running on the reconciliation tool itself: the first live tie-out failed for the right reason, and that failure was the most useful test result of the project.

"Could not read" and "does not exist" are different answers, and a tool that merges them will eventually report an outage as a fact about your data. When the input is ambiguous, fail loudly. Every bug here was an ambiguous case resolved into a plausible number.

Getting from the first live run to a clean tie-out took days. I would let an AI agent write the first version of a tool like this again.

The tool is open source (Python, MIT): github.com/Am0MuK/onchain-tieout

This describes software behavior, not tax or financial advice.

The Uniswap v4 tick that only breaks when it's negative

Am0MuK — Fri, 18 Sep 2026 16:58:19 +0000

A wallet's DeFi positions quietly disappeared from a report I generate. Not zeroed — absent. No error, no stack trace, no failed run. The pipeline said it finished successfully.

The cause was one line of tick decoding that is wrong only when the number is negative. Everything about how it hid is more interesting than the bug itself.

Two ways to read a tick

The code reads Uniswap v4 positions in two steps.

First, PositionManager.getPoolAndPositionInfo(tokenId) returns the pool key and a PositionInfo — a single 256-bit word with several fields bit-packed into it. From the least significant bit: 8 bits hasSubscriber, 24 bits tickLower, 24 bits tickUpper, 200 bits of truncated pool id.

To get a tick out of that word you shift, mask, and sign-extend by hand:

def _sign_extend_24(value: int) -> int:
    return value - (1 << 24) if value >= (1 << 23) else value

tick_lower = _sign_extend_24((position_info >> 8) & 0xFFFFFF)
tick_upper = _sign_extend_24((position_info >> 32) & 0xFFFFFF)

This is correct, and it matches what Uniswap's own library does:

_tickLower := signextend(2, shr(TICK_LOWER_OFFSET, info))

Second, StateView.getSlot0(poolId) returns the pool's current state. Its signature:

function getSlot0(PoolId poolId)
    external view
    returns (uint160 sqrtPriceX96, int24 tick, uint24 protocolFee, uint24 lpFee);

Four separate return values. And here I wrote this:

current_tick = _sign_extend_24(_parse_u256(_word(data, 1)))

Same helper, same idea, second word of the return data. It looks consistent with the packed decode three lines above it. It is wrong.

Why it's wrong

getSlot0 is an ordinary external function returning an ordinary tuple. The ABI encoder gives every return value its own 32-byte word, and for a signed type it sign-extends into the full word. By the time the bytes reach you, int24 tick = -100 is already two's complement across all 256 bits:

0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff9c

That is not a 24-bit field inside a larger word. It is a complete 256-bit signed integer, and the only correct way to read it is as one:

def _parse_i256(hex_word: str) -> int:
    value = _parse_u256(hex_word)
    return value - (1 << 256) if value >= (1 << 255) else value

Feed that same word to the 24-bit path instead and you get:

_parse_u256(word)              # 115792089237316195423570985008687907853269984665640564039457584007913129639836
_sign_extend_24(...)           # 115792089237316195423570985008687907853269984665640564039457584007913112862620
_parse_i256(word)              # -100   ← correct

_sign_extend_24 checks whether bit 23 is set. In a fully sign-extended negative number every high bit is set, so the check passes, it subtracts 2²⁴, and returns a number that is still astronomically large. The guard fires and accomplishes nothing.

Why it stayed hidden

Positive ticks are unaffected. int24 tick = 12345 ABI-encodes to a word with leading zeros — indistinguishable from an unsigned 24-bit field. _sign_extend_24 sees bit 23 clear, returns the value untouched, and everything downstream is correct.

So the bug is invisible in exactly the situation you test first: a pool whose price sits above the 1:1 raw ratio.

Negative ticks are not an edge case. A tick is log₁.₀₀₀₁(price) where price is currency1 per currency0 in raw base units, and decimals are part of that ratio. In any v4 pool paired with native ETH, ETH is currency0 — address(0) sorts below every token. Pair it with USDC:

1 ETH ≈ 3000 USDC
raw ratio = 3000 × 10⁶ / 10¹⁸ = 3 × 10⁻⁹
tick = ln(3 × 10⁻⁹) / ln(1.0001) ≈ -196,000

Every ETH/stablecoin pool in v4 sits at a deeply negative tick, permanently. Not a boundary condition — the common case.

Why nothing reported it

The corrupted tick goes into a price calculation:

def _sqrt_price_at_tick(tick: int) -> float:
    return 1.0001 ** (tick / 2)

With a tick around 1.16 × 10⁷⁷ that raises OverflowError. Which would be a fine, loud failure — except the enrichment calls were wrapped like this:

try:
    snapshot.uniswap_v3_positions = get_uniswap_v3_positions(...)
    snapshot.uniswap_v4_positions = get_uniswap_v4_positions(...)
    snapshot.morpho_positions     = get_morpho_positions(...)
    snapshot.compound_v3_positions = get_compound_v3_positions(...)
    snapshot.euler_positions      = get_euler_positions(...)
    snapshot.pendle_positions     = get_pendle_positions(...)
    snapshot.curve_positions      = get_curve_positions(...)
except Exception as e:
    logger.info(f"Position enrichment failed (non-fatal): {e}")

One except around seven protocols, logged at info. A single negative tick in one Uniswap pool therefore removed the wallet's Morpho, Compound, Euler, Pendle and Curve positions from the report as well — because they are simply the lines that never ran. The log line that would have explained it sits below the level anyone filters for in production.

Three failures stacked: a decode that is wrong only for negative numbers, a sign asymmetry that hides it during testing, and an exception handler broad enough to turn it into silence.

The rule

Two decodings, one file, opposite handling — and the difference is not the type, it's the path the value took to reach you:

Source	What you receive	How to decode
A return value of an external function	Already sign-extended to 32 bytes by the ABI encoder	Read the whole word as signed
A field inside a manually packed word	A raw bit range, no sign extension	Mask, then sign-extend by width

Uniswap's own library shows both. PositionInfoLibrary calls signextend(2, ...) because it is pulling bits out of storage it packed itself. getSlot0 doesn't, because returning int24 through the ABI already did it.

The fix was one line:

current_tick = _parse_i256(_word(data, 1))

which is what the v3 path in the same file had been doing correctly all along, a few hundred lines up.

Two changes worth making beyond the fix: raise that logger.info to warning, and treat "a whole class of positions vanished from output" as a condition worth asserting on, not something to discover by reading a report and noticing an absence.

Written from a real bug in a multi-chain DeFi tax engine I maintain. References: StateView, PositionInfoLibrary.

Five Ways DeFi Tax Software Silently Produces Wrong Numbers

Am0MuK — Wed, 16 Sep 2026 18:36:26 +0000

Anyone who reconciles DeFi portfolios for tax purposes knows the pattern: a tool pulls the wallet history, applies FIFO, spits out a number. The number looks plausible. It gets filed.

The problem is rarely the calculation logic. FIFO is FIFO. The problem sits one layer down — in whether the engine actually saw every relevant transaction before it started calculating. And that's exactly where systems fail silently: no error, no crash, just an incomplete number wearing the same confident formatting as a complete one.

We ran our own engine against real multi-chain wallets for months and found (and fixed) five structural failure classes. Below are five concrete failure modes, with the technical mechanisms behind them — not because they're quirks of our implementation, but because they can affect any engine that relies on the same underlying data sources and assumptions.

1. Provider rate tiers that refuse entire chains — with HTTP 200

Explorer APIs (Etherscan V2 and compatible endpoints on other chains) respond to low-tier requests on certain chains not with an error, but with a success-shaped status message: status: "0", message "Free API access is not supported for this chain". No HTTP error code, no exception — a formally valid response with no content.

An engine that doesn't check the status field inside the body logs this as "no transactions on this chain." On a multi-chain portfolio, that means an entire chain silently disappears from the tax report. (Confirmed live, including on Base.)

A related second case: the same APIs cap result sets (typically 10,000 rows per query). Without active pagination via startblock, you get the first 10,000 entries and treat them as the full history.

2. Internal transfers that simply aren't available on most chains

Native internal transfers (contract-to-contract, triggered by a smart contract call rather than an external transaction) aren't an edge case for DeFi users — bridges, liquidations, and wrapper repayments run through them.

On Alchemy, the internal category in alchemy_getAssetTransfers is only queryable on a subset of chains. On the rest, the request doesn't partially degrade — it fails completely with a -32602 RPC error, taking every other requested category down with it. An engine has to know, per chain, whether it's even allowed to ask for that category.

The honest consequence is uncomfortable: on chains where the provider doesn't support the category, internal transfers via this path are not collectible. That's not a bug you code away — it's a data gap you either close with a second source or declare openly in the report. What you can't do is silently log it as "no internal transfers found."

3. WETH unwraps that emit no transfer event

WETH9.withdraw(uint256) burns the WETH balance and sends native ETH 1:1 — but only emits a Withdrawal log, never a standard ERC-20 Transfer event.

Every common indexer (Etherscan's tokentx, Alchemy's erc20 category) is built on transfer logs. The WETH leg of the operation simply doesn't exist for them. What lands in the journal is only the native ETH side flowing back.

The result is inventory drift in both directions: ETH appears from nowhere, while the corresponding WETH position never gets drawn down. Without an active reconciliation between computed and actual on-chain balance, this doesn't surface — the report stays internally consistent and is still wrong.

4. Phantom transfers from failed transactions

Explorer APIs' transaction lists include transactions that reverted on-chain — with a non-zero value field. The transaction was sent, burned gas, but the state change never happened.

Skip checking isError / txreceipt_status separately, and you book an asset movement that never occurred. Depending on where this phantom entry lands in the FIFO stack, it shifts acquisition order, holding periods, and therefore tax liability — in either direction.

(The gas fee actually spent is real, by the way, and stays correctly recorded — only the transfer itself isn't.)

5. The same method selector meaning a different asset on every chain

DeFi protocols get recognized by method selectors (the first 4 bytes of calldata). Aave's WrappedTokenGateway uses the exact same depositETH selector for native-gas-token deposits on every chain — including chains where the native token isn't ETH at all.

On Sonic, that identical selector fires for a native S deposit. An engine that infers the asset from the selector's name books WETH instead of WS: wrong asset, wrong price, wrong cost basis — while correctly recognizing the transaction type.

The fix requires deriving the actual token that moved from the transaction's balance changes, instead of guessing it from the selector name.

What these five have in common

None of them throws an error. Each produces a number that looks like a complete calculation — cleanly formatted, decimal places included, ready to file. The difference between a correct and a silently incomplete tax calculation isn't visible from outside without active cross-checking.

That's why we built our engine to report its own incompleteness instead of hiding it: an automatic tie-out between on-chain balance and computed inventory after every run, a completeness statement listing which chains were covered with which data source and coverage level, and a hard rule that an unresolvable transaction gets flagged, never silently dropped.

The question worth asking any DeFi tax tool isn't "does it calculate FIFO correctly?" — most do. It's:

"What does it do when it can't fully attribute a transaction — does it show you, or does it hide it?"

This describes software behavior, not tax advice.