OmniTipper Documentation

OmniTipper - Architectural Overview

Table of Contents

  1. System Overview
  2. Architecture Components
  3. Data Flow
  4. Database Schema
  5. Security Architecture
  6. External Integrations
  7. Deployment Architecture
  8. Key Design Decisions
  9. Technology Stack

System Overview

OmniTipper is a Discord-based cryptocurrency tipping bot that operates on the Base blockchain. The system enables users to tip, deposit, and withdraw various ERC20 tokens and native ETH through Discord commands, with off-chain transfers for tips and on-chain operations for deposits and withdrawals.

System Diagram

!System Architecture Diagram

Core Principles

Architecture Components

1. Bot Layer (src/bot.ts)

The main entry point that orchestrates all components: src/utils/rate-limiter.ts). Per-command limits are configured at the top of bot.ts; unknown command keys fall back to a default bucket so newly added commands cannot bypass throttling. ADMINCHANNELID are set, !admin is only accepted in DMs to the bot or in the configured guild channel (threads under it count). With either env var unset, !admin works anywhere the user is otherwise authorized (legacy). Key Responsibilities:

2. Command Handlers (src/commands/)

Modular command processors for user interactions:

User Commands

Admin Commands (admin.ts)

3. Service Layer (src/services/)

Core business logic services:

Web3Service (web3.ts)

Handles all blockchain interactions:

PriceService (price.ts)

Handles cryptocurrency price conversions:

MetricsService (metrics.ts)

Prometheus-compatible metrics collection: omnitipperdepositmonitorbatchusers, omnitipperdepositmonitoreligibleusers, omnitipperdepositmonitorchunkedmode ready/shardResume and shardDisconnect handlers), omnitipperdiscordguilds, omnitipperdiscordguild_channels Alert rules consuming these metrics live in prometheus-alerts.yml; SLO targets and the metric ↔ rule mapping are in docs/monitoring/SLOs-and-alerts.md.

MetricsServer (metrics-server.ts)

HTTP server exposing Prometheus metrics:

4. Database Layer (src/database/)

MongoDB-based data persistence:

Connection (connection.ts)

pool size under concurrent command load

Models (models.ts)

Database schema and operations: Collections: lastUserId) used when DEPOSITCHECKUSERBATCHSIZE > 0 so chunked scans resume across restarts instead of always starting from user 0 Key Features:

5. Utility Layer (src/utils/)

Supporting utilities:

Encryption (encryption.ts)

Logger (logger.ts)

Environment (env.ts)

Rate Limiter (rate-limiter.ts)

Admin Command Context (admin-command-context.ts)

is unset (legacy global behavior), and otherwise requires both guildId and the channel id (parent channel for threads) to match

Operational scaling

These mechanisms are documented in detail in docs/monitoring/SLOs-and-alerts.md, docs/runbooks/high-availability.md, and docs/architecture-tenancy.md. user with a deposit address each tick (legacy behavior). > 0 switches to round-robin chunks: each tick reads batchSize users starting after the persisted cursor and advances the cursor on success. On retryable balance errors the cursor is not advanced so the same chunk is retried next tick. bucket catches unknown commands. Limits live in src/bot.ts and can be raised for power users without code changes elsewhere. both set, !admin is restricted to DMs or that single channel (and its threads). Audit-friendly: admin actions concentrate in one logged channel. bot token. The bot is not horizontally scaled across replicas; use active/passive failover and rely on omnitipperdiscordgateway_up for alerting. pool ceiling under concurrent command load.

Data Flow

1. Tip Flow (Off-chain)

!Tip Flow Diagram No blockchain interaction - pure database operation

2. Deposit Flow (On-chain)

!Deposit Flow Diagram

3. Withdrawal Flow (On-chain)

!Withdrawal Flow Diagram

4. ERC20 Transfer from Deposit Address Flow

!ERC20 Transfer Flow Diagram

5. Price Conversion Flow

!Price Conversion Flow Diagram

Database Schema

!Database Schema Diagram

Users Collection

{
  _id: string;                    // Discord user ID
  username: string;                // Discord username
  balances: Record<string, string>; // coin symbol -> balance (string for precision)
  depositAddress: string | null;   // Single address for all tokens
  depositPrivateKey: string | null; // Encrypted private key
  createdAt: Date;
  updatedAt: Date;
}
Indexes:

Coins Collection

{
  _id: string;                     // Token symbol (e.g., "USDC", "ETH")
  contractAddress: string | null;  // ERC20 contract address (null for native ETH)
  decimals: number;                 // Token decimals
  name: string;                    // Token name
  enabled: boolean;                 // Whether token is enabled
  isNative: boolean;                // true for native ETH
  createdAt: Date;
}
Indexes:

BotBalances Collection

{
  coin: string;                    // Token symbol
  balance: string;                  // On-chain balance (string for precision)
  updatedAt: Date;
}
Indexes:

DepositTracking Collection

{
  _id: string;                     // "userId:coinSymbol"
  userId: string;                  // Discord user ID
  coin: string;                    // Token symbol
  lastCheckedBalance: string;      // Last checked balance
  botFundedAmount: string;         // ETH funded by bot (not user deposit)
  updatedAt: Date;
}
Indexes:

GasFeeTracking Collection

{
  _id: string;                     // Transaction hash or 'total'
  type: 'funding' 
'withdrawal'
 'transfer';
  amount: string;                   // Gas fee in ETH (string for precision)
  transactionHash?: string;         // Transaction hash
  depositAddress?: string;         // For funding operations
  userId?: string;                  // For withdrawal operations
  createdAt: Date;
}
Indexes:

Security Architecture

1. Private Key Encryption

2. Access Control

3. Input Validation

4. Rate Limiting

5. Balance Precision

6. Transaction Safety

External Integrations

1. Discord API

2. Base Blockchain

3. CoinMarketCap API

4. MongoDB

Deployment Architecture

Container Architecture

!Container Architecture Diagram

Docker Compose Setup

┌─────────────────────────────────────┐
│         Docker Network              │
│                                     │
│  ┌──────────────┐  ┌─────────────┐ │
│  │   Bot        │  │  MongoDB    │ │
│  │  Container   │◄─┤  Container  │ │
│  │              │  │             │ │
│  │  - Bun       │  │  - MongoDB 7│ │
│  │  - Node.js   │  │  - Volume   │ │
│  │  - Source    │  │    Mounted  │ │
│  └──────┬───────┘  └─────────────┘ │
│         │                          │
└─────────┼──────────────────────────┘
          │
          ▼
    ┌──────────┐
    │ Discord  │
    │   API    │
    └──────────┘
          │
          ▼
    ┌──────────┐
    │  Base    │
    │  RPC     │
    └──────────┘
          │
          ▼
    ┌──────────┐
    │CoinMarket│
    │   Cap    │
    └──────────┘

Container Configuration

Bot Container: MongoDB Container:

Environment Variables

Required: Optional:

Key Design Decisions

1. Off-chain Tips

Decision: Tips are database-only operations (no blockchain transactions) Rationale: Trade-offs:

2. Single Deposit Address per User

Decision: One deposit address per user for all tokens Rationale: Trade-offs:

3. Automatic ETH Funding

Decision: Bot automatically funds deposit addresses with ETH for gas Rationale: Trade-offs:

4. ETH Sweeping

Decision: Automatically sweep excess ETH from deposit addresses Rationale: Trade-offs:

5. Batch Balance Checking

Decision: Use JSON-RPC batch requests for balance checks Rationale: Trade-offs:

6. String-based Balance Storage

Decision: Store all balances as strings in database Rationale: Trade-offs:

7. Gas Fee Tracking

Decision: Track all gas fees separately for accounting Rationale: Trade-offs:

8. Recursive Deposit Checking

Decision: Use recursive setTimeout instead of setInterval Rationale: Trade-offs:

Technology Stack

Runtime & Language

Core Dependencies

Infrastructure

External Services

Development Tools

Performance Considerations

1. RPC Optimization

2. Database Optimization

3. API Optimization

4. Memory Management

Monitoring & Observability

Logging

Metrics (Prometheus)

The bot exposes Prometheus-compatible metrics on an HTTP endpoint for integration with Grafana or other monitoring systems.

Metrics Endpoint

Available Metrics

Counters: Gauges: Summaries:

Grafana Integration

  1. Configure Prometheus to scrape the metrics endpoint:
scrape_configs:

  • job_name: 'omnitipper'

       static_configs:

  • targets: ['bot-container:9090']
  1. Import Grafana Dashboard or create custom dashboards using the available metrics
  1. Set up Alerts for:

Key Metrics to Monitor

Health Checks

Future Enhancements

Potential Improvements

  1. Multi-chain support: Extend to other EVM chains
  2. Transaction history: Track all user transactions
  3. Analytics dashboard: Admin interface for metrics
  4. Webhook notifications: Alternative to DMs
  5. Rate limiting: Per-user command rate limits
  6. Multi-signature wallet: Enhanced security
  7. Automated testing: Comprehensive test suite
  8. API endpoint: REST API for external integrations

Conclusion

OmniTipper is designed as a scalable, secure, and efficient cryptocurrency tipping bot. The architecture prioritizes: The system is production-ready and can handle high-volume operations while maintaining accuracy and security.