# Binance Alpha Farm Agent

Automated trading agent for Binance Alpha Farm with Task-Step architecture.

## 🏗️ System Architecture

### Core Components

- **AppState**: Centralized state management with observer pattern
- **TaskRunner**: Task execution engine
- **StateWatchers**: Observers for state changes
- **BAF API**: Server communication module
- **BINANCE**: Binance page detection and navigation

## 📋 Task-Step System

### Task Types

```javascript
TASK_TYPES = {
    LOGIN: 'login',
    GET_ORDER_HISTORY: 'get_order_history', 
    GET_BALANCE: 'get_balance',
    SWAP: 'swap',
    NO_TASK: 'no_task'
}
```

### Step Types

```javascript
STEP_TYPES = {
    // Login task steps
    NAVIGATE_TO_LOGIN: 'navigate_to_login',
    SELECT_QR_CODE: 'select_qr_code', 
    SEND_TO_SERVER: 'send_to_server',
    WAIT_FOR_LOGIN: 'wait_for_login',
    REPORT_RESULT: 'report_result',
    
    // Order history task steps
    NAVIGATE_TO_ORDER_HISTORY: 'navigate_to_order_history',
    EXTRACT_ORDER_DATA: 'extract_order_data',
    SEND_ORDER_DATA: 'send_order_data',
    
    // Balance task steps
    NAVIGATE_TO_BALANCE: 'navigate_to_balance',
    EXTRACT_BALANCE_DATA: 'extract_balance_data',
    SEND_BALANCE_DATA: 'send_balance_data',
    
    // Swap task steps
    NAVIGATE_TO_SWAP: 'navigate_to_swap',
    FILL_SWAP_FORM: 'fill_swap_form',
    CONFIRM_SWAP: 'confirm_swap',
    WAIT_FOR_SWAP: 'wait_for_swap',
    
    // Common steps
    WAIT: 'wait',
    ERROR_HANDLING: 'error_handling'
}
```

## 🤖 Bot Status Flow

### Status Types

```javascript
BOT_STATUS = {
    READY_FOR_NEW_TASKS: 'ready-for-new-tasks',
    PAUSE_AUTOMATION: 'pause-automation', 
    PERFORMING_TASKS: 'performing-tasks'
}
```

### Main Flow

```
┌─────────────────┐
│   Initialize    │
└─────────┬───────┘
          │
          ▼
┌─────────────────┐
│ Check Bot Status│
└─────────┬───────┘
          │
          ▼
┌─────────────────┐     ┌─────────────────┐
│ Ready for Tasks │────▶│   Ask Server    │
└─────────┬───────┘     │   for Tasks     │
          │             └─────────┬───────┘
          │                       │
          ▼                       ▼
┌─────────────────┐     ┌─────────────────┐
│   Sleep         │     │  No Task Found  │
│   (Interval)    │◀────│                 │
└─────────┬───────┘     └─────────────────┘
          │
          ▼
┌─────────────────┐     ┌─────────────────┐
│ Check Bot Status│────▶│  Task Received  │
└─────────┬───────┘     └─────────┬───────┘
          │                       │
          ▼                       ▼
┌─────────────────┐     ┌─────────────────┐
│ Ready for Tasks │     │  Perform Task   │
└─────────────────┘     └─────────┬───────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │  Task Complete  │
                       └─────────┬───────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │ Return to Ready │
                       └─────────────────┘
```

### Status Transitions

1. **READY_FOR_NEW_TASKS**
   - Poll server for new tasks
   - Sleep for `task_poll_interval` if no tasks
   - Transition to `PERFORMING_TASKS` when task received

2. **PAUSE_AUTOMATION** 
   - Stop all automation
   - No polling or task execution
   - Manual intervention required

3. **PERFORMING_TASKS**
   - Execute current task step by step
   - Update task data during execution
   - Transition back to `READY_FOR_NEW_TASKS` when complete

## 📊 Task Data Examples

### Login Task

