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, byce-subjectorder/<id>) for symbol and side; a fill whose order has not arrived is held until it does. Eachfill_idis 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: nullmarks the symbolfee_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 limitslimit,breached),gross_notional,net_notional,quote, and with limitsgross_limit,gross_breached;risk.limit.breach, once when a limit becomes breached:limit_name(max_notional_per_symbol, subjectpair/<PAIR>;max_gross_notional, subjectposition/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.