Syncmoney

Syncmoney

<b>Enterprise-grade cross-server economy synchronization for Minecraft</b>

---

Overview

Syncmoney is a high-performance Minecraft economy plugin designed for multi-server networks. It synchronizes player balances across all servers in real-time using Redis Pub/Sub, with comprehensive protection against economic exploits and data loss.

Perfect for: Survival servers, factions, SMPs, minigame networks, and any multi-server economy ecosystem.

Key Highlights

- ⚡ Discord Webhooks — In-memory caching with O(1) balance lookups - 🔄 Discord Webhooks — Redis Pub/Sub propagation - 🛡️ Discord Webhooks — Enterprise-grade economic protection - 🌐 Discord Webhooks — Vue 3 dashboard with real-time monitoring - 🔧 Discord Webhooks — Works with any Vault-enabled economy plugin - 📊 Discord Webhooks — Complete transaction history with cursor-based pagination - 🎮 Discord Webhooks — Region-based scheduling support - 💾 Discord Webhooks — Automatic background backup to external databases - 🔔 Discord Webhooks — Real-time security notifications

---

Features

Core Synchronization

- Version-based Optimistic Locking — Balance changes instantly propagate to all servers via Redis Pub/Sub - Version-based Optimistic Locking — Full compatibility with any Vault-enabled economy plugin (EssentialsX, CMI, etc.) - Version-based Optimistic Locking — 7 Redis Lua scripts prevent money duplication during race conditions - Version-based Optimistic Locking — Automatic fallback chain: Memory → Redis → Database → LocalSQLite - Version-based Optimistic Locking — Full Vault bank API implementation with Redis-backed storage - Version-based Optimistic Locking — Prevents ABA problems across distributed nodes

Security & Protection

- Discord Webhook Alerts - Single transaction limits - Rate limiting (transactions per second) - Sudden balance change detection - Periodic inflation monitoring - Discord Webhook Alerts - L1: Rate limiting per player - L2: Anomaly detection with warning state - L3: Auto-lock for suspicious activity - L4: Global economy lock - Discord Webhook Alerts — WAL-based graceful fallback for queue saturation - Discord Webhook Alerts — Prevents money loss when players teleport during transactions - Discord Webhook Alerts — Guards against failed database writes - Discord Webhook Alerts — Real-time security notifications for 11 event types

Web Admin Dashboard

- PWA Support — Server status, Redis/DB health, circuit breaker state - PWA Support — Intelligent SSE reconnections with Exponential Backoff & Jitter - PWA Support — Total supply, player counts, transaction statistics - PWA Support — Search, filter, cursor-based pagination for massive datasets - PWA Support — Edit server config without file access - PWA Support — Full zh-TW and en-US support - PWA Support — User preference persistence - PWA Support — Installable as a standalone app

Migration & Backup

- Automatic Backup — One-command import from CMI economy - Automatic Backup — Combines economy data from multiple CMI servers (LATEST/SUM/MAX strategies) - Automatic Backup — Automatic background backup to external databases - Automatic Backup — Large migrations can resume if interrupted - Automatic Backup — Creates JSON/SQL backup before migration

Leaderboards & Integration

- Audit Trail — Redis-powered sorted set leaderboard with smart formatting - Audit Trail — 10+ dynamic placeholders for scoreboards - Audit Trail — Region-based scheduling compatibility - Audit Trail — Cursor-based pagination with millisecond sequence ordering

---

Requirements

| Component | Version | |-----------|---------| | Server | Paper 1.20+ / Spigot 1.20+ / Folia 1.20+ | | Java | 21+ | | Redis | 5.0+ (for multi-server sync) | | Database | MySQL 8.0+ / MariaDB 10.5+ / PostgreSQL 13+ / SQLite | | Plugin | Vault (required) | | Plugin | PlaceholderAPI (optional) |

> Note: Redis and a database (MySQL/PostgreSQL) are required for cross-server sync. For single-server use, Syncmoney works with SQLite only (no Redis needed).

---

Quick Start

1. Install

Place `Syncmoney.jar` in your server's `plugins/` folder.

2. Configure

Edit `plugins/Syncmoney/config.yml`:

```yaml server-name: "survival-01"

redis: enabled: true host: "localhost" port: 6379

database: enabled: true type: "mysql" host: "localhost" port: 3306 username: "root" password: "" database: "syncmoney" ```

3. Multi-Server Setup

1. Install Syncmoney on same Redis instance servers 2. Connect all servers to the same Redis instance 3. Set a unique `server-name` for each server 4. Restart all servers — economy syncs automatically

4. PlaceholderAPI (Optional)

For scoreboard placeholders:

