📖 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: 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_WALLET_PASSWORD: Optional password to encrypt wallet files

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

# 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

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