Economy plugin for Minecraft servers.
Integrates crypto wallets, card, and UPI payment processing with the Vault API.

Website  •  Configuration  •  Features  •  Contract

About

MineFi is a server-side economy plugin that gives server operators a way to integrate external payment processing into their Vault-based economy. It connects player wallets via WalletConnect v2, processes payments through Stripe and Razorpay, and registers as a Vault economy provider so existing shop plugins work without modification.

Balances are managed server-side in USD. The crypto path uses an on-chain escrow contract (MineFiVault.sol) with EIP-712 signed withdrawals and periodic Merkle root publishing, allowing players to verify their balances independently and recover funds directly from the contract if needed.

Features

WalletConnect v2

Crypto deposits

Stripe + Razorpay

Crypto withdrawals

Transaction history

Emergency withdrawal — Merkle proof on-chain recovery

Vault API — works with any Vault-compatible plugin

Architecture

graph TB
    Player([Player]) --> BookGUI[Book GUI]
    BookGUI --> Providers

    subgraph Providers
        Crypto[CryptoProvider]
        Stripe[StripeProvider]
        Razorpay[RazorpayProvider]
    end

    Crypto --> WC[WalletConnect v2 Relay]
    Crypto --> Chain[ChainService / web3j]
    Chain --> Contract[MineFiVault.sol]
    Stripe --> StripeAPI[Stripe API]
    Razorpay --> RzpAPI[Razorpay API]

    Providers --> DB[(SQLite)]
    Providers --> Vault[Vault Economy]
    Vault --> Shops[Shop Plugins]

    MerklePublisher[Merkle Publisher] --> DB
    MerklePublisher --> Contract
    PriceService[PriceService] --> CoinGecko[CoinGecko API]

Loading

WalletConnect pairing sequence

sequenceDiagram
    participant P as Player
    participant S as Server
    participant R as WC Relay
    participant W as Wallet App

    P->>S: /wallet connect
    S->>S: Generate X25519 keypair + symKey
    S->>R: Publish session proposal (tag 1100)
    S->>P: QR map with wc: URI
    P->>W: Scan QR
    W->>R: Session approval + responder pubkey
    R->>S: Approval response
    S->>S: X25519 key agreement, derive session key
    R->>S: Session settle (accounts, chains)
    S->>R: Settle acknowledgment (tag 1103)
    S->>P: Wallet connected!

Loading

Deposit and withdrawal flow

sequenceDiagram
    participant P as Player
    participant S as Server
    participant W as Wallet
    participant C as MineFiVault

    Note over P,C: Deposit
    P->>S: /wallet approve 1.0
    S->>W: eth_sendTransaction (deposit)
    W->>C: deposit(player) + 1 ETH
    C-->>S: Deposited event
    S->>S: Credit balance (FIFO ledger)

    Note over P,C: Spend
    P->>S: Buy item at shop
    S->>S: Vault.withdraw(), FIFO deduct

    Note over P,C: Withdraw
    P->>S: /wallet withdraw
    S->>W: eth_signTypedData_v4 (EIP-712)
    W-->>S: Signature
    S->>C: withdraw(player, amount, sig)
    C->>C: Verify sig, deduct gas
    C->>W: Payout (amount - gas)
    C->>S: Gas reimbursement

Loading

Commands

/wallet                             open the book
/wallet connect                     QR to link a wallet
/wallet approve <amount>            deposit ETH
/wallet withdraw <chain> <amount>   withdraw crypto
/wallet verify                      check balance against Merkle root
/wallet history                     recent transactions

Full reference in docs/CONFIGURATION.md.

Requirements

• Spigot or Paper 1.20+
• Java 17+
• Vault (for economy integration)
• WalletConnect Cloud project ID (for crypto)
• Stripe and/or Razorpay keys (for cards/UPI)

Building

./gradlew shadowJar
cp build/libs/MineFi-0.1.0.jar /path/to/server/plugins/

Restart once to write plugins/MineFi/config.yml, fill in your keys, restart again.

Project Structure

MineFi/
├── contracts/
├── docs/
│   └── media/
├── site/
├── src/
│   ├── main/kotlin/com/minefi/
│   │   ├── chain/
│   │   ├── commands/
│   │   ├── gui/
│   │   ├── listeners/
│   │   ├── map/
│   │   ├── merkle/
│   │   ├── price/
│   │   ├── provider/
│   │   ├── relay/
│   │   ├── storage/
│   │   └── vault/
│   └── test/
├── build.gradle.kts
└── settings.gradle.kts

Directory	What it does
contracts/	Solidity escrow contract, deployable to any EVM chain
site/	Landing page and payment redirect pages (Cloudflare Pages)
relay/	WalletConnect v2: WebSocket, session management, X25519 + ChaCha20-Poly1305 encryption
merkle/	Keccak-256 Merkle tree for on-chain balance proofs
provider/	Payment providers (crypto, Stripe, Razorpay) behind a common interface
map/	QR code and receipt rendering on Minecraft maps
gui/	Book-based in-game menu with clickable buttons
vault/	Vault economy bridge
chain/	web3j RPC, transaction signing, contract calls

Documentation

Features	What it does, for server owners
Configuration	config.yml reference and every command
Redirect pages	Hosting Stripe/Razorpay success pages
Providers	Writing a new payment provider
Contract	MineFiVault.sol reference
Architecture	How the pieces fit

Known Issues

Issue	Details
Per-transaction signing blocks main thread	I would've preferred every in game transaction to be signed but Vault API blocks the main thread when waiting for balance to be approved since Vault works primarily synchronously, would be happy to know about the solution.
No live provider testing	Stripe live keys need a verified business; Razorpay needs a registered Indian business with KYC. Current testing is limited to Stripe test mode, Razorpay test mode, and local Hardhat. Looking for testers with live merchant accounts.
Merkle gas on mainnet	Hourly publishing is prohibitive on Ethereum mainnet. Tested on Hardhat; Base / Arbitrum deployment planned but uncosted in real-world volume.
Single hot wallet	The contract trusts one relayer address. No multi-sig or role rotation. If the key leaks, players must use emergency withdrawal.
ETH only	Native chain token only. USDC/USDT support requires a new contract.

Bug reports and PRs welcome — open an issue.

License

MIT