Stablecoin Payments Backend: Dual-Ledger Spring Boot
Build a stablecoin payments backend in Spring Boot: dual-ledger design, confirmation states, reorg handling and reconciliation for USDT/USDC transfers.

Short version of the design: keep an internal double-entry ledger, treat the blockchain as a second, slower source of truth, only release value after a per-chain finality depth, and run a job whose only purpose is to prove the two agree. In Spring Boot that is a ledger service, a confirmation state machine, idempotent Kafka consumers and a scheduled drift check.
Toss, the Korean fintech super-app, has reportedly started offering its users a wallet built around dollar stablecoins, and Kakao attempted something comparable before without gaining much traction. I have not seen any public detail about either company's backend, so I am not going to claim to know why one worked and the other did not. Distribution, licensing, KYC approval and FX pricing probably explain most of it. What interested me is narrower: whichever app wins users, its balances still have to be correct, and that part is plain engineering that any team can get wrong. This post is about that part.
I have worked on payment backends for years, including Open Banking PSD2 integrations, and the mistakes below are the ones I keep seeing in review. Where I describe a failure, treat it as a scenario to design against, not a war story with invented numbers.
Part 1: Why "sent" and "final" are different states
Quick glossary, only what the rest of the post needs. A stablecoin (USDT, USDC) is a token that tracks a fiat currency. The chain is the public ledger that records who holds how many tokens. Settlement, for our purposes, is the point after which you would be willing to bet money the transfer will not be reversed.
When a user taps "send 50 USDC", three separate things happen on different clocks:
- Your database records the debit. Immediate, and only your company's claim.
- Your service signs a transaction and submits it to the network's mempool, where it waits for a block producer to pick it up. A low fee or a bad nonce can leave it sitting there for a long time.
- A block includes it, and later blocks stack on top. Each extra block makes a rollback less likely. At some chain-specific depth you stop worrying.
So for a stretch of seconds to minutes, your DB and the chain disagree on purpose. The backend's job is to know, for every transfer, which of "submitted" or "settled" is currently true, and to say only that to the customer.
Part 2: Where custody ledgers actually break
The three generic failures (crediting too early, double-processing, silent drift) are real, but the ones that cost time in practice are more specific. This is the checklist I would run any design against.
Crediting before finality. The watcher sees a deposit in a block and credits immediately. A reorg drops that block, and the customer has already spent the credit. The fix is the state machine in Part 5.
Duplicate events. Kafka and every other broker deliver at least once. A restart replays the last batch, and the deposit is credited twice unless the consumer can recognise a repeat.
Decimals. USDC on Ethereum uses 6 decimals. USDT on BNB Chain uses 18, and the same ticker elsewhere may use 6. If you store a single decimals constant per asset instead of per asset-per-network, you will eventually mis-scale a transfer by a factor of a trillion. Store base units as integers and keep decimals in network config.
Nonce management. On account-model chains, every outgoing transaction from a hot wallet carries a sequential nonce. If transaction 41 is stuck on a low fee, 42 and 43 queue behind it. You need a single owner for nonce assignment, a policy for replacing a stuck transaction with a higher-fee one at the same nonce, and a way to tell the ledger that the original hash is dead and the replacement is the real one.
Gas funding. Sending an ERC-20 token costs the chain's native coin, not the token. A hot wallet full of USDC and out of ETH cannot move anything. Native-coin balance of every signer needs its own alarm.
Wrong-chain and wrong-token deposits. Users send USDT to a USDC address, or a Tron-network token to an Ethereum-format address. Some of these are recoverable by hand. The ledger must not auto-credit anything it did not expect, and unknown arrivals need a quarantine account.
Issuer freezes. Tether and Circle can blacklist addresses. A frozen omnibus address means your on-chain balance can stop moving while the ledger still shows funds. Reconciliation should flag a balance that stays unchanged while pending withdrawals pile up.
Sweeping and rebalancing. Many custodial designs give each customer a deposit address and sweep funds to an omnibus hot wallet, with a rebalance to cold storage past a threshold. Every sweep is itself a chain transaction with fees, and it moves value between your own addresses. Those internal moves must be ledger postings too, or the totals drift by exactly the sweep fees.
Travel-rule and sanctions screening. In many jurisdictions a withdrawal to an external address needs screening before broadcast. That is one more state before APPROVED, and it can reject a transfer after the customer has already seen the button turn green.
UTXO chains differ from account chains here: there are no nonces, but you manage coin selection and change outputs, and one deposit may arrive as several inputs. The state machine below still applies; only the watcher and the signer change.
Part 3: The shape of the system
The company side is fast and fully yours. The chain side is slow and outside anyone's control. The interesting engineering sits in between.

