Syncmoney 1.3.2

Overview
Syncmoney is an enterprise-oriented Minecraft economy plugin focused on safe, consistent cross-server balance synchronization. It bridges Vault and VaultUnlocked economies across network nodes using Redis Pub/Sub and relational database persistence, backed by in-memory caching and comprehensive circuit breakers.
Syncmoney manages balances, currency operations, and its own economy commands and administration tiers. It is not a general-purpose permission or arbitrary command replicator.

Key Features

1. Standard Economy Compatibility: Integrates seamlessly with Vault 1.7 and VaultUnlocked (Vault2 API).
2. Flexible Economy Modes: Supports standalone SQLite ([ICODE]local[/ICODE]), Redis-only sync ([ICODE]local_redis[/ICODE]), Redis + SQL database persistence ([ICODE]sync[/ICODE]), and CMI-authoritative sync ([ICODE]cmi[/ICODE]).
3. Distributed Synchronization: Redis Pub/Sub with atomic Lua scripts, monotonic versioning, and echo suppression to eliminate race conditions.
4. In-Memory Performance: O(1) balance reads served directly from memory; persistent storage writes handled asynchronously off the tick thread.
5. Multi-Layer Circuit Breaker: Real-time per-transaction limits, anomaly rate detection, and an independent per-player guard (L1–L4 states).
6. Comprehensive Auditing & Analytics: High-throughput asynchronous audit log pipeline with search, stats, automated cleanup, and external export.
7. Shadow Backups: Independent background account synchronization designed for cold-standby snapshots and state tracking.
8. Embedded Web Admin Dashboard: Modern web interface (Vue 3 / Undertow) for health telemetry, configuration inspection, audit viewing, and economy monitoring.
9. Region Scheduler Safe: Validated on Paper 1.20.4/26.2, Folia 26.2 BETA, and Canvas 26.2; scheduler boundaries are designed for region-threaded architectures.
10. Extensible Ecosystem: Official PlaceholderAPI expansion and Bukkit transaction events ([ICODE]PostTransactionEvent[/ICODE]).

Platform & Compatibility

The 1.3.0 acceptance matrix covers Paper 1.20.4, Paper 26.2, Folia 26.2 BETA, Canvas 26.2, and a two-backend Paper 26.2 network behind the latest [ICODE]velocity-ctd[/ICODE] build. This is a tested compatibility baseline, not a promise that an unreleased server build will remain binary-compatible.

Installation & Setup
[LIST=1]Backup: Stop your server and take a full backup of existing plugin configs, economy databases, and Redis persistence.Install Plugin: Place [ICODE]Syncmoney-1.3.0.jar[/ICODE] and your preferred Vault provider in the server's [ICODE]plugins/[/ICODE] directory. Remove any older Syncmoney JAR versions.Initialize Configuration: Start the server once to generate default configuration files, then stop it.Configure Node: In [ICODE]plugins/Syncmoney/config.yml[/ICODE]:

1. Assign a unique [ICODE]server-name[/ICODE] (e.g., [ICODE]survival-01[/ICODE], [ICODE]lobby-01[/ICODE]).
2. Select your target [ICODE]economy.mode[/ICODE].
3. Configure Redis and SQL database connection credentials if using synchronized modes.

Start & Verify: Start the server. Confirm in the console logs that Syncmoney and Vault have registered successfully. Verify basic transactions with [ICODE]/money[/ICODE] and [ICODE]/pay[/ICODE].Placeholders (Optional): If using PlaceholderAPI, copy [ICODE]SyncmoneyExpansion-1.3.0.jar[/ICODE] into [ICODE]plugins/PlaceholderAPI/expansions/[/ICODE] and run [ICODE]/papi reload[/ICODE].
[/LIST]

Economy Modes

Minimal Standalone Configuration ([ICODE]local[/ICODE])

server-name: "single-01"
economy:
  mode: "local"
redis:
  enabled: false
database:
  enabled: false
db-enabled: false
pubsub-enabled: false

Shared Network Configuration ([ICODE]sync[/ICODE])
Set [ICODE]economy.mode: "sync"[/ICODE], enable both [ICODE]redis[/ICODE] and [ICODE]database[/ICODE], and ensure [ICODE]db-enabled: true[/ICODE] and [ICODE]pubsub-enabled: true[/ICODE]. Point all participating nodes to the same isolated Redis database and relational database schema while giving each server a distinct [ICODE]server-name[/ICODE].

Optional Modules & Lifecycle
All optional modules can be toggled in [ICODE]plugins/Syncmoney/config.yml[/ICODE].

Commands & Permissions
Player Commands

Administrative Commands

Administrative Permission Tiers
Configurable in [ICODE]config.yml[/ICODE] under [ICODE]admin-permissions[/ICODE]:

PlaceholderAPI Identifiers
Syncmoney provides an optional expansion ([ICODE]SyncmoneyExpansion[/ICODE]) for PlaceholderAPI:

Web Admin Setup & Security
The Web Admin module includes a lightweight Undertow HTTP server and pre-built frontend distribution.

web-admin:
  enabled: true
  server:
    host: "127.0.0.1"
    port: 8080
  security:
    api-key: "GENERATE_A_LONG_SECURE_RANDOM_KEY"
    cors-allowed-origins: "https://admin.yournetwork.com"

Security Recommendations
[LIST=1]Reverse Proxy: Bind Web Admin to [ICODE]127.0.0.1[/ICODE] and route external traffic through Nginx or Caddy with HTTPS.API Key: Always replace the placeholder API key with a cryptographically secure token.SSE / WebSocket: When reverse proxying, ensure proxy buffering is disabled to support live SSE updates.Firewall: Restrict external access to the configured HTTP port.
[/LIST]

Developer Integration
Vault Provider Access
Syncmoney registers itself as a standard Vault provider:

RegisteredServiceProvider rsp = getServer().getServicesManager().getRegistration(Economy.class);
if (rsp != null) {
    Economy economy = rsp.getProvider();
    BigDecimal balance = BigDecimal.valueOf(economy.getBalance(player));
}

On servers running VaultUnlocked, Syncmoney also registers modern Vault2 services automatically.
Transaction Events
Subscribe to [ICODE]PostTransactionEvent[/ICODE] for transaction auditing:

@EventHandler
public void onPostTransaction(PostTransactionEvent event) {
    if (!event.isSuccess()) {
        return;
    }
    UUID playerUuid = event.getPlayerUuid();
    BigDecimal amount = event.getAmount();
    AsyncPreTransactionEvent.TransactionType type = event.getType();
    // Handle post-transaction telemetry
}

Building from Source
Syncmoney uses Gradle with a Java 21 toolchain:

# Build the plugin JAR and PAPI expansion
./gradlew test shadowJar :syncmoney-papi-expansion:jar
# Build Web Admin frontend (requires Node.js and pnpm)
cd syncmoney-web
pnpm install
pnpm typecheck
pnpm test:unit --run
pnpm build

Compiled JAR files are produced in [ICODE]build/libs/[/ICODE] and [ICODE]syncmoney-papi-expansion/build/libs/[/ICODE].

Troubleshooting & Support

1. Balances Not Synchronizing: Ensure all nodes have identical Redis server settings and databases. Verify that each node has a unique [ICODE]server-name[/ICODE] in [ICODE]config.yml[/ICODE] and [ICODE]pubsub-enabled: true[/ICODE].
2. Account Locked: If a player account trips rate or anomaly limits, inspect [ICODE]/syncmoney audit [/ICODE] to diagnose the trigger, then unlock with [ICODE]/syncmoney breaker unlock [/ICODE].
3. Configuration Reload Incomplete: Check the console output when executing [ICODE]/syncmoney reload[/ICODE]. Settings requiring service reconstruction require a full server restart.
4. Reporting Issues: Include plugin version ([ICODE]/syncmoney version[/ICODE]), server software build ([ICODE]/version[/ICODE]), Java version, and sanitized logs/configs (redact passwords, API keys, and webhook URLs).
5. GitHub Issues: Issues Tracker
6. Community Discord: Join Discord

License
This project is licensed under the Apache License 2.0.