Telegram Auction Bot - Complete Project Specification

Project Overview

A Telegram bot for managing various types of auctions, built in Rust using SQLite as the backend database. The bot facilitates auctions between sellers and buyers without handling payments directly.

See a list of user stories for the project under backlog/docs/user-stories.md.

Core Features

Listing Types

1. Basic Auctions: Traditional time-based bidding with anti-sniping protection
2. Multi-slot Auctions: Multiple winners (e.g., 3 commission slots available)
3. Fixed Price Listing: Set price with limited quantity
4. Blind Auctions: Bidders submit amounts with descriptions; seller chooses winner (not necessarily highest bid)

Key Functionality

• Telegram Bot: The bot is interacted with primarily through Telegram. Sellers can create listings, and view bids on listings. Buyers can bid on listings and view their bids.
• Proxy/Automatic Bidding: Users set maximum bid; system auto-bids up to that amount
• Anti-sniping Protection: Configurable time extension if bid placed in last N minutes
• Buy-now Option: Instant purchase at fixed price
• Media Support: Multiple images/videos per listing on the telegram post.
• Outbid Notifications: Configurable user notifications
• Non-payment Handling: Track failed payments, allow selection of next highest bidder
• Localization Support: Multi-language structure (to be implemented)
• Admin Interface: Separate web interface for moderation (to be implemented)

Key Design Decisions

1. Proxy Bid Architecture

• Proxy bids are stored as strategies in proxy_bids table
• Actual bids are events stored in bids table
• When a bid is placed, system checks for proxy bids and generates actual bids
• proxy_bid_id in bids table is NULL for manual bids, references proxy for auto-generated

2. Database Normalization

• No redundant data - everything computed from source
• Winning bid inferred from highest non-cancelled bid
• Last proxy bid amount inferred from bids with that proxy_bid_id

3. Multi-slot Auctions

• Single auction with slots_available > 1
• Top N bids win (where N = slots_available)
• Each winning bid gets a slot_number

Project Structure

auction-bot/
├── Cargo.toml           # Dependencies
├── .env                 # Environment variables (create from .env.example)
├── migrations/          # SQL migrations
│   └── 001_initial_schema.sql
└── src/
    └── main.rs         # Entry point, bot setup, command router

Current Implementation Status

❌ Not Yet Implemented

• Auction creation flow
• Media upload handling
• Bidding flow
• Settings management
• Proxy bidding logic
• Anti-snipe detection and time extension
• Notification system
• Tasks for auction expiry, scheduled to run when the auction ends
• Admin web interface (separate from the bot, uses the same database)
• Auction browsing with pagination
• Bid history viewing
• Localization/i18n

Critical Implementation Details

Proxy Bidding Logic

// When a new bid is placed:
// 1. Insert the actual bid
// 2. Find all active proxy bids for this auction (except current bidder)
// 3. For each proxy that can beat the new bid:
//    - Generate actual bid = current_bid + min_increment
//    - Update proxy's last generated bid
//    - Only one proxy responds per bid event

// When proxy bid is created/updated:
// 1. Upsert proxy bid strategy
// 2. Check current winning bid
// 3. If can beat it, generate immediate bid

Anti-Snipe Logic

// On each bid:
// 1. auction.ends_at = MAX(auction.ends_at, now + anti_snipe_minutes)
// 2. Notify users of time extension if there was one

Auction State Management

• Consider using HashMap<user_id, AuctionDraft> for in-memory draft storage
• Or create auction_drafts table for persistence across bot restarts

Background Tasks Needed

1. Auction Expiry Checker (every 30 seconds)

   • Find auctions where ends_at < now AND is_active = true
   • Mark as inactive
   • Create winner records
   • Send notifications

2. Notification Dispatcher (every 10 seconds)

   • Check notification queue
   • Batch send to avoid rate limits
   • Handle outbid, win, and reminder notifications

Environment Variables (.env)

# Required
TELOXIDE_TOKEN=your_bot_token_here
DATABASE_URL=sqlite:pawctioneer_bot.db

# Optional
RUST_LOG=info,pawctioneer_bot=debug
ADMIN_USER_ID=your_telegram_user_id
WEB_PORT=3000  # For future admin interface
TZ=UTC

Bot Commands (Set in BotFather)

start - Show welcome message
help - Show help message
newlisting - Create a new listing
mylistings - View your listings as a seller
mybids - View your active bids
settings - Configure notifications

Dependencies Rationale

• teloxide: Modern Telegram bot framework with good ergonomics
• sqlx: Compile-time checked SQL queries, async support
• tokio: Industry standard async runtime
• rust_decimal: Proper decimal handling for money

Next Implementation Steps (Priority Order)

1. Complete Listing Creation Flow

• Implement multi-step wizard state machine
• Handle media uploads (store Telegram file_ids)
• Add validation for each field
• Create listing in database

2. Implement Bidding System

• Place manual bid function
• Proxy bid creation and processing
• Bid validation (minimum amounts, increment checks)
• Update auction message after each bid

3. Add Background Tasks

• Tokio spawn for periodic tasks
• Auction expiry processing
• Notification sending

4. Listing Browsing

• Paginated list with filters
• Search functionality
• Detailed listing view with bid history

5. Admin Interface

• Axum web server in same binary
• Dashboard with stats
• User management (bans, warnings)
• Auction moderation tools

Testing Checklist

• User registration on first interaction
• Auction creation (all types)
• Manual bidding
• Proxy bidding with conflicts
• Anti-snipe time extension
• Buy-now purchase
• Multi-slot auction with multiple winners
• Blind auction with description
• Non-payment flow
• User ban system
• Notification delivery
• Media upload and display

Telegram API Rate Limits to Consider

• Telegram allows 30 messages/second to different users
• 20 messages/minute to same user
• Bulk notifications should be queued and throttled
• Edit message updates should be debounced