Engineering9 min read
The Wallet System: How Every Transaction Flows Through One Place
Every financial operation on Cometbid Social — escrow holds, SafePay transactions, subscription payments, and internal transfers — flows through a single wallet system. Here's how we designed it.
When a platform handles other people's money, the architecture underneath matters more than the interface on top. Every financial operation on Cometbid Social — escrow holds, SafePay transactions, subscription payments, and internal transfers — flows through a single wallet system. This isn't an accident. It's a deliberate design decision that makes every dollar traceable, every operation atomic, and every balance provably correct.
01Why One Wallet for Everything
Early in the design process, we faced a choice: give each feature its own balance system (a SafePay balance, an escrow balance, a subscription credit pool) or unify everything under a single wallet per user. We chose unification, and the reasons are both practical and philosophical.
Scattered balances create scattered problems. When money lives in multiple places, reconciliation becomes a nightmare. Which balance does a refund come from? What happens when a user wants to use their escrow release to pay for a subscription? How do you show someone their "total" when totals are spread across three systems? These aren't edge cases — they're daily operations.
A single wallet means a single source of truth for all financial state. Your balance is your balance. Deposits go in, holds are placed for active transactions, releases move funds to recipients, and withdrawals take money out. Every feature — SafePay, Escrow Contracts, subscriptions, internal transfers — interacts with the same wallet through the same interface. One system to audit. One system to secure. One system to trust.
02Anatomy of a Transaction
Every financial operation in the wallet system is recorded as an immutable ledger entry. The wallet balance is never stored as a mutable field that gets incremented or decremented — it's calculated from the complete history of ledger entries. This distinction matters enormously for correctness and auditability.
A ledger entry contains: the transaction ID, timestamp, type (deposit, withdrawal, hold, release, transfer, fee), amount, currency, source wallet, destination wallet, reference ID (linking to the escrow or SafePay transaction that triggered it), and status. Once written, a ledger entry is never modified or deleted. Corrections are made by writing compensating entries, just like in traditional double-entry bookkeeping.
This approach means we can reconstruct the exact state of any wallet at any point in time. If a user says their balance was wrong last Tuesday at 3pm, we can prove exactly what it was and why. The audit trail is complete and immutable. There's no "balance drift" problem where rounding errors or race conditions cause numbers to diverge from reality over time.
03How Funds Flow: Escrow, SafePay, and Subscriptions
Let's trace a typical fund flow through the system. A user deposits money via an external payment method — this creates a credit entry in their wallet ledger, increasing their available balance. When they initiate a SafePay transaction, the system places a hold: the funds remain in their wallet but are earmarked and unavailable for other use. The ledger records a hold entry.
When the transaction completes successfully, the hold converts to a transfer: a debit from the buyer's wallet and a corresponding credit to the seller's wallet. The seller now has available funds they can withdraw or use for their own transactions. If the seller wants to cash out, a withdrawal creates a debit entry and triggers an external payment to their bank account or payment method.
Subscription payments follow the same path — a recurring debit from the user's wallet to the platform's revenue wallet. Escrow milestones are holds that release incrementally. Internal transfers between users are paired debit-credit entries. Every path through the system uses the same primitives: credit, debit, hold, release. The wallet doesn't care where the instruction came from — it just processes ledger entries according to strict rules.
04Security and Isolation
Financial systems fail in predictable ways: money appears from nowhere (credit without matching debit), money disappears (debit without matching credit), or operations partially complete (funds leave one wallet but don't arrive in another). We prevent all three through double-entry bookkeeping principles and atomic transactions.
Every credit in the system has a matching debit somewhere. When money enters the platform (user deposits), the system credits the user's wallet and debits the platform's funding account. When money moves between users, one wallet is debited and another credited in the same atomic operation. If either side fails, neither side commits. There is no state where money exists in transit — it's either in the source or the destination, determined by a single atomic write.
Wallet operations are isolated at the database level. Concurrent operations on the same wallet are serialized to prevent race conditions. Two simultaneous SafePay transactions can't both spend the same funds — the second one will see the reduced available balance after the first hold is placed. This serialization adds a few milliseconds of latency but eliminates an entire class of financial bugs that have cost other platforms millions.
05The Credit System: Platform Currency You Earn
The wallet doesn't only hold money you deposit. It also holds credits — platform-issued currency that you earn through activity. Complete an achievement? Credits. Refer a friend who signs up? Credits. Contribute to an open-source project on the platform? Credits. Write a review after a SafePay transaction? Credits.
Credits flow through the same ledger as fiat. They're not a separate system or a gamification layer bolted on top — they're first-class ledger entries with the same immutability, the same audit trail, and the same atomic guarantees. Your wallet shows your fiat balance and your credit balance side by side. Both are real. Both are spendable.
What can you spend credits on? Subscription discounts, boosted project visibility, reduced SafePay transaction fees, premium profile features, and priority support. Credits reduce the cost of using the platform for people who actively contribute to the community. The more you participate, the less you pay. We'll expand the full credit earning mechanics, redemption rules, and anti-abuse safeguards in a dedicated article later in this series.
06Bitcoin and Crypto: A New On-Ramp to the Wallet
For users in regions where traditional banking rails are slow, expensive, or inaccessible, crypto offers a practical alternative. Bitcoin support adds a new on/off ramp to the wallet — deposit BTC, and it either converts to a fiat equivalent at market rate or remains as a crypto balance you can hold and spend.
The ledger-based architecture makes this integration clean. A crypto deposit is just another credit entry, denominated in a different currency. SafePay transactions and escrow holds can be funded from crypto the same way they're funded from fiat. The wallet doesn't care about the source of value — it tracks what's there, who owns it, and how it moves.
This isn't a speculative feature or a DeFi play. It's a pragmatic solution for cross-border transactions where a freelancer in Nigeria and a client in Canada need to exchange value without paying 8% in wire transfer fees and waiting 5 business days for settlement. Crypto settles in minutes at a fraction of the cost. The full architecture — exchange integration, conversion logic, volatility handling, and regulatory compliance — will be covered in a dedicated article later in this series.
07What's Next
Beyond credits and crypto, we're exploring additional fiat on/off ramps that reduce the friction of moving money in and out of the platform. Future iterations will support more local payment methods across regions — mobile money in Africa, UPI in India, PIX in Brazil — reducing fees and settlement times for users in different countries.
Multi-currency support is also on the roadmap — allowing users to hold balances in multiple currencies and convert between them at market rates. This is essential for a platform serving a global community where a buyer in euros needs to pay a seller who wants to receive in naira.
The wallet system is designed to grow. Each new currency type, each new payment method, each new on-ramp is just another ledger entry type plugged into the same infrastructure. The foundation handles it all.
A platform that handles other people's money needs to get it right. The wallet system is the financial backbone — simple for users, rigorous underneath. Every dollar accounted for, every transaction traceable, every operation atomic. The complexity lives in the infrastructure so users never have to think about it. They see a balance. They see a history. They trust that the numbers are correct. That trust is earned one ledger entry at a time.
EngineeringProductPayments
Never miss a post
Subscribe to get the latest TCTF articles delivered to your inbox.
