feat: add versioned Spark command protocol

This commit is contained in:
arham committed 2026-09-30 06:49:31 +00:00
1 parent 4614b60218
commit 8ba8d55bc2
2 files changed
+184

No files matched your search

@@ -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
```
@@ -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;
}