Rename PublicOrders to PublicTrades

proto/frequenz/api/electricity_trading/v1/electricity_trading.proto

@@ -53,13 +53,13 @@ service ElectricityTradingService {
   rpc ReceiveGridpoolOrdersStream(ReceiveGridpoolOrdersStreamRequest)
       returns (stream ReceiveGridpoolOrdersStreamResponse);
 
-  // Lists all public executed historic orders (trades).
-  rpc ListPublicOrders(ListPublicOrdersRequest)
-      returns (ListPublicOrdersResponse);
+  // Lists all historic public trades.
+  rpc ListPublicTrades(ListPublicTradesRequest)
+      returns (ListPublicTradesResponse);
 
-  // Stream all executed public orders (trades).
-  rpc ReceivePublicOrdersStream(ReceivePublicOrdersStreamRequest)
-      returns (stream ReceivePublicOrdersStreamResponse);
+  // Stream all historic public trades.
+  rpc ReceivePublicTradesStream(ReceivePublicTradesStreamRequest)
+      returns (stream ReceivePublicTradesStreamResponse);
 }
 
 // OrderExecutionOption defines specific behavior for the execution of an order.
@@ -180,6 +180,17 @@ enum OrderState {
   // RECALL: The order has been recalled. This could be due to a system issue or
   // a request from the market participant or market operator.
   ORDER_STATE_RECALL = 10;
+
+  // RECALL_REQUESTED: A recall request for the order has been submitted but the
+  // order is not yet removed from the order book.
+  ORDER_STATE_RECALL_REQUESTED = 11;
+
+  // RECALL_REJECTED: The order recall request was rejected, likely due to it
+  // having already been filled or expired.
+  ORDER_STATE_RECALL_REJECTED = 12;
+
+  // APPROVAL: The order has been sent for approval.
+  ORDER_STATE_APPROVAL = 13;
 }
 
 // Represents an order in the electricity market.
@@ -326,14 +337,27 @@ message OrderDetail {
   google.protobuf.Timestamp modification_time = 7;
 }
 
-// Represents a public order in the market.
+// Represents a public trade in the market.
 //
