Hannibal B2C Crypto Deposit & Withdrawal System
Design Document v1.1
Executive Summary
This document describes how Hannibal will enable users to deposit cryptocurrency, place bets, and withdraw their winnings directly—without going through agents. This is called B2C mode (Business-to-Consumer), as opposed to the current B2B2C mode where agents manage user funds.
Key Principles:
- Users deposit crypto and bet with real money (not points)
- Users can only withdraw on the same blockchain they deposited on
- All betting happens on an internal ledger (fast, free, instant)
- The platform holds a liquidity pool to pay winners immediately
- Web3Auth handles login only - deposits and withdrawals use platform-controlled wallets
Important Clarification: Web3Auth's Role
What Web3Auth Does
Web3Auth is our authentication system. When users log in with Google or Email:
- Web3Auth verifies their identity
- Web3Auth automatically creates embedded wallets for them (Solana, Ethereum, Tron)
- These wallets are tied to their social login
What We Use vs. What We Ignore
| Web3Auth Feature | Do We Use It? | Why? |
|---|---|---|
| Authentication | ✅ Yes | Secure, familiar login with Google/Email |
| User Identity | ✅ Yes | Links user to their account |
| Embedded Wallets | ❌ No (for B2C) | Not needed for deposits/withdrawals |
Why Not Use the Web3Auth Wallets for Deposits?
The Web3Auth wallets are embedded wallets - they exist inside our app. If we required users to deposit to their Web3Auth wallet first, they would need to:
- Send crypto from Coinbase → Web3Auth wallet (first transaction)
- Send crypto from Web3Auth wallet → Platform wallet (second transaction)
This is cumbersome and unnecessary.
Instead, we let users deposit directly to the platform from any external wallet (Coinbase, Binance, MetaMask, etc.). The Web3Auth wallet simply sits unused for B2C users - and that's fine! Web3Auth is free, so there's no cost to having these wallets exist.
The Simple Truth
Think of it like this:
- Web3Auth = Your login credentials (like logging into a bank with your fingerprint)
- Platform Wallet = The bank's vault (where money actually goes)
- Web3Auth Wallet = A free safety deposit box you got but don't use
How Industry Leaders Do It
Polymarket (Prediction Markets)
Polymarket is the world's largest prediction market platform. Here's how they handle money:
- Currency: USDC (a stablecoin pegged to $1 USD)
- Blockchain: Polygon network (fast, cheap transactions)
- Deposits: Users can deposit USDC from Ethereum (automatically bridged) or directly on Polygon
- Card Payments: Users can buy USDC with Visa/Mastercard via MoonPay
- Internal System: Once deposited, all trading happens on their internal system—no blockchain fees for each bet
- Withdrawals: Fast and fee-free back to user's wallet
- No Limits: Polymarket has no deposit or withdrawal limits
Crypto Exchanges (Binance, Coinbase)
Major exchanges use a similar pattern:
- User deposits crypto to the exchange's address
- Exchange credits user's internal balance (stored in a database)
- All trades happen on the internal ledger (instant, free)
- User requests withdrawal → exchange sends crypto to user's wallet
- Exchanges keep most funds in "cold storage" (offline, very secure) and only a small portion in "hot wallets" (online, for instant withdrawals)
Key Insight
No platform runs every transaction on the blockchain. They all use an internal ledger for speed and cost efficiency. Blockchain is only used for deposits and withdrawals.
Hannibal's Approach
What Makes Us Different
Hannibal supports three different blockchains to serve users worldwide:
| Blockchain | Stablecoin | Why Users Choose It |
|---|---|---|
| Solana | USDC | Very fast, very cheap (~$0.001 per transaction) |
| Ethereum | USDC or USDT | Most popular, widely available |
| Tron | USDT | Popular in Asia, cheap transactions |
The Chain-Lock Principle
Users must withdraw on the same chain they deposited on.
Why? Cross-chain transfers (moving money between blockchains) are expensive and complex. By keeping each user's funds on their original chain, we:
- Eliminate expensive bridging fees
- Simplify our operations
- Reduce risk of errors
Example:
- User deposits 100 USDC on Solana → Can only withdraw to Solana
- User deposits 100 USDT on Tron → Can only withdraw to Tron
User Journey
Step 1: Sign Up and Choose Your Chain
When a user signs up for B2C mode:
- User logs in with Google/Email (via Web3Auth)
- Web3Auth authenticates them and creates embedded wallets (we won't use these for deposits)
- User selects their preferred chain (one-time choice)
- System generates a unique deposit address for this user on their chosen chain
- User provides their withdrawal address (where they want to receive funds)
┌─────────────────────────────────────────────────────────────┐
│ CHOOSE YOUR CHAIN │
├─────────────────────────────────────────────────────────────┤
│ │
│ Which blockchain do you want to use for deposits and │
│ withdrawals? (This cannot be changed later) │
│ │
│ ○ Solana (USDC) │
│ • Fastest transactions │
│ • Lowest fees (~$0.001) │
│ • Popular for DeFi users │
│ │
│ ○ Ethereum (USDC/USDT) │
│ • Most widely available │
│ • Higher fees ($1-50) │
│ • Supported by all exchanges │
│ │
│ ○ Tron (USDT) │
│ • Popular in Asia │
│ • Low fees (~$1) │
│ • USDT focused │
│ │
│ [Continue →] │
└─────────────────────────────────────────────────────────────┘
After choosing a chain, user enters their withdrawal address:
┌─────────────────────────────────────────────────────────────┐
│ SET WITHDRAWAL ADDRESS │
├─────────────────────────────────────────────────────────────┤
│ │
│ Enter your Solana wallet address for withdrawals: │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ (paste your wallet address here) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ This is where we'll send your winnings when you │
│ request a withdrawal. │
│ │
│ 💡 You can use any Solana wallet address: │
│ • Your Coinbase Solana address │
│ • Your Phantom wallet │
│ • Your Binance Solana address │
│ • Any other Solana wallet you control │
│ │
│ ⚠️ Make sure this address is correct! Withdrawals to │
│ wrong addresses cannot be recovered. │
│ │
│ [Save & Continue →] │
└─────────────────────────────────────────────────────────────┘
Step 2: Deposit Funds
Once setup is complete, user sees their unique deposit address (this is a platform-controlled address, NOT their Web3Auth wallet):
┌─────────────────────────────────────────────────────────────┐
│ DEPOSIT FUNDS │
├─────────────────────────────────────────────────────────────┤
│ │
│ Your Personal Deposit Address (Solana): │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU │ │
│ └─────────────────────────────────────────────────────┘ │
│ [Copy Address] [Show QR Code] │
│ │
│ This address is unique to your account. │
│ Send USDC from ANY wallet or exchange. │
│ │
│ ✅ You can send from: │
│ • Coinbase, Binance, Kraken, etc. │
│ • MetaMask, Phantom, Trust Wallet │
│ • Any wallet that holds USDC on Solana │
│ │
│ Minimum deposit: $10 │
│ Expected arrival: ~1 minute after confirmation │
│ │
│ ⚠️ Only send USDC on Solana network. │
│ │
└─────────────────────────────────────────────────────────────┘
How Deposits Work Behind the Scenes:
- Each user gets a unique deposit address generated by the platform
- User sends USDC from ANY external wallet (Coinbase, Binance, MetaMask, etc.)
- Our system monitors this unique address for incoming transactions
- When deposit arrives, we know exactly which user it belongs to (it's their unique address)
- We credit the user's internal balance
- User can now place bets
Key Point: The deposit address is platform-controlled (we have the private key). It's NOT the user's Web3Auth wallet. This means users can deposit from anywhere - no need to first fund their Web3Auth wallet.
Step 3: Place Bets
Once the user has a balance, betting works identically to the current system:
- User browses available markets (sports, events, etc.)
- User places bets using their dollar balance
- Bets are tracked on our internal system (instant, no blockchain involved)
- When the user wins, their balance increases
- When the user loses, their balance decreases
Important: No blockchain transactions happen during betting. Everything is on our fast internal ledger.
Step 4: Withdraw Winnings
When the user wants to cash out, we send to the withdrawal address they provided during setup:
┌─────────────────────────────────────────────────────────────┐
│ WITHDRAW FUNDS │
├─────────────────────────────────────────────────────────────┤
│ │
│ Available Balance: $1,250.00 │
│ │
│ Withdrawal Amount: │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ $500.00 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Sending to your registered withdrawal address: │
│ 8yLMnH3CX98e08UYTEqcC6kBkhfUr84TZSvJptBtWxV │
│ [Change Address] │
│ │
│ You will receive: 500 USDC on Solana │
│ Network fee: ~$0.001 (paid by platform) │
│ Estimated arrival: ~1 minute │
│ │
│ [Confirm Withdrawal] │
│ │
└─────────────────────────────────────────────────────────────┘
How Withdrawals Work Behind the Scenes:
- User requests withdrawal amount
- System checks user has sufficient balance
- System checks withdrawal limits (security measure)
- For small amounts: processed automatically (instant)
- For large amounts: queued for manual approval (security)
- Platform sends USDC from our hot wallet to user's registered withdrawal address
- User's internal balance is reduced
Key Point: Withdrawals go to the address the user provided during setup - this can be their Coinbase address, Phantom wallet, Binance address, or any wallet they control. It is NOT the Web3Auth embedded wallet.
The Deposit Flow (Detailed)
Key Points:
- Each user gets a unique deposit address generated by the platform
- Users can deposit from ANY wallet (Coinbase, Binance, MetaMask, etc.)
- No need to identify sender - the destination address tells us which user
- Deposits are credited after blockchain confirmations (varies by chain)
- Users receive in-app notification when deposit is credited
- Web3Auth wallet is NOT involved in the deposit process
The Withdrawal Flow (Detailed)
Key Points:
- Withdrawals go to the user's registered withdrawal address (set during onboarding)
- This address can be their Coinbase, Binance, MetaMask, or any wallet they control
- Web3Auth wallet is NOT involved - we send directly to their external address
- Users can update their withdrawal address (with security verification)
Withdrawal Limits (Security)
| Amount | Processing | Time |
|---|---|---|
| Under $1,000 | Automatic | ~1-5 minutes |
| $1,000 - $10,000 | Automatic with delay | ~1 hour |
| Over $10,000 | Manual approval required | 1-24 hours |
These limits protect against theft if our system is compromised.
Platform Wallet Architecture
Three Types of Platform Wallets
The platform manages three types of wallets:
┌─────────────────────────────────────────────────────────────┐
│ WALLET ARCHITECTURE │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. USER DEPOSIT ADDRESSES (Many) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ • One unique address per user per chain │ │
│ │ • Platform controls private keys │ │
│ │ • Used ONLY for receiving deposits │ │
│ │ • Funds swept to hot wallet periodically │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ (sweep) │
│ 2. HOT WALLET (One per chain) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ • Online, automated │ │
│ │ • Processes withdrawals 24/7 │ │
│ │ • Limited funds ($20-50K per chain) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ (manual top-up) │
│ 3. COLD WALLET (One per chain) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ • Offline, hardware wallet │ │
│ │ • Bulk of funds ($200K+) │ │
│ │ • Manual transfers only │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
User Deposit Addresses
Each B2C user gets a unique deposit address for their chosen chain:
| User | Chain | Their Unique Deposit Address |
|---|---|---|
| alice@email.com | Solana | 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU |
| bob@email.com | Solana | 9yMNoI4DY98f08VZUFrdD7lClifVs95UZTvKquCtXwW |
| carol@email.com | Ethereum | 0x1234...abcd |
How it works:
- When user signs up, we generate a new wallet address for them
- We store the private key securely (encrypted in our database)
- User deposits to this address from anywhere
- We periodically "sweep" funds from these addresses to our hot wallet
Hot Wallet (Online)
- Connected to the internet
- Private key stored on server (encrypted)
- Can process withdrawals automatically 24/7
- Contains limited funds (max $20-50K per chain)
- If hacked: maximum loss is limited to hot wallet balance
Cold Wallet (Offline)
- Hardware wallet (Ledger/Trezor) held by platform owner
- Never connected to internet servers
- Manual transfers only
- Contains majority of platform funds
- Virtually impossible to hack remotely
Why Separate Wallets Per Chain?
Critical concept: Each blockchain is a completely separate network. Tokens on different chains are NOT interchangeable.
┌─────────────────────────────────────────────────────────────┐
│ │
│ USDC on Solana ≠ USDC on Ethereum ≠ USDT on Tron │
│ │
│ These are DIFFERENT tokens on DIFFERENT blockchains. │
│ You CANNOT send Solana USDC to an Ethereum address. │
│ You CANNOT pay an Ethereum user from a Solana wallet. │
│ │
└─────────────────────────────────────────────────────────────┘
This means:
- A Solana user deposits → funds go to Solana hot wallet
- A Solana user withdraws → funds come from Solana hot wallet
- An Ethereum user deposits → funds go to Ethereum hot wallet
- An Ethereum user withdraws → funds come from Ethereum hot wallet
Each chain operates as a completely independent money pool.
Per-Chain Wallet Summary
┌─────────────────────────────────────────────────────────────┐
│ MULTI-CHAIN WALLET SETUP │
├─────────────────────────────────────────────────────────────┤
│ │
│ SOLANA │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Deposit Addresses: Many (one per Solana user) │ │
│ │ Hot Wallet: 1 (for Solana withdrawals) - $20-50K │ │
│ │ Cold Wallet: 1 (Solana reserves) - $200K+ │ │
│ │ Token: USDC │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ETHEREUM │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Deposit Addresses: Many (one per Ethereum user) │ │
│ │ Hot Wallet: 1 (for Ethereum withdrawals) - $20-50K │ │
│ │ Cold Wallet: 1 (Ethereum reserves) - $200K+ │ │
│ │ Token: USDC or USDT │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ TRON │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Deposit Addresses: Many (one per Tron user) │ │
│ │ Hot Wallet: 1 (for Tron withdrawals) - $20-50K │ │
│ │ Cold Wallet: 1 (Tron reserves) - $200K+ │ │
│ │ Token: USDT │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
| Chain | User Deposit Addresses | Hot Wallet | Cold Wallet | Token |
|---|---|---|---|---|
| Solana | Many (one per user) | 1 | 1 | USDC |
| Ethereum | Many (one per user) | 1 | 1 | USDC/USDT |
| Tron | Many (one per user) | 1 | 1 | USDT |
Total: 6 platform wallets (3 hot + 3 cold) + many user deposit addresses
Liquidity Management Across Chains
Since each chain is independent, we need to manage liquidity separately:
| Scenario | Problem | Solution |
|---|---|---|
| Solana hot wallet runs low | Can't pay Solana withdrawals | Top up from Solana cold wallet |
| Ethereum has excess, Solana is low | Can't move ETH funds to Solana easily | Manual rebalancing via CEX (costly, avoid if possible) |
| One chain is more popular | Imbalanced liquidity | Monitor and adjust cold wallet reserves |
This is why we lock users to their deposit chain - it keeps liquidity predictable and avoids expensive cross-chain bridging.
Sweeping: Consolidating Funds
What is Sweeping?
Sweeping is the process of moving funds from individual user deposit addresses into the main hot wallet pool.
┌─────────────────────────────────────────────────────────────┐
│ SWEEP PROCESS │
├─────────────────────────────────────────────────────────────┤
│ │
│ User Deposit Addresses Hot Wallet │
│ (funds scattered) (funds consolidated) │
│ │
│ ┌─────────────┐ │
│ │ Alice: $100 │──────┐ │
│ └─────────────┘ │ │
│ ┌─────────────┐ │ SWEEP ┌─────────────────┐ │
│ │ Bob: $50 │──────┼──────────────►│ HOT WALLET │ │
│ └─────────────┘ │ │ $350 total │ │
│ ┌─────────────┐ │ └─────────────────┘ │
│ │ Carol: $200 │──────┘ │
│ └─────────────┘ │
│ │
│ After sweep: deposit addresses are empty, hot wallet full │
│ │
└─────────────────────────────────────────────────────────────┘
Why We Need Sweeping
| Reason | Explanation |
|---|---|
| Operational simplicity | One wallet to manage withdrawals from, not thousands |
| Withdrawal speed | Hot wallet always has funds ready to send |
| Security | Fewer addresses holding funds = smaller attack surface |
| Key management | Easier to secure and monitor one hot wallet |
| Avoid complexity | Without sweeping, withdrawal logic becomes complex (which address to send from?) |
When Does Sweeping Happen?
| Chain | Sweep Strategy | Why |
|---|---|---|
| Solana | Immediate (on each deposit) | Gas is ~$0.001, negligible cost |
| Ethereum | Batched (every 6 hours) or threshold ($100+) | Gas is expensive ($2-5 per tx) |
| Tron | Immediate or hourly | Gas is cheap (~$0.5) |
Important: Balance Credit vs Sweep
These are two separate operations:
┌─────────────────────────────────────────────────────────────┐
│ │
│ 1. CREDIT BALANCE (always immediate) │
│ ───────────────────────────────── │
│ • Deposit detected on blockchain │
│ • User's database balance updated IMMEDIATELY │
│ • User can bet right away │
│ • User sees: "Deposit confirmed!" │
│ │
│ 2. SWEEP FUNDS (can be delayed) │
│ ───────────────────────────────── │
│ • Move actual crypto from deposit address → hot wallet │
│ • Can happen immediately OR in batches │
│ • User never sees this - internal housekeeping │
│ • User doesn't care where the crypto physically sits │
│ │
└─────────────────────────────────────────────────────────────┘
The user experience is always instant - sweeping is just backend housekeeping.
Gas Fees for Sweeping
| Action | Who Pays Gas | Notes |
|---|---|---|
| User deposits to platform | User pays | They initiate the transaction |
| Sweep to hot wallet | Platform pays | Our operational cost |
| User withdraws | Platform pays | Our operational cost |
Cost estimate per chain (for sweeping):
- Solana: ~$0.001 per sweep (negligible)
- Ethereum: ~$2-5 per sweep (batch to reduce costs)
- Tron: ~$0.5 per sweep (acceptable)
The Internal Ledger System
What is an Internal Ledger?
Think of it like a bank's record system:
- When you deposit $100 at a bank, they don't put a $100 bill in a box with your name on it
- Instead, they record "+$100" next to your account number in their system
- When you spend money, they subtract from your balance
- Your "balance" is just a number in their database
We work exactly the same way.
How It Works
┌─────────────────────────────────────────────────────────────┐
│ INTERNAL LEDGER │
├─────────────────────────────────────────────────────────────┤
│ │
│ USER: john@example.com │
│ ─────────────────────────────────────────────────────── │
│ Chain: Solana │
│ ─────────────────────────────────────────────────────── │
│ │
│ Date | Action | Amount | Balance │
│ ────────────┼─────────────┼─────────┼───────── │
│ Jan 15 | Deposit | +$500 | $500 │
│ Jan 16 | Bet placed | -$100 | $400 │
│ Jan 16 | Bet won! | +$180 | $580 │
│ Jan 17 | Bet placed | -$50 | $530 │
│ Jan 17 | Bet lost | $0 | $530 │
│ Jan 18 | Withdrawal | -$200 | $330 │
│ │
│ Current Balance: $330.00 │
│ │
└─────────────────────────────────────────────────────────────┘
Benefits of Internal Ledger
| Benefit | Explanation |
|---|---|
| Instant | No waiting for blockchain confirmations |
| Free | No transaction fees for betting |
| Scalable | Can handle millions of bets per second |
| Auditable | Complete history of every transaction |
| Reversible | Can fix errors (unlike blockchain) |
The Settlement Gap Problem
The Challenge
When users bet on Betfair/Pinnacle through Hannibal:
- Users expect instant withdrawal when they win
- But Betfair/Pinnacle settle with us weekly
This creates a 7-day gap where we need to pay winners from our own pocket.
The Solution: Liquidity Pool
We maintain a liquidity pool (reserve of funds) to bridge this gap:
┌─────────────────────────────────────────────────────────────┐
│ LIQUIDITY FLOW │
├─────────────────────────────────────────────────────────────┤
│ │
│ DAY 1-6: Users win bets │
│ ↓ │
│ We pay winners from our liquidity pool │
│ ↓ │
│ DAY 7: Bookmakers settle with us │
│ ↓ │
│ Our pool is replenished │
│ │
└─────────────────────────────────────────────────────────────┘
Liquidity Requirements
| Scenario | Required Liquidity |
|---|---|
| Low volume (launch) | $50K - $100K |
| Medium volume | $100K - $250K |
| High volume | $250K - $500K+ |
The liquidity pool should cover approximately 7 days of expected net payouts.
Security Measures
Protection Layers
Key Security Features
| Feature | Purpose |
|---|---|
| Withdrawal Limits | Limit damage if account compromised |
| Rate Limiting | Prevent rapid-fire withdrawal attacks |
| Hot/Cold Split | Minimize funds at risk |
| Manual Approval | Human review for large amounts |
| Monitoring Alerts | Notify admins of unusual activity |
| Audit Trail | Complete log of all transactions |
What Happens If We're Hacked?
Worst Case Scenario:
- Attacker gains access to hot wallet
- Maximum loss: Contents of hot wallet ($20-50K)
- Cold wallet remains safe (offline)
- User funds in database are just records (can be restored)
Recovery Plan:
- Disable withdrawals immediately
- Assess damage
- Top up hot wallet from cold reserves
- Resume operations
- Review and strengthen security
B2C vs B2B2C Mode
Hannibal will support both modes simultaneously:
| Aspect | B2B2C (Current) | B2C (New) |
|---|---|---|
| Currency | Points | USD (Stablecoins) |
| Funding | Through agents | Direct deposit to platform |
| Withdrawals | Agent handles | User withdraws to their external wallet |
| Target Users | Users in agent networks | Direct crypto users |
| Settlement | Agent settles weekly | Instant to user |
| Authentication | Web3Auth | Web3Auth (same) |
| Web3Auth Wallet Used? | For identification | Not used (exists but ignored) |
Mode Toggle
The system will use a simple flag to determine user mode:
B2B2C users: Continue using points and agentsB2C users: Use crypto deposits and withdrawals
Users cannot switch between modes once they've started (to prevent confusion and accounting issues).
Web3Auth in Both Modes
| Mode | Web3Auth Role |
|---|---|
| B2B2C | Authentication + wallet address for identification |
| B2C | Authentication only (wallet exists but unused) |
Why keep Web3Auth for B2C?
- It's free - no cost to us
- Single authentication system for all users
- Familiar login experience (Google/Email)
- If we ever need the wallet later, it's there
Implementation Phases
Phase 1: Foundation (2-3 weeks)
- Set up platform wallets (hot + cold for each chain)
- Build internal ledger system
- Create deposit monitoring service
- Design withdrawal processing queue
Phase 2: Single Chain Launch (2 weeks)
- Launch with Solana only (fastest, cheapest)
- Test deposit/withdrawal flows
- Monitor for issues
- Gather user feedback
Phase 3: Multi-Chain Expansion (2-3 weeks)
- Add Ethereum support
- Add Tron support
- Build chain-selection UI
Phase 4: Enhancements (Ongoing)
- Add card payments (via MoonPay or similar)
- Implement advanced security features
- Add liquidity management dashboard
- Build automated rebalancing alerts
Risk Management
Financial Risks
| Risk | Mitigation |
|---|---|
| Insufficient liquidity | Maintain 7-day reserve buffer |
| Large winning streak | Exposure limits per user |
| Market volatility | Use stablecoins (pegged to $1) |
Technical Risks
| Risk | Mitigation |
|---|---|
| Server compromise | Hot/cold wallet split |
| Database failure | Regular backups + replicas |
| Blockchain congestion | Queue system with retries |
Operational Risks
| Risk | Mitigation |
|---|---|
| Wrong chain deposit | Clear warnings in UI |
| User sends wrong token | Detection + manual recovery process |
| Withdrawal delays | Status page + notifications |
Summary
What We're Building
- Direct crypto deposits on Solana, Ethereum, or Tron via unique deposit addresses
- Internal ledger for fast, free betting
- Instant withdrawals to user-specified external addresses (within limits)
- Chain-locked funds (no expensive bridging)
- Hot/cold wallet security architecture
- Web3Auth for login only - embedded wallets exist but are not used for B2C
Key Design Decisions
| Decision | Rationale |
|---|---|
| Chain-locked withdrawals | Eliminates bridging costs |
| Internal ledger | Fast, free, scalable |
| Hot/cold wallets | Security vs usability balance |
| Withdrawal limits | Damage control |
| Unique deposit addresses | Users can deposit from anywhere (Coinbase, Binance, etc.) |
| User-provided withdrawal addresses | Users withdraw to any wallet they control |
| Keep Web3Auth (ignore wallet) | Free, single auth system, familiar UX |
Success Metrics
- Deposit success rate > 99%
- Withdrawal processing time < 5 minutes (under limits)
- Zero security incidents
- User satisfaction with funding flow
Appendix: Glossary
| Term | Definition |
|---|---|
| Stablecoin | Cryptocurrency pegged to $1 USD (e.g., USDC, USDT) |
| Hot Wallet | Platform wallet connected to internet for automated withdrawals |
| Cold Wallet | Platform wallet kept offline for secure storage of bulk funds |
| User Deposit Address | Unique platform-controlled address assigned to each user for receiving deposits |
| Withdrawal Address | External wallet address provided by user where they want to receive withdrawals |
| Sweep | Moving funds from user deposit addresses to the hot wallet pool (consolidation) |
| Ledger | Record-keeping system for balances and transactions |
| Bridging | Moving funds between different blockchains (we avoid this) |
| Settlement | When bookmakers pay out winnings |
| Liquidity Pool | Reserve funds for paying winners before bookmaker settlement |
| B2C | Business-to-Consumer (direct user relationship) |
| B2B2C | Business-to-Business-to-Consumer (through agents) |
| Web3Auth | Authentication service using social logins; creates embedded wallets (unused in B2C) |
| Embedded Wallet | Wallet created by Web3Auth tied to user's social login (not used for B2C deposits/withdrawals) |
| Gas Fee | Transaction fee paid to blockchain network for processing transactions |
Document Version: 1.3 Last Updated: January 2026 Author: Hannibal Engineering Team