RoyalBank

A Vault-backed banking plugin for Paper — upgradeable account tiers, daily interest, secure transfers, and GUIs you configure down to the slot.

RoyalBank gives your players a real bank: a separate, safe balance they grow through account tiers and interest, kept completely under your control through config. It's built to slot into the eco suite (EcoItems, EcoShop, and the companion RoyalAuctions, RoyalBazaar, and EconGuard plugins) but has no hard dependency on any of them — drop it onto any server with Vault and an economy plugin and it just works.

---

Features

• Upgradeable account tiers — each level has its own max balance and interest rate. Players work their way up; you decide the ladder.
• Deposits, withdrawals, and player-to-player transfers, with a configurable confirmation threshold for large transfers.
• Daily interest that's claim-driven, not paid by a background timer — so it never silently ticks against an offline or full account.
• First-deposit bonus, paid once per account and tracked persistently. Emptying and re-depositing won't farm it.
• Fully config-driven GUIs — every menu is a YAML file in the EcoMenus dialect (buttons placed by row/column, click effects, %placeholders%, and sounds), consistent with the rest of the Royal suite.
• Optional EcoItems-style upgrade costs — charge money and items (vanilla or custom) to unlock a tier.
• Built-in anti-abuse / RMT detection — large-transaction alerts and balance-velocity flagging, with an audit trail for enforcement.
• PlaceholderAPI support and SQLite or MySQL storage — SQLite out of the box, MySQL for a shared/networked setup.

---

How interest works

Interest is claim-driven. Players receive it on join (if enabled) or via /bank interest and the GUI button, subject to a cooldown. The cooldown is only consumed when interest is actually paid — so an empty or already-full bank never wastes a claim.

• max-daily-interest caps each claim; the cooldown governs how often a claim can happen.
• A per-level cap lets you tune (or disable) interest tier by tier.
• The first-deposit bonus is paid once per account, tracked in the database.

Upgrade costs

Charge whatever you like to unlock a tier — money, items, or both:

upgrade-cost:
  money: 25000000.0
  items:
    - "minecraft:GOLD_BLOCK:64"
    - "ecoitems:enchanted_gold_block:20"
    - "ecoitems:bank_upgrade_core:1"

Vanilla requirements reject custom/PDC-tagged EcoItems, so a custom gold-block item can't be used to satisfy a plain minecraft:GOLD_BLOCK cost.

---

Anti-abuse & RMT detection

RoyalBank watches money moving in and out of the bank to surface laundering and real-money trading — for example, a brand-new account suddenly parking a fortune.

• Large-transaction alerts fire when a single deposit/withdraw or a total balance crosses a threshold you set.
• Balance-velocity flagging catches accounts gaining wealth unusually fast.
• Alerts go to the console, to online staff with royalbank.alerts, and to an optional Discord webhook. Staff are told the pending flag count on join.
• Review with /bank admin flags and inspect a suspect with /bank admin transactions <player>.

If EconGuard is installed, RoyalBank also reports every movement to its shared audit ledger, so a player's banking activity is correlated with their auction and shop activity in one place — which is what catches an RMT chain that launders through an auction sale before it ever reaches the bank.

---

Commands

Players

Command	Action
/bank	Open the bank GUI
/bank balance	Show your bank balance
/bank deposit <amount>	Deposit money
/bank withdraw <amount>	Withdraw money
/bank upgrade	Upgrade your account tier
/bank interest	Claim available interest
/bank info	Account details

Admins

Command	Action
/bank reload	Reload config, messages, and GUIs
/bank admin balance <player>	View a player's balance
/bank admin setbalance / addbalance / removebalance <player> <amount>	Adjust a balance
/bank admin setlevel <player> <level>	Set a player's tier
/bank admin reset <player>	Reset an account
/bank admin transactions <player>	View transaction history
/bank admin backup	Create a database backup
/bank admin flags [clear]	Review or clear anti-abuse flags

Permissions

Node	Default
royalbank.use	true
royalbank.deposit	true
royalbank.withdraw	true
royalbank.upgrade	true
royalbank.admin	op
royalbank.alerts	op

GUI buttons enforce the same permissions as the equivalent commands.

PlaceholderAPI

If PlaceholderAPI is installed, RoyalBank registers placeholders for balance, level, level name, max balance, remaining bank space, next-interest time and amount, max interest, and combined (bank + purse) balance — e.g. %royalbank_balance%, %royalbank_level_name%, %royalbank_bank_space%, %royalbank_combined_balance%.

---

Reliability

• Every money operation moves through Vault and persists in a single database transaction. If the write fails, the Vault side is rolled back — money is never created or destroyed.
• SQLite or MySQL, both via HikariCP. SQLite is the default (zero setup, ideal for one server); switch to MySQL to share bank accounts across a network. JDBC drivers are downloaded at runtime by Paper's library loader — nothing is bundled into the jar.
• Online players' accounts are cached in memory; GUIs and placeholders read the cache instead of hitting the database.
• Reads and writes don't block each other — SQLite runs in WAL mode with a busy timeout; MySQL uses pooled connections.
• /bank admin backup takes a clean, consistent snapshot via SQLite VACUUM INTO, off the main thread (SQLite only — on MySQL, use your database's own backup tooling).
• Existing databases are migrated automatically on startup.
• RoyalBank waits for the Vault economy provider to register rather than disabling on enable — so plugin load order can never silently kill it.

---

Requirements

• Paper 1.21+ (tested on Paper 26.2)
• Vault and a Vault-compatible economy provider (EssentialsX, CMI, etc.)
• Optional: EcoItems or another PDC-tagged custom-item plugin, PlaceholderAPI, EconGuard

Installation

1. Drop RoyalBank.jar into your plugins/ folder.
2. Start the server — config files generate under plugins/RoyalBank/.
3. Edit config.yml, messages.yml, and the gui/*.yml files to taste.
4. Run /bank reload after any edits.

---

Part of the suite

RoyalBank pairs with RoyalAuctions, RoyalBazaar, and EconGuard — but every one of them runs standalone. Full admin and developer documentation lives on the GitHub repository.