feat: add Blotter system for trade documentation and order book management

- Add Blotter ABC with place_order, cancel_order, batch_order, and transaction recording
- Add SimulationBlotter with configurable slippage and commission models
- Add SlippageModel (NoSlippage, PercentageSlippage, FixedSlippage)
- Add CommissionModel (NoCommission, PercentageCommission, FixedCommission)
- Add Transaction data class for trade documentation
- Integrate blotter into App (set_blotter/get_blotter) and Context (batch_order/get_transactions)
- Add 43 unit tests

Closes #457

Author: MDUYN

investing_algorithm_framework/__init__.py

@@ -24,7 +24,10 @@
     APPLICATION_DIRECTORY, DataSource, OrderExecutor, PortfolioProvider, \
     SnapshotInterval, AWS_S3_STATE_BUCKET_NAME, BacktestEvaluationFocus, \
     save_backtests_to_directory, BacktestMetrics, DATA_DIRECTORY, \
-    retag_backtests
+    retag_backtests, \
+    Blotter, SimulationBlotter, Transaction, \
+    SlippageModel, NoSlippage, PercentageSlippage, FixedSlippage, \
+    CommissionModel, NoCommission, PercentageCommission, FixedCommission
 from .infrastructure import AzureBlobStorageStateHandler, \
     CSVOHLCVDataProvider, CSVTickerDataProvider, CSVURLDataProvider, \
     JSONURLDataProvider, ParquetURLDataProvider, \
@@ -229,5 +232,16 @@
     "download_v2",
     "DownloadResult",
     "create_data_storage_path",
-    "DATA_DIRECTORY"
+    "DATA_DIRECTORY",
+    "Blotter",
+    "SimulationBlotter",
+    "Transaction",
+    "SlippageModel",
+    "NoSlippage",
+    "PercentageSlippage",
+    "FixedSlippage",
+    "CommissionModel",
+    "NoCommission",
+    "PercentageCommission",
+    "FixedCommission",
 ]

investing_algorithm_framework/app/app.py

@@ -71,10 +71,16 @@ def __init__(self, state_handler=None, name=None):
         self._state_handler = state_handler
         self._run_history = None
         self._name = name
+        self._blotter = None
 
     @property
     def context(self):
-        return self.container.context()
+        ctx = self.container.context()
+
+        if self._blotter is not None:
+            ctx._blotter = self._blotter
+
+        return ctx
 
     @property
     def resource_directory_path(self):
@@ -2207,6 +2213,39 @@ def add_market(
         )
         self.add_market_credential(market_credential)
 
+    def set_blotter(self, blotter):
+        """
+        Set a blotter for order book management. The blotter sits
+        between the strategy and the order execution layer, enabling
+        batch ordering, transaction tracking, and custom order routing.
+
+        Args:
+            blotter: Instance of Blotter
+
+        Returns:
+            None
+        """
+        from investing_algorithm_framework.domain.blotter import Blotter
+
+        if inspect.isclass(blotter):
+            blotter = blotter()
+
+        if not isinstance(blotter, Blotter):
+            raise OperationalException(
+                "Blotter should be an instance of Blotter"
+            )
+
+        self._blotter = blotter
+
+    def get_blotter(self):
+        """
+        Get the configured blotter.
+
+        Returns:
+            Blotter or None: The configured blotter instance.
+        """
+        return self._blotter
+
     def add_order_executor(self, order_executor):
         """
         Function to add an order executor to the app. The order executor

investing_algorithm_framework/app/context.py

@@ -50,6 +50,7 @@ def __init__(
             trade_stop_loss_service
         self.trade_take_profit_service: TradeTakeProfitService = \
             trade_take_profit_service
+        self._blotter = None
 
     def _validate_target_symbol(self, target_symbol, market=None):
         """
@@ -2196,3 +2197,111 @@ def run_strategy(self, context, data):
             self._parquet_url_providers[url] = provider
 
         return self._parquet_url_providers[url].get_data()
