Confirmations, Finality, and Reorgs: How Settlement Actually Works

A wallet shows one confirmation and calls it done. That's fine for a personal transfer between two accounts you control. It's a bad model for a business deciding whether to ship a package or credit a balance, because one confirmation tells you almost nothing about whether the transaction will still be there in an hour.

This piece is about the mechanism most integrations get wrong: what a confirmation actually measures, why the threshold differs by network instead of being one global number, and what happens to a payment when the chain briefly disagrees with itself underneath it.

A confirmation is a probability, not a switch

Think of writing something down in pencil. You can erase it a minute later at no cost. Now imagine that page gets photocopied, then bound into a book, then shipped out to a hundred libraries. You could still theoretically change that original sentence. Practically, it isn't happening.

A blockchain confirmation works the same way, just compressed into blocks instead of print runs. The first confirmation means a transaction was included in a block the network currently treats as canonical. It says nothing about how permanent that inclusion is going to be. Every block stacked on top afterward makes rewriting that history a little more expensive, a little less likely, until at some depth the probability of reversal rounds down to zero for practical purposes.

That's the whole idea behind a confirmation threshold. It isn't a formality or a delay tacked on for show. It's the number of blocks it takes, on a given network, for the probability of reversal to drop below a level your business is willing to accept. Get the number wrong in either direction and you've either shipped goods against a transaction that can still vanish, or made customers wait through confirmations that were buying you nothing.

Why one policy doesn't fit every business

If a single confirmation were always enough, nobody would bother configuring a threshold at all. The reason policies exist is that the same blockchain event carries wildly different consequences depending on what's riding on it.

Take a $15 digital newsletter subscription. If the rare reversed transaction slips through, the cost is a support ticket and maybe a refund. A merchant selling that product has every reason to prioritize a fast checkout experience over squeezing out the last basis point of certainty.

Now take an electronics store shipping a $2,000 order. Physical goods can't be un-shipped once they leave the warehouse, so the merchant reasonably wants more confidence before triggering fulfillment, even if it costs the customer a few extra minutes of waiting.

Push it further: an institutional platform processing a $5,000,000 deposit. Here the tolerance for being wrong approaches zero, because reversing a decision at that scale isn't a support ticket, it's a real loss on the books.

The blockchain producing all three transactions is identical. The acceptable risk is not. That's the entire argument for letting confirmation policy track business risk instead of forcing every merchant through the same rule regardless of what's on the line. Suward's two-stage model, accepted for goods and success for money, exists precisely so a $15 subscription and a $5,000,000 deposit can gate different actions at different points on the same timeline. → Accepted vs. Success covers how to pick a threshold for each side.

What a reorg actually does to a pending payment

Occasionally, a network briefly produces two competing versions of its most recent history. Two blocks get mined around the same time, or a validator set disagrees for a few slots, and for a short window there are two candidate chains instead of one. Eventually the network converges: one version becomes canonical, the other gets discarded. This is called a chain reorganization, or reorg for short, and it's a normal, expected property of distributed consensus, not a sign that something is broken.

The part that matters operationally: a transaction sitting in a block that gets discarded doesn't just quietly stay confirmed. It has to be re-evaluated against whatever chain wins. In most cases the transaction gets picked back up and included again a block or two later, on the winning chain, and nothing changes from the merchant's point of view except a short delay. In rarer cases it doesn't reappear at all, at least not before the payment's window runs out.

That's why continuous monitoring, not a single lookup, is the right design. A gateway that checks a transaction once and marks it confirmed has no way of knowing the block it relied on got dropped five minutes later. Suward keeps watching every payment through its confirmation window rather than treating "seen once" as "settled." If a reorg hits a payment that hasn't reached accepted yet, the payment is re-verified automatically against the new canonical chain. If the transaction is genuinely gone once that window closes, the payment reports failed; a static-wallet deposit undone the same way reports invalidated, with nothing ever credited on either side.

The sequencing is the actual guarantee here, not just the fact that reorgs get handled. Reorg resolution happens before a payment reaches accepted, never after. By the time your code sees accepted, the question "could this still get reorganized out" has already been answered. There's no later stage where a webhook says one thing and a subsequent reorg quietly takes it back. → Settlement & finality covers the full stage model this rests on.

Why Polygon needs 128 confirmations and Ethereum needs 12

Confirmation depth isn't a scorecard where a bigger number means a worse network. It reflects how each chain reaches finality, and different consensus designs get there through different mechanics. GET /v1/blockchains reports the live figure for every network Suward supports, and the spread across it is real: Ethereum, Arbitrum, Optimism, Base, and Plasma each require 12 confirmations, BSC requires 15, and Polygon requires 128.

That 128 isn't Polygon being slow or unreliable. Polygon's PoS chain produces blocks fast, roughly every couple of seconds, and its finality model leans on stacking enough of those quick blocks to reach an equivalent safety margin, rather than on a smaller number of slower, more expensive-to-produce blocks the way some other chains do. A shallow confirmation count on a chain with fast, cheap block production would leave a much wider window for a reorg to undo something than the same count would on a chain where each block costs more to produce. Depth and block time are trading against each other; the actual safety margin at the end is what matters, not the raw block count used to get there.

The practical takeaway for an integrator: don't hardcode any of these numbers, and don't try to reason about safety by counting blocks yourself. Read status. Suward has already translated "128 blocks on Polygon" and "12 blocks on Ethereum" into the same two words, accepted and success, calibrated so both mean the same thing about risk regardless of which chain produced them. Rebuild that math yourself and you're re-deriving a threshold you already get for free. Get it wrong in either direction and the cost shows up later: too shallow, and you've absorbed reorg risk you didn't need to; too deep, and customers waited for margin that was already spent. → Which assets and networks to accept covers how this same per-network variance shows up in fees, not just confirmation depth.

Designing around uncertainty instead of ignoring it

None of this is unique to blockchain. Distributed systems generally have to account for network partitions and nodes that briefly disagree with each other. A reorg is that same category of problem showing up in a payment context. What separates production-grade payment infrastructure from a demo is whether it was built assuming this happens, or built assuming it's rare enough to ignore.

A gateway that credits a balance the instant it first sees a transaction is optimizing for a demo. It looks fast right up until the first reorg reverses something it already told a customer was final. A gateway that keeps monitoring through the confirmation window, resolves reorgs before crediting anything, and only then reports accepted is optimizing for what actually happens at real volume, where uncommon events stop being uncommon simply because you're running enough transactions for them to show up.