1. Download `SyncmoneyExpansion.jar` from Releases 2. Place in `plugins/PlaceholderAPI/expansions/` 3. Restart the server

---

Configuration

Economy Modes

| Mode | Description | |------|-------------| | `auto` | Auto-detect based on Redis/DB availability (recommended) | | `local` | Single server only, SQLite backup | | `local_redis` | Multi-server sync via Redis (no MySQL) | | `sync` | Full cross-server sync with Redis + MySQL | | `cmi` | Direct CMI database integration |

Pay Settings

```yaml pay: cooldown-seconds: 30 min-amount: 1 max-amount: 1000000 confirm-threshold: 100000 ```

Circuit Breaker

```yaml circuit-breaker: enabled: true max-single-transaction: 100000000 max-transactions-per-second: 10 rapid-inflation-threshold: 0.2 sudden-change-threshold: 100

player-protection: enabled: true rate-limit: max-transactions-per-second: 5 max-transactions-per-minute: 50 max-amount-per-minute: 1000000 ```

Discord Webhook

```yaml discord-webhook: enabled: false webhooks: - name: "admin-alerts" url: "https://discord.com/api/webhooks/YOUR_WEBHOOK_URL_HERE" type: "private" events: - "player_warning" - "player_locked" - "player_unlocked" - "global_lock" - "circuit_breaker_trigger" ```

---

Web Admin

Syncmoney includes a built-in web administration panel for monitoring economy status and managing transactions.

Access

By default, the Web Admin is available at `http://localhost:8080` (when running locally).

Configuration

```yaml web-admin: enabled: true server: host: "0.0.0.0" port: 8080 security: api-key: "your-secure-api-key-here" cors-allowed-origins: "*" rate-limit: enabled: true requests-per-minute: 60 ```

In-Game Management

``` /syncmoney web download [latest] # Download web frontend from GitHub /syncmoney web build # Build frontend from source /syncmoney web open # Open the web admin server /syncmoney web status # Show web frontend status /syncmoney web check # Check for available updates ```

Production HTTPS Setup

Syncmoney Web Admin does not include built-in SSL support. For production environments, use a reverse proxy:

Nginx Configuration

```nginx server { listen 443 ssl; server_name syncmoney.yourdomain.com;

ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem;

location / { proxy_pass http://localhost:8080; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme;

WebSocket / SSE support

proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } }

HTTP to HTTPS redirect

server { listen 80; server_name syncmoney.yourdomain.com; return 301 https://$server_name$request_uri; } ```

Caddy Configuration

```caddy syncmoney.yourdomain.com { reverse_proxy localhost:8080 tls /path/to/cert.pem /path/to/key.pem } ```

Note: When using a reverse proxy, update `config.yml` to bind to localhost only:

```yaml web-admin: server: host: "127.0.0.1" port: 8080 ```

---

Commands

Players

| Command | Description | Permission | |---------|-------------|------------| | `/money` | View your balance | `syncmoney.money` | | `/money <player>` | View another player's balance | `syncmoney.money.others` | | `/pay <player> <amount>` | Transfer money to player | `syncmoney.pay` | | `/pay confirm` | Confirm large transfer | — | | `/baltop [page]` | View global leaderboard | `syncmoney.money` | | `/baltop me` | View your rank | `syncmoney.money` |

Administrators

| Command | Description | Permission | |---------|-------------|------------| | `/syncmoney admin give <player> <amount>` | Give money to player | `syncmoney.admin.give` | | `/syncmoney admin take <player> <amount>` | Take money from player | `syncmoney.admin.take` | | `/syncmoney admin set <player> <amount>` | Set player balance | `syncmoney.admin.set` | | `/syncmoney admin reset <player>` | Reset balance to zero | `syncmoney.admin.set` | | `/syncmoney migrate cmi` | Migrate from CMI | `syncmoney.admin` | | `/syncmoney migrate local-to-sync` | Migrate from LOCAL to SYNC | `syncmoney.admin` | | `/syncmoney breaker status` | View protection status | `syncmoney.admin` | | `/syncmoney breaker unlock <player>` | Unlock locked player | `syncmoney.admin` | | `/syncmoney audit <player>` | View transaction history | `syncmoney.admin.audit` | | `/syncmoney audit search` | Advanced search | `syncmoney.admin.audit` | | `/syncmoney econstats` | View economy statistics | `syncmoney.admin` | | `/syncmoney monitor` | View system monitoring | `syncmoney.admin` | | `/syncmoney shadow status` | View shadow sync status | `syncmoney.admin` | | `/syncmoney web status` | View web admin status | `syncmoney.admin` | | `/syncmoney reload` | Reload configuration | `syncmoney.admin` | | `/syncmoney test concurrent-pay` | Stress test | `syncmoney.admin.test` |

