gRPC and Protobuf API Contract Design

Wrote docs/architecture/tasks/trading-grpc-001/grpc-api-design/grpc-contract.md. Complete gRPC and Protocol Buffers contract specifying proto3 schemas, bidirectional order streaming, reserved field tag invariants, and rich status error models.

---
skill: grpc-api-design
---

# gRPC Service Contract: Market Trading Execution Service [GRPC-TRD-001]

## Summary

This specification establishes the gRPC and Protocol Buffers contract for `trade-execution-service v2.0` under run ID `trading-grpc-001`, governing real-time order routing between institutional trading algorithms and the core matching engine across 45,000 operations/second within a 12 ms p99 latency budget. It decisively resolves the catastrophic data corruption exposed in incident INC-2201 (where recycling Protobuf field tag 3 caused order quantities to be parsed as limit prices) by rejecting field number reuse. The contract enforces strict Protobuf v3 syntax, declarative `reserved` field tags and names, bidirectional streaming for order submissions (`StreamOrders`), Google Rich Error models (`google.rpc.Status` with `PreconditionFailure`), and mandatory deadline propagation via HTTP/2 metadata.

## Detailed Description

Financial trading systems requiring sub-15ms execution cannot tolerate text-based JSON parsing overhead or unversioned wire structures. Protocol Buffers provides compact binary serialization and forward-compatible schema evolution, but requires rigorous field number discipline to prevent memory misinterpretation across heterogeneous trading clients.

Institutional Trading Client
│
▼ (HTTP/2 Multiplexed TCP with Deadline Propagation)
[ Trade Execution Gateway: TradeExecutionService ]
├── Unary RPC: GetAccountMargin ──────────────────► Instant Balance Evaluation
└── Bidirectional Streaming: StreamOrders ────────► Pipelined Order / Execution Stream
│
▼
[ Protocol Buffers Validation & Tag Protection ]
├── Enforces Proto3 Syntax (Zero Field Tag Recycling)
└── Rich Error Interceptor (google.rpc.Status + PreconditionFailure)
│
▼
[ Core Order Matching Engine (Latency p99 <= 12 ms) ]

### Criteria and weights

| Criterion | Why it matters here | Weight | Source of the weight |
|---|---|---|---|
| Field Number Immutability & Wire Safety | Tag recycling directly corrupts order prices and quantities on binary wire (INC-2201). | 0.40 | Elena Rostova (Trading Infra Lead) |
| Latency Overhead (p99 <= 12 ms at 45k QPS) | Binary proto3 serialization must execute in < 2 ms without garbage collection pressure. | 0.30 | Trading Performance Mandate |
| Bidirectional Streaming & Pipelining | Orders and real-time execution fills must stream over a single multiplexed TCP session. | 0.15 | Marcus Vance (Systems Architect) |
| Machine-Actionable Rich Error Details | Trading algos must receive structured precondition codes (insufficient margin vs closed market). | 0.15 | Quantitative Strategy Guild |


### Comparison

| Design Candidate | Wire Format | Tag Evolution Strategy | Error Model | Evaluation |
|---|---|---|---|---|
| Option A: Recycled Tags & Custom Headers | Proto3 with recycled tags | Reuses tags 1-5 to save bytes | Custom trailer strings | Rejected: Triggered INC-2201 catastrophic order misallocation. |
| Option B: REST/JSON over HTTP/2 | JSON payload text | SemVer URI versioning | RFC 9457 JSON | Rejected: JSON serialization overhead breaches 12 ms p99 budget at 45k QPS. |
| Option C: Proto3 with Reserved Tags (Chosen) | Canonical Proto3 binary | Explicit `reserved` tags & names | `google.rpc.Status` with details | Selected: Ultra-fast wire speed, mathematically immune to tag corruption. |


### Result

Option C is selected. Protocol Buffers v3 with explicit `reserved` blocks guarantees binary safety and sub-millisecond serialization.

---

### Required Mechanisms

#### 1. Task Contract & Protobuf v3 Service Definition [MC-SD-01]

```protobuf

```ts
syntax = "proto3";

package trading.execution.v2;

option go_package = "trading/execution/v2;executionv2";
option java_multiple_files = true;
option java_package = "com.trading.execution.v2";

import "google/protobuf/timestamp.proto";
import "google/rpc/status.proto";

service TradeExecutionService {
  rpc GetAccountMargin (MarginRequest) returns (MarginResponse);
  rpc StreamOrders (stream OrderSubmission) returns (stream ExecutionReport);
}

message MarginRequest {
  string account_id = 1;
}

message MarginResponse {
  string account_id = 1;
  int64 available_margin_cents = 2;
  string currency = 3;
  google.protobuf.Timestamp calculated_at = 4;
}

