Skip to content

PnL

A scenario's P&L and spot exposure (openspec pubsub-topics, P&L Worker). It folds the scenario's fills into a book per symbol (quantity, average cost, realized P&L, fees), marks the held symbols to their order book mids, publishes P&L and exposure, and saves the book where the TUI's P&L and Risk panes read it. Venue-neutral: it reads the scenario's trading events and any venue's order books, and publishes events only.

Property Value
Project Virtufin.Worker.PnL
Worker type pnl
Base class Virtufin.Behavior.DevKit.BehaviorWorkerBase
Engine application/x-dotnet-dll
Input topics sc.<S>.trading.order.submitted, sc.<S>.trading.order.filled, <world>.exchange.<venue>.orderbook.changed.<PAIR> of the pairs it trades, sys.api.state.saved (its registry entry changed)
Output topics sc.<S>.pnl.realized.update, sc.<S>.pnl.unrealized.update, sc.<S>.risk.exposure.update (subject position/portfolio), sc.<S>.risk.limit.breach
State sc.<S>.pnl.book (service stateservice), the fold in worker state

Fold

  • A fill (order.filled) is joined to its order (order.submitted, by ce-subject order/<id>) for symbol and side; a fill whose order has not arrived is held until it does. Each fill_id is folded once, also across a restart or a replay.
  • Per symbol: quantity (buys add, sells subtract), average cost of the open quantity (reset when it crosses zero: the rest opens at the fill price), realized P&L on a reducing fill.
  • Fees: in the symbol's quote asset they are in the realized P&L; in its base asset they are paid out of the holding (the same cost over less quantity); any other asset is listed. A fill with fees: null marks the symbol fee_unknown.
  • Marks: the mid of the latest book of each pair. Unrealized = quantity x (mid - average cost); notional = |quantity| x mid. Totals sum the symbols in quote.

Publishing

At most once per publishintervalms, on an input, and only when a fill or a held symbol's mark changed:

  • pnl.realized.update: realized_pnl, by_symbol, period (cumulative);
  • pnl.unrealized.update: unrealized_pnl, by_symbol, mark_prices;
  • risk.exposure.update: by_symbol (qty, mark, notional, share, and with limits limit, breached), gross_notional, net_notional, quote, and with limits gross_limit, gross_breached;
  • risk.limit.breach, once when a limit becomes breached: limit_name (max_notional_per_symbol, subject pair/<PAIR>; max_gross_notional, subject position/portfolio), limit_value, actual_value, severity (warning).

Limits

The scenario's registry entry cfg.scenario.<S> (service statestore) may carry limits: { max_notional_per_symbol?, max_gross_notional? } in the quote asset. They are read at start and again on each sys.api.state.saved of that key, mark the exposure and are reported; nothing enforces them. Set them in the TUI's Scenario pane or by saving the entry.

Each publish saves the fold in worker state (a restart continues from it) and, in the background, the book at sc.<S>.pnl.book: { time, quote, symbols: { <PAIR>: { qty, avg_cost, mark, realized_pnl, unrealized_pnl, notional, fees, fee_unknown } }, realized_pnl, unrealized_pnl, fills_folded }.

Config

Key Kind Meaning
scenarioid config Required: the scenario (uppercase id).
quote config Default USDT: the quote asset of the totals.
publishintervalms config Default 1000: the least time between two publishes.
stateservice config Default workmanager: the State service of the book.

The topics are given at creation: the scenario's two trading topics, the order book changed topics of the pairs it trades and sys.api.state.saved (config/config.json is an example).

Not here

Enforcing limits, margin, greeks, drawdown alerts, a P&L history.