TON Deposits: Idempotency and Exact Credit
Crypto / FinTech · TON deposits
The blockchain confirms a transfer, but its delivery event may arrive twice. How can a platform credit TON once and tell a safe retry from conflicting data?
Give the event a verifiable identity
The platform's TON deposit handler derives an external ID from the network, wallet address, transaction LT and normalized hash. The supplied external_id must match both this formula and the Idempotency-Key header. A sender cannot invent a new “unique” identifier for a transfer already seen.
Before crediting, the code checks the minimum amount and whether deposits are blocked for the user. An exact retry returns the existing result; a retry with conflicting parameters fails. A second check detects the same chain transaction even under another external ID.
Balance and ledger change together
The deposit record, balance increment and TON ledger entry are written inside one database transaction. The balance row is locked. If the ledger write fails, there must be no untraceable credit. User notification happens after the commit; a notification failure does not undo the funds.
Jetton uses a separate handler and atomic units, because token amounts should not be rounded through floating-point arithmetic.
Why it matters
A retried webhook or queue delivery becomes an ordinary safe event. Operators can investigate delivery, chain transaction identity and internal balances separately.