Syncmoney

Cross-server economy synchronization plugin for Minecraft

Syncmoney

Enterprise-grade cross-server economy synchronization for Minecraft <a href="https://official.noie.fun"> <img src="https://img.shields.io/discord/1453099158884978850?label=Discord&logo=discord" alt="Discord"> </a> <a href="https://paypal.me/NoieSrv"> <img src="https://img.shields.io/badge/Donate-PayPal-blue" alt="Donate"> </a>

---

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.

---

Built for high-scale Minecraft networks

Syncmoney

Syncmoney

Syncmoney

Overview

Key Highlights

Features

Core Synchronization

Security & Protection

Web Admin Dashboard

Migration & Backup

Leaderboards & Integration

Requirements

Quick Start

1. Install

2. Configure

3. Multi-Server Setup

4. PlaceholderAPI (Optional)

Configuration

Economy Modes

Pay Settings

Circuit Breaker

Discord Webhook

Web Admin

Access

Configuration

In-Game Management

Production HTTPS Setup

Nginx Configuration

WebSocket / SSE support

HTTP to HTTPS redirect

Caddy Configuration

Commands

Players

Administrators

Admin Permission Tiers

Placeholders

Migration from CMI

Preview migration data

Start migration

Force migration (skip validation)

Force migration without backup

Performance

API for Developers

Vault API

Event System

REST API

Health check (no auth)

Economy stats

Troubleshooting

Building from Source

Clone the repository

Build the plugin (Shadow JAR)

Output: build/libs/Syncmoney-1.1.0.jar

Build PlaceholderAPI expansion

Output: build/libs/SyncmoneyExpansion-1.1.0.jar

Build web frontend

Support

License

Versions