polycratia

Fee-on-transfer tokens: the only honest number is the balance

· 9 min read

A token transfer can deliver less than it was asked to deliver, and nothing in the transaction says so. The amount sitting in the call data is the amount I asked for, the return value only tells you the call did not revert, and a token that deducts on the way through writes that deduction in neither place. So a payout pipeline that credits the number it requested is crediting a number the chain never agreed to.

The fix is not clever: read the recipient's balance before the transfer and again after it, then treat the difference as the only number worth writing down. What makes it worth writing down is what the measurement refuses to do, and that is most of this post. The code comes from erc20-transfers (https://github.com/polycratia/erc20-transfers), a package I maintain for the parts of the ERC-20 surface that actually bite.

The two places the fee is not#

Call data first. A transfer is a four-byte selector and two words, and there is no room in it for the token to answer back:

python
from erc20_transfers import encode_transfer

data = encode_transfer(to=bob, amount=1_500_000)

That 1,500,000 is an input. It is what the sender wants moved. A token whose implementation credits the recipient with less and keeps the rest accepts exactly this call data, unchanged, and the bytes on chain afterwards still say 1,500,000. The call data is a request, and I have watched people read it back out of a block explorer as if it were a settlement record.

Then the return value, which is where the optimism usually creeps in. The standard says transfer returns a bool. The tokens that predate the finalised standard, USDT among them, return nothing at all and revert on failure instead. So the package reads the return data defensively rather than coercing it:

python
def read_transfer_return(data: bytes) -> TransferReturn:
    raw = bytes(data)
    if not raw:
        return TransferReturn(data=b"", value=None)
    if len(raw) != WORD_SIZE:
        raise NonBooleanReturn(...)  # not a word and not empty

    word = int.from_bytes(raw, "big")
    if word > 1:
        raise NonBooleanReturn(...)  # not a boolean either

    return TransferReturn(data=raw, value=word == 1)

Even at its most cooperative, that boolean carries one bit: the call did not revert. Empty data and True mean the same thing here, and neither of them is a quantity. Anything that is neither empty nor a boolean word gets refused rather than read as truthy, because a token returning something else is not described by the interface it claims to implement, and guessing at what it meant is how a fee turns into a rounding error in someone's ledger.

So: the amount is mine, the boolean is binary, and the fee is in neither.

Two reads, one receipt#

Since the token will not say, the recipient's balance has to. Two balanceOf reads around the transfer, and the difference between them is what arrived:

python
from erc20_transfers import (
    decode_uint256,
    encode_balance_of,
    encode_transfer,
    measure_received,
)

def pay(token, recipient, amount):
    before = decode_uint256(eth_call(token, encode_balance_of(account=recipient)))
    send(token, encode_transfer(to=recipient, amount=amount))
    after = decode_uint256(eth_call(token, encode_balance_of(account=recipient)))

    return measure_received(sent=amount, balance_before=before, balance_after=after)

You want those two reads pinned to blocks rather than taken whenever the node feels like answering: the block before the transfer landed, and the block it landed in. A read taken a few blocks late on a busy recipient address is measuring the recipient's week, not this transfer.

What comes back is a TransferReceipt, which is two integers plus the arithmetic that would otherwise be scattered across three services:

python
@property
def fee(self) -> int:
    return self.sent - self.received

@property
def has_fee(self) -> bool:
    return self.received < self.sent

@property
def fee_bps(self) -> Decimal:
    if self.sent == 0:
        return Decimal(0)

    return Decimal(self.fee * _BPS_PER_UNIT) / Decimal(self.sent)

_BPS_PER_UNIT is 10_000, and the share is a Decimal rather than a float because a fee expressed in basis points is going to end up next to money. The zero branch is there because a zero-value transfer is a legitimate thing to send and dividing by it is not.

The receipt says what happened in one sentence:

python
receipt = pay(token, bob, 1_500_000)

print(receipt.explain())
# 1485000 of 1500000 units arrived; the token kept 15000 (100.00 bps), so
# anything downstream that was promised 1500000 is short

and for a well-behaved token, all 1500000 units arrived; this token takes no fee.

Measuring is not the same as deciding, so the raise is a separate call:

python
receipt.raise_for_fee()  # FeeOnTransfer, carrying the receipt

FeeOnTransfer is a RuntimeError that keeps the receipt on the exception, so the handler gets the numbers and not just a message. Whether 100 bps is a problem depends on what the transfer was for. Routing through a pool, it is a cost of doing business. Paying out against an invoice that names a figure, it is a breach, and the right move is to fail the payout loudly rather than book the shortfall as drift.

The two readings it refuses#

A fee measured from the wrong pair of reads is worse than no measurement at all, because it looks like a fact. Two pairs get rejected outright.

A balance that fell is not a pair of reads around an incoming transfer:

python
measure_received(sent=1_500_000, balance_before=10, balance_after=5)
# ValueError: the recipient balance fell from 10 to 5 across a transfer in;
# the two reads are not around the same transfer

Something else moved tokens out between the reads, or the reads were taken against the wrong account or the wrong blocks. Either way the subtraction would go negative, and the only sane answer is to refuse rather than clamp to zero and report a 100% fee.

A balance that grew by more than was sent is refused in TransferReceipt.__post_init__:

python
measure_received(sent=1_000, balance_before=0, balance_after=1_500)
# ValueError: 1500 arrived out of 1000 sent; a balance that grew by more than
# the transfer means a rebase or a second transfer landed in between, so this
# measurement says nothing

That one is the interesting refusal. A rebasing token moves every holder's balance on its own schedule, and a second transfer landing in the same window is ordinary on a hot recipient address. Both produce a difference that is arithmetically fine and semantically meaningless. Returning a negative fee, or quietly reporting "no fee", would hide the fact that the measurement window was not clean.

Underneath, every input goes through the same _uint256 check: a bool or a non-int raises TypeError, a negative value or one above UINT256_MAX raises ValueError. The bool rejection earns its place in Python specifically, since True is an int, and a balance_after=True slipping out of a truthy helper would otherwise measure as one unit arriving.

Units are not money yet#

The receipt counts in the token's smallest unit, which is the only scale the chain knows. A fee of 15000 units is 0.015 on a six-decimal token and 0.000000000000015 on an eighteen-decimal one, so the number is not fit to show anyone until the token has said how to read it:

python
from erc20_transfers import decode_decimals, encode_decimals, from_units

decimals = decode_decimals(eth_call(token, encode_decimals()))
print(from_units(receipt.fee, decimals=decimals))

Nothing in the package has a default for decimals, and TokenAmount exists so an on-chain integer can travel with the scale it was read at. A fee-on-transfer bug and a decimals bug compound in the same direction: both produce a payout that is confidently wrong and already final.

Why grossing up is left out#

The obvious next feature is "send enough extra that the net comes out exact", and the package does not offer it. Inverting a fee schedule nobody published is guesswork. The rate is whatever the contract's owner last set it to, and it can change between the block I measured and the block my transaction lands in. Some tokens deduct on receive, some on send, some exempt particular addresses, and none of them are obliged to tell me which. And a grossed-up transfer still has to be measured afterwards, so the inversion buys nothing except a second number to be wrong about.

Measure, report, raise. If the exact net matters, the thing to adjust is the agreement with the counterparty, not the arithmetic.

What I would do differently#

On earlier payout work I credited the requested amount at the moment of broadcast and let reconciliation catch any difference later. That holds up until a token with a transfer fee enters the asset list, and then it fails in the worst shape available: small per-transfer gaps that pile up quietly in an account nobody watches, surfacing as an unexplained reconciliation delta long after the transactions are irreversible.

What I do now is narrower. The ledger entry takes received, never sent. The difference, when there is one, gets written as an explicit fee line with its basis points next to it, so it is a recorded fact rather than a discrepancy somebody has to explain later. And I do not keep a fee_on_transfer boolean per token in a config table, because that table is a snapshot of what was true when somebody last looked, and the behaviour it describes is controlled by someone else's contract. Two balanceOf reads cost almost nothing next to a transfer. Paying for them every time is cheaper than being wrong once.

The general habit this is a special case of: read what the chain says, and do not stand in for it with a constant. The amount in my call data is a constant I chose. The balance is what happened.

react

$ new-project --brief

or email hey@polycratia.com