This is the story of that definition.

The Problem

Imagine a user has ₹10,000 in their wallet. They place a ₹4,000 bid. Now you have to represent something your balance column was never designed to express:

Available Balance = ₹6,000
Held Balance      = ₹4,000
Total             = ₹10,000

The ₹4,000 isn't gone. It's reserved — committed to a bid that might win, might lose, might get outbid in the next second. A single balance field can't represent "this money exists, but you can't spend it right now." You need two numbers, and you need an invariant that never breaks:

Available + Held = Total wallet funds

If that invariant ever drifts — if a bug lets Available + Held exceed the user's real funds — you haven't shipped a backend bug. You've created money that doesn't exist. That distinction shaped every decision that followed.

Architecture, roughly:

                 ┌──────────────┐
                 │   Bid API    │
                 └──────┬───────┘
                        │
                        ▼
                 ┌──────────────┐
                 │ Wallet Logic │
                 └──────┬───────┘
                        │
             ┌──────────┴──────────┐
             ▼                     ▼
      Available Balance       Held Balance
             │                     │
             └──────────┬──────────┘
                        ▼
                  PostgreSQL
            (transactions + row locking)
                        │
                        ▼
              Settlement / Refund
                 (idempotent)

1. Money Is an Integer, Not a Float

The first decision has nothing to do with auctions — it's about representation. float64 cannot represent currency exactly; rounding errors compound silently across thousands of operations until your ledger and your bank statement disagree.

// Never this:
amount := 100.50

// Always this — smallest currency unit, as an integer:
amount := int64(10050) // ₹100.50, stored as paise

The financial layer represents monetary values as int64 paise rather than floating-point values, throughout. A 2% platform fee on a ₹10,000 win is 1000000 * 2 / 100 = 20000 paise — deterministic, exact, reproducible.

2. Available vs. Held: The Core Invariant

This is the structural decision everything else depends on. A wallet in PriceFlow isn't one number:

CREATE TABLE wallets (
    user_id UUID PRIMARY KEY,
    available_balance BIGINT NOT NULL DEFAULT 0,
    held_balance       BIGINT NOT NULL DEFAULT 0
);

When a bid is placed, money moves from available to held — not out of the wallet, just out of reach:

Before:  Available ₹10,000  |  Held ₹0
Bid ₹4,000 →
After:   Available  ₹6,000  |  Held ₹4,000

Nothing left the user's total. The invariant held. This is the number I check first whenever I'm debugging anything wallet-related — if it's ever violated, the bug is upstream of whatever I'm looking at.

3. Concurrency: The Bug That Doesn't Show Up in Testing

Here's the failure mode that doesn't appear until real concurrent load hits it. Two bids arrive for the same user at nearly the same instant — a genuine race, or a network retry firing twice. Both read available_balance = 1000 before either has written anything. Both see enough funds. Both proceed. Both hold ₹1,000.

The user now has ₹2,000 held against ₹1,000 they actually had. That's a double-spend, and it will never show up in single-user manual testing — only under real concurrent access, which is exactly when you can least afford it.

The fix is a row-level lock, held for the duration of the check-then-write:

func (r *WalletRepository) GetWalletForUpdate(ctx context.Context, tx pgx.Tx, userID string) (*Wallet, error) {
    row := tx.QueryRow(ctx, `
        SELECT user_id, available_balance, held_balance
        FROM wallets WHERE user_id = $1
        FOR UPDATE
    `, userID)
    // ...
}

FOR UPDATE forces a second concurrent request for the same user to wait until the first transaction commits or rolls back — at which point it reads the updated balance and correctly sees there isn't enough left. Different users never block each other; only genuine contention on the same row serializes.

4. The Outbid Scenario — Where It Gets Interesting

Alice bids ₹4,000. Bob bids ₹5,000. Alice's hold needs to release the instant she's overtaken:

Alice before:  Available ₹6,000  |  Held ₹4,000
Bob outbids →
Alice after:   Available ₹10,000 |  Held ₹0
Bob after:     Available ₹5,000  |  Held ₹5,000

But this release has to be safe against duplication. If the same "release Alice's hold" operation fires twice — a retried event, a duplicate message — you get:

Release ₹4,000
Release ₹4,000 (again)
→ Available = ₹14,000

Money appeared from nowhere. The fix isn't "try not to send it twice" — distributed systems will retry. The fix is designing every financial operation so a retry is a no-op, not a second transaction.

5. Idempotency: A Retry Must Never Become a Second Transaction

Every hold, release, and settlement in PriceFlow carries a reference_id tying it to the specific bid or payment it belongs to:

Settlement ID: SETTLE-123

First request:  process → transfer money → mark completed
Retry:           SETTLE-123 already processed → do nothing

The principle: idempotency isn't a nice-to-have for financial operations, it's the baseline requirement. A payment provider's webhook will retry. A network call will time out after the money already moved. The system has to recognize "I've already done this" before it does it again.

6. Database Transactions: Nothing Financial Happens Halfway

A single settlement touches at least four things: debit the buyer's hold, credit the seller, record the platform's fee, close the hold. The important part is that these operations are not independent writes — they share the same transaction boundary. If any of them fails independently, you get a state no reconciliation should ever have to explain:

Buyer debited ✅
Seller credited ❌
Service crashed

That's not a bug ticket, that's money that's unaccounted for. So every related financial write happens inside one database transaction, all-or-nothing:

dbTx, err := pool.Begin(ctx)
defer dbTx.Rollback(ctx) // no-op once committed

updateBalances(ctx, dbTx, ...)
createLedgerEntry(ctx, dbTx, ...)

return dbTx.Commit(ctx)

If the ledger insert fails after the balance update succeeded, the whole transaction rolls back — the balance update never happened either, as far as the database is concerned.

7. The Auction Lifecycle Gates the Money

PriceFlow's auctions move through SCHEDULED → OPEN → CLOSED → MATCHED. Financial operations aren't allowed to ignore where the auction actually is:

OPEN    → bids accepted, holds placed
CLOSED  → no new bids
MATCHED → winner determined, winning hold persists
          → settlement workflow begins
          → financial settlement completes

A bid that arrives after CLOSED, or a settlement attempt on an auction still OPEN, is a bug the financial layer has to refuse — not because the money math is wrong, but because the timing is wrong. State and money are coupled on purpose.

8. When a Service Crashes Mid-Transfer

This is the scenario that actually matters: the process dies between "debit buyer" and "credit seller." What does the system look like on restart?

The answer isn't a clever recovery trick. The database transaction prevents a crash from leaving a partially committed financial update, while idempotency makes a retry safe if the operation is attempted again. They solve different failure modes, and the system needs both: the transaction guarantees nothing is left half-done, and idempotency guarantees that whatever retries afterward doesn't repeat what already succeeded.

9. Disputes and Refunds Ask the Same Question Twice

A buyer disputes a delivery. If the dispute is upheld, funds get refunded instead of settled to the seller:

Settlement completed → Dispute raised → Dispute accepted → Refund initiated

The interesting question was never "how do I refund ₹5,000." It was "how do I guarantee ₹5,000 can never be refunded twice" — the same idempotency and transaction-boundary thinking from settlement, applied to the reverse direction of the same money.

10. What Could Go Wrong — and What Stops It

That table is the actual content of the article. Everything above it is just the reasoning that produced each row.

The Real Lesson

Building the wallet wasn't the hard part. Adding and subtracting integers is not a hard problem.

The hard part was accepting that a financial system isn't correct because the balance looks right while everything runs normally — it's correct only if it stays right when requests are duplicated, services crash mid-write, auctions change state underneath a pending operation, and the same event gets processed twice because a network timed out. I designed each part with failure in mind. If something goes wrong, the invariant should still hold.

That's what I took from building PriceFlow's financial layer: correctness isn't the normal case. It's every abnormal case, handled on purpose.

In PriceFlow, every bid holds money. When you bid ₹500 on an auction, that ₹500 gets locked in your wallet so you can actually pay if you win. If someone outbids you, your hold gets released. When the auction closes, the winner's money moves into escrow, and eventually to the seller.

That sounds simple until you ask: what happens if this operation runs twice?

A network retry, a client that times out and resubmits, two goroutines racing on the same bid — any of these can trigger the same wallet operation more than once. If "hold ₹500" runs twice by accident, you've locked ₹1,000 instead of ₹500. If "release hold" runs twice, you might release money that should still be protected. In a system handling real money, this isn't a theoretical edge case — it's the first thing that has to be correct, before anything else.

Why floats were never an option

Before getting into idempotency, one smaller but equally non-negotiable decision: money in PriceFlow is stored as integers — paise, not rupees, and never as a float. Floating-point arithmetic has rounding behavior that's fine for most things and completely unacceptable for money. Storing everything as an integer count of the smallest currency unit sidesteps the entire category of bug.

Making operations idempotent

The core guarantee doesn't live in application code — it lives in the database. Every wallet transaction is inserted with a reference_id tied to the real-world event that caused it (a specific bid, a specific refund), paired with the transaction type:

func (r *WalletRepository) CreateTransaction(
    ctx context.Context,
    tx *WalletTransaction,
) error {
    query := `
        INSERT INTO wallet_transactions
            (id, user_id, type, amount, reference_id, sequence_id, created_at)
        VALUES
            ($1, $2, $3, $4, $5, DEFAULT, NOW())
        ON CONFLICT (reference_id, type)
        DO NOTHING
    `

    _, err := r.db.Exec(
        ctx, query,
        tx.ID, tx.UserID, tx.Type, tx.Amount, tx.ReferenceID,
    )

    return err
}

That ON CONFLICT (reference_id, type) DO NOTHING is doing the real work, backed by a unique constraint on exactly those two columns:

CREATE UNIQUE INDEX idx_wallet_transactions_reference_type
ON wallet_transactions(reference_id, type);

If ReleaseBidHold for a given bid gets called twice — because of a retry, a timeout, or a race — the second insert simply doesn't happen. The database rejects the duplicate before it can double-release or double-charge anything. This is deliberately a database-level guarantee rather than an application-level check like "query first, then insert if not found" — a check-then-insert in application code has its own race window between the check and the insert; a unique constraint closes that window entirely, because the database itself is the single source of truth for "has this already happened."

Hold and release under concurrent bidding

The flow when a bidder gets outbid:

func (s *WalletService) ReleaseBidHold(
    ctx context.Context,
    userID string,
    bidID string,
    amount int64,
) error {
    referenceID := "bid:" + bidID

    if err := s.repo.ReleaseHold(ctx, userID, amount); err != nil {
        return err
    }

    return s.repo.CreateTransaction(ctx, &WalletTransaction{
        UserID:      userID,
        Type:        TransactionTypeHoldRelease,
        Amount:      amount,
        ReferenceID: referenceID,
    })
}

End to end, the sequence looks like this:

New bidder places higher bid
        ↓
Wallet.Hold(new bidder)
        ↓
Previous bidder becomes outbid
        ↓
Wallet.Release(previous bidder)
        ↓
HOLD_RELEASE transaction recorded

The reference_id of "bid:" + bidID means that no matter how many times a release gets triggered for that specific bid — a retry from the caller, a duplicate event — only one HOLD_RELEASE transaction is ever recorded for it. The balance can't drift from repeated calls, which matters most exactly when load is highest: several bidders competing on the same auction, each triggering holds and releases in quick succession.

Escrow: protecting money across a multi-day window

Once an auction closes, the winner's held funds move into escrow rather than being released. From there, the money stays protected through shipping, delivery, and a protection period, before a settlement step pays the seller and deducts the platform fee.

This is where the same reference_id + type pattern matters most, at a different point in the system. A settlement worker runs periodically to find escrows whose protection period has expired and pay them out. If that worker crashes mid-run and restarts, it can't be allowed to pay the same seller twice for the same escrow — the exact same uniqueness guarantee that protects a bid hold from being released twice is what protects a seller payout from being issued twice.

What I'd do differently

I'd apply this same idempotency pattern as a deliberate first decision for every new financial operation in the system, rather than reasoning about it case by case as each one came up. Once you've seen how cleanly a unique constraint closes the race that a check-then-insert leaves open, there's no reason not to make it the default for anything touching money from day one.

PriceFlow lets sellers create auctions and buyers compete through real-time bids. The engine behind this needs to do three things well: handle many bids arriving close together, always know the current highest bid instantly, and — because that state lives in memory for speed — not lose it if the service restarts.

The first two are a data structures problem. The third turned out to be where most of the real engineering happened.

Designing the bid book: a heap plus a hashmap

For each auction, I needed fast answers to two different questions, and no single data structure answers both well.

Question one: who's currently winning? A max-heap keeps the highest-priority bid at the top at all times, so checking the current leader is O(1), and inserting a new bid is O(log n) — no re-sorting a list every time a bid comes in.

Priority isn't just price, though. Two bids can land with the exact same price, and under real concurrent load, they can even share the exact same timestamp (clock resolution has limits). Without a tiebreaker that's always unique, the heap has no correct answer for which one goes first. So priority resolves in three steps:

go

func (b *BidBook) Less(i, j int) bool {
    if b.bids[i].Price != b.bids[j].Price {
        return b.bids[i].Price > b.bids[j].Price       // higher price wins
    }
    if !b.bids[i].SubmittedAt.Equal(b.bids[j].SubmittedAt) {
        return b.bids[i].SubmittedAt.Before(b.bids[j].SubmittedAt) // earlier wins
    }
    return b.bids[i].SequenceNo < b.bids[j].SequenceNo  // final, always-unique tiebreaker
}