Components:
- Internal double-entry ledger. The authoritative record of who is owed what.
- Broadcast path. Turns an approved transfer into a signed chain transaction.
- Confirmation tracker. Follows the chain and walks each transfer through explicit states.
- Reconciliation job. Periodically proves ledger and chain agree.
Each of these has a real alternative, so the trade-offs deserve a word.
Broadcast path. I use a transactional outbox: the ledger posting and the "please broadcast" row commit in one DB transaction, and a poller publishes them. Change-data-capture with Debezium reads the same table from the WAL instead, which gives lower latency and no polling load, but adds Kafka Connect as a component to operate and monitor. For a wallet doing modest volume, polling every second or two is simpler and easier to reason about during an incident. For high volume, CDC pays for itself. Delivery mechanics are in my transactional outbox post.
Watcher. Polling eth_getLogs per block is easy and restartable from a stored height. Subscribing over WebSocket is quicker but drops events on disconnect, so you still need the polling backfill. I would build the poller first and treat subscriptions as an optimisation.
Failure analysis. If the broadcaster dies after signing but before recording the hash, you can resubmit the same signed bytes (same nonce, same hash) safely. If the watcher dies, it resumes from its last stored height and re-emits observations, which the idempotent consumer absorbs. If the reconciler dies, nothing breaks, but you lose detection, so its own freshness needs an alert.
Part 4: The internal ledger
A double-entry ledger writes every movement as two or more lines that sum to zero. Value is never created or destroyed inside it, only moved. That gives you a cheap invariant: if the global sum is not zero, something is wrong, and a query tells you before a customer does.
Accounts for a custodial stablecoin wallet:
CUSTOMER:{id}:USDCfor each customer's spendable balance.CUSTOMER:{id}:USDC:HELDfor amounts reserved while a withdrawal is in flight.OMNIBUS:USDCwhich mirrors the pooled on-chain address the company controls.FEES:USDCandNETWORK_FEE:USDCfor revenue and costs.IN_FLIGHT:USDCfor value that has left the customer but not yet been proven final on chain.QUARANTINE:USDCfor arrivals nobody expected (wrong token, unknown sender).
IN_FLIGHT earns its place. Without it, a withdrawal jumps from "customer has 50" to "customer has 0" and you can no longer express that the transfer is unfinished. With it, each lifecycle step is a posting that mirrors a real-world fact.
Amounts are integer base units, never floating point.
@Service
public class LedgerService {
private final JournalRepository journals;
public LedgerService(JournalRepository journals) {
this.journals = journals;
}
/** Move funds from the customer into IN_FLIGHT when a withdrawal is approved. */
@Transactional
public Journal reserveWithdrawal(UUID transferId, String customerAcct,
long amountMicros, long feeMicros) {
// Idempotency: the same transferId can only ever post once.
return journals.findByBusinessKey("WD-RESERVE-" + transferId)
.orElseGet(() -> {
long available = journals.balanceOf(customerAcct);
if (available < amountMicros + feeMicros) {
throw new InsufficientFundsException(customerAcct);
}
Journal j = Journal.open("WD-RESERVE-" + transferId)
.debit(customerAcct, amountMicros + feeMicros)
.credit("IN_FLIGHT:USDC", amountMicros)
.credit("FEES:USDC", feeMicros)
.build(); // throws if debits != credits
return journals.save(j);
});
}
}
Two details. The business_key column carries a unique constraint, so if two threads race, the database rejects the second insert; idempotency lives in the data. And build() refuses to create an unbalanced journal, so a whole class of bugs becomes a test failure rather than silent drift. Adding that constraint to a table that already holds live postings is its own risk; I cover the safe sequence in my zero-downtime database migrations guide.
One caveat on the balance read: in production take a row lock on the customer's account record (or use an optimistic version column) so two concurrent withdrawals cannot both pass the check. A double-spent mandate in Commercial VRP mandate payments is a regulatory issue, not merely a bug, and the same append-only habit carries into IBAN-name verification and fraud-liability decisions under PSD3, where every decision has to be reproducible later.
Part 5: Confirmation as a state machine
Most first versions model a chain transfer as a boolean confirmed. That flag is where reorg bugs are born. A transfer has a lifecycle, and each state should map to one ledger effect and one sentence you are allowed to show the customer.
| State | Meaning | Customer sees | Ledger effect |
|---|---|---|---|
APPROVED | Passed risk and balance checks | "Processing" | Funds moved to IN_FLIGHT |
BROADCAST | Signed and sent to the network | "Sent, waiting for network" | None |
SEEN | Found in a block, few confirmations | "On the network" | None |
CONFIRMING | Buried under N blocks, below final threshold | "Almost done" | None |
FINAL | Reached the chain's finality depth | "Completed" | IN_FLIGHT released to omnibus |
REORGED | Block it lived in was replaced | "Delayed, re-checking" | None, state rolled back |
FAILED | Rejected or dropped permanently | "Failed, refunded" | IN_FLIGHT returned to customer |
Rules I do not bend:
- Only
FINALmoves value out ofIN_FLIGHT. Seeing a transaction is a hint; finality is the fact. - A state may move backwards only through
REORGED. Everything else is forward-only, so illegal histories cannot be represented. - Finality depth is per-network configuration. Ethereum-style chains, Tron and layer-2s settle at different depths, and a single global "6 confirmations" is a bug waiting to be copied into the wrong place. Some L2s also have a gap between sequencer confirmation and L1 finality, which your config must be able to express.
Deposits mirror this, with a stricter rule: never credit spendable balance on SEEN. Show a pending line in the UI if you like, but post the spendable credit on FINAL.
A replaced transaction (the nonce-bump case from Part 2) fits as well: the original hash moves to FAILED-superseded and the replacement hash becomes the tracked one, with the ledger untouched because the reservation is keyed on the transfer, not the hash.
Part 6: Idempotent confirmation handling with Kafka
The watcher emits observations: "transaction X is in block B at height H", "block B was replaced", "tip is now H+12". I key them by transfer id so one transfer's events land on one partition in order, and the consumer advances the state machine.
The consumer has to survive duplicates, out-of-order events after a rebalance, and reorg events that contradict earlier ones. Each handler is a function of stored state plus the event, guarded by a sequence number.
@Component
public class ConfirmationConsumer {
private final TransferRepository transfers;
private final LedgerService ledger;
private final ChainProperties chains;
// ... constructor omitted
@KafkaListener(topics = "chain.observations", groupId = "confirmation-tracker")
@Transactional
public void on(ChainObservation obs) {
Transfer t = transfers.findByIdForUpdate(obs.transferId());
// Idempotency: ignore anything not newer than what we already applied.
if (obs.observedSeq() <= t.getLastAppliedSeq()) {
return;
}
long depth = obs.chainHeight() - obs.blockHeight() + 1;
long finality = chains.finalityDepth(t.getNetwork());
switch (obs.kind()) {
case INCLUDED -> t.moveTo(depth >= finality ? State.FINAL : State.CONFIRMING,
obs.blockHash());
case BLOCK_REPLACED -> {
if (t.getState() == State.FINAL) {
// Finality violated: page a human, never auto-heal money.
throw new FinalityBreachException(t.getId(), obs);
}
t.moveTo(State.REORGED, null);
}
case DROPPED -> t.moveTo(State.FAILED, null);
}
if (t.getState() == State.FINAL && !t.isSettledInLedger()) {
ledger.releaseInFlight(t.getId()); // idempotent by business key
t.markSettledInLedger();
}
if (t.getState() == State.FAILED && !t.isRefunded()) {
ledger.refundWithdrawal(t.getId());
t.markRefunded();
}
t.setLastAppliedSeq(obs.observedSeq());
transfers.save(t);
}
}
What the code deliberately avoids: it does not trust Kafka to deliver once, because observedSeq plus the row lock make replays harmless. It does not quietly repair a FINAL transfer that gets reorged; that throws and pages someone, since a finality breach means an assumption in the model was wrong and money decisions made on a broken assumption should be human ones. And the ledger calls are idempotent by business key, so a crash between the ledger write and the state update just re-runs.
For retry topics, dead-letter handling and poison messages, the patterns in the outbox and idempotent consumer write-up apply unchanged. Share groups in Kafka are interesting for queue-style scaling, but they give up the strict per-key ordering this design depends on, so test carefully before adopting them here.
Part 7: Reconciliation
The earlier parts make drift unlikely. Reconciliation makes it visible. I treat it as a product feature with its own owner, not a nightly script nobody reads.
For a custodial wallet, the ledger's total of customer balances plus fees plus in-flight value must equal what the company's addresses hold on chain, after adjusting for known pending items. Each run does three comparisons:
- Total check.
OMNIBUS:USDCledger balance against the real on-chain token balance of the controlled addresses, read at a specific block height (not "latest", which keeps moving). - Transfer check. Every journal tied to a
FINALtransfer has a matching chain transaction, and every chain transaction touching our addresses has a matching journal. The second direction is what catches deposits we never noticed, and wrong-token arrivals. - Stuck-state check. Any transfer sitting in
BROADCAST,SEEN,CONFIRMINGorREORGEDpast an agreed limit is listed for a person. StuckBROADCASTis usually a nonce or gas problem from Part 2.
The total check query is intentionally dull:
-- Run against a ledger snapshot taken at the same moment as the chain block read
SELECT
l.omnibus_micros AS ledger_omnibus,
:chain_balance_micros AS chain_balance,
l.omnibus_micros - :chain_balance_micros AS drift,
l.in_flight_micros AS pending_outbound
FROM (
SELECT
COALESCE(SUM(CASE WHEN account = 'OMNIBUS:USDC' THEN signed_amount END), 0) AS omnibus_micros,
COALESCE(SUM(CASE WHEN account = 'IN_FLIGHT:USDC' THEN signed_amount END), 0) AS in_flight_micros
FROM journal_line
WHERE posted_at <= :snapshot_ts
) l;
Time alignment is the subtle part. The ledger runs on wall-clock time and the chain on block heights. I record the height I read and compare against postings up to that block's timestamp, with a small margin. Skip this and every transfer that lands mid-run produces a phantom discrepancy, the team learns to ignore the alert, and an ignored alert is worse than none.
On a mismatch the job never edits balances. It opens a ticket carrying the block height, both numbers, the diff and the candidate transfers. Corrections go in as new journal entries with a reason and an approver. The ledger is append-only.
The same habit shows up in my deterministic replay post: if you cannot re-derive a number from recorded history, you cannot defend it.
Part 8: Observability and operational edges
Signals I would have on a dashboard from the first deployment:
- Count and age of transfers in each state, per network.
- Reconciliation drift in base units, with an expected value of exactly zero.
- Reorg events per day, per chain, plus maximum depth seen.
- Consumer lag on the observations topic.
- Native-coin (gas) balance of each signer.
- Hot-wallet versus cold-storage balance ratio.
Trace IDs should follow a transfer from the API call through the ledger posting, the broadcast and each confirmation event; my distributed tracing guide for Spring Boot covers the setup. When support gets "my money has not arrived", one trace should tell the whole story.
Part 9: The Korean won angle and regulation
Reports suggest Korea's large platforms are all positioning for won-denominated stablecoins: Toss linked to a chain built on the OP Stack, Naver tied to the exchange operator Dunamu, and Kakao with its own plans after the earlier wallet struggled. This is moving quickly and I cannot verify commercial terms, so read those specifics as reported rather than confirmed.
The engineering consequence is clearer. A won token on a layer-2 has different finality behaviour from USDT on Tron or USDC on Ethereum, which is the reason finality depth lives in configuration. Regulated issuance also tends to demand reserve reporting, meaning you must show tokens outstanding against reserves held. A proper double-entry ledger gives you that nearly for free; mutable balance columns do not.
Two regulatory threads make this skill set marketable:
- MiCA, the EU's Markets in Crypto-Assets regulation, sets expectations on safeguarding client assets, record-keeping and complaints for stablecoin issuers and service providers. A custodial wallet serving EU users needs demonstrable asset segregation and auditable records, which are ledger and reconciliation features.
- ASEAN cross-border payments are linking national QR and instant schemes, and stablecoins compete for the same corridors. I covered the QR side in my piece on EMVCo-based ASEAN QR routing. A ledger that sits cleanly between a QR scheme and a token rail is a useful thing to be able to design.
Some compliance evidence can be generated automatically; policy-as-code for DORA and NIS2 shows how I produce audit artefacts from the deployment pipeline.
What I would do differently from a first draft
- Make finality a per-network config object from the first commit, with a test that fails when a network is added without one.
- Never let a human edit a balance. Allow only a new, signed, reasoned journal entry.
- Reconcile from day one, even against fake money in staging. It is cheapest to build before anything depends on it.
- Treat "FINAL breached" as an incident, not an exception to retry.
- Keep the customer-facing vocabulary smaller than the internal one. Nobody needs to see
CONFIRMING; "Almost done" is enough.
None of this is glamorous. Whether any wallet keeps user trust through a bad day on the network will depend more on this layer than on which token it moves. Customers tolerate slow; they do not tolerate wrong.
Work with me
If you are building or rescuing a payments backend, ledger or reconciliation pipeline, you can see the systems I have shipped in my projects and reach me through the contact section. Send a short description of your transfer flow and the failure you fear most, and I will reply with a first-pass state model for it.
Related Articles
- Transactional Outbox and Idempotent Consumers in Spring Boot Payment Systems
- Open Banking PSD2 API Development
- ASEAN Cross-Border QR Payments: EMVCo Router with PayNow, DuitNow, PromptPay and QRIS in Spring Boot
FAQ
What is a stablecoin?
A token pegged to a fiat currency, most often the US dollar. USDT and USDC are the big dollar ones, and they travel over public blockchains rather than bank payment rails.
Is a stablecoin transfer instant?
Not in the sense a backend cares about. An app can show "sent" within a second, but the payment is only safe to treat as done once enough later blocks sit on top of it, and that depth differs per chain.
What is a double-entry ledger?
A ledger where each posting touches at least two accounts and the amounts net to zero. If a posting is lost or applied twice, the totals stop balancing and the bug shows up in a query instead of in a customer complaint.
Why does a wallet app need reconciliation?
Because the app's database and the chain are two independent records that can drift apart through missed events, manual fixes or fees nobody posted. A scheduled comparison surfaces the gap on your schedule, not the customer's.