VaultX 2.0 — Modern Vault Economy API

A fully backward-compatible, modern economy API for Minecraft servers.
Drop-in replacement for Vault 1.7.3-b131 with multi-currency, async/Folia support, web API, GUI framework, and unified storage.

---

✨ Features

🔄 100% Backward Compatible

• Identical Economy, EconomyResponse, and AbstractEconomy signatures to Vault 1.7.3-b131
• All old plugins work without recompilation
• Legacy bridge auto-registers net.milkbowl.vault.economy.Economy service

🚀 Modern VaultX 2.0 Additions

• UUID-based API (like Vault 2.5.0) — EconomyV2 interface
• Folia-safe async — depositPlayerAsync(), withdrawPlayerAsync()
• Multi-currency — CurrencyDefinition, getCurrencies(), setActiveCurrency()
• Atomic transfers — transferPlayer() in one call
• Transaction history — TransactionRecord, getTransactionHistory()
• Leaderboards — getTopBalances(int) + async variants
• GUI Framework — EconomyGUI, GUIManager ready for menus
• Web API Server — Built-in HTTP server (/health, /api/balance)
• Unified Storage — EconomyStorage interface (SQLite/MySQL/Redis ready)
• PlaceholderAPI — %vaultx_balance%, %vaultx_currency%
• i18n — Multi-language support via I18nManager

🖥️ Supported Platforms

Platform	Version
Paper	1.21.4+
Purpur	1.21.4+
Folia	1.21.4+
DivineMC	1.21.x
Leaf	1.21.x
Pufferfish	1.21.x

---

📦 Installation

For Server Admins

1. Download VaultX2.0.jar from Releases
2. Place in your server's plugins/ folder
3. Restart server
4. Install an economy provider plugin (EssentialsX, CMI, etc.)

For Developers (Maven)

<repositories>
    <repository>
        <id>papermc</id>
        <url>https://repo.papermc.io/repository/maven-public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>net.milkbowl.vaultx</groupId>
        <artifactId>vaultx-api</artifactId>
        <version>2.0.0</version>
    </dependency>
</dependencies>

---

🚀 Quick Start

Creating an Economy Provider

public class MyEconomy extends AbstractEconomyV2 {
    
    @Override
    public boolean isEnabled() { return true; }
    
    @Override
    public String getName() { return "MyEconomy"; }
    
    @Override
    public boolean hasAccount(String playerName) {
        // Check if account exists
        return true;
    }
    
    @Override
    public double getBalance(String playerName) {
        // Get balance from your storage
        return 1000.0;
    }
    
    @Override
    public boolean has(String playerName, double amount) {
        return getBalance(playerName) >= amount;
    }
    
    @Override
    public EconomyResponse withdrawPlayer(String playerName, double amount) {
        if (!hasAccount(playerName)) {
            return EconomyResponse.fail(amount, 0.0, "ACCOUNT_NOT_FOUND", "ACCOUNT_NOT_FOUND");
        }
        final double balance = getBalance(playerName);
        if (balance < amount) {
            return EconomyResponse.fail(amount, balance, "INSUFFICIENT_FUNDS", "INSUFFICIENT_FUNDS");
        }
        // Deduct from storage
        return EconomyResponse.success(amount, balance - amount);
    }
    
    @Override
    public EconomyResponse depositPlayer(String playerName, double amount) {
        if (!hasAccount(playerName)) {
            return EconomyResponse.fail(amount, 0.0, "ACCOUNT_NOT_FOUND", "ACCOUNT_NOT_FOUND");
        }
        // Add to storage
        return EconomyResponse.success(amount, getBalance(playerName) + amount);
    }
    
    @Override
    public boolean createPlayerAccount(String playerName) {
        // Create account in storage
        return true;
    }
}

Registering Your Provider

public class MyEconomyPlugin extends JavaPlugin {
    @Override
    public void onEnable() {
        VaultXBukkit.get().registerProvider(new MyEconomy());
    }
}

Using the API

// Get economy service
Economy economy = VaultX.getEconomy();
EconomyV2 economyV2 = VaultX.getEconomyV2();

// Legacy style (Vault 1.x compatible)
EconomyResponse response = economy.depositPlayer(player, 100.0);

// Modern style (UUID-based)
economyV2.depositPlayerAsync(player, 100.0)
    .thenAccept(resp -> player.sendMessage("New balance: " + resp.balance));

// Multi-currency
economyV2.setActiveCurrency("GOLD");
economyV2.setPlayerCurrency(player, "USD");

// Atomic transfer
EconomyResponse transfer = economyV2.transferPlayer(from, to, 50.0, "default", true);

// Leaderboard
List<LeaderboardEntry> top10 = economyV2.getTopBalances(10);

---

🏗️ Project Structure

