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

Technologies

Library	Used for
web3j	EVM transaction signing, contract interaction
BouncyCastle	X25519, Ed25519, HKDF, ChaCha20-Poly1305, Keccak-256
ZXing	QR code generation
OkHttp	HTTP + WebSocket for relay, Stripe, Razorpay, CoinGecko
OpenZeppelin	EIP712, ECDSA, MerkleProof, Nonces
Vault API	Economy provider interface
SQLite (xerial)	Balances, sessions, deposits, transactions
Silkscreen	Landing page pixel font

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

License

MIT