XzBank

XzBank

XzBank is a server-side Paper plugin that provides wallet money, Coins, player transfers, money notes, XP vouchers, a Server Bank, transaction history, an optional Vault economy provider, PlaceholderAPI values, and an API for XzPlugin integrations.

Requirements

• Paper or Purpur matching the plugin's declared Paper API version.
• Java 21.
• XzCore 0.3.x or newer. XzCore is required.
• SQLite storage is built in and is the only supported database backend for this release.

Optional integrations:

• Vault, when other plugins need XzBank to register as the server economy provider.
• PlaceholderAPI, for %xzbank_*% placeholders.

Installation

1. Stop the server cleanly. Do not use Bukkit /reload for JAR updates.
2. Back up the existing plugins/XzBank/ folder and its xzbank.db database before replacing an existing installation.
3. Place the XzCore JAR and XzBank JAR in plugins/.
4. Start the server and confirm XzCore is ready.
5. Run /xzbank version, /xzbank status, and /xzbank health as an administrator.
6. Run /bank update to review configuration updates. Use /bank update confirm only after reviewing the plan and retaining a backup.

A fresh installation creates the plugins/XzBank/ configuration folder and the SQLite database xzbank.db.

Core player commands

Command	Purpose	Permission
/bank	Open the Bank menu.	xzbank.use
/bal	Show wallet balance.	xzbank.balance
/bal top	Show the money leaderboard.	xzbank.top
/pay <player> <amount>	Send wallet money.	xzbank.pay
/coins	Show Coin balance.	xzbank.coins.balance
/coinpay <player> <amount>	Send Coins to another player.	xzbank.coins.pay
/bank note money <amount>	Create an allowed money note.	xzbank.note.money
/bank note xp <amount>	Create an allowed XP voucher.	xzbank.note.xp

Money notes and XP vouchers use the configured safe denominations. A note is stored in the database and can only be redeemed once.

Administration

xzbank.admin includes the individual administrator permissions declared in plugin.yml. Common diagnostics are:

/xzbank version
/xzbank status
/xzbank health
/xzbank history <player>
/bank update

Administrative money, Coin, Server Bank, tax, audit, migration, and configuration commands require their corresponding xzbank.admin.* permission. Grant these permissions only to trusted staff.

Configuration

All default configuration files are stored under plugins/XzBank/.

File	Purpose
config.yml	SQLite filename, money scale, note settings, limits, fees, and GUI layout.
economy.yml	Economy-provider enablement, Vault registration, currency symbol, and player commands.
coins.yml	Coin naming, starting balances, balance policy, and Coin commands.
server-bank.yml	Server Bank enablement, starting balance, and treasury command options.
taxes.yml	Tax categories and rates.
audit.yml	Audit queue and flush settings.
migration.yml	EssentialsX migration safeguards.
messages.yml	Player-facing messages.

Keep storage.type: sqlite. Do not point XzBank at a shared or network-synced SQLite file. Back up xzbank.db, xzbank.db-wal, and xzbank.db-shm together while the server is stopped.

Vault compatibility

When Vault is installed and economy.yml enables registration, XzBank registers its wallet as a Vault economy provider. This supports normal player balances, account creation, deposits, withdrawals, and formatting.

Vault bank-account methods are intentionally unsupported. XzBank's Server Bank is managed through XzBank administrator commands and is not exposed as a Vault bank account. Servers whose plugins require Vault bank support should use a provider that implements it.

PlaceholderAPI

When PlaceholderAPI is available, XzBank registers the xzbank expansion. Available placeholders are:

%xzbank_balance%
%xzbank_balance_formatted%
%xzbank_coins%
%xzbank_coins_formatted%
%xzbank_xp_balance%
%xzbank_xp_balance_formatted%
%xzbank_total_deposited%
%xzbank_total_withdrawn%
%xzbank_daily_withdrawn%
%xzbank_daily_banknote_created%

API use

XzPlugin integrations can obtain XzBankApi for asynchronous balances, wallet operations, idempotent external charges, Coin charges, dual-currency reservations, and server-backed XP-note issuance.

Callers must supply a stable operation ID for every idempotent charge or reservation. Do not reuse an operation ID for a different player or amount. Never block the Paper main thread on an API future.

Updating and migration

Use a clean server restart for JAR updates. Preserve the owner-managed plugins/XzBank/ directory. Use /bank update before /bank update confirm; the update process is designed to add missing defaults while preserving customized values.

The EssentialsX migration is disabled unless explicitly enabled in migration.yml. Always run its preview first and retain the generated backup before importing balances.

Troubleshooting

• XzCore is not ready: update or start XzCore first, then restart the server cleanly.
• Vault provider registration skipped: install Vault when third-party plugins need Vault economy access. XzBank's own wallet features remain available.
• SQLite unhealthy: stop the server, back up the complete XzBank data folder, then inspect the database with a SQLite integrity check before attempting recovery.
• A payment fails: verify sender balance, recipient name, permission, enabled economy settings, and server logs.
• A configuration update reports changes: review the plan, back up the XzBank folder, then confirm the update.