OmniTipper - Discord Cryptocurrency Tipping Bot

A Discord bot for tipping cryptocurrencies on the Base chain. Supports unlimited tokens with off-chain transfers for tips and on-chain withdrawals.

!System Architecture

Features

💰 Multi-currency support: Add unlimited tokens by contract address
🔄 Off-chain tips: Fast, free internal transfers
💸 On-chain withdrawals: Withdraw to any Base chain address
📊 Balance tracking: View balances for all supported tokens
💵 USD conversion: Tip using USD amounts (automatically converted)
🔐 Admin controls: Add coins, view bot and user balances
📝 Transaction history: Full audit trail of all deposits, withdrawals, and tips
💰 Fee system: 0.1% fee on deposits and withdrawals (transparently tracked)
📈 Monitoring: Prometheus metrics, Grafana dashboards, and Loki log aggregation

Prerequisites

Bun runtime (v1.2.17+)
MongoDB instance (local or remote)
Discord Bot Token
Base chain wallet with private key
Node.js 18+ (if not using Bun)

Discord Bot Setup

Important: To enable DM support, you must configure the following in the Discord Developer Portal:

Go to your bot application → Bot section
Enable Privileged Gateway Intents:

✅ MESSAGE CONTENT INTENT (Required for reading message content in DMs)
✅ SERVER MEMBERS INTENT (Required for role-based tipping to see all role members)

Save changes and restart your bot

Note: The bot code includes Partials configuration (Channel, Message, Reaction, User) which is required for Discord.js v14+ to receive DM messages. Without these partials, the bot will not receive DM events even if intents are enabled. Note: Without SERVER MEMBERS INTENT, role-based tipping will only include cached members (recently active members). With the intent enabled, all role members will be included. Note: The bot can receive DMs from users even if they're not in a shared server, but some Discord features may require the bot to be in at least one server with the user.

Setup

Install dependencies:

bun install

Configure environment variables:

Create a .env file in the root directory:

# Discord Bot Configuration
   DISCORDBOTTOKEN=yourdiscordbottokenhere
   # MongoDB Configuration
   # For Docker Compose (with authentication):
   MONGODBURL=mongodb://admin:yourmongo_password@mongodb:27017/omnitipper?authSource=admin
   MONGODBDBNAME=omnitipper
   MONGOROOTUSERNAME=admin
   MONGOROOTPASSWORD=yourstrongpasswordheremin32chars
   # For local MongoDB (without Docker):
   # MONGODB_URL=mongodb://localhost:27017
   # MONGODBDBNAME=omnitipper
   # Base Chain Configuration
   BASERPCURL=https://mainnet.base.org
   WALLETPRIVATEKEY=yourwalletprivatekeyhere
   # Price API Configuration
   COINMARKETCAPAPIKEY=yourcoinmarketcapapikeyhere
   # Encryption Configuration (must be at least 32 characters)
   ENCRYPTIONKEY=yourencryptionkeyheremin32_chars
   # Admin Configuration (comma-separated Discord user IDs)
   ADMINUSERIDS=yourdiscorduseridhere
   # Logging Configuration (optional)
   LOG_LEVEL=INFO              # Log level: ERROR, WARN, or INFO (default: INFO)
   LOG_FORMAT=json             # Log format: text or json (default: text, use json for Loki)
   LOGTOFILE=false           # Enable file logging (default: false)
   # Rate Limiting Configuration (optional - adjust if hitting RPC rate limits)
   MINRPCINTERVAL_MS=100          # Minimum ms between RPC batch calls (default: 100ms = 10 RPS)
   BALANCECHECKDELAY_MS=500       # Delay between individual balance checks in updateBotBalances (default: 500ms)
   BATCHBALANCECHECKDELAYMS=1000 # Delay between batches in batchCheckBalances (default: 1000ms)
   CONTRACTBALANCECHECKDELAYMS=500 # Delay between different contract addresses (default: 500ms)
   DEPOSITCHECKINTERVAL_MS=60000  # Interval between deposit checks (default: 60000ms = 1 minute)
   LOG_DIR=./logs
   # Minimum Threshold Configuration (optional)
   MINDEPOSITTHRESHOLD_USD=1.0    # Minimum deposit/withdrawal amount in USD (default: 1.0)
   MINDEPOSITTHRESHOLD_TOKENS=100 # Fallback minimum in tokens if USD conversion fails (default: 100)
   # Metrics Configuration (optional)
   METRICS_PORT=9090

