Dual-currency wallet architecture

How Gold Coins and Sweeps Coins stay separate in one ledger, and what stops working when the separation is inferred rather than recorded.

One ledger, two balances

Both balances belong to one player record in one system. Not two wallets, not two services reconciled overnight, not a Sweeps Coin store bolted onto an existing Gold Coin balance.

The reason is narrower than it sounds. Any design that reconciles two stores on a schedule has a window between writes in which the two currencies are not reliably distinguishable — and that window is the one thing this model cannot have, because the distinction between the currencies is what the whole product rests on. A discrepancy in a normal ledger is an accounting problem you fix tomorrow. A discrepancy here is a question about whether a prize was earned or bought.

One player record holding two balances, with a round written against one of them A single player record contains a Gold Coin balance and a Sweeps Coin balance. A game round arrives carrying the currency it was played in, established by which callback it came through, and is written against that balance only. The currency is recorded on the transaction at the moment it is written, not inferred afterwards from the game or the player. Player record one row, one system Gold Coin balance play only, no cash value Sweeps Coin balance redeemable for prizes Game round bet + win, one message currency: SC set by which callback it arrived on written against one balance only one round, never both One player record holding two balances, with a round written against one of them A single player record contains a Gold Coin balance and a Sweeps Coin balance. A game round arrives carrying the currency it was played in and is written against that balance only. Player record one row, one system Gold Coin balance play only, no cash value Sweeps Coin balance redeemable for prizes written against one balance only Game round bet + win, currency: SC set by which callback it arrived on
One player record, two balances, and a round written against exactly one of them, carrying the currency it was played in.

Currency context travels with the round

The callback is registered per currency. A round arrives on the Gold Coin endpoint or the Sweeps Coin endpoint, and the currency is therefore established at the boundary — before anything is written, by the route the message took, rather than by looking up the game or the player afterwards.

The consequence is worth stating plainly, because it is the design decision everything else in this page depends on: every transaction is attributable to a currency at write time. Not derivable. Recorded.

Inference is a lookup that was correct when you ran it. A recorded value is correct when somebody asks you eighteen months later, after the game has been retired and the player’s session is long gone.

Reconciling a round

Four behaviours do the work, and they are worth knowing as behaviours before you go near the field shapes:

  • Bet and win arrive together, in one message. There is no window in which a stake has left a balance and the outcome has not been applied.
  • The balance in the response is the balance after the message has been applied, not before it.
  • A repeated transaction applies nothing and returns the current balance. Retrying is therefore always safe, which matters because network timeouts are the normal case rather than the exception.
  • A rollback restores once. A second rollback of the same transaction is another repeat, and is treated as one.

Those are the guarantees. The request and response shapes, the signature scheme and the status codes are set out in the wallet callback reference, and this page deliberately does not reproduce them — a field table in two places is a field table that will disagree with itself.

What breaks when the separation is soft

The failure modes are specific, and none of them shows up during integration. They show up months later, which is why they are worth designing against before there is any data.

  • A redemption you cannot evidence. Somebody asks how a Sweeps Coin balance was accumulated. If the currency on each historical round was inferred from the game rather than recorded on the transaction, the answer is a reconstruction — and a reconstruction is exactly what nobody wants to offer a regulator.
  • Questions your data cannot answer. “How much Sweeps Coin was won on this title last month” is either a query or a research project, and which one it is was decided by a schema choice made before launch.
  • A grant in the wrong balance. A promotional award that lands in the redeemable currency when it was meant for the play currency cannot be cleanly unwound once it has been played through — and the correction is itself a transaction that has to be explicable.
  • A migration under pressure. The worst version: the distinction is reconstructed after the fact, under a deadline set by somebody else, on live data you cannot take offline.

The one that is not recoverable

Three of those four can be fixed with work. The first cannot: if the currency was never written down, no amount of later engineering puts it back. Everything else on this page is a preference. This one is the reason the page exists.

Reporting consequences

Recording currency at write time is not a reporting feature — it decides what questions your data is capable of answering, whoever eventually asks them.

With the currency on the transaction, the answerable set includes how much of each currency was staked and won, per title and per period; which titles carry Sweeps Coin play at all; how a specific balance was accumulated, transaction by transaction; and what a promotional grant did after it landed. Without it, every one of those becomes an estimate with a caveat attached.

What you then do with that data is a separate decision, and it differs by route — see the platform overview for what the managed service exposes.

The wire protocol

Three commands against a callback you expose, signed, with the currency established by the endpoint the message arrives on.

The reference is the wallet callback documentation — commands, fields, signature verification, status codes — and the reasoning behind the single-wallet choice is in the seamless wallet guide.

Something here not match what you were told on a call? Tell us — the page is wrong or the call was, and either way we want to know which.