How it's built

The parts

WoW Onchain is a handful of parts that each do one job, and a website around them.

YOUR BROWSER
  benilla client  <---->  Phantom
        |                 (sign in, withdraw, deposit)
        | websocket
        v
THE REALM
  relay  ---->  game server + database
                   |            ^
            outbox |            | inbox
                   v            |
                 bridge --------+
                   |            ^
                tx |            | confirmations
                   v            |
SOLANA
  economy program + MITH token -+

The website (this one) adds the Exchange and Withdraw pages, the public Ledger of every money event, and the Goblin Market.

Signing in

1. Connect Phantom. The page asks Phantom to sign a short text message that names this site and a one-time challenge. It's a message, not a transaction: nothing moves and no fee is paid.
2. The sign-in service checks the signature, then opens your game account. The first time a wallet signs in, it gets an account of its own, and that wallet belongs to that account for good.
3. One-time realm credentials. The service hands the client a short-lived login for the realm, used once. There is no password to steal or reuse.
4. The client connects to the realm through the relay, on the same site.

The realm's own ports aren't open to the internet: the relay is the only way in, and it only talks to the realm.

Playing

The client starts in about the time it takes to download it (about 12 MB, compressed) and then streams the game's data as it needs it, in small pieces, from a data host that sits close to the realm. About 40 MB gets you to character select, and a couple of hundred MB covers your first minutes in the world.

The realm's own art, like the Mithril coin, the loading screens and custom mounts, comes as a small overlay of separate files. The game's files are never modified.

Everything you do in the world goes to the realm, which decides what happens, exactly as a 2006 server did: movement, combat, loot, quests, trades and the auction house.

A coin's journey

You kill a boar and loot 15 silver, which on this realm is 1,500 Mithril. Here's what happens next.

1. The game records it. The realm adds 1,500 to your money and writes a row to its outbox with the reason (loot) and your new balance, in the same database transaction. Every money change in the game, whether loot, vendor, repair, training, trade, mail or auction, writes one row with its reason.
2. The bridge gathers rows for up to about a second and packs them into transactions of about ten wallets each, so a busy realm sends few transactions, not one per coin.
3. The program applies each row according to its kind:
   • a payout (loot, quests, selling to vendors) moves MITH from the Vault to your game vault, within your daily allowance and the realm's budget;
   • a sink (repairs, training, flights, vendor purchases, boosts) moves MITH from your game vault back to the Vault; Cartel purchases are burned instead while the Vault is well stocked;
   • a transfer (trade, mail, auction) moves MITH from one vault to another, through escrow while it's in transit.
4. Confirmation. The bridge listens for the confirmation, marks the rows settled and records the transaction signature. The coin's row shows up on the Ledger with a link to the transaction. It takes about a second from the loot to settled.
5. When the chain pays less than you earned (your daily allowance is used up), the bridge writes a row to the game's inbox, and the game holds the difference as pending Mithril, paid as the allowance frees up.

So the game is always the source of truth for what happened, and the chain is the source of truth for who holds the tokens. The outbox and inbox are how the two keep each other informed.

Exactly once

A payment system has two classic failures: paying twice and paying never. Both are designed out:

• Every batch has an id and every withdrawal a per-wallet sequence number. The program accepts each once.
• After a restart, the bridge resolves first. It checks every transaction it had in flight against the chain before it sends anything new, so a crash in the middle of a batch is harmless.
• The game's side is atomic. A money change and its outbox row commit together, so the bridge never sees a change the game didn't make, and never misses one it did.
• Reconciliation compares every character's money with its vault on chain. Any difference fails the check and raises an alert. We've migrated the bridge three times and moved to a new token once in testing, and moved the whole realm to a new server; each time the books matched to the copper.

Withdraw and deposit

• Withdraw at a Mithril Exchange, with .withdraw <amount>, or on the Withdraw page. The game takes the Mithril from your bags first, then the bridge moves it from your game vault to your own wallet. You pay no fee; it lands in about a second. Details: Withdraw: game to Phantom.
• Deposit at a Mithril Exchange or on the Exchange page. The bridge builds a transaction, you approve it in Phantom (the server pays the network fee), and the game credits your character when it confirms.

The economy program

The MITH mint is Token-2022 with 6 decimals, on-chain metadata, no transfer fee, no freeze authority, and after the one genesis mint no mint authority: nobody can create MITH. See Tokenomics. More: Mithril and the economy and Onchain mechanics.

Keys

What each key can and can't do, and how your game vault is protected: Security and custody.

Running it

• The realm and the chain are checked against each other, account by account, around the clock, with an alert on any drift, and a circuit breaker pauses payouts on a spike.
• The public Ledger shows every money event with its transaction, so anyone can audit the realm.
• New money features run on a separate test realm first, with their own test accounts, before they reach the public realm.
• Updates to the page don't kick anyone. A new client is swapped in while you play and picked up at your next reload. Server restarts are announced in game.
• Every change can be rolled back. The previous bridge, program and configuration are kept until the new ones have proven themselves.

Built on

• vmangos, the open-source vanilla server, for the realm.
• benilla for the browser client.
• Solana and its Token-2022 program for the token, and Phantom for wallets.

The parts that touch money (the outbox and inbox in the game, the bridge and the economy program) are our own, and are what the rest of these docs describe.