Start MongoDB:

# If using local MongoDB
   mongod

Run the bot:

bun run start

Or for development with auto-reload:

bun run dev

Docker Setup

Using Docker Compose (Recommended)

The easiest way to run the bot with MongoDB and monitoring stack is using Docker Compose:

Create a .env file with your configuration (see Setup section above)

Build and run:

docker-compose up -d

View logs:

docker-compose logs -f bot

Access monitoring:

Grafana: (default: admin/admin)
Prometheus:
Loki:

Stop the services:

docker-compose down

Stop and remove volumes (clears database):

docker-compose down -v

Note: The Docker Compose setup includes:

Bot service (OmniTipper)
MongoDB database
Prometheus (metrics collection)
Grafana (visualization)
Loki (log aggregation)
Promtail (log shipping)

Using Docker Only

If you already have MongoDB running elsewhere:

Build the image:

docker build -t omnitipper .

Run the container:

docker run -d \
     --name omnitipper-bot \
     --restart unless-stopped \
     --env-file .env \
     omnitipper

View logs:

docker logs -f omnitipper-bot

Stop the container:

docker stop omnitipper-bot
   docker rm omnitipper-bot

Note: When using Docker Compose, the MongoDB URL in your .env should be mongodb://mongodb:27017 (the service name), or you can omit MONGODB_URL and it will use the default from docker-compose.yml.

Commands

User Commands

!help - Show comprehensive help menu with all commands and examples
!balances - Show all your token balances
!tip @user - Tip a user
Amount can be in USD (e.g., $10) or token amount (e.g., 1.5)
Example: !tip USDC $10 @username or !tip USDC 10 @username
!withdraw
[amount] - Withdraw tokens to an address
If amount is not specified, withdraws all balance
0.1% fee applies (shown in confirmation message)
Example: !withdraw USDC 0x1234...abcd or !withdraw USDC 0x1234...abcd 10
!deposit - Get or create your deposit address (works for all tokens)

Admin Commands

!admin addcoin - Add a new ERC20 token (symbol, name, and decimals are automatically fetched from the contract)
Example: !admin addcoin 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
!admin addeth - Add native ETH token to the system
!admin botbalances - View bot's on-chain balances for all tokens
!admin userbalances @user - View a user's balances
!admin accounting - Compare bot's on-chain balance vs sum of all user balances (accounting check)

Transaction History

All deposits, withdrawals, and tips are automatically recorded in the transaction history:

Deposits: Tracked with transaction hash, deposit address, amount, and fee
Withdrawals: Tracked with transaction hash, withdrawal address, amount, and fee
Tips: Tracked with sender/recipient information (both tipsent and tipreceived records)
Fee Tracking: All fees (0.1%) are recorded for accounting purposes

Backups

Quick Backup

Create a manual backup:

./scripts/backup-mongodb.sh

Backups are stored in the backups/ directory as compressed tar.gz files.

Backup Encryption (Recommended)

Enable encryption for backups:

export ENCRYPT_BACKUPS=true
export BACKUPENCRYPTIONKEY=yourstrongencryptionkeyheremin32_chars
./scripts/backup-mongodb.sh

Encrypted backups use AES-256-CBC encryption and have a .enc extension.

Automated Backups

Set up daily automated backups:

./scripts/setup-backup-cron.sh

