🔐

# Monero (XMR) Integration

Complete guide for integrating Monero with wallet RPC into your Bicrypto Ecosystem

## 📖 Overview

This guide covers the Monero (XMR) integration in Bicrypto Ecosystem. Monero is a privacy-focused cryptocurrency that uses ring signatures, stealth addresses, and RingCT for anonymous transactions. The integration uses the wallet RPC service to manage wallets, monitor deposits, and handle withdrawals.

Key Features

- • Privacy-focused blockchain with untraceable transactions
- • Wallet RPC integration for managing multiple wallets
- • Automatic deposit monitoring with confirmations
- • Queue-based withdrawal processing
- • Redis caching for transaction processing

## ⚙️ System Requirements

### Minimum Requirements

- • OS: Ubuntu 20.04 LTS or higher
- • CPU: 2+ cores (x86-64)
- • RAM: 4GB minimum
- • Storage: 150GB+ SSD (blockchain size)
- • Network: Stable internet connection
- • Ports: 18081 (Daemon RPC), 18083 (Wallet RPC)

### Recommended Requirements

- • OS: Ubuntu 22.04 LTS
- • CPU: 4+ cores (x86-64)
- • RAM: 8GB or more
- • Storage: 200GB+ NVMe SSD
- • Network: High-speed broadband
- • Firewall: Configure for RPC access

## 1️⃣ Install Monero Daemon and Wallet RPC

### Using Official Binaries (Recommended)

    # Update system packages
    sudo apt update && sudo apt upgrade -y

    # Install required dependencies
    sudo apt install -y wget bzip2

    # Create directory for Monero
    mkdir -p ~/monero && cd ~/monero

    # Download latest Monero release
    MONERO_VERSION="0.18.3.1"
    wget https://downloads.getmonero.org/cli/monero-linux-x64-v$MONERO_VERSION.tar.bz2

    # Extract the archive
    tar -xvf monero-linux-x64-v$MONERO_VERSION.tar.bz2

    # Move to system directory
    sudo mv monero-x86_64-linux-gnu-v$MONERO_VERSION /opt/monero

    # Create symbolic links for easy access
    sudo ln -sf /opt/monero/monerod /usr/local/bin/monerod
    sudo ln -sf /opt/monero/monero-wallet-rpc /usr/local/bin/monero-wallet-rpc
    sudo ln -sf /opt/monero/monero-wallet-cli /usr/local/bin/monero-wallet-cli

    # Verify installation
    monerod --version
    monero-wallet-rpc --version

Version Note

Always check getmonero.org for the latest stable version.

## 2️⃣ Configure Monero Daemon

### Create Configuration File

    # Create Monero data directory
    mkdir -p ~/.bitmonero

    # Create configuration file
    cat > ~/.bitmonero/bitmonero.conf << EOF
    # Monero Daemon Configuration

    # Network settings
    data-dir=/home/$USER/.bitmonero
    log-file=/home/$USER/.bitmonero/monero.log
    log-level=0

    # P2P network settings
    p2p-bind-ip=0.0.0.0
    p2p-bind-port=18080

    # RPC settings for daemon
    rpc-bind-ip=127.0.0.1
    rpc-bind-port=18081
    restricted-rpc=false
    confirm-external-bind=true

    # RPC authentication (CHANGE THESE!)
    rpc-login=monero_rpc:your_secure_password_here

    # Performance settings
    db-sync-mode=safe
    max-concurrency=4
    block-sync-size=10

    # Security settings
    no-igd=true

    # Use mainnet (default)
    # For testnet, uncomment: testnet=true
    # For stagenet, uncomment: stagenet=true
    EOF

    # Set proper permissions
    chmod 600 ~/.bitmonero/bitmonero.conf

Important configuration options:

- • `rpc-login`: Set secure username and password for RPC access
- • `rpc-bind-ip`: Use 127.0.0.1 for local access only
- • `db-sync-mode`: Use "safe" for data integrity
- • `restricted-rpc`: Set to false for wallet operations

