Skip to content

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.