Admin Permission Tiers

| Tier | Permission | Daily Give Limit | Daily Take Limit | |------|-----------|-----------------|-----------------| | Observe | `syncmoney.admin.observe` | 0 | 0 | | Reward | `syncmoney.admin.reward` | 100,000 | 0 | | General | `syncmoney.admin.general` | 1,000,000 | 1,000,000 | | Full | `syncmoney.admin.full` | Unlimited | Unlimited |

---

Placeholders

Requires SyncmoneyExpansion + PlaceholderAPI.

| Placeholder | Description | |-------------|-------------| | `%syncmoney_balance%` | Player's current balance | | `%syncmoney_balance_formatted%` | Balance with smart formatting | | `%syncmoney_balance_abbreviated%` | Balance abbreviated (1.5K, 2.3億) | | `%syncmoney_rank%` | Player's leaderboard rank | | `%syncmoney_my_rank%` | Player's own rank | | `%syncmoney_total_supply%` | Total money in circulation | | `%syncmoney_total_players%` | Total players in leaderboard | | `%syncmoney_online_players%` | Currently online players | | `%syncmoney_version%` | Plugin version | | `%syncmoney_top_<n>%` | Balance of player at rank n | | `%syncmoney_balance_<player>%` | Specific player's balance by name |

---

Migration from CMI

```bash

Preview migration data

/syncmoney migrate cmi -preview

Start migration

/syncmoney migrate cmi

Force migration (skip validation)

/syncmoney migrate cmi -force

Force migration without backup

/syncmoney migrate cmi -force -no-backup ```

Features: - PostgreSQL, MySQL, and SQLite support - Multi-server data merge (LATEST/SUM/MAX strategies) - Automatic backup before migration - Checkpoint resume for large datasets - Auto-disable CMI economy after migration

---

Performance

Syncmoney is optimized for high-throughput scenarios:

- OverflowLog WAL (default: 30 connections) - OverflowLog WAL — prevents main thread blocking (capacity: 50,000 events) - OverflowLog WAL — O(1) balance reads with ConcurrentHashMap - OverflowLog WAL — efficient audit log persistence (500 records/batch) - OverflowLog WAL — single-writer pattern avoids contention - OverflowLog WAL — 7 scripts ensure consistency without locks - OverflowLog WAL — prevents data loss when queues saturate

---

API for Developers

Syncmoney provides multiple integration points:

Vault API

```java // Get economy via Vault Economy economy = Bukkit.getServicesManager() .getRegistration(Economy.class).getProvider();

// Standard operations economy.getBalance(player); economy.depositPlayer(player, amount); economy.withdrawPlayer(player, amount); ```

Event System

```java // Listen for completed transactions @EventHandler public void onTransaction(PostTransactionEvent event) { String player = event.getPlayerName(); BigDecimal amount = event.getAmount(); // type: DEPOSIT, WITHDRAW, TRANSFER, SET_BALANCE } ```

REST API

Full REST API available when Web Admin is enabled. See API Reference.

```bash

Health check (no auth)

curl http://localhost:8080/health

Economy stats

curl -H "Authorization: Bearer <api-key>" http://localhost:8080/api/economy/stats ```

For complete documentation, see: - API Reference - Developer Guide - Changelog

---

Troubleshooting

| Issue | Solution | |-------|----------| | "Server name not configured" | Set `server-name` in config.yml | | Redis connection failed | Verify host/port/password in config | | Balances not syncing | Ensure all servers use same Redis instance | | Performance issues | Increase `pool-size` and `queue-capacity` | | Circuit breaker locked | Use `/syncmoney breaker reset` to unlock | | Player account locked | Use `/syncmoney breaker unlock <player>` | | Web admin not loading | Check `web-admin.enabled: true` and port availability |

Enable `debug: true` in config.yml for detailed logs.

---

Building from Source

```bash

Clone the repository

git clone https://github.com/Misty4119/Syncmoney.git cd Syncmoney

Build the plugin (Shadow JAR)

./gradlew shadowJar

Output: build/libs/Syncmoney-1.1.0.jar

Build PlaceholderAPI expansion

cd syncmoney-papi-expansion && ../gradlew jar

Output: build/libs/SyncmoneyExpansion-1.1.0.jar

Build web frontend

cd syncmoney-web && pnpm install && pnpm build ```

---

Support

- Issues: Issues - Issues: %%MD1%%

---

License

Apache License 2.0 — Free to use, modify, and distribute.

---

<sub>Built for high-scale Minecraft networks</sub>