diff --git a/src/client/spark_command_protocol/README.md b/src/client/spark_command_protocol/README.md new file mode 100644 index 000000000..26e04279a --- /dev/null +++ b/src/client/spark_command_protocol/README.md @@ -0,0 +1,58 @@ +# Spark command protocol + +This directory owns the versioned, command-only gRPC boundary between the +standalone Spark command bridge and its generated clients. It intentionally +does not import or expose Spark's internal protobuf messages. + +Version 1 supports order entry, update, cancellation, synthetic-spread +creation, and health. It has no query or public subscription RPCs. + +Decimal values are encoded as invariant-culture strings at this boundary. +`security_id` and `order_id` are public strings; when an ID is supplied, the +bridge accepts the numeric Spark keys produced by the existing Spark APIs and +keeps their representation out of the Python gateway. + +## Security locators + +`EnterOrderRequest` supports two ways to identify its security: + +- `security_id` +- `exchange` together with `exchange_security_name` + +A request must use exactly one locator form. It must not combine +`security_id` with either named-locator field, and both named-locator fields +are required when that form is used. The bridge resolves the named form +case-insensitively against its live Spark security cache before submitting the +order. Existing `security_id` clients remain wire-compatible. + +For example, a named-security limit order uses these protocol fields: + +```text +client_order_id: "strategy-a-0001" +account: "ACC A" +exchange: "okx" +exchange_security_name: "SOL-USDC" +side: SIDE_BUY +order_type: ORDER_TYPE_LIMIT +quantity: "2" +price: "100.25" +``` + +`SyntheticLeg` uses the same mutually exclusive locator rule for each leg of +`CreateSyntheticSpreadRequest`. + +## Regenerating bindings + +The bridge project generates its C# service types during `dotnet build`. Refresh +the committed Python bindings whenever `spark_command.proto` changes: + +```sh +python -m grpc_tools.protoc \ + -I src/client/spark_command_protocol \ + --python_out=src/client/spark_command_client/src/spark_command_client/generated \ + --grpc_python_out=src/client/spark_command_client/src/spark_command_client/generated \ + src/client/spark_command_protocol/spark_command.proto +sed -i \ + 's/^import spark_command_pb2 as spark__command__pb2$/from . import spark_command_pb2 as spark__command__pb2/' \ + src/client/spark_command_client/src/spark_command_client/generated/spark_command_pb2_grpc.py +``` diff --git a/src/client/spark_command_protocol/spark_command.proto b/src/client/spark_command_protocol/spark_command.proto new file mode 100644 index 000000000..f20d42d7d --- /dev/null +++ b/src/client/spark_command_protocol/spark_command.proto @@ -0,0 +1,126 @@ +syntax = "proto3"; + +package spark.command.v1; +option csharp_namespace = "Spark.Command.V1"; + +service SparkCommandService { + rpc EnterOrder(EnterOrderRequest) returns (OrderResult); + rpc UpdateOrder(UpdateOrderRequest) returns (OrderResult); + rpc DeleteOrder(DeleteOrderRequest) returns (OrderResult); + rpc CreateSyntheticSpread(CreateSyntheticSpreadRequest) + returns (CreateSyntheticSpreadResult); + rpc Health(HealthRequest) returns (HealthResult); +} + +enum Side { + SIDE_UNSPECIFIED = 0; + SIDE_BUY = 1; + SIDE_SELL = 2; +} + +enum OrderType { + ORDER_TYPE_UNSPECIFIED = 0; + ORDER_TYPE_MARKET = 1; + ORDER_TYPE_LIMIT = 2; +} + +enum CommandStatus { + COMMAND_STATUS_UNSPECIFIED = 0; + COMMAND_STATUS_ACCEPTED = 1; + COMMAND_STATUS_REJECTED = 2; + COMMAND_STATUS_UNKNOWN = 3; +} + +enum PriceCalculation { + PRICE_CALCULATION_STANDARD = 0; + PRICE_CALCULATION_NET_CHANGE = 1; + PRICE_CALCULATION_NOTIONAL_LEG = 2; +} + +enum HedgePricing { + HEDGE_PRICING_CACHED_DRIVERS = 0; + HEDGE_PRICING_RECALCULATE_CROSSES = 1; +} + +enum SpreaderType { + SPREADER_TYPE_REQUOTE = 0; + SPREADER_TYPE_REVERSE_HEDGE = 1; + SPREADER_TYPE_SNIPER = 2; +} + +enum MarketDataType { + MARKET_DATA_TYPE_MERGED = 0; + MARKET_DATA_TYPE_DIRECT = 1; +} + +message EnterOrderRequest { + string client_order_id = 1; + string account = 2; + string security_id = 3; + Side side = 4; + OrderType order_type = 5; + string quantity = 6; + optional string price = 7; + optional string exchange = 8; + optional string exchange_security_name = 9; +} + +message UpdateOrderRequest { + string order_id = 1; + optional string quantity = 2; + optional string price = 3; +} + +message DeleteOrderRequest { + string order_id = 1; +} + +message OrderResult { + string order_id = 1; + CommandStatus status = 2; + string message = 3; + string spark_error = 4; +} + +message SyntheticLeg { + string security_id = 1; + optional string quantity = 2; + optional string price_multiplier = 3; + optional string leg_delta = 4; + optional Side side = 5; + optional bool is_active_quoting = 6; + optional bool enable_hedging = 7; + optional MarketDataType market_data_type = 8; + optional string exchange = 9; + optional string exchange_security_name = 10; +} + +message CreateSyntheticSpreadRequest { + SyntheticLeg leg1 = 1; + SyntheticLeg leg2 = 2; + optional string name = 3; + optional string symbol = 4; + optional string currency = 5; + optional string tick_size = 6; + optional string cash_per_point = 7; + optional string price_multiplier = 8; + optional uint32 main_fraction = 9; + optional uint32 sub_fraction = 10; + optional uint32 price_display_format = 11; + optional PriceCalculation price_calculation = 12; + optional bool cancel_hedges_on_cancel = 13; + optional HedgePricing hedge_pricing = 14; + optional SpreaderType spreader_type = 15; + optional string lean_quantity_ratio = 16; +} + +message CreateSyntheticSpreadResult { + string security_id = 1; +} + +message HealthRequest {} + +message HealthResult { + bool ready = 1; + string message = 2; +}