Building a Prediction Market From Scratch (5): Positions — the Other Half of the Account

Balance tracked a user’s cash. But cash is only half of what a prediction-market account holds — the other half is shares: how much YES (or NO) you’re holding. That half is Position, and it’s what we build next.

It matters because you can’t even describe a seller without it. A buy order locks cash; a sell order locks shares. With only Balance, the engine could model buyers and nothing else — no sellers, no trades, no payouts. Position is the seller’s side, and the thing resolution pays out on.

It’s Balance’s twin

Position has the same shape as Balance, just counting shares instead of cents: available shares you can sell or lock into an ask, frozen shares already reserved by a resting ask. Same private fields, same conserving rule, same checked arithmetic.

#[derive(Debug, Clone)]
pub struct Position {
    available: u64,   // can be sold or locked into an ask
    frozen: u64,      // reserved by a resting ask
}

lock / unlock / spend_frozen are line-for-line what Balance had. The one new verb is add — a buyer’s shares appear out of a fill:

pub fn add(&mut self, qty: u64) -> Result<(), PositionError> {
    self.available = checked_math::checked_add(self.available, qty)?;
    Ok(())
}

Building it right after Balance is almost “now do the same thing for shares” — which is the point. The money-safety discipline (private fields, conserve the total, refuse to go negative, never bare arithmetic) gets applied a second time while it’s fresh. Same shape, second proof.

How it all connects

Balance and Position are deliberately “dumb” — they don’t know who owns them or which market they’re in. The wiring lives one level up:

The keys are the whole story. Cash is kept per user — one pool, since money is fungible across markets. Shares are kept per (user, market) — you hold a separate Position in each market you’ve traded. An Order carries both a user_id and a market_id, and that’s how the engine finds the right buckets:

• place a bid → balance.lock(qty × price) — reserve cash;
• place an ask → positions[market_id].lock(qty) — reserve shares;
• on a fill → buyer’s balance.spend_frozen(...) + positions[market].add(qty); seller’s positions[market].spend_frozen(qty) + balance.credit(...).

The Order is the verb; Balance and Position are the nouns it moves; user_id and market_id are the keys that say whose and which. Keeping the value types context-free is what lets the engine organize accounts and books however it needs — and what made them trivial to unit-test in isolation.

The vocabulary it rode in with

Position shipped alongside two smaller things the coming code needs. Typed IDs — OrderId, MarketId, UserId, EventId are each a u64 newtype, not a bare number, so the compiler refuses to let you pass a UserId where an OrderId belongs. And the label enums — OrderSide (Bid/Ask), OrderType (Limit/Market), MarketSide (Yes/No), plus the status and result labels — the fixed words the engine speaks in.

One deliberate omission: no serde, no rkyv yet. The crate still depends on nothing but thiserror. Serialization derives arrive in the increment that first writes a command to the log — added when we actually need them, not before.

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

Twenty-six green. Next we compose these into Account (one balance, a map of positions) and Order, and the shapes start to act like a market. Every line is in the open repo, free, no strings.