📖 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. 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. 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. 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

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.

Monero (XMR) Integration