DEV Community: polycratia

under_investigation is a status, not an excuse

polycratia — Tue, 08 Sep 2026 13:21:26 +0000

A scanner tells you a component in your build carries a known advisory. It cannot tell you whether the vulnerable code is reachable in your product, and that judgement is the entire content of a VEX document. So the interesting design question is not how to express affected or not_affected. It is what your tooling does with the findings nobody has judged yet. The common answer, defaulting them to not_affected because the release is on Friday, turns a triage backlog into a signed assurance.

I build payments and crypto backends, so I ship services whose dependency lists are long, boring, and audited by people who did not write them. The Cyber Resilience Act expects manufacturers to answer the reachability question quickly and in writing for every product they ship, which is a schedule problem before it is a security problem. Schedule problems are where defaults do their damage: nobody decides to publish a false claim, they decide not to block the release, and the default publishes the claim for them.

What the default actually asserts

not_affected is a claim about your code. It says: I looked, and the vulnerable path is not in the execute path, or the component is not present, or the adversary cannot control the input. under_investigation is a claim about your process. It says: this is in the queue and it has not been answered.

Both are publishable. Only one of them can be falsified by an attacker with a weekend and a debugger, and it is not the honest one.

The consequence shows up in the shape of the document rather than in any single statement. If unreviewed findings default to not_affected, the number of not_affected statements stops tracking how much review happened and starts tracking how big your SBOM is. A downstream reader (a customer's security team, an auditor, the person who inherits the service) cannot tell eighty components somebody worked through from eighty components nobody opened. That distinction is the only reason the document exists.

The other failure mode is quieter: dropping undecided findings entirely, so they simply do not appear. Absence is worse than an honest status, because absence is ambiguous. Did the matcher not find this advisory, or did it find it and get ignored?

Three kinds of unknown, each with a reason attached

When I wrote vexdesk, the rule I started from was that nothing which cannot be determined gets quietly cleared. In practice "cannot be determined" is not one thing, and the reasons are not interchangeable:

$ vexdesk match -sbom sbom.cyclonedx.json -advisories ./advisories
4 component(s) compared against the advisory set

STATUS    ADVISORY      COMPONENT        VERSION  REASON
affected  FIXTURE-0001  widget           1.2.3    version falls inside the advisory's affected range
affected  FIXTURE-0004  cogwheel         4.0.0    version is in the advisory's affected version list
unknown   FIXTURE-0003  Example_Fixture  3.1.2    ECOSYSTEM range for PyPI needs that ecosystem's own version ordering, which is not implemented

Not checked (1):
  vendored-blob  no package URL: nothing to look up

Three different human actions hide behind those lines. A component with no package URL cannot be looked up in any advisory database, so somebody has to identify that vendored blob by hand, and no amount of tooling will do it for them. A PyPI ECOSYSTEM range needs PEP 440 ordering, which the tool does not implement; that is a gap in my matcher, not a property of your product, and the right response is to compare the version manually or fix the matcher. An affected line is a reachability question for whoever owns that code path.

The reason string is the payload here, not the status. An unknown with no reason is indistinguishable from a bug in the tool, and a status a reviewer cannot interrogate is a status they will either rubber-stamp or ignore. The same rule shapes version parsing: 2023-08-01 is not read as major version 2023, it is refused. A date that silently outranks every real version produces a confident wrong answer, which is the most expensive output a matcher can produce, worse than no answer, because it terminates the conversation.

The absence of a decision is itself a statement

Decisions live in a file, separate from the matcher, because they are human output and the match is machine output:

{
  "decisions": [
    {
      "vulnerability": "FIXTURE-0001",
      "product": "pkg:golang/github.com/example/widget@v1.2.3",
      "status": "not_affected",
      "justification": "vulnerable_code_not_in_execute_path",
      "impact_statement": "the affected parser is only reached from the admin importer, which this build does not include"
    }
  ]
}

The part that matters is what happens to the findings this file does not mention. They are not dropped and they are not cleared: they are emitted as under_investigation. The undecided finding survives into the published document as an undecided finding, and the document stays a rendering of the triage queue rather than a summary of the parts of it somebody got around to.

This also removes the incentive that produces bad not_affected statements. not_affected requires one of the five OpenVEX justification codes (component_not_present, vulnerable_code_not_present, vulnerable_code_not_in_execute_path, vulnerable_code_cannot_be_controlled_by_adversary, inline_mitigations_already_exist) and the document refuses to build without one. affected requires an action statement: what should the user do. under_investigation requires nothing, because there is nothing to say yet.

That asymmetry is deliberate. If the only way to make the build pass were to write a justification, engineers under deadline would pick the code that sounds closest to true, and a reviewer six months later would have no way to tell a considered vulnerable_code_not_in_execute_path from a guessed one. Leaving one status available at zero prose cost means the pressure valve is honesty rather than a plausible code.

A status that survives review carries its why

A VEX statement is read by someone who was not in the room. That reader has exactly two questions: what did you conclude, and on what basis. The justification code answers the second in a form they can compare against every other statement you have made, which is the whole reason to require a code alongside the prose rather than prose alone. Free text is unanswerable at scale. A code is sortable.

The same logic applies to the document as an artefact. In vexdesk the document id is derived from the statements, so an unchanged set of decisions rebuilds to the same id instead of looking newly issued on every CI run. That sounds cosmetic until you try to review a burn-down. If the id churns on every build, no consumer can tell a re-publish from a re-decision, and a finding flipping from under_investigation to not_affected, the single most important event in this whole workflow, disappears into noise. Document comparison lives in its own package in that repository for the same reason: the interesting object is the delta between two documents, not either document alone.

And because match exits 1 when anything needs attention, the backlog can gate a pipeline rather than sit in a wiki:

#!/usr/bin/env bash
set -euo pipefail

vexdesk match -sbom sbom.cyclonedx.json -advisories ./advisories || echo "findings need review"

vexdesk vex -sbom sbom.cyclonedx.json -advisories ./advisories \
            -decisions decisions.json -author "Example Ltd" -o vex.json

Note the shape: the match result informs, the document still builds. A gate that refuses to produce a VEX document until every finding is resolved gets disabled in a week. A gate that publishes the truth, including the unresolved parts, survives contact with a release schedule, which is probably the only property that matters, because a control nobody can ship past is a control nobody keeps.

What I would do differently

under_investigation has a half-life. It is honest on the day you publish it and it is an indictment three months later, and nothing in the document as it stands expresses that difference. A statement carries what you concluded, not when you first saw the finding, so a stale queue and a fresh one look identical to a reader.

If I were extending this, that is where I would go next: record when a finding first appeared undecided, and let the age of an under_investigation statement be visible to the person reading it. Not as a gate, since an aging finding is not automatically a problem and plenty of them are waiting on an upstream fix, but as the thing a reviewer should look at first. That is not built, and I would rather say so than describe it as though it were.

The rest of the design I would keep unchanged. A tool that refuses to answer a question it cannot answer is more useful than one that answers everything, because the second kind trains you to stop reading its output. under_investigation is not the tool admitting defeat. It is the one status in the vocabulary that is always available and never a lie, and a document that uses it freely is a document a reviewer can actually work with.

Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.

The ERC-20 that returns nothing still moved your money

polycratia — Mon, 07 Sep 2026 13:22:59 +0000

Three behaviours in deployed token contracts break integrations that trust the return value of a transfer: contracts that return no data at all, contracts that refuse to raise an allowance that is not currently zero, and contracts that credit the receiver with less than the amount you passed. All three succeed on chain. All three leave your ledger wrong, because the thing you checked was the call and the thing that mattered was the balance.

I have run stablecoin rails in daily production since 2018, and every incident I have had in that area came from the same shape of mistake: some layer of the stack decided that a function signature in a standard was a description of what is actually deployed. It is not. The standard describes what a token should do. The chain holds what somebody compiled years ago and can never change.

The return value is a claim about the call, not about the money

ERC-20 says transfer and transferFrom return a bool. Plenty of widely used contracts (including the largest stablecoin by circulation) were written before that convention hardened, and they return nothing. The function body executes, the state changes, and the call returns zero bytes of data.

That is where naive client code fails, and it fails in the worst direction. A decoder that expects 32 bytes and gets zero either raises, or reads whatever the ABI layer decides to hand back for an empty buffer. So a transfer that actually moved money surfaces as an exception, or as False. The retry logic sees a failure, sends the transfer again, and now the money has moved twice.

In erc20-transfers I keep the decode step separate from the call for exactly this reason:

from erc20_transfers import (
    decode_transfer_result,
    decode_uint256,
    encode_balance_of,
    encode_transfer,
)

data = encode_transfer(to=bob, amount=1_500_000)
ok = decode_transfer_result(eth_call(token, data))

decode_transfer_result exists because "the token said True", "the token said nothing", and "the token reverted" are three different outcomes, and only the third one means the transfer will not work. Collapsing the first two into a single boolean is the whole bug.

There is a second trap stacked on top of it, and it is the one I see most often in code review. eth_call, or .call() in web3.py, is a simulation. It runs the function against a local copy of state and returns what it would have returned. Nothing is signed, nothing reaches a mempool, no receipt is produced. A True out of .call() on transferFrom means "this would work", not "the tokens moved". Moving tokens needs a signed transaction and eth_sendRawTransaction. I have seen a service log a successful payout from a simulated call and mark an order as settled while the balance never changed.

Measure the effect, not the call

If the return value cannot be trusted and the simulation is not the transfer, the only ground truth is what balanceOf says before and after the transaction was mined. That is the rule the library is built on: check the effect on balances rather than trusting the call to revert.

receipt = send_and_wait(signed_tx)

before = decode_uint256(
    eth_call(token, encode_balance_of(account=treasury), block=receipt.block_number - 1)
)
after = decode_uint256(
    eth_call(token, encode_balance_of(account=treasury), block=receipt.block_number)
)

credited = after - before

The block pinning is not decoration. If you read "before" against latest, send, and read "after" against latest, any other transfer touching that address between the two reads lands inside your delta. For a hot treasury address that is not an edge case, it is Tuesday. Pinning both reads to the receipt block and its parent makes the delta a property of one transaction instead of a property of how busy you were. For a shared address it is still an approximation over everything in that block that touched it. If you need it exact, the account has to be exclusive to the flow, which is one more argument for per-purpose deposit addresses.

The fee case falls straight out of this. Some contracts deduct a fee from the transferred amount, so the receiver is credited less than the sender was debited. At least one heavily used stablecoin carries a fee rate in storage that currently happens to be zero: a value somebody can change, not a property of the compiled code. If your ledger credits the amount you passed in, you have written down a number the chain never agreed to, and it will drift away from the balance quietly until somebody reconciles by hand. Credit the measured delta. Debit the requested amount. If they differ, that difference is a real cost and belongs in the ledger as one, not as an unexplained gap.

The allowance is read, not assumed

transferFrom moves someone else's tokens and only works while that someone has approved the spender for at least the amount being moved. Short allowance means revert, and a revert from a simulated call is easy to misread as a transient node problem. So the allowance is read first and reported with the numbers in it, before any call data is built:

from erc20_transfers import check_allowance, decode_uint256, encode_allowance

allowance = decode_uint256(eth_call(token, encode_allowance(owner=alice, spender=bob)))
check = check_allowance(owner=alice, spender=bob, required=1_500_000, current=allowance)

if not check.sufficient:
    print(check.explain())
    # 0x2222...2222 holds an allowance of 400000 from 0x1111...1111, but
    # transferFrom of 1500000 needs 1100000 more; the call reverts until the
    # owner approves at least 1500000

That sentence is why the module exists. "Execution reverted" tells an operator nothing at three in the morning. The shortfall, the owner, the spender and the amount that needs approving tell them what to do next.

The non-standard twist here is the reset requirement. Some contracts reject an approve that raises a non-zero allowance to a different non-zero value, and the original reasoning was to close a front-running window between the old and new limits. To raise such an allowance you must first set it to zero, then set the new value. That is two transactions and two nonces, and the state in between is a real state your process can die in: allowance zero, nothing approved, and a queue of payouts that all revert.

So the top-up is a small state machine, not a function call. Whatever encodes your approve, the discipline around it is the same three rules. Re-read the allowance from the chain before every attempt instead of assuming your last approve landed. Treat "currently zero" as a resumable position rather than an error. And do not build transferFrom call data from a remembered number: encode_checked_transfer_from refuses to produce call data when the allowance it was handed does not cover the amount, which turns a future revert into an immediate, explainable failure.

Decimals belong to the token too

While I am refusing to assume things about contracts, the number of decimals is one of them. USDT and USDC use 6, DAI and most others 18, WBTC 8. Assuming 18 against a 6-decimal token inflates a payout by a factor of a million. Read it and pass it explicitly:

from decimal import Decimal

from erc20_transfers import decode_decimals, encode_decimals, to_units

decimals = decode_decimals(eth_call(token, encode_decimals()))
amount = to_units(Decimal("1.5"), decimals=decimals)  # 1500000 on USDT

Conversion is exact by construction: amounts are Decimal, floats are refused, and a value with more precision than the token can hold raises instead of silently dropping the digit. A rounding mode you did not choose is a rounding mode you will eventually have to explain to somebody counting their money.

What I would do differently

For a long time I handled this with a quirks table: a per-token map of "returns no bool", "needs zero reset", "takes a fee". It works right up until a token you have not classified shows up, or a contract with an upgradeable proxy changes behaviour underneath your entry. The table is a cache of the chain's state maintained by hand, and it goes stale the way every hand-maintained cache does.

What I would build from the start now is the inverse: assume every token is non-standard, and let measurement be the normal path rather than the fallback. Decode the return value if there is one, and treat its absence as an absence rather than as a denial. Take the credited amount from the balance delta at the receipt block for every transfer, not just for the ones flagged as fee-taking. Read decimals and the allowance from the chain each time, cheaply, rather than remembering them. A well-behaved token costs you two extra eth_calls under that regime. A badly behaved one costs you nothing extra at all, because it is being handled by the same code as everything else.

The library is at github.com/polycratia/erc20-transfers. It is pre-alpha and the public API is not stable yet, but the shape of the argument is stable: on chain the return value is a claim, and the balance is the evidence.

Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.

A withdrawal is a queue entry before it is a transfer

polycratia — Sun, 06 Sep 2026 13:20:20 +0000

Most withdrawal code collapses two different events into one function call: the user asking for money to leave, and the money actually leaving. Once those are the same operation, everything you might reasonably want to do in between — hold the request for review, batch it with others going to the same chain, re-price it when the fee market moves, cancel it because the destination has a typo in it — has nowhere to live. The fix is not a smarter send function. It is to make the request its own record with an explicit state machine, and to demote the broadcast to one transition inside it.

The shape that causes this

The version I keep finding in custodial systems is a single handler. It validates the destination, debits the user's balance, calls the node, stores the transaction hash on the user's withdrawal row, and returns. It reads fine. It is short. It has no safe moments in it at all.

The first thing you lose is cancellation. There is no interval during which the operation exists but the money has not moved, so "cancel" is either impossible or it is a support ticket that ends with a manual transfer back. The second thing you lose is batching: to batch you need a population of pending requests, and in this design a request is never pending — it is either absent or already broadcast. The third thing you lose is pricing control. The fee gets decided at the instant a user pressed a button, by whoever happened to press it, rather than at the instant you were ready to send.

The fourth loss is the one that hurts during an incident. When the node call times out, you have no idea what happened, and the only place to look is the chain. So you write a reconciler that reads the mempool and tries to infer your own intent from someone else's data structure. You are asking the network what you decided.

Every transition is a decision someone can make

The alternative is boring in the best way. A withdrawal is a record with a state, and the states are named after the decisions that produce them. In withdrawals the path is requested -> approved -> sending -> sent -> confirmed, with rejected and failed as the two ways out.

from decimal import Decimal

from withdrawals import WithdrawalRequest, WithdrawalState

request = WithdrawalRequest(
    id="w-1041",
    amount=Decimal("25.00"),
    currency="USDC",
    destination="0x5c69bee701ef814a2b6a3edd4b1652cb9cc5aa6f",
)

approved = request.approve()
sending = approved.start_sending()
sent = sending.mark_sent("0xdeadbeef")
confirmed = sent.confirm()

assert confirmed.state is WithdrawalState.CONFIRMED
assert confirmed.is_terminal

Four calls, four values. That is the entire point: there are now four moments where the request exists and something can be done to it, instead of one moment where it either worked or did not.

Two details in that snippet matter more than they look. A request is an immutable value — a transition returns a new request and the caller decides where to store it. That keeps the state machine out of your persistence layer, and it means the natural way to store a withdrawal is one row per version, appended, rather than one row mutated in place until the history is gone. When someone asks in three months why a payout went out at that fee, the answer is a sequence of rows, not a guess.

The other detail is rejected. It is reachable only while the money has not moved. That restriction is the state machine's real content. It draws a line through the lifecycle: on one side the operation is a piece of data you own and can freely change your mind about, on the other it is an event on a network that does not care what you decided afterwards. A state machine that lets you reject a broadcast withdrawal is not modelling a withdrawal, it is modelling a wish.

The cancellable prefix is where the policy lives

Once the prefix exists, things that were architecture problems become ordinary queries.

def ready_to_send(requests):
    return [r for r in requests if r.state is WithdrawalState.APPROVED]

That is a population. Batching is a grouping over it. Fee estimation is a function of it, evaluated at the moment you are actually about to sign rather than at the moment of the request. A four-eyes approval rule is a guard on one transition instead of a feature bolted across a handler. A daily limit is a predicate over requests in the prefix plus requests already past it — and, importantly, both are visible, because a request that has not been sent yet is still a real object with an amount on it.

Routing belongs here too. A withdrawal whose destination is an address you also custody does not need a chain at all; it is an internal transfer between two accounts you control, and paying a network fee to move it is a donation. But you can only make that choice while nothing has been broadcast. In a design where the request is the transfer, the routing decision has already been made for you by the shape of the code — badly, and always in the expensive direction.

The repository is honest about where it stands: the request and its state machine are in place, the routing and the senders are not. That ordering is deliberate. The senders are the part everyone writes first and the part that is least interesting, because a sender is just an adapter over a node. The state machine is what decides whether a sender is even reachable, and whether you have anywhere to stand when you need to stop sending.

Idempotency becomes a property of the value

Callbacks arrive twice. Node RPCs time out after the node did the work. Any queue you put in front of the sender is at-least-once, and if it claims otherwise it is lying about a network partition it has not met yet. So the interesting question is not how to avoid duplicate delivery but what a duplicate does when it lands.

assert sent.mark_sent("0xdeadbeef") is sent

Replaying a transition that already happened with the same data returns the same value. The second callback costs nothing, and the handler that processes it does not need to know it was second. That is worth more than a dedup table, because a dedup table has a window and a window is a bet about how late a retry can be.

The conflicting case is the one worth being loud about:

from withdrawals import InvalidTransition

try:
    sent.mark_sent("0xfeedface")
except InvalidTransition:
    # two hashes for one request: a double broadcast or a replacement
    # we did not record. This is an incident, not a race to smooth over.
    raise

A replay carrying different data is a conflict, not a silent overwrite. If you let the last writer win, you have quietly decided that a second transaction hash for the same request is a normal event, and you will find out otherwise during reconciliation, at the worst possible moment, with the chain as your only witness. The same rule covers any step the machine does not allow: confirming something that was never sent is not a slightly out-of-order message, it is a bug in whatever produced it.

What I would do differently

I have built custodial wallets and an on-chain payment system, and stablecoin rails that run daily, and I have got this wrong in a couple of directions before settling here.

I would persist every version rather than the latest state. The immutable value makes this nearly free, and it converts "why did this go out twice" from forensics into a select.

I would decide the fee at the sending transition and never at request time. The gap between those two moments is exactly the window the request was created to give you.

I would reserve the user's balance when the request is created, not when it is broadcast. A queue that does not reserve lets the same balance be spent twice while it waits, and the second spend will look perfectly valid to every check you have.

And I would keep the terminal set explicit — is_terminal rather than a set of state names copied into three different retry loops. Reapers, retries and alerting all need the same answer to "is this still ours to touch", and they should get it from the same place.

Close

A withdrawal is a queue entry that sometimes becomes a transfer. The broadcast is the shortest and least controllable step in it, and it is the only step most implementations model. Give the request a record and a state machine, and cancellation, batching, routing and pricing stop being features you have to retrofit — they are just things you can do to a row that has not left yet.

Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.

A ledger should not own a money type

polycratia — Sat, 05 Sep 2026 13:20:20 +0000

Most ledger libraries ship their own Money class, so any system that already had a money type ends up with two of them and a conversion layer in between. A ledger does not need to own a money type. It needs a contract: an exact amount, the asset that amount is denominated in, and the arithmetic of netting — which a protocol can express without defining a class.

That is how I built ledger-core: it posts any value satisfying a MoneyLike protocol and defines no money type of its own. The protocol itself was the easy part. The interesting part was what a protocol refuses to give you, and where that shows up in the API.

The second money type is the bug

In the payment systems I have worked on since 2018, money arrives in at least three shapes before anyone writes a line of domain code: an integer count of minor units from a provider, a numeric column from the database, and whatever the application decided a currency-carrying value looks like. Each boundary between those shapes is a function that takes a number and a currency code and returns another number and another currency code, and every one of those functions is a place where quantization, code casing, and — worst — the binding between the amount and its currency can be quietly lost. A Decimal that has lost track of what it is denominated in is just a number, and numbers add up fine no matter how wrong the result is.

A ledger that ships its own money class adds another shape to that list, in the one component whose entire job is to be right about netting. So: one money type per system, provided by the currency library, consumed by everything else.

What the ledger actually needs from a money value

All of it fits in one module:

@runtime_checkable
class MoneyLike(Protocol):
    """An exact amount tied to the asset it is denominated in."""

    @property
    def amount(self) -> Decimal: ...

    @property
    def currency(self) -> str: ...

    def __add__(self: M, other: M) -> M: ...

    def __sub__(self: M, other: M) -> M: ...

    def __neg__(self: M) -> M: ...

    def __lt__(self: M, other: M) -> bool: ...

Two properties and four operations. amount is a Decimal because a ledger that cannot represent an amount exactly has no business claiming entries net to zero. currency is on the value, not passed alongside it, so the pairing cannot come apart in transit.

What is missing matters more. There is no multiplication, because a ledger posts and nets; it does not price. There is no division, because splitting one incoming amount across several parties is a separate problem with its own exactness invariant — an integer allocation over minor units, not a fraction of a money object — and it does not belong behind an operator. The contract stays at four operations because those four are all the ledger performs.

M is a TypeVar bound to MoneyLike, so the arithmetic is self-typed: __add__ takes the same type it returns. The protocol does not merely permit some money type, it rules out mixing two implementations in a single expression, which is exactly the failure mode a second money type introduces.

The ledger does keep one opinion about currency, because it stores currency codes on accounts and needs entries to net per currency:

class CurrencyMismatch(ValueError):
    """Raised when amounts in different currencies are combined."""


def validate_currency(code: str) -> str:
    if not isinstance(code, str) or len(code) != 3 or not code.isalpha() or not code.isupper():
        raise ValueError(f"currency must be a 3-letter uppercase ISO 4217 code, got {code!r}")
    return code

More on that check below — it is the part of my own design I would change.

A protocol gives you arithmetic, not constructors

This is the part nobody warns you about when they tell you to depend on abstractions. A protocol types values you were handed. It does not give you a way to make one. There is no MoneyLike.zero(currency), no parse, no seed value for sum(). A library that consumes a protocol can fold, compare and negate, but it cannot produce a value out of nothing.

Most of the ledger never notices, because every amount it works with came in through an entry. Netting the sides of a movement within a currency needs no seed as long as there is at least one posting to start from. The place where it does notice is the empty account. Holds have to answer "what is available here" for an account that has never been posted to, and the honest answer is zero — but zero of which class?

holds.balance(customer)    # what the account holds
holds.held(customer)       # what open holds have reserved
holds.available(customer)  # balance minus holds

Those return Decimal in the account's currency, not a money object. The ledger owns no money type, so it cannot mint the zero an empty balance would need.

There were three ways out and I want to be explicit about why I picked this one. Widening the protocol with a zero classmethod would make the contract prescribe how implementations are constructed, not just how they behave, and every currency library would have to grow a constructor shaped the way my ledger likes. Taking a money factory as a constructor argument pushes the same problem onto the caller at every entry point, and adds a piece of configuration that can be wrong. Returning the exact number, with the currency already known from the account, keeps the contract narrow and leaves construction where the money type lives.

The rule I would now apply to any library that consumes a value type: consume freely, produce never. Where production is unavoidable, hand back the raw exact quantity and let the caller mint it with the one money type the system already has.

Keep the stand-in obviously temporary

A package that defines no money type still has to be installable and testable on its own, so ledger_core.Money exists as a stand-in until the currency library it is meant to pair with is released. It lives in a module named _stand_in.py, and the README says what it is:

from datetime import datetime, timezone
from decimal import Decimal

from ledger_core import Account, AccountType, Entry, Journal, Money

cash = Account("cash", AccountType.ASSET, "EUR")
customer = Account("customer:42", AccountType.LIABILITY, "EUR")

deposit = Entry.transfer(
    entry_id="e-1",
    occurred_at=datetime.now(timezone.utc),
    debit=cash,
    credit=customer,
    amount=Money(Decimal("25.00"), "EUR"),
    memo="card deposit",
)

The discipline is to keep it useless for anything else. The moment a stand-in grows formatting, conversion, or allocation helpers, applications start importing it for those, and the promise that swapping the money type is an import change stops being true. A stand-in earns its place by staying small enough that nobody wants to build on it.

What I would do differently

Two things.

First, validate_currency enforces a three-letter uppercase alphabetic code. That is an ISO 4217 assumption, and it is precisely the kind of assumption I have just argued a ledger should not make. Stablecoin rails have been in daily production use in systems I run, and USDT does not fit that check; neither would most asset identifiers outside fiat. The ledger only needs equality and grouping from an asset code — it never interprets it. The right move is to make the code opaque to the ledger and leave denomination rules, including how many decimal places an asset actually has, to the money type. A ledger that bakes in two decimal places is fine right up until the first eight-decimal asset arrives.

Second, runtime_checkable on a protocol only checks that attributes are present, not that their signatures match. isinstance(value, MoneyLike) is documentation with a smoke alarm attached, not validation. It is useful at a boundary to catch someone passing a bare Decimal; it is not a reason to skip the currency checks that actually protect the invariant.

Close

The division of labour is clean once you say it out loud. Being exact about a quantity of an asset is one job, and it belongs to a currency library. Guaranteeing that both sides of a movement net to zero and that balances are derived rather than stored is another job, and it belongs to a ledger. Two packages, one money type per system, and a protocol as the only thing that crosses between them.

Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.

Fee estimation belongs inside the coin selection loop

polycratia — Fri, 04 Sep 2026 13:20:21 +0000

Coin selection on a UTXO chain is usually written as two steps: pick inputs until they cover the amount, then compute the fee and adjust. That order cannot be made to work. The fee is a function of the transaction's virtual size, the size is a function of which inputs you chose, and how many inputs you need is a function of the fee. It is a circular dependency, and the only honest way to resolve it is to estimate the fee inside the selection loop rather than after it.

I have been building custodial wallets and on-chain payment systems since 2018, and this is the bug I have watched people rediscover most often. It never looks like a bug at first. It looks like a transaction that sits in the mempool longer than it should, or a wallet that reports a spendable balance it cannot actually spend, or a change output worth less than it costs to spend later. All three have the same root: the fee was computed against a transaction that was already decided.

I keep the reference implementation of the argument in the open at github.com/polycratia/utxo-select — a small Python library that does coin selection, change computation, size estimation and failure reporting as one thing rather than four.

The circle

Spell the dependency out and it stops being abstract.

A transaction's weight is fixed overhead plus a per-input cost plus a per-output cost, and virtual size is that weight divided by four, rounded up. The per-input cost depends on the script type of the output being spent: a legacy P2PKH input is 148 vbytes, a P2WPKH input is 68, a Taproot key-path input is 58. So each candidate you add pushes the size up by a different amount depending on what kind of output it is, and pushes the required total up by that amount multiplied by the fee rate.

from utxo_select import ScriptType, estimate_fee, estimate_vsize

vsize = estimate_vsize(
    inputs=[ScriptType.P2WPKH, ScriptType.P2WPKH],
    outputs=[ScriptType.P2TR, ScriptType.P2WPKH],
)

print(vsize, estimate_fee(vsize, fee_rate=12_000))
print(ScriptType.P2PKH.input_vsize)  # marginal cost of one more legacy input

Fee rates here are quoted per 1000 virtual bytes and everything is an integer of base units, because satoshi arithmetic that touches a float is a bug waiting for a rounding boundary. 12_000 is twelve satoshi per vbyte.

Now run the naive algorithm. You need 100,000. You take inputs by descending value until you have 100,000. Then you compute the fee — say it comes to 1,800 — and discover you are short. So you add another input. That input is worth 45,000, which covers the shortfall easily, but it also added 68 vbytes to the transaction, which added another 816 to the fee. This time you are still fine. Next time, with a smaller candidate, you will not be.

Why the second pass does not save you

The fix people reach for is a second pass: cover the amount, compute the fee, add inputs until the fee is covered too. This terminates on well-funded wallets and quietly diverges on the wallets where it matters.

The reason is that an input is not free money. Spending an output of value v at fee rate r costs estimate_fee(script.input_vsize, r), and what the input is actually worth to this transaction is the difference. That difference is the effective value, and it can be zero or negative. An output holding 500 satoshi, spent as P2WPKH at twelve satoshi per vbyte, costs 816 to spend. Adding it to close a shortfall makes the shortfall larger.

def effective_value(utxo, script_type, fee_rate):
    return utxo.value - estimate_fee(script_type.input_vsize, fee_rate)

That is one line, and it is the line that turns "add inputs until it fits" from a heuristic into an algorithm. Candidates with a non-positive effective value are not candidates; a wallet made entirely of them cannot fund anything at any amount, which is a distinct failure from being merely underfunded, and the library reports it as dust_only.

One caveat on input_vsize that took me an embarrassingly long time to internalize: rounding each input's weight to vbytes independently overstates the total, because the rounding happens once per input instead of once per transaction. It is a safe number to compare two candidates with — it is an upper bound, and upper bounds are what you want when the failure mode is underpaying — but it is not a term to sum into a total. The total goes through estimate_vsize over the actual input and output lists.

So the loop looks like this. Nothing exotic, just the fee re-derived on every iteration against the transaction as it currently stands:

from utxo_select import ScriptType, estimate_fee, estimate_vsize

def cover(candidates, target, fee_rate,
          spend=ScriptType.P2WPKH,
          outputs=(ScriptType.P2TR, ScriptType.P2WPKH)):
    chosen, total = [], 0
    for utxo in sorted(candidates, key=lambda u: u.value, reverse=True):
        chosen.append(utxo)
        total += utxo.value
        vsize = estimate_vsize([spend] * len(chosen), list(outputs))
        required = target + estimate_fee(vsize, fee_rate)
        if total >= required:
            return chosen, required, total - required
    return None, None, None

The important line is required, recomputed after every append. There is no point in the function where the amount to beat is a constant.

The change output is a term in the size, not a leftover

The second place the circularity bites is change, and it bites harder because the coupling runs the other way. Change is not what is left over after the fee. Change is an output, an output has a size, and that size is in the fee you just computed.

A P2WPKH change output is 31 vbytes, which at twelve satoshi per vbyte costs 372 to create. So the moment the remainder drops below the dust threshold — 546 in the usual configuration — you face a decision the naive pipeline has no place to express: you cannot create the output, and you cannot silently drop it either, because dropping it shrinks the transaction, lowers the fee, and increases the remainder you were about to discard.

The honest resolutions are a small, closed set, which is why change policy is an input to selection rather than a post-processing step:

from utxo_select import ChangePolicy, SelectionRequest, Target, Utxo

request = SelectionRequest(
    targets=(Target(value=100_000),),
    fee_rate=12_000,
    dust_threshold=546,
    change_policy=ChangePolicy.ALLOW_CHANGE,
)

ALLOW_CHANGE gives a remainder too small to be worth an output to the fee instead — you overpay slightly, but nothing unspendable is created. REQUIRE_CHANGE keeps adding inputs until the change clears dust, which is what you want when the change address is doing accounting work downstream. FORBID_CHANGE never creates one at all. What you must not do is create a 400-satoshi output and call the selection successful. That output costs 816 to spend. You have not given the user change; you have given them a liability and charged them a fee for it.

Changeless spends make the coupling explicit

Branch-and-bound is the strategy where the whole argument becomes visible, because it optimizes for the change output not existing. It searches for a subset of candidates that pays the targets and the fee exactly, with no remainder worth returning.

from utxo_select import Selection, select_branch_and_bound

result = select_branch_and_bound(utxos, request)

if isinstance(result, Selection) and not result.has_change:
    print("changeless", result.fee, result.vsize)

"Exactly" needs a tolerance, and the tolerance is derived, not tuned. Dropping the change output saves its fee now — 372 — and saves the fee of spending that output later — 816. So a subset that overshoots the target by less than roughly 1,188 at this rate is still an improvement over the alternative, and can be accepted as a solution. That bound is not a magic constant. It is two fee estimates, both of which require knowing the script types involved, which means the search cannot be separated from size estimation any more than the greedy loop could.

Exact matches are rare in real wallets, so the search runs against a budget — 100,000 nodes by default, tunable — and falls back to the largest-first result when it runs out. A selector that returned a failure there would be lying: an answer existed, it just was not the elegant one.

One more consequence worth stating plainly. Because the fee lives inside the loop, the selector can tell you why it failed in terms a human can act on. "The candidates do not hold the target amount" and "they hold the target amount but not the fee on top of it" are different sentences, and only the second one is fixed by waiting for a cheaper fee rate. A selector that added the fee afterwards cannot distinguish them, because at the moment it gave up it did not know what the fee was going to be.

What I would do differently

The first version I ever wrote returned a boolean and mutated a transaction builder in place. Both were mistakes. Returning a value that is either a balanced selection — inputs equal targets plus change plus fee, checked — or a structured failure carrying available, required and shortfall removed an entire category of bug, because there is no longer a state where the caller holds a half-built transaction and a False.

The other thing I would fix earlier: round up, everywhere, without apology. Virtual size rounds up. The fee rounds up. Signatures are counted at their maximum encoded length rather than their typical one. Paying one base unit more than necessary costs nothing anybody will ever measure. Paying one less drops you below the rate a fee estimator quoted, and a transaction that misses its band by a single satoshi is stuck just as thoroughly as one that missed by a thousand.

Coin selection reads like a knapsack problem, and it is tempting to treat the fee as a constraint you apply to the solution. It is not a constraint on the solution. It is a function of the solution. Write the loop that way and the awkward cases — dust, changeless spends, wallets that are technically funded and practically not — stop being special cases and start being outcomes the same arithmetic produces on its own.

Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.

Exactly-once deposits: a broker cannot deduplicate a reorg

polycratia — Thu, 03 Sep 2026 13:21:57 +0000

A service that credits user balances from on-chain deposits has to tell its consumer about each deposit exactly once. The usual reflex is to push the problem onto the transport: turn on deduplication in the queue, set a dedup id, move on. That solves the wrong half. A broker deduplicates the delivery of a message you already decided to send. Nothing in it deduplicates the decision, and on a chain the decision is the part that repeats.

I have been building custodial wallets, on-chain payment systems and fiat-to-crypto onramps since 2018, through three market cycles, and every exactly-once bug I have had to fix in that time lived on the producer side of the queue.

Two problems wearing one name

A deposit watcher polls. Every poll re-reads a range of blocks that overlaps the previous one, because that overlap is the only way to notice that a block you already read is gone. So the same transfer comes back on poll after poll, by design, not by accident. Add a process restart, a node resync, an operator replaying from height zero after a bad deploy, and the same payment is presented to your code an unbounded number of times over an unbounded stretch of wall-clock time.

Broker deduplication only helps if you hand it the same dedup id each time. But knowing that this transfer is the same one you already reported is the state problem. If you can compute a stable id, you have already solved deduplication and the broker is doing nothing for you; if you cannot, the broker has nothing to work with. Exactly-once at the queue is a property you supply, not one you receive.

The key names the payment, not the message

This is where most implementations go wrong, and it is a modelling error rather than a distributed-systems one. The identity you deduplicate on has to name the payment itself, independent of when you learned about it and where it was mined.

In chain-watch, a small library I maintain (https://github.com/polycratia/chain-watch), that identity is DepositKey: the (tx_id, output_index) pair naming the transaction output the money landed on. Every deposit carries it as deposit.key.

from chain_watch import DepositWatcher

watcher = DepositWatcher(source, ["addr-1"], policy=3, reorg_depth=20)

result = watcher.poll()
for deposit in result.confirmed:
    credit(deposit.key, deposit.address, deposit.amount, deposit.asset)
for deposit in result.reverted:
    withdraw(deposit.key)

Compare that with the two keys people reach for instead. A broker message id is attempt-scoped: two polls that see the same transfer produce two ids, so it deduplicates retries of one publish and nothing else. A block-scoped identity — block hash plus index, or a poll cursor — is location-scoped: it survives ordinary repetition and then changes precisely when the transfer is mined into a different block, which is the one moment you needed it to hold. Location-based keys fail exactly when the chain gets interesting.

(tx_id, output_index) says what was paid, not where it was mined. It holds across polls, duplicated blocks, restarts and reorgs, and it is also the natural unique constraint downstream.

Dedup windows are measured in time; finality is measured in blocks

Even a broker that does deduplicate on a key you supply does it inside a window, and that window is expressed in minutes. Chain finality is not expressed in minutes. It is expressed in depth, and depth per asset:

from chain_watch import ConfirmationPolicy

policy = ConfirmationPolicy(default=6, per_asset={"ETH": 12, "USDT": 12})

policy.depth_for("BTC")   # 6, the default
policy.depth_for("USDT")  # 12, the override

Six blocks is an hour on one chain and a couple of minutes on another. A resync replays a year of history in the time it takes to read it. There is no minute count you can configure that means "never report this key again, whatever the source says afterwards" — the units do not match, so the guarantee cannot be stated in the broker's vocabulary at all.

It can be stated in the watcher's. The state carries three things: pending transfers that are not deep enough yet, reported deposits already notified but still inside the reorg window, and settled — the keys of deposits buried below it, final, never reverted and never notified again.

import json
from chain_watch import DepositWatcher, WatcherState

state = WatcherState.from_dict(json.loads(snapshot.read_text()))
watcher = DepositWatcher(source, ["addr-1"], policy=3, state=state)

settled only grows, and the snapshot grows with the number of deposits ever seen. That is the price of the guarantee, and it is worth being honest about it rather than dressing it up. A time window is cheap because it forgets. Forgetting is the bug.

A retraction is not a duplicate

There is a second thing a broker cannot model: an event that was true and stopped being true. Blocks disappear. A deposit you credited at three confirmations can be reorged out, and the consumer needs to hear about that too. A poll therefore returns two lists, not one.

@dataclass(frozen=True, slots=True)
class PollResult:
    confirmed: tuple[Deposit, ...] = ()
    reverted: tuple[Deposit, ...] = ()

The useful part is the invariant between them: a key that was reverted may confirm again, but only after the revert was reported. Credits and withdrawals always alternate. That single rule is what lets the consumer stay dumb — it can apply each side blindly, without comparing amounts, reconciling against a running balance, or deciding whether this confirmation is the first or the third.

On the consumer side the whole thing collapses into one transaction:

def apply(watcher, result, db):
    with db.transaction():
        for deposit in result.confirmed:
            db.execute(
                "insert into deposit_credit (tx_id, output_index, address, amount, asset)"
                " values (%s, %s, %s, %s, %s) on conflict do nothing",
                (*deposit.key, deposit.address, str(deposit.amount), deposit.asset),
            )
        for deposit in result.reverted:
            db.execute(
                "delete from deposit_credit where tx_id = %s and output_index = %s",
                deposit.key,
            )
        db.execute(
            "update watcher_snapshot set data = %s",
            (json.dumps(watcher.state.to_dict()),),
        )

The unique constraint on (tx_id, output_index) is the downstream mirror of DepositKey, and on conflict do nothing is a seatbelt rather than the guarantee. The guarantee is that the credit and the snapshot commit together.

Which is the whole point about placement, stated once: commit the snapshot in the same transaction as the notification and you get exactly once; commit it after and a crash in between replays the poll, so you get at least once; commit it before and the same crash drops the notification, so you get at most once. The broker sits downstream of that choice and cannot improve on it. If you do need to fan out to other services, publish from that same transaction — the transport's job is transport, and its own deduplication becomes a nicety rather than a load-bearing part of the design.

One demand this puts on the chain source: transfers() must describe the current best chain, so a transfer it stops returning is a transfer the chain no longer has. If your node or provider cannot promise that, no amount of bookkeeping above it will save you, and that is worth checking before anything else.

What I would do differently

Earlier custodial systems I built keyed deduplication on things that were not the payment. One keyed on the provider's webhook id, which is really "this notification", so a provider that reissued notifications after an outage produced duplicate credits that looked like a balance bug for a week. Another keyed on block-scoped identity, which held beautifully until the first reorg deep enough to matter.

The subtler mistake was structural. I kept a notified boolean on the same row the scanner was updating with confirmation counts — mixing the record of what the chain says with the record of what I told downstream. Those are two different facts with two different lifetimes, and once they share a row every reorg becomes a data-repair task rather than an event.

What I would build first now is the identity: a key that names the output rather than the message or the block, and a persisted, restorable set of what has already been said. Everything else — the polling loop, the depth policy, the choice of transport — is replaceable around that. The queue is a pipe. Exactly-once was decided before the message reached it.

Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.

A deposit is confirmed by the tip, not by first sight

polycratia — Wed, 02 Sep 2026 13:20:32 +0000

Crediting on-chain deposits fails in a specific way. The watcher sees a transfer, writes a row, and starts incrementing a confirmations column on a timer. Two things are already wrong: the count is stored instead of derived, and the first sighting has been treated as a fact rather than as an event. A confirmation count is not a property of a transfer. It is the distance between the block that currently contains it and the current tip, and that distance can go down as well as up.

I have been running custodial wallets and on-chain payment flows since 2018, through three market cycles, and the reorg itself is not the hard part. The hard part is that a reorg arrives after you have already told the rest of the system something. A ledger entry, a released order, a notification. Re-deriving chain state is cheap. Un-saying things is not. So the design question is not how to count confirmations. It is which single fact you own that the chain cannot rewrite underneath you.

Two facts, and only one of them is yours

Everything a deposit watcher knows splits cleanly in two.

The chain owns where a transfer is: which block, at which height, under which hash, and how far that block sits below the tip. All of it is re-readable on every poll and all of it can change. There is no reason to persist any of it as authority, and every reason not to — a stored confirmation count is a cached answer to a question whose inputs move.

You own what you have already said out loud. That is the only thing the chain cannot re-derive for you, because it never happened on the chain. It happened in your process, to a consumer that has already acted on it.

That split is the whole architecture. Recount from the tip every time, and keep exactly one piece of state: the set of payments you have already reported. I wrote chain-watch around that split, so the poll loop reads as two lists rather than as a state machine:

from chain_watch import DepositWatcher

watcher = DepositWatcher(source, ["addr-1", "addr-2"], policy=3, reorg_depth=20)

result = watcher.poll()
for deposit in result.confirmed:
    credit(deposit)
for deposit in result.reverted:
    withdraw(deposit)

A transfer that is still too shallow does not appear in either list. It sits in watcher.pending and is recounted next time. Nothing downstream hears about a deposit that has not yet reached the depth you asked for, which means a shallow transfer that vanishes in a reorg produces no work at all — the ordinary case costs nothing.

The demand this puts on the data source is worth stating plainly, because it is the one assumption the whole thing rests on: transfers() must describe the current best chain. A transfer the source stops returning is a transfer the chain no longer has. If your node adapter serves a cached union of everything it has ever seen, this design cannot work, and neither can any other.

Depth is a policy, and it is per asset

How deep is deep enough is not a library's decision. It is a risk decision, it differs per asset, and on rails where I have moved stablecoins in production it differs by an order of magnitude from what a low-value native transfer needs.

from chain_watch import ConfirmationPolicy, DepositWatcher

policy = ConfirmationPolicy(default=6, per_asset={"ETH": 12, "USDT": 12})
watcher = DepositWatcher(source, ["addr-1"], policy=policy)

policy.depth_for("BTC")   # 6, the default
policy.depth_for("USDT")  # 12, the override

Two details in there are deliberate and both are about failure modes.

A mapping of overrides leaves the default at one confirmation, not at some large safe-looking number. The reasoning is that an asset nobody listed should be reported rather than held forever. A silently stuck deposit is the worst outcome in this system: no error, no alert, just a user whose money never arrives and a support ticket that takes a day to trace. Loud and shallow beats silent and deep.

Asset names are matched exactly as the chain source spells them. That looks unhelpful until you have shipped a source adapter that reports usdt while the policy says USDT, and case-insensitive matching quietly papers it over on one deployment and not another. Exact matching turns a config mistake into an observable one: the asset falls to the default depth, which you can see in the policy rather than guess at from behaviour.

The dedup key names the payment, not the block

The set of things you have already said needs a key, and choosing it badly is how exactly-once quietly becomes approximately-once.

Anything that includes the block — a block hash, a height, a composite of both with the transaction — is a key that changes when the chain reorganises. The same payment reappears under a new identity and gets credited twice. Keying on the address plus the amount is worse: two identical payments to the same address are indistinguishable, so a legitimate second deposit gets swallowed.

The key that holds is the one that names the payment itself. In chain-watch that is DepositKey, the (tx_id, output_index) pair naming the transaction output the money landed on. It says what was paid, not where it was mined, so it survives polls, duplicated blocks, restarts and reorgs. Every deposit carries it as deposit.key, and it is also the key downstream should deduplicate on, because your consumer needs the same protection your watcher has.

On top of that key the guarantees become statable, which matters more than it sounds — a guarantee you cannot write in one sentence is one you cannot test:

a transfer the source returns on every poll is confirmed once;
a source that replays a range it already served changes nothing;
a key that was reverted may confirm again, but only after the revert was reported, so credits and withdrawals always alternate;
a key below the reorg window is settled: never reverted, never reported again, whatever the source says afterwards.

The third one is the one that saves your ledger. A deposit that reorgs out and is mined again is held from scratch and confirms a second time, but the revert is always reported first. Downstream never has to reason about a credit that arrives twice with a withdrawal owed somewhere in between. The pairing is enforced, so the accounting stays a simple alternation.

Where you write the snapshot decides what the pipeline delivers

Memory is not a guarantee. A process that restarts with an empty dedup set will re-report every deposit still inside its window, so the bookkeeping has to be a value you can persist and hand back:

import json
from chain_watch import DepositWatcher, WatcherState

state = WatcherState.from_dict(json.loads(snapshot.read_text()))
watcher = DepositWatcher(source, ["addr-1"], policy=3, state=state)

result = watcher.poll()
notify(result)
snapshot.write_text(json.dumps(watcher.state.to_dict()))

That three-line ordering is the actual delivery semantics of your pipeline, and it is worth being explicit that no library can decide it for you. Storing the snapshot in the same transaction as the notification gives exactly once. Storing it after gives at least once, because a crash in between replays the poll. Storing it before gives at most once, because the same crash drops the notification. Same watcher, three different products.

This is why the state is a plain value with to_dict() and from_dict() rather than a database integration. The interesting boundary is your transaction, not mine, and the only way to land inside it is to be a value you can write next to your own rows. The serialised form keeps amounts as strings so no decimal is rounded on the way out and back — money that survives a chain reorg and then loses a fractional unit to a JSON float is a comedy I would rather not stage.

What I would do differently

One cost here is real and I have not solved it. Settled keys are kept for the lifetime of the state. That is what makes a replay from height zero safe, and it is also what makes the snapshot grow with the number of deposits ever seen. It is the honest trade: unbounded safety bought with unbounded memory.

In earlier wallet services I built, I would have reached for a stored confirmation count and a periodic repair job, and the repair job is exactly the thing that turns a reorg into a data-integrity incident instead of a routine poll. I would not do that again. But I would bound the settled set — once you accept a finality horizon, keys below it can be dropped, since a source that replays them is reporting blocks you have already declared unreachable. The reason it is not in there yet is that the horizon is a per-chain claim, and I would rather ship the version that is safe against a source I do not control than the version that is cheap against one I have assumed things about.

The underlying discipline generalises past crypto. Anywhere a system observes an external source and tells someone about it, the same split applies: derive everything you can re-read, persist only what you have already said, and key that record on the thing being described rather than on the circumstances of the observation. First inclusion is an event. Exactly-once notification is the product.

Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.

Coin selection should return a reason, not None

polycratia — Tue, 01 Sep 2026 13:23:09 +0000

A withdrawal fails at three in the morning and the log line says the coin selector returned None. That one value covers at least four different situations: two of them are answered by funding the hot wallet, two by changing the request, and nothing in the log says which one you are looking at. The information existed inside the function for a few microseconds and was discarded at the return statement.

I have shipped custodial BTC and ETH wallets and on-chain payment flows since 2018, and this is the failure mode I keep meeting. Coin selection gets written as a predicate — it either produced inputs or it did not — and then the whole operational cost of that decision lands on whoever is awake. They reconstruct the reason by hand from a balance snapshot and a fee chart. That reconstruction is the library's job.

This is the thing I wanted to get right in utxo-select, a small coin selection library I maintain. It is pre-alpha: the models, size estimation, largest-first and branch-and-bound are in place, and the remaining strategies are not. But the failure type was designed before either strategy was, and that ordering turned out to matter more than the strategies did.

Four answers hiding behind one None

A selection can fail in ways that a caller would answer differently:

`reason`	What happened	What fixes it
`insufficient_funds`	the candidates do not hold the targets, fee aside	more coins
`insufficient_after_fees`	they hold the targets but not the fee on top	more coins, or a lower fee rate
`dust_only`	every candidate costs more to spend than it holds	more coins, and consolidate later
`change_below_dust`	they can pay, but leave no change worth relaying	relax the change policy

The last one only fails a selection under REQUIRE_CHANGE. Under the default policy a remainder too small to be worth its own output is given to the fee instead, which is the right default and a surprising one the first time you see the fee come out larger than you asked for.

The distinction that earns its keep operationally is the first two. insufficient_funds means no fee rate on earth makes this transaction; the wallet is simply too small for what was asked. insufficient_after_fees means the wallet covers the payment and loses to the fee, so waiting for a quieter mempool or picking fewer, larger inputs can still close the gap. Those are different pages in a runbook, and a boolean cannot tell them apart.

Because the outcome is a returned value rather than an exception, the caller narrows it with isinstance and the type checker keeps the branches honest:

from utxo_select import FailureReason, Selection, SelectionFailure
from utxo_select import select_largest_first


def explain(result: Selection | SelectionFailure) -> str:
    if isinstance(result, Selection):
        return (
            f"ok: {len(result.inputs)} inputs, fee {result.fee}, "
            f"change {result.change}, vsize {result.vsize}"
        )
    if result.reason is FailureReason.INSUFFICIENT_FUNDS:
        return f"underfunded before any fee, short by {result.shortfall}"
    if result.reason is FailureReason.INSUFFICIENT_AFTER_FEES:
        return (
            f"a lower fee rate closes a gap of {result.shortfall}; "
            f"spending everything would owe {result.fee}"
        )
    if result.reason is FailureReason.DUST_ONLY:
        return f"all {result.candidate_count} candidates are dust at this rate"
    return f"can pay, but change would not clear dust; needs {result.shortfall}"


print(explain(select_largest_first(utxos, request)))

That function is the entire on-call improvement. It is also the thing you cannot write against a selector that returns None.

The fee is inside the loop, not after it

Here is why two of those reasons are even distinguishable, and why they are hard.

The naive shape of coin selection is: sum the candidates, compare against the targets plus the fee, take inputs until the comparison passes. That shape does not work, because the fee is not a constant you can compute up front. A transaction costs a fixed overhead, plus 41 virtual bytes and an unlocking script for every input, plus 9 virtual bytes and a locking script for every output. Every input you add to cover the fee makes the fee larger. Sometimes it makes it larger than the input was worth.

So the required amount is a function of the answer you are still computing. Selection and fee estimation are one loop:

from utxo_select import ScriptType, estimate_fee, estimate_vsize

fee_rate = 12_000  # per 1000 virtual bytes

vsize = estimate_vsize(
    inputs=[ScriptType.P2WPKH, ScriptType.P2WPKH],
    outputs=[ScriptType.P2TR, ScriptType.P2WPKH],
)
print(vsize, estimate_fee(vsize, fee_rate=fee_rate))

# What one more input actually costs you at this rate:
print(estimate_fee(ScriptType.P2WPKH.input_vsize, fee_rate=fee_rate))
print(estimate_fee(ScriptType.P2PKH.input_vsize, fee_rate=fee_rate))

That marginal number is the whole story. An output is worth its value minus the fee of spending it — its effective value — and an output whose effective value is negative should never be picked up, no matter how short the selection is. That is what dust_only names: a wallet with a visible balance that cannot pay anything at all at the current rate, because every coin in it is underwater against its own input cost. Users report this as "my balance is wrong". It is not wrong. It is unspendable, which is a different bug report entirely, and the selector is the only component that knows.

Estimates are upper bounds and both the virtual size and the fee round up. Underpaying is what leaves a transaction stuck in the mempool, and a transaction stuck in the mempool at three in the morning is strictly worse than a selection that refused with a reason.

A failure that carries its own arithmetic

A reason code alone still makes the operator go and look things up. The numbers behind the verdict should travel with it: what the candidates hold (available) against what they would have needed (required), the shortfall between them, the fee a transaction spending every candidate would owe, the target_value that was asked for, and how many candidates were worth spending at all.

result = select_largest_first(utxos, request)

if isinstance(result, SelectionFailure):
    print(result.available, result.required, result.shortfall)
    print(result.spendable_count, "of", result.candidate_count, "spendable")
    print(result.dust_count, "dust at this rate")
    print("gap not caused by the fee rate:", result.required - result.fee)

That last line is the one I reach for most. required - fee is the part of the gap the fee rate is not responsible for, which immediately tells you whether waiting for the mempool to calm down is a strategy or a waste of an hour. dust_count tells you whether the wallet needs a consolidation transaction rather than a top-up. None of these are new computations — the selector did all of them on its way to failing. It just has to not throw them away.

Why a failure is a value and a success is checked

Two choices hold this together.

First, failure is a returned value, not an exception. Not being able to pay is an ordinary outcome of asking a wallet to pay, not an exceptional one, and modelling it as a value forces every caller to look at it. An exception gets swallowed by a broad except three frames up and turns back into None with extra steps.

Second, success is verified before it can exist. A Selection checks its own identity in __post_init__ — inputs equal targets plus change plus fee — and refuses to be constructed otherwise:

if self.total_input != self.total_output + self.fee:
    raise ValueError(
        f"selection does not balance: {self.total_input} in, "
        f"{self.total_output} out, {self.fee} fee"
    )

This is the same discipline as a double-entry ledger, and it is there for the same reason: the expensive failures are not the loud ones. An underpaying selection is a transaction that looks fine, broadcasts fine, and sits unconfirmed. Making that state unconstructible is worth more than any amount of downstream validation.

The pairing also lets a strategy degrade honestly. Branch-and-bound searches for a subset that pays the targets and the fee exactly, so the transaction carries no change output at all — which saves the change output's fee now and the fee of spending it later. Exact matches are the exception, not the rule. When the search budget runs out (100000 nodes by default, tunable via max_tries), the largest-first result is returned instead. The caller gets the best available answer rather than a failure, and it never has to guess which strategy produced it, because a Selection reports its own fee, change and has_change.

What I would do differently

I would write the failure type before the first strategy, not after — and this time I did, which is the only reason branch-and-bound needed no new reasons when it landed. The four outcomes are properties of the problem, not of the algorithm. Every strategy fails for the same four causes; if adding a strategy adds a reason, the reason vocabulary was wrong.

The thing I underestimated is how much of the failure payload is inference rather than measurement. available and candidate_count are facts. required is a claim that depends on which script types you assumed and how you rounded, and spendable_count depends on the fee rate at the moment you asked. Those numbers are only true for one request. I would put more of that context into the failure itself rather than letting a log line imply it was universal.

A coin selector is not a predicate over a wallet. It is an oracle about a wallet at a fee rate, and the answer "no" is the least interesting thing it knows.

Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.

A balance is a query, and a hold is not a column

polycratia — Mon, 31 Aug 2026 13:22:37 +0000

Custodial systems lose money in two ordinary writes: UPDATE accounts SET balance = balance + :amount, and the one next to it that nudges a frozen column up and down while a withdrawal is pending. Both are read-modify-write against a cell that several code paths believe they own, and both turn an accounting question into a concurrency question. The fix is not a better lock. It is to stop storing the answer: derive the balance from paired postings, and make a reservation a first-class object that settles or releases, rather than a number parked beside the balance.

I have been building payment and custodial systems in production since 2018 — per-user virtual account ledgering with separate borrowing and investing sides, attribution of incoming transfers, custodial wallets for BTC and ETH, stablecoin rails in daily use. Nearly every reconciliation bug I have chased in that time was a variation of one thing: a number was stored as authoritative, and more than one path was allowed to edit it. I put the shape I keep re-deriving into a small library, ledger-core, and I will use it here, because it is easier to argue with code than with adjectives.

The constraint: a withdrawal is two moments, not one

The thing that makes custodial balances harder than they look is that the interesting states are not moments. A card deposit is one movement. A withdrawal is two: the funds stop being spendable now, and they leave later — or they never leave, because the payout failed, or compliance stopped it, or the customer cancelled while the batch was still queued.

If the only representation you have is a balance cell, you are forced to encode that gap somewhere. The usual answer is a second cell. Now every code path has to remember to touch both, atomically, in the right order, and the invariant that used to be arithmetic becomes procedure — something enforced by everyone remembering. That is the shape that fails under retry, under partial failure, and under two operators clicking at once.

So the design has two halves. Postings are the only thing written. Everything else — the balance, what is reserved, what may be spent — is derived from them.

Movements: two sides, one id, no partial writes

A movement has two sides and one id. Nothing in the system writes one side of it:

from datetime import datetime, timezone
from decimal import Decimal

from ledger_core import Account, AccountType, Entry, Journal, Money

cash = Account("cash", AccountType.ASSET, "EUR")
customer = Account("customer:42", AccountType.LIABILITY, "EUR")

deposit = Entry.transfer(
    entry_id="e-1",
    occurred_at=datetime.now(timezone.utc),
    debit=cash,
    credit=customer,
    amount=Money(Decimal("25.00"), "EUR"),
    memo="card deposit",
)

journal = Journal()
journal.append(deposit)

An entry that does not net to zero in every currency it touches raises UnbalancedEntry at construction. That is the part worth sitting with: the invalid object does not exist. There is no window in which a one-sided movement is in memory waiting for a validator to catch it, no repair job that finds orphaned legs at 3am. More than two postings are fine — fee splits, multi-party settlements — as long as they sum to zero.

Batches inherit the rule. Journal.extend is all-or-nothing: a duplicate id or a correction of something nobody wrote rejects the batch, not the offending row. Half-applied imports are the single most expensive category of reconciliation work I have done, and they are almost always the residue of a loop that committed per item.

Entries are never edited or deleted. To undo one, you write the entry that undoes it:

refund = deposit.reversal(
    entry_id="e-2",
    occurred_at=datetime.now(timezone.utc),
)
journal.append(refund)

This is not purity for its own sake. An append-only journal is what lets you answer why a balance is what it is, months later, when a customer disputes it — and the answer is the same one your finance side will compute independently.

Balances: derived, snapshotted, never edited

A balance is what the entries add up to, counted in the account's normal direction:

from ledger_core import Balances

balances = Balances(journal)
balances.balance(cash)  # Decimal("25.00")

Reading writes nothing, so two readers cannot overwrite each other's arithmetic — which is exactly how a mutable column updated by read-modify-write silently loses a movement. The lost update is not a rare race in a busy custodial system; it is the normal outcome of a webhook redelivery landing next to a manual adjustment.

The objection to deriving is performance, and it is a real objection: folding the whole journal on every read gets slower as the journal grows. The answer is to cache the fold, not to abandon it. Each fold is kept as a snapshot — how far it got and what it had by then — and the next read resumes from there, replaying only what has been written since:

snapshot = balances.snapshot(customer)
snapshot.total    # what the account held
snapshot.through  # how many entries are folded into it
snapshot.as_of    # when the last of them occurred

Snapshots are plain values. They can be stored, shipped between processes and handed back: Balances(journal, [snapshot]). The discipline around them is what keeps this from becoming a stored balance in disguise. A snapshot is only ever replaced by one that reaches further, never edited, and one claiming more entries than the journal holds is refused with SnapshotMismatch. A stale snapshot therefore costs a replay, never a wrong answer. That asymmetry — degrade into slowness, never into incorrectness — is the property I want from every cache that sits in front of money.

One deliberate exception: a balance as of a moment ignores snapshots entirely and replays in full, because a position in the journal says nothing about a point in time. Entries can be appended with earlier occurred_at values than the ones before them; back-dated settlement files do this routinely.

balances.at(customer, datetime.now(timezone.utc))

Holds: a reserve with a state, not a number

Now the second half of the thesis. A hold writes nothing to the ledger. It stands in front of the balance:

from ledger_core import Holds

holds = Holds(journal)

holds.place(
    hold_id="h-1",
    account=customer,
    amount=Money(Decimal("10.00"), "EUR"),
    placed_at=datetime.now(timezone.utc),
    memo="withdrawal to IBAN",
)

holds.balance(customer)    # what the account holds
holds.held(customer)       # what open holds have reserved
holds.available(customer)  # balance minus holds

available is the number every spend decision should be asking about, and it is derived too — balance less everything still open. A hold that does not fit raises InsufficientFunds: the reservation is refused rather than the account going short. Refusing at reservation time is the whole point. If the check lives at capture time instead, you have already told the customer their withdrawal is in progress.

The Hold itself is a frozen record with a state — OPEN, RELEASED, CAPTURED — and it settles exactly once. released() and captured() return a new hold rather than mutating one, and calling either on an already-settled hold raises HoldNotOpen. Compare that to a frozen_amount column: a double release against a column is an arithmetic error that shows up days later as a balance that no longer reconciles, while a double release against a state machine is an exception at the call site.

If the payout falls through, the reservation goes back:

holds.release("h-1", at=datetime.now(timezone.utc))

If it goes through, the hold is settled by the entry that moves the money — the same paired posting as any other movement, no special case. The settled hold keeps a reference to the entry that settled it, so "which movement discharged this reservation" is a stored fact rather than a join on amount and timestamp. And a settling entry that does not move exactly what was held is refused with CaptureMismatch, which closes the gap where a partial capture quietly leaves stranded funds reserved forever. Every long-lived custodial system I have worked on accumulates those: reservations nobody can explain, on accounts nobody can release.

Holds read through the same projection as balances. Pass Holds(journal, balances=balances) to share snapshots with an existing projection, or let it build its own — but there is only ever one arithmetic, not a reserve calculation that has drifted from the balance calculation.

The money type the ledger refuses to own

The third piece is the one people argue with most, so it is worth stating plainly: the ledger should not own a money type. It posts any value that exposes an exact amount, the currency it is denominated in, and +, -, unary - and ordering. That is the MoneyLike protocol, and it is the entire contract.

This is not abstraction for its own sake. Money types are opinionated and domain-specific — minor-unit precision, rounding policy, whether eight decimal places are normal, how currency codes are compared. A ledger that ships its own Money forces every system that adopts it into a conversion layer at the boundary, and conversion layers between two money types are where rounding differences are born. Accepting a protocol means the type you already trust is the type that gets posted.

In ledger-core there is a small stand-in Money so the library stays usable and testable on its own, with the real pairing behind an extra:

pip install "ledger-core[crypto]"

Swapping is an import change; nothing else in the API moves.

The refusal has one visible consequence I like a lot. balance, held and available come back as Decimal in the account's own currency, not as money objects — because the ledger owns no money type, it cannot mint the zero that an empty balance would need. The return type tells you the truth about where the boundary is instead of papering over it.

What I would do differently

On earlier systems I reached for the stored balance first and the ledger second, usually with a nightly job that recomputed from history and flagged discrepancies. That job is a confession: it exists because the primary number is not trustworthy. It also arrives too late — by the time it flags drift, the wrong number has already been shown to a customer, used in a spend decision, and possibly settled against.

The other thing I would change earlier is treating holds as a feature of the withdrawal flow rather than a concept of the ledger. When the reserve belongs to one flow, the second flow that needs one — a pending trade, a compliance freeze, a chargeback provision — invents its own, and available stops being a single answer. Making the hold a ledger-level object with its own id, state and settling entry is what keeps a fifth reservation type from being a fifth column.

What I would keep: derivation with a snapshot in front of it, snapshots that can only move forward, and validation at construction rather than at commit.

Close

Stored balances and freeze columns feel like performance decisions. They are not; they are decisions to make a derived fact editable, and everything expensive that follows — the lost updates, the repair jobs, the stranded reservations, the nightly recompute nobody trusts — descends from that. Postings are the only thing worth writing down. The balance is a question you ask them, and a hold is an object that stands in front of the answer until it settles or goes away.

Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.

Declare once, apply to many: scoping VEX decisions without lying

polycratia — Sun, 30 Aug 2026 13:29:29 +0000

A vulnerability scanner does not remember what you decided yesterday. Every build re-reports the same CVEs against the same dependencies, and someone re-reads the same advisory to reach the same conclusion. VEX exists to record that conclusion once, but a VEX statement is an assertion about a concrete product at a concrete version — so the moment anything bumps, you either re-triage from zero or you quietly reuse a claim you never re-checked. Neither of those is a process; the first is attrition and the second is a lie with good formatting.

I hit this on services where the scanner output is not decoration. In payment and compliance-adjacent systems, someone eventually asks for the basis of a specific claim about a specific artifact that was running on a specific day. "We marked it not affected" is not an answer. "We marked it not affected in March against version 2.4.1, and the artifact you are asking about shipped 2.4.9, and nobody looked again" is at least a true answer — but only if the system was built to know that.

The two ways to be wrong

The first way is to pin every decision to the exact tuple of product version and dependency version. This is honest and unusable. A patch bump on a transitive dependency invalidates a decision that is still obviously correct, the queue fills with re-triage that produces the same verdict, and within two months the team is clicking through it without reading. An honest model that nobody follows produces dishonest data.

The second way is to declare component-wide: this CVE against this library is not affected, full stop, whatever version. This is usable and false. It keeps asserting after the fact underneath it stopped being true, and it fails silently, which is the worst failure mode available for a security claim.

Both failures come from treating scope as a UI convenience — a checkbox for "apply to all versions" — rather than as part of the claim itself. Scope is part of the claim. A decision without an explicit applies_to is not a compact decision; it is an ambiguous one.

Scope follows the justification

Here is the part that made the model tractable for me. Under OpenVEX, a not_affected status carries a justification (or a written impact statement), and each justification is a statement about a different thing:

Justification	It is a property of	Survives a dependency bump?
`component_not_present`	your build and packaging	yes
`vulnerable_code_not_present`	that exact dependency version	no
`vulnerable_code_not_in_execute_path`	your code's call graph	usually
`vulnerable_code_cannot_be_controlled_by_adversary`	your input and deployment path	usually
`inline_mitigations_already_exist`	your configuration	usually

Four of the five are assertions about your product. They are legitimately component-wide with respect to the dependency, and they break when you change — when packaging changes, when someone starts calling the function you swore you never call, when a mitigating config option gets flipped in one environment. Exactly one, vulnerable_code_not_present, is an assertion about the dependency's source at a version. Carrying that one across a version bump is not a shortcut; it is a fabricated claim, because the whole content of the claim was "this code is not in this version".

So the scope is not a preference. It follows from the justification — and a decision whose scope contradicts its justification is a bug you can detect mechanically. vexdesk does not enforce that check yet; today it is a review rule I apply by hand when a decision lands in the file, and encoding it is the next change on the list. I will come back to why it matters more than anything else here.

The scope a decision actually carries

In vexdesk I keep decisions as source rather than as scanner-tool state: a JSON file in the repository, one entry per judgement, applied to whatever the current scan finds. The tool is Go, standard library only, and the scope model it ships today is deliberately the small one — a single axis, on the component:

// Scope says how far one decision reaches.
type Scope string

const (
    // ScopeVersion keeps the decision on the exact product it names. It is the
    // default: a judgement made about one build does not travel unless asked.
    ScopeVersion Scope = "version"
    // ScopeComponent applies the decision to the same component at any version,
    // so a justification written once survives the next scan. A version-scoped
    // decision naming a particular version wins over it, which is how a rule is
    // taken back for that version.
    ScopeComponent Scope = "component"
)

type Decision struct {
    Vulnerability string                `json:"vulnerability"`
    Product       string                `json:"product"`
    AppliesTo     Scope                 `json:"applies_to,omitempty"`
    Status        openvex.Status        `json:"status"`
    Justification openvex.Justification `json:"justification,omitempty"`
    Impact        string                `json:"impact_statement,omitempty"`
    Action        string                `json:"action_statement,omitempty"`
}

A decision file entry looks like this:

{
  "vulnerability": "CVE-0000-00000",
  "product": "pkg:pypi/somelib@2.4.1",
  "applies_to": "component",
  "status": "not_affected",
  "justification": "vulnerable_code_not_in_execute_path",
  "impact_statement": "the vulnerable parser is never invoked; we only use the encoder"
}

applies_to defaults to version: a judgement made about one build does not travel unless you asked it to. "Every version" is a value you had to type, not a default you inherited. And an unreadable scope is refused at load time rather than narrowed to the default — a typo would otherwise silently shrink a rule, which is the quiet kind of wrong this whole design exists to avoid.

Resolution: the exact decision wins

Precedence is specificity, not recency. A decision naming the exact product is used as written; only when there is none does a component-wide rule for the same component apply. That is also how you take a blanket rule back for one version — write the version-specific decision, and it outranks the rule without deleting it:

if d, ok := exact[[2]string{f.Advisory, f.Component.PURL}]; ok {
    apply(&s, d, "")
} else if d, ok := componentWide[[2]string{f.Advisory, componentKey(f.Component.PURL)}]; ok {
    apply(&s, d, d.Product)
}

Anything no decision reaches comes out as under_investigation — the honest status for "we have seen it and have not finished looking". The tool never upgrades that on its own: deciding that vulnerable code is unreachable is an engineering judgement, and a tool that guesses it produces documents that look authoritative and are not.

Every carried decision must say it was carried

A status is not enough. It matters how the status reached this artifact, because "declared for exactly this build" and "inherited from a rule written months ago against a different version" are different epistemic states and belong in different review queues. So when a component-wide rule fires, the emitted statement says so, in the statement itself:

note := fmt.Sprintf("carried from the decision recorded for %s by an applies_to=%s rule",
    carriedFrom, ScopeComponent)

That line ends up in the published document, so a reader of the VEX file — not just a reader of my internal state — can tell a pinned judgement from an inherited one. It is a deliberately blunt mechanism: provenance as text, in the field people actually read. A structured carried_from object with the source decision, its date and a review deadline is the obvious next step, and it belongs in an internal store rather than the published document — OpenVEX products are concrete identifiers, there is no wildcard with agreed semantics, and the published document should say what is true about this artifact while the store says how you came to believe it.

One consequence of the current model worth stating plainly: the carried note lands in impact_statement, which OpenVEX defines for not_affected. For rules with other statuses that placement is questionable, and it is on the list to move.

What I would do differently

My first version of this was a table keyed by (product, cve) with a status column and a notes field, because that is what the triage session in front of me needed. Ranges got bolted on later as a nullable string, and the meaning of NULL drifted between "all versions" and "nobody filled this in" depending on which script wrote the row. Cleaning that up cost more than modelling scope explicitly from the start would have.

The model I keep converging on has two independent version axes — which versions of my product, and which versions of the vulnerable component — with precedence by specificity on both, and a tie between two equally specific decisions treated as a build failure rather than resolved by recency. Picking the newest one is how you get an audit trail that is technically complete and substantively meaningless. vexdesk today ships the one-axis version of that model on purpose: it covers the cases my triage actually produces, and every scope concept it does have is spelled out rather than implied. The two-axis model earns its complexity the day a vulnerable_code_not_present claim needs to coexist with a product-side rule for the same CVE — and that is exactly the day the justification check from earlier stops being a review habit and must become code, refusing at authoring time the one blanket rule that is always a fabrication.

The other thing I would change earlier: make a review deadline mandatory on any decision that can be carried. An unbounded assertion about your own call graph is fine on the day you verify it and slowly rots afterwards, and the only cheap defence is that carried decisions expire into a review queue instead of quietly aging into permanence. A carried decision past its review date should degrade to under_investigation rather than keep asserting.

None of this makes triage disappear. It makes triage compound: the component-wide rules absorb the churn they are entitled to absorb, the version-specific facts stay pinned to the versions they are facts about, and everything inherited is labelled as inherited. An audit trail that distinguishes what you checked from what you assumed is worth having. One that does not is a guess with timestamps on it.

Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.

Multi-carrier shipping rates are quotes, not prices

polycratia — Fri, 28 Aug 2026 13:26:41 +0000

The shipping amount a customer sees at checkout comes from a carrier API call that happened seconds or minutes earlier, computed from package dimensions and an address that can both change before anyone buys a label. If you store that amount as a price column on the order, every gap between what you quoted and what the carrier actually billed becomes manual work that never ends.

I have spent years on the delivery side of a cross-border shopping platform: rates, labels and tracking from several carriers behind one checkout. The design decision that mattered most was refusing to treat a rate as a number. A rate is a quote — an object with inputs, an issuer, a carrier-side reference and an expiry. Once it is modelled that way, most of the ugly cases stop being ugly.

The rate is a function of inputs you do not fully own

A carrier price depends on billable weight (which may be volumetric rather than actual), on whether the destination is classified residential or commercial, on surcharges that change without notice, on declared value, and on which service code you asked for. Half of those inputs are decided after checkout, by a warehouse operator choosing a box.

So the first thing to write down is not the price. It is the exact input vector the price was computed from, hashed, so you can later ask a precise question: is this quote still about the same shipment?

import hashlib
import json
from dataclasses import dataclass, asdict

@dataclass(frozen=True)
class QuoteInputs:
    origin_zone: str
    dest_country: str
    dest_postcode: str
    dest_kind: str              # 'residential' or 'commercial'
    billable_weight_grams: int
    dims_mm: tuple[int, int, int]
    declared_value_minor: int
    currency: str
    incoterm: str

def fingerprint(inputs: QuoteInputs) -> str:
    payload = json.dumps(asdict(inputs), sort_keys=True, separators=(',', ':'))
    return hashlib.sha256(payload.encode()).hexdigest()

Note what is deliberately absent: cart contents, customer id, promo codes. The fingerprint covers the shipment, not the order. Adding a second identical item changes the weight and must invalidate the quote; changing the billing email must not.

Persist the quote, not the number

Every offer a carrier returns gets a row. Not the winning one — every one. The alternatives are what let you answer, months later, why a parcel went out with the carrier it did.

create table shipping_quote (
    id                 uuid primary key,
    shipment_id        uuid        not null references shipment(id),
    carrier            text        not null,
    service_code       text        not null,
    carrier_quote_ref  text,
    amount_minor       bigint      not null,
    currency           char(3)     not null,
    input_fingerprint  char(64)    not null,
    raw_response       jsonb       not null,
    fetched_at         timestamptz not null,
    expires_at         timestamptz not null
);

create index shipping_quote_lookup
    on shipping_quote (shipment_id, fetched_at desc);

Two columns there are load-bearing and easy to skip.

carrier_quote_ref is the identifier the carrier hands back with its rate. Where a carrier honours it at purchase time, buying against that reference is the difference between paying what you quoted and paying whatever the rate engine feels like today.

raw_response is the untouched body. Normalized columns throw away precisely the field you will need when an unfamiliar surcharge shows up on an invoice line and you have to prove whether it was visible at quote time.

Fetching is the other place where multi-carrier integrations rot, because it is tempting to gather everything into one list and move on:

def refresh_quotes(shipment, carriers, ttl=timedelta(minutes=30)):
    inputs = quote_inputs(shipment)
    fp = fingerprint(inputs)
    issued_at = now()
    quotes, unavailable = [], []

    for carrier in carriers:
        try:
            offers = carrier.rate(inputs)
        except CarrierError as exc:
            unavailable.append(CarrierOutage(carrier.code, str(exc)))
            continue
        for offer in offers:
            quotes.append(store_quote(
                shipment=shipment,
                offer=offer,
                input_fingerprint=fp,
                fetched_at=issued_at,
                expires_at=issued_at + min(ttl, offer.carrier_ttl or ttl),
            ))

    return quotes, unavailable

An empty list from a carrier means it does not serve that destination. An exception means you do not know. Those are different facts and they belong in different variables. Collapse them into 'no options available' and you will quietly stop selling to a country for as long as one integration is broken, and nobody will file a bug, because the checkout looks fine.

Buying the label against a quote, not against a service code

The purchase step is where the model earns its keep. It has one job: refuse to spend money if the world has moved.

def buy_label(quote_id: UUID) -> Label:
    with transaction.atomic():
        quote = Quote.objects.select_for_update().get(id=quote_id)
        shipment = quote.shipment

        if quote.expires_at <= now():
            raise QuoteExpired(quote_id)
        if fingerprint(quote_inputs(shipment)) != quote.input_fingerprint:
            raise ShipmentChanged(quote_id)

        label = carriers[quote.carrier].buy(
            quote_ref=quote.carrier_quote_ref,
            service_code=quote.service_code,
            idempotency_key=f'label:{quote.id}',
        )

        record_charge(shipment, kind='label', amount_minor=label.amount_minor,
                      currency=label.currency, quote=quote,
                      carrier_ref=label.tracking_number, source='label_api')
        return label

The idempotency key is derived from the quote id rather than generated per call, because a retried label purchase is not a duplicate row in a report — it is a second parcel and a second charge. Deriving the key from something already persisted means a retry after a timeout, a redeploy, or an operator double-click all land on the same key.

ShipmentChanged is the interesting failure. It fires when the warehouse repacked, when the customer corrected an address, when the classification of the destination flipped. The correct response is to re-quote and show the new price to whoever is standing at the packing bench — not to buy the old one and file the difference under 'shipping variance'.

The carrier reprices after you shipped

This is the part nobody warns you about. Carriers re-measure parcels in their own hubs. Address corrections, remote-area surcharges and dimensional-weight adjustments arrive days later, on an invoice, keyed by tracking number — not by your order id, and not through the API that sold you the label.

If shipping cost is a column, you now have to overwrite it, and the quote is gone. Make it a ledger instead.

create table shipping_charge (
    id           uuid primary key,
    shipment_id  uuid        not null references shipment(id),
    quote_id     uuid        references shipping_quote(id),
    kind         text        not null,   -- quoted | label | adjustment | refund
    amount_minor bigint      not null,   -- signed
    currency     char(3)     not null,
    carrier_ref  text,                   -- tracking number or invoice line id
    source       text        not null,   -- checkout | label_api | invoice
    occurred_at  timestamptz not null,
    unique (source, carrier_ref, kind, amount_minor, occurred_at)
);

Rows are appended, never updated. What the customer paid is one row. What the label cost is another. Every later adjustment is its own row, attached by carrier_ref because that is the only key the invoice actually contains. Margin on a shipment becomes a sum, reconciliation becomes a query, and 'what did we quote and why' remains answerable forever.

The uniqueness constraint matters because invoice ingestion is a file-parsing job, and file-parsing jobs get run twice.

What I would do differently

I would introduce the input fingerprint at the same time as the quote table, not later. Without it, quote expiry is the only guard you have, and expiry does not catch the case that actually costs money: a quote that is still fresh but no longer describes the parcel on the bench.

I would model carrier unavailability as a first-class value returned to the caller from day one, rather than a log line. Everything downstream — checkout messaging, alerting, deciding whether a destination is genuinely unserved — needs that distinction, and retrofitting it means touching every call site.

And I would store the raw carrier payload immediately. It costs a jsonb column, and it is the only thing that makes a surcharge dispute a five-minute lookup instead of an argument.

Close

A price is a fact. A rate is a promise made under assumptions, by a third party, with a shelf life. Almost every recurring problem in multi-carrier shipping — quoted-versus-charged drift, duplicate labels, mystery invoice lines, silently disappearing destinations — comes from storing the second thing in a shape designed for the first.

Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.

Custodial ETH withdrawals: the nonce is a database row, not a node call

polycratia — Tue, 25 Aug 2026 13:25:40 +0000

A custodial wallet service has to turn a user's withdrawal request into exactly one on-chain transaction, while every layer around it — HTTP clients, queues, restarts, impatient users — is at-least-once. The first thing that breaks is the nonce. Two workers ask the node for the next transaction count, both get the same number, both sign, and one transaction quietly replaces the other on the network. Nothing throws. The user sees a confirmation and no coins.

I have built custodial wallet services for BTC and ETH and the on-chain payment system around them. Account-model chains punish sloppiness here more than UTXO chains do, because the nonce is a strictly sequential resource owned by the sending address, and nothing in the JSON-RPC API will defend it for you.

The node's nonce is a report, not a reservation

eth_getTransactionCount answers one of two different questions depending on the block tag: how many transactions from this address are mined (latest), or how many the node currently holds in its own mempool view (pending). Neither one is an allocation.

latest ignores everything in flight, so under any concurrency it hands the same number to everybody. pending reflects a single node's mempool, which is not a consensus object: it evicts transactions under memory pressure, it cannot see what a sibling node accepted, and it forgets everything on restart. Building a withdrawal queue on pending means your correctness depends on a cache you do not own and cannot audit after the fact.

So the rule I end up at every time: the nonce is allocated by my database, in the same transaction that persists the signed payload. The node is told about the result afterwards, as many times as necessary.

Three states, not one

"Send a withdrawal" is not one operation. It is three, and they have completely different repeat semantics.

state	meaning	safe to repeat
requested	an intent exists, nothing is signed	yes, freely — discard and rebuild at will
signed	a nonce is consumed, a payload is durable	never — this is the irreversible step
broadcast	the network has been told at least once	yes, endlessly, with the same bytes
settled	the nonce slot is mined	terminal

Most broken pipelines I have inherited collapse signed and broadcast into one sent state. After a crash they cannot distinguish "we never built this transaction" from "we built it and the RPC call timed out" — and those two have opposite recovery paths. One should rebuild, the other must never rebuild.

Allocating the nonce

create table hot_account (
    address    text   primary key,
    next_nonce bigint not null
);

create table withdrawal (
    id           bigserial primary key,
    user_id      bigint        not null,
    from_address text          not null references hot_account(address),
    to_address   text          not null,
    amount_wei   numeric(78,0) not null,
    state        text          not null default 'requested',
    nonce        bigint,
    raw_tx       bytea,
    tx_hash      text,
    created_at   timestamptz   not null default now()
);

create unique index withdrawal_nonce_uniq
    on withdrawal (from_address, nonce)
    where nonce is not null;

Two details there matter more than they look.

The partial unique index is the invariant, expressed in the only place that can actually enforce it under concurrency. If a bug ever lets two workers allocate the same nonce, I want a constraint violation and one stuck withdrawal, not two valid signatures racing on the network.

And next_nonce lives in its own tiny table so it can be locked on its own. That lock serialises every withdrawal leaving that address, so the critical section has to stay short — which is exactly why no network call belongs inside it.

from eth_account import Account

GAS_LIMIT = 21_000  # plain value transfer

def allocate_and_sign(conn, withdrawal_id, key, chain_id, max_fee, priority_fee):
    with conn:  # one database transaction
        cur = conn.cursor()
        cur.execute(
            'select state, from_address, to_address, amount_wei '
            'from withdrawal where id = %s for update',
            (withdrawal_id,),
        )
        state, from_address, to_address, amount_wei = cur.fetchone()
        if state != 'requested':
            return  # already allocated by someone else; not our job

        cur.execute(
            'select next_nonce from hot_account where address = %s for update',
            (from_address,),
        )
        (nonce,) = cur.fetchone()

        signed = Account.sign_transaction(
            {
                'chainId': chain_id,
                'nonce': nonce,
                'to': to_address,
                'value': int(amount_wei),
                'gas': GAS_LIMIT,
                'maxFeePerGas': max_fee,
                'maxPriorityFeePerGas': priority_fee,
            },
            key,
        )

        cur.execute(
            'update hot_account set next_nonce = next_nonce + 1 where address = %s',
            (from_address,),
        )
        cur.execute(
            "update withdrawal set state = 'signed', nonce = %s, raw_tx = %s, tx_hash = %s "
            'where id = %s',
            (nonce, signed.raw_transaction, signed.hash.hex(), withdrawal_id),
        )

The ordering is the whole point. The lock, the increment, the signature and the stored payload commit together. If the process dies halfway, the transaction rolls back, the nonce is not consumed, and nothing was ever broadcast — the request is still cleanly requested. If it commits, exactly one signed payload exists for that nonce and it is durable before a single packet leaves the process.

Note also what is absent: any RPC call. Signing is local. Fee parameters are read before the transaction opens and passed in; a plain transfer's gas limit is a constant. Fetching fees inside the critical section would put a network timeout inside a lock that every other withdrawal from that address is waiting on.

Rebroadcast is free; re-signing is not

ALREADY_HAVE_IT = ('already known', 'known transaction', 'transaction already exists')

def rpc_message(exc):
    arg = exc.args[0] if exc.args else ''
    text = arg.get('message', '') if isinstance(arg, dict) else str(arg)
    return text.lower()

def broadcast(w3, conn, withdrawal_id):
    cur = conn.cursor()
    cur.execute(
        "select raw_tx from withdrawal where id = %s and state in ('signed', 'broadcast')",
        (withdrawal_id,),
    )
    row = cur.fetchone()
    if row is None:
        return

    try:
        w3.eth.send_raw_transaction(bytes(row[0]))
    except ValueError as exc:
        message = rpc_message(exc)
        if 'nonce too low' in message:
            return  # the slot is already mined; the watcher decides by whom
        if not any(known in message for known in ALREADY_HAVE_IT):
            raise

    with conn:
        cur.execute(
            "update withdrawal set state = 'broadcast' where id = %s and state = 'signed'",
            (withdrawal_id,),
        )

The error handling is the interesting half. already known is not a failure of this withdrawal, it is evidence the network already has the exact bytes I am holding. Sending the same signed payload a thousand times produces one transaction, because the payload is its own identity.

The dangerous instinct is the opposite one: a send times out, and somebody "retries" by rebuilding the transaction with a fresh nonce. Now two signed payloads exist for one intent, and if the first one was in fact accepted, both can mine, and the user is paid twice from a hot wallet. Once a payload is signed, the retry is always the same bytes.

Fee bumps create siblings

Under a rising fee market a transaction can sit unmined for a long time, and because nonces are sequential, everything behind it waits. The fix is a replacement: same nonce, higher fee, new signature. Most clients require a meaningful increase before they will evict the old one — geth's default price bump is ten percent — so the bump has to be real, not cosmetic.

That produces the part nobody warns you about. One withdrawal now has several valid transaction hashes, and only one of them will ever be mined. If the confirmation watcher polls a single stored tx_hash, a successful bump is indistinguishable from a lost transaction, and the operator on shift starts investigating a payment that actually went through.

So attempts get their own table, and the watcher keys on the pair that is genuinely unique on-chain — (from_address, nonce) — rather than on any one hash.

create table withdrawal_attempt (
    id            bigserial primary key,
    withdrawal_id bigint      not null references withdrawal(id),
    tx_hash       text        not null unique,
    raw_tx        bytea       not null,
    max_fee_wei   numeric(78,0) not null,
    created_at    timestamptz not null default now()
);

def settle(w3, conn, withdrawal_id):
    cur = conn.cursor()
    cur.execute('select from_address, nonce from withdrawal where id = %s', (withdrawal_id,))
    from_address, nonce = cur.fetchone()

    mined = w3.eth.get_transaction_count(from_address, 'latest')
    if mined <= nonce:
        return  # the slot is still open; keep rebroadcasting or bump

    cur.execute(
        'select tx_hash from withdrawal_attempt where withdrawal_id = %s', (withdrawal_id,)
    )
    for (tx_hash,) in cur.fetchall():
        try:
            receipt = w3.eth.get_transaction_receipt(tx_hash)
        except Exception:
            continue
        with conn:
            cur.execute(
                "update withdrawal set state = 'settled', tx_hash = %s where id = %s",
                (tx_hash, withdrawal_id),
            )
        return

    raise RuntimeError(f'nonce {nonce} on {from_address} mined by an unknown transaction')

That last line is deliberate. If the slot is consumed and none of my siblings has a receipt, something signed with my key that I did not record. That is not a retry condition, it is an alert.

Head-of-line blocking is the price

Per-address serialisation means one stuck transaction blocks every later withdrawal from that address. This is not a bug to engineer away; it is the chain's model. The only real lever is how many sending addresses you run. Assigning withdrawals to lanes by hashing the withdrawal id gives independent nonce sequences and independent failure domains, at the cost of splitting the hot balance across them and needing a rebalancing job that is itself a withdrawal — and therefore must use the same allocator, not a special path.

What I would do differently

Persist the signed payload before touching the node, always. I have worked on code that broadcast first and recorded the hash after. The gap between those two lines is where a crashed process becomes an untracked transaction spending real funds, and reconciling that afterwards means scanning the chain for your own address to find out what you did.

Never expose a cancel button that deletes the row. Once a nonce is signed and broadcast, the only cancel that exists is a replacement at the same nonce: zero value, self-transfer, higher fee. A cancel that just marks the database row as cancelled leaves a live transaction on the network with a stale user expectation attached to it.

And keep nonce too low visible in metrics even though the broadcaster treats it as benign. In steady state it appears exactly when a slot has just settled. A cluster of it anywhere else is the signature of double allocation, which is the one failure in this design that costs money rather than time.

The nonce is the only part of a withdrawal that cannot be recreated after the fact. Once I started treating it as a row I allocate and a payload I persist — with the node as a broadcast medium rather than a source of truth — withdrawals stopped being the frightening part of a custodial system and became the boring part.

Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.