+
+    def batch_order(self, orders, market=None):
+        """
+        Place multiple orders at once.
+
+        If a blotter is configured (via ``app.set_blotter()``), the
+        orders are routed through the blotter. Otherwise, orders are
+        created directly.
+
+        Each order dict supports the same parameters as
+        ``create_limit_order`` and ``create_market_order``.
+
+        Args:
+            orders (list[dict]): List of order dicts. Each dict should
+                contain at minimum ``target_symbol``, ``order_side``,
+                and either ``amount`` or ``percentage_of_portfolio``.
+                Include ``price`` for limit orders.
+                Include ``order_type`` to specify MARKET orders
+                (default is LIMIT).
+            market (str, optional): Default market for all orders.
+                Can be overridden per order.
+
+        Returns:
+            list[Order]: The created orders.
+
+        Example::
+
+            context.batch_order([
+                {
+                    "target_symbol": "BTC",
+                    "order_side": OrderSide.BUY,
+                    "percentage_of_portfolio": 5.0,
+                    "price": 45000,
+                },
+                {
+                    "target_symbol": "ETH",
+                    "order_side": OrderSide.BUY,
+                    "percentage_of_portfolio": 3.0,
+                    "price": 3000,
+                },
+            ])
+        """
+        if self._blotter is not None:
+            # Add default market to each order if not set
+            for order_data in orders:
+                if "market" not in order_data and market is not None:
+                    order_data["market"] = market
+
+            return self._blotter.batch_order(orders, self)
+
+        # Default: create orders directly
+        results = []
+
+        for order_data in orders:
+            order_market = order_data.get("market", market)
+            order_type = order_data.get("order_type", OrderType.LIMIT.value)
+
+            if OrderType.MARKET.equals(order_type):
+                order = self.create_market_order(
+                    target_symbol=order_data["target_symbol"],
+                    order_side=order_data["order_side"],
+                    amount=order_data.get("amount"),
+                    percentage_of_portfolio=order_data.get(
+                        "percentage_of_portfolio"
+                    ),
+                    percentage_of_position=order_data.get(
+                        "percentage_of_position"
+                    ),
+                    precision=order_data.get("precision"),
+                    market=order_market,
+                    metadata=order_data.get("metadata"),
+                )
+            else:
+                order = self.create_limit_order(
+                    target_symbol=order_data["target_symbol"],
+                    price=order_data["price"],
+                    order_side=order_data["order_side"],
+                    amount=order_data.get("amount"),
+                    percentage_of_portfolio=order_data.get(
+                        "percentage_of_portfolio"
+                    ),
+                    percentage_of_position=order_data.get(
+                        "percentage_of_position"
+                    ),
+                    precision=order_data.get("precision"),
+                    market=order_market,
+                    metadata=order_data.get("metadata"),
+                )
+
+            results.append(order)
+
+        return results
+
+    def get_transactions(self):
+        """
+        Get all recorded transactions from the blotter.
+
+        Returns a list of Transaction objects representing all
+        fills/executions that have been processed through the blotter.
+
+        Returns:
+            list[Transaction]: Recorded transactions, or an empty
+                list if no blotter is configured.
+        """
+        if self._blotter is not None:
+            return self._blotter.get_transactions()
+
+        return []

investing_algorithm_framework/domain/__init__.py

@@ -25,6 +25,9 @@
     TakeProfitRule, StopLossRule, PositionSize, ScalingRule, TradingCost
 from .order_executor import OrderExecutor
 from .portfolio_provider import PortfolioProvider
+from .blotter import Blotter, SimulationBlotter, Transaction, \
+    SlippageModel, NoSlippage, PercentageSlippage, FixedSlippage, \
+    CommissionModel, NoCommission, PercentageCommission, FixedCommission
 from .services import MarketCredentialService, AbstractPortfolioSyncService, \
     RoundingService, StateHandler
 from .stateless_actions import StatelessActions
@@ -152,4 +155,15 @@
     "save_backtests_to_directory",
     "retag_backtests",
     "generate_algorithm_id",
+    "Blotter",
+    "SimulationBlotter",
+    "Transaction",
+    "SlippageModel",
+    "NoSlippage",
+    "PercentageSlippage",
+    "FixedSlippage",
+    "CommissionModel",
+    "NoCommission",
+    "PercentageCommission",
+    "FixedCommission",
 ]