Post your first multi-asset transaction
Clone Formance Ledger from GitHub to build the posting, reconciliation, and metadata logic locally and post your first multi-asset transaction.
Stablecoin pay-ins are landing in engineering plans alongside Automated Clearing House (ACH) and Single Euro Payments Area (SEPA) fiat payment rails.
A system credits a 2,500,000 USD Coin (USDC) deposit on Ethereum the moment a node reports the Transfer event. The block carrying that transfer drops out in a reorg, and the deposit never finalizes. The user holds a 2,500,000 USDC spendable balance with no on-chain tokens behind the ledger credit, and nothing in your ACH or SEPA playbook tells you how to unwind it.
For a ledger engineer, this phantom balance is a correctness problem that compounds into reconciliation breaks, auditor questions, and real financial exposure once the next deposit lands on top of it.
This guide walks ledger engineers through what a stablecoin is, what backs it, how settlement and finality work, how to model stablecoins in a core ledger and use reconciliation, and what to test before production.
A stablecoin is a digital token designed to hold a steady value against a reference currency, usually one US dollar.
A stablecoin has three separate components: the token that moves on-chain, the issuer's promise to redeem each token for fiat, and the off-chain reserve of cash and Treasuries that backs the promise.
The issuer promises to redeem each token for one unit of fiat from a bank or Treasury reserve that neither your ledger nor on-chain data can observe.
Fiat-backed payment stablecoins are the dominant design. Other stablecoin types include commodity-backed tokens like PAXG, crypto-backed tokens like DAI, and algorithmic designs.
Your core ledger touches only the token, and your risk comes from the redemption promise and the reserve.
Fiat-backed stablecoins are backed by low-risk, highly liquid assets the issuer holds in reserve. These include:
Verify the backing through the issuer's monthly reserve disclosures and the credit quality of the custodian banks holding those assets. Under the Guaranteed Enforcement and Navigation of Innovative Use of Stablecoins (GENIUS) Act (enacted in July 2025), issuers must “maintain identifiable reserves backing the outstanding payment stablecoins of the permitted payment stablecoin issuer on at least a 1-to-1 basis.”
Issuers must also publish reports covering total tokens outstanding, reserve composition, average tenor, and custodian locations. Reserves cannot be reused, lent out, or pledged, except for narrow cases like meeting repo margin or raising redemption liquidity.
In March 2023, Circle disclosed that $3.3 billion of roughly $40 billion in USDC reserves sat at Silicon Valley Bank when regulators seized the bank on Friday, March 10. USDC traded down to $0.8726 on March 11 and recovered to $0.9918 by March 13, after depositors were confirmed whole. USDC tokens stayed transferable all weekend with redemption uncertain, while downstream systems still valued each token at $1.
Circle could have avoided the position-verification failure by recording issuer, custodian, and reserve disclosure as metadata on every stablecoin balance in a programmable core ledger.
When the next custodian failure hits, that metadata turns a weekend of grepping wallet addresses into a single exposure query.
A stablecoin transfer settles on the chain that issued it, and not on a central bank's balance sheet. The settlement finality depends on whatever that chain's consensus rule defines as final.
Finality is a prerequisite for the token to work as a fungible means of payment, and the finality interval differs per chain.
Ethereum produces a block every 12-second slot after two 32-slot epochs, while Solana finalizes in about 12.8 seconds. Neither Ethereum's nor Solana's finality guarantee protects you from a chain halt. On February 6, 2024, Solana block production stopped for about five hours.
The posting time determines what breaks. Post at submission and you credit a transfer that may never be mined, since a halted chain or a dropped transaction leaves a user balance with nothing behind it.
Post at first confirmation, and a block reorg can drop the block. You then owe the user and the auditor an explanation for the reversal.
Post only at finality, and the risk of crediting a user twice for a reversed transfer largely disappears, at the cost of a pending window the product must display honestly. Confirmation is not settlement, and no fixed confirmation count substitutes for each chain's actual finality rule.
Post pending on observation and settled on finality, and change the user's available balance only on the settled posting.
A core ledger should model each stablecoin as a typed asset in the same account namespace as fiat, inside one ledger, with precision fixed in the asset identifier.
Formance Ledger is an MIT-licensed, open-source, programmable core ledger that unifies fiat and digital assets with regulatory-grade traceability. One posting primitive handles USD/2 and USDC/6, with no parallel balance table to reconcile fiat and digital assets.
Four rules keep the core ledger model consistent: use typed assets per token in the identifier, model chain and custody as transaction metadata, post network gas as a separate native-token leg, and deduplicate by transaction hash and log index.
Write USD/2, USDC/6, and ETH/18, and let the ledger enforce double-entry accounting per asset with integer arithmetic in the smallest unit.
A posting of USDC cannot balance against USD without an explicit conversion posting, so a bug that credits dollars for a token deposit fails at write time.
The precision suffix prevents the ledger from aggregating USDC balances across deployments with different decimal counts as one untyped amount, and integer arithmetic avoids float-based errors.
Keep one USDC/6 asset and carry the chain and custody location as transaction metadata so finality can be applied per chain without creating a second aggregable representation of the same tokens.
Named external boundary accounts record per-chain inflows, and metadata on each deposit and sweep identifies whether the tokens sit in an Ethereum deposit address, a Solana deposit address, or the omnibus wallet.
Carrying chain and custody as metadata keeps each user's holdings whole, instead of splitting them into per-chain asset slices or duplicating them in custody accounts.
Use Formance's Assets Coloring for funding-source provenance, such as separating units still under compliance review from cleared inflows.
For any stablecoin transfer, model the network fee as a separate posting in the chain's native gas token to the fee account rather than netting the fee into the stablecoin amount.
On Ethereum, this is an ETH/18 leg, while on Solana it is a SOL/9 leg. A posting that records "2,499,999.40 USDC net of fees" invents a conversion rate nobody agreed to and breaks the stablecoin leg against the chain.
Keeping the gas leg separate also gives the treasury a per-chain gas cost it can read straight from accounts like @platform:expenses:gas:ethereum or @platform:expenses:gas:solana.
Use the chain transaction hash and log index as the external event identity in your ingestion layer. Retries and duplicate Transfer event deliveries are then detected before submitting a posting.
Preserve the same hash and log index as metadata on the observation, on any reversal after a reorg, and on any later posting if the transfer lands in a canonical block.
The three transactions below follow a 2,500,000 USDC deposit for user 88231 on Ethereum, written in Numscript, Formance's transactional language.
For stablecoin ledgering, Numscript enforces per-asset balance rules (so a USDC/6 leg cannot silently net against USD/2 or ETH/18), and lets you attach chain, transaction hash, log index, and custody location as transaction metadata on every posting.
The language makes the observation, finality, and sweep steps explicit as separate transactions that share a common event identity for reconciliation.
Observation moves the deposit from the chain boundary into the user's pending balance, finality moves pending to available, and the sweep records the gas cost in ETH while tracking the custody change via metadata.
Observation:
// STABLECOIN_DEPOSIT_OBSERVED
// Event: observe user 88231's 2,500,000 USDC deposit on Ethereum
send [USDC/6 2500000000000] (
source = @external:blockchain:ethereum:userDeposits allowing unbounded overdraft
destination = @users:88231:pending
)
set_tx_meta("event_type", "stablecoin_deposit_observed")
set_tx_meta("transaction_hash", "0xabc123")
set_tx_meta("log_index", "0")
set_tx_meta("chain", "ethereum")
set_tx_meta("custody_location", "ethereum:deposits:88231")
Finality:
// STABLECOIN_DEPOSIT_FINALIZED
// Event: finalize user 88231's 2,500,000 USDC deposit on Ethereum
send [USDC/6 2500000000000] (
source = @users:88231:pending
destination = @users:88231:available
)
set_tx_meta("event_type", "stablecoin_deposit_finalized")
set_tx_meta("transaction_hash", "0xabc123")
set_tx_meta("log_index", "0")
**Sweep confirmation:**
// STABLECOIN_SWEEP_CONFIRMED
// Event: confirm the custody sweep and record its Ethereum gas cost
send [ETH/18 2100000000000000] (
source = @platform:treasury:ethereum:gas
destination = @platform:expenses:gas:ethereum
)
set_tx_meta("event_type", "stablecoin_sweep_confirmed")
set_tx_meta("sweep_id", "swp88231")
set_tx_meta("transaction_hash", "0xdef456")
set_tx_meta("chain", "ethereum")
set_tx_meta("custody_location", "ethereum:omnibus")
The three Numscript postings credit the deposit once, finalize the deposit once, and record the gas cost without ever double-counting the same USDC tokens.
Stablecoin balance reconciliation compares three sources on three independent clocks:
Do not give the chain a daily close. With a midnight reporting cut-off, a transfer observed at 23:59 and finalized at 00:04 may appear in different reporting periods depending on the snapshot rule.
A chain reorganization (reorg), where a block that briefly appeared on the canonical chain is dropped in favor of a competing fork, can revert a balance a snapshot already captured.
If an issuer mints or burns supply between your check and the issuer's own ledger cut-off, the total supply figure you compare against is stale before the reconciliation script finishes. A batch that runs once a day finds the drift a day late.
Issuer supply belongs on the list of inputs. A single erroneous mint or burn by an issuer, even one reversed within minutes, can leave total issued supply off by orders of magnitude during the window a reconciliation script runs.
Every mint needs a supply-cap check in front of the mint. Pull issued supply from the token contract with a block height attached and treat a jump in issued supply with no corresponding mint event as an alert.
Formance Reconciliation compares ledger balances and boundary flows against chain and custodian balances, with independent cut-offs per source, and alerts when any source disagrees. Keep in-flight transfers in pending accounts so they never count toward available.
Run these five tests in a staging environment before your first stablecoin pay-in reaches production.
Point the environment at a forked chain so you can replay real blocks, and feed it a recorded event stream so you can trigger reorgs, duplicates, and halts on demand.
Each of these tests exercises posting, reconciliation, or metadata logic that lives inside the core ledger, so the fastest way to run them end-to-end is against a working ledger instance on your own machine.