## 3️⃣ Create Systemd Services

### Monero Daemon Service

    # Create systemd service file for daemon
    sudo tee /etc/systemd/system/monerod.service > /dev/null << EOF
    [Unit]
    Description=Monero Daemon
    After=network.target

    [Service]
    Type=simple
    User=$USER
    Group=$USER
    ExecStart=/usr/local/bin/monerod --config-file=/home/$USER/.bitmonero/bitmonero.conf --non-interactive
    Restart=always
    RestartSec=30

    [Install]
    WantedBy=multi-user.target
    EOF

    # Enable and start daemon
    sudo systemctl daemon-reload
    sudo systemctl enable monerod.service
    sudo systemctl start monerod.service

    # Check daemon status
    sudo systemctl status monerod.service

### Wallet RPC Service

    # Create wallet directory
    mkdir -p ~/monero-wallets

    # Create wallet RPC service file
    sudo tee /etc/systemd/system/monero-wallet-rpc.service > /dev/null << EOF
    [Unit]
    Description=Monero Wallet RPC
    After=network.target monerod.service
    Requires=monerod.service

    [Service]
    Type=simple
    User=$USER
    Group=$USER
    ExecStart=/usr/local/bin/monero-wallet-rpc \
        --rpc-bind-ip 127.0.0.1 \
        --rpc-bind-port 18083 \
        --daemon-address 127.0.0.1:18081 \
        --rpc-login wallet_rpc:your_wallet_rpc_password \
        --wallet-dir /home/$USER/monero-wallets \
        --log-level 2 \
        --confirm-external-bind \
        --trusted-daemon

    Restart=always
    RestartSec=30

    [Install]
    WantedBy=multi-user.target
    EOF

    # Enable and start wallet RPC
    sudo systemctl daemon-reload
    sudo systemctl enable monero-wallet-rpc.service
    sudo systemctl start monero-wallet-rpc.service

    # Check wallet RPC status
    sudo systemctl status monero-wallet-rpc.service

Initial Sync Time

The initial blockchain sync can take 24-48 hours. Monitor progress with: `sudo journalctl -u monerod.service -f`

## 4️⃣ Configure Bicrypto Environment Variables

### Add to .env File

    # Monero RPC Configuration
    XMR_RPC_USER="wallet_rpc"
    XMR_RPC_PASSWORD="your_wallet_rpc_password"

    # Optional: Custom RPC URLs (if using non-standard ports)
    # These override the default ports if set
    XMR_DAEMON_RPC_URL=""  # Example: "http://127.0.0.1:18081/json_rpc"
    XMR_WALLET_RPC_URL=""  # Example: "http://127.0.0.1:28083/json_rpc"

    # Optional: Wallet password if you want to encrypt wallets
    # XMR_WALLET_PASSWORD="your_wallet_encryption_password"

Environment variable descriptions:

- • `XMR_RPC_USER`: Username for wallet RPC authentication
- • `XMR_RPC_PASSWORD`: Password for wallet RPC authentication
- • `XMR_DAEMON_RPC_URL`: Full URL for daemon RPC (optional, uses default port 18081 if not set)
- • `XMR_WALLET_RPC_URL`: Full URL for wallet RPC (optional, uses default port 18083 if not set)
- • `XMR_WALLET_PASSWORD`: Optional password to encrypt wallet files

Custom Port Configuration

If your Monero RPC services are running on non-standard ports (e.g., wallet RPC on port 28083 instead of 18083), use the `XMR_DAEMON_RPC_URL` and `XMR_WALLET_RPC_URL` variables to specify the full URLs including the custom ports.

## 5️⃣ How Monero Works in Bicrypto Ecosystem

### Integration Architecture

#### 🔄 Wallet Management

- • Each user gets a unique Monero wallet file created via RPC
- • Wallets are stored in `~/monero-wallets/` directory
- • Wallet names use the user's wallet ID for identification
- • Master wallet is created as "master_wallet" for ecosystem operations