VaultX/
├── vaultx-api/                    ← Pure API module
│   └── net/milkbowl/vaultx/
│       ├── VaultX.java            ← Static facade
│       ├── economy/
│       │   ├── Economy.java       ← Legacy interface (Vault 1.x compatible)
│       │   ├── EconomyV2.java     ← Modern interface (UUID, async, multi-currency)
│       │   ├── AbstractEconomy.java
│       │   ├── AbstractEconomyV2.java
│       │   ├── EconomyResponse.java
│       │   ├── CurrencyDefinition.java
│       │   ├── TransactionRecord.java
│       │   ├── LeaderboardEntry.java
│       │   ├── EconomyContext.java
│       │   ├── EconomyEvent.java
│       │   ├── BankAccount.java
│       │   ├── CurrencyConverter.java
│       │   └── EconomyService.java
│       ├── storage/
│       │   └── EconomyStorage.java
│       ├── web/
│       │   ├── EconomyWebAPI.java
│       │   └── WebAPIConfig.java
│       ├── i18n/
│       │   └── I18nManager.java
│       └── util/
│           ├── UUIDUtils.java
│           └── TranslationKey.java
├── vaultx-bukkit/                 ← Bukkit/Paper/Folia implementation
│   ├── plugin.yml
│   ├── config.yml
│   └── net/milkbowl/vaultx/bukkit/
│       ├── VaultXBukkit.java
│       ├── command/
│       │   └── VaultXCommand.java
│       ├── config/
│       │   └── VaultXConfig.java
│       ├── economy/
│       │   ├── VaultXEconomyService.java
│       │   └── ExampleVaultXEconomyProvider.java
│       ├── gui/
│       │   ├── EconomyGUI.java
│       │   └── GUIManager.java
│       ├── web/
│       │   └── WebAPIServer.java
│       ├── placeholder/
│       │   └── VaultXPlaceholder.java
│       └── scheduler/
│           └── VaultXScheduler.java
├── pom.xml                        ← Maven parent POM
├── VaultX2.0.jar                  ← Pre-built plugin
├── README.md                      ← This file (English)
├── README_zh.md                   ← Chinese description
└── LICENSE                        ← AGPL-3.0

---

🔧 Building

# Clone the repository
git clone https://github.com/yourusername/VaultX.git
cd VaultX

# Build
mvn clean package

# Output: vaultx-bukkit/target/vaultx-bukkit-2.0.0.jar

---

📚 API Documentation

Economy (Legacy - Vault 1.x compatible)

public interface Economy {
    boolean isEnabled();
    String getName();
    boolean hasBankSupport();
    int fractionalDigits();
    String format(double amount);
    String currencyNamePlural();
    String currencyNameSingular();
    
    // Account queries
    boolean hasAccount(String playerName);
    boolean hasAccount(OfflinePlayer player);
    boolean hasAccount(String playerName, String worldName);
    
    // Balance queries
    double getBalance(String playerName);
    double getBalance(OfflinePlayer player);
    double getBalance(String playerName, String worldName);
    
    // ... and more
}

EconomyV2 (Modern - UUID, Async, Multi-currency)

public interface EconomyV2 extends Economy {
    // UUID-based methods
    boolean hasAccount(UUID uuid);
    double getBalance(UUID uuid);
    EconomyResponse withdrawPlayer(UUID uuid, double amount);
    EconomyResponse depositPlayer(UUID uuid, double amount);
    
    // Async methods
    CompletableFuture<EconomyResponse> depositPlayerAsync(OfflinePlayer player, double amount);
    CompletableFuture<EconomyResponse> withdrawPlayerAsync(OfflinePlayer player, double amount);
    
    // Multi-currency
    Map<String, CurrencyDefinition> getCurrencies();
    String getActiveCurrency();
    boolean setActiveCurrency(String currencyCode);
    
    // Transfers
    EconomyResponse transferPlayer(OfflinePlayer from, OfflinePlayer to, 
                                    double amount, String worldName, boolean autoCreate);
    
    // History & Leaderboards
    List<TransactionRecord> getTransactionHistory(OfflinePlayer player, int limit);
    List<LeaderboardEntry> getTopBalances(int limit);
}

---

🎨 GUI Framework

// Open balance menu
GUIManager.openBalanceMenu(player);

// Create custom GUI
EconomyGUI gui = new EconomyGUI(player);
gui.open();

---

🌐 Web API

// Start web server
WebAPIServer server = new WebAPIServer(8080);
server.start();

// Endpoints:
// GET /health - Health check
// GET /api/balance?uuid=xxx&currency=USD - Player balance
// GET /api/leaderboard?currency=USD&limit=10 - Top balances
// POST /api/transfer - Transfer funds

---

🌍 Internationalization

VaultX supports multiple languages out of the box:

// Get translated string
String message = I18nManager.get(TranslationKey.ECONOMY_BALANCE);

// Use custom locale
String message = I18nManager.get(Locale.CHINESE, TranslationKey.ECONOMY_BALANCE);

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

This means:

• ✅ You can use, modify, and distribute this software
• ✅ You must keep the same license for derivatives
• ✅ You must disclose the source code when serving the modified version over a network
• ✅ You must state changes made to the code

See LICENSE for full details.

---

🙏 Credits

• Original Vault by cereal, Sleaker, mung3r
• VaultX Contributors
• Inspired by Vault 2.5.0 community fork

---

📞 Support

• GitHub Issues - Bug reports and feature requests
• GitHub Discussions - Questions and community chat

---

🗺️ Roadmap

• Core Economy API (Vault 1.x compatible)
• UUID-based EconomyV2 interface
• Folia-safe async operations
• Multi-currency support
• GUI Framework
• Web API Server
• PlaceholderAPI integration
• i18n support
• SQLite/MySQL unified storage implementation
• Complete Web Dashboard (HTML/JS)
• ChestShop / QuickShop compatibility layer
• Player Market system
• More language packs (zh_CN, ja_JP, ko_KR)

---

VaultX 2.0 — Built for the modern Minecraft economy ecosystem.