Emerald Bank (MineClonia)

Code under AGPLv3-or-later License

EmeraldBank Mod is Libre/Free Software, copy and share.

This is Free Software not open source!

EmeraldBank

EmeraldBank is a banking and economy mod for MineClonia.

Keep your emeralds safely in bank accounts, transfer money between players and organizations, manage shared accounts, and keep a permanent transaction history.

Why emeralds? In MineClonia, emeralds are already used as currency for trading with villagers, so EmeraldBank uses them as its banking currency too.

Features

• Personal bank account for every player

• Deposit and withdraw physical emeralds

• Bank interface accessible from the Emerald Bank node

• Economy tab in the MineClonia inventory

• Transfers between players and other accounts

• Organization accounts with shared access

• Organization roles:

  • Owner
  • Manager
  • Viewer

• Configurable organization creation limits and fees

• Dedicated bank and treasury accounts

• Permanent transaction ledger

• Transaction details and paginated history

• Administrative account browser and audit interface

• Account freezing and administrative balance adjustments

• Periodic and starting income paid from the treasury

• Shop earnings integration

• Migration from older EmeraldBank account and transaction formats

• Multiplayer support

Transactions are never deleted from the permanent ledger. Corrections and reversals are recorded as new transactions, preserving the banking history.

Accounts

EmeraldBank supports several account types:

• Personal accounts — automatically associated with players
• Organization accounts — shared accounts created and managed by players
• Bank account — system account used by the bank
• Treasury account — system account used for public payments, fees and other server economy operations

Every account has a stable internal ID:

acc:<id>

For example:

acc:17

Account IDs can be used when an exact account must be specified.

Organization Accounts

Players can create organization accounts from the bank interface.

Organizations can be used for groups, towns, clans, shops, projects or any other shared purpose.

Members can have different roles:

• Owner — full account management
• Manager — can use the account and perform financial operations
• Viewer — can view the account and its history

Organization accounts can be renamed and closed from the management interface.

Closing an account does not delete it or its transaction history.

Bank Interface

The main bank interface provides:

• Overview — balance and physical emerald deposit/withdrawal
• Transfer — send emeralds to another account
• History — browse the permanent transaction history
• Manage — manage organization members and account settings

Players with the appropriate privileges can also access the administration and audit interface.

Commands

/bank

Open the EmeraldBank interface.

/bank

/pay

Transfer emeralds from your personal account to another player or account.

/pay <player|acc:id> <amount> [description]

Examples:

/pay Steve 10
/pay Steve 25 Building materials
/pay acc:17 50 Organization payment

Transfers require confirmation before being completed.

/money

Show your personal account balance.

/money

Players with EmeraldBank administration or audit privileges can inspect another account:

/money <player|account name|acc:id>

/bankadmin

Open the administration and audit interface.

/bankadmin

Requires the appropriate EmeraldBank administration or audit privilege.

/emeralds

Administrative balance adjustment.

/emeralds <player|acc:id> <signed amount> <reason>

Examples:

/emeralds Steve +50 Compensation for shop bug
/emeralds acc:17 -10 Administrative correction

Every adjustment is permanently recorded in the transaction ledger together with the administrator and reason.

Privileges

EmeraldBank provides dedicated privileges:

emeraldbank_admin

Full bank administration.

Allows account administration, freezing/unfreezing accounts, administrative balance adjustments and access to the audit interface.

emeraldbank_audit

Read-only access to account and transaction auditing.

emeraldbank_treasury

Allows operation of the treasury account without granting full bank administration.

Treasury and Money Supply

The treasury is a real account with a finite balance.

Periodic income and starting balances are paid from the treasury instead of creating unlimited money automatically.

If the treasury does not have enough funds, those payments cannot be made until it is funded again.

The bank is also represented by its own account, allowing the economy to support finite bank liquidity and future systems such as loans.

Permanent Transaction Ledger

EmeraldBank keeps an append-only transaction ledger.

Transactions include information such as:

• Transaction ID
• Date and time
• Source account
• Destination account
• Amount
• Transaction type
• Source mod or subsystem
• Actor
• Description

The history is stored in paged records, so accounts can keep years of transaction history without loading the entire ledger at once.

The administration interface can audit the global ledger, while individual accounts can browse their own history.

Settings

EmeraldBank includes settings for:

• Bank node crafting
• MineClonia inventory tab
• Number of history entries displayed per page
• Maximum organization accounts created by each player
• Organization creation cost
• Bank account name
• Treasury account name
• Initial bank and treasury balances
• Periodic income
• Starting balance
• Legacy storage migration

A value of 0 for the maximum number of organization accounts means unlimited.

Migration

EmeraldBank can migrate accounts and transaction history from older versions of the mod.

Legacy migration is handled separately from the normal banking code.

It is recommended to keep legacy storage removal disabled until the migrated balances and accounts have been verified.

MineClonia

This mod is designed for MineClonia.

EmeraldBank uses MineClonia emeralds as its physical currency.