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 toalpacaagain, 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).