MultiBank

A secure, feature-rich economy plugin for Paper/Purpur 26.3 servers (2.0.0 runs on 26.2, 1.x on 1.21.x).

MultiBank replaces EssentialsX Economy and acts as your server's main economy system, with GUI support, multi-account management, a Vault bridge for legacy plugins, and a clean developer API.

Features

• Multi-account system: Personal + Group/Joint accounts with roles (OWNER, MANAGER, MEMBER, VIEWER)
• GUI interface: Full-featured inventory GUI via /mb — pay players, manage accounts, view history, accept invites, view top balances
• Vault bridge: Legacy plugins (shops, auction houses, etc.) work seamlessly via Vault Economy provider
• Developer API: Exposed via Bukkit ServicesManager with async CompletableFuture methods
• Custom Events: BalanceChangeEvent, TransferEvent, AccountCreateEvent, PrimaryAccountChangeEvent, AccountFrozenEvent
• Atomic transactions: No duplication, no double-spend, no race conditions — all DB operations are transactional
• SQLite/MySQL: Configurable storage backend with HikariCP connection pooling
• Localization: English (en_US) + Portuguese (pt_PT), easily extensible
• Rate limiting: Configurable per-player operation throttling
• Long cents storage: Balances stored as long cents internally — no floating-point precision loss

Banking modules

Four optional modules, on by default, each switchable in config.yml without losing its data.

• Savings accounts (/poupanca): interest paid on the lowest balance held during the period, so money parked a moment before the tick earns nothing.
• Term deposits (/poupanca prazo): capital locked in escrow for a fixed term and out of the player's balance, at several times the open savings rate. The accruing interest stays hidden until it matures — and cancelling early returns exactly what went in, to the cent.
• Loans (/emprestimo): borrow from the State, or from other players through an offer board where capital is escrowed at offer time and acceptance is a database compare-and-swap. Defaulting hands the balance to garnishment, which collects it from the borrower's future income.
• Certificates (/certificados): savings and treasury certificates modelled on the Portuguese instruments. Subscribing lends money to the State, which puts it to work.
• The State (/estado): a public treasury balance sheet and the community projects it funds. Delivering a project destroys the money — the economy's one deliberate sink.

No module creates currency. Every credit has a matching debit: interest is paid out of the treasury, loans move treasury or escrow money, and if the State cannot afford a payment it is not made rather than minted. /mb admin audit reconciles the escrow accounts against the contracts they back and reports any drift.

Installation

1. Download MultiBank-2.1.0+mc26.3.jar
2. Place it in your server's plugins/ folder
3. (Optional) Place Vault.jar in plugins/ for legacy plugin support
4. Start the server — config.yml and lang/ files will be generated
5. Edit plugins/MultiBank/config.yml to customize currency, database, pay limits, etc.
6. Use /mb admin reload to apply config changes without restart

Commands

Player Commands

Account Management (/mb account)

Savings and term deposits (/poupanca, /savings)

Interest is paid on the lowest balance held during the period, so capital that was not at risk for the whole period earns nothing. A term deposit's accrued interest is hidden until it matures.

Loans (/emprestimo, /loan)

Instalments are collected automatically. Missing too many defaults the loan, and the balance is then collected as a share of the borrower's incoming money until it is cleared.

Certificates (/certificados, /certs)

The State (/estado, /state)

Admin Commands (/mb admin)

Console and RCON replies for these are written to the server log: the lookups answer from a database thread, by which time RCON has already closed out the request.

The treasury starts empty. Until it holds money it cannot lend or pay interest — either seed it with /mb admin treasury grant, or let it fill from certificate subscriptions and loan fees.

OP Override Commands (/mb op)

These commands are restricted to server OPs (isOp()) and console only — no permission nodes, pure OP check. They always target the player's personal account, regardless of their current primary account setting.

Rules:

• Amount supports decimals (e.g., 4000.50), converted to cents internally
• Works for offline players (UUID lookup via Bukkit.getOfflinePlayer)
• All operations are atomic (single DB transaction)
• Every action is logged to console and transaction history with reason "OP override"
• Take behavior when balance would go negative is configurable:
  • clamp-negative-to-zero: true (default) — takes only what the player has, balance becomes 0
  • clamp-negative-to-zero: false — denies the operation entirely
  • allow-negative-after-take: true — allows negative balance (overrides clamp)

