YAS Currency

YASCurrency - Major Economy Control Update

This update turns YASCurrency into a full economy-management system with transaction monitoring, account inspection, rollback tools, source blocking, configurable fees, QuestLines/Claims economy support, and API v4 for structured integrations.

Highlights

• Added full Economy Control system.
• Added transaction monitoring for digital and cash economy flows.
• Added advanced admin transaction journal.
• Added player account inspection with transaction history.
• Added rollback support through safe counter-transactions.
• Added source and external-ID blocking tools.
• Added configurable fees for QuestLines rewards and claim payments.
• Added optional inflation-control settings.
• Added optional dynamic reward-scaling settings.
• Added public API v4 with structured transaction contexts, fee policies, previews, and rich result objects.
• Improved localization handling for the admin UI.
• Improved VaultUnlocked naming consistency.

Added: Economy Control

• Added new economy and security tools for server owners.
• Added transaction monitoring dashboard.
• Added tracking for money creation, money destruction, transfers, warnings, and total money supply.
• Added configurable daily global money creation limit.
• Added configurable daily money creation limit per player.
• Added configurable large-transaction warning threshold.
• Added configurable high daily-gain warning threshold.
• Added configurable target money supply.
• Added configurable reward scaling min/max factors.
• Added optional inflation-control mode.
• Added optional dynamic reward-scaling mode.
• Transaction monitoring remains available for simple servers without forcing advanced economy controls.

Added: Transaction Journal

• Added improved admin transaction overview.
• Added transaction detail panel.
• Added selected transaction highlighting.
• Added transaction filtering by player, transaction ID, type, source, amount, warnings, blocked status, and duplicates.
• Added transaction summary cards for minted money, destroyed money, transfers, and warnings.
• Added readable transaction risk states.
• Added transaction source inspection.
• Added direct navigation from a transaction to the affected player account.
• Added safer transaction detail layout for amount, source, target, reason, external ID, metadata, and risk information.

Added: Rollback & Blocking Tools

• Added rollback action for selected transactions.
• Rollback now creates a safe counter-transaction instead of deleting transaction history.
• Added blocking action for suspicious transaction sources or external IDs.
• Added confirmation dialog for rollback and block actions.
• Added source/external-ID blocklist support.
• Added safer admin flow to prevent accidental destructive economy actions.

Added: Player Account Control

• Added detailed player account view in the admin accounts tab.
• Added player-specific transaction history.
• Added pagination for player account transaction history.
• Added direct account loading from selected transactions.
• Added account detail button for loading player account details without opening the player wallet frontend.
• Improved player account tools for give, take, and set balance operations.
• Improved visual transaction rows for player account history.
• Player account transaction amounts are now displayed with clearer income/expense coloring.

Added: Fees & Taxes

• Added configurable fee for QuestLines rewards.
• Added configurable fee for claim purchases.
• Added configurable fee for claim rent and renewal.
• Added support for showing fee metadata in transaction history.
• Improved fee handling for digital transaction flows.
• Improved fee handling for cash deposit and cash withdrawal flows.
• Improved fee visibility for admin transaction review.
• Improved player-facing fee visibility when structured transaction metadata is available.

Added: QuestLines & Claims Economy Support

• Added support for QuestLines reward fee handling.
• Added support for claim purchase fee handling.
• Added support for claim rent and renewal fee handling.
• Added clearer transaction source tracking for QuestLines and QuestLines Claims flows.
• Added support for claim-related external IDs in transaction tracking.
• Added improved transaction metadata support for claim and quest economy activity.

Added: API v4

• Added TransactionContext for structured transaction metadata.
• Added FeePolicy for explicit fee handling.
• Added TransactionCategory for cleaner transaction classification.
• Added PaymentChannel for digital, cash, or mixed transaction flows.
• Added TransactionPreview for pre-calculating transaction cost, fee, total, and status before charging a player.
• Added YasCurrencyTransactionResult for rich transaction responses.
• Added TransactionStatus for integration-friendly success and failure handling.
• Added preview methods for deposit, withdrawal, and transfer operations.
• Added context-aware deposit, withdrawal, and transfer methods.
• Added context-aware cash grant and cash spend methods.
• Added helper methods for QuestLines reward contexts.
• Added helper methods for claim purchase contexts.
• Added helper methods for claim rent contexts.
• Added API feature flags for structured transactions, fee policy, transaction previews, transaction results, and API v2 support.
• Updated public API version to API_VERSION 4.

