Pub/Sub Topics
Purpose
Canonical naming scheme for Dapr pub/sub topics and state keys across all Virtufin services: the naming library and its fragments, the routing taxonomy, the CloudEvents envelope contract, the state-key taxonomy, and the scenario axis.
Related specs:
- Scenarios — scenario registry, triplet definition, LIVE bootstrap.
- Cross-cutting — API-mediated pub/sub (envelope contract travels through the API gRPC).
- Worker Management and WebSocket Feed — worker lifecycle events (sys.workmanager.worker.lifecycle), which also carry a WebSocketFeed's connection status, and the relayed venue frames.
- Naming reference — every published naming fragment, composed and rendered.
Architecture
Two orthogonal routing axes plus a scenario-agnostic infrastructure axis:
| Axis | Pattern | Scope | Example |
|---|---|---|---|
| Market data world | act.exchange.<venue>.<entity>.<event>[.<identity>] or hyp.<WORLD>.exchange.<venue>.<entity>.<event>[.<identity>] |
data-universe-bound; shared across scenarios | act.exchange.binance.orderbook.update.BTC_USDT |
| Portfolio world | act.portfolio.<venue>.<entity>.<event>.<account> or hyp.<WORLD>.portfolio.<venue>.<entity>.<event>.<account> |
one venue account; shared across scenarios | act.portfolio.binance.balance.changed.main |
| Scenario world | sc.<scenarioId>.<domain>.<entity>.<event>[.<identity>] |
triplet-bound (market + portfolio + strategy) | sc.LIVE.trading.order.filled |
| Tier 0 / infrastructure | sys.<service>.<entity>.<event> |
scenario-agnostic | sys.workmanager.worker.lifecycle, sys.api.state.saved |
Workers, request-reply and dead letters have their own scopes (wrk, rpc, dlq; Topic Patterns requirement); registry keys use cfg.
Rationale: - Market data is world-scoped because it depends on the data universe (live vs hypothetical replay) and is shareable across scenarios. Two paper runs sharing the same Binance feed do not double-publish ticks. - The venue-side portfolio is world-scoped for the same reason: an account's balances, holdings and ledger as the venue reports them are one fact, shared by every scenario whose portfolio leg uses that account. Portfolio workers observe only; the executors change the portfolio. - Trading / position / risk / pnl are scenario-scoped because each depends on the full triplet. P&L in particular is meaningless without knowing all three legs. - Tier 0 is scenario-agnostic because infra lifecycle (workers up, connections reconnecting) is a deployment concern, not a trading concern.
act and hyp.<WORLD> are both top-level world markers. act is the single actual reality (act.exchange.*); a hypothetical world carries a <WORLD> segment identifying which hypothetical reality is in play (hyp.BACKTEST.exchange.*). Bare hyp (no name) is never a valid topic segment — it denotes the category of all hypothetical worlds, not a specific one (see Scenarios spec §Named Hypothetical Worlds). The data universe (ALL, EQ_EUROPE, EQ_2008_2009, …) is not encoded in the topic — it travels in the marketuniverse CloudEvent envelope extension (see below) and on the producing WebSocketFeed worker's universe tag. The scenario triplet (market + portfolio + strategy legs) lives in the scenario registry.
Requirements
Requirement: Names Are Built by the Naming Library
Every pubsub topic, state key and CloudEvent type, subject and source SHALL be produced by the naming library: Virtufin.Naming (C#), virtufin-naming (Python) or @virtufin/naming (TypeScript), all published from lib. Code SHALL NOT assemble a name from string fragments. The three ports SHALL behave identically, which the shared conformance vectors (lib/naming/conformance/vectors.yaml) verify in each port's CI.
The library SHALL validate its arguments in the caller's process. This does not relax the "No Topic or Scenario-State Validation Anywhere" requirement: infrastructure (virtufin-api, WorkManager, Dapr) SHALL keep passing names through unchanged.
Scenario: Producer builds a topic
- WHEN a worker publishes an order-book change for
BTC_USDTon Binance - THEN it SHALL obtain the topic from the entity (
book.Topic("changed", World.Act, pair)), not from string interpolation - AND the result SHALL be
act.exchange.binance.orderbook.changed.BTC_USDT
Scenario: Invalid argument fails in the caller
- WHEN a caller builds a name with an invalid value (a lowercase or unseparated pair, a missing world, an unknown event)
- THEN the library SHALL throw
NamingException(C#) orNamingError(Python, TypeScript) before anything is published or stored
Scenario: Infrastructure passes names through
- WHEN
virtufin-apireceives a publish or state request - THEN it SHALL NOT parse or validate the topic or key against the naming library
Scenario: Ports agree
- WHEN a naming change is made
- THEN it SHALL land in all three ports and in the conformance vectors in the same lib release
Requirement: Segment Classes
Names SHALL be sequences of segments joined with .. Every segment SHALL belong to exactly one class, and the letter case SHALL identify the class: vocabulary is lowercase, identifiers are uppercase.
| Class | Alphabet | Used for |
|---|---|---|
vocab |
[a-z][a-z0-9-]* |
scope, domain, entity, event, venue, service, worker type, indicator instance |
identifier |
[A-Z0-9_]{1,32} with at least one letter |
scenario, world, universe, strategy and world registry names |
pair |
BASE_QUOTE, uppercase |
currency pair |
guid |
lowercase canonical GUID | worker, order, connection id |
interval |
1s 1m 3m 5m 15m 30m 1h 2h 4h 6h 8h 12h 1d 3d 1w 1mo |
candle interval |
token |
[a-z0-9][a-z0-9-]* |
opaque lowercase id, e.g. a run id |
any |
[A-Za-z0-9_-]+ |
experimental (x.) names only |
A segment SHALL be at most 64 characters and a whole name at most 249 characters.
Scenario: Pair format
- WHEN a currency pair appears in a topic, key or subject
- THEN it SHALL be written
BASE_QUOTEin uppercase (BTC_USDT), never in the venue's own form (BTCUSDT,BTC/USD,btcusdt)
Scenario: Reserved lowercase words cannot collide with identities
- WHEN an entity has an index key
<stem>.index - THEN its identity class SHALL NOT admit
index; because identities are uppercase or GUIDs, an index key never collides with an instance key
Scenario: Multi-word vocabulary
- WHEN an event, entity or worker type needs more than one word
- THEN the words SHALL be joined with
-(load-failed), never_or a further.
Requirement: Name Derivation
Names SHALL be derived from an entity: a scope (the leading segments that are not part of the CloudEvent type), a path (vocabulary naming the entity), an identity (the segments identifying one instance), an entity type, and a set of events, each partitioned or not. Topic, key, subject and type of one entity SHALL therefore never disagree.
| Name | Rule |
|---|---|
| topic | scope.path.event[.identity]; the identity only if the event is partitioned |
| state key | scope.path.identity; all events of the entity share it |
| index key | scope.path.index |
| ce-subject | entity_type/identity |
| ce-type | com.virtufin.path.event |
| ce-source | urn:com.virtufin:<service>[:<instance>]; workers urn:com.virtufin:worker:<type>[:<worker_id>] |
| dead letter | dlq.<topic>; dlq.pubsub is reserved (Dapr's Redis pub/sub has no dead-letter topic) |
| experimental | x.<segments>, outside the contract |
Identity segments SHALL be last: nothing follows them in a topic or key.
Scenario: Partitioned event
- WHEN an order book for
BTC_USDTchanges on Binance in the actual world - THEN the topic SHALL be
act.exchange.binance.orderbook.changed.BTC_USDT, the keyact.exchange.binance.orderbook.BTC_USDT, the subjectcurrency_pair/BTC_USDTand the typecom.virtufin.exchange.binance.orderbook.changed
Scenario: Unpartitioned event
- WHEN an order is filled in scenario
LIVE - THEN the topic SHALL be
sc.LIVE.trading.order.filled, the subjectorder/<order_id>and the keysc.LIVE.trading.order.<order_id>
Scenario: Pure event family
- WHEN an entity declares no state (
state: false), e.g. worker commands - THEN it SHALL have topics but no state key
Requirement: Naming Fragments
Names SHALL be defined in YAML fragments that live in the repo owning them (<repo>/naming/<fragment-id>.yaml) and ship with its packages: embedded under naming/ and packed under naming/ for NuGet, as package data under an entry point in the group virtufin.naming for Python. A fragment declares an id, the fragments it imports, and its patterns, entities, bindings (bind), venues and worker types, all written as combinator expressions (literals, typed segments, ref, optional, oneOf). There SHALL be no central list of names: the global catalog SHALL be generated from the published fragments.
| Fragment | Owner | Defines |
|---|---|---|
virtufin.core |
lib | segment classes; the sys, wrk, rpc, cfg, dlq, x scopes; worker and reply families |
virtufin.worlds |
domain-devkit | the act/hyp.<WORLD> and sc.<SCENARIO> scopes; scenario, world and strategy registries |
virtufin.market |
market-data-devkit | venue-generic order book, candle, trade, instrument |
virtufin.indicator |
indicator-devkit | indicator values |
virtufin.portfolio |
portfolio-devkit | the venue-side account: snapshot, balances, holdings, ledger, open orders |
virtufin.trading |
strategy-devkit (Trading.Contracts) | a scenario's orders and trades |
virtufin.positions |
portfolio-devkit | a scenario's positions, P&L and risk; the P&L book key sc.<S>.pnl.book |
virtufin.venue.<venue> |
market-data-devkit | the venue, its symbol mapping, the market families bound to it, and the worker types of that venue's workers (in any repo) |
virtufin.worker.<type> |
the worker's repo | its worker type, for a worker not tied to a venue |
virtufin.service.<service> |
the service's repo | the service's sys.* and cfg.* names |
worker-devkit is generic and SHALL own no fragment that names a business entity (nor any domain envelope attribute; see Common Envelope Extensions).
Scenario: Adding a venue
- WHEN an order-book worker for a new venue (e.g. Alpaca) is added
- THEN market-data-devkit SHALL add one fragment that declares the venue, binds
virtufin.market/orderbookto it and declares the worker's type - AND the worker's repo SHALL NOT carry a copy of that fragment, and no central file SHALL change
Scenario: One owner, one copy
- WHEN a repo needs a fragment another repo owns
- THEN it SHALL load the fragment from the package that ships it and SHALL NOT keep a copy
- AND it SHALL compose it so that a registry already holding an identical copy is accepted
Scenario: Conflicting fragments
- WHEN two fragments could produce the same topic or key, and neither is a
bindspecialisation of the other, or two fragments declare the same venue or worker type - THEN composition SHALL fail and name both fragments
- AND the specs site build, which composes every published fragment, SHALL fail with it
Scenario: Reference without import
- WHEN a fragment references another fragment's pattern or entity without importing it
- THEN composition SHALL fail
Scenario: Docs tables
- WHEN a repo with a
naming/folder publishes its docs - THEN the docs workflow SHALL render the repo's families, keys, worker types and venues as tables (
virtufin-naming render)
Requirement: Venue Symbols
Each venue fragment SHALL declare how the venue spells a pair (symbol: "{BASE}{QUOTE}", "{BASE}/{QUOTE}", optionally lowercase) and how it names intervals that differ from the canonical set (Binance 1M → 1mo). Workers SHALL accept configuration in the canonical forms only and convert at the venue boundary.
Scenario: Outgoing venue call
- WHEN a worker configured with
BTC_USDTsubscribes to Binance - THEN it SHALL use the venue symbol
BTCUSDTfrom the venue declaration
Scenario: Incoming venue message
- WHEN a venue message carries
BTCUSDT - THEN the worker SHALL map it to the canonical pair by looking it up among its configured pairs, because an unseparated venue symbol cannot be split on its own
Requirement: Topic Patterns
Services SHALL publish to and subscribe from topics produced by the naming library (Names Are Built by the Naming Library requirement). Every topic SHALL start with one of these scopes:
| Scope | Template | Owner fragment |
|---|---|---|
act |
act.<path>.<event>[.<identity>] |
virtufin.worlds |
hyp |
hyp.<WORLD>.<path>.<event>[.<identity>] |
virtufin.worlds |
sc |
sc.<SCENARIO>.<path>.<event>[.<identity>] |
virtufin.worlds |
sys |
sys.<service>.<entity>.<event> |
virtufin.core, each service |
wrk |
wrk.<worker_type>.<event>[.<worker_id>] |
virtufin.core, each worker |
rpc |
rpc.<caller>.reply.<run_id> |
virtufin.core |
dlq |
dlq.<topic> |
virtufin.core |
x |
x.<segments> |
none (experimental) |
cfg is a scope for keys only. This is not an enforced contract at the infrastructure: no service validates or rejects topics before publish -- see cross-cutting spec for why no enforcement point owns this check.
Scenario: Tier 0 / infrastructure topic
- WHEN a service publishes a lifecycle or infrastructure event
- THEN the topic SHALL match
sys.<service>.<entity>.<event>(e.g.sys.workmanager.worker.lifecycle,sys.api.state.saved) - AND
<event>SHALL name a kind of event (lifecycle,heartbeat,changed), not a state; the state travels in the payload
Scenario: Market data topic (real)
- WHEN a service publishes real (live) market data
- THEN the topic SHALL match
act.exchange.<venue>.<entity>.<event>[.<identity>] - AND the data universe SHALL be carried in the
marketuniverseenvelope extension (ALLfor unrestricted,EQ_EUROPEfor a live subset) — it is not a topic segment
Scenario: Market data topic (hypothetical)
- WHEN a service publishes hypothetical (replay / backtest) market data
- THEN the topic SHALL match
hyp.<WORLD>.exchange.<venue>.<entity>.<event>[.<identity>] - AND
<WORLD>SHALL identify the specific hypothetical world (see Scenarios spec §Named Hypothetical Worlds) — barehyp(no name) SHALL NOT appear in a topic - AND the data universe SHALL be carried in the
marketuniverseenvelope extension, independent of<WORLD>— the same universe MAY appear under different hypothetical worlds and vice versa
Scenario: Trading topic
- WHEN a service publishes a trading-domain event (order lifecycle, trade lifecycle)
- THEN the topic SHALL match
sc.<scenarioId>.trading.<order|trade>.<event>(unpartitioned; per-order/per-trade routing viace-subject-- see the Cardinality Rule requirement for why the entity ID does not appear in the topic) - AND
<scenarioId>SHALL be either the reservedLIVEor a registered opaque scenario ID - AND
ce-subjectSHALL be set toorder/<order_id>ortrade/<trade_id>per the Common Envelope Extensions requirement
Scenario: Position topic
- WHEN a service publishes a position-domain event
- THEN the topic SHALL match
sc.<scenarioId>.position.<event>(unpartitioned; per-pair and portfolio-aggregate routing viace-subject) - AND
ce-subjectSHALL be set toposition/<PAIR>for a per-pair event orposition/portfoliofor the aggregate snapshot
Scenario: Risk topic
- WHEN a service publishes a risk-domain event
- THEN the topic SHALL match
sc.<scenarioId>.risk.<metric>.<event>(unpartitioned; per-pair routing viasubject)
Scenario: P&L topic
- WHEN a service publishes a P&L-domain event
- THEN the topic SHALL match
sc.<scenarioId>.pnl.<metric>.<event>(unpartitioned; per-pair routing viasubject)
Requirement: No Topic or Scenario-State Validation Anywhere
No service — publisher, subscriber, virtufin-api's publish handlers, or any shared helper — SHALL validate a topic's shape against the patterns in this spec, or a scenario ID's registration/lifecycle status, before publish. Topic shape (universes, scenario IDs, venues, lifecycle status) is Virtufin domain vocabulary, and the infrastructure services (API, WorkManager) are pure infrastructure with no domain logic. The naming library validates the arguments of the caller that builds a name (Names Are Built by the Naming Library requirement); nothing downstream re-checks the result.
Scenario: Malformed or unregistered topic is published anyway
- WHEN a service publishes to a topic that matches no pattern in this spec, or to an
sc.<scenarioId>.*topic whosescenarioIdis not registered (or ispaused/archived/deleted) - THEN the publish SHALL proceed; the Dapr pub/sub component (
pubsub.redis) is the only enforcement point, accepting whatever it considers a legal topic string - AND detecting and correcting a bad topic or stale scenario reference is a monitoring/observability concern (dead-letter, consumer-side logging), not a publish-time rejection
Requirement: CloudEvents Envelope
Every event SHALL be a CloudEvents v1.0 envelope. The CE base attributes (id, source, type, time, subject when applicable, specversion, datacontenttype) SHALL be carried as ce- prefixed metadata; data SHALL be the JSON payload. type, subject and source SHALL be derived by the naming library (Name Derivation requirement).
Scenario: ce-type format
- WHEN a service publishes an event
- THEN
ce-typeSHALL becom.virtufin.<path>.<event>: the topic without its scope and identity segments. Examples: - Tier 0:
com.virtufin.workmanager.worker.lifecycle,com.virtufin.api.state.saved - Market data:
com.virtufin.exchange.binance.orderbook.changed,com.virtufin.exchange.binance.candle.closed - Trading:
com.virtufin.trading.order.filled - Position:
com.virtufin.position.flipped - Risk:
com.virtufin.risk.exposure.update - P&L:
com.virtufin.pnl.realized.update - Indicator:
com.virtufin.indicator.sma-20.changed - Worker:
com.virtufin.httpget.response - AND a multi-word event SHALL hyphenate (
load-failed), never use_
Scenario: ce-source format
- WHEN a service publishes an event
- THEN
ce-sourceSHALL beurn:com.virtufin:<service>(e.g.urn:com.virtufin:workmanager,urn:com.virtufin:api) - AND a per-instance publisher MAY append the instance as a further segment (
urn:com.virtufin:<service>:<instance>) - AND a worker SHALL use
urn:com.virtufin:worker:<worker_type>[:<worker_id>] - AND the namespace and service SHALL be colon-separated, not dot-separated:
urn:<NID>:<NSS>is the URN shape
Scenario: subject attribute (per-entity events)
- WHEN a service publishes an event referring to a specific entity (order, trade, position, currency pair)
- THEN
ce-subjectSHALL be<entity_type>/<identity>(e.g.order/<order_id>,position/BTC_USDT,currency_pair/BTC_USDT) — partitioned topics carry the same identity in both the topic and the subject - AND unpartitioned topics (trading, position, risk, pnl) SHALL use
subjectto enable per-entity routing without topic proliferation
Requirement: Common Envelope Extensions
Every Tier 1 event SHALL carry the following CloudEvents extensions, scoped by the event's axis. Tier 0 events MAY carry correlationid only. The generic legs (correlationid, eventtime, walltime, ingesttime) are provided by worker-devkit; the domain legs (scenarioid, runid, exchange, clocktype, marketworld, marketuniverse, portfolioworld, strategyworld) by domain-devkit (DomainEnvelope.Stamp on a derived event).
The scenario-bound extensions -- scenarioid, runid, portfolioworld, strategyworld -- apply to scenario-scoped Tier 1 events (sc.<scenarioId>.*) only. World-scoped market-data events (act|hyp.<WORLD>.exchange.<venue>.*) SHALL NOT carry them: market data is shared across scenarios (see Architecture), so no single scenario, run, portfolio or strategy owns it, and any value would be wrong for every other consumer.
| Extension | Type | Required | Notes |
|---|---|---|---|
correlationid |
UUID | Tier 1 yes; Tier 0 no | Ties fills back to originating order across services |
scenarioid |
string | Scenario-scoped yes; market data no | Opaque registry key; LIVE for production |
runid |
UUID | Scenario-scoped yes when parallel backtests; market data no | Disambiguates concurrent runs sharing a scenario |
exchange |
string | Tier 1 yes (when applicable) | Exchange name (binance, coinbase, …); distinct from ce-source |
clocktype |
wall | historical |
Tier 1 yes | wall for prod + paper; historical for backtest replay |
eventtime |
RFC3339 | Tier 1 yes (= ce-time) |
Logical event time matching clocktype; for derived events, inherited from the triggering event (see below) |
walltime |
RFC3339 | Tier 1 yes | Always real clock at publish — for tracing / logging |
marketworld |
act | hyp.<WORLD> |
Tier 1 yes | Triplet leg (world) for market |
marketuniverse |
string | Tier 1 yes | Triplet leg (universe) for market; present for both act and hyp.<WORLD> (use "ALL" for unrestricted) |
portfolioworld |
act | hyp.<WORLD> |
Scenario-scoped yes; market data no | Triplet leg for portfolio |
strategyworld |
act | hyp.<WORLD> |
Scenario-scoped yes; market data no | Triplet leg for strategy |
CloudEvents extension attribute names are restricted to lowercase alphanumerics — no dots, no underscores. These four are deliberately concatenated (marketworld, not market.world or market_world) to satisfy that constraint, matching every other extension in this table.
Scenario: Envelope on a production fill event
- WHEN a service publishes
sc.LIVE.trading.order.filled(ce-subject = order/<order_id>) - THEN the CloudEvent extensions SHALL include
scenarioid=LIVE,runid=<uuid>,correlationid=<uuid>,exchange=binance,clocktype=wall,eventtime=<rfc3339>,walltime=<rfc3339>,marketworld=act,marketuniverse=ALL,portfolioworld=act,strategyworld=act
Scenario: Envelope on a backtest fill event
- WHEN a backtest engine publishes
sc.S7F3A9B.trading.order.filled(ce-subject = order/<order_id>) - THEN the envelope SHALL include
scenarioid=S7F3A9B,clocktype=historical,eventtime=<historical rfc3339>(the replayed tick's timestamp),walltime=<real rfc3339>(now),marketworld=hyp.BACKTEST,marketuniverse=EQ_2008_2009,portfolioworld=hyp.BACKTEST,strategyworld=hyp.BACKTEST - AND
runidSHALL differ for concurrent backtests against the same scenario
Scenario: clocktype rationale
- WHEN a strategy computes a time-series indicator (e.g. 20-period moving average) from a backtest stream
- THEN it SHALL use
eventtime(which ishistoricalfor backtests) to maintain correct indicator semantics - AND it SHALL use
walltimeonly for tracing, logging, and alerting
Scenario: Envelope on a derived event
- WHEN a worker publishes an event derived from a triggering event (an indicator value from a candle, an order from a market event, a trade event from an order)
- THEN its
eventtimeSHALL be the triggering event'seventtime, else the triggering event'sce-time, else the current time, regardless ofclocktype - AND its
ce-timeSHALL equal thateventtime, itswalltimeSHALL be the current time, and itsclocktypeSHALL be the triggering event's, defaulting towall - AND it SHALL carry the triggering event's other common envelope extensions (
correlationid,scenarioid,runid,exchange, the world and universe legs) unless the deriving worker sets them explicitly
Scenario: Envelope on a market data event
- WHEN a service publishes a world-scoped market-data event, e.g.
act.exchange.binance.orderbook.changed.BTC_USDT - THEN the CloudEvent extensions SHALL include
exchange=binance,clocktype=wall,eventtime=<rfc3339>(the exchange's own event time, =ce-time),walltime=<rfc3339>,marketworld=act,marketuniverse=ALL - AND they SHALL NOT include
scenarioid,runid,portfolioworldorstrategyworld
Scenario: Envelope on a portfolio event
- WHEN a service publishes a world-scoped portfolio event, e.g.
act.portfolio.binance.balance.changed.main - THEN the CloudEvent extensions SHALL include
exchange=binance,portfolioworld=act,clocktype=wall,eventtime=<rfc3339>(the venue's own time, =ce-time),walltime=<rfc3339> - AND they SHALL NOT include
scenarioid,runid,strategyworld,marketworldormarketuniverse: an account is shared across scenarios and is not market data
Requirement: Trade Lifecycle Events
The trading domain SHALL model the lifecycle: submitted → accepted → (partially_filled →)* filled → cleared → settled. For Binance CEX, cleared and settled collapse to near-instantaneous but the events remain distinct for future DeFi / TradFi integration. Every event below publishes to a consolidated per-scenario topic (no <order_id>/<trade_id> topic segment); ce-subject carries the entity reference per the Common Envelope Extensions and Cardinality Rule requirements.
Scenario: Order submitted
- WHEN a service submits an order to an exchange
- THEN it SHALL publish
sc.<scenarioId>.trading.order.submittedwithce-type = com.virtufin.trading.order.submittedandce-subject = order/<order_id> - AND the data payload SHALL include
order_id,symbol,side(buy|sell),type(market|limit),qty,price?,venue,submitted_at
Scenario: Order accepted
- WHEN the venue acknowledges the order
- THEN the service SHALL publish
sc.<scenarioId>.trading.order.acceptedwithce-subject = order/<order_id>and datavenue_order_id,accepted_at
Scenario: Order rejected
- WHEN an order is rejected by pre-trade risk or the venue
- THEN the service SHALL publish
sc.<scenarioId>.trading.order.rejectedwithce-subject = order/<order_id>and datareject_reason,reject_source(risk|venue),rejected_at - AND an order that cannot be sent because it fails a venue's filters (it rounds to nothing, or falls below the minimum quantity or notional) SHALL be rejected this way with source
risk, never dropped
Scenario: Order amended (mutation, not transition)
- WHEN an order's price or quantity is changed in-place
- THEN the service SHALL publish
sc.<scenarioId>.trading.order.amendedwithce-subject = order/<order_id>and datanew_price?,new_qty?,amended_at - AND the order's status SHALL remain unchanged (
pendingorpartially_filled)
Scenario: Order cancelled
- WHEN an order is canceled by the user or system
- THEN the service SHALL publish
sc.<scenarioId>.trading.order.canceledwithce-subject = order/<order_id>and datacanceled_at,canceled_by(user|system|venue) - AND an order that executed part of its quantity before it was canceled SHALL carry the cumulative
qty_filled, thefill_idand thefeesof itsorder.filledin this event too, because the two events travel on two topics and a consumer's inputs are ordered only within a topic; a consumer folds the quantity and its fees from whichever arrives first, once perfill_id
Scenario: Order expired
- WHEN an order's time-in-force is reached without a fill
- THEN the service SHALL publish
sc.<scenarioId>.trading.order.expiredwithce-subject = order/<order_id>and dataexpired_at - AND an order that executed part of its quantity before it expired SHALL carry
qty_filled,fill_idandfeesas an order that was canceled does
Scenario: Order filled (workhorse event)
- WHEN a partial or full fill is received from the venue (Binance WebSocket fill callback)
- THEN the service SHALL publish
sc.<scenarioId>.trading.order.filledwithce-subject = order/<order_id>and datafill_id,qty_filled,price,fees,liquidity(maker|taker),remaining_qty,filled_at,realized_pnl?(optional, included if computed at fill time) - AND for partial fills,
remaining_qtySHALL be the post-fill remaining quantity (decreasing across events) - AND
feesSHALL state what the venue charged for this fill per asset, an object from asset to amount ({"BNB":0.02,"BTC":0.0005}):{}when nothing was charged,nullonly when the fee is unknown (a trade was missed, the source failed); assets charged nothing are left out, so one order may pay in several assets and every producer of a fill states the same object - AND a consumer folding holdings SHALL subtract the part of
feesin the instrument's base asset once perfill_id, leave fees in any other asset alone unless it tracks that asset, and report an unknown fee rather than treat it as zero - AND when
remaining_qty == 0, nothing more of the order will fill: it is implicitly fully filled (no separateorder.completedevent), or, when anorder.canceled/order.expiredfollows, it ended withqty_filledas its final executed quantity
Scenario: Trade cleared
- WHEN an order is fully filled and counterparty obligations are netted
- THEN the service SHALL publish
sc.<scenarioId>.trading.trade.clearedwithce-subject = trade/<trade_id>and datatrade_id,order_id,cleared_at - AND this event SHALL fire exactly once per trade (not per fill)
Scenario: Trade settled
- WHEN asset transfer for a trade is final
- THEN the service SHALL publish
sc.<scenarioId>.trading.trade.settledwithce-subject = trade/<trade_id>and datatrade_id,order_id,settled_at,tx_hash?(null for CEX, populated for on-chain settlement) - AND for Binance CEX,
clearedandsettledSHALL be emitted back-to-back by the publisher - AND for DeFi / TradFi integration, the gap between
clearedandsettledmay span minutes to days
Requirement: Position Lifecycle Events
Position state SHALL be derived from signed size plus a liquidation sub-state. position.flipped SHALL be a first-class atomic event because the risk engine needs direction-change awareness without a flat interval. Every event below publishes to a consolidated per-scenario topic (no <PAIR> topic segment); ce-subject carries the entity reference. Multi-word events hyphenate (liquidation-warning), so every position topic is sc.<scenarioId>.position.<event>.
Scenario: Who publishes position events
- WHEN a strategy folds its own fills into its holdings (behaviour spec, Derived Portfolio State)
- THEN no platform service SHALL be required to publish position events for a strategy to hold its positions
- AND an absolute event is how a strategy leaves
degraded(position or fee unknown) without being recreated: an operator MAY publish one as an external correction, and a reconciliation worker SHALL publish one only under Automatic Position Recovery (behaviour spec);BinancePositionReconciler(portfolio-workers) is the one worker that publishes position events
Scenario: Recovery event
- WHEN a reconciliation worker recovers a strategy from a read of the venue
- THEN it SHALL publish
sc.<scenarioId>.position.openedfor a holding above zero andsc.<scenarioId>.position.closedat zero, withsource = External,avgEntry = 0andrealizedPnL = 0(a spot balance has no cost basis, so these are no prices), the read's time as the event's time and in theasofextension (RFC 3339) - AND an event carrying
asofis a recovery event, which a strategy treats per Automatic Position Recovery; an event without it is folded as before
Scenario: Position opened
- WHEN a position is established (absolute: sets the holding)
- THEN the publisher SHALL publish
sc.<scenarioId>.position.openedwithce-subject = position/<PAIR>and datasymbol,quantity,avgEntry,source,openedAt
Scenario: Position updated
- WHEN a position grows or shrinks on the same side (absolute:
newQuantitysets the holding) - THEN the publisher SHALL publish
sc.<scenarioId>.position.updatedwithce-subject = position/<PAIR>and datasymbol,deltaQuantity,newQuantity,newAvgEntry,source,updatedAt
Scenario: Position updated, attributed
- WHEN one fill's change is attributed to a strategy (delta: applied once per
fillId) - THEN the publisher SHALL publish
sc.<scenarioId>.position.updated-attributedwithce-subject = position/<PAIR>and datasymbol,deltaQuantity,strategyId,fillId,updatedAt
Scenario: Position flipped (atomic direction change)
- WHEN a position changes from long to short or vice versa in a single fill sequence (absolute)
- THEN the publisher SHALL publish
sc.<scenarioId>.position.flippedwithce-subject = position/<PAIR>and datasymbol,newQuantity,oldDirection,newDirection,flippedAt - AND this event SHALL be atomic — no intermediate
position.closed+position.openedsequence
Scenario: Position closed
- WHEN a position returns to flat (absolute: zeroes the holding)
- THEN the publisher SHALL publish
sc.<scenarioId>.position.closedwithce-subject = position/<PAIR>and datasymbol,closedAt,realizedPnL
Scenario: Reserved position events
- WHEN a publisher considers
increased,decreased, or an event below (liquidated,liquidation-warning,adjustment,snapshot) - THEN it SHALL NOT publish it to a strategy: these names are reserved, no strategy consumes them yet, and a strategy SHALL treat any position event it does not know as an error
Scenario: Position liquidated (forced)
- WHEN a position is force-closed by the venue
- THEN the service SHALL publish
sc.<scenarioId>.position.liquidatedwithce-subject = position/<PAIR>and dataliquidation_price,realized_pnl,liquidated_at
Scenario: Liquidation warning (signal, not transition)
- WHEN margin ratio crosses a warning threshold
- THEN the service SHALL publish
sc.<scenarioId>.position.liquidation-warningwithce-subject = position/<PAIR>and datamargin_ratio,threshold - AND the position's primary state SHALL NOT change; only the
liquidation_statussub-state becomeswarning
Scenario: Position adjustment (corporate action)
- WHEN a corporate action (split, dividend, symbol change) mutates a position's size or avg_price
- THEN the service SHALL publish
sc.<scenarioId>.position.adjustmentwithce-subject = position/<PAIR>and dataadjustment_type(split|dividend|symbol_change),new_qty,new_avg_price,corporate_action_id
Scenario: Portfolio snapshot
- WHEN a full portfolio snapshot is published (consolidated)
- THEN the service SHALL publish
sc.<scenarioId>.position.snapshotwithce-subject = position/portfolioand datatotal_value,total_pnl,position_count
Requirement: Market Data Events
Market data events SHALL live under the world-scoped scopes (act.exchange.<venue>.* or hyp.<WORLD>.exchange.<venue>.*), as the entities of the virtufin.market fragment (market-data-devkit) bound to a venue by that venue's fragment (e.g. virtufin.venue.binance in market-data-workers). hyp carries one more segment than act (the <WORLD> slot); neither carries the data universe, which travels in the marketuniverse envelope extension. Every order-book event, trade.executed, candle.closed and instrument.snapshot SHALL be partitioned by pair, and so SHALL the raw feeds a WebSocketFeed worker serves: orderbook.update and trade.update per pair, candle.update per pair and interval (market-data-devkit 0.19.0; they were one topic for every pair), so a topic is the whole dependency of the worker that reads it (worker-management, Topic Dependencies). ticker.update, funding.rate and mark.price are reserved in the fragment and not produced yet.
Scenario: Order book snapshot
- WHEN the venue publishes a full order book snapshot
- THEN it SHALL be relayed on
act\|hyp.<WORLD>.exchange.<venue>.orderbook.snapshot.<PAIR>(act omits<WORLD>), carrying the venue's own frame
Scenario: Order book update (delta)
- WHEN the venue publishes an order book delta
- THEN it SHALL be relayed on
act\|hyp.<WORLD>.exchange.<venue>.orderbook.update.<PAIR>(act omits<WORLD>), carrying the venue's own frame; the WebSocketFeed worker serving the topic routes each frame to it (websocket-feed, Served Topics, Frame Publishing)
Scenario: Order book change
- WHEN a service applies a snapshot or update-delta to a maintained per-pair local order book (see the State Keys requirement's "Order book state key" scenario)
- THEN it SHALL publish
act\|hyp.<WORLD>.exchange.<venue>.orderbook.changed.<PAIR>(act omits<WORLD>) with ce-typecom.virtufin.exchange.<venue>.orderbook.changedandce-subjectcurrency_pair/<PAIR>, for every applied update - AND the data SHALL be the whole book as of that update as an order book image: FlatBuffers table
OrderBook(market-data-devkitschemas/orderbook.fbs, identifierVFOB) withpair,last_update_id,event_time_unix_ns(the exchange's time of the last applied delta, 0 when unknown),price_precision,size_precision, andbids/askswith every level, best first, each level theDecimalAmountcardinals of price and size (value = cardinal / 10^precision) - AND
datacontenttypeSHALL beapplication/x-virtufin-orderbook+flatbuffersanddataschemaurn:virtufin:marketdata:orderbook:v1 - AND this event is the source of truth for the book at that update: a consumer acts on it alone; the order book state key holds a snapshot of the book for display and startup, written in the background and possibly older than the latest event
Scenario: Order book gap detected
- WHEN a service maintaining a local order book detects a sequence gap (an update-delta's first update id doesn't bracket the book's current
last_update_id) that it cannot resolve without a fresh snapshot - THEN it SHALL publish
act\|hyp.<WORLD>.exchange.<venue>.orderbook.gap.<PAIR>(act omits<WORLD>) with ce-typecom.virtufin.exchange.<venue>.orderbook.gap,ce-subjectcurrency_pair/<PAIR>, and payloadaction(gap),reason(gap),pair,expected(the update id the book needed),got(the update id actually received), andevent_timewhen known - AND it SHALL NOT overwrite the order book state key's cached value until a fresh snapshot resolves the gap -- a consumer that needs to know whether the cached book is currently fresh or stale SHALL subscribe to this topic rather than assume the state key alone reflects freshness
Scenario: Order book snapshot request
- WHEN a pair's local order book is not live: it has no book yet (
reasonbootstrap,expected0), a gap was detected (reasongap), or the book is still not live once the last request's backoff is over (reasonretry: the request was lost, the fetch failed, or the snapshot did not bracket the buffered deltas) - THEN the gap event SHALL be the pair's snapshot request: the pair's snapshot fetcher (an HttpGet worker deployed with the venue's depth URL and
replay=off) subscribes to the pair's gap topic and answers with anorderbook.snapshot; no timer polls snapshots - AND at most one request per pair SHALL be open: the next waits for a backoff that starts at 5 s and doubles up to 60 s while the pair stays out of sync, reset once the book is live, so a live book requests nothing and an out-of-sync pair at most one snapshot per minute
- AND a restarted service SHALL restore a pair's instrument metadata from the instrument state key it saved, since
instrument.snapshotis published once per run
Scenario: Raw trade and candle frames
- WHEN a WebSocketFeed worker serves a pair's raw trades or a pair's candles at an interval
- THEN it SHALL relay the venue's frames on
act\|hyp.<WORLD>.exchange.<venue>.trade.update.<PAIR>andact\|hyp.<WORLD>.exchange.<venue>.candle.update.<PAIR>.<interval>(act omits<WORLD>)
Scenario: Public trade tape
- WHEN a public trade occurs on the venue
- THEN the service SHALL publish
act\|hyp.<WORLD>.exchange.<venue>.trade.executed.<PAIR>(act omits<WORLD>) with ce-typecom.virtufin.exchange.<venue>.trade.executed, subjectcurrency_pair/<PAIR>, and payloadtrade_id,price,qty,side(buy/sell, the aggressor),trade_time
Scenario: Ticker update
- WHEN a venue worker publishes 24h rolling stats (reserved: no worker produces them yet)
- THEN it SHALL publish
act\|hyp.<WORLD>.exchange.<venue>.ticker.update.<PAIR>(act omits<WORLD>) withlast_price,volume_24h,change_24h_pct, and its venue fragment SHALL bind the reservedtickerentity
Scenario: Funding rate
- WHEN a venue worker publishes a perpetual funding rate tick (reserved)
- THEN it SHALL publish
act\|hyp.<WORLD>.exchange.<venue>.funding.rate.<PAIR>(act omits<WORLD>) withfunding_rate,next_funding_time
Scenario: Mark price
- WHEN a venue worker publishes a mark price update (derivatives; reserved)
- THEN it SHALL publish
act\|hyp.<WORLD>.exchange.<venue>.mark.price.<PAIR>(act omits<WORLD>) withmark_price,index_price
Scenario: OHLCV candle
- WHEN a candle interval closes
- THEN the service SHALL publish
act\|hyp.<WORLD>.exchange.<venue>.candle.closed.<PAIR>.<interval>(act omits<WORLD>) with ce-typecom.virtufin.exchange.<venue>.candle.closedandce-subjectcurrency_pair/<PAIR> - AND the payload SHALL be JSON
{ symbol, interval, open, high, low, close, volume, windowStart, windowEnd }:symbolthe canonical pair, prices and volume as JSON numbers,windowStart/windowEndas RFC3339 (windowEndis the candle's close time) - AND
<interval>SHALL be the canonical interval (Segment Classes requirement), identical in the topic segment and theintervalfield; a venue's own interval name is mapped by its venue fragment (Binance1M→1mo) - AND the envelope SHALL be the world-scoped market-data envelope (Common Envelope Extensions requirement), with
eventtime=ce-time=windowEnd - AND only closed candles SHALL be published: a still-open candle is not a fact yet
Scenario: Candle intervals are market data
- WHEN a candle is aggregated over a standard venue interval
- THEN it SHALL be published as market data under this requirement, whatever the interval (a
1dcandle and a1scandle are equally market data) - AND an aggregation over a non-standard, strategy-chosen window SHALL instead be an indicator (Indicator Events requirement)
Scenario: Instrument info
- WHEN instrument metadata changes (lot size, tick size, status)
- THEN it SHALL be published on
act\|hyp.<WORLD>.exchange.<venue>.instrument.snapshot.<PAIR>(act omits<WORLD>)
Requirement: Portfolio Events
The venue-side view of a user account -- what the venue reports the account holds, not what the executors derived from their fills -- SHALL live under the world-scoped portfolio scopes (act.portfolio.<venue>.* or hyp.<WORLD>.portfolio.<venue>.*), as the entities of the virtufin.portfolio fragment (portfolio-devkit). <WORLD> is the portfolio world: act for a live account, hyp.<NAME> for a venue-backed paper or testnet account (e.g. hyp.PAPER for an Alpaca paper account). Every portfolio event SHALL be partitioned by the logical account name (lowercase vocabulary, e.g. main, paper), which is the last topic segment; ce-subject SHALL be account/<account>; the ce-type SHALL be com.virtufin.portfolio.<venue>.<entity>.<event>, the same for every account. The asset, symbol, ledger entry or order SHALL travel in the payload. Payloads SHALL be JSON with snake_case fields, decimals as JSON numbers and RFC3339 UTC times.
A portfolio worker SHALL observe only: it SHALL NOT place, amend or cancel orders. Order lifecycle (Trade Lifecycle Events) and the positions derived from fills (Position Lifecycle Events) remain scenario-scoped and owned by the executors. Reconciling the two views is a consumer's concern; the one consumer that publishes from it is a reconciliation worker, which holds no venue credential (behaviour spec, Automatic Position Recovery).
Scenario: Raw account frames
- WHEN a WebSocketFeed worker relays a frame of an account's push stream (Binance user data stream, Alpaca trading stream)
- THEN it SHALL be relayed on
act\|hyp.<WORLD>.portfolio.<venue>.account.update.<account>(act omits<WORLD>), carrying the venue's own frame
Scenario: Account snapshot
- WHEN a portfolio worker pulls the account from the venue (on start, after a reconnect, on a periodic trigger)
- THEN it SHALL publish
act\|hyp.<WORLD>.portfolio.<venue>.account.snapshot.<account>with ce-typecom.virtufin.portfolio.<venue>.account.snapshotand payload{ account, time, balances, holdings, open_orders }, each list holding the entries below;timeSHALL be when the read began, the open orders SHALL be read before the balances, andbalancesSHALL hold every asset the venue lists, zero ones included (a zero proves an asset flat, a missing asset proves nothing) - AND it SHALL then publish only the changes since its previous snapshot (an asset gone as a zero balance, a holding gone as quantity zero, an order gone with status
closed), never a replay of unchanged state
Scenario: Balance changed
- WHEN an asset balance of the account changes
- THEN the service SHALL publish
act\|hyp.<WORLD>.portfolio.<venue>.balance.changed.<account>with payload{ asset, free, locked, total }(total=free+locked)
Scenario: Holding changed
- WHEN a holding (a position with the venue's cost basis and value) of the account changes
- THEN the service SHALL publish
act\|hyp.<WORLD>.portfolio.<venue>.holding.changed.<account>with payload{ symbol, qty, avg_price?, market_value?, unrealized_pnl?, currency? }; a venue that reports balances only publishes none
Scenario: Ledger entry posted
- WHEN the venue reports a movement of an asset on the account (deposit, withdrawal, transfer, fill, fee, dust conversion, dividend, interest)
- THEN the service SHALL publish
act\|hyp.<WORLD>.portfolio.<venue>.ledger.posted.<account>with payload{ entry_id, kind, asset, delta, time, reference? },kindone ofdeposit,withdrawal,transfer,fill,fee,dust,dividend,interest,other, and each entry published once
Scenario: Open order changed
- WHEN the venue reports a change of an order on the account, whoever placed it
- THEN the service SHALL publish
act\|hyp.<WORLD>.portfolio.<venue>.openorder.changed.<account>with payload{ order_id, symbol, side, type, qty, filled_qty, status, time, price?, client_order_id? },statusone ofnew,partially_filled,filled,canceled,expired,rejected,closed - AND this event SHALL NOT replace the executors'
order.*events: it is the venue's view, for reconciliation and for orders placed outside Virtufin
Scenario: Portfolio state keys
- WHEN a portfolio worker keeps the account's current state
- THEN it SHALL use the keys
act\|hyp.<WORLD>.portfolio.<venue>.<entity>.<account>foraccount(the latest snapshot),balance,holdingandopenorder; ledger entries have no state key, their history lives in the portfolio database
Requirement: Risk Events
Risk events SHALL be consolidated (one topic per metric). Per-symbol routing SHALL use ce-subject.
Scenario: Exposure update
- WHEN risk greeks (delta / gamma / vega / theta) are recomputed
- THEN the service SHALL publish
sc.<scenarioId>.risk.exposure.updatewithgreeks: { delta, gamma, vega, theta },underlyings[]
Scenario: Spot exposure update
- WHEN spot exposure is recomputed (a fill, or a new mark)
- THEN the service SHALL publish
sc.<scenarioId>.risk.exposure.updatewithce-subject = position/portfolioand databy_symbol: { <PAIR>: { qty, mark, notional, share } },gross_notional,net_notional,quote, whereshare= the symbol's notional /gross_notional - AND when the scenario's registry entry has
limits(scenarios spec), each symbol SHALL carrylimitandbreached(truewhen its notional is abovemax_notional_per_symbol) and the payloadgross_limitandgross_breached(max_gross_notional); a limit that becomes breached SHALL be published once assc.<scenarioId>.risk.limit.breach(limit_namethe limit's name,severitywarning, subjectpair/<PAIR>for a symbol's limit,position/portfoliofor the gross one)
Scenario: Margin update
- WHEN margin used or available changes
- THEN the service SHALL publish
sc.<scenarioId>.risk.margin.updatewithmargin_used,margin_available,margin_ratio
Scenario: Drawdown alert
- WHEN drawdown crosses a configured threshold
- THEN the service SHALL publish
sc.<scenarioId>.risk.drawdown.alertwithdrawdown_pct,threshold_pct,peak_value,current_value
Scenario: Limit breach
- WHEN a configured risk limit is breached
- THEN the service SHALL publish
sc.<scenarioId>.risk.limit.breachwithlimit_name,limit_value,actual_value,severity
Scenario: Scenario P&L (stress test)
- WHEN a stress / scenario P&L computation completes
- THEN the service SHALL publish
sc.<scenarioId>.risk.scenario.pnlwithscenario_name,pnl,scenario_inputs
Requirement: P&L Events
P&L events SHALL be consolidated. The full triplet context is carried in the envelope (not the topic) because P&L is meaningless without it.
Scenario: Realized P&L update
- WHEN realized P&L is recomputed (e.g. on fill or position close)
- THEN the service SHALL publish
sc.<scenarioId>.pnl.realized.updatewithrealized_pnl,by_symbol: { <PAIR>: <pnl> },period(daily|session|cumulative)
Scenario: Unrealized P&L update
- WHEN unrealized P&L is recomputed (mark-to-market)
- THEN the service SHALL publish
sc.<scenarioId>.pnl.unrealized.updatewithunrealized_pnl,by_symbol: { <PAIR>: <pnl> },mark_prices: { <PAIR>: <price> }
Scenario: P&L book
- WHEN a P&L producer keeps a scenario's per-symbol book
- THEN it SHALL save it at the state key
sc.<scenarioId>.pnl.book(entitypnl_book,virtufin.positions) as{ time, quote, symbols: { <PAIR>: { qty, avg_cost, mark?, realized_pnl, unrealized_pnl?, notional?, fees: { <asset>: <amount> }, fee_unknown } }, realized_pnl, unrealized_pnl, fills_folded }, decimals as JSON numbers,timeRFC 3339 UTC
Requirement: P&L Worker
A generic P&L worker (portfolio-workers, no venue code) SHALL compute each configured scenario's P&L and spot exposure from the scenario's own trading events and the market world's order books.
- Inputs:
sc.<S>.trading.order.submitted(symbol, side, of eachorder_id) andsc.<S>.trading.order.filled; a fill SHALL be joined to its order byce-subjectorder/<order_id>, and a fill whose order is unknown SHALL be held until the order arrives. The quantity of a canceled or expired order that executed part of it SHALL be folded from itsorder.filled, which carries the price. Marks: the order bookchangedevents of the scenario's market world (<marketworld>.exchange.<venue>.orderbook.changed.<PAIR>) for the symbols it holds. - Fold per symbol: quantity (buys add, sells subtract), average cost (the quantity-weighted fill price of the open quantity, reset when the quantity crosses zero), realized P&L (on a reducing fill: reduced quantity × (fill price − average cost), sign by side), fees (in the quote asset when charged in it; a fee in another asset SHALL be kept per asset and not converted). Each fill SHALL be folded once (by
fill_id). - Mark to market: the mark of a symbol SHALL be its book's mid; unrealized P&L = quantity × (mark − average cost); notional = |quantity| × mark.
- Publish: on an input, at most once per
publishintervalms(default 1000) and only when a fill or a held symbol's mark changed:sc.<S>.pnl.realized.update,sc.<S>.pnl.unrealized.updateandsc.<S>.risk.exposure.update(P&L Events, Risk Events). - State: it SHALL save the book (P&L Events, P&L book) at
sc.<S>.pnl.bookwith each publish, and what a restart needs (symbols, marks, orders, the fill ids folded, the fills held) in worker state, from which it SHALL continue on start; input replay across moves (worker management) SHALL NOT fold a fill twice. - Limits: it SHALL read the scenario's
limits(scenarios, Scenario Limits) fromcfg.scenario.<S>at start and again on eachsys.api.state.savedof that key.
Scenario: A round trip
- WHEN a scenario buys 2 BTC_USDT at 100, buys 2 at 110 and sells 3 at 120, with the book mid at 125
- THEN the book SHALL hold quantity 1, average cost 105, realized P&L 45 and unrealized P&L 20
Scenario: Restart
- WHEN the worker restarts
- THEN it SHALL continue from
sc.<S>.pnl.bookand fold only fills not in it
Requirement: Tier 0 / Infrastructure Events
Tier 0 events SHALL be scenario-agnostic and SHALL use the sys scope: sys.<service>.<entity>.<event>. Each service SHALL define its Tier 0 entities in its own fragment (virtufin.service.<service>). The state of a lifecycle event SHALL travel in the payload, not in the topic or the ce-type.
Scenario: Worker lifecycle event
- WHEN a worker changes state (
registered,starting,online,degraded,stopping,stopped,failed,loaded,load-failed), is deleted (deleted), or its tags or code change (updated) - THEN the WorkManager SHALL publish to
sys.workmanager.worker.lifecyclewithce-type = com.virtufin.workmanager.worker.lifecycleandce-subject = worker/<worker_id> - AND the event SHALL carry
state,worker_id,topic, and state-specific fields (error_type,error_messageon a failure;librariesonloaded;changedandtagsorcodeurlonupdated)
Scenario: New topics announced
- WHEN the gateway's topic catalog gains topics
- THEN the gateway SHALL publish
com.virtufin.api.topic.catalog.addedonsys.api.topic.catalog.addedwith{topics: [...]}, once per topic cluster-wide, best effort
Scenario: Trigger change events
- WHEN
ScheduleTriggerorDeleteTriggersucceeds - THEN the gateway SHALL publish
com.virtufin.api.trigger.scheduledonsys.api.trigger.scheduledwith the trigger's definition (name,schedule,duetime,repeats,ttl,targettopic,ownerworkerid), orcom.virtufin.api.trigger.deletedonsys.api.trigger.deletedwithname - AND like the state-change events these SHALL be best effort: a failed publish SHALL NOT fail the call
- AND a trigger's firing SHALL stay on its target topic (
com.virtufin.api.trigger.fired), never on these topics
Scenario: Worker metrics event
- WHEN a worker pushes its counters (worker-devkit
WorkerMetrics) - THEN it SHALL publish
com.virtufin.<worker_type>.metricsonwrk.<worker_type>.metricswithce-subject = worker/<worker_id>and data{workerid, counters: {name: integer}, at}, at most once permetricssecondsand only when the counters changed
Scenario: Connection lifecycle event
- WHEN a WebSocketFeed worker's connection changes state (
connecting,connected,reconnecting,disconnected,degraded,released) - THEN it SHALL be reported as a worker lifecycle event on
sys.workmanager.worker.lifecyclewithstate = status,status= the connection state anddetail(worker-management, Worker Lifecycle Events); there SHALL be no connection lifecycle topic
Scenario: Infra events (connection / worker detail)
- WHEN a service publishes a finer-grained heartbeat for one of its entities
- THEN it SHALL publish to
sys.<service>.<entity>.heartbeat(thevirtufin.service.workmanagerfragment declaressys.workmanager.worker.heartbeat; it is not published today, and a connection, being a worker, has no heartbeat of its own)
Requirement: Cardinality Rule
Services SHALL prefer consolidated topics (one topic, per-entity routing via ce-subject) over per-entity topics (.<entity_id> segment). Per-entity topics SHALL be used only when a subscriber chooses one specific, known entity at subscribe time and the deployed pub/sub backend supports an exact-topic subscription for it. Per-entity topics SHALL NOT be used when a subscriber needs an unbounded or dynamically-appearing set of entities (e.g. every order in a scenario, every symbol in a portfolio) — that access pattern requires either a consolidated topic or genuine broker-level wildcard/pattern subscription support, and the currently-deployed Dapr pubsub component (pubsub.redis, Redis Streams) provides neither: its Subscribe/Publish implementation matches the topic string against a Redis Stream key exactly, with no pattern matching (confirmed by reading components-contrib/pubsub/redis/redis.go — XGROUP CREATE MKSTREAM <topic> and XAdd(ctx, req.Topic, ...) both treat <topic> as a literal key).
Scenario: Per-entity topic justified
- WHEN a subscriber knows the specific entity ahead of time and subscribes to exactly that entity's topic (e.g., order book updates for one specific, chosen currency pair)
- THEN the topic SHALL carry the entity ID segment (
act.exchange.binance.orderbook.changed.<PAIR>)
Scenario: Consolidated topic preferred
- WHEN a subscriber needs events for an unbounded or dynamically-appearing set of entities it cannot enumerate ahead of subscribing (e.g., all orders in a scenario, all symbols in a portfolio)
- THEN the topic SHALL be consolidated (
risk.exposure.update,sc.<scenarioId>.trading.order.filled,sc.<scenarioId>.position.opened) andce-subjectSHALL carry the entity reference (subject=position/BTC_USDT,subject=order/<order_id>) - AND this SHALL NOT be worked around with a broker-level wildcard subscription (e.g.
sc.<scenarioId>.>) unless the deployed pub/sub backend is confirmed to support wildcard/pattern subscriptions -- it does not today (see the requirement description above)
Scenario: act and hyp carry no universe segment
- WHEN a topic uses the
act.exchange.<venue>.*orhyp.<WORLD>.exchange.<venue>.*pattern - THEN the
hypform SHALL have exactly one more segment than theactform (the<WORLD>slot) - AND the data universe SHALL NOT appear in either topic — it travels in the
marketuniverseenvelope extension, not as a topic segment - AND brokers and wildcard subscriptions SHALL NOT assume segment-count parity between the two forms — subscribe to
act.exchange.*andhyp.*.exchange.*as two separate patterns rather than one shared positional pattern
Requirement: State Keys
State keys SHALL be derived like topics (Name Derivation requirement): scope.path.identity. The physical key is api||<key> because every write goes through virtufin-api's State service.
| Owner | Pattern | Example |
|---|---|---|
| Service | sys.<service>.<entity>[.<id>] |
sys.workmanager.worker.<worker_id>, sys.workmanager-runtime.worker.<worker_id>, sys.api.publication.fence.<worker_id>, sys.api.topic.catalog |
| Market data cache | act\|hyp.<WORLD>.exchange.<venue>.<entity>.<identity> |
act.exchange.binance.orderbook.BTC_USDT |
| Scenario state | sc.<scenarioId>.<path>.<identity> |
sc.LIVE.trading.order.<order_id> |
| Registry | cfg.<registry>.<ID>, cfg.<registry>.index |
cfg.scenario.LIVE, cfg.scenario.index |
Scenario: Order state key
- WHEN a service writes order state
- THEN the key SHALL be
sc.<scenarioId>.trading.order.<order_id> - AND the value SHALL be JSON
{ status, side, type, qty, remaining_qty, avg_price, venue, created_at, updated_at }
Scenario: Trade state key
- WHEN a service writes trade state
- THEN the key SHALL be
sc.<scenarioId>.trading.trade.<trade_id> - AND the value SHALL be JSON
{ status, order_id, cleared_at?, settled_at?, tx_hash? }
Scenario: Position state key
- WHEN a service writes position state
- THEN the key SHALL be
sc.<scenarioId>.position.<PAIR> - AND the value SHALL be JSON
{ size, avg_price, realized_pnl, liquidation_status, updated_at }
Scenario: Portfolio state key
- WHEN a service writes portfolio state
- THEN the key SHALL be
sc.<scenarioId>.position.portfolio(a lowercase literal, so it can never collide with a<PAIR>position key) - AND the value SHALL be JSON
{ total_value, total_pnl, position_count, updated_at }
Scenario: Indicator state key
- WHEN a service persists a deployed indicator's current value (e.g.
IndicatorWorkerBaseinindicator-devkit) - THEN the key SHALL be
sc.<scenarioId>.indicator.<name>.<PAIR>(e.g.sc.LIVE.indicator.sma-10.BTC_USDT) - AND the value SHALL be JSON
{ value, updated_at }(the indicator's own encoding of its current value, plus a write timestamp) - AND this key is scenario-scoped rather than market-data-cache-scoped (contrast the "Order book state key" scenario below): an indicator fed by scenario-specific replayed/synthetic data under
hyp.*needs run disambiguation two concurrent backtests of the same pair would otherwise collide on — an order book has no such need, since it's a genuinely singular venue-level fact regardless of observer
Scenario: Trading halt key
- WHEN a scenario's trading is halted or resumed (the kill switch)
- THEN the key SHALL be
sc.<scenarioId>.trading.halt(thevirtufin.trading/haltentity) - AND the value SHALL be JSON
{ halted, reason, by, at }(Trading Halt)
Scenario: Worker state key
- WHEN the WorkManager writes worker state
- THEN the key SHALL be
sys.workmanager.worker.<worker_id>, with the list of workers atsys.workmanager.worker.index - AND the value SHALL be the JSON worker record (id, code source, MIME type, topics, config, secret references, tags, status, code history)
- AND the Runtime SHALL keep its own execution copy of the worker under
sys.workmanager-runtime.worker.<worker_id>
Scenario: Connection state key
- WHEN a worker writes its own state through its context (
context.State), e.g. a WebSocketFeed worker its connection session - THEN the key SHALL be
sys.workmanager.worker.<worker_id>.state.<key>, deleted with the worker - AND a WebSocketFeed worker SHALL keep its session there (
sys.workmanager.worker.<worker_id>.state.session: publish topic, routing, replayed frames, attachments; never a credential)
Scenario: Order book state key
- WHEN a service maintains a per-pair local order book (e.g. a WorkManager worker consuming the venue's update-delta and snapshot feeds -- not the WebSocketFeed worker that relays them, which is a generic, exchange-agnostic relay with no order-book logic of its own)
- THEN the key SHALL be
act\|hyp.<WORLD>.exchange.<venue>.orderbook.<PAIR>(act omits<WORLD>) - AND the value SHALL be JSON
{ bids, asks, last_update_id, updated_at }: a consolidated snapshot per venue + pair, for display and startup (updated_atis an RFC3339 timestamp of the last applied snapshot/update). It is not the source of truth for a live book -- thechangedevent is, written at most once persaveintervalms, so the key can trail the latest event - AND on a detected sequence gap the value SHALL NOT be overwritten until a fresh snapshot resolves it (see the Market Data Events requirement's "Order book gap detected" scenario) -- the key keeps serving the last known-good book rather than being cleared
Scenario: Scenario registry key
- WHEN a service writes scenario metadata
- THEN the key SHALL be
cfg.scenario.<scenarioId>, with the registered scenarios listed atcfg.scenario.index - AND the value SHALL be the scenario triplet definition (see Scenarios spec)
Requirement: Source-of-Truth Rule
Each piece of derived or owned state SHALL have exactly one writer.
Scenario: Single publisher per status field
- WHEN two publishers attempt to write the same status field on the same entity (e.g. both writing
order.status) - THEN this SHALL be treated as a design bug — the entity has exactly one owner for status transitions
- AND consumers SHALL treat the status field as monotonically advancing through the state machine
Scenario: Single owner per derived metric
- WHEN multiple services could compute the same derived metric (e.g. portfolio total value)
- THEN exactly one aggregator SHALL own the write; other services SHALL subscribe to the topic for read access
Requirement: Delete-on-Deploy (No Deprecation)
Topic and state-key renames SHALL NOT carry a deprecation window. Old names SHALL be deleted on the same commit that introduces new names.
Scenario: Rename lifecycle
- WHEN a topic or state-key name is changed
- THEN the change SHALL be a single commit per affected repo
- AND old names SHALL be removed in the same commit (no parallel publishing under both names)
- AND the change proposal that renames them SHALL list the old → new mappings
Requirement: Multi-Publisher Tier 2
Subscribers of Tier 2 (scenario-scoped) topics SHALL NOT assume single-source. A scenario topic MAY have multiple publishers (e.g., aggregator + per-leg publisher).
Scenario: Multiple publishers on same topic
- WHEN two services publish to the same scenario topic (e.g., a strategy publishes
order.filledand a replayer also publishes the same event during replay) - THEN consumers SHALL handle events from either source
- AND
ce-sourceSHALL identify the publishing service for filtering / dedup
Requirement: Run-ID in Envelope, Not Topic
Backtest replay and parallel scenarios SHALL NOT introduce run-id segments into topics. Run isolation SHALL be achieved via the runid envelope extension.
Scenario: Parallel backtests share topic
- WHEN two backtests run concurrently against the same scenario (
sc.S7F3A9B) - THEN both SHALL publish to
sc.S7F3A9B.trading.* - AND each event SHALL carry a distinct
runidextension - AND consumers that want a single backtest's events SHALL filter by
runid
Scenario: Run-id dropped from topic
- WHEN a service migrates from
binance-depth.<run_id>to the new scheme - THEN the topic SHALL become
act.exchange.binance.orderbook.update.<PAIR>(no run-id segment) - AND the run-id SHALL travel in the
runidenvelope extension (or be omitted for production traffic)
Requirement: Subscription Implementation Pattern
Dapr-based subscribe handlers in any Virtufin service SHALL open one Dapr subscription per topic per service process and fan out the resulting event stream in-process to every interested consumer within that process. Per-call Dapr subscriptions (one per gRPC call or one per caller) are PROHIBITED because they cause the same event to be silently load-balanced across callers instead of broadcast to each.
Scenario: Multiple callers on one topic
- WHEN two gRPC clients subscribe to the same topic in the same API process
- THEN each caller SHALL receive every message on that topic (true 1:many broadcast within the process)
- AND the Dapr sidecar SHALL see exactly one subscription per topic per process
Scenario: Every replica receives every message
- WHEN a topic is subscribed in several processes, e.g. two API replicas each serving a caller
- THEN each process SHALL receive every message on the topic: the pub/sub component SHALL give every sidecar its own consumer group (
consumerID: {podName}with Dapr's Redis pub/sub), not one group shared by an app's replicas - AND there SHALL be no competing-consumer layer: Dapr has no first-class broadcast (dapr/dapr#3332), so this per-sidecar group is how broadcast is achieved, and fan-out within a process stays the process's job
Scenario: New caller arrives
- WHEN a third gRPC client subscribes to a topic that already has two subscribers in the same process
- THEN the existing Dapr subscription SHALL be reused; the new caller's in-process handler SHALL be added to the fan-out list; no new Dapr subscription SHALL be opened
Scenario: Last caller leaves
- WHEN the last gRPC client unsubscribes from a topic
- THEN the in-process fan-out registration SHALL be removed and the Dapr subscription SHALL be kept for a linger (api
PubsubSubscriptionLingerSeconds, default 10 s; 0 disposes it at once) - AND a caller that subscribes to the topic during the linger SHALL join that Dapr subscription, so a quick resubscribe never closes and reopens one (with Dapr's Redis pub/sub a closed subscription's leftover reader would take the topic's next message, common#28)
- AND once the topic has had no caller for a whole linger, the Dapr subscription SHALL be disposed; subsequent callers SHALL open a new Dapr subscription on demand
- AND messages published while the topic has no caller SHALL NOT be delivered to a later caller (no catch-up)
Scenario: New subscription starts at the stream tail
- WHEN a service process opens a new Dapr subscription for a topic (no in-process subscription for that topic exists)
- THEN it SHALL receive only messages published after the subscription opened -- no replay of entries still in the stream, and no redelivery of entries left pending by an earlier subscription
- AND there is no catch-up: messages published while the process held no subscription for the topic SHALL NOT be delivered to it, including during the brief gap of a consumer reload; consumers that need continuity SHALL reconcile from state (e.g. an order book resyncs from its next snapshot)
- AND with Dapr's Redis pub/sub (one consumer group per sidecar,
consumerID: {podName}) the process SHALL move its own consumer group to the stream tail (the id of the stream's last entry, read first;0-0for an empty stream) and ack the group's entries pending up to that id before subscribing, because Dapr resumes an existing group at itslast-delivered-id, creates a missing one at the stream start ("0"), andstreamTTLtrims only on publish - AND if the group cannot be positioned the subscribe SHALL fail rather than fall back to replay
Scenario: A closed subscription's reader takes a live message
- WHEN a closed subscription's leftover sidecar reader (daprd leaves it blocked in
XREADGROUP, common#28) takes a message published after the topic's current subscription opened, and abandons it unacked - THEN the process SHALL deliver that message to the current subscription within seconds (late and possibly out of order) and ack it, rather than drop it
- AND an abandoned entry published before the current subscription opened SHALL still be acked without delivery (no catch-up)
Scenario: Subscription with replay_since
- WHEN a caller subscribes with
replay_since(a time) on the Redis backend - THEN the gateway SHALL first deliver every entry each topic's stream still retains from that time on (the stream's own clock), oldest first, read without moving any consumer group, and then the live messages, skipping a live message the replay already delivered (matched by CloudEvent id)
- AND it SHALL refuse the subscription before sending its response headers with
FAILED_PRECONDITIONwhen the backend cannot read a stream's history and withOUT_OF_RANGEwhen a topic retains more than 1000 entries since then; replay is for low-rate topics (a worker's command topic), never for market data
Scenario: In-process exception on a subscriber
- WHEN an in-process subscriber's handler throws an exception while processing a fanned-out message
- THEN the broker SHALL continue delivering to the remaining subscribers (per-subscriber fault isolation)
- AND the failed subscriber SHALL be logged but SHALL NOT cause the message to be re-delivered to the surviving subscribers
Requirement: Dead-Letter Policy on Subscribe Exceptions
Services that consume pub/sub messages SHALL NOT silently lose a message on an uncaught processing exception, and SHALL NOT retry it either: a message the handler fails on SHALL be dead-lettered once and the consumer SHALL go on with the next message. Where this is enforced depends on the consumption model:
- A consumer of the streaming
Pubsub.SubscribegRPC API (see the "Subscription Implementation Pattern" requirement above) is one of potentially several in-process fan-out consumers per Dapr subscription; the Gateway acks Dapr's broker before any consumer processes the message, so broker-level redelivery is not available to it, and redelivering would double-process the other consumers. Such a consumer SHALL publish the original message, unchanged except for failure extensions, exactly once todlq.<topic>(Name Derivation requirement) and SHALL NOT retry the processing or the dead-letter publish. The WorkManager Runtime does this for every worker (worker-management spec, "Worker Dead Letters"). - The Gateway's own Dapr subscription is governed by the pub/sub component for messages its handler answers
Retryon: with Dapr's Redis pub/sub the entry stays pending and is redelivered once pendingprocessingTimeout, checked everyredeliverInterval(helmpubsub.redis.*), with no retry limit and no dead-letter topic; the component SHALL set only keys its type reads.DropSHALL be reserved for explicit business-logic skips (e.g., "no local worker registered for this topic"); it SHALL NOT be used to silently discard a message on an uncaught exception.
Scenario: Streaming-API consumer throws on a message
- WHEN a consumer of the streaming
Pubsub.SubscribeAPI throws processing a message on topicT - THEN the consumer SHALL publish the original message once to
dlq.T, with no retry - AND the consumer's process SHALL NOT terminate and SHALL continue processing subsequent messages
Scenario: Dead-letter publish fails
- WHEN publishing a dead letter fails
- THEN the consumer SHALL log it at error level and continue; it SHALL NOT retry the publish or block the subscription
Scenario: Explicit business-logic skip
- WHEN a handler determines the message is not relevant (e.g., no local worker on the topic) and explicitly chooses to skip it
- THEN the handler MAY return
TopicResponseAction.Dropand the message SHALL be acked with no redelivery and no dead letter
Scenario: Handler times out
- WHEN a handler does not return within
MessageHandlingPolicytimeout (default 30 s) - THEN the call SHALL be treated as a failure of that message, and the handler's process SHALL remain responsive
Requirement: State Change Events
virtufin-api's State RPCs publish a change notification when the caller opts in. Which topic that notification belongs on SHALL follow the tier the state belongs to, not the service that wrote it.
Infrastructure state — records whose owner is a platform service and whose meaning is deployment-scoped (worker registrations, connection records, leader leases) — SHALL use the Tier 0 topics sys.api.state.saved and sys.api.state.deleted, one per action.
Domain state — records that are scenario- or universe-scoped (positions, portfolios, orders, risk and P&L artefacts) — SHALL NOT use those topics. Its change notifications SHALL be published as ordinary Tier 1 events on the market-data or scenario axes, carrying the full Tier 1 envelope. Which service performed the write is an implementation detail; subscribers route on the domain topic and MUST NOT be required to track it.
The gateway cannot synthesise a Tier 1 event from a state write: it knows the store, key and value, but not the scenario, the world markers, the clock type, or the writing service's identity. A caller publishing a domain state change SHALL therefore supply the complete CloudEvent and its target topic, and the gateway SHALL publish it only after the write has succeeded.
Scenario: Infra state change
- WHEN a service writes infrastructure state with change notification enabled
- THEN the event SHALL be published to
sys.api.state.savedfor a save orsys.api.state.deletedfor a delete - AND
ce-typeSHALL becom.virtufin.api.state.savedorcom.virtufin.api.state.deleted, so a subscriber can filter by action on either the topic or the type without parsing the payload - AND
ce-sourceSHALL beurn:com.virtufin:api, the publishing service
Scenario: Domain state change
- WHEN a service writes scenario- or universe-scoped domain state with change notification enabled
- THEN the caller SHALL supply the CloudEvent and its topic, matching the Tier 1 patterns in the Topic Patterns requirement (e.g.
sc.<scenarioId>.position.snapshot) - AND the event SHALL carry the extensions required of every Tier 1 event by the Common Envelope Extensions requirement
- AND the gateway SHALL publish it only after the state write succeeds
- AND the gateway SHALL NOT additionally publish that change to
sys.api.state.saved/sys.api.state.deleted
Scenario: Domain state change without a caller-supplied event
- WHEN a caller enables change notification for domain state but supplies no CloudEvent
- THEN the gateway SHALL publish to
sys.api.state.saved/sys.api.state.deletedas for infra state - AND the resulting event is Tier 0 and carries no scenario or world markers, so subscribers cannot route it by scenario — the caller has opted out of the domain taxonomy, not into a degraded form of it
Scenario: State-name topics are not a substitute
- WHEN a design would give each state its own topic (
sys.api.state.saved.<state_name>) - THEN it SHALL be rejected: a Tier 0 topic names an entity and a kind of event, not a state, and per-key topics contradict the Cardinality Rule
- AND domain state SHALL use the Tier 1 taxonomy instead, which already provides the routing such a design is reaching for
Scenario: Change payload
- WHEN the gateway publishes to
sys.api.state.saved/sys.api.state.deleted - THEN the payload SHALL carry
service, thekey(orkeysfor a bulk delete), andaction(save/delete) - AND it SHALL carry
valueonly when the caller set the include-value flag
Scenario: Tier 0 events carry no version
- WHEN the gateway publishes a
sys.api.state.savedorsys.api.state.deletedevent - THEN it SHALL NOT claim a version for the written value: Dapr's state API returns no etag from a write, so the gateway cannot label the event with the version it just produced
- AND it SHALL NOT re-read the key to obtain one — a concurrent writer may have advanced the value in between, which would attribute a newer version to an older payload and corrupt exactly the ordering the version exists to establish
Scenario: Event-carried state transfer on the Tier 0 topic
- WHEN a subscriber uses a Tier 0 state-change event's
valueinstead of reading the state back - THEN it SHALL treat the value as advisory: with no version there is no way to detect out-of-order delivery, so two rapid writes to one key may arrive reversed under redelivery and silently regress the subscriber
- AND it SHALL do so only where writes to that key are known to be serialized, and SHALL read state back where correctness depends on freshness
- AND a subscriber needing a stronger guarantee SHALL use the Tier 1 path below, where the caller controls the envelope
Scenario: Ordering on the Tier 1 path
- WHEN a caller supplies a CloudEvent for a domain state change and subscribers consume its payload without reading state back
- THEN the caller SHALL carry a monotonic ordering token for the entity in the event (a domain version, sequence number, or
eventtimewhere the clock is authoritative) - AND subscribers SHALL discard any event not newer than the last processed for that entity
- AND the token is the caller's to supply because only the caller knows the entity's versioning; the gateway has the key and the bytes and nothing that orders them
Scenario: Delivery guarantee
- WHEN the state write succeeds and the subsequent publish fails
- THEN the change event is lost: publication is at-most-once and is not atomic with the write
- AND subscribers SHALL be designed to reconcile from state rather than assuming every change produced an event
- AND the gateway SHALL NOT report the write itself as failed on account of a failed publish, since the write did land and reporting failure invites a caller to repeat it
Requirement: Indicator Events
An indicator deployed as a worker SHALL publish each new value as a scenario-scoped event, because an indicator is a tuned analytic owned by a scenario (behaviour spec, Glossary requirement), not a world-scoped market fact.
Scenario: Indicator changed
- WHEN a deployed indicator folds a sample and has a new value
- THEN it SHALL publish
sc.<scenarioId>.indicator.<name>.changed.<PAIR>with ce-typecom.virtufin.indicator.<name>.changedandce-subjectcurrency_pair/<PAIR> - AND
<name>SHALL be the deployment's configured indicator name, built as Indicator Names requires, so two parameterisations of one indicator (sma-7x1m,sma-30x1m) publish on distinct topics - AND the payload SHALL be the indicator's own JSON encoding of its value,
{ value }for a scalar - AND the envelope SHALL follow the derived-event rule (Common Envelope Extensions requirement):
eventtimeinherited from the triggering sample, andscenarioidset to<scenarioId>
Scenario: Indicator value persisted
- WHEN an indicator publishes a changed event
- THEN it SHALL have saved the same value under the indicator state key (State Keys requirement) first, so a consumer that receives the event can read the matching state
Scenario: Indicator names
- WHEN an indicator is deployed
- THEN its name SHALL be
<kind>-<parameter>:<kind>the indicator's kind as its worker names it (sma,entropy,logreturn,absolutereturn,relativereturn,range,tradeflow,bookimbalance),<parameter>its window with the unit it counts in - AND a window of candles SHALL be written
<n>x<interval>(sma-20x1m: 20 one-minute candles), because the topic carries no candle interval andsma-20on 1 s and on 1 m candles would otherwise share one topic - AND a window of time SHALL be written in seconds, one spelling per window (
tradeflow-60s,tradeflow-300s, never5m) - AND an indicator without a window parameter SHALL be its kind alone (
bookimbalance) - AND the name SHALL be built by indicator-devkit's
IndicatorNames(C#, Python), never by hand
Requirement: Cross-Topic Delivery Ordering
Consumers SHALL NOT assume any ordering guarantee between messages published to different topics. Per the Subscription Implementation Pattern requirement, each topic is its own independent Dapr subscription with its own dispatch loop; two topics' streams interleave in whatever order messages happen to arrive from the broker, not by publish wall-clock order. Ordering guarantees (if any) apply only within a single topic and are broker-dependent.
Scenario: Strategy worker's market and position feeds
- WHEN a strategy worker subscribes to both a market-data topic and a position topic (see the multi-topic worker support in worker-management)
- THEN a market event and a related position update MAY arrive in either order
- AND a strategy that needs the two consistent with each other (e.g. "this candle's decision must see the fill it depends on") SHALL NOT assume the position update arrives first -- it must handle the out-of-order case itself (e.g. by re-evaluating on the next event) or accept the resulting staleness window
Scenario: No cross-topic sequencing infrastructure exists
- WHEN a service needs strict ordering between events on two different topics
- THEN it SHALL implement that ordering itself (e.g. via a sequence number in the envelope, or by consolidating both event kinds onto one topic) -- the platform provides no built-in mechanism for it
Requirement: Ingest Time
A frame relayed from an exchange connection SHALL carry the CloudEvents extension ingesttime (RFC3339): the real clock when the frame was received off the connection, taken before any routing or queueing. A world-scoped market-data event derived from such a frame SHALL carry the triggering frame's ingesttime unchanged. ingesttime is optional for every other event.
Scenario: Relayed frame
- WHEN a WebSocketFeed worker publishes a frame it received off its connection
- THEN the event SHALL carry
ingesttime= the receive time, and itsce-timeSHALL remain the publish time
Scenario: Derived market-data event
- WHEN a venue worker publishes an order-book
changedevent for a frame carryingingesttime - THEN the event SHALL carry the same
ingesttime, so thateventtimetoingesttimemeasures the exchange and the network, andingesttimetowalltimemeasures the pipeline from receiving the order-book diff to publishing the new book
Scenario: No ingest time
- WHEN the input of a market-data event carries no
ingesttime - THEN the event SHALL NOT carry one