frequenz-floss / frequenz-api-electricity-trading Goto Github PK

// Request to update an existing order for a given Gridpool.
message UpdateGridpoolOrderRequest {
  // Represents the order properties that can be updated after an order has been
  // placed. At least one of the optional fields must be set for an update to
  // take place.
  message UpdateOrder {
-   // The updated limit price at which the contract is to be traded.
+   // Optional; The updated limit price at which the contract is to be traded.
    // This is the maximum price for a BUY order or the minimum price for a SELL
    // order.
-    optional frequenz.api.common.v1.market.Price price = 2;
+   frequenz.api.common.v1.market.Price price = 2;

-   // The updated quantity of the contract being traded, specified in MWh.
+  // Optional; The updated quantity of the contract being traded, specified in MWh.
-   optional frequenz.api.common.v1.market.Energy quantity = 3;
+  frequenz.api.common.v1.market.Energy quantity = 3;

-   // Applicable for STOP_LIMIT orders. This is the updated stop price that
+   // Optional; Applicable for STOP_LIMIT orders. This is the updated stop price that
    // triggers the limit order.
-   optional frequenz.api.common.v1.market.Price stop_price = 4;
+  frequenz.api.common.v1.market.Price stop_price = 4;

-   // Applicable for ICEBERG orders. This is the updated price difference
+   // Optional; Applicable for ICEBERG orders. This is the updated price difference
    // between the peak price and the limit price.
-   optional frequenz.api.common.v1.market.Price peak_price_delta = 5;
+  frequenz.api.common.v1.market.Price peak_price_delta = 5;

-   // Applicable for ICEBERG orders. This is the updated quantity of the order
+   // Optional; Applicable for ICEBERG orders. This is the updated quantity of the order
    // to be displayed in the order book.
-   optional frequenz.api.common.v1.market.Energy display_quantity = 6;
+  frequenz.api.common.v1.market.Energy display_quantity = 6;

-   // Updated execution options such as All or None, Fill or Kill, etc.
+   // Optional; Updated execution options such as All or None, Fill or Kill, etc.
    optional OrderExecutionOption execution_option = 7;

-   // This is an updated timestamp defining the time after which the order
+   // Optional; This is an updated timestamp defining the time after which the order
    // should be cancelled if not filled. The timestamp is in UTC.
    google.protobuf.Timestamp valid_until = 8;

-    // Updated user-defined payload individual to a specific order.
+   // Optional; Updated user-defined payload individual to a specific order.
    // This can be any data that the user wants to associate with the order.
    google.protobuf.Struct payload = 9;

-   // Updated user-defined tag to group related orders.
+   // Optional; Updated user-defined tag to group related orders.
    optional string tag = 10;
  }

  // ID of the Gridpool the order belongs to.
  uint64 gridpool_id = 1;

  // The order identifier
  uint64 order_id = 2;

  // Field mask specifying which fields should be updated
  google.protobuf.FieldMask update_mask = 3;

  // The fields that can be updated
  UpdateOrder update_order_fields = 4;
}

// ... 

// Represents an order in the electricity market.
message Order {
  // The delivery area where the contract is to be delivered. The representation
  // of the delivery area may vary by jurisdiction.
  frequenz.api.common.v1.grid.DeliveryArea delivery_area = 2;

  // The delivery period for the contract, specified as a start and end
  // timestamp in UTC. It represents the period during which the contract is
  // expected to be fulfilled.
  frequenz.api.common.v1.grid.DeliveryPeriod delivery_period = 3;

  // The type of order, such as LIMIT, STOP_LIMIT, ICEBERG etc.
  // This determines how the order is to be executed in the market.
  OrderType type = 4;

  // Indicates if the order is on the Buy or Sell side of the market.
  MarketSide side = 5;

  // The limit price at which the contract is to be traded. This is the maximum
  // price for a BUY order or the minimum price for a SELL order.
  frequenz.api.common.v1.market.Price price = 6;

  // The quantity of the contract being traded, specified in MWh.
  frequenz.api.common.v1.market.Energy quantity = 7;

- // Applicable for STOP_LIMIT orders. This is the stop price that triggers the
+ // Optional; Applicable for STOP_LIMIT orders. This is the stop price that triggers the
  // limit order.
-  optional frequenz.api.common.v1.market.Price stop_price = 8;
+ frequenz.api.common.v1.market.Price stop_price = 8;

- // Applicable for ICEBERG orders. This is the price difference between the
+ // Optional; Applicable for ICEBERG orders. This is the price difference between the
  // peak price and the limit price.
- optional frequenz.api.common.v1.market.Price peak_price_delta = 9;
+ frequenz.api.common.v1.market.Price peak_price_delta = 9;

-  // Applicable for ICEBERG orders. This is the quantity of the order to be
+  // Optional; Applicable for ICEBERG orders. This is the quantity of the order to be
  // displayed in the order book.
- optional frequenz.api.common.v1.market.Energy display_quantity = 10;
+ frequenz.api.common.v1.market.Energy display_quantity = 10;

  // Optional; Execution options such as All or None, Fill or Kill, etc.
  optional OrderExecutionOption execution_option = 11;

- // Do not use if ExecutionOption is set to FOK or IOC. This is an optional UTC
+ // Optional; Do not use if ExecutionOption is set to FOK or IOC. This is an optional UTC
  // timestamp defining the time after which the order should be cancelled if
  // not filled.
- optional google.protobuf.Timestamp valid_until = 12;
+ google.protobuf.Timestamp valid_until = 12;

  // Optional user-defined payload individual to a specific order. This can be
  // any data that needs to be associated with the order.
  //
  // The field can store e.g. JSON objects containing details involved in the
  // order. This feature can simplify application development by eliminating the
  // need for complicated state management to remember the specifics of each
  // order.
  //
  // By embedding this "state" within the order itself, you can include
  // specifics like which microgrids consume or provide how much power. This
  // makes it easier to manage complex orders and can simplify the logic
  // required in applications.
  //
  // Example JSON payload:
  // {
  //   "microgrids": [
  //     {
  //       "microgrid_id": "1",
  //       "mwh": 1.0
  //     },
  //     {
  //       "microgrid_id": "2",
  //       "mwh": 0.5
  //     }
  //   ]
  // }
  //
  // In this example, if the order is exectuted, these microgrids might consume
  // the electricity mentioned in the example JSON payload.
- optional google.protobuf.Struct payload = 13;
+ google.protobuf.Struct payload = 13;

  // Optional user-defined tag to group related orders.
  optional string tag = 14;
}

// Parameters for filtering Gridpool orders.
//
// !!! note
//     Multiple filters can be used in combination to narrow down the returned
//     results. For example, you can apply both state and side filters
//     simultaneously to list only the open orders on the buy side of the
//     market.
message GridpoolOrderFilter {
-  // Optional filter for order state.
-  repeated OrderState states = 1;

  // Optional filter for order side.
-  optional MarketSide side = 2;
+  optional MarketSide side = 1;

  // Optional filter for delivery period.
-  frequenz.api.common.v1.grid.DeliveryPeriod delivery_period = 3;
+  frequenz.api.common.v1.grid.DeliveryPeriod delivery_period = 2;

  // Optional filter for delivery area.
-  frequenz.api.common.v1.grid.DeliveryArea delivery_area = 4;
+  frequenz.api.common.v1.grid.DeliveryArea delivery_area = 3;

  // Optional filters the listed orders by their associated tag.
-  optional string tag = 5;
+  optional string tag = 4;
}

  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;

    // Delivery area code of the sell side.
    frequenz.api.common.v1.grid.DeliveryArea sell_delivery_area = 3;

    // The delivery period for the contract.
    frequenz.api.common.v1.grid.DeliveryPeriod delivery_period = 4;

-   // UTC Timestamp of the last order update or matching.
-   google.protobuf.Timestamp modification_time = 5;
+   // UTC Timestamp of the trades execution time.
+   google.protobuf.Timestamp execution_time = 5;

-   // The limit price at which the contract is to be traded.
+   // The price at which the trade was executed.
    frequenz.api.common.v1.market.Price price = 6;

-   // The quantity of the contract being traded in MWh.
+   // The executed quantity of the contract traded.
    frequenz.api.common.v1.market.Energy quantity = 7;

    // Final state of the trade.
    OrderState state = 8;
  }