Syncmoney

Vault / VaultUnlocked compatible cross-server economy synchronization with Redis Pub/Sub, multi-layer transaction guards, auditing, shadow backups, and embedded Web Admin.

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

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

Platform & Compatibility

[!NOTE] Future server releases remain compatibility targets rather than unconditional guarantees. Always validate upgrades on a staging environment prior to updating production balances.

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 velocity-ctd build. This is a tested compatibility baseline, not a promise that an unreleased server build will remain binary-compatible.

Installation & Setup

1. Backup: Stop your server and take a full backup of existing plugin configs, economy databases, and Redis persistence.
2. Install Plugin: Place Syncmoney-1.3.0.jar and your preferred Vault provider in the server's plugins/ directory. Remove any older Syncmoney JAR versions.
3. Initialize Configuration: Start the server once to generate default configuration files, then stop it.
4. Configure Node: In plugins/Syncmoney/config.yml:
   • Assign a unique server-name (e.g., survival-01, lobby-01).
   • Select your target economy.mode.
   • Configure Redis and SQL database connection credentials if using synchronized modes.
5. Start & Verify: Start the server. Confirm in the console logs that Syncmoney and Vault have registered successfully. Verify basic transactions with /money and /pay.
6. Placeholders (Optional): If using PlaceholderAPI, copy SyncmoneyExpansion-1.3.0.jar into plugins/PlaceholderAPI/expansions/ and run /papi reload.

Economy Modes

Minimal Standalone Configuration (local)

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

Shared Network Configuration (sync)

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

Optional Modules & Lifecycle

All optional modules can be toggled in plugins/Syncmoney/config.yml.

[!IMPORTANT] Configuration Reload vs. Full Restart: /syncmoney reload updates localization messages and safe runtime parameters (display, pay, permissions, admin-permissions, debug). Changes to database/Redis connections, economy modes, module switches, schedulers, or Web Admin server endpoints require a full server restart. If modified, reload will notify you of the restart-only keys.

Commands & Permissions

Player Commands

Administrative Commands

Administrative Permission Tiers

Configurable in config.yml under admin-permissions:

PlaceholderAPI Identifiers

Syncmoney provides an optional expansion (SyncmoneyExpansion) for PlaceholderAPI:

[!TIP] Cache misses for offline player lookups resolve asynchronously in the background. If data is still loading, placeholders return N/A without freezing the main server thread.

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

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

Developer Integration

Vault Provider Access

Syncmoney registers itself as a standard Vault provider:

RegisteredServiceProvider<Economy> 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 PostTransactionEvent 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 build/libs/ and syncmoney-papi-expansion/build/libs/.

Troubleshooting & Support

• Balances Not Synchronizing: Ensure all nodes have identical Redis server settings and databases. Verify that each node has a unique server-name in config.yml and pubsub-enabled: true.

• Account Locked: If a player account trips rate or anomaly limits, inspect /syncmoney audit <player> to diagnose the trigger, then unlock with /syncmoney breaker unlock <player>.

• Configuration Reload Incomplete: Check the console output when executing /syncmoney reload. Settings requiring service reconstruction require a full server restart.

• Reporting Issues: Include plugin version (/syncmoney version), server software build (/version), Java version, and sanitized logs/configs (redact passwords, API keys, and webhook URLs).

• GitHub Issues: Issues Tracker

• Community Discord: Join Discord

License

This project is licensed under the Apache License 2.0.