```javascript
{
    type: TASK_TYPES.LOGIN,
    id: "task_123",
    data: {
        method: LOGIN_METHOD.QR_CODE, // 'qr_code' | 'password' | 'email'
        credentials: {
            email: 'user@example.com',    // For password method
            password: 'password123'       // For password method
        },
        timeout: 300000,  // 5 minutes timeout
        retry_count: 3
    },
    steps: [
        STEP_TYPES.NAVIGATE_TO_LOGIN,
        STEP_TYPES.SELECT_QR_CODE,
        STEP_TYPES.SEND_TO_SERVER,
        STEP_TYPES.WAIT_FOR_LOGIN,
        STEP_TYPES.REPORT_RESULT
    ]
}
```

### Get Order History Task

```javascript
{
    type: TASK_TYPES.GET_ORDER_HISTORY,
    id: "task_124", 
    data: {
        limit: 100,
        offset: 0,
        date_range: {
            start_date: '2024-01-01',
            end_date: '2024-12-31'
        },
        order_types: [
            ORDER_TYPE.SWAP,
            ORDER_TYPE.LIMIT, 
            ORDER_TYPE.MARKET
        ],
        status: [
            ORDER_STATUS.COMPLETED,
            ORDER_STATUS.PENDING,
            ORDER_STATUS.CANCELLED
        ]
    },
    steps: [
        STEP_TYPES.NAVIGATE_TO_ORDER_HISTORY,
        STEP_TYPES.EXTRACT_ORDER_DATA,
        STEP_TYPES.SEND_ORDER_DATA
    ]
}
```

### Get Balance Task

```javascript
{
    type: TASK_TYPES.GET_BALANCE,
    id: "task_125",
    data: {
        currencies: ['USDT', 'BTC', 'ETH'], // null for all currencies
        include_zero: false,
        include_locked: true,
        format: BALANCE_FORMAT.JSON // 'json' | 'csv'
    },
    steps: [
        STEP_TYPES.NAVIGATE_TO_BALANCE,
        STEP_TYPES.EXTRACT_BALANCE_DATA,
        STEP_TYPES.SEND_BALANCE_DATA
    ]
}
```

### Swap Task

```javascript
{
    type: TASK_TYPES.SWAP,
    id: "task_126",
    data: {
        from_token: 'USDT',
        to_token: 'BTC', 
        amount: 100,
        slippage: 0.5,        // percentage
        gas_fee: GAS_FEE_TYPE.AUTO, // 'auto' | 'fast' | 'slow' | number
        deadline: 300,         // seconds
        auto_confirm: true
    },
    steps: [
        STEP_TYPES.NAVIGATE_TO_SWAP,
        STEP_TYPES.FILL_SWAP_FORM,
        STEP_TYPES.CONFIRM_SWAP,
        STEP_TYPES.WAIT_FOR_SWAP
    ]
}
```

## 🔧 Enums & Constants

### Login Method
```javascript
LOGIN_METHOD = {
    QR_CODE: 'qr_code',
    PASSWORD: 'password', 
    EMAIL: 'email'
}
```

### Order Type
```javascript
ORDER_TYPE = {
    SWAP: 'swap',
    LIMIT: 'limit',
    MARKET: 'market'
}
```

### Order Status
```javascript
ORDER_STATUS = {
    COMPLETED: 'completed',
    PENDING: 'pending',
    CANCELLED: 'cancelled'
}
```

### Balance Format
```javascript
BALANCE_FORMAT = {
    JSON: 'json',
    CSV: 'csv'
}
```

### Gas Fee Type
```javascript
GAS_FEE_TYPE = {
    AUTO: 'auto',
    FAST: 'fast',
    SLOW: 'slow'
}
```

## 🎯 Page Detection

### Supported Pages

```javascript
BINANCE_PAGES = {
    LOGIN: 'login',
    ALPHA_SWAP: 'alpha-swap',
    ALPHA_ORDER_HISTORY: 'alpha-order-history',
    UNKNOWN: 'unknown'
}
```

### Page URLs

- **Login**: `https://accounts.binance.com/login`
- **Alpha Swap**: `https://www.binance.com/alpha/bsc/`
- **Alpha Order History**: `https://www.binance.com/en/my/orders/alpha/orderhistory`