SequenceNo is a counter, incremented atomically on every bid, so there's always exactly one right answer, even if price and timestamp both tie.

Question two: find this exact bid, fast. Say a bidder wants to cancel. The heap is great at "who's winning" but terrible at "find bid #4821" — that's an O(n) scan through the whole structure. So alongside the heap, I keep a hashmap (byID) mapping bid ID to a pointer to that same Bid struct. It's not a copy of the data — both the heap slice and the hashmap point at the identical objects in memory, kept in sync every time a bid is added or removed.

The concurrency bug that taught me the most

Go's container/heap package doesn't just call Push and Pop — a single heap operation from outside can trigger internal calls to Len, Less, and Swap too, as part of re-sorting. My first instinct was to lock only Push and Pop, since those are the "obvious" writes. That leaves a window: if Less or Swap run unprotected while another goroutine is mid-write, that's still a race, just through a different door. All five methods needed the same lock.

That decision avoided one class of bug. It caused another.

When I added bid cancellation, I needed a way to remove any bid from the heap, not just the top one — so each Bid stores its own current position (index), updated every time Swap runs. Cancellation became: look up the bid by ID, get its index, call heap.Remove at that position.

I wrote Remove() to lock the mutex first, then call heap.Remove(). That looked correct. It wasn't. Internally, heap.Remove() re-sorts the heap by calling back into my own Less and Swap methods — and each of those also tries to acquire the same mutex, because I'd locked all five methods individually. Go's sync.Mutex isn't reentrant: a goroutine can't lock a mutex it's already holding. So the moment I called cancel, the program froze — permanently, with no error, no panic, just silence.

I found this by testing through a real client, not through a static analysis tool — I placed a bid, cancelled it, and watched it hang instead of returning. The fix was removing the outer lock from Remove() itself; the individual heap methods it calls already lock correctly on their own, so wrapping the whole thing in another lock was both redundant and, in this case, fatal.

That bug is the one I'd tell an interviewer about first. It's not a bug you can spot by reading the code once you have to actually trace who's calling what, and understand that "more locking" isn't automatically "more correct."

Surviving a restart: the Replay Engine

The heap and hashmap live in memory because that's what makes them fast. It also means a crash or restart wipes every active auction's bid state — unless something durable exists to rebuild from.

The approach: every domain event (right now, BidPlaced) gets persisted as it happens, through a separate Persistence Service talking over gRPC. On startup, a Replay Engine reads the saved events in order and re-applies them, rebuilding the heap and hashmap from scratch. Because ordering is fully deterministic price, then time, then sequence number replaying the same events always produces the same state back.

Building this surfaced two bugs that are easy to miss if you're not specifically looking for them.

Bug one: replay silently reassigned sequence numbers. My Push method always handed out a new sequence number from the atomic counter — correct for a brand-new bid, wrong during replay. A bid that originally held ticket #5 could come back with a completely different number, scrambling the tie-order that made the auction fair in the first place.

Bug two: the counter didn't catch up after replay. Even with bug one fixed, a freshly restarted BidBook starts its sequence counter at zero. If replay restores 50 old bids with numbers up to #50, the next genuinely new bid after restart would also get handed #1 colliding with a number that already exists. The fix for both:

go

func ReplayBidBook(itemID string, events []BidPlacedEvent) *BidBook {
    bb := NewBidBook(itemID)
    var maxSeq int64

    for _, e := range events {
        bid := e.ToBid()          // keeps the ORIGINAL SequenceNo, doesn't reassign
        heap.Push(bb, bid)
        if bid.SequenceNo > maxSeq {
            maxSeq = bid.SequenceNo
        }
    }

    bb.seqCounter = maxSeq        // new bids after restart continue counting up from here
    return bb
}

Both were confirmed with a test: feed in three fake bid-placed events, then check that the rebuilt bid book has the right count, the right bid on top, and a counter correctly caught up to the highest number replayed.

What's still open: this proves the replay logic is correct against a known set of events. It doesn't yet prove the full loop capturing real events live as bids come in, persisting them to Postgres, and recovering an actual running service after a real crash. That's the next piece of work, not something I'm claiming is done.

What I'd do differently

I'd write the concurrency tests for Remove() before adding it, not after — the deadlock would have surfaced in a test run instead of a hung client. I'd also design the locking strategy for the whole heap interface up front, as one decision, rather than arriving at "lock all five methods" one bug at a time. It worked out, but it was slower than it needed to be.