\n
# Syncmoney<\/p>\n
\n
\n <\/p>\n
\n
\n
\n
\n \n<\/p>\n
\n Enterprise-grade cross-server economy synchronization for Minecraft<\/b>
\n <\/p>\n
<\/p>\n
<\/p>\n
—<\/p>\n
## Overview<\/p>\n
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.<\/p>\n
**Perfect for**: Survival servers, factions, SMPs, minigame networks, and any multi-server economy ecosystem.<\/p>\n
### Key Highlights<\/p>\n
– \u26a1 **Sub-millisecond reads** \u2014 In-memory caching with O(1) balance lookups
\n– \ud83d\udd04 **Instant cross-server sync** \u2014 Redis Pub\/Sub propagation
\n– \ud83d\udee1\ufe0f **4-layer circuit breaker** \u2014 Enterprise-grade economic protection
\n– \ud83c\udf10 **Built-in Web Admin** \u2014 Vue 3 dashboard with real-time monitoring
\n– \ud83d\udd27 **Zero-config Vault** \u2014 Works with any Vault-enabled economy plugin
\n– \ud83d\udcca **Full audit trail** \u2014 Complete transaction history with cursor-based pagination
\n– \ud83c\udfae **Folia compatible** \u2014 Region-based scheduling support
\n– \ud83d\udcbe **Shadow Sync** \u2014 Automatic background backup to external databases
\n– \ud83d\udd14 **Discord Webhooks** \u2014 Real-time security notifications<\/p>\n
—<\/p>\n
## Features<\/p>\n
### Core Synchronization<\/p>\n
– **Real-time Cross-Server Sync** \u2014 Balance changes instantly propagate to all servers via Redis Pub\/Sub
\n– **Vault Integration** \u2014 Full compatibility with any Vault-enabled economy plugin (EssentialsX, CMI, etc.)
\n– **Atomic Transactions** \u2014 7 Redis Lua scripts prevent money duplication during race conditions
\n– **Graceful Degradation** \u2014 Automatic fallback chain: Memory \u2192 Redis \u2192 Database \u2192 LocalSQLite
\n– **Bank Support** \u2014 Full Vault bank API implementation with Redis-backed storage
\n– **Version-based Optimistic Locking** \u2014 Prevents ABA problems across distributed nodes<\/p>\n
### Security & Protection<\/p>\n
– **4-Layer Circuit Breaker**
\n – Single transaction limits
\n – Rate limiting (transactions per second)
\n – Sudden balance change detection
\n – Periodic inflation monitoring
\n– **Per-Player Protection (L1-L4)**
\n – L1: Rate limiting per player
\n – L2: Anomaly detection with warning state
\n – L3: Auto-lock for suspicious activity
\n – L4: Global economy lock
\n– **Event Overflow Protection** \u2014 WAL-based graceful fallback for queue saturation
\n– **Transfer Guard** \u2014 Prevents money loss when players teleport during transactions
\n– **Rollback Protection** \u2014 Guards against failed database writes
\n– **Discord Webhook Alerts** \u2014 Real-time security notifications for 11 event types<\/p>\n
### Web Admin Dashboard<\/p>\n
– **Real-time Monitoring** \u2014 Server status, Redis\/DB health, circuit breaker state
\n– **Connection Resiliency** \u2014 Intelligent SSE reconnections with Exponential Backoff & Jitter
\n– **Economy Dashboard** \u2014 Total supply, player counts, transaction statistics
\n– **Audit Log Viewer** \u2014 Search, filter, cursor-based pagination for massive datasets
\n– **Configuration Editor** \u2014 Edit server config without file access
\n– **Internationalization** \u2014 Full zh-TW and en-US support
\n– **Dark\/Light Theme** \u2014 User preference persistence
\n– **PWA Support** \u2014 Installable as a standalone app<\/p>\n
### Migration & Backup<\/p>\n
– **CMI Migration Tool** \u2014 One-command import from CMI economy
\n– **Multi-Server Merge** \u2014 Combines economy data from multiple CMI servers (LATEST\/SUM\/MAX strategies)
\n– **Shadow Sync** \u2014 Automatic background backup to external databases
\n– **Checkpoint Resume** \u2014 Large migrations can resume if interrupted
\n– **Automatic Backup** \u2014 Creates JSON\/SQL backup before migration<\/p>\n
### Leaderboards & Integration<\/p>\n
– **Global Baltop** \u2014 Redis-powered sorted set leaderboard with smart formatting
\n– **PlaceholderAPI Expansion** \u2014 10+ dynamic placeholders for scoreboards
\n– **Folia Support** \u2014 Region-based scheduling compatibility
\n– **Audit Trail** \u2014 Cursor-based pagination with millisecond sequence ordering<\/p>\n
—<\/p>\n
## Requirements<\/p>\n
| Component | Version |
\n|———–|———|
\n| Server | Paper 1.20+ \/ Spigot 1.20+ \/ Folia 1.20+ |
\n| Java | 21+ |
\n| Redis | 5.0+ (for multi-server sync) |
\n| Database | MySQL 8.0+ \/ MariaDB 10.5+ \/ PostgreSQL 13+ \/ SQLite |
\n| Plugin | Vault (required) |
\n| Plugin | PlaceholderAPI (optional) |<\/p>\n
> **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).<\/p>\n
—<\/p>\n
## Quick Start<\/p>\n
### 1. Install<\/p>\n
Place `Syncmoney.jar` in your server’s `plugins\/` folder.<\/p>\n
### 2. Configure<\/p>\n
Edit `plugins\/Syncmoney\/config.yml`:<\/p>\n
“`yaml
\nserver-name: “survival-01”<\/p>\n
redis:
\n enabled: true
\n host: “localhost”
\n port: 6379<\/p>\n
database:
\n enabled: true
\n type: “mysql”
\n host: “localhost”
\n port: 3306
\n username: “root”
\n password: “”
\n database: “syncmoney”
\n“`<\/p>\n
### 3. Multi-Server Setup<\/p>\n
1. Install Syncmoney on **all** servers
\n2. Connect all servers to the **same Redis instance**
\n3. Set a unique `server-name` for each server
\n4. Restart all servers \u2014 economy syncs automatically<\/p>\n
### 4. PlaceholderAPI (Optional)<\/p>\n
For scoreboard placeholders:<\/p>\n
1. Download `SyncmoneyExpansion.jar` from Releases
\n2. Place in `plugins\/PlaceholderAPI\/expansions\/`
\n3. Restart the server<\/p>\n
—<\/p>\n
## Configuration<\/p>\n
### Economy Modes<\/p>\n
| Mode | Description |
\n|——|————-|
\n| `auto` | Auto-detect based on Redis\/DB availability (recommended) |
\n| `local` | Single server only, SQLite backup |
\n| `local_redis` | Multi-server sync via Redis (no MySQL) |
\n| `sync` | Full cross-server sync with Redis + MySQL |
\n| `cmi` | Direct CMI database integration |<\/p>\n
### Pay Settings<\/p>\n
“`yaml
\npay:
\n cooldown-seconds: 30
\n min-amount: 1
\n max-amount: 1000000
\n confirm-threshold: 100000
\n“`<\/p>\n
### Circuit Breaker<\/p>\n
“`yaml
\ncircuit-breaker:
\n enabled: true
\n max-single-transaction: 100000000
\n max-transactions-per-second: 10
\n rapid-inflation-threshold: 0.2
\n sudden-change-threshold: 100<\/p>\n
player-protection:
\n enabled: true
\n rate-limit:
\n max-transactions-per-second: 5
\n max-transactions-per-minute: 50
\n max-amount-per-minute: 1000000
\n“`<\/p>\n
### Discord Webhook<\/p>\n
“`yaml
\ndiscord-webhook:
\n enabled: false
\n webhooks:
\n – name: “admin-alerts”
\n url: “https:\/\/discord.com\/api\/webhooks\/YOUR_WEBHOOK_URL_HERE”
\n type: “private”
\n events:
\n – “player_warning”
\n – “player_locked”
\n – “player_unlocked”
\n – “global_lock”
\n – “circuit_breaker_trigger”
\n“`<\/p>\n
—<\/p>\n
## Web Admin<\/p>\n
Syncmoney includes a built-in web administration panel for monitoring economy status and managing transactions.<\/p>\n
### Access<\/p>\n
By default, the Web Admin is available at `http:\/\/localhost:8080` (when running locally).<\/p>\n
### Configuration<\/p>\n
“`yaml
\nweb-admin:
\n enabled: true
\n server:
\n host: “0.0.0.0”
\n port: 8080
\n security:
\n api-key: “your-secure-api-key-here”
\n cors-allowed-origins: “*”
\n rate-limit:
\n enabled: true
\n requests-per-minute: 60
\n“`<\/p>\n
### In-Game Management<\/p>\n
“`
\n\/syncmoney web download [latest] # Download web frontend from GitHub
\n\/syncmoney web build # Build frontend from source
\n\/syncmoney web open # Open the web admin server
\n\/syncmoney web status # Show web frontend status
\n\/syncmoney web check # Check for available updates
\n“`<\/p>\n
### Production HTTPS Setup<\/p>\n
Syncmoney Web Admin does not include built-in SSL support. For production environments, use a reverse proxy:<\/p>\n
#### Nginx Configuration<\/p>\n
“`nginx
\nserver {
\n listen 443 ssl;
\n server_name syncmoney.yourdomain.com;<\/p>\n
ssl_certificate \/path\/to\/cert.pem;
\n ssl_certificate_key \/path\/to\/key.pem;<\/p>\n
location \/ {
\n proxy_pass http:\/\/localhost:8080;
\n proxy_http_version 1.1;
\n proxy_set_header Host $host;
\n proxy_set_header X-Real-IP $remote_addr;
\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
\n proxy_set_header X-Forwarded-Proto $scheme;<\/p>\n
# WebSocket \/ SSE support
\n proxy_set_header Upgrade $http_upgrade;
\n proxy_set_header Connection “upgrade”;
\n }
\n}<\/p>\n
# HTTP to HTTPS redirect
\nserver {
\n listen 80;
\n server_name syncmoney.yourdomain.com;
\n return 301 https:\/\/$server_name$request_uri;
\n}
\n“`<\/p>\n
#### Caddy Configuration<\/p>\n
“`caddy
\nsyncmoney.yourdomain.com {
\n reverse_proxy localhost:8080
\n tls \/path\/to\/cert.pem \/path\/to\/key.pem
\n}
\n“`<\/p>\n
**Note:** When using a reverse proxy, update `config.yml` to bind to localhost only:<\/p>\n
“`yaml
\nweb-admin:
\n server:
\n host: “127.0.0.1”
\n port: 8080
\n“`<\/p>\n
—<\/p>\n
## Commands<\/p>\n
### Players<\/p>\n
| Command | Description | Permission | ### Administrators<\/p>\n | Command | Description | Permission | ### Admin Permission Tiers<\/p>\n | Tier | Permission | Daily Give Limit | Daily Take Limit | —<\/p>\n ## Placeholders<\/p>\n Requires SyncmoneyExpansion + PlaceholderAPI.<\/p>\n | Placeholder | Description | —<\/p>\n ## Migration from CMI<\/p>\n “`bash # Start migration # Force migration (skip validation) # Force migration without backup **Features**: —<\/p>\n ## Performance<\/p>\n Syncmoney is optimized for high-throughput scenarios:<\/p>\n – **Redis connection pooling** (default: 30 connections) —<\/p>\n ## API for Developers<\/p>\n Syncmoney provides multiple integration points:<\/p>\n ### Vault API<\/p>\n “`java \/\/ Standard operations ### Event System<\/p>\n “`java ### REST API<\/p>\n Full REST API available when Web Admin is enabled. See [API Reference](docs\/API_REFERENCE.md).<\/p>\n “`bash # Economy stats For complete documentation, see: —<\/p>\n ## Troubleshooting<\/p>\n | Issue | Solution | Enable `debug: true` in config.yml for detailed logs.<\/p>\n —<\/p>\n ## Building from Source<\/p>\n “`bash # Build the plugin (Shadow JAR) # Build PlaceholderAPI expansion # Build web frontend —<\/p>\n ## Support<\/p>\n – **Discord**: Join —<\/p>\n ## License<\/p>\n [Apache License 2.0](LICENSE) \u2014 Free to use, modify, and distribute.<\/p>\n —<\/p>\n \n Built for high-scale Minecraft networks<\/sub><\/p>\n","protected":false},"excerpt":{"rendered":" Cross-server economy synchronization plugin for Minecraft<\/p>\n","protected":false},"featured_media":151461,"template":"","meta":{"_minecraft_slug":"syncmoney","_minecraft_project_id":"mKd80dJ7","_minecraft_author":"misty4119","_minecraft_license":"Apache-2.0","_minecraft_downloads":64,"_minecraft_follows":2,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"syncmoney.zip","_minecraft_size_bytes":159476803,"_minecraft_version_count":5,"_minecraft_updated_at":"2026-05-15T20:37:35.849879Z","_minecraft_date_created":"2026-03-04T22:19:12.347404Z","_minecraft_date_modified":"2026-04-03T11:00:28.969106Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/syncmoney","_minecraft_icon_attachment_id":151461,"_minecraft_imported_at":"2026-06-09T03:22:42+00:00","_minecraft_import_hash":"c68035f3459797e9d1fb12f062daf503","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[844,125,126,127,128],"mod_loader":[131,132,133],"minecraft_version":[94,41,38,167],"class_list":["post-151460","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-economy","mod_category-folia","mod_category-management","mod_category-paper","mod_category-purpur","mod_loader-folia","mod_loader-paper","mod_loader-purpur","minecraft_version-1-20-4","minecraft_version-1-21-11","minecraft_version-1-21-4","minecraft_version-26-1-1"],"yoast_head":"\n
\n|———|————-|————|
\n| `\/money` | View your balance | `syncmoney.money` |
\n| `\/money
\n| `\/pay
\n| `\/pay confirm` | Confirm large transfer | \u2014 |
\n| `\/baltop [page]` | View global leaderboard | `syncmoney.money` |
\n| `\/baltop me` | View your rank | `syncmoney.money` |<\/p>\n
\n|———|————-|————|
\n| `\/syncmoney admin give
\n| `\/syncmoney admin take
\n| `\/syncmoney admin set
\n| `\/syncmoney admin reset
\n| `\/syncmoney migrate cmi` | Migrate from CMI | `syncmoney.admin` |
\n| `\/syncmoney migrate local-to-sync` | Migrate from LOCAL to SYNC | `syncmoney.admin` |
\n| `\/syncmoney breaker status` | View protection status | `syncmoney.admin` |
\n| `\/syncmoney breaker unlock
\n| `\/syncmoney audit
\n| `\/syncmoney audit search` | Advanced search | `syncmoney.admin.audit` |
\n| `\/syncmoney econstats` | View economy statistics | `syncmoney.admin` |
\n| `\/syncmoney monitor` | View system monitoring | `syncmoney.admin` |
\n| `\/syncmoney shadow status` | View shadow sync status | `syncmoney.admin` |
\n| `\/syncmoney web status` | View web admin status | `syncmoney.admin` |
\n| `\/syncmoney reload` | Reload configuration | `syncmoney.admin` |
\n| `\/syncmoney test concurrent-pay` | Stress test | `syncmoney.admin.test` |<\/p>\n
\n|——|———–|—————–|—————–|
\n| Observe | `syncmoney.admin.observe` | 0 | 0 |
\n| Reward | `syncmoney.admin.reward` | 100,000 | 0 |
\n| General | `syncmoney.admin.general` | 1,000,000 | 1,000,000 |
\n| Full | `syncmoney.admin.full` | Unlimited | Unlimited |<\/p>\n
\n|————-|————-|
\n| `%syncmoney_balance%` | Player’s current balance |
\n| `%syncmoney_balance_formatted%` | Balance with smart formatting |
\n| `%syncmoney_balance_abbreviated%` | Balance abbreviated (1.5K, 2.3\u5104) |
\n| `%syncmoney_rank%` | Player’s leaderboard rank |
\n| `%syncmoney_my_rank%` | Player’s own rank |
\n| `%syncmoney_total_supply%` | Total money in circulation |
\n| `%syncmoney_total_players%` | Total players in leaderboard |
\n| `%syncmoney_online_players%` | Currently online players |
\n| `%syncmoney_version%` | Plugin version |
\n| `%syncmoney_top_
\n| `%syncmoney_balance_
\n# Preview migration data
\n\/syncmoney migrate cmi -preview<\/p>\n
\n\/syncmoney migrate cmi<\/p>\n
\n\/syncmoney migrate cmi -force<\/p>\n
\n\/syncmoney migrate cmi -force -no-backup
\n“`<\/p>\n
\n– PostgreSQL, MySQL, and SQLite support
\n– Multi-server data merge (LATEST\/SUM\/MAX strategies)
\n– Automatic backup before migration
\n– Checkpoint resume for large datasets
\n– Auto-disable CMI economy after migration<\/p>\n
\n– **Async write queues** \u2014 prevents main thread blocking (capacity: 50,000 events)
\n– **In-memory caching** \u2014 O(1) balance reads with ConcurrentHashMap
\n– **Batch database writes** \u2014 efficient audit log persistence (500 records\/batch)
\n– **Lock-free event driven** \u2014 single-writer pattern avoids contention
\n– **Redis Lua atomics** \u2014 7 scripts ensure consistency without locks
\n– **OverflowLog WAL** \u2014 prevents data loss when queues saturate<\/p>\n
\n\/\/ Get economy via Vault
\nEconomy economy = Bukkit.getServicesManager()
\n .getRegistration(Economy.class).getProvider();<\/p>\n
\neconomy.getBalance(player);
\neconomy.depositPlayer(player, amount);
\neconomy.withdrawPlayer(player, amount);
\n“`<\/p>\n
\n\/\/ Listen for completed transactions
\n@EventHandler
\npublic void onTransaction(PostTransactionEvent event) {
\n String player = event.getPlayerName();
\n BigDecimal amount = event.getAmount();
\n \/\/ type: DEPOSIT, WITHDRAW, TRANSFER, SET_BALANCE
\n}
\n“`<\/p>\n
\n# Health check (no auth)
\ncurl http:\/\/localhost:8080\/health<\/p>\n
\ncurl -H “Authorization: Bearer
\n“`<\/p>\n
\n– [API Reference](docs\/API_REFERENCE.md)
\n– [Developer Guide](docs\/DEVELOPER_GUIDE.md)
\n– [Changelog](docs\/CHANGELOG.md)<\/p>\n
\n|——-|———-|
\n| “Server name not configured” | Set `server-name` in config.yml |
\n| Redis connection failed | Verify host\/port\/password in config |
\n| Balances not syncing | Ensure all servers use same Redis instance |
\n| Performance issues | Increase `pool-size` and `queue-capacity` |
\n| Circuit breaker locked | Use `\/syncmoney breaker reset` to unlock |
\n| Player account locked | Use `\/syncmoney breaker unlock
\n| Web admin not loading | Check `web-admin.enabled: true` and port availability |<\/p>\n
\n# Clone the repository
\ngit clone https:\/\/github.com\/Misty4119\/Syncmoney.git
\ncd Syncmoney<\/p>\n
\n.\/gradlew shadowJar
\n# Output: build\/libs\/Syncmoney-1.1.0.jar<\/p>\n
\ncd syncmoney-papi-expansion && ..\/gradlew jar
\n# Output: build\/libs\/SyncmoneyExpansion-1.1.0.jar<\/p>\n
\ncd syncmoney-web && pnpm install && pnpm build
\n“`<\/p>\n
\n– **Issues**: GitHub<\/p>\n