Helpers
The devkit ships the reusable pieces a strategy worker needs. All are first-in-org implementations.
CloudEvent mappers
MarketEventJson (Virtufin.MarketData.DevKit) and
PositionEventJson (Virtufin.Trading.Contracts) map CloudEvent payloads to
the event ADTs. Position types are the naming library's
virtufin.positions/position events (portfolio-devkit's PositionNames) (com.virtufin.position.<event>, the ADT
case in lowercase kebab). The virtufin.market.* types are the ADT test and
replay contract; published market data arrives as the venue's
candle.closed (see Naming):
CloudEvent type |
Maps to |
|---|---|
virtufin.market.TickReceived |
MarketEvent.TickReceived |
virtufin.market.OrderBookReceived |
MarketEvent.OrderBookReceived |
virtufin.market.CandleClosed |
RichMarketEvent.CandleClosed |
virtufin.market.VWAPComputed |
RichMarketEvent.VWAPComputed |
virtufin.market.VolatilityEstimate |
RichMarketEvent.VolatilityEstimate |
com.virtufin.position.opened / updated / closed / flipped |
PositionEvent.* |
com.virtufin.position.updated-attributed |
RichPositionEvent.UpdatedAttributed |
com.virtufin.exchange.<venue>.candle.closed (the published candle) |
RichMarketEvent.CandleClosed |
Payloads are camelCase JSON; amounts are plain JSON numbers (parsed
exactly via decimal); timestamps are RFC 3339. Unknown types return
null (wildcard noise); a known type with a malformed payload throws.
Portfolio fold (Virtufin.Strategy.DevKit)
PortfolioState is the first concrete IPortfolioState;
PortfolioAlgebra is the first IAlgebra<IPositionEvent, TState>. It
folds position events with set semantics — Opened.Quantity,
Updated.NewQuantity and Flipped.NewQuantity set the absolute
holding, Closed zeroes it, and UpdatedAttributed applies a delta.
Quantities are tracked as integer cardinals at
PortfolioState.QuantityPrecision (8), rescaling events at other
precisions via DecimalAmount.ToCardinal(int).
Since 0.20.0 it also carries what the strategy base adds: Pending(symbol)
(the strategy's own submitted, unfilled orders, signed) and
Exposure(symbol) = Quantity + Pending, and IsKnown(symbol):
PortfolioState.Unknown knows no symbol until an absolute event sets it
(WithQuantity). FromCardinals rebuilds a saved portfolio.
Moving average
SimpleMovingAverage<TTime,TValue> moved to Virtufin.Base.Behavior
(lib) — an immutable, time-windowed SMA: Add returns a new
instance (safe inside IStrategyState records); Value throws until at
least one sample has been added. See that repo's docs for the full API
(the divisor and window-cutoff delegates, the TimestampedSample<TTime,TValue>
shape). This repo's MovingAverageCrossover example strategy
(strategy-workers) shows the inline consumption pattern.
Amount conversion
Fixed-point conversion lives in DecimalAmount itself
(Virtufin.Core 0.6.0+): From(decimal, int) (exact),
FromCardinal(long, int), ToDecimal(), and ToCardinal(int)
(precision rescale). The JSON wire mapping is Wire (Virtufin.Worker.DevKit):
ReadAmount/ReadOptionalAmount parse JSON numbers into DecimalAmount at
Wire.Precision (8), and ToDecimal() writes the exact decimal back.
Config resolution (Virtufin.Worker.DevKit)
ConfigResolution reads per-instance config from CloudEvent
extension attributes only, failing loudly on invalid values.