Split OrderState into OrderState and TradeState

[thomas-nicolai-frequenz]

What's needed?

Currently OrderState is used to also return the state of a trade. This might be confusing to understand. There are two solutions to the problem. One is to seperate the state of orders and trades or to rename OrderState to just State.

Proposed solution

Remove the trade statuses from OrderState and create a new TradeState message.

// Enum for the state of an order.
enum TradeState {
  // UNSPECIFIED: The state is not known.
  TRADE_STATE_UNSPECIFIED = 0;

  // ACTIVE: The trade has been executed in the market.
  TRADE_STATE_ACTIVE = 1;

  // CANCEL_REQUESTED: A cancellation request for the trade has been submitted.
  ORDER_STATE_CANCEL_REQUESTED = 2;

  // CANCEL_REJECTED: The trade cancellation request was rejected.
  ORDER_STATE_CANCEL_REJECTED = 3;

  // CANCELED: The trade has been cancelled. This can occur due to a
  // cancellation request by the market participant, system, or market operator.
  TRADE_STATE_CANCELED = 4;

  // RECALL: The trade has been recalled. This could be due to a system issue or
  // a request from the market participant or market operator.
  TRADE_STATE_RECALLED = 5;

  // RECALL_REQUESTED: A recall request for the trade has been submitted.
 TRADE_STATE_RECALL_REQUESTED = 6;

  // RECALL_REJECTED: The trade recall request was rejected.
  TRADE_STATE_RECALL_REJECTED = 7; 

  // APPROVAL: An approval has been requested.
  ORDER_STATE_APPROVAL_REQUESTED = 8;
}

Here is also an updated OrderStatus enum:

// Enum for the state of an order.
enum OrderState {
  // UNSPECIFIED: The order state is not known. This is usually the default
  // state of a newly created order object before any operations have been
  // applied.
  ORDER_STATE_UNSPECIFIED = 0;

  // PENDING: The order has been sent to the marketplace but has not yet been
  // confirmed. This can be due to awaiting validation or system processing.
  ORDER_STATE_PENDING = 1;

  // ACTIVE: The order has been confirmed and is open in the market.
  // It may be unfilled or partially filled.
  ORDER_STATE_ACTIVE = 2;

  // HIBERNATE: The order has been entered into the system but is not currently
  // exposed to the market. This could be due to certain conditions not yet
  // being met.
  ORDER_STATE_HIBERNATE = 3;

  // FILLED: The order has been completely filled and there are no remaining
  // quantities on the order.
  ORDER_STATE_FILLED = 4;

  // CANCELED: The order has been cancelled. This can occur due to a
  // cancellation request by the market participant, system, or market operator.
  ORDER_STATE_CANCELED = 5;

  // CANCEL_REQUESTED: A cancellation request for the order has been submitted
  // but the order is not yet removed from the order book.
  ORDER_STATE_CANCEL_REQUESTED = 6;

  // CANCEL_REJECTED: The order cancellation request was rejected, due to
  // it having already been filled or expired.
  ORDER_STATE_CANCEL_REJECTED = 7;

  // EXPIRED: The order has not been filled within the defined duration and has
  // expired.
  ORDER_STATE_EXPIRED = 8;

  // FAILED: The order submission failed and was unable to be placed on the
  // order book, usually due to a validation error or system issue.
  ORDER_STATE_FAILED = 9;
}

Use cases

No response

Alternatives and workarounds

Rename OrderState to just State

Additional context

No response

[thomas-nicolai-frequenz]

Here is an example of where OrderState is used to report the state of a trade.

frequenz-api-electricity-trading/proto/frequenz/api/electricity_trading/v1/electricity_trading.proto

Line 381 in f5768a1

OrderState state = 8;

The following change would need to be applied too:

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;

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

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

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

[camille-bouvy-frequenz]

I like the idea or separating the state of orders and trades better than the renaming into a single State, as there are some states in orders that don't apply to trades (e.g. pending)

[cwasicki]

I also support the separation. About the state fields I am missing background. Is there some documentation related to this?

[matthias-wende-frequenz]

Looks good to me as well. Is there anything more to discuss or can we pull that change in?

[thomas-nicolai-frequenz]

Is there anything more to discuss or can we pull that change in?

Move fast, break things...