Package dev.mintychochip.mint

Interface EconomyService

All Superinterfaces:
Service
@AvailableSince("1.0") public interface EconomyService extends Service
Service for managing economy accounts, balances, and transactions.

Overview

This service provides a complete economy API including:

  • Account management (create, retrieve, update, delete)
  • Balance operations (get, deposit, withdraw, transfer)
  • Transaction support with context tracking
  • Asynchronous operations for all database interactions

Asynchronous Operations

All account and balance operations return CompletableFuture for non-blocking execution. Transactions are created synchronously but execute asynchronously when committed.

Usage Example


 // Get the service
 EconomyService economy = Mint.ECONOMY_SERVICE.get();

 // Create an account for a player
 Account account = economy.createAccount(playerId, "Steve").join();

 // Deposit funds
 economy.deposit(playerId, new BigDecimal("100.0"))
     .thenAccept(actualDeposit -> {
       // Handle completion
     });

 // Transfer with transaction context
 TransactionContext ctx = TransactionContext.builder()
     .actor(Actor.player(adminId))
     .reason("Payment for goods")
     .build();

 economy.transfer(fromId, toId, amount, ctx)
     .thenAccept(transferred -> {
       // Handle completion
     });
Since:
1.0

  • Method Details

    • getMaxFractionalDigits

      @AvailableSince("1.0") int getMaxFractionalDigits()
      Gets the maximum number of fractional digits allowed for currency amounts.

      This value determines the precision of monetary values. For example:

      • 2 = Standard currency (cents, e.g., $10.99)
      • 0 = Whole numbers only (e.g., 10 gold)
      • 4 = High precision (e.g., gas prices)
      Returns:
      maximum decimal places for monetary values

    • beginTransaction

      @AvailableSince("1.0") default Transaction beginTransaction(UUID accountId)
      Begins a new transaction against the specified account with empty context.

      Creates a transaction in Transaction.State.ACTIVE state. Operations can be chained before calling Transaction.commit().

      Equivalent to: beginTransaction(accountId, TransactionContext.empty())

      Parameters:
      accountId - the account to transact against
      Returns:
      a new active transaction

    • beginTransaction

      @AvailableSince("1.0") Transaction beginTransaction(UUID accountId, TransactionContext ctx)
      Begins a new transaction against the specified account with context.

      Transactions track who performed the operation and why, providing an audit trail for economy changes. The context is persisted with the transaction record.

      Parameters:
      accountId - the account to transact against
      ctx - context containing actor and optional reason
      Returns:
      a new active transaction

    • getBalanceByAccount

      @AvailableSince("1.0") CompletableFuture<BigDecimal> getBalanceByAccount(UUID accountId)
      Gets the balance of the specified account.
      Parameters:
      accountId - the account identifier
      Returns:
      future completing with the account balance

    • getBalanceByHolder

      @AvailableSince("1.0") CompletableFuture<BigDecimal> getBalanceByHolder(UUID holderId)
      Gets the balance for the specified holder's primary account.

      This is a convenience method that first resolves the holder's account ID and then retrieves the balance.

      Parameters:
      holderId - the holder's unique identifier
      Returns:
      future completing with the account balance

    • getBalances

      @AvailableSince("1.0") CompletableFuture<List<BigDecimal>> getBalances(List<UUID> accountIds)
      Gets balances for multiple accounts in a single batch operation.

      More efficient than calling getBalanceByAccount(UUID) multiple times. The returned list contains balances in the same order as the input account IDs.

      Parameters:
      accountIds - list of account identifiers
      Returns:
      future completing with list of balances in matching order

    • hasAccount

      @AvailableSince("1.0") CompletableFuture<Boolean> hasAccount(UUID holderId)
      Checks if an account exists for the specified holder.
      Parameters:
      holderId - the holder's unique identifier
      Returns:
      future completing with true if account exists

    • createAccount

      @AvailableSince("1.0") CompletableFuture<Account> createAccount(UUID holderId, String name)
      Creates a new account for the specified holder.

      If an account already exists for this holder, the future will complete exceptionally. Use hasAccount(UUID) to check existence first if needed.

      Parameters:
      holderId - the holder's unique identifier
      name - the display displayName for the account
      Returns:
      future completing with the newly created account

    • getAccount

      @AvailableSince("1.0") CompletableFuture<Optional<Account>> getAccount(UUID accountId)
      Retrieves an account by its identifier.
      Parameters:
      accountId - the account identifier
      Returns:
      future completing with optional containing the account if found

    • deleteAccount

      @AvailableSince("1.0") CompletableFuture<Boolean> deleteAccount(UUID accountId)
      Deletes the specified account.

      This operation is irreversible. All associated transaction history will be removed.

      Parameters:
      accountId - the account identifier
      Returns:
      future completing with true if account was deleted, false if not found

    • updateAccountName

      @AvailableSince("1.0") CompletableFuture<Boolean> updateAccountName(UUID accountId, String name)
      Updates the display displayName of the specified account.
      Parameters:
      accountId - the account identifier
      name - the new display displayName for the account
      Returns:
      future completing with true if updated, false if account not found

    • transfer

      @AvailableSince("1.0") CompletableFuture<BigDecimal> transfer(UUID fromHolderId, UUID toHolderId, BigDecimal amount)
      Transfers funds from one holder's account to another holder's account.

      If the source account has insufficient funds, the transfer will fail exceptionally.

      Parameters:
      fromHolderId - the holder transferring funds
      toHolderId - the holder receiving funds
      amount - the amount to transfer
      Returns:
      future completing with the amount actually transferred

    • deposit

      @AvailableSince("1.0") CompletableFuture<BigDecimal> deposit(UUID holderId, BigDecimal amount)
      Deposits funds into the specified holder's account.
      Parameters:
      holderId - the holder's unique identifier
      amount - the amount to deposit (must be positive)
      Returns:
      future completing with the amount actually deposited

    • withdraw

      @AvailableSince("1.0") CompletableFuture<BigDecimal> withdraw(UUID holderId, BigDecimal amount)
      Withdraws funds from the specified holder's account.

      If the account has insufficient funds, the withdrawal will fail exceptionally.

      Parameters:
      holderId - the holder's unique identifier
      amount - the amount to withdraw (must be positive)
      Returns:
      future completing with the amount actually withdrawn

    • getTopBalances

      @AvailableSince("1.0") CompletableFuture<Map<UUID,BigDecimal>> getTopBalances(int limit)
      Gets the top balances sorted by balance in descending order.

      Useful for leaderboards and "baltop" commands. Returns a map of holder IDs to their balances, sorted highest first.

      Parameters:
      limit - the maximum number of entries to return
      Returns:
      future completing with a map of holder IDs to balances, sorted by balance (highest first)