From 34fccda7a6152342a89fa357c6aa15d580f71b45 Mon Sep 17 00:00:00 2001 From: Matthias Wende Date: Tue, 2 Jan 2024 10:21:40 +0100 Subject: [PATCH] Rename PublicOrders to PublicTrades --- .../v1/electricity_trading.proto | 118 +++++++++++------- 1 file changed, 76 insertions(+), 42 deletions(-) diff --git a/proto/frequenz/api/electricity_trading/v1/electricity_trading.proto b/proto/frequenz/api/electricity_trading/v1/electricity_trading.proto index 125b427..0667fdd 100644 --- a/proto/frequenz/api/electricity_trading/v1/electricity_trading.proto +++ b/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; }