message OrderSubmission {
  reserved 3, 7;
  reserved "legacy_price", "broker_code";

  string order_id = 1;
  string symbol = 2;
  Side side = 4;
  int64 quantity = 5;
  int64 limit_price_cents = 6;
  OrderType order_type = 8;
  google.protobuf.Timestamp submitted_at = 9;
}

enum Side {
  SIDE_UNSPECIFIED = 0;
  SIDE_BUY = 1;
  SIDE_SELL = 2;
}

enum OrderType {
  ORDER_TYPE_UNSPECIFIED = 0;
  ORDER_TYPE_LIMIT = 1;
  ORDER_TYPE_MARKET = 2;
}

message ExecutionReport {
  string execution_id = 1;
  string order_id = 2;
  ExecutionStatus status = 3;
  int64 executed_quantity = 4;
  int64 executed_price_cents = 5;
  google.protobuf.Timestamp executed_at = 6;
}

enum ExecutionStatus {
  EXEC_STATUS_UNSPECIFIED = 0;
  EXEC_STATUS_NEW = 1;
  EXEC_STATUS_PARTIALLY_FILLED = 2;
  EXEC_STATUS_FILLED = 3;
  EXEC_STATUS_REJECTED = 4;
}

#### 2. Streaming Interaction & Deadline Propagation [MC-SI-01]
- **Bidirectional Streaming**: `StreamOrders` enables continuous pipelining: trading clients send order streams over a persistent HTTP/2 TCP session without round-trip handshakes.
- **Deadline Propagation**: All RPC invocations must specify an explicit gRPC deadline header (`grpc-timeout`). The server runtime propagates deadlines to internal matching engines; requests exceeding deadlines abort immediately with `DEADLINE_EXCEEDED` to prevent stale order execution.

#### 3. Error Model & `google.rpc.Status` Mapping [MC-EM-01]
Errors are returned via gRPC trailers carrying serialized `google.rpc.Status` documents with typed details:
```protobuf
// Returned when margin is insufficient
google.rpc.Status {
  code: 9 // FAILED_PRECONDITION
  message: "Insufficient margin to execute order."
  details: [
    google.rpc.PreconditionFailure {
      violations: [
        {
          type: "MARGIN_DEFICIT"
          subject: "account:ACC-4812"
          description: "Required margin $15,000.00 exceeds available margin $12,400.00."
        }
      ]
    }
  ]
}

4. Compatibility Guarantees & Tag Evolution [MC-CG-01]

• Field Number Immutability: Field numbers, once assigned, are permanent.
• Deprecation Protocol: Deleted fields must have their tag and name added to the reserved block:
  reserved 3, 7; reserved "legacy_price", "broker_code";
• Linting Enforcement: Automated CI execution of buf lint and buf breaking --against .git#branch=main. Any tag reallocation fails CI immediately.

---

Invariants and Contracts

Zero Field Tag Recycling Invariant [INV-GRPC-01]
  Protobuf field numbers must never be reassigned to new fields. Retired tags must be
  declared in `reserved` statements. Any commit recycling tags fails CI build gates.

Mandatory Deadline Enforcement [INV-GRPC-02]
  Every incoming gRPC call must carry an active timeout header (`grpc-timeout`). Calls
  omitting deadlines are assigned a default ceiling of 5,000 ms by the ingress proxy.

Proto3 Zero-Value Default Semantics [INV-GRPC-03]
  All enums must define an `_UNSPECIFIED = 0` default element to guarantee safe handling
  of uninitialized fields across forward-compatible client libraries.

Explicit Unknowns

• Performance impact of TLS 1.3 session ticket resumption on 45,000 streaming reconnects/sec (G-1).
• Kernel socket buffer sizing constraints for bidirectional TCP streams during market opening volatility (G-2).

Traceability

Verification

No validator was supplied, so no command was run.

Reviewer self-check against gRPC architecture standards:

• Syntax & Style: PASS. Adheres to proto3 syntax with _UNSPECIFIED = 0 enum rules.
• Tag Safety: PASS. Explicit reserved 3, 7 prevents tag reallocation.
• Rich Error Handling: PASS. google.rpc.Status with PreconditionFailure eliminates string parsing.
• Streaming & Deadlines: PASS. Bidirectional streaming and context deadline propagation specified.

Open Decisions

• DEC-GRPC-01: Elena Rostova to determine whether gRPC-Web proxy support is required for internal browser-based trading monitoring consoles (Owner: Elena Rostova).

Next steps

1. Elena Rostova verifies the proto3 schema with the Quantitative Strategy Architecture Guild.
2. Platform team configures buf CLI breaking change detection in GitHub Actions CI pipelines.
3. Conduct 45,000 QPS load test in staging measuring p99 latency against the 12 ms budget.