Bridge
ExecutorWorkerBase<TState> is the bridge between an
IExecutor<TState, RichTradeAction, TradeEvent> and the WorkManager's
worker contract (IWorker.ProcessAsync(CloudEvent input, IWorkerContext context)).
Topic binding
Bind to one topic per scenario the executor serves:
sc.<scenarioid>.trading.order.submitted
Not a wildcard -- the deployed Dapr pubsub component is Redis Streams,
which has no wildcard subscription support. A worker instance MAY list
multiple such topics (CreateWorkerRequest.topics) if one executor
serves multiple scenarios (it carries no scenario-specific state, so
this is safe for e.g. SimulatedExecutor); a live executor should only
ever bind sc.LIVE.trading.order.submitted.
Dispatch
flowchart TD
E[CloudEvent] --> T{ce-type?}
T -->|"com.virtufin.trading.order.submitted"| DEC["OrderSubmittedJson.ToTradeAction"]
DEC --> EXE["Executor.ExecuteAsync(state, action)"]
EXE --> ENC["TradeEventJson.ToOutgoing"]
ENC --> RESP[response CloudEvent]
T -->|other| N[ignored]
- Anything but an "Order submitted" event is ignored (no response) -- a defensive check; in practice a worker only ever receives what it subscribed to, but nothing guarantees the topic never carries anything else.
OrderSubmittedJson.ToTradeAction(Virtufin.Trading.Contracts) parses the pubsub-topics spec's "Order submitted" payload (order_id,symbol,side,type,qty,price?,venue,submitted_at) into aRichTradeAction. The submitting strategy's id is carried when the strategy sent it (Guid.Emptyotherwise); the latency budget isn't part of the wire payload and is zero.IExecutor.ExecuteAsyncis the actual fill/routing logic -- everything upstream and downstream of this call is generic bridge plumbing, common to every executor.TradeEventJson.ToOutgoingmaps the resultingTradeEventcase to its Trade Lifecycle Events payload, topic,ce-typeandce-subject. Only the cases reachable from one action-in/event-out call are mapped (OrderPlaced-> "Order accepted",FillReceived-> "Order filled",OrderCanceled,OrderExpired,OrderRejected-> "Order rejected") -- the rest throwNotSupportedExceptionrather than silently mis-route.
The fill payload
Every producer of order.filled writes the same payload
(TradeEventJson.FillPayload; a venue user-data translator such as
BinanceOrderUpdates uses it too):
| Field | Type | Value |
|---|---|---|
fill_id |
string (UUID) | TradeEventJson.FillId(order_id): the version 5 UUID of the order id, one per order |
qty_filled |
number | the filled quantity (cumulative, for a venue report), wire precision 8 |
price |
number | the fill price (the average, for a cumulative fill), wire precision 8 |
fees |
object or null | what the venue charged, per asset ({"BNB":0.02000000,"BTC":0.00050000}); {} when nothing was charged (a simulated fill); null only when the fee is unknown (FillFees, Virtufin.Trading.Contracts) |
remaining_qty |
number | 0 (the base drives full-fill executors today) |
filled_at |
string (RFC 3339) | when the fill happened, UTC |
Amounts are JSON numbers at the wire precision with a fixed scale
(0.001 is 0.00100000), so the same fill serializes identically whichever
path built it; the shared executor conformance vectors compare numbers
numerically across languages.
Response routing
Unlike a typical WorkerBase worker (which publishes on
CloudEvent.Type, overridable per message via replytopic), the
trading envelope keeps ce-type fixed at the event's own stable
identifier (e.g. com.virtufin.trading.order.filled) regardless of any
inbound override -- it's meant to be a stable identifier per the
pubsub-topics spec, independent of the per-scenario topic. Routing
instead goes through Virtufin.Worker.Host.WorkerBase.PublishTopicAttribute
(publishtopic), set from TradeEventJson.ToOutgoing's topic,
sc.<scenarioid>.trading.order.<event> (topic, ce-type and subject all come from the
naming library's virtufin.trading/order entity, shipped in Virtufin.Trading.Contracts;
see the naming docs); the WorkManager reads that extension
to pick the publish topic and strips it before publish, so subscribers
never see it (workmanager's WorkManager.PublishOutputAsync).
scenarioid is read back from the triggering "Order submitted"
event's own extension (stamped there by StrategyWorkerBase) -- an
executor never needs its own scenario config, it just echoes whatever
scenario the order it's processing came from.
State
The executor's own TState lives in the worker instance (via
ExecutorWorkerBase.State) -- the engine keeps one worker object alive
for the instance's lifetime, so state threads across deliveries.
Redelivery
Orders arrive at least once since WorkManager 0.38.0: after a hard crash the
orders of the last cursor window (≤250 ms) come again
(Inputs across a move). ExecutorWorkerBase executes each order once
per instance: BehaviorWorkerBase drops a repeated event (input-id deduplication,
Inputs can arrive twice), and an order whose order_id the instance
already executed is skipped whatever its event id (the last 100 000 order
ids). A fresh instance after a crash executes a replayed order again, but its
trade event carries the same event id and the same fill_id (a version 5
UUID of the order id, TradeEventJson.FillId), so consumers drop it. An
executor with a side effect outside the event stream must make that call
idempotent itself: LiveExecutor places each order under a client order id
derived from the order id and looks it up before placing.
Trading halt and cancel-all
The kill switch (the trading halt change in OpenSpec, 0.21.0):
- Halt. Before an order is executed the base reads its scenario's halt,
sc.<scenarioid>.trading.halt(TradingHaltJson, Virtufin.Trading.Contracts), once per order and uncached: this is the last line. A halted scenario's order is rejected (order.rejected,reject_source = risk,reject_reason = trading halted: <reason>) and never reaches the executor; so is an order whose halt cannot be read. The C# base only: a Python worker's context has no shared state, and the Python executors are simulated. cancel-all. The worker command (InvokeWorkerCommand) callsCancelOpenOrdersAsync(default: nothing rests), publishesorder.canceled(canceled_by = user) for each canceled order whose scenario this instance knows (it executed the order), and answers{ command, ok, canceled: [{order_id, symbol}], failed: [...], unannounced: [order ids] }.unannouncedare orders canceled at the venue that this instance did not execute (a restart): the venue's own report (BinanceOrderUpdates) announces them. Python: the same answer fromExecutor.cancel_open_orders.
Limitations
One action in, one event out, matching IExecutor's own shape. The host
contract allows several outputs per trigger (IWorker.ProcessAsync returns a list), so publishing e.g. an explicit "accepted" and an
immediate "filled" event needs only a multi-event executor shape, not a
host change. ExecutorWorkerBase is built on BehaviorWorkerBase
(Virtufin.Behavior.DevKit): scenarioid is checked before the executor
runs, so an order missing it is never executed, and the trade event
inherits the order's eventtime (pubsub-topics "Envelope on a derived
event"), also for wall-clock orders.