Building a Prediction Market From Scratch (4): The Account Model — a Balance That Can't Lose Money

The repo’s empty. Where do you start?

You’d probably guess the order book, or the matching engine. Neither. I start with the account — a little type called Balance that just holds one person’s money. It looks humble, but it earns the first slot, and here’s why.

Why the account comes first

Three reasons, and they stack up.

First, it’s the foundation. Matching, settlement, every order you’ll ever place — all of it is just moving money around. If the engine is hazy about “how much does this person have, and how much is already tied up in open orders,” every layer on top inherits that haze. And money bugs are the ones that cost real money.

Second, it depends on nothing. You build from the ground up, and if you keep asking “what does this need first?” — the order book needs orders, orders need their types, all of it eventually needs an account — you end up right here, at the bottom. Start here and everything above stands on tested ground.

Third, it’s small enough to nail completely. Two numbers and a handful of methods. You can write a test for every way it might go wrong and know it’s solid before you lean on it.

What a balance really is

A person’s money isn’t one number, it’s two. There’s what they can spend right now — call it available. And there’s what’s tied up in their resting buy orders — call it frozen.

Say you bid for 100 shares at 60¢. The market has to set that 6,000¢ aside the instant you place the order — otherwise the order sits there waiting and you could turn around and spend the same money again. Cancel the order, and it comes straight back.

So the type really only does four things. A deposit adds to available. Placing an order moves money from available into frozen. Cancelling moves it back. And when an order actually fills, the frozen money leaves the account for good. Through all of that, one number must never move on its own: the total, available plus frozen. Locking and unlocking just slide money between the two buckets — the sum doesn’t budge. Guarding that sum is the whole job.

Making the bug impossible, not just unlikely

Here’s the part that actually keeps the money safe. Those two numbers are private — nothing outside the type can reach in and change them. The only way in is through a few methods, and every one of them is written to keep the total honest and to refuse to drop below zero.

So “oops, we just created money out of nowhere” isn’t a bug we’re carefully trying to dodge. It’s a sentence the type won’t let you write. Everything above — matching, settlement, all of it — can only move money through these methods, so it can’t conjure or lose a single cent.

The type itself is almost nothing:

#[derive(Debug, Clone)]
pub struct Balance {
    avail: u64,          // spendable
    order_frozen: u64,   // reserved by resting orders
}

Two unsigned integers. Unsigned is a deliberate little safety net: a balance can’t go negative, and u64 makes “negative” impossible to even write down — the compiler won’t hear of it. Money’s counted in whole cents too, never floating-point, so there’s no rounding dust drifting around.

Locking, and why the math is “checked”

lock fires every time someone places a buy order — it slides money from available to frozen, and backs out cleanly if there isn’t enough.

pub fn lock(&mut self, amount: u64) -> Result<(), BalanceError> {
    self.avail = checked_math::checked_sub(self.avail, amount)?;
    self.order_frozen = checked_math::checked_add(self.order_frozen, amount)?;
    Ok(())
}

Notice there’s no plain - or + in there. It uses checked subtraction and addition — math that hands back an error instead of quietly wrapping around. Try to lock 200 when you’ve only got 100, and checked_sub doesn’t silently spit out some enormous number the way unsigned subtraction underflows; it returns an error, the method stops, and the balance is left exactly as it was. We take this seriously enough that the project’s lint settings flat-out ban bare + and - on these values — raw arithmetic isn’t allowed anywhere near the money. The helper behind it is four lines:

pub fn checked_sub(current: u64, amount: u64) -> Result<u64, MathError> {
    current.checked_sub(amount).ok_or(MathError::Insufficient {
        needed: amount,
        available: current,
    })
}

unlock is the same thing in reverse. credit and debit handle deposits and withdrawals. spend_frozen takes the money out when an order fills. Three checked lines each — nothing clever.

The tests are the spec

Test-first means the tests came before the type — the type exists to make them pass. Read them and they’re basically a list of promises the money keeps. Two of them:

#[test]
fn lock_and_unlock_conserves_total() {
    let mut b = Balance::new(100);
    b.lock(60).expect("lock");
    assert_eq!((b.avail(), b.frozen(), b.total()), (40, 60, 100));
    b.unlock(60).expect("unlock");
    assert_eq!((b.avail(), b.frozen(), b.total()), (100, 0, 100));
}

#[test]
fn lock_insufficient_leaves_balance_unchanged() {
    let mut b = Balance::new(100);
    assert!(b.lock(200).is_err());
    assert_eq!(b.avail(), 100); // untouched
}

The first says: lock some money, unlock it, and the total lands exactly where it started. The second says: ask to lock more than you have, and it’s refused — and, crucially, nothing changes, no half-done state left behind. Run them:

$ cargo test -p zhulong-types
test result: ok. 14 passed; 0 failed

Fourteen green, before a single thing is built on top.

And quietly, this one little type has set the house rules for everything that follows: money is unsigned integer cents, anything with rules hides its insides behind checked methods, and the test gets written first. Next up: the IDs, the enums, then Position — same idea as Balance, but for shares instead of cash. One brick at a time, every line out in the open.