-// Each PublicOrder within this response message represents an order that was
-// previously active in the public order book, along with its key attributes and
-// final state.
-message PublicOrder {
-  // ID of the order from the public order book.
-  uint64 public_order_id = 1;
+// Each `trade` within this response message represents two orders that were
+// previously active in the public order book and matched, along with its key
+// attributes and final state.
+//
+// !!! note
+//      A `trade` refers to the event where a buy order and a sell order are
+//      matched and executed, representing the final state of those orders.
+//      While "executed" or "filled" orders pertain to the completion of
+//      individual buy or sell orders, a "trade" signifies the actual
+//      transaction where both types of orders (buy and sell) are successfully
+//      matched and carried out. This distinction is crucial, as a trade is the
+//      broader occurrence resulting from the execution of both sides of the
+//      transaction, although post-trade processes like settlement may still
+//      follow. The term 'trade' is sometimes used interchangeably with
+//      'executed order' in trading platforms, but it technically encompasses
+//      the completion of both a buy and a sell order.
+message PublicTrade {
+  // ID of the trade from the public order book.
+  uint64 id = 1;
 
   // Delivery area code of the buy side.
   frequenz.api.common.v1.grid.DeliveryArea buy_delivery_area = 2;
@@ -353,7 +377,7 @@ message PublicOrder {
   // The quantity of the contract being traded in MWh.
   frequenz.api.common.v1.market.Energy quantity = 7;
 
-  // State of the order.
+  // Final state of the trade.
   OrderState state = 8;
 }
 
@@ -381,18 +405,28 @@ message GridpoolOrderFilter {
   optional string tag = 5;
 }
 
-// Parameters for filtering the historic, publicly executed orders (trades).
-message PublicOrderFilter {
-  // If set, only orders in this state are returned.
+// Parameters for filtering historic public trades.
+//
+// !!! note
+//     In some countries or regions the buy and sell delivery area can be
+//     different. This is usually referred to as cross bid.
+//
+// !!! note
+//     Multiple filters can be used in combination to narrow down the returned
+//     results. For example, you can apply both state and delivery area filters
+//     simultaneously to list only the trades that occurred at a certain time in
+//     a specific delivery area.
+message PublicTradeFilter {
+  // If set, only trades in this state are returned.
   repeated OrderState states = 1;
 
-  // If set, only orders with this delivery period are returned.
+  // If set, only trades with this delivery period are returned.
   optional frequenz.api.common.v1.grid.DeliveryPeriod delivery_period = 2;
 
-  // If set, only orders in this buy delivery area are returned.
+  // If set, only trades in this buy delivery area are returned.
   optional frequenz.api.common.v1.grid.DeliveryArea buy_delivery_area = 3;
 
-  // If set, only orders in this sell delivery area are returned.
+  // If set, only trades in this sell delivery area are returned.
   optional frequenz.api.common.v1.grid.DeliveryArea sell_delivery_area = 4;
 }
 
@@ -590,41 +624,41 @@ message ReceiveGridpoolOrdersStreamResponse {
   OrderDetail order_detail = 1;
 }
 
-// Request to list all executed public orders with optional filters.
+// Request to list all historic public trades with optional filters.
 // This method allows for querying historical data, useful for various analytics
 // tasks.
-message ListPublicOrdersRequest {
-  // Optional filter to narrow down the list of public orders.
-  PublicOrderFilter filter = 1;
+message ListPublicTradesRequest {
+  // Optional filter to narrow down the list of trades.
+  PublicTradeFilter filter = 1;
 
   // Pagination parameters.
   frequenz.api.common.v1.pagination.PaginationParams pagination_params = 3;
 }
 
-// ListPublicOrdersResponse is a message that contains a list of historic
-// executed public orders. This dataset is vital for tasks such as training
-// machine learning models, backtesting trading strategies, and conducting
-// market analysis.
-message ListPublicOrdersResponse {
-  // List of all public orders that met the specified filtering criteria.
-  repeated PublicOrder public_order_lists = 1;
+// ListPublicTradesResponse is a message that contains a list of historic public
+// trades.
+// This dataset is vital for tasks such as training machine learning models,
+// backtesting trading strategies, and conducting market analysis.
+message ListPublicTradesResponse {
+  // List of all public trades that met the specified filtering criteria.
+  repeated PublicTrade public_trade_lists = 1;
 
   // Metadata for pagination, including token for next page to retrieve.
   frequenz.api.common.v1.pagination.PaginationInfo pagination_info = 2;
 }
 
-// Subscribe to public order stream.
-// This method provides real-time updates on newly executed public orders,
-// making it useful for dynamic analytics and real-time decision-making.
-message ReceivePublicOrdersStreamRequest {
-  // Optional filter to specify which orders should be included in the stream.
-  PublicOrderFilter filter = 1;
+// Subscribe to the stream of public trades.
+// This method provides real-time updates on newly executed public trades,
+// making it useful dynamic analytics and real-time decision-making.
+message ReceivePublicTradesStreamRequest {
+  // Optional filter to specify which trades should be included in the stream.
+  PublicTradeFilter filter = 1;
 }
 
-// Response to a subscription request for a stream of public orders.
-// Real-time information on public orders is pushed through this response.
-message ReceivePublicOrdersStreamResponse {
-  // The public order that has been executed and is being broadcasted in
+// Response to a subscription request for a stream of public trades.
+// Real-time information on public trades is pushed through this response.
+message ReceivePublicTradesStreamResponse {
+  // The public trade that has been executed and is being broadcasted in
   // real-time.
-  PublicOrder public_order = 1;
+  PublicTrade public_trade = 1;
 }