Added: Transaction Preview Support

• Integrations can now calculate the final transaction before executing it.
• Preview includes requested amount, applied amount, fee, total, net amount, status, and message key.
• Preview helps shops, claims, quests, and other integrations show the final cost to players before charging them.
• Preview supports better handling of fees, insufficient funds, blocked transactions, and inflation-control reductions.

Improved: Admin UI

• Improved admin transaction layout.
• Improved transaction list readability.
• Improved transaction detail panel.
• Improved selected transaction state.
• Improved player account tab layout.
• Improved player transaction history display.
• Improved fees tab with QuestLines and Claims fee settings.
• Improved economy tab spacing and readability.
• Improved confirmation flow for rollback and block actions.
• Improved Admin UI localization handling.
• Improved VaultUnlocked display naming.

Improved: Localization

• Improved English and German admin language handling.
• Removed visible hardcoded Admin UI text from the UI layout where applicable.
• Moved visible admin text into language files.
• Improved consistency between English and German language files.
• Kept VaultUnlocked as a proper mod name in both languages.
• Improved translation coverage for new economy-control features.
• Improved translation coverage for API transaction message keys.

Improved: Cash & Digital Economy Flow

• Improved tracking for digital balance activity.
• Improved tracking for physical cash activity.
• Improved cash deposit and cash withdrawal fee support.
• Improved transaction metadata for cash-related flows.
• Improved support for mixed economy setups where both digital balances and physical cash are used.

Improved: Transaction History

• Improved transaction labels for shop purchases, QuestLines rewards, and claim payments when structured metadata is available.
• Improved amount formatting for income and expense transactions.
• Improved fee display support in transaction history.
• Improved hiding of technical audit entries from normal player-facing transaction history.
• Improved readability for transaction source and reason fields.

Compatibility

• Existing legacy API methods remain available.
• Existing reason-string based integrations continue to work.
• New integrations should prefer TransactionContext and FeePolicy.
• QuestLines and QuestLines Claims support remain optional.
• VaultUnlocked support remains optional and depends on the available VaultUnlocked environment.
• Physical cash support depends on configured cash items and compatible integrations.

Developer Notes

• API v4 is designed to reduce reliance on plain reason strings.
• Integrations can now pass source, category, external ID, display reason, metadata, fee policy, and payment channel in a structured way.
• Use previews before charging players in shops, claims, quest systems, and custom payment flows.
• Use explicit fee policies for predictable fee handling.
• Use transaction result objects for better success/failure handling.
• Use structured external IDs to make transaction review and source blocking more reliable.

Example API v4 Flow

TransactionContext ctx = TransactionContext.builder()
    .source("YetAnotherShop")
    .category(TransactionCategory.SHOP_PURCHASE)
    .feePolicy(FeePolicy.SHOP_BUY)
    .externalId(orderId)
    .displayReason("Shop purchase: " + itemName)
    .metadata("item", itemName)
    .metadata("quantity", String.valueOf(quantity))
    .build();

TransactionPreview preview = YasCurrencyAPI.previewWithdraw(playerUuid, price, ctx);

if (preview.allowed()) {
    YasCurrencyTransactionResult result = YasCurrencyAPI.withdraw(playerUuid, price, ctx);
}

Notes for Server Owners

• Simple servers can continue using YASCurrency as a wallet, cash, HUD, and transaction plugin.
• Advanced economy controls are optional.
• Transaction monitoring is designed to help understand where money enters and leaves the economy.
• Inflation control and reward scaling should be configured carefully for your server economy.
• For best results, compatible plugins should use the new API v4 structured transaction flow.