MultiBank
适用于 Paper/Purpur 26.3 服务器(2.0.0 版本运行于 26.2,1.x 版本运行于 1.21.x)的安全、功能丰富的经济插件。
MultiBank 替代 EssentialsX Economy,作为服务器的主要经济系统,支持 GUI、多账户管理、用于兼容旧插件的 Vault 桥接以及简洁的开发人员 API。
功能
- 多账户系统:个人 + 群组/联名账户,支持角色权限(OWNER, MANAGER, MEMBER, VIEWER)
- GUI 界面:通过
/mb 提供全功能的库存 GUI — 向玩家付款、管理账户、查看历史记录、接受邀请、查看余额排行
- Vault 桥接:旧插件(商店、拍卖行等)可通过 Vault Economy 提供商无缝工作
- 开发人员 API:通过 Bukkit
ServicesManager 暴露,支持异步 CompletableFuture 方法
- 自定义事件:
BalanceChangeEvent, TransferEvent, AccountCreateEvent, PrimaryAccountChangeEvent, AccountFrozenEvent
- 原子事务:无重复、无双重支付、无竞态条件 — 所有数据库操作均为事务性
- SQLite/MySQL:可配置的存储后端,配备 HikariCP 连接池
- 本地化:英语 (
en_US) + 葡萄牙语 (pt_PT),易于扩展
- 速率限制:可配置的单玩家操作节流
- 长整型分币存储:余额在内部以
long 类型分币存储 — 无浮点数精度损失
银行模块
四个可选模块,默认开启,每个均可在 config.yml 中切换而不丢失数据。
- 储蓄账户 (
/poupanca):按期间持有的最低余额支付利息,因此在刻度前一刻存入的资金不会产生利息。
- 定期存款 (
/poupanca prazo):资金锁定在托管账户中固定期限,且不计入玩家余额,利率高于活期储蓄。累积的利息在到期前保持隐藏 — 提前取消则精确返还本金至分币。
- 贷款 (
/emprestimo):向国家借款,或通过报价板向其他玩家借款,其中资金在报价时托管,接受为数据库比较并交换操作。违约将导致余额被扣押,从借款人未来的收入中收取。
- 证书 (
/certificados):基于葡萄牙工具的储蓄和国库债券模型。认购即向国家放贷,由国家运作资金。
- 国家 (
/estado):公共国库资产负债表及其资助的社区项目。交付项目会销毁货币 — 这是经济体中唯一的有意消耗项。
没有任何模块会创造货币。 每一笔贷方都有对应的借方:利息由国库支付,贷款移动国库或托管资金,如果国家无力支付,则不支付而不是铸造。/mb admin audit 将托管账户与其背后的合同进行对账,并报告任何偏差。
安装
- 下载
MultiBank-2.1.0+mc26.3.jar
- 将其放入服务器的
plugins/ 文件夹
- (可选)将
Vault.jar 放入 plugins/ 以支持旧插件
- 启动服务器 — 将生成
config.yml 和 lang/ 文件
- 编辑
plugins/MultiBank/config.yml 以自定义货币、数据库、支付限额等。
- 使用
/mb admin reload 应用配置更改而无需重启
命令
玩家命令
| 命令 |
别名 |
描述 |
/mb |
— |
打开主 GUI |
/money [player] |
/bal, /saldo, /balance |
检查余额(主账户) |
/pay <player> <amount> [fromAccount] |
/pagar |
向其他玩家付款 |
/pay confirm |
— |
确认待处理的大额付款 |
/pay cancel |
— |
取消待处理的付款 |
/topbal [page] |
/top, /baltop, /topmoney |
查看最富有账户 |
账户管理 (/mb account)
| 命令 |
描述 |
/mb account list |
列出您的所有账户 |
/mb account info <accountId> |
查看账户详情 |
/mb account create <name> |
创建群组/联名账户 |
/mb account rename <accountId> <name> |
重命名账户 |
/mb account setprimary <accountId> |
设置您的主账户 |
/mb account invite <accountId> <player> |
邀请玩家加入您的群组账户 |
/mb account accept [inviteId] |
接受邀请(若无 ID 则为最新) |
/mb account kick <accountId> <player> |
从您的群组账户中移除成员 |
/mb account role <accountId> <player> <OWNER|MANAGER|MEMBER|VIEWER> |
更改成员角色 |
/mb account leave <accountId> |
退出群组账户(如果是所有者则无法退出) |
储蓄和定期存款 (/poupanca, /savings)
| 命令 |
描述 |
/poupanca |
储蓄和定期存款 GUI |
/poupanca abrir [name] |
开设储蓄账户 |
/poupanca depositar <amount> [savingsId] |
将资金转入储蓄 |
/poupanca levantar <amount> [savingsId] |
提取资金 |
/poupanca info |
您的账户、利息基数及距下次支付的时间 |
/poupanca taxa |
当前利率及其计算方式 |
/poupanca prazo tipos |
提供的定期存款类型 |
/poupanca prazo abrir <type> <amount> |
将资金锁定固定期限 |
/poupanca prazo |
您的锁定头寸 |
/poupanca prazo cancelar <id> |
取消或领取 — 资金始终全额返还 |
利息按期间持有的最低余额支付,因此在整个期间未承担风险的资金不会产生收益。定期存款的应计利息在到期前保持隐藏。
贷款 (/emprestimo, /loan)
| 命令 |
说明 |
/emprestimo |
信贷仪表盘 |
/emprestimo simular <amount> <periods> |
在承诺借款前,对政府贷款进行报价估算 |
/emprestimo pedir <amount> <periods> |
向政府借款 |
/emprestimo oferecer <amount> <rate%> <periods> |
向其他玩家提供贷款(资金将存入托管账户) |
/emprestimo mercado |
浏览公开的贷款要约 |
/emprestimo aceitar <offerId> |
接受某项要约 |
/emprestimo cancelar <offerId> |
撤回你自己的要约 |
/emprestimo pagar <loanId> [amount] |
还款;若不提供金额则结算全部余额 |
/emprestimo meus |
你欠下的贷款以及你发放的贷款 |
/emprestimo credito |
你的信用评分、记录及授信额度 |
分期款项会自动扣收。若拖欠过多导致违约,系统将按比例从借款人收到的资金中扣除欠款,直至结清。
债券 (/certificados, /certs)
| 命令 |
说明 |
/certificados |
债券图形界面 |
/certificados series |
当前发行的债券系列,含利率与条款 |
/certificados subscrever <series> <amount> |
向政府出借指定金额 |
/certificados resgatar <certId> |
赎回债券 |
/certificados meus |
你持有的债券 |
政府 (/estado, /state)
| 命令 |
说明 |
/estado |
国库与项目图形界面 |
/estado info |
余额、债务、对外放贷情况、偿付能力 |
/estado projetos |
社区项目及其进度 |
/estado propor <goal> <name…> |
提议一个新项目 |
/estado votar <projectId> |
为某项提议投票 |
/estado financiar <projectId> <amount> |
注资支持 |
管理员命令 (/mb admin)
| 命令 |
说明 |
权限节点 |
/mb admin give <player|accountId> <amount> [reason] |
给予金钱 |
multibank.admin.give |
/mb admin take <player|accountId> <amount> [reason] |
扣除金钱 |
multibank.admin.take |
/mb admin set <player|accountId> <amount> [reason] |
设置余额 |
multibank.admin.set |
/mb admin freeze <player|accountId> <on|off> |
冻结/解冻账户 |
multibank.admin.freeze |
/mb admin reload |
重新加载配置文件和语言文件 |
multibank.admin.reload |
/mb admin treasury info |
查看国库资产负债表 |
multibank.admin.treasury |
/mb admin treasury grant <amount> [reason] |
向国库注入初始资金(铸造货币;会如实记录) |
multibank.admin.treasury |
/mb admin treasury burn <amount> [reason] |
销毁国库中的货币 |
multibank.admin.treasury |
/mb admin project open <goal> <name…> |
开放项目以接受注资 |
multibank.admin.project |
/mb admin project complete <id> |
标记项目已交付——消耗并销毁相应资金 |
multibank.admin.project |
/mb admin project cancel <id> |
取消项目并退还所有贡献者的资金 |
multibank.admin.project |
/mb admin audit |
核对托管资金与合同的一致性;报告偏差 |
multibank.admin.audit |
这些命令的控制台和 RCON 回复均写入服务器日志:查询操作由数据库线程处理,而 RCON 请求在此时已经关闭。
国库初始为空。在其拥有资金之前,无法放贷或支付利息——你可以使用 /mb admin treasury grant 为其注入初始资金,或等待其通过债券认购和贷款费用自动充盈。
OP 覆盖命令 (/mb op)
这些命令仅限 服务器 OP (isOp()) 和 控制台 使用——无需权限节点,仅检查 OP 身份。
它们始终针对玩家的 个人 账户,无论其当前设置的主要账户为何。
| 命令 |
说明 |
示例 |
/mb op set <player> <amount> |
强制设置玩家的个人余额 |
/multibank op set username 4000 |
/mb op give <player> <amount> |
向玩家的个人账户给予金钱 |
/mb op give username 250 |
/mb op take <player> <amount> |
从玩家的个人账户扣除金钱 |
/mb op take username 100 |
规则:
- 金额支持小数(例如
4000.50),内部转换为分单位存储
- 支持 离线玩家(通过
Bukkit.getOfflinePlayer 查找 UUID)
- 所有操作均为 原子性(单次数据库事务)
- 每个操作都会记录到控制台和交易历史中,原因标注为
"OP override"
- 当余额可能变为负数时的“扣除”行为可配置:
clamp-negative-to-zero: true(默认)——只扣除玩家现有的金额,余额归零
clamp-negative-to-zero: false —— 完全拒绝该操作
allow-negative-after-take: true —— 允许余额为负(覆盖上述钳制逻辑)
示例:
/multibank op set Steve 4000 → 将 Steve 的个人余额设置为 $4,000.00
/mb op give Alex 250.50 → 向 Alex 的个人账户给予 $250.50
/mb op take Notch 100 → 从 Notch 的个人账户扣除 $100.00
权限
| 权限 |
描述 |
默认值 |
multibank.use |
使用 /mb GUI 和基本命令 |
所有玩家 |
multibank.balance |
查看余额 |
所有玩家 |
multibank.pay |
使用 /pay |
所有玩家 |
multibank.top |
查看余额排行榜 |
所有玩家 |
multibank.account.create |
创建群组账户 |
所有玩家 |
multibank.admin |
访问管理子命令 |
仅 OP |
multibank.admin.give |
/mb admin give |
仅 OP |
multibank.admin.take |
/mb admin take |
仅 OP |
multibank.admin.set |
/mb admin set |
仅 OP |
multibank.admin.freeze |
/mb admin freeze |
仅 OP |
multibank.admin.reload |
/mb admin reload |
仅 OP |
multibank.savings |
储蓄账户和定期存款 |
所有玩家 |
multibank.loan |
贷款命令和 GUI |
所有玩家 |
multibank.loan.borrow |
借款或接受贷款要约 |
所有玩家 |
multibank.loan.lend |
发布出借要约 |
所有玩家 |
multibank.cert |
证书 |
所有玩家 |
multibank.state |
查看国库和项目 |
所有玩家 |
multibank.project.vote |
对提议的项目投票 |
所有玩家 |
multibank.project.propose |
提议项目 |
所有玩家 |
multibank.admin.treasury |
/mb admin treasury |
仅 OP |
multibank.admin.project |
/mb admin project |
仅 OP |
multibank.admin.audit |
/mb admin audit |
仅 OP |
节点在启用时于代码中注册。Paper 会忽略 paper-plugin.yml 中的 permissions: 块,且未注册的节点会静默默认为 OP——这导致尽管配置暗示并非如此,multibank.account.create 仍仅限员工(staff)使用。
角色(群组账户)
| 角色 |
存入 |
取出 |
转账 |
邀请 |
踢出 |
设置角色 |
重命名 |
设置主账户 |
查看 |
| OWNER |
|
|
|
|
|
|
|
|
|
| MANAGER |
|
|
|
|
|
|
|
|
|
| MEMBER |
|
|
|
|
|
|
|
|
|
| VIEWER |
|
|
|
|
|
|
|
|
|
Vault 桥接
如果服务器中存在 Vault,MultiBank 会自动注册为 Vault Economy 提供者。这意味着任何使用 Vault Economy API 的插件(商店、拍卖行、工作插件等)都将透明地使用 MultiBank 余额。
工作原理:
Economy.getBalance(player) → 读取玩家的个人账户余额
Economy.depositPlayer(player, amount) → 存入个人账户(原子操作)
Economy.withdrawPlayer(player, amount) → 从个人账户取款(原子操作)
Economy.has(player, amount) → 检查个人账户余额
Economy.createPlayerAccount(player) → 自动创建带有初始余额的个人账户
- 银行操作 → 返回
NOT_IMPLEMENTED(请使用 MultiBank 的群组账户)
启动日志:
"Vault bridge enabled — MultiBank is now the economy provider." — 成功
"Vault not found; bridge disabled." — 服务器上未找到 Vault(这是正常的)
配置: 在 config.yml 中设置 vault.enabled: false 以禁用桥接。
线程安全: 所有 Vault 操作均使用带超时保护的异步数据库调用。该桥接可从任何线程安全调用。
开发者 API
包
pt.henrique.multibank.api.MultiBankApi
事件位于:
pt.henrique.multibank.api.event.*
获取 API
import pt.henrique.multibank.api.MultiBankApi;
// 在你的插件的 onEnable() 中:
MultiBankApi api = getServer().getServicesManager().load(MultiBankApi.class);
if(api ==null){
getLogger().
warning("MultiBank not found! Economy features disabled.");
return;
}
API 方法
所有方法均返回 CompletableFuture 以支持异步执行。可使用 .thenAccept() / .thenCompose() 进行链式调用以实现非阻塞使用。
账户解析
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)
余额操作
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)
群组管理
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)
安全性
boolean isFrozen(String accountId)
用法示例
// 获取玩家的主账户余额
api.getPrimaryAccount(playerUuid).thenAccept(account -> {
long cents = account.getBalanceCents();
getLogger().info("Balance: " + (cents / 100.0));
});
// 存入资金
api.deposit(accountId, 5000L, "Shop purchase refund", actorUuid)
.thenAccept(result -> {
if (result.isSuccess()) {
getLogger().info("Deposit OK, txId=" + result.transaction().txId());
}
});
// 在账户间转账(原子操作)
api.transfer(fromId, toId, 10000L, "Trade deal", actorUuid)
.thenAccept(result -> {
if (result.isSuccess()) {
// 转账完成 — 两个余额均已原子更新
} else {
// result.status() 告诉你原因:INSUFFICIENT_FUNDS, ACCOUNT_FROZEN 等
}
});
// 创建群组账户
api.createGroupAccount(ownerUuid, "My Faction Bank").thenAccept(accountId -> {
getLogger().info("Created group account: " + accountId);
});
// 检查账户是否被冻结
boolean frozen = api.isFrozen(accountId);
自定义事件
所有事件均位于 pt.henrique.multibank.api.event 包中,并在主服务器线程上触发。
| 事件 |
可取消 |
字段 |
BalanceChangeEvent |
|
accountId, oldBalance, newBalance, amount, actor, reason |
TransferEvent |
|
fromAccountId, toAccountId, amount, actor, reason |
AccountCreateEvent |
|
accountId, type, owner, name |
PrimaryAccountChangeEvent |
|
playerId, oldAccountId, newAccountId |
AccountFrozenEvent |
|
accountId, frozen, actor |
import pt.henrique.multibank.api.event.BalanceChangeEvent;
@EventHandler
public void onBalanceChange(BalanceChangeEvent event) {
getLogger().info("账户 " + event.getAccountId()
+ " 余额变动了 " + event.getAmount()
+ " 分。原因: " + event.getReason());
}
将 MultiBank 添加为依赖项
在你的插件的 build.gradle.kts 文件中:
repositories {
// 添加托管 MultiBank 的仓库,或使用本地 jar 文件
}
dependencies {
compileOnly(files("libs/MultiBank-1.0.0.jar"))
}
在你的 paper-plugin.yml 文件中:
dependencies:
server:
MultiBank:
load: BEFORE
required: true # 如果为可选依赖则设为 false
join-classpath: true
配置
请参阅 plugins/MultiBank/config.yml 以获取所有选项:
| 部分 |
键选项 |
language |
en_US, pt_PT(或任何自定义语言文件) |
starting-balance |
新账户的起始资金(默认值:100.00) |
currency.* |
符号、位置、小数位数、分隔符、名称 |
database.* |
sqlite(默认)或带有主机/端口/凭据的 mysql |
pay.* |
启用/禁用、最小/最大金额、确认阈值 |
accounts.* |
透支、邀请过期时间、最大群组账户数 |
admin.op-override.* |
启用/禁用 OP 覆盖、允许控制台操作、负余额规则 |
vault.enabled |
启用/禁用 Vault 桥接 |
top.* |
模式(personal/all/primary)、每页大小 |
security.* |
速率限制、GUI 防抖 |
数据库架构
| 表名 |
用途 |
accounts |
账户 ID、类型、所有者 UUID、名称、冻结标志、创建时间戳 |
balances |
账户 ID → 以分为单位的余额 (long) |
account_members |
账户 ID + 成员 UUID + 角色 |
primary_accounts |
玩家 UUID → 其主账户 ID |
invites |
邀请 ID、账户、目标、邀请人、过期时间 |
transactions |
完整审计日志:交易 ID、时间戳、类型、来源/目标账户、金额、操作者、原因、是否成功 |
schema_version |
迁移记录;升级是累加且幂等的 |
savings_state |
每个账户的累计水位线、低水位余额和已赚利息 |
interest_accruals |
每个 (账户, 周期) 一行,用于贷记 — 储蓄的幂等键 |
loan_offers |
点对点贷款要约及其托管状态 |
loans |
合同:本金、未偿余额、逾期金额、利率、期限、排期位置、状态 |
loan_charges |
每个 (贷款, 周期) 一行,用于扣费 — 分期付款的幂等键 |
garnishments |
从债务人收入中收取的违约余额 |
credit_profiles |
还款记录和信用评分 |
certificates |
订阅的证书和定期存款及其托管情况 |
cert_accruals |
每个 (证书, 周期) 一行,用于累计收益 |
projects, project_contributions, project_votes |
社区项目、贡献和投票 |
安全说明
- 原子事务:所有经济操作(存款、取款、转账、设置)均使用数据库事务 —— 无法进行部分更新
- 防双花:转账操作在一个原子事务中同时扣款和入账两个账户
- SQLite WAL 模式:已启用,配合忙等待超时以确保并发读写安全
- 速率限制:可配置每位玩家的操作节流(默认:30次/分钟),防止滥用
- GUI 防抖:点击防抖(默认:250毫秒)防止双击漏洞利用
- 冻结账户:在管理员解冻之前,无法发送或接收任何资金
- 基于 UUID 的身份标识:所有内部操作均使用 UUID —— 从不信任玩家名称
- 长整型分币存储:余额以
long 类型的分币存储 —— 无浮点数精度问题
- 交易审计日志:每项操作都会生成唯一的
txId UUID,并记录操作者、原因和时间戳
- 非负强制:除非启用了
allow-overdraft,否则余额不能为负
- Vault 超时安全:Vault 桥接操作使用 10 秒超时,以防止服务器挂起
- 数据库内算术运算:每次余额变更均在 SQL 语句中计算,并在行的写锁保护下进行。如果在 Java 中进行读-改-写,两个线程可能会观察到相同的余额并同时写入 —— 这正是本插件修复的丢失更新重复问题
- 幂等累积:利息和分期付款通过主键认领其周期,因此调度器误触发、批量追赶或手动重跑只会支付每个周期一次
- 单调时间:累积水位线按完整周期从其前一个值推进,从不使用墙钟时间;时钟回拨将导致零周期,且追赶逻辑会被限制
- 承诺前的托管:贷款报价在发布时会借记贷方,因此它绝不可能由已花费的资金支撑,且一个余额不能支撑多个报价
- 比较并交换合约:接受报价、赎回证书和完成项目都会使行从预期状态翻转;并发尝试只产生一个赢家
- 防套利验证:如果计息产品的收益高于借贷成本,该配置将在启动时禁用该产品而非被接受,并且持有债务会阻止投资 —— 这也关闭了“向朋友借 0% 贷款”的变体
- 账目对账:
/mb admin audit 检查每个托管账户与其支持的合约,并报告偏差,这是任何重复错误留下的痕迹
从源码构建
从一个源代码树构建两个目标:
git clone <repo-url>
cd MultiBank
./gradlew build # 26.3 (默认) — 运行测试套件
./gradlew -Pmc=262 build # 26.2
./gradlew -Pmc=1211 build # 1.21.11
输出:build/libs/MultiBank-<version>+mc26.3.jar(或 +mc26.2, +mc1.21.11)。
每个目标均生成 Java 21 字节码。26.x API 编译为 class file 69,只能由 JDK 25 读取,因此需要 JDK 25 工具链;将其放入 /opt/jdk-25 或调整
org.gradle.java.installations.paths。
测试针对真实的 SQLite 数据库检验银行逻辑,包括一个随机化的 400 次操作运行,断言货币供应量永不改变。
要求
- Paper 或 Purpur 26.3(26.2 对应 2.0.0,1.21.x 对应 1.x)
- Java 25
- (可选)VaultUnlocked 用于支持旧版插件经济
许可证
GPL-3.0 — 请参阅 LICENSE。
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
- Download
MultiBank-2.1.0+mc26.3.jar
- Place it in your server's
plugins/ folder
- (Optional) Place
Vault.jar in plugins/ for legacy plugin support
- Start the server —
config.yml and lang/ files will be generated
- Edit
plugins/MultiBank/config.yml to customize currency, database, pay limits, etc.
- Use
/mb admin reload to apply config changes without restart
Commands
Player Commands
| Command |
Aliases |
Description |
/mb |
— |
Opens the main GUI |
/money [player] |
/bal, /saldo, /balance |
Check balance (primary account) |
/pay <player> <amount> [fromAccount] |
/pagar |
Pay another player |
/pay confirm |
— |
Confirm a pending large payment |
/pay cancel |
— |
Cancel a pending payment |
/topbal [page] |
/top, /baltop, /topmoney |
View richest accounts |
Account Management (/mb account)
| Command |
Description |
/mb account list |
List all your accounts |
/mb account info <accountId> |
View account details |
/mb account create <name> |
Create a group/joint account |
/mb account rename <accountId> <name> |
Rename an account |
/mb account setprimary <accountId> |
Set your primary account |
/mb account invite <accountId> <player> |
Invite a player to your group account |
/mb account accept [inviteId] |
Accept an invite (latest if no ID) |
/mb account kick <accountId> <player> |
Remove a member from your group account |
/mb account role <accountId> <player> <OWNER|MANAGER|MEMBER|VIEWER> |
Change a member's role |
/mb account leave <accountId> |
Leave a group account (cannot leave if owner) |
Savings and term deposits (/poupanca, /savings)
| Command |
Description |
/poupanca |
Savings and term deposit GUI |
/poupanca abrir [name] |
Open a savings account |
/poupanca depositar <amount> [savingsId] |
Move money into savings |
/poupanca levantar <amount> [savingsId] |
Take money out |
/poupanca info |
Your accounts, interest base and time to the next payment |
/poupanca taxa |
The current rate and how it is calculated |
/poupanca prazo tipos |
Term deposits on offer |
/poupanca prazo abrir <type> <amount> |
Lock capital away for a fixed term |
/poupanca prazo |
Your locked positions |
/poupanca prazo cancelar <id> |
Cancel or collect — capital always returned in full |
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)
| Command |
Description |
/emprestimo |
Credit dashboard |
/emprestimo simular <amount> <periods> |
Quote a State loan before committing |
/emprestimo pedir <amount> <periods> |
Borrow from the State |
/emprestimo oferecer <amount> <rate%> <periods> |
Offer a loan to other players (escrows the capital) |
/emprestimo mercado |
Browse open offers |
/emprestimo aceitar <offerId> |
Take an offer |
/emprestimo cancelar <offerId> |
Withdraw your own offer |
/emprestimo pagar <loanId> [amount] |
Repay; no amount settles the balance |
/emprestimo meus |
Loans you owe and loans you granted |
/emprestimo credito |
Your score, record and credit line |
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)
| Command |
Description |
/certificados |
Certificate GUI |
/certificados series |
Series on offer, with rates and terms |
/certificados subscrever <series> <amount> |
Lend the amount to the State |
/certificados resgatar <certId> |
Redeem |
/certificados meus |
Your holdings |
The State (/estado, /state)
| Command |
Description |
/estado |
Treasury and projects GUI |
/estado info |
Balance, obligations, what is lent out, solvency |
/estado projetos |
Community projects and their progress |
/estado propor <goal> <name…> |
Propose a project |
/estado votar <projectId> |
Vote for a proposal |
/estado financiar <projectId> <amount> |
Contribute |
Admin Commands (/mb admin)
| Command |
Description |
Permission |
/mb admin give <player|accountId> <amount> [reason] |
Give money |
multibank.admin.give |
/mb admin take <player|accountId> <amount> [reason] |
Take money |
multibank.admin.take |
/mb admin set <player|accountId> <amount> [reason] |
Set balance |
multibank.admin.set |
/mb admin freeze <player|accountId> <on|off> |
Freeze/unfreeze account |
multibank.admin.freeze |
/mb admin reload |
Reload config & lang files |
multibank.admin.reload |
/mb admin treasury info |
Treasury balance sheet |
multibank.admin.treasury |
/mb admin treasury grant <amount> [reason] |
Seed the treasury (mints; recorded as such) |
multibank.admin.treasury |
/mb admin treasury burn <amount> [reason] |
Destroy treasury money |
multibank.admin.treasury |
/mb admin project open <goal> <name…> |
Open a project for contributions |
multibank.admin.project |
/mb admin project complete <id> |
Mark delivered — spends and destroys the money |
multibank.admin.project |
/mb admin project cancel <id> |
Cancel and refund every contributor |
multibank.admin.project |
/mb admin audit |
Reconcile escrow against contracts; report drift |
multibank.admin.audit |
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.
| Command |
Description |
Example |
/mb op set <player> <amount> |
Hard-set a player's personal balance |
/multibank op set username 4000 |
/mb op give <player> <amount> |
Give money to a player's personal account |
/mb op give username 250 |
/mb op take <player> <amount> |
Take money from a player's personal account |
/mb op take username 100 |
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
| Permission |
Description |
Default |
multibank.use |
Use /mb GUI and basic commands |
All players |
multibank.balance |
Check balances |
All players |
multibank.pay |
Use /pay |
All players |
multibank.top |
View top balances |
All players |
multibank.account.create |
Create group accounts |
All players |
multibank.admin |
Access admin subcommands |
OP only |
multibank.admin.give |
/mb admin give |
OP only |
multibank.admin.take |
/mb admin take |
OP only |
multibank.admin.set |
/mb admin set |
OP only |
multibank.admin.freeze |
/mb admin freeze |
OP only |
multibank.admin.reload |
/mb admin reload |
OP only |
multibank.savings |
Savings accounts and term deposits |
All players |
multibank.loan |
Loan commands and GUI |
All players |
multibank.loan.borrow |
Take a loan or accept an offer |
All players |
multibank.loan.lend |
Post a lending offer |
All players |
multibank.cert |
Certificates |
All players |
multibank.state |
View the treasury and projects |
All players |
multibank.project.vote |
Vote on proposed projects |
All players |
multibank.project.propose |
Propose a project |
All players |
multibank.admin.treasury |
/mb admin treasury |
OP only |
multibank.admin.project |
/mb admin project |
OP only |
multibank.admin.audit |
/mb admin audit |
OP only |
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)
| Role |
Deposit |
Withdraw |
Transfer |
Invite |
Kick |
Set Roles |
Rename |
Set Primary |
View |
| OWNER |
|
|
|
|
|
|
|
|
|
| MANAGER |
|
|
|
|
|
|
|
|
|
| MEMBER |
|
|
|
|
|
|
|
|
|
| VIEWER |
|
|
|
|
|
|
|
|
|
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.
| Event |
Cancellable |
Fields |
BalanceChangeEvent |
|
accountId, oldBalance, newBalance, amount, actor, reason |
TransferEvent |
|
fromAccountId, toAccountId, amount, actor, reason |
AccountCreateEvent |
|
accountId, type, owner, name |
PrimaryAccountChangeEvent |
|
playerId, oldAccountId, newAccountId |
AccountFrozenEvent |
|
accountId, frozen, actor |
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:
| Section |
Key options |
language |
en_US, pt_PT (or any custom lang file) |
starting-balance |
Starting money for new accounts (default: 100.00) |
currency.* |
Symbol, position, decimals, separators, name |
database.* |
sqlite (default) or mysql with host/port/credentials |
pay.* |
Enable/disable, min/max amounts, confirmation threshold |
accounts.* |
Overdraft, invite expiry, max group accounts |
admin.op-override.* |
Enable/disable OP override, allow console, negative balance rules |
vault.enabled |
Enable/disable Vault bridge |
top.* |
Mode (personal/all/primary), page size |
security.* |
Rate limits, GUI debounce |
Database Schema
| Table |
Purpose |
accounts |
Account ID, type, owner UUID, name, frozen flag, created timestamp |
balances |
Account ID → balance in cents (long) |
account_members |
Account ID + member UUID + role |
primary_accounts |
Player UUID → their primary account ID |
invites |
Invite ID, account, target, inviter, expiry |
transactions |
Full audit log: txId, timestamp, type, from/to accounts, amount, actor, reason, success |
schema_version |
Migration bookkeeping; upgrades are additive and idempotent |
savings_state |
Per-account accrual watermark, low-water balance and interest earned |
interest_accruals |
One row per (account, period) credited — the idempotency key for savings |
loan_offers |
Peer-to-peer offers and their escrow state |
loans |
Contracts: principal, outstanding, arrears, rate, term, schedule position, status |
loan_charges |
One row per (loan, period) charged — the idempotency key for instalments |
garnishments |
Defaulted balances being collected from a debtor's income |
credit_profiles |
Repayment record and score |
certificates |
Subscribed certificates and term deposits, with their custody |
cert_accruals |
One row per (certificate, period) accrued |
projects, project_contributions, project_votes |
Community projects, contributions and votes |
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.
评论 0
登录后参与评分
还没有评论,来抢沙发吧