Preparing to Work with Stablecoins
Before you begin integrating, it’s essential for both design and engineering teams to share a deep conceptual understanding of how stablecoin issuance, movement and settlement operate in our platform. This section focuses on the “what” and the “why,” leaving the “how” (API calls) for later.
Testnets vs Mainnets
Purpose: Testnets (e.g. Ethereum Goerli, Solana Devnet) let you simulate real transfers without moving real value.
Differences: confirmation times, token faucets instead of real assets, different network parameters.
Key takeaway: your workflows must behave identically in both environments—logic for retries, confirmations and error handling shouldn’t change when you swap URLs.
Wallets, Addresses and Tokens
Wallet abstraction: a logical container for balances across chains. Does not hold keys—it simply tracks how much USDC/USDT you control.
Deposit addresses: unique on-chain addresses per wallet per chain. They map incoming tokens to the correct internal account.
Token standards: ERC-20 (Ethereum, Arbitrum, BSC), SPL (Solana), TRC-20 (Tron). Although standards differ, they share core functions: transfer, balanceOf, approval.
Confirmations and Finality
Block confirmations: each new block reduces risk of reorgs; the number you wait for varies by chain (e.g. 15 on Ethereum, 1 on Solana).
Finality models:
Probabilistic (Ethereum): risk decreases over time but never hits zero.
Absolute (some PoS chains): once confirmed, blocks are final.
Design impact: UI should show “1/15 confirmations” or “confirmed” states; engineers must reconcile late-arriving reorgs or orphaned blocks.
Idempotency and Consistency
Why idempotency? Prevents duplicate transfers when clients retry after network errors.
Atomicity guarantee: balance updates, token issuance and notification scheduling must all succeed or none do—avoiding mismatches between on-chain and internal records.
Architectural note: treat each business event (e.g. “user requested a withdrawal”) as a single unit of work identified by a unique key.
Event-Driven Architecture
Webhooks vs Polling: our platform emits events when deposits or withdrawals settle.
Benefits: near-instant notification, simplified client logic.
Design outlook: dashboards subscribe to event streams and update balances in real time; engineers build idempotent handlers to process each event exactly once.
Core Stablecoin Workflows (Conceptual Flows)
Below are the three main on-chain stablecoin flows. Each flow is presented as a high-level sequence, key states and potential edge cases.
Deposit Flow
Key teaching points
Address generation is a purely internal mapping—no on-chain transaction needed.
Confirmation waiting is asynchronous; your UI must handle “pending” vs “confirmed.”
A late chain reorg could invalidate a deposit—design jobs to detect and reverse if needed.
Withdrawal Flow
Key teaching points
Balance lock ensures funds aren’t double-spent while the on-chain transfer remains in flight.
Idempotency prevents duplicate token transfers if the client retries.
Handling on-chain failure (e.g. out-of-gas) must clean up locks and inform clients.
Internal Transfers (Netting)
When: moving stablecoins between two Bitnob wallets on the same chain.
How:
If both wallets exist internally, update balances off-chain.
Batch and net external settlement later to save fees.
Diagram:
