Add definitions for Electricity Trading API (#148)

Add some protobuf definitions necessary for the Electricity Trading (and
for Ancillary Services Market).

This folder structure is a proposal, if anyone is against it for
whatever reason, please suggest another folder structure that you would
consider better.

FYI @thomas-nicolai-frequenz @tiyash-basu-frequenz
@frequenz-floss/api-electricity-trading-team

Author: camille-bouvy-frequenz

.gitmodules

@@ -1,3 +1,3 @@
 [submodule "submodules/api-common-protos"]
 	path = submodules/api-common-protos
-	url = https://github.com/googleapis/api-common-protos.git
+	url = https://github.com/googleapis/googleapis.git

RELEASE_NOTES.md

@@ -16,7 +16,7 @@ This release:
 
 ## New Features
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+Add protobufs definition necesary for Electricity Trading (and for Ancillary Services Market). 
 
 ## Bug Fixes
 

proto/frequenz/api/common/v1/grid/delivery_duration.proto

@@ -0,0 +1,61 @@
+// Frequenz definitions of the time increment used for electricity 
+// deliveries and trading.
+//
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1.grid;
+
+import "google/protobuf/timestamp.proto";
+
+// DeliveryDuration represents the time increment, in minutes, 
+// used for electricity deliveries and trading. These durations
+// serve as the basis for defining the delivery period in contracts,
+// and they dictate how energy is scheduled and delivered to meet 
+// contractual obligations.
+//
+// !!! note "Compatibility Constraints"
+//     Not all delivery durations are universally 
+//     compatible with all delivery areas or markets.
+//
+enum DeliveryDuration {
+  // Default value, indicates that the duration is unspecified.
+  DELIVERY_DURATION_UNSPECIFIED = 0; 
+    
+  // 5-minute duration
+  DELIVERY_DURATION_5 = 1; 
+
+  // 15-minute contract duration.
+  DELIVERY_DURATION_15 = 2; 
+  
+  // 30-minute contract duration.
+  DELIVERY_DURATION_30 = 3; 
+  
+  // 1-hour contract duration.
+  DELIVERY_DURATION_60 = 4; 
+}
+
+// DeliveryPeriod represents the time period during which the contract 
+// is delivered. It is defined by a start timestamp and a duration.
+message DeliveryPeriod {
+  // Start UTC timestamp represents the beginning of the delivery period.
+  // This timestamp is inclusive, meaning that the delivery period starts
+  // from this point in time.
+  // 
+  // !!! note
+  //     Delivery period start time constraints:
+  //     - 5-minute durations must start at times that are multiples of 
+  //       5 minutes past the hour.
+  //     - 15-minute durations must start at :00, :15, :30, or 
+  //       :45 past the hour.
+  //     - 30-minute durations must start at :00 or :30 past the hour.
+  //     - 60-minute durations must start at :00 past the hour.
+  google.protobuf.Timestamp start = 1;
+
+  // The length of the delivery period.
+  DeliveryDuration duration = 2;
+}

proto/frequenz/api/common/v1/market/price.proto

@@ -0,0 +1,53 @@
+// Frequenz definitions of price for electricity trading.
+//
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1.market;
+
+import "google/type/decimal.proto";
+
+// Represents a monetary price for electricity trading, including
+// the amount and currency. The currency used should align with the
+// delivery area's standard currency.
+//
+// !!! caution "Validation Required"
+//     It's essential to ensure that the currency aligns with the 
+//     standard currency of the associated delivery area. Failure to
+//     do so may result in the API service rejecting the request due to currency
+//     mismatches.
+//
+// !!! info "Relation to Delivery Area"
+//     The currency specified is intrinsically related to the delivery area 
+//     for the contract. Make sure the chosen currency is compatible with 
+//     the delivery area's currency standards.
+//
+message Price {
+  // List of supported currencies.
+  // 
+  // !!! info "Extensibility"
+  //     New currencies can be added to this enum to support additional markets.
+  enum Currency {
+    CURRENCY_UNSPECIFIED = 0;
+    CURRENCY_USD = 1;
+    CURRENCY_CAD = 2;
+    CURRENCY_EUR = 3;
+    CURRENCY_GBP = 4;
+    CURRENCY_CHF = 5;
+    CURRENCY_CNY = 6;
+    CURRENCY_JPY = 7;
+    CURRENCY_AUD = 8;
+    CURRENCY_NZD = 9;
+    CURRENCY_SGD = 10;
+  }
+
+  // The amount of the price.
+  google.type.Decimal amount = 1; 
+
+  // The currency in which the price is denominated.
+  Currency currency = 2;
+}

py/frequenz/api/common/v1/market/__init__.py

@@ -0,0 +1,4 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""Frequenz common gRPC API and bindings."""

pyproject.toml

@@ -26,7 +26,8 @@ classifiers = [
 ]
 requires-python = ">= 3.11, < 4"
 dependencies = [
-  "googleapis-common-protos >= 1.56.2, < 2",
+  "googleapis-common-protos >= 1.56.4, < 2",
+  "googleapis-common-protos-stubs == 2.2.0",
   "grpcio >= 1.51.1, < 2",
 ]
 dynamic = ["version"]