Onchain mechanics

Everything here is how the game's money works at launch. The numbers are the launch settings; the admin multisig can tune them only inside ceilings compiled into the program.

The moving parts

 World server (vmangos)       Bridge (about 1 s)        Solana
 ----------------------       ------------------        ------
 money change + reason  --->  outbox -> batch    --->  economy program
 .withdraw / Exchange   --->  withdraw_to_owner  --->  your wallet
 inbox, applied by game <---  refunds, deposits,
                              corrections

• The world server is the game. It stays the authority on what happened: you looted, you repaired, you traded.
• The bridge is a service that reads every money change the game records and settles it onchain, then tells the game when the chain settled a different amount.
• The economy program is a Solana program that holds the Vault of Undermine and every game vault and enforces the limits. It is the authority on how much may leave the Vault.

Game vaults

When your wallet first plays, the bridge opens two accounts for it, derived from your wallet address:

• a vault, a Token-2022 account that holds your in-game MITH, owned by the program (not by a private key);
• a player state, which records how much you were paid today, when you last withdrew, and a counter that makes each withdrawal unique.

The server's fee wallet pays the rent for both (about 0.004 SOL). You never sign anything while you play: the server's bridge moves vault money as the game tells it to, inside the program's limits. That's why there are no Phantom popups when you loot or repair.

Your Phantom wallet only appears three times: to sign in (a message, not a transaction), and optionally to withdraw (a message that authorises the debit) and deposit (one transaction, which the server pays for).

Settlement

Every call that changes a character's money passes a reason and, for money between players, a transfer id and the other party. The game writes one row per change into an outbox, through its asynchronous database queue, so the game never waits for the chain.

The bridge picks rows up about every 200 ms, turns them into onchain operations and sends them as a batch. Events in the same second can share a transaction. Most rows settle between 0.1 and 1.5 seconds after they happen.

Characters of accounts without a linked wallet are part of the world, not the chain: money they send to linked players counts as a payout, and money they receive counts as a sink.

Transfers and escrow

Pairing. A debit and a credit with the same transfer id and amount become one vault-to-vault transfer. Each side of a trade has its own id, so each id has exactly one debit and one credit.

Escrow. Mail and auction money can wait in the game for minutes or days between the two sides. Instead of holding the debit open, the bridge parks it in an escrow vault: player to escrow when you send or bid, escrow to player when the money is taken. The escrow's owner is a program address with no private key, so nobody can withdraw it. Every row still settles within about a second, and money in transit is visible onchain.

No fees. MITH has no transfer fee, so moving Mithril between players costs nothing: what one side sends, the other receives.

Payouts are exact. Your vault receives exactly what you looted.

The daily allowance

The program pays each wallet at most 2,000,000 MITH per UTC day from the Vault. That's about 35 hours of grinding at level 60, so a person never meets it; it's there for bots farming around the clock and for exploits.

Payouts are never refused; they're clamped. In order, a payout can be reduced by:

1. payouts being paused (the circuit breaker),
2. your wallet's allowance for the day,
3. the realm's pro-rata factor,
4. what's left of the realm's budget window,
5. the Vault's balance.

The bridge also pre-clamps each payout to your remaining allowance itself, so no single request can trip the breaker for everyone.

Pending Mithril

When the chain pays less than you earned, nothing is lost. The unpaid part becomes pending Mithril:

• the game puts a hold on that amount: it leaves your bags and can't be spent while it's pending, and a chat line tells you how much is held;
• every minute the bridge pays pending amounts out, oldest first, as your allowance frees up (it resets at midnight UTC), credits them back in game and tells you in chat;
• new loot queues behind older pending money, and entries are never deleted.

A wallet with 8,000,000 MITH pending and a 2,000,000 MITH allowance is paid back over four days.

Withdraw and deposit

Withdraw: game to Phantom

Three ways in, one path out:

• a Mithril Exchange goblin beside the bankers: the withdraw page shows what you can send and offers 1%, 10%, 25%, 50% or 100% of it, or any amount you type;
• the chat command .withdraw <amount>, for example .withdraw 25000;
• the web page: Phantom signs a short text that authorises the debit. It's a message, not a transaction.

The rules, enforced by the game and again by the program:

What happens: the game checks the minimum, the cooldown and your wallet link, then takes the amount from your character. The bridge re-checks the program's rules against the chain's clock and sends withdraw_to_owner, signed by the server. The program moves the amount from your vault to your wallet's MITH account, and you receive exactly what you asked for, usually within about a second. If the chain refuses, the game gives the money back with the reason ("Your next free withdrawal is available in 12 minutes.").

The token account rent is sponsored once per wallet. If you close your empty MITH account in Phantom, the next free withdrawal is refused until it's reopened; this stops anyone farming the rent.

Deposit: Phantom to game

The web page asks the bridge to build a deposit for an amount. The bridge returns a transaction that the server's fee wallet has already signed as the payer; Phantom signs it as the owner of the tokens, once. The program moves the MITH from your wallet into your vault, and the game credits your character when the deposit is confirmed. No SOL needed, no fee.

The Vault and its budget

Budget. At most 2% of the Vault can be paid out per 24-hour window, measured when the window starts. That's 320,000,000 MITH a day on day one, enough for 160 wallets at their full allowance. When a window's demand exceeds the budget, the next window pays every payout the same fraction (pro rata), so one burst can't starve the rest of the day. The admin can't set the budget above 10% a day: that ceiling is compiled into the program.

The Cartel burn. Cartel purchases are burned in full while the Vault holds more than 75% of what it started with, partly between 75% and 50%, and not at all below 50%, where they go back into the Vault like any sink. The program reads the Vault's balance on every sink, so the rule can't be skipped. See Tokenomics.

Fixed supply. No new MITH is ever minted. Because the budget is a share of what's in the Vault, it shrinks as the Vault does and can't empty it; if the game ever asks for more than a day's budget, the rest waits as pending Mithril. See Tokenomics.

The circuit breaker

If one hour's requested payouts exceed five times the trailing 30-day hourly average (and at least 50,000,000 MITH), the program pauses payouts. Sinks and transfers keep settling; payouts are clamped to zero and flagged, which the bridge carries over as pending Mithril. Only the admin can clear the pause. It's a deliberately loud alarm: a dupe or a stolen key shows up as a stopped faucet instead of a drained Vault.

Fees

Exactly once, and reconciliation

• Every batch has a sequence number; the program accepts only the next one. A batch that may or may not have landed is resolved by reading the program's last sequence number, then either confirmed or re-sent under the same number, so nothing settles twice.
• Each withdrawal carries the wallet's next withdrawal number, so two wallets' withdrawals can be in flight at once and none can land twice.
• The attempt and the rows it settles are written to the database before anything is sent.
• Reconciliation compares, for every linked account, the money its characters hold in game (plus corrections not yet applied, minus changes not yet settled) with its vault onchain. Any difference is drift and fails the check. A watcher runs it on the live realm around the clock; it has reported zero drift.

Addresses

The economy program, the MITH mint and the Vault are published on this site at launch, with how to check each one on an explorer: see Tokenomics. Settlement times measured in our tests are on the Tested page.