aitbc/docs/development/14_user-management-setup.md

User Management System for AITBC Trade Exchange

Overview

The AITBC Trade Exchange now includes a complete user management system that allows individual users to have their own wallets, balances, and transaction history. Each user is identified by their wallet address and has a unique session for secure operations.

Features Implemented

1. User Registration & Login

• Wallet-based Authentication: Users connect with their wallet address
• Auto-registration: New wallets automatically create a user account
• Session Management: Secure token-based sessions (24-hour expiry)
• User Profiles: Each user has a unique ID, email, and username

2. Wallet Management

• Individual Wallets: Each user gets their own AITBC wallet
• Balance Tracking: Real-time balance updates
• Address Generation: Unique wallet addresses for each user

3. Transaction History

• Personal Transactions: Each user sees only their own transactions
• Transaction Types: Buy, sell, deposit, withdrawal tracking
• Status Updates: Real-time transaction status

API Endpoints

User Authentication

POST /api/users/login
{
    "wallet_address": "aitbc1abc123..."
}

Response:

{
    "user_id": "uuid",
    "email": "wallet@aitbc.local",
    "username": "user_abc123",
    "created_at": "2025-12-28T...",
    "session_token": "sha256_token"
}

User Profile

GET /api/users/me
Headers: X-Session-Token: <token>

User Balance

GET /api/users/{user_id}/balance
Headers: X-Session-Token: <token>

Response:

{
    "user_id": "uuid",
    "address": "aitbc_uuid123",
    "balance": 1000.0,
    "updated_at": "2025-12-28T..."
}

Transaction History

GET /api/users/{user_id}/transactions
Headers: X-Session-Token: <token>

Logout

POST /api/users/logout
Headers: X-Session-Token: <token>

Frontend Implementation

1. Connect Wallet Flow

1. User clicks "Connect Wallet"
2. Generates a demo wallet address
3. Calls /api/users/login with wallet address
4. Receives session token and user data
5. Updates UI with user info

2. UI Components

• Wallet Section: Shows address, username, balance
• Connect Button: Visible when not logged in
• Logout Button: Clears session and resets UI
• Balance Display: Real-time AITBC balance

3. Session Management

• Session token stored in JavaScript variable
• Token sent with all API requests
• Automatic logout on token expiry
• Manual logout option

Database Schema

Users Table

• id: UUID (Primary Key)
• email: Unique string
• username: Unique string
• status: active/inactive/suspended
• created_at: Timestamp
• last_login: Timestamp

Wallets Table

• id: Integer (Primary Key)
• user_id: UUID (Foreign Key)
• address: Unique string
• balance: Float
• created_at: Timestamp
• updated_at: Timestamp

Transactions Table

• id: UUID (Primary Key)
• user_id: UUID (Foreign Key)
• wallet_id: Integer (Foreign Key)
• type: deposit/withdrawal/purchase/etc.
• status: pending/completed/failed
• amount: Float
• fee: Float
• created_at: Timestamp
• confirmed_at: Timestamp

Security Features

1. Session Security

• SHA-256 hashed tokens
• 24-hour automatic expiry
• Server-side session validation
• Secure token invalidation on logout

2. API Security

• Session token required for protected endpoints
• User isolation (users can only access their own data)
• Input validation and sanitization

3. Future Enhancements

• JWT tokens for better scalability
• Multi-factor authentication
• Biometric wallet support
• Hardware wallet integration

How It Works

1. First Time User

1. User connects wallet
2. System creates new user account
3. Wallet is created and linked to user
4. Session token issued
5. User can start trading

2. Returning User

1. User connects wallet
2. System finds existing user
3. Updates last login
4. Issues new session token
5. User sees their balance and history

3. Trading

1. User initiates purchase
2. Payment request created with user_id
3. Bitcoin payment processed
4. AITBC credited to user's wallet
5. Transaction recorded

Testing

Test Users

Each wallet connection creates a unique user:

• Address: aitbc1wallet_[random]x...
• Email: wallet@aitbc.local
• Username: user_[last_8_chars]

Demo Mode

• No real registration required
• Instant wallet creation
• Testnet Bitcoin support
• Simulated balance updates

Next Steps

1. Enhanced Features

• Email verification
• Password recovery
• 2FA authentication
• Profile customization

2. Advanced Trading

• Limit orders
• Stop-loss
• Trading history analytics
• Portfolio tracking

3. Integration

• MetaMask support
• WalletConnect protocol
• Hardware wallets (Ledger, Trezor)
• Mobile wallet apps

Support

For issues or questions:

• Check the logs: journalctl -u aitbc-coordinator -f
• API endpoints: https://aitbc.bubuit.net/api/docs
• Trade Exchange: https://aitbc.bubuit.net/Exchange