TWAP Execution Scheduling and Order Lifecycle Management

# twapexecutor


The **TWAPExecutor** is an implementation of a Time-Weighted Average Price (TWAP) execution strategy within the Hummingbot trading framework. This strategy is used to execute trades over a specified time horizon to minimize the market impact by breaking up a large order into smaller orders and executing them at regular intervals. Below is an overview of the key components and functionalities of the TWAPExecutor class:

### Key Components:

**Class Inheritance and Initialization**: The `TWAPExecutor` class inherits from `ExecutorBase`, indicating it's a specialized form of executor with additional logic for TWAP strategy execution. It initializes with a strategy, configuration, update interval, and maximum retries.
  
**Logging**: Utilizes Hummingbot's logging mechanism for logging information, warnings, and errors.
  
**Configuration and Validation**: Takes a `TWAPExecutorConfig` object as configuration, which defines the parameters for the TWAP strategy such as the connector to use, trading pair, number of orders, order interval, and order amount. It also validates if the order amount meets the minimum requirement of the trading pair.

**Order Plan Creation**: Generates a plan for when orders should be placed (`create_order_plan`) based on the configuration, mapping timestamps to `None` initially, which later gets replaced with actual `TrackedOrder` objects.

- **Order Execution and Management**:

  - Validates sufficient balance before placing orders.
  - Dynamically creates orders based on the order plan and updates the plan as orders are executed or need to be refreshed.
  - Handles order creation, completion, and failure events to manage the lifecycle of each order according to the TWAP strategy.
  - Can cancel open orders in case of early stop or shutdown.
  
**Control Task**: An asynchronous control task (`control_task`) that evaluates conditions for creating, refreshing, and completing orders, as well as retrying failed orders.

**Performance Metrics**: Calculates performance metrics such as filled amount, trade PnL (profit and loss), average executed price, cumulative fees, and net PnL.

### Key Functions:

- **`create_order_plan`**: Generates a schedule for when orders should be executed.

- **`validate_sufficient_balance`**: Ensures there is enough balance to execute the planned orders.

- **`control_task`**: Asynchronously evaluates various conditions to manage order execution lifecycle.

- **`create_order`**: Creates a new order based on the current state of the order plan and execution parameters.

- **`process_order_created_event`**, **`process_order_failed_event`**, **`process_order_completed_event`**: Event handlers for order lifecycle events.

- **Performance Metrics Methods**: Includes methods to calculate and retrieve performance metrics related to the execution of the TWAP strategy.

### Example Script

Use **TWAPExecutor** from a Strategy V2 script or controller: configure `TWAPExecutor` / `TWAPExecutorConfig` in code or via the Hummingbot API. There is no separate sample script named `v2_twap_multiple_pairs.py` in the current `scripts/` folder; refer to the executor class and API docs below. 

```python
class TWAPMultiplePairsConfig(StrategyV2ConfigBase):
    script_file_name: str = Field(default_factory=lambda: os.path.basename(__file__))
    candles_config: List[CandlesConfig] = []
    controllers_config: List[str] = []
    markets: Dict[str, Set[str]] = {}
    position_mode: PositionMode = Field(
        default="HEDGE",
        client_data=ClientFieldData(
            prompt=lambda mi: "Enter the position mode (HEDGE/ONEWAY): ",
            prompt_on_new=True
        ))
    twap_configs: List[TWAPExecutorConfig] = Field(
        default="binance,WLD-USDT,BUY,1,100,60,15,TAKER",
        client_data=ClientFieldData(
            prompt=lambda mi: "Enter the TWAP configurations (e.g. connector,trading_pair,side,leverage,total_amount_quote,total_duration,order_interval,mode:same_for_other_config): ",
            prompt_on_new=True))
```

- Inherits from **StrategyV2ConfigBase**, indicating it's a complex strategy capable of handling multiple trading pairs and executors.

- Initializes with a dictionary of connectors and the strategy-specific configuration (TWAPMultiplePairsConfig).

- Defines configuration parameters for executing TWAP orders, including details for multiple trading pairs, position mode, and TWAP executor configurations (twap_configs).

- Utilizes a validator to parse and validate the TWAP configurations from a string format into TWAPExecutorConfig objects, ensuring each configuration adheres to expected parameters such as connector name, trading pair, trade side, leverage, total amount in quote currency, total duration, order interval, and execution mode (e.g., MAKER or TAKER).


### Conclusion:

The `TWAPExecutor` class is designed to execute orders following a TWAP strategy, aiming to reduce market impact by distributing the execution of a large order across multiple smaller orders over time. It involves complex logic for scheduling orders, managing their lifecycle, and calculating execution performance, making it a sophisticated component within the Hummingbot trading bot framework for algorithmic trading strategies.