Skip to content

Introduction

The Virtufin Lib (lib) is the .NET 10 foundational layer for the Virtufin trading platform. It provides the data model, type system, serialization format, and reactive primitives that the higher-level services (WorkManager, API Gateway) and the workers build on.

What this library is

  • A data model for trading workflows: entities, attributes, values, positions, scenarios, transactions, contracts.
  • A type system: Variant (sealed discriminated union), DecimalAmount (arbitrary-precision decimal with explicit precision), Cash (currency-aware money), Currency (12 ISO codes).
  • A serialization format: FlatBuffers schema for Variant so the same value can round-trip across C#, Python, and TypeScript SDKs.
  • A reactive layer: IObservable<T> adapters for NATS pub/sub, WebSocket frames, and Valkey keyspaces, with auto-reconnect.

What this library is not

  • Not a gRPC service. The transport is in api and workmanager; venue WebSocket connections are WebSocketFeed workers (general-workers).
  • Not a strategy engine. Strategies are external workers that call into this library.
  • Not a backtesting engine. The execution algebra is here (the IExecutor<TState, TAction, TEvent> template), but actual backtest runners are out of scope.
  • Not an exchange connector. The LiveExecutorBase in this library is a base class; subclasses route to a real exchange.

Key concepts

The EAV model

Every business entity (order, position, scenario) is an IEntity<V, I> with a typed identifier I. The entity has a name, attributes, and a value. Attributes are looked up by name; values are produced by pluggable IValueProvider<V, I> instances. See Core EAV.

The Variant type

A Variant is exactly one of: None, Bool, Int32, String, Dictionary, or nested array. Implicit conversions exist for all C# primitives (int, string, bool, long, double, decimal). The FlatBuffers schema lets a value produced in C# be deserialized in Python or TypeScript with the same shape. See Variant Type.

The DecimalAmount type

DecimalAmount is a struct of (long Whole, int Fraction, byte N) where N is the precision (number of fractional digits). Two DecimalAmount values with different N are not equal — precision is part of the value. All arithmetic uses checked semantics and throws OverflowException on overflow. Cash wraps a DecimalAmount plus a Currency and rejects mismatched-currency operations. See DecimalAmount.

The execution algebra

IExecutor<TState, TAction, TEvent> is the morphism A → IO E from the trading domain spec — given a current state and an action, produce the next state and an outcome event. Three base classes capture distinct execution strategies: DeterministicExecutorBase<TState, TAction, TEvent> (no randomness), SlippageExecutorBase<TState, TAction, TEvent> (random slippage, distribution-agnostic), LiveExecutorBase<TState, TAction, TEvent> (exchange-routing subclass). All three are abstract — subclasses define the case-by-case fill logic. ObserveOnlyExecutor<TState, TAction, TEvent> decorates any other executor and records what would have happened (for SHADOW_* scenarios).

Conventions

  • C# 14 preview features (e.g., extension syntax) are used where they reduce noise.
  • Nullable reference types are enabled — respect the annotations.
  • Generic type parameters use single uppercase letters: V for value types, I for identifier types, A for attribute types.
  • I prefix for interfaces, PascalCase for classes, _camelCase for private fields, UPPER_SNAKE_CASE for constants.
  • sealed on classes that aren't designed for inheritance (e.g., Variant).