SMPEcoGuard v1.0

Every SMP server with an active economy eventually reaches the same problem: something does not feel right.

A player suddenly has far more money than expected, shop prices start losing balance, money generation becomes difficult to understand, and staff members are forced to manually compare console logs, balance changes, plugin activity and player reports.


SMPEcoGuard is not an economy plugin and does not replace your current economy system.

It works as a professional monitoring, protection and analytics layer for Vault-based economies.

It watches money movement, captures direct transaction data from supported plugins, detects suspicious earning behavior, stores alerts, creates economy snapshots, calculates a server economy health score, and gives staff clear tools to inspect, export and moderate economy activity safely.

• Monitor money flow across your server economy.
• Detect abnormal earnings before they damage your economy.
• Understand where money comes from with direct plugin integrations.
• Review suspicious players using staff commands and GUI tools.
• Track inflation and economy health through snapshots and reports.
• Export evidence in CSV or JSON for review, appeals or external analysis.
• Moderate safely using protected tax and reset actions with audit logs.

Many economy monitoring plugins only see raw balance changes.

SMPEcoGuard goes further.

When supported plugins fire real transaction events, SMPEcoGuard records the transaction directly instead of only guessing from the final balance. This allows the plugin to understand whether money came from a shop sale, a job reward, a purchase, staff moderation, or an unknown balance change.

• EconomyShopGUI
• EconomyShopGUI Premium
• ShopGUIPlus
• Jobs Reborn
• ExcellentShop
• Tax actions
• Reset actions
• Vault balance polling fallback

Direct integrations are stored as real plugin transactions with inferred=false.

Unsupported or unknown balance changes are still detected through Vault polling and stored as inferred balance changes with inferred=true.



Each transaction can store useful context for staff review and future analysis.

Depending on the source and integration, SMPEcoGuard can record:

• Player
• Previous balance
• New balance
• Balance delta
• Transaction type
• Transaction source
• Timestamp
• Whether the transaction was inferred or directly captured
• Currency
• Integration result
• Item material
• Item identifier
• Shop section
• Item amount

This makes it much easier to understand what actually happened instead of only seeing that a player’s balance changed.



SMPEcoGuard also monitors player balances through Vault polling.

This fallback allows the plugin to detect balance changes even when they come from unsupported plugins, commands, admin actions or systems that do not expose direct transaction events.

Vault polling transactions are useful because they ensure money movement is still visible, but they may not include detailed shop, item or job metadata.

• Direct integrations provide precise transaction context.
• Vault polling catches unknown balance changes.
• Suppression logic helps prevent the same movement from being counted twice.

SMPEcoGuard includes a suspicious earning detection system designed for SMP and economy servers.

It does not simply check whether a player earned “too much money”. Instead, it analyzes repeated economy behavior and tries to detect patterns that may indicate automated farms, exploit loops, macro activity, abuse or abnormal money generation.

• Repeated earning amounts
• Similar transaction values
• Stable or suspicious timing intervals
• High-volume earning bursts
• Short-term earning spikes
• Long-term earning spikes
• Recent player earning history
• Configurable thresholds
• Cooldowns to reduce alert spam

When suspicious behavior is detected, SMPEcoGuard can create a persistent staff alert with a risk level and reason.

Important: the anti-farm system is heuristic. It is designed to help staff detect and review suspicious economy patterns, not to automatically punish players.



SMPEcoGuard can check configurable earning windows such as short-term and long-term limits.

This allows staff to detect cases where a player generates too much money in a short period of time, even if the behavior does not perfectly match a repeated farming pattern.

Example use cases:

• A player earns an abnormal amount in 15 minutes.
• A player earns far more than expected in 24 hours.
• A farm produces money at a perfectly stable interval.
• A shop/job loop generates repeated identical payouts.

SMPEcoGuard can support exemption rules for trusted players, staff testing, planned events or controlled economy operations.

Typical use cases include:

• Exempting trusted staff during economy testing.
• Ignoring planned server events.
• Avoiding false positives during admin balancing work.
• Temporarily excluding specific players or permissions from detection.

SMPEcoGuard calculates an economy health score from 0 to 100.

This score gives staff a quick way to understand whether the economy is healthy, unstable or moving toward a dangerous state.

The health score can consider:

• Total money growth
• Inflation percentage
• Alert volume
• Farm flags
• Money concentration among top holders
• Generated money
• Removed money