#### 📥 Deposit Monitoring

- • MoneroService monitors incoming transactions for each wallet
- • Requires minimum 6 confirmations before crediting
- • Uses queue system to prevent concurrent wallet access
- • Transactions are cached in Redis to prevent duplicate processing

#### 📤 Withdrawal Processing

- • Withdrawals are queued and processed sequentially per wallet
- • Checks for sufficient unlocked balance before sending
- • Automatically handles locked funds by requeuing transactions
- • Updates transaction status in database upon completion

#### 🔧 Service Features

- • Automatic chain synchronization checking
- • Queue-based operations to prevent race conditions
- • Retry mechanism with maximum 60 attempts
- • Transaction processing expiry after 30 minutes
- • Fee estimation based on network conditions

## 6️⃣ Testing RPC Connections

### Test Daemon RPC

    # Check daemon sync status (default port)
    curl -X POST http://127.0.0.1:18081/json_rpc \
        -d '{"jsonrpc":"2.0","id":"0","method":"get_info"}' \
        -H 'Content-Type: application/json' \
        -u monero_rpc:your_secure_password_here

    # Get current block height
    curl -X POST http://127.0.0.1:18081/json_rpc \
        -d '{"jsonrpc":"2.0","id":"0","method":"get_block_count"}' \
        -H 'Content-Type: application/json' \
        -u monero_rpc:your_secure_password_here

### Test Wallet RPC

    # Create a test wallet (default port 18083)
    curl -X POST http://127.0.0.1:18083/json_rpc \
        -d '{"jsonrpc":"2.0","id":"0","method":"create_wallet","params":{"filename":"test_wallet","password":"","language":"English"}}' \
        -H 'Content-Type: application/json' \
        -u wallet_rpc:your_wallet_rpc_password

    # If using custom port (e.g., 28083)
    curl -X POST http://127.0.0.1:28083/json_rpc \
        -d '{"jsonrpc":"2.0","id":"0","method":"create_wallet","params":{"filename":"test_wallet","password":"","language":"English"}}' \
        -H 'Content-Type: application/json' \
        -u wallet_rpc:your_wallet_rpc_password

    # Open the wallet
    curl -X POST http://127.0.0.1:18083/json_rpc \
        -d '{"jsonrpc":"2.0","id":"0","method":"open_wallet","params":{"filename":"test_wallet","password":""}}' \
        -H 'Content-Type: application/json' \
        -u wallet_rpc:your_wallet_rpc_password

    # Get wallet address
    curl -X POST http://127.0.0.1:18083/json_rpc \
        -d '{"jsonrpc":"2.0","id":"0","method":"get_address","params":{"account_index":0}}' \
        -H 'Content-Type: application/json' \
        -u wallet_rpc:your_wallet_rpc_password

Port Mismatch Issues

If you get "fetch failed" errors when the system tries to connect to the wallet RPC, ensure your `XMR_WALLET_RPC_URL` environment variable matches your actual wallet RPC port. The system will log the configured URLs on startup for verification.

## 7️⃣ Configure in Bicrypto Admin Panel

### Add Monero to Ecosystem

1. 1. Navigate to Master Wallets:

   Go to `Admin → Extensions → Ecosystem → Master Wallet`

   - • Click "Create Master Wallet"
   - • Select Chain: XMR
   - • Currency will auto-populate as XMR
   - • The system will create a master wallet automatically
2. 2. Configure XMR Token:

   Go to `Admin → Extensions → Ecosystem → Tokens`

   - • Create new token for XMR if not exists
   - • Set decimals to 12 (Monero uses 12 decimal places)
   - • Configure withdrawal fees and limits
   - • Enable the token for trading
3. 3. Create XMR Markets:

   Go to `Admin → Extensions → Ecosystem → Markets`

   - • Create trading pairs like XMR/USDT
   - • Set appropriate fees and limits
   - • Enable the markets for trading

## 8️⃣ Monitoring and Maintenance

### Monitoring Commands

    # Monitor daemon logs
    sudo journalctl -u monerod.service -f

    # Monitor wallet RPC logs
    sudo journalctl -u monero-wallet-rpc.service -f

    # Check blockchain sync progress
    monerod status

    # Check disk usage
    df -h ~/.bitmonero

    # Monitor system resources
    htop

    # Check service status
    systemctl status monerod
    systemctl status monero-wallet-rpc

    # Restart services if needed
    sudo systemctl restart monerod
    sudo systemctl restart monero-wallet-rpc

### Backup Procedures

    # Backup wallet files
    cp -r ~/monero-wallets ~/monero-wallets-backup-$(date +%Y%m%d)

    # Create automated backup script
    cat > ~/backup-monero.sh << 'EOF'
    #!/bin/bash
    BACKUP_DIR="/backup/monero/$(date +%Y%m%d-%H%M%S)"
    mkdir -p $BACKUP_DIR
    cp -r ~/monero-wallets $BACKUP_DIR/
    cp ~/.bitmonero/bitmonero.conf $BACKUP_DIR/
    echo "Backup completed to $BACKUP_DIR"
    EOF

    chmod +x ~/backup-monero.sh

    # Add to crontab for daily backups
    (crontab -l 2>/dev/null; echo "0 2 * * * /home/$USER/backup-monero.sh") | crontab -

Critical: Wallet Backups

Always backup wallet files before system maintenance. Each wallet file contains the private keys for that specific wallet. Lost wallet files cannot be recovered without backups!

## 🔧 Troubleshooting

### Common Issues

Chain not synchronized:

- • Check if daemon is running: `systemctl status monerod`
- • Wait for full sync (can take 24-48 hours initially)
- • Check sync status: `monerod status`
- • Ensure sufficient disk space (150GB+)

Wallet RPC connection refused:

- • Ensure wallet RPC is running: `systemctl status monero-wallet-rpc`
- • Check RPC credentials in .env file
- • Verify wallet-dir path exists and has correct permissions
- • Check firewall settings if accessing remotely

Failed to open wallet:

- • Check if wallet file exists in wallet directory
- • Verify wallet password is correct
- • Ensure only one process is accessing the wallet
- • Check wallet RPC logs for detailed errors

High memory usage:

- • Reduce `max-concurrency` in daemon config
- • Use `db-sync-mode=safe:sync` instead of fast
- • Add swap space if RAM is limited
- • Consider pruning blockchain with `--prune-blockchain`

## 🔒 Security Best Practices

- ✓ Use strong RPC passwords: Generate unique passwords for daemon and wallet RPC access
- ✓ Restrict RPC access: Bind to localhost (127.0.0.1) unless remote access is required
- ✓ Regular backups: Backup wallet files daily to secure locations
- ✓ Monitor logs: Regularly check daemon and wallet logs for suspicious activity
- ✓ Keep updated: Regularly update Monero software to latest stable version
- ✓ Firewall configuration: Only open required ports and restrict access by IP if possible
- ✓ Wallet encryption: Consider using wallet passwords for additional security

## 📚 Additional Resources

### Official Documentation

- • Monero Developer Guides
- • Wallet RPC Documentation
- • Daemon RPC Documentation

### Implementation Files

- • `backend/src/blockchains/xmr.ts` - Monero service implementation
- • `backend/src/api/(ext)/ecosystem/utils/wallet.ts` - Wallet integration
- • `backend/src/api/(ext)/ecosystem/utils/withdrawalQueue.ts` - Withdrawal handling

### Setup Complete!

You've successfully set up Monero integration for your Bicrypto Ecosystem. The system now supports:

- ✓ Private cryptocurrency transactions with full anonymity
- ✓ Automatic wallet creation for users
- ✓ Deposit monitoring with confirmation tracking
- ✓ Queue-based withdrawal processing
- ✓ Integration with Bicrypto's ecosystem trading

Remember to monitor system resources, maintain regular backups, and keep the Monero software updated for optimal security and performance.