Skip to content

Adding a venue: Alpaca

This walkthrough shows how the Alpaca venue and its workers got their names. A venue's names live in one fragment in market-data-devkit, naming/virtufin.venue.<venue>.yaml. That fragment also declares the worker types of the venue's workers. The worker repos add no fragment of their own, and no central file changes.

1. The fragment

market-data-devkit/naming/virtufin.venue.alpaca.yaml:

fragment: virtufin.venue.alpaca
imports: [virtufin.market]

venues:
  alpaca:
    symbol: "{BASE}/{QUOTE}"          # BTC_USD <-> BTC/USD

bind:
  # Partial application: the venue-generic families with venue = alpaca.
  orderbook: {entity: virtufin.market/orderbook, with: {venue: alpaca}}
  trade: {entity: virtufin.market/trade, with: {venue: alpaca}}

workers:
  alpacaorderbook:
    consumes: [orderbook.update]
    produces: [orderbook.changed]
  alpacatrades:
    consumes: [trade.update]
    produces: [trade.executed]

Virtufin.MarketData.DevKit embeds it under naming/ and loads it by default, and virtufin-marketdata-devkit ships it through the virtufin.naming entry point. A new worker for the venue adds its type to workers here, in the same release as the worker.

A workers entry can only reference families of fragments it imports. The raw feeds (orderbook.update, trade.update, candle.update, all per pair, the candle also per interval) are published by a WebSocketFeed worker that serves those topics: market-data-devkit's venue preset (feeds/<venue>.json) maps each family to a channel, and the topic rules the feed matches are rendered from this fragment's bound entities, so no topic is written by hand. The feed's own fragment, virtufin.worker.websocketfeed (general-workers), names only the frame's ce-type, so the venue fragment declares nothing for it. A new venue is this fragment plus a preset; the feed's code never changes.

2. The names it gets

Name Value
raw feed topic (consumed) act.exchange.alpaca.orderbook.update
changed topic act.exchange.alpaca.orderbook.changed.BTC_USD
state key act.exchange.alpaca.orderbook.BTC_USD
ce-subject currency_pair/BTC_USD
ce-type com.virtufin.exchange.alpaca.orderbook.changed
worker response / error wrk.alpacaorderbook.response / wrk.alpacaorderbook.error
worker metrics (pushed counters) wrk.alpacaorderbook.metrics
venue symbol of BTC_USD BTC/USD

3. The code

The worker composes its registry from the assemblies that own the fragments it uses (DomainNames.For of domain-devkit adds virtufin.worlds, which virtufin.market imports):

var names = DomainNames.For(typeof(AlpacaOrderBookWorker), typeof(MarketNames).Assembly);
var book = MarketNames.At(MarketNames.OrderBook, "alpaca", names);
var alpaca = names.GetVenue("alpaca");

foreach (var pair in config.Pairs)                       // canonical: BTC_USD
{
    var symbol = alpaca.ToVenueSymbol(pair);             // BTC/USD, for the Alpaca API
    var topic = book.Topic("changed", World.Act, pair);  // act.exchange.alpaca.orderbook.changed.BTC_USD
    var key = book.Key(World.Act, pair);
}

// Incoming venue symbol back to the canonical pair, among the configured pairs.
alpaca.TryFromVenueSymbol("BTC/USD", config.Pairs, out var canonical);

The generic entity can also be bound in code, without a fragment: names.GetEntity("virtufin.market/orderbook").Bind(venue). Only the fragment makes the family visible to the docs and to the conflict check, so every venue has one.

4. What protects everyone else

  • The fragment cannot change existing names: composition adds families and never edits them. The conformance suite checks that every Binance name is unchanged after the Alpaca fragment is added.
  • If another fragment also declared venue alpaca, bound the order book to alpaca again, or declared one of its worker types, composition would fail with a message naming both fragments, and so would the specs site build.
  • A fragment id composes only once, unless the copies are identical. Worker builds from before the venue fragments moved to market-data-devkit embed an older copy. Once the fragment changes, those builds no longer compose with the current Virtufin.MarketData.DevKit (AlpacaOrderBook ≤ 0.9.2, AlpacaTrades ≤ 0.5.4 since market-data-devkit 0.15.1).