Economy status can move through clear states such as:

• STABLE
• WARNING
• UNSTABLE
• CRITICAL

This helps staff understand the global economy without manually reading database rows or console logs.



Snapshots are historical records of your economy state.

They can store:

• Total money
• Known players
• Money generated today
• Money removed today
• Net growth
• Growth percentage
• Economy status
• Health score
• Alert count
• Farm flag count
• Top earners

Snapshots make it easier to compare your economy over time and understand what changed after events, updates, shop changes or player activity spikes.



SMPEcoGuard can generate scheduled daily and weekly economy reports.

Reports can summarize:

• Economy health
• Total money
• Generated money
• Removed money
• Growth percentage
• Alerts
• Farm flags
• Top earners
• Resolved and unresolved issues

This allows staff to keep track of the economy without manually checking the plugin every day.



SMPEcoGuard includes a staff dashboard designed to give a fast overview of the server economy directly in-game.

The dashboard can display:

• Total money
• Generated money today
• Removed money today
• Economy status
• Health score
• Alerts today
• Top earners
• Recent alerts
• Snapshot actions
• Export actions

Staff can quickly move from a global economy overview to alerts, player inspection and exports.





Staff can inspect individual players to understand their economy activity.

A player profile can show:

• Current / last known balance
• Recent transactions
• Generated money
• Removed money
• Suspicious earning history
• Farm flags
• Alerts linked to the player
• Stored economy data

This is useful when reviewing reports, checking suspicious players, handling appeals or investigating possible exploits.



Alerts are stored persistently, not just shown once in chat.

Each alert can include:

• Alert ID
• Player
• Risk level
• Reason
• Amount
• Source
• Timestamp
• Status
• Resolved state

Staff can review alerts from commands or GUI and resolve them when they have been handled.



SMPEcoGuard can optionally forward important information to Discord using webhooks.

Supported Discord notifications can include:

• Economy alerts
• Suspicious earning warnings
• Farm detection alerts
• Inflation alerts
• Snapshots
• Scheduled reports

This helps your staff team stay informed even when they are not online in-game.



Staff can apply a percentage tax to:

• One player
• All online players

Tax actions are performed through Vault and can be protected by permissions, confirmations and cooldowns.

Tax actions are also written to audit storage and tax ledger storage, making staff economy changes trackable.



Staff can reset:

• One player
• All online players

Reset actions can require confirmation to prevent accidental economy damage.

Every committed reset action is recorded in the audit log.

Staff moderation actions are tracked separately from normal player income.

This means tax and reset activity does not pollute anti-farm detection as if it were normal player economy behavior.



Important staff actions can be recorded with useful context.

Audit data can include:

• Who performed the action
• Target player or target scope
• Action type
• Amount or percentage
• Previous balance
• New balance
• Timestamp
• Reason / metadata

This gives server owners better accountability over economy moderation.



SMPEcoGuard includes built-in exports for staff review and external analysis.

Supported export types include:

• Transactions
• Alerts
• Snapshots
• Player economy summaries

Supported formats:

• CSV
• JSON

Export rows can include evidence fields such as:

• Source
• Delta
• Timestamp
• Transaction type
• Integration result
• Currency
• Item material
• Item identifier
• Shop section
• Item amount
• Inferred/direct status

This is useful for staff investigations, player appeals, economy balancing and long-term server analysis.




SQLite is simple and works well for small to medium servers.



MySQL is recommended for larger servers, long-term production usage or networks that need stronger database scalability.



The storage layer can include:

• Persistent players
• Transactions
• Alerts
• Snapshots
• Audit logs
• Tax ledger rows
• Farm flags
• Schema migrations
• Indexed tables

SMPEcoGuard can automatically clean old data based on configurable retention settings.

Cleanup can apply to:

• Transactions
• Alerts
• Farm flags
• Audit logs
• Tax ledger entries

Cleanup runs in batches to avoid deleting too much data in one cycle.



Reliability features can include:

• Transaction retry queues
• Balance persistence retry queues
• Fallback files for pending transactions
• Fallback files for pending balances
• Startup diagnostics
• Shutdown diagnostics
• Slow Vault operation warnings
• Temporary Vault read circuit protection
• Configurable debug logging

This helps reduce the chance of losing important economy data during temporary database or runtime issues.



SMPEcoGuard is designed around Paper and Folia-aware scheduling.

It uses a scheduler abstraction to separate runtime behavior between standard Paper servers and Folia-style scheduling.

The plugin is designed to keep database work async and route player-sensitive work through the correct scheduler path when needed.

Important: on Folia, SMPEcoGuard is scheduler-aware, but your Vault economy provider and hooked plugins must also be safe and compatible with Folia.



When PlaceholderAPI is installed, SMPEcoGuard can expose placeholders for scoreboards, menus, holograms and other plugins.

Available placeholders can include economy and player data such as:

• Total money
• Generated money today
• Removed money today
• Economy status
• Health score
• Alerts today
• Player earned today
• Player lost today
• Top earner name
• Top earner amount
• Player farm flag count
• Next scheduled report information

Placeholder values are designed to be cache-backed to avoid unnecessary repeated database reads.



SMPEcoGuard can integrate with popular economy-related plugins when they are installed.

Optional supported integrations include:

• PlaceholderAPI
• EconomyShopGUI
• EconomyShopGUI Premium
• ShopGUIPlus
• Jobs Reborn
• ExcellentShop

SMPEcoGuard will still work without optional integrations, but direct transaction context is only available when supported plugins are installed and compatible.

• /smpecoguard dashboard opens the main staff dashboard GUI.
• /smpecoguard report generates an on-demand economy report.
• /smpecoguard alerts shows current stored alerts.
• /smpecoguard alerts resolve <id> marks an alert as resolved.
• /smpecoguard player <player> opens or displays a player economy inspection view.
• /smpecoguard snapshot creates a manual economy snapshot.
• /smpecoguard tax and /smpecoguard reset require confirmation before applying.
• Bulk tax/reset actions on online players require the additional smpecoguard.economy.bulk permission.
• /smpecoguard export has a sender cooldown to prevent spam.
• /smpecoguard debug is recommended when opening a support ticket.

smpecoguard.admin is recommended only for trusted administrators.

For read-only staff members, use more limited permissions such as dashboard, report, alerts, player and snapshot access without giving tax/reset permissions.

• Minecraft 1.21+
• Paper or Folia
• Java 21+
• Vault
• A Vault-compatible economy provider

• PlaceholderAPI
• EconomyShopGUI
• EconomyShopGUI Premium
• ShopGUIPlus
• Jobs Reborn
• ExcellentShop

Please read these limitations before purchasing or installing:

• SMPEcoGuard requires Vault and a Vault-compatible economy provider.
• SMPEcoGuard does not replace your economy plugin.
• Direct shop/item/job metadata is only available for supported integrations.
• Unsupported economy changes can still be detected through Vault polling, but may appear as inferred balance changes.
• Non-Vault currencies are ignored by shop integrations.
• Jobs Reborn tracking focuses on MONEY rewards only; EXP and POINTS are not treated as economy money.
• ExcellentShop multi-currency or non-Vault transactions may be ignored unless they expose a supported single Vault amount.
• Vault balance polling is not instant by nature and depends on the configured polling interval.
• The anti-farm system is heuristic. It alerts staff about suspicious patterns but does not replace an anticheat.
• Thresholds should be tuned to your server economy. A casual SMP, Skyblock server and high-multiplier economy server may require different limits.
• Offline player inspection depends on stored / last-known data unless your economy provider exposes reliable offline balances through Vault.
• For very large servers, MySQL is recommended over SQLite.
• On Folia, hooked plugins and your economy provider should also be Folia-safe.

Most economy plugins only move money.

SMPEcoGuard is different.

It gives server owners and staff visibility over the economy itself: where money is generated, who is earning abnormally fast, when inflation becomes dangerous, which players need review, and what actions were taken by staff.

If your server economy is part of your gameplay, SMPEcoGuard gives you the tools to protect it before small problems become server-wide damage.

• Better visibility
• Better staff investigations
• Better economy control
• Better long-term stability
• Less guessing