## 🔄 State Management

### AppState Structure

```javascript
{
    // Server configuration
    server_mode: 'prod',
    server: { label: '🌐 Prod', url: 'https://baf.thuanle.me' },
    
    // Page state
    current_page: 'alpha-swap',
    is_logged_in: true,
    
    // Bot status
    bot_status: BOT_STATUS.READY_FOR_NEW_TASKS,
    
    // Task state
    current_task: { type: 'login', id: 'task_123', ... },
    task_data: { method: 'qr_code', timeout: 300000, ... },
    current_step: 'navigate_to_login',
    step_data: { attempts: 0, start_time: 1234567890 },
    
    // UI state
    is_loading: false,
    error_message: null
}
```

### Observer Pattern

State changes trigger observers:

- **server_mode** → Save to storage, reload page
- **bot_status** → Save to storage, start/stop task polling
- **current_page** → Continue current step if task active
- **is_logged_in** → Continue current step if task active

## 🛠️ Helper Functions

### TaskRunner Helpers

```javascript
// Validate enum values
TaskRunner.validateEnum(value, enumObj, defaultValue)

// Validate and merge task data
TaskRunner.validateTaskData(taskType, taskData)

// Get current task data
TaskRunner.getCurrentTaskData()

// Update task data during execution
TaskRunner.updateTaskData(newData)

// Check current task type
TaskRunner.isCurrentTaskType(TASK_TYPES.LOGIN)

// Get current task type
TaskRunner.getCurrentTaskType()
```

### State Helpers

```javascript
// Get current state
APP_STATE.getData()

// Update state (triggers observers)
APP_STATE.update({ bot_status: BOT_STATUS.PERFORMING_TASKS })

// Subscribe to state changes
APP_STATE.subscribe('bot_status', callback)

// Unsubscribe from state changes
APP_STATE.unsubscribe('bot_status', callback)
```

## 🎮 Menu Commands

### Available Commands

1. **Server**: Switch between local/prod servers
2. **Token**: Configure Bearer token for API access
3. **Bot Status**: Cycle through bot statuses (ready/pause/performing)
4. **Get Tasks**: Manually check for new tasks

### Usage

```javascript
// Access via Tampermonkey menu
// Right-click extension icon → Binance Alpha Farm Agent
```

## 📡 API Endpoints

### Server Communication

```javascript
// Ping server with status
BAF.ping(status)

// Get new task
BAF.getTasks()

// Submit task result
BAF.submitTaskResult(taskId, result)
```

### Status Payload

```javascript
{
    logged_in: true,
    current_page: 'alpha-swap',
    bot_status: 'ready-for-new-tasks',
    current_task: 'login',
    task_data: { method: 'qr_code', ... },
    current_step: 'navigate_to_login',
    has_current_task: true
}
```

## 🔧 Configuration

### CONFIG Object

```javascript
CONFIG = {
    heartbeat_interval: 10000,    // 10 seconds
    task_poll_interval: 10000,    // 10 seconds
    is_debug: true,
    servers: {
        local: { label: '🏠 Local', url: 'http://localhost:3000' },
        prod: { label: '🌐 Prod', url: 'https://baf.thuanle.me' }
    }
}
```

## 🚀 Getting Started

1. Install Tampermonkey browser extension
2. Install the user script
3. Configure server token via menu
4. Set bot status to "ready-for-new-tasks"
5. Bot will automatically start polling for tasks

## 📝 Development Notes

### Adding New Task Types

1. Add to `TASK_TYPES` enum
2. Define task data structure in `TASK_DATA_EXAMPLES`
3. Add validation in `validateTaskData()`
4. Implement execution method in `TaskRunner`
5. Define steps in `STEP_TYPES`

### Adding New Steps

1. Add to `STEP_TYPES` enum
2. Implement step logic in task execution
3. Update step data during execution
4. Handle step transitions

### Error Handling

- Invalid enum values fallback to defaults
- Task execution errors return bot to ready state
- Network errors trigger retry after interval
- Page navigation errors handled by observers