How to design a digital wallet
The first sections are free. The deep dives, level expectations and quiz are part of Pro.
On this page
The problem
A digital wallet moves money between accounts inside one payments app: A pays B, A's balance goes down and B's goes up, and the two changes must stand or fall together. At a million transfers a second no single database keeps up, so balances are spread across shards by account id, and nearly all transfers touch two shards. The answer turns on two ideas: committing a transfer across shards without a lock that spans them, and recording each balance change as an immutable event so any past balance can be rebuilt and checked rather than taken on trust.
Clarifying questions
| Ask | Why it matters | A typical answer |
|---|---|---|
How many transfers a second, and does each one touch two accounts? | The rate decides whether one database can hold the balances. If it can't, sharding is forced, and with it a transfer that crosses machines, which is where most of the difficulty lives. | A million transfers a second, each debiting one account and crediting another, so 2 million balance updates a second. Assume one relational node handles about 1,000 transactions a second. |
Is a wallet-to-wallet move the whole scope, or do I also handle cards, banks and currencies? | Pay-in and pay-out involve third parties with their own failure modes and would take the whole round. Currency conversion adds a rate and a second ledger. | Wallet to wallet in a single currency. Cards, bank payouts and foreign exchange are out of scope. |
What does transactional mean here: money is neither created nor lost, or also that nobody sees a half-finished transfer? | Conservation of money is a must. Hiding the in-between state is far more expensive and may not be needed, so it's worth pinning down before choosing how to commit across shards. | Money must not be created or lost in a transfer. A short window in which the sender's balance has dropped and the receiver's hasn't risen yet is acceptable, as long as it resolves. |
Do we need to answer what a balance was at a past moment, with proof? | A current-balance table can answer today's balance. Proving a past one changes the storage model from a mutable row to a replayable history. | Yes. Auditors may ask for any wallet's balance at any past time and want to verify it, not just read it. |
What availability do we promise, and may a transfer be delayed rather than refused when a node is down? | The target decides how many copies of the balance data we keep and whether the commit path may wait on a single machine. | 99.99% availability. A transfer may take longer under failure, but a money move that was acknowledged must not be lost. |
Do clients retry, and do they send an id with each transfer? | A retried transfer without an id can become a double payment unless something else deduplicates it. If the client sends a transaction id, the service can make a repeat harmless. | Yes. The transfer call carries a transaction_id chosen by the client, and the same id sent twice must move money once. |
Non-functional requirements
| Requirement | What it forces |
|---|---|
1 million transfers a second | At about 1,000 transactions a second per relational node, 2 million balance updates need about 2,000 nodes, so the balances have to be split across shards by account id, and a transfer usually spans two shards. The transfer path has to work without a lock held across machines, and the stateless layer in front must scale sideways. |
99.99% availability | That leaves about 52 minutes of downtime a year, so no shard's data may live on one machine: the event log of each shard is replicated with a consensus protocol, a leader failure is handled by election rather than a page, and a transfer in flight when a coordinator dies is finished or undone from a durable record. |
Transactional: money is never created or lost in a transfer | Each transfer is a debit and a credit that end in the same state, done or undone. Across shards that means a protocol with a compensating step and a status record for each phase, with the debit first so money is not spendable in two places while the transfer is in flight. |
Reproducible: the full history can be replayed to check every balance | Balance changes are recorded as immutable events rather than as updates to a row, and the code that applies an event to a balance must be deterministic: no clock, no randomness, no call to another system. A balance at any moment is then a replay, and a code change can be tested by replaying old events. |
Estimates
| Quantity | Working | Result | What it sizes |
|---|---|---|---|
Database nodes for the balance updates | A million transfers a second × two balance updates each = 2 million updates a second; 2,000,000 ÷ 1,000 per node = 2,000 nodes. At 100 a node: 20,000 nodes; at 10,000 a node: 200 nodes | About 2,000 relational nodes, between 200 and 20,000 depending on node speed | Why, at the node speeds assumed here (100 to 10,000 transactions a second), one database is out and sharding by account follows. |
Load on one shard, and how often a transfer stays on one shard | 2 million updates ÷ 2,000 shards = 1,000 updates a shard a second; a cross-shard transfer makes one update on each shard it touches, so about 1,000 transfers touch each shard a second. With accounts spread over 2,000 shards, the chance both parties share a shard is about 1 ÷ 2,000 = 0.05% | About 1,000 transfer touches a second per shard, and about 99.95% of transfers cross shards | What one shard's consensus group must accept per second, and why the cross-shard path is the normal path, not an edge case. |
Events written a day | 2 million balance changes a second × 86,400 seconds = 172.8 billion, about 173 billion a day; ÷ 2,000 shards = about 86 million events a shard a day | About 173 billion events a day, about 86 million per shard | How fast each shard's event log grows, and why a restart that replays from the beginning is not an option without snapshots. |
Events a year, for the audit replay | 173 billion a day × 365 days = about 63 trillion a year; per shard, 86 million × 365 = about 31 billion a year | About 63 trillion events a year across the system, about 31 billion per shard | The size of a replay that proves last year's balances were unchanged by a code change: run per shard, from a snapshot, in parallel. |
Downtime that 99.99% allows | 0.01% × 525,600 minutes a year ≈ 52.6 minutes a year; 0.01% × 43,200 minutes a month ≈ 4.3 minutes a month | About 52 minutes a year, about 4 minutes a month | How fast failover of a shard leader or a coordinator must be: automatic, within seconds, not a person paged. |
Core entities
| Entity | What it holds |
|---|---|
Account | One wallet. Its balance is state derived from events, kept materialized for fast reads. |
Transfer command | A request to move money: an intent, not yet a fact. It may be refused. |
Event | An applied debit or credit, immutable once written. The balance of an account is the sum of its events. |
Phase status row | The coordinator's durable memory of one transfer: which steps are done, so a restart can finish or undo it. |
The API
| Endpoint | Notes |
|---|---|
| The client picks transaction_id and reuses it on a retry. The wallet service looks the id up first: a known id returns the recorded outcome without touching balances. Amount is an integer in minor units. In this design the response status is one of done, failed or pending; pending means the debit committed and the credit is still being applied, and the client polls or gets a push. |
| Served by a read replica of the account's shard, so reads don't compete with the state machine that commits transfers. It may trail the leader by the replication delay; say so when asked. |
| Loads the newest snapshot before the time, applies the shard's events up to it and returns the result. In this design the response also carries the event sequence the replay stopped at, so the caller can repeat the replay and get the same answer; that repeatability is the proof the auditors want. |
The high-level design
Step 1 of 5
One service, one balance store
Start with the smallest thing that moves money. A stateless wallet service takes the transfer call, checks that the sender has the funds, and runs one database transaction that lowers one balance and raises the other. Balance reads go to the same store. The service holds no state, so it scales by adding instances. With a single database, a transfer is one local transaction and the hard problem doesn't exist yet. It can't stay this simple: one relational node handles about 1,000 transactions a second, and we need 2 million balance updates a second.
What breaks first
The deep dives
A transfer across two shards. A pays B a dollar and the two balances live on different machines. What does the wallet service do on each shard, in what order, and how does the transfer end correctly if the service crashes between the debit and the credit?
Reproducible balances. Auditors want A's balance at noon last Tuesday and a way to verify it, not a number to trust. What does each shard record per transfer, how is a past balance rebuilt from it, and what happens when the node holding the records dies?
A concept that helps here: Replicated state machines and consensus logs
A concept that helps here: Replication and read replicasConcepts this guide uses
- Sagas and two-phase commit
- Sharding and partition keys
- Idempotency keys
- Event sourcing and ledgers
- Replicated state machines and consensus logs
- Replication and read replicas
Sources
- Digital Wallet: key concepts and system design (notes on the digital wallet chapter of System Design Interview volume two)
- Wikipedia: Two-phase commit protocol
- microservices.io: Pattern: Saga
- Apache Seata documentation: TCC mode
- Apache Seata blog: Distributed transaction Seata and its three modes
- The Raft consensus algorithm (raft.github.io)
- Wikipedia: Raft (algorithm)
- Apache ZooKeeper: a distributed coordination service for distributed applications
- RocksDB wiki: Home
- Martin Fowler: Event Sourcing
- System Design Academy: Digital wallet system design interview