• Plugin overview what SMPEcoGuard is and what it is designed to do.
• Requirements Paper/Folia 1.21+, Java 21+, Vault and a Vault-compatible economy provider.
• Installation how to install the plugin, generate files and configure the first setup.
• Architecture bootstrap, runtime services, scheduler, modules, GUI, commands and integrations.
• Storage SQLite, MySQL, schema migrations, indexed tables and persistent economy data.
• Economy tracking direct integrations, Vault polling fallback and inferred/direct transaction separation.
• Supported modules EconomyShopGUI, EconomyShopGUI Premium, ShopGUIPlus, Jobs Reborn and ExcellentShop.
• Anti-farm detection repeated amounts, suspicious timing, bursts, earning patterns and cooldowns.
• Suspicious earnings configurable short-term and long-term earning windows.
• Whitelist and exemptions exempt players, permissions and temporary event windows.
• Health score 0–100 economy score based on growth, alerts, farm flags and money concentration.
• Snapshots and reports automatic/manual economy snapshots and scheduled daily/weekly reports.
• Staff GUI dashboard, alerts GUI, export GUI and player economy inspection GUI.
• Commands and permissions full command list, permission nodes and staff access separation.
• Tax and reset tools protected moderation actions with confirmations, cooldowns and audit logging.
• Audit trail staff action history, tax ledger entries and economy moderation accountability.
• Exports CSV/JSON exports for transactions, alerts, snapshots and player summaries.
• Retention cleanup automatic cleanup for old transactions, alerts, farm flags and audit data.
• Reliability retry queues, fallback files, diagnostics and slow Vault operation warnings.
• Paper and Folia scheduler adapter, async database work and runtime-safe execution notes.
• PlaceholderAPI cache-backed placeholders for economy totals, player stats, alerts and reports.
• Discord webhook alerts, snapshots and scheduled report notifications.
• Known limitations polling delay, non-Vault currencies, unsupported metadata and heuristic detection.

1. Stop your server.
2. Install Vault and a Vault-compatible economy provider.
3. Place SMPEcoGuard.jar inside your server's plugins folder.
4. Start the server once to generate config.yml, messages.yml and gui.yml.
5. Configure storage, thresholds, Discord webhook, modules and retention settings.
6. Restart the server or run /smpecoguard reload.
7. Run /smpecoguard debug to verify Vault, storage, tasks and optional modules.

SMPEcoGuard generates and uses:

• config.yml: storage, polling, thresholds, modules, Discord, retention, logging and safety settings.
• messages.yml: plugin messages.
• gui.yml: dashboard, alerts GUI, export GUI and player GUI layout/items.

Configuration files are versioned and can be updated through the plugin's configuration management system when new versions are released.



SMPEcoGuard can automatically create and use persistent tables for:

• Schema metadata
• Players
• Transactions
• Alerts
• Snapshots
• Audit logs
• Tax ledger rows
• Farm flags

The storage system is designed to persist important economy data across restarts and support long-term staff review.



The export system supports:

• Transactions
• Alerts
• Snapshots
• Player summaries

Available formats:

• CSV
• JSON

Exports are useful for staff investigations, player appeals, economy review, external analysis and record keeping.



When PlaceholderAPI is installed, SMPEcoGuard can expose placeholders for:

• Total money
• Money generated today
• Money removed today
• Economy status
• Economy health score
• Alerts today
• Player earned today
• Player lost today
• Top earner data
• Player farm flag count
• Next scheduled report information

Placeholder values are cache-backed to reduce repeated database reads from scoreboards, holograms and menu plugins.



Discord webhook support can be used for:

• Suspicious earning alerts
• Farm detection alerts
• Inflation alerts
• Snapshot notifications
• Daily reports
• Weekly reports

To use Discord webhooks, enable Discord support in the config and set your webhook URL.

• SMPEcoGuard is not an economy provider.
• Vault is required.
• Direct transaction metadata is available only for supported integrations.
• Unsupported balance changes may appear as inferred Vault polling transactions.
• Non-Vault currencies are ignored by shop integrations.
• Jobs Reborn tracking focuses on MONEY rewards only.
• ExcellentShop multi-currency or non-Vault transactions may be ignored.
• Balance polling is not instant and depends on the configured polling interval.
• Anti-farm detection is heuristic and does not automatically punish players.
• Thresholds should be tuned for your server economy.
• On Folia, your economy provider and hooked plugins should also be Folia-safe.

When requesting support, please include:

• Server software and version.
• Java version.
• SMPEcoGuard version.
• Vault version.
• Economy provider name.
• Storage type: SQLite or MySQL.
• Installed optional integrations.
• Relevant console errors.
• Output of /smpecoguard debug.
• Steps to reproduce the issue.