This creates a cron job that runs backups daily at 2:00 AM and automatically cleans up backups older than 30 days.

Restore from Backup

# Unencrypted backup
./scripts/restore-mongodb.sh mongodbbackup20240101_120000.tar.gz
Encrypted backup
BACKUPENCRYPTIONKEY=yourkey ./scripts/restore-mongodb.sh mongodbbackup20240101120000.tar.gz.enc

⚠️ Warning: Restore will replace all existing data in the database! For detailed backup documentation, see scripts/BACKUPREADME.md. Transaction history is stored in MongoDB and can be queried programmatically for accounting, auditing, and analytics.
Architecture

Database: MongoDB for user balances, coin configurations, deposit addresses, and transaction history

Web3: ethers.js for Base chain interactions

Off-chain transfers: Tips are handled internally in the database (no gas fees)

On-chain operations: Withdrawals and deposits interact with the Base chain

Transaction History: Full audit trail of all financial operations stored in MongoDB

Monitoring: Prometheus for metrics, Grafana for visualization, Loki for log aggregation

Fees: 0.1% fee on deposits and withdrawals, transparently tracked and displayed

Important Notes
⚠️ Security:
Never share your .env file or commit it to version control

Keep your wallet private key secure

The bot wallet should only hold funds needed for withdrawals

Private keys are encrypted in the database using AES-256-GCM

Use a strong, random ENCRYPTION_KEY (at least 32 characters)

Store the encryption key securely and never lose it (you cannot decrypt without it)
⚠️ Deposit Addresses:
Each user gets one deposit address that works for all tokens (ERC20s and native ETH)

The same address can receive any supported token

ERC20 tokens: Automatically transferred to bot wallet and credited to your account

Native ETH: Credited to your account but stays on the deposit address for gas fees

Native ETH is needed on the deposit address to pay for gas when transferring ERC20 tokens

Users receive automatic DM notifications when deposits are confirmed

0.1% fee is deducted from all deposits (transparently shown in notifications)
⚠️ Fees:
0.1% fee applies to all deposits and withdrawals

Fees are transparently displayed in transaction notifications

Fee amount is tracked in transaction history for accounting

Fees stay in bot balance (not sent anywhere)
⚠️ Minimum Thresholds:
Minimum deposit/withdrawal: $1 USD (or 100 tokens if USD conversion unavailable)

Deposits and withdrawals below the minimum threshold will be rejected

Configure via MINDEPOSITTHRESHOLDUSD and MINDEPOSITTHRESHOLDTOKENS environment variables

Users will be notified if their deposit/withdrawal is below the threshold
⚠️ Price API:
Uses CoinMarketCap API (requires API key)

Get your API key from

Prices are cached for 1 minute to reduce API calls
⚠️ Logging & Monitoring:
Three log levels: ERROR, WARN, INFO

Configure via LOG_LEVEL environment variable (default: INFO)

Two log formats: text (default) or json (Loki-compatible)

Set LOG_FORMAT=json for structured JSON logs compatible with Loki

Optional file logging via LOGTOFILE=true

Logs are written to ./logs/ directory (separate files for errors)

Log files are automatically created with date stamps

Prometheus metrics exposed on port 9090 (configurable via METRICS_PORT)

Grafana and Loki available via Docker Compose for full observability stack

Promtail configured to automatically scrape and parse logs (supports both text and JSON formats)

Transaction history tracked for all deposits, withdrawals, and tips

Project Structure

src/ ├── bot.ts # Main bot entry point ├── commands/ # Command handlers │ ├── balances.ts │ ├── tip.ts │ ├── withdraw.ts │ ├── deposit.ts │ └── admin.ts ├── database/ # MongoDB models and connection │ ├── connection.ts │ └── models.ts ├── services/ # External services │ ├── web3.ts # Base chain interactions │ └── price.ts # Price conversion └── types/ # TypeScript types └── index.ts

License
Private project - All rights reserved