Repository Public
1// SP Wallet Core2// File: Sources/SPWalletCore/Domains/Ops/QuoteStreamProtocol.swift3// Description: Wire protocol (version 1) of the live quote stream, ported from services/api/src/quotes/protocol.ts and4// shared.ts: channels, client and server messages, close codes, the book checksum (CRC-32), decimal comparison5// without floats, delta application, the reconnect delay, and the freshness rule of apps/web/src/quotes.ts.6// READ-ONLY public market data. Every price, size and rate is the server's canonical decimal STRING; a field the7// source does not publish is nil — nothing is interpolated, defaulted or carried over.8//9// Author: Simon-Pierre Boucher10// Contact: contact@spboucher.ai11import Foundation1213public enum QuoteProtocol {14 public static let version = 115 /** The server sends a `heartbeat` frame this often; a client that sees no frame for 2.5 periods reconnects. */16 public static let heartbeatMs = 15_00017 public static let bookDepths = [5, 10, 20]18 public static let candleIntervals = ["1m", "5m", "15m", "1h", "4h", "1d"]19 /** Levels per side covered by the book checksum. */20 public static let checksumLevels = 1021 /** Channels per subscribe / unsubscribe frame accepted by the server. */22 public static let maxChannelsPerFrame = 20023 public static let path = "/api/v1/stream"2425 /** Close codes of the stream (4000–4999 is the application range of RFC 6455). */26 public enum Close {27 /** The server is shutting down or restarting: reconnect. */28 public static let goingAway = 100129 /** Frame larger than the limit. */30 public static let tooBig = 100931 /** Too many stream connections for this principal (sent when two handshakes raced past the gate). */32 public static let tryAgainLater = 101333 /** The session ended (logout, expiry, revoked device): do NOT reconnect with the same credential. */34 public static let unauthorized = 400135 public static let rateLimited = 400236 public static let slowConsumer = 400337 /** Nothing subscribed and nothing sent for the idle timeout. */38 public static let idle = 400439 public static let deadPeer = 400540 /** Protocol violation repeated. */41 public static let `protocol` = 400642 }4344 // MARK: helpers shared by value with the server (shared.ts)4546 private static let crcTable: [UInt32] = (0..<256).map { n in47 var c = UInt32(n)48 for _ in 0..<8 { c = c & 1 == 1 ? 0xedb8_8320 ^ (c >> 1) : c >> 1 }49 return c50 }51 /** CRC-32 (IEEE) of an ASCII string. */52 public static func crc32(_ s: String) -> UInt32 {53 var c: UInt32 = 0xffff_ffff54 for u in s.utf16 { c = crcTable[Int((c ^ UInt32(u)) & 0xff)] ^ (c >> 8) }55 return c ^ 0xffff_ffff56 }57 /** CRC-32 of `p:s|p:s…;p:s|…` over the best 10 levels of each side (bids first), the decimal strings exactly as sent. */58 public static func bookChecksum(bids: [StreamLevel], asks: [StreamLevel]) -> UInt32 {59 func side(_ l: [StreamLevel]) -> String { l.prefix(checksumLevels).map { "\($0.price):\($0.size)" }.joined(separator: "|") }60 return crc32("\(side(bids));\(side(asks))")61 }62 /** Compares two canonical decimal strings without a float: −1, 0 or 1. */63 public static func compareDecimal(_ a: String, _ b: String) -> Int {64 let na = a.hasPrefix("-"), nb = b.hasPrefix("-")65 if na != nb { return na ? -1 : 1 }66 func parts(_ x: Substring) -> (Substring, Substring) {67 guard let dot = x.firstIndex(of: ".") else { return (x, "") }68 return (x[..<dot], x[x.index(after: dot)...])69 }70 func magnitude(_ x: Substring, _ y: Substring) -> Int {71 let (xi, xf) = parts(x), (yi, yf) = parts(y)72 if xi.count != yi.count { return xi.count < yi.count ? -1 : 1 }73 if xi != yi { return xi < yi ? -1 : 1 }74 let n = max(xf.count, yf.count)75 let pf = xf + String(repeating: "0", count: n - xf.count), qf = yf + String(repeating: "0", count: n - yf.count)76 return pf == qf ? 0 : (pf < qf ? -1 : 1)77 }78 let r = magnitude(na ? a.dropFirst() : Substring(a), nb ? b.dropFirst() : Substring(b))79 return na ? -r : r80 }81 /** Applies a delta to one side: a size of "0" removes the price; the result is sorted (bids descending, asks ascending) and cut at `depth`. */82 public static func applyLevels(_ levels: [StreamLevel], changes: [StreamLevel], bids: Bool, depth: Int) -> [StreamLevel] {83 if changes.isEmpty { return Array(levels.prefix(depth)) }84 var order: [String] = [], sizes: [String: String] = [:]85 for l in levels { if sizes[l.price] == nil { order.append(l.price) }; sizes[l.price] = l.size }86 for c in changes {87 if c.size == "0" { sizes[c.price] = nil }88 else { if sizes[c.price] == nil, !order.contains(c.price) { order.append(c.price) }; sizes[c.price] = c.size }89 }90 let out = order.compactMap { p in sizes[p].map { StreamLevel(price: p, size: $0) } }91 .sorted { bids ? compareDecimal($0.price, $1.price) > 0 : compareDecimal($0.price, $1.price) < 0 }92 return Array(out.prefix(depth))93 }94 /** Reconnect delay in milliseconds: `min · 2^attempt` capped at `max`, with full jitter in the upper half. `random` in 0…1. */95 public static func backoffMs(attempt: Int, min: Double = 1000, max: Double = 30_000, random: Double) -> Double {96 Swift.min(max, min * pow(2, Double(Swift.min(Swift.max(attempt, 0), 16)))) * (0.5 + 0.5 * random)97 }98}99100// MARK: channels101102public enum StreamChannelType: String, Codable, Sendable, CaseIterable { case quote, book, trades, candle, status }103104/** One subscription. `id` is `venue:symbol` (`hyperliquid:BTC`, `dydx:BTC-USD`, `spot:BTC`…); for `status`, `*` or a venue id. */105public struct StreamChannel: Codable, Sendable, Hashable {106 public let type: StreamChannelType107 public let id: String108 /** Book only: levels per side (5, 10 or 20; the server's default is 20). */109 public let depth: Int?110 /** Candle only (the server's default is 1m). */111 public let interval: String?112113 public static func quote(_ id: String) -> StreamChannel { StreamChannel(type: .quote, id: id, depth: nil, interval: nil) }114 public static func book(_ id: String, depth: Int = 20) -> StreamChannel { StreamChannel(type: .book, id: id, depth: depth, interval: nil) }115 public static func trades(_ id: String) -> StreamChannel { StreamChannel(type: .trades, id: id, depth: nil, interval: nil) }116 public static func candle(_ id: String, interval: String = "1m") -> StreamChannel { StreamChannel(type: .candle, id: id, depth: nil, interval: interval) }117 public static func status(_ venue: String = "*") -> StreamChannel { StreamChannel(type: .status, id: venue, depth: nil, interval: nil) }118119 /** `type|id|param` — the identity of a subscription on both sides of the socket (`channelKey`). */120 public var key: String {121 switch type {122 case .book: "\(type.rawValue)|\(id)|\(depth ?? 20)"123 case .candle: "\(type.rawValue)|\(id)|\(interval ?? "1m")"124 default: "\(type.rawValue)|\(id)|"125 }126 }127128 /** What the server's schema accepts; a channel that fails here would be answered `bad_message` and counted as a violation. */129 public var isValid: Bool {130 let allowed = CharacterSet(charactersIn: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789*._:/[] -")131 guard !id.isEmpty, id.utf8.count <= 80, id.unicodeScalars.allSatisfy(allowed.contains) else { return false }132 if let depth, !QuoteProtocol.bookDepths.contains(depth) { return false }133 if let interval, !QuoteProtocol.candleIntervals.contains(interval) { return false }134 return true135 }136}137138/** `[price, size]` on the wire. */139public struct StreamLevel: Codable, Sendable, Hashable {140 public let price: String141 public let size: String142 public init(price: String, size: String) { self.price = price; self.size = size }143 public init(from decoder: Decoder) throws {144 var c = try decoder.unkeyedContainer()145 price = try c.decode(String.self); size = try c.decode(String.self)146 }147 public func encode(to encoder: Encoder) throws { var c = encoder.unkeyedContainer(); try c.encode(price); try c.encode(size) }148}149150public enum StreamVenueState: Sendable, Hashable, Codable {151 case connected, reconnecting, stale, down, idle152 case unknown(String)153 public var rawValue: String {154 switch self { case .connected: "connected"; case .reconnecting: "reconnecting"; case .stale: "stale"; case .down: "down"; case .idle: "idle"; case .unknown(let s): s }155 }156 public init(rawValue: String) {157 switch rawValue {158 case "connected": self = .connected; case "reconnecting": self = .reconnecting; case "stale": self = .stale159 case "down": self = .down; case "idle": self = .idle; default: self = .unknown(rawValue)160 }161 }162 public init(from decoder: Decoder) throws { self.init(rawValue: try decoder.singleValueContainer().decode(String.self)) }163 public func encode(to encoder: Encoder) throws { var c = encoder.singleValueContainer(); try c.encode(rawValue) }164 /** The venue's figures are no longer maintained. An unknown state is treated as troubled: never as healthy. */165 public var isTroubled: Bool { switch self { case .connected, .idle: false; default: true } }166}167168// MARK: server → client data169170public struct StreamQuoteMessage: Codable, Sendable, Hashable {171 public let id: String172 public let bid: String?173 public let bidSize: String?174 public let ask: String?175 public let askSize: String?176 /** (bid + ask) / 2 when the source gives both sides, else the venue's own mid; nil when it gives neither. */177 public let mid: String?178 public let mark: String?179 public let index: String?180 public let last: String?181 /** Per funding interval of the venue, as the venue publishes it. */182 public let funding: String?183 public let openInterest: String?184 /** Fraction (0.01 = 1 %). */185 public let change24h: String?186 public let volume24h: String?187 /** The venue's own timestamp (ms) of the newest part of this quote; nil when the venue gives none. */188 public let venueTs: Int64?189 /** When the server received the newest part (ms, the server's clock). */190 public let recvTs: Int64191 /** Per channel, increasing; a jump means conflated updates, never lost state. */192 public let seq: Int64193 /** `hyperliquid-ws`, `coinbase-ws`, `coingecko-rest`… */194 public let source: String195 /** The server's verdict when the frame was built. */196 public let stale: Bool197}198199public struct StreamBookMessage: Codable, Sendable, Hashable {200 public let id: String201 public let depth: Int202 /** `snapshot` (replace) or `delta` (changed prices only; a size of "0" removes the price). */203 public let kind: String204 public let bids: [StreamLevel]205 public let asks: [StreamLevel]206 public let seq: Int64207 /** A delta applies only when this is the `seq` of the last message applied. */208 public let prevSeq: Int64?209 /** CRC-32 of the best 10 levels per side AFTER this message. */210 public let checksum: UInt32211 public let venueTs: Int64?212 public let recvTs: Int64213 public let source: String214 public let stale: Bool215}216217public struct StreamTrade: Codable, Sendable, Hashable, Identifiable {218 public let id: String219 public let price: String220 public let size: String221 /** `buy` or `sell`. */222 public let side: String223 /** The venue's time of the trade (ms). */224 public let ts: Int64225}226227public struct StreamTradeMessage: Codable, Sendable, Hashable {228 public let id: String229 /** Oldest first. */230 public let trades: [StreamTrade]231 public let seq: Int64232 public let recvTs: Int64233 public let source: String234 /** True for recent history sent with a subscription (not live prints). */235 public let snapshot: Bool?236}237238public struct StreamCandleMessage: Codable, Sendable, Hashable {239 public let id: String240 public let interval: String241 /** Open time of the bar (ms); the bar is in progress until a bar with a later `ts` arrives. */242 public let ts: Int64243 public let open: String244 public let high: String245 public let low: String246 public let close: String247 public let volume: String248 public let seq: Int64249 public let recvTs: Int64250 public let source: String251}252253public struct StreamVenueStatus: Codable, Sendable, Hashable {254 public let venue: String255 public let status: StreamVenueState256 public let since: Int64257 /** Age of the last message the server received from the venue; nil before the first one. */258 public let ageMs: Int64?259 /** `stream` or `poll`. */260 public let transport: String261 public let source: String262 public let detail: String?263 public let ts: Int64264}265266public struct StreamHello: Codable, Sendable, Hashable {267 public struct Limits: Codable, Sendable, Hashable {268 public let maxSubscriptions: Int269 public let maxFrameBytes: Int270 public let maxMessagesPerSec: Int271 public let idleTimeoutMs: Int272 }273 public let connId: String274 public let heartbeatMs: Int275 public let serverTs: Int64276 public let limits: Limits277}278279public struct StreamChannelEcho: Codable, Sendable, Hashable {280 public let type: String281 public let id: String282 public let depth: Int?283 public let interval: String?284 public var key: String {285 switch type {286 case "book": "\(type)|\(id)|\(depth ?? 20)"287 case "candle": "\(type)|\(id)|\(interval ?? "1m")"288 default: "\(type)|\(id)|"289 }290 }291}292293public struct StreamSubscribed: Codable, Sendable, Hashable {294 public let channel: StreamChannelEcho295 public let key: String296 /** A quote of this channel is stale once it is older than this (re-evaluated with the client's own clock). */297 public let staleAfterMs: Int64?298 public let source: String?299 /** The last known value (a quote, a book snapshot, a trade batch, a candle, or the status list); nil when nothing was received yet. */300 public let snapshot: JSONValue?301 public let snapshotAgeMs: Int64?302}303304/** An `error` frame. Stable codes: bad_frame, bad_message, unsupported_version, unknown_instrument, unsupported_channel, restricted, too_many_subscriptions, rate_limited, upstream_unavailable, internal. */305public struct StreamErrorMessage: Codable, Sendable, Hashable {306 public let code: String307 public let message: String308 public let channel: StreamChannelEcho?309 /** These codes mean the channel will never be served on this connection or the next: it is not subscribed again. */310 public var isPermanentForChannel: Bool { ["unknown_instrument", "unsupported_channel", "restricted"].contains(code) }311}312313/** One decoded server frame. */314public enum StreamServerMessage: Sendable, Hashable, Decodable {315 case hello(StreamHello)316 case subscribed(StreamSubscribed)317 case unsubscribed(key: String)318 case quote(StreamQuoteMessage)319 case book(StreamBookMessage)320 case trade(StreamTradeMessage)321 case candle(StreamCandleMessage)322 case status(StreamVenueStatus)323 /** Trades the server did NOT send because this client is slow. */324 case dropped(id: String, count: Int, total: Int)325 case heartbeat(ts: Int64, subscriptions: Int)326 case pong(t: Double?, ts: Int64)327 case error(StreamErrorMessage)328 /** A frame type added by a newer server: ignored, never guessed at. */329 case unknown(String)330331 private enum Keys: String, CodingKey { case v, type, key, id, count, total, ts, subscriptions, t }332333 public init(from decoder: Decoder) throws {334 let c = try decoder.container(keyedBy: Keys.self)335 let v = try c.decode(Int.self, forKey: .v)336 guard v == QuoteProtocol.version else { throw DecodingError.dataCorruptedError(forKey: .v, in: c, debugDescription: "protocol version \(v)") }337 let type = try c.decode(String.self, forKey: .type)338 switch type {339 case "hello": self = .hello(try StreamHello(from: decoder))340 case "subscribed": self = .subscribed(try StreamSubscribed(from: decoder))341 case "unsubscribed": self = .unsubscribed(key: try c.decode(String.self, forKey: .key))342 case "quote": self = .quote(try StreamQuoteMessage(from: decoder))343 case "book": self = .book(try StreamBookMessage(from: decoder))344 case "trade": self = .trade(try StreamTradeMessage(from: decoder))345 case "candle": self = .candle(try StreamCandleMessage(from: decoder))346 case "status": self = .status(try StreamVenueStatus(from: decoder))347 case "dropped": self = .dropped(id: try c.decode(String.self, forKey: .id), count: try c.decode(Int.self, forKey: .count), total: try c.decode(Int.self, forKey: .total))348 case "heartbeat": self = .heartbeat(ts: try c.decode(Int64.self, forKey: .ts), subscriptions: try c.decode(Int.self, forKey: .subscriptions))349 case "pong": self = .pong(t: try c.decodeIfPresent(Double.self, forKey: .t), ts: try c.decode(Int64.self, forKey: .ts))350 case "error": self = .error(try StreamErrorMessage(from: decoder))351 default: self = .unknown(type)352 }353 }354355 public static func decode(_ text: String) throws -> StreamServerMessage { try JSONDecoder().decode(StreamServerMessage.self, from: Data(text.utf8)) }356}357358// MARK: client → server359360enum StreamClientMessage: Encodable, Sendable {361 case subscribe([StreamChannel])362 case unsubscribe([StreamChannel])363 case ping(t: Double)364365 private enum Keys: String, CodingKey { case v, op, channels, t }366 func encode(to encoder: Encoder) throws {367 var c = encoder.container(keyedBy: Keys.self)368 try c.encode(QuoteProtocol.version, forKey: .v)369 switch self {370 case .subscribe(let ch): try c.encode("subscribe", forKey: .op); try c.encode(ch, forKey: .channels)371 case .unsubscribe(let ch): try c.encode("unsubscribe", forKey: .op); try c.encode(ch, forKey: .channels)372 case .ping(let t): try c.encode("ping", forKey: .op); try c.encode(t, forKey: .t)373 }374 }375 var text: String { String(decoding: (try? APICoding.encoder().encode(self)) ?? Data(), as: UTF8.self) }376}377378// MARK: what the client holds, with its freshness379380/** The state of the client's own connection. */381public enum QuoteStreamState: Sendable, Hashable {382 /** Not started, stopped, or closed by the server for being idle. */383 case idle384 case connecting385 /** Greeted by the server (`hello`): subscriptions are (re)sent and data flows. */386 case live387 /** The connection was lost; a new attempt is scheduled after `delayMs`. Everything held is no longer maintained. */388 case reconnecting(attempt: Int, delayMs: Int)389 /** The stream will not reconnect by itself. */390 case ended(QuoteStreamEnd)391}392393public enum QuoteStreamEnd: Sendable, Hashable {394 /** No session token: nothing was sent. */395 case signedOut396 /** The server closed with 4001 or refused the handshake with 401: the session ended. Re-check the session; never retry with the same credential. */397 case unauthorized398 /** The handshake was refused for a reason a retry cannot fix (403: `origin_refused`). */399 case refused(status: Int)400}401402public enum StreamFreshnessState: String, Sendable, Codable { case live, delayed, stale, reconnecting, none }403404/** live / delayed / stale / reconnecting for one value, with its age — the server's verdict AND this device's clock (`freshnessOf`). */405public struct StreamFreshness: Sendable, Hashable {406 public let state: StreamFreshnessState407 public let ageMs: Int64?408 /** Only `live` may be presented as a live figure. */409 public var isLive: Bool { state == .live }410411 /** Shown as « delayed » past this age, before the source's own staleness bound. */412 public static let delayedAfterMs: Int64 = 5000413414 /**415 - Parameters:416 - freshAt: when the figure was fresh on THIS clock (arrival, minus the snapshot's age and the source's own lag); nil when there is no value.417 - serverStale: the `stale` flag of the frame.418 - staleAfterMs: the cadence of the source (`subscribed.staleAfterMs`); 30 s when the server gave none.419 - venue: the state of the value's upstream as the server reports it.420 A stream that is not live never yields `live`; one that ended or was stopped yields `stale` at once.421 */422 public static func evaluate(freshAt: Date?, serverStale: Bool, staleAfterMs: Int64?, connection: QuoteStreamState, now: Date, venue: StreamVenueState? = nil) -> StreamFreshness {423 let isLive = connection == .live424 guard let freshAt else {425 switch connection { case .connecting, .reconnecting: return StreamFreshness(state: .reconnecting, ageMs: nil); default: return StreamFreshness(state: .none, ageMs: nil) }426 }427 let age = max(0, Int64((now.timeIntervalSince(freshAt) * 1000).rounded())), bound = staleAfterMs ?? 30_000, troubled = venue?.isTroubled ?? false428 if age > bound || (serverStale && isLive && !troubled) { return StreamFreshness(state: .stale, ageMs: age) }429 switch connection {430 case .idle, .ended: return StreamFreshness(state: .stale, ageMs: age) // nobody is coming back for this figure431 case .connecting, .reconnecting: return StreamFreshness(state: .reconnecting, ageMs: age)432 case .live: break433 }434 if troubled { return StreamFreshness(state: .reconnecting, ageMs: age) }435 return StreamFreshness(state: age > min(delayedAfterMs, bound / 2) ? .delayed : .live, ageMs: age)436 }437}438439/** A quote as received, plus when it was fresh on this device's clock. It is never a live figure by itself: ask `freshness`. */440public struct LiveQuote: Sendable, Hashable {441 public let quote: StreamQuoteMessage442 /** Arrival on this clock, minus the snapshot's age and minus the lag the server measured between the source's own date and its receipt. */443 public let freshAt: Date444 public let staleAfterMs: Int64?445 public var id: String { quote.id }446 public var venue: String { String(quote.id.prefix { $0 != ":" }) }447448 public func freshness(connection: QuoteStreamState, now: Date, venue: StreamVenueState? = nil) -> StreamFreshness {449 .evaluate(freshAt: freshAt, serverStale: quote.stale, staleAfterMs: staleAfterMs, connection: connection, now: now, venue: venue)450 }451}452453/** A book the client rebuilt: only produced when every delta applied in sequence and the checksum matched. */454public struct LiveBook: Sendable, Hashable {455 public let id: String456 public let depth: Int457 public let bids: [StreamLevel]458 public let asks: [StreamLevel]459 public let seq: Int64460 public let freshAt: Date461 public let venueTs: Int64?462 public let source: String463 public let stale: Bool464 public var key: String { "book|\(id)|\(depth)" }465}466