Examples:

/multibank op set Steve 4000       → Sets Steve's personal balance to $4,000.00
/mb op give Alex 250.50            → Gives Alex $250.50 into personal account
/mb op take Notch 100              → Takes $100.00 from Notch's personal account

Permissions

Nodes are registered in code at enable time. Paper ignores the permissions: block of paper-plugin.yml, and an unregistered node silently defaults to OP — which is what had made multibank.account.create staff-only despite the config implying otherwise.

Roles (Group Accounts)

Vault Bridge

MultiBank automatically registers as a Vault Economy provider if Vault is present on the server. This means any plugin that uses Vault's Economy API (shops, auction houses, job plugins, etc.) will transparently use MultiBank balances.

How it works:

• Economy.getBalance(player) → reads the player's personal account balance
• Economy.depositPlayer(player, amount) → deposits into personal account (atomic)
• Economy.withdrawPlayer(player, amount) → withdraws from personal account (atomic)
• Economy.has(player, amount) → checks personal account balance
• Economy.createPlayerAccount(player) → auto-creates personal account with starting balance
• Bank operations → return NOT_IMPLEMENTED (use MultiBank's group accounts instead)

Startup logs:

• "Vault bridge enabled — MultiBank is now the economy provider." — success
• "Vault not found; bridge disabled." — Vault not on server (this is fine)

Configuration: set vault.enabled: false in config.yml to disable the bridge.

Thread safety: All Vault operations use timeout-guarded async DB calls. The bridge is safe to call from any thread.

Developer API

Package

pt.henrique.multibank.api.MultiBankApi

Events are in:

pt.henrique.multibank.api.event.*

Getting the API

import pt.henrique.multibank.api.MultiBankApi;

// In your plugin's onEnable():
MultiBankApi api = getServer().getServicesManager().load(MultiBankApi.class);
if(api ==null){

        getLogger().

        warning("MultiBank not found! Economy features disabled.");
    return;
            }

API Methods

All methods return CompletableFuture for async execution. Chain with .thenAccept() / .thenCompose() for non-blocking use.

Account Resolution

CompletableFuture<Account> getPersonalAccount(UUID playerId)
CompletableFuture<Optional<Account>> getAccountById(String accountId)
CompletableFuture<List<Account>> listAccounts(UUID playerId)
CompletableFuture<Account> getPrimaryAccount(UUID playerId)
CompletableFuture<Void> setPrimaryAccount(UUID playerId, String accountId)

Balance Operations

CompletableFuture<Long> getBalanceCents(String accountId)
CompletableFuture<TransactionResult> deposit(String accountId, long cents, String reason, UUID actor)
CompletableFuture<TransactionResult> withdraw(String accountId, long cents, String reason, UUID actor)
CompletableFuture<TransactionResult> transfer(String fromAccountId, String toAccountId, long cents, String reason, UUID actor)

Group Management

CompletableFuture<String> createGroupAccount(UUID owner, String name)
CompletableFuture<Void> inviteMember(String accountId, UUID inviter, UUID target)
CompletableFuture<Void> setMemberRole(String accountId, UUID actor, UUID target, Role role)

Security

boolean isFrozen(String accountId)

Example Usage

// Get a player's primary balance
api.getPrimaryAccount(playerUuid).thenAccept(account -> {
    long cents = account.getBalanceCents();
    getLogger().info("Balance: " + (cents / 100.0));
});

// Deposit money
api.deposit(accountId, 5000L, "Shop purchase refund", actorUuid)
    .thenAccept(result -> {
        if (result.isSuccess()) {
            getLogger().info("Deposit OK, txId=" + result.transaction().txId());
        }
    });

// Transfer between accounts (atomic)
api.transfer(fromId, toId, 10000L, "Trade deal", actorUuid)
    .thenAccept(result -> {
        if (result.isSuccess()) {
            // Transfer complete — both balances updated atomically
        } else {
            // result.status() tells you why: INSUFFICIENT_FUNDS, ACCOUNT_FROZEN, etc.
        }
    });

// Create a group account
api.createGroupAccount(ownerUuid, "My Faction Bank").thenAccept(accountId -> {
    getLogger().info("Created group account: " + accountId);
});

// Check if an account is frozen
boolean frozen = api.isFrozen(accountId);

Custom Events

All events are in pt.henrique.multibank.api.event and are fired on the main server thread.

import pt.henrique.multibank.api.event.BalanceChangeEvent;

@EventHandler
public void onBalanceChange(BalanceChangeEvent event) {
  getLogger().info("Account " + event.getAccountId()
          + " balance changed by " + event.getAmount()
          + " cents. Reason: " + event.getReason());
}

Adding MultiBank as a Dependency

In your plugin's build.gradle.kts:

repositories {
    // Add the repo where MultiBank is hosted, or use a local jar
}

dependencies {
    compileOnly(files("libs/MultiBank-1.0.0.jar"))
}

In your paper-plugin.yml:

dependencies:
  server:
    MultiBank:
      load: BEFORE
      required: true  # or false if optional
      join-classpath: true

Configuration

See plugins/MultiBank/config.yml for all options:

Database Schema

Security Notes

• Atomic transactions: All economy operations (deposit, withdraw, transfer, set) use database transactions — no partial updates possible
• No double-spend: Transfer operations debit and credit both accounts in a single atomic transaction
• SQLite WAL mode: Enabled for concurrent read/write safety with busy timeout
• Rate limiting: Configurable per-player operation throttle (default: 30/min) prevents abuse
• GUI debouncing: Click debounce (default: 250ms) prevents double-click exploits
• Frozen accounts: Cannot send or receive any funds until unfrozen by admin
• UUID-based identity: All internal operations use UUID — never trusts player names
• Long cents storage: Balances stored as long cents — no floating-point precision issues
• Transaction audit log: Every operation generates a unique txId UUID and is logged with actor, reason, and timestamp
• Non-negative enforcement: Balances cannot go negative unless allow-overdraft is enabled
• Vault timeout safety: Vault bridge operations use 10-second timeout to prevent server hangs
• In-database arithmetic: every balance change is computed inside the SQL statement under the row's write lock. A read-modify-write in Java lets two threads observe the same balance and both write — the lost-update duplication this plugin was patched for
• Idempotent accrual: interest and instalments claim their period through a primary key, so a scheduler misfire, a bulk catch-up or a manual re-run pays each period exactly once
• Monotonic time: accrual watermarks advance by whole periods from their previous value, never to the wall clock; a clock moved backwards yields zero periods, and catch-up is clamped
• Escrow before commitment: a lending offer debits the lender when it is posted, so it can never be backed by money since spent, and one balance cannot back two offers
• Compare-and-swap contracts: accepting an offer, redeeming a certificate and completing a project all flip a row from an expected state; concurrent attempts produce one winner
• Anti-arbitrage validation: a configuration where an interest-bearing product out-earns the cost of borrowing disables that product at startup rather than being accepted, and holding debt blocks investing — which also closes the 0%-loan-from-a-friend variant
• Ledger reconciliation: /mb admin audit checks each escrow account against the contracts it backs and reports drift, which is the footprint any duplication bug leaves behind

Building from Source

Two targets from one source tree:

git clone <repo-url>
cd MultiBank

./gradlew build                 # 26.3 (default) — runs the test suite
./gradlew -Pmc=262 build        # 26.2
./gradlew -Pmc=1211 build       # 1.21.11

Output: build/libs/MultiBank-<version>+mc26.3.jar (or +mc26.2, +mc1.21.11).

Every target emits Java 21 bytecode. The 26.x APIs are compiled to class file 69 and can only be read by JDK 25, hence the JDK 25 toolchain; put one in /opt/jdk-25 or adjust org.gradle.java.installations.paths.

The tests exercise the banking logic against a real SQLite database, including a randomised 400-operation run that asserts the money supply never changes.

Requirements

• Paper or Purpur 26.3 (2.0.0 for 26.2, 1.x for 1.21.x)
• Java 25
• (Optional) VaultUnlocked for legacy plugin economy support

License

GPL-3.0 — see LICENSE.