Economy

Economy is audited financial infrastructure for Paper 1.21.11 servers. It provides exact-cent wallets, Vault compatibility, player banks, checking accounts, signed debit cards, reserve-backed withdrawals, loans, government payroll, taxes, ATMs, chest shops, and public APIs for future business, robbery, technology, property, and finance plugins.

Accounting model

• All values are stored as integer minor units. Floating-point values never become authoritative balances.
• Player and institutional spending accounts cannot go negative.
• Every balance mutation produces an immutable ledger record with a type, time, source, destination, actor/integration identity, correlation key, memo, and metadata.
• Administrative issuance, destruction, transfers, and balance corrections are separately audited.
• Checking balances are bank liabilities. Deposits move wallet cash to bank reserves and create the matching checking liability; withdrawals redeem the liability against reserves. A bank's business account automatically backstops reserve shortfalls before a withdrawal fails.
• If reserve and business liquidity are both exhausted during a withdrawal, wire, or debit-card purchase, the operation fails, the incident is audited, and the bank plus its accounts are frozen as DISTRESSED until authorized staff resolve it.
• Vault represents wallet money only. Checking accounts require the Economy API or a signed debit card.

Player lifecycle and circulation

New players receive $1,000 immediately. The remaining $4,000 vests after 30 minutes of recorded playtime. Both amounts are configurable.

After 60 days without joining, all wallet and checking balances are settled into the Staff account. Up to the configured $5,000 starter grant is then destroyed from that reaped value. If the player returns, a new starter cycle begins and the player is told to contact staff concerning the prior balance. These movements are auditable.

Money owed for fines, taxes, and loans is collected immediately from checking accounts and then the wallet. Any remainder becomes a debt that garnishes future credits at the configured percentage. The default priority is fines, taxes, then loans, at 100% garnishment.

Death losses and cards

Wallet death loss follows a configurable Gaussian distribution (default mean 5%, standard deviation 1%). PvP losses go to the killer; environmental losses go to Staff. Repeated victim/killer pairs inside the anti-farming cooldown cause no loss.

Debit cards contain no balance. They carry a signed serial that maps to one server-side checking account. On death, all duplicate items with the same serial are collapsed into one chance roll, preventing duplicates from increasing drop odds. The first hacking attempt consumes the serial's server-side hacking opportunity; every physical duplicate then reports it as already consumed. Actual compromise behavior belongs to the future Technology plugin.

Holding a card and running /bank card revoke revokes that server-side serial, so every original or duplicated item with the serial immediately stops working.

Banks

Players submit bank applications and authorized reviewers approve or deny them through /bank review. Each approved bank has:

• one reserve account;
• one owner-controlled business account for capital, interest, and fee profit;
• configurable owner-set checking APR;
• configurable wire percentage and flat fees, capped by government policy;
• a government-set reserve ratio;
• one or more WorldGuard bank regions and registered ATM blocks.

Players may have one checking account per bank and accounts at multiple banks. Balance viewing, account opening, deposits, withdrawals, debit-card issuance, wires, and loan repayment require the appropriate bank region or ATM.

Daily checking snapshots feed weekly average-balance interest. Interest is funded from the bank business account, never minted. Insufficient interest and payroll payments become retryable arrears.

Loans

Bank owners can offer fixed-rate amortized loans with APR, payment frequency, term, missed-payment threshold, and optional collateral reference. Borrowers explicitly accept offers and may repay early without a penalty. Principal returns to reserves; interest enters the bank business account and can be income-taxed. Reserve requirements are checked before disbursement.

CollateralProvider is the stable Property boundary. Collateral validation, locking, release, and seizure activate when Property registers its adapter. No fake property ownership behavior is embedded in Economy.

Taxes and payroll

• Income tax is a configurable flat withholding on /pay, /wire, government/business payroll, and bank loan-interest revenue. Loan principal is not income.
• Balance tax uses marginal brackets across a player's wallet plus checking accounts.
• Property tax uses a flat amount after a configurable tax-free property allowance through PropertyTaxProvider.
• Sales tax is deducted from chest-shop seller proceeds.
• Revenue enters the main government treasury.
• Daily balance/property assessment is partitioned deterministically into 24 hourly groups.

Government assigns each job to the main treasury or a configured department:<key> account. Payroll runs once per real-world day after the configured time. A player must have 15 recorded online minutes in the prior 24 hours. Ineligible players receive nothing; insufficient budgets create arrears that retry after funding.

Chest shops and analytics

Look at a chest containing the exact custom item and use /shop create <sell|buy> <unit-price> [quantity]. Purchases are direct: wallet if no card is held, or only the held card's checking account. Insufficient funds never fall back to another payment method.

Custom identity uses Paper's complete serialized ItemStack with amount normalized to one, covering names, lore, enchantments, attributes, custom model data, and persistent data. /shop inspect prints the identity hash.

/shop export writes a 30-day aggregate CSV containing day, item identity, material, display snapshot, quantity, gross value, seller proceeds, tax, transaction count, and average unit price.

Storage

SQLite is the default and enables WAL, foreign keys, busy timeout, startup backups, and exact backup retention. MySQL is an alternative single-server backend using HikariCP. Do not point multiple Minecraft servers at the same database; cross-server transaction coordination is intentionally out of scope.

Build and install

1. Build from the repository root with gradlew.bat :Economy:build on Windows or ./gradlew :Economy:build elsewhere.
2. Install Vault. Install WorldGuard for bank-region enforcement. Government is optional but required for government payroll.
3. Copy the current build/libs/MCSkylines-Economy-*.jar into the Paper server's plugins directory.
4. Start and stop once, then review every file under plugins/Economy/ before enabling taxes or MySQL.
5. Create and capitalize Staff, treasury/department, and bank budgets deliberately. Tax rates ship disabled at 0%.

The public EconomyApi is registered through Bukkit's services manager. Integrations should use unique idempotency/correlation keys and never modify the database directly.

Player money workflow

Wallet money is the balance shown through Vault and is used by /pay and ordinary chest-shop purchases. Checking money belongs to a specific bank and is accessed at that bank's WorldGuard region or registered ATM. Holding a valid debit card selects its checking account for supported purchases; the system never silently falls back from a failed card payment to the wallet.

New players receive the immediate starter portion on first initialization. The vested portion is granted only after the configured recorded playtime. Credits may be intercepted by outstanding fine, tax, or loan debts according to the configured priority and garnishment percentage.

Set up and use a bank

1. A prospective owner runs /bank apply <name>.
2. A reviewer opens /bank review and approves or denies the application.
3. Capitalize the approved bank's reserve and business accounts before customers withdraw or receive loans.
4. Register one or more WorldGuard regions with /bank region add <bank-id> <region>.
5. Look at a block and register an ATM with /economy atm create <bank-id>. Remove it by targeting it and using the matching remove action.
6. Set the bank's checking APR and wire fees with /bank policy. Government-authorized staff set the reserve ratio separately.
7. Customers enter a bank region or use its ATM, open a checking account, and then deposit wallet money. Deposits increase reserves and the customer's checking liability in one ledger operation.
8. Issue a card only at the bank or ATM. A card is owner-bound and points to one checking account; it carries no stored balance.

Withdrawals and card/wire purchases monitor liquidity. If reserves and the bank business account cannot cover redemption, the operation fails and the bank is marked distressed and frozen for staff resolution. Use /bank resolve only after correcting the underlying funding problem.

Debit cards and wires

Hold the genuine debit card in the main hand when making a card-backed shop purchase or wire. /wire <player> <amount> [memo] requires the sender to be at the card's bank or ATM and the recipient to have at least one checking account. The recipient's first active checking account is used. Bank percentage and flat wire fees are charged according to policy.

If a card is lost, hold another copy of the same serial and use /bank card revoke. Revocation invalidates every duplicated physical copy. Card duplication does not create balances or extra hacking attempts; server-side serial state is authoritative.

Chest shops: complete setup and use

1. Place a chest in a protected location and put at least one exact example item inside it. The example determines the complete item identity, including custom model data, persistent data, name, lore, enchantments, attributes, and other components.
2. Look directly at that chest while holding the exact item in the main hand.
3. Run /shop create sell <unit-price> [quantity] to sell chest stock to players, or /shop create buy <unit-price> [quantity] to buy items from players. quantity is the base number transferred per interaction and defaults to the configured value when omitted.
4. Use /shop info while looking at the chest to confirm mode, item, quantity, and price. /shop inspect prints the held item's identity hash when two visually similar custom items need to be compared.
5. Right-click the chest to transact. A normal click uses the configured normal multiplier; sneaking uses the configured sneak multiplier. The final quantity is the shop quantity times that multiplier, capped at 2,304 items.

For a sell shop, the plugin removes stock from the chest before attempting payment. If payment fails, stock is restored. Purchased items go to the buyer's inventory and overflow drops naturally at the buyer. For a buy shop, the chest must have enough capacity and the seller must carry the exact item; failed owner payment restores the seller's items.

Wallet payment is used unless the buyer holds a genuine card in the main hand. Card payment accepts only a valid card owned by that buyer and draws only from its checking account. Sales tax is removed from seller proceeds when enabled. The shop owner receives an online notification or a queued notification on the next login.

Active shop chests cannot be broken, exploded, or moved by pistons. Remove the shop registration first with /shop remove; ownership is checked unless the caller has the administrative removal permission. Removing the registration does not delete the chest or its inventory.

Loans

A bank owner creates an offer with principal, APR, payment count, payment interval, allowed missed payments, and optional collateral type/reference. The borrower must visit the relevant bank or ATM to accept. Disbursement checks reserve policy and places principal in the borrower's financial flow without treating principal as taxable income.

Scheduled payments divide principal and interest according to the fixed amortization schedule. Principal returns to bank reserves; interest enters the business account and may be taxed as income. /bank loan pay makes the scheduled wallet payment and /bank loan payoff attempts the remaining payoff. Collateral operations work only when a provider such as Property has registered the referenced collateral type.

Taxes, payroll, and debt

Income withholding applies only to configured income-producing flows. Balance tax uses marginal brackets across wallet plus checking balances. Property tax requires Property's provider. Sales tax applies to chest-shop seller proceeds. Assessment work is split across the day so all players are not processed in one tick.

Government payroll uses job salary policy and the mapped treasury or department account. A player must meet the prior-24-hour active-play requirement. Underfunded payroll and bank interest become arrears rather than minted money and retry after funding.

Economy testing checklist

1. Verify the immediate and vested starter grants with a fresh player.
2. Open two banks, checking accounts at both, and test region/ATM location enforcement.
3. Deposit, withdraw, issue/revoke a card, and test a wallet purchase and card purchase separately.
4. Test sell and buy chest shops with normal click, sneak click, insufficient stock, full chest, full inventory, invalid card, and insufficient owner funds.
5. Make a wire, create and accept a loan, run one payment, and test a collateral-backed offer when Property is installed.
6. Enable each tax at a small staging rate and confirm destination treasury balances and ledger entries.
7. Underfund a bank and a payroll account to confirm distress/arrears behavior, then fund and resolve them.
8. Run /shop export and reconcile the 30-day CSV totals against sample sales.