@usherlabs/cex-broker 0.2.44 → 0.2.46

package/dist/helpers/market-data-vendor-backfill/promotion.d.ts

@@ -0,0 +1,9 @@
+import { type BackfillArchiveRow, type PromotionReceipt, type PromotionReceiptWire } from "./contracts";
+export type StablePromotionReceipt = Omit<PromotionReceipt, "receiptId" | "verificationTimeMs">;
+export declare function promotionReceiptId(receipt: StablePromotionReceipt): string;
+type UnfinalizedPromotionReceiptWire = Omit<PromotionReceiptWire, "receipt_id" | "promotion_identity_sha256"> & Partial<Pick<PromotionReceiptWire, "receipt_id" | "promotion_identity_sha256">>;
+export declare function finalizePromotionReceipt(receipt: UnfinalizedPromotionReceiptWire): PromotionReceiptWire;
+export declare function finalizePromotionReceipt(receipt: StablePromotionReceipt, verificationTimeMs: number): PromotionReceipt;
+export declare function promotionReceiptToArchiveRow(receiptInput: PromotionReceipt | PromotionReceiptWire): BackfillArchiveRow;
+export declare function promotionReceiptFromArchiveRow(row: Record<string, unknown>): PromotionReceipt | PromotionReceiptWire;
+export {};

package/dist/helpers/market-data-vendor-backfill/qualification.d.ts

@@ -0,0 +1,20 @@
+import type { BackfillArchiveRow, FixedUtcTimestamp, Sha256Hex } from "./contracts";
+export type QualificationEvent = {
+    qualification_event_id: string;
+    capture_bundle_id: Sha256Hex;
+    state: "qualified" | "quarantined" | "revoked";
+    receipt_id: Sha256Hex;
+    promotion_identity_sha256: Sha256Hex;
+    window: {
+        start_at: FixedUtcTimestamp;
+        end_at: FixedUtcTimestamp;
+    };
+    event_at: FixedUtcTimestamp;
+    reason_code: string;
+};
+type UnfinalizedQualificationEvent = Omit<QualificationEvent, "qualification_event_id"> & Partial<Pick<QualificationEvent, "qualification_event_id">>;
+export declare function parseQualificationEvent(value: unknown): QualificationEvent;
+export declare function finalizeQualificationEvent(event: UnfinalizedQualificationEvent): QualificationEvent;
+export declare function qualificationEventToArchiveRow(eventInput: QualificationEvent): BackfillArchiveRow;
+export declare function qualificationEventFromArchiveRow(row: Record<string, unknown>): QualificationEvent;
+export {};

package/dist/helpers/market-data-vendor-backfill/selection.d.ts

@@ -0,0 +1,30 @@
+import { type ArchiveSelectionWire, type BackfillArchiveRow, type BackfillRequestWire, type MarketDataVendorBackfillRequest } from "./contracts";
+export type ArchiveQualificationEvidence = {
+    qualificationEventId: string;
+    state: "qualified" | "quarantined" | "revoked";
+    receiptId: string;
+    promotionIdentitySha256: string;
+};
+export type ArchiveSupportAnchorEvidence = {
+    captureBundleId: string;
+    rawCaptureId: string;
+    snapshotId: string;
+    sourceTimeMs: number;
+    normalizedSummaryChecksum: string;
+};
+export type ArchiveBundleEvidence = {
+    captureBundleId: string;
+    captureOrigin: "production_capture" | "vendor_historical_backfill";
+    startTimeMs: number;
+    endTimeMs: number;
+    qualification: ArchiveQualificationEvidence | null;
+    supportAnchors: ArchiveSupportAnchorEvidence[];
+};
+export declare function resolveArchiveSelection(input: {
+    request: MarketDataVendorBackfillRequest;
+    bundles: readonly ArchiveBundleEvidence[];
+    resolvedAtMs: number;
+    storedSelection?: unknown;
+}): ArchiveSelectionWire;
+export declare function archiveSelectionToArchiveRow(request: BackfillRequestWire, selectionInput: ArchiveSelectionWire): BackfillArchiveRow;
+export declare function archiveSelectionFromArchiveRow(row: Record<string, unknown>): ArchiveSelectionWire;

package/dist/helpers/market-data-vendor-backfill/semantic-verification.d.ts

@@ -0,0 +1,24 @@
+import type { BackfillArchiveRow, MarketDataVendorBackfillRequest } from "./contracts";
+export declare function semanticDigest(rows: readonly BackfillArchiveRow[]): string;
+export type SemanticPromotionEvidence = {
+    request: MarketDataVendorBackfillRequest;
+    normalizedRows: readonly BackfillArchiveRow[];
+    candidateRows: readonly BackfillArchiveRow[];
+    conflictCount: number;
+    prefixDigestBefore: string;
+    prefixDigestAfter: string;
+    suffixDigestBefore: string;
+    suffixDigestAfter: string;
+    seamVerified: boolean;
+    exporterCompatible: boolean;
+};
+export type SemanticPromotionResult = {
+    passed: boolean;
+    reasonCode: string;
+    canonicalSemanticDigest: string;
+    prefixDigest: string;
+    suffixDigest: string;
+    seamVerified: boolean;
+    coverageVerified: boolean;
+};
+export declare function verifySemanticPromotion(evidence: SemanticPromotionEvidence): SemanticPromotionResult;

package/dist/helpers/public-market-data-feed/identity.d.ts

@@ -0,0 +1,12 @@
+export type PublicFeedName = "ORDERBOOK" | "TICKER" | "TRADES" | "OHLCV";
+export type PublicFeedKeyInput = {
+    exchange: string;
+    symbol: string;
+    marketType: string;
+    feed: PublicFeedName;
+    acquisitionProfileId?: string;
+    timeframe?: string;
+};
+export declare function normalizePublicExchange(exchange: string): string;
+export declare function resolvePublicOhlcvTimeframe(timeframe: string | undefined): string;
+export declare function buildPublicFeedKey(input: PublicFeedKeyInput): string;

package/dist/helpers/public-market-data-feed/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./identity";
+export * from "./orderbook-coalescing-evidence";
+export * from "./orderbook-profile";
+export * from "./subscriber-buffer";
+export * from "./supervisor";

package/dist/helpers/public-market-data-feed/orderbook-coalescing-evidence.d.ts

@@ -0,0 +1,79 @@
+import type { OrderBookBandCoverage } from "./orderbook-profile";
+export declare const CEX_ORDERBOOK_COALESCING_EVIDENCE_SCHEMA: "cex-orderbook-coalescing-evidence/v1";
+export type CexOrderBookEvidenceVenue = "binance" | "mexc";
+export type CexPolicyVisibleOrderBookSnapshot = {
+    bids: number[][];
+    asks: number[][];
+    timestamp: number;
+    exchange: CexOrderBookEvidenceVenue;
+    symbol: string;
+    depthLimit: number;
+};
+export type CexOrderBookObservationEvidence = {
+    index: number;
+    conservative: {
+        live: CexPolicyVisibleOrderBookSnapshot;
+        rehydrated: CexPolicyVisibleOrderBookSnapshot;
+    };
+    coalesced: {
+        live: CexPolicyVisibleOrderBookSnapshot;
+        rehydrated: CexPolicyVisibleOrderBookSnapshot;
+    };
+    coverage: {
+        conservativeLive: OrderBookBandCoverage[];
+        conservativeRehydrated: OrderBookBandCoverage[];
+        coalescedLive: OrderBookBandCoverage[];
+        coalescedRehydrated: OrderBookBandCoverage[];
+    };
+    snapshotHashes: {
+        conservativeLive: string;
+        conservativeRehydrated: string;
+        coalescedLive: string;
+        coalescedRehydrated: string;
+    };
+};
+export type CexOrderBookPhysicalWorkEvidence = {
+    workers: number;
+    watchIterations: number;
+    frames: number;
+    archiveDecisions: number;
+};
+export type CexOrderBookCoalescingCaseEvidence = {
+    venue: CexOrderBookEvidenceVenue;
+    profileId: string;
+    observations: CexOrderBookObservationEvidence[];
+    cexVerdicts: {
+        logicalPayloadsEqual: true;
+        canonicalArchiveEqual: true;
+        liveReplayInputsEqual: true;
+        bandCoverageComplete: true;
+        reducedPhysicalWork: true;
+        physicalWork: {
+            conservative: CexOrderBookPhysicalWorkEvidence;
+            coalesced: CexOrderBookPhysicalWorkEvidence;
+        };
+    };
+    insufficientReplayCase: {
+        archiveDepth: number;
+        policyDepth: number;
+        rejected: true;
+        observations: Array<{
+            index: number;
+            coverage: OrderBookBandCoverage[];
+            diagnostics: string[];
+        }>;
+    };
+};
+export type CexOrderBookCoalescingEvidence = {
+    schemaVersion: typeof CEX_ORDERBOOK_COALESCING_EVIDENCE_SCHEMA;
+    policyDepth: number;
+    archiveDepth: number;
+    bandsBps: number[];
+    cases: [
+        CexOrderBookCoalescingCaseEvidence,
+        CexOrderBookCoalescingCaseEvidence
+    ];
+};
+export declare function validateCexOrderBookCoalescingEvidence(value: unknown): CexOrderBookCoalescingEvidence;
+export declare function serializeCexOrderBookCoalescingEvidence(value: unknown): Uint8Array;
+export declare function sha256CexOrderBookCoalescingEvidence(value: unknown): string;

package/dist/helpers/public-market-data-feed/orderbook-profile.d.ts

@@ -0,0 +1,54 @@
+import type { NormalizedOrderBookSnapshot } from "../order-book";
+export type OrderBookAcquisitionProfile = {
+    id: string;
+    upstreamLimit?: number;
+    upstreamOptions?: Record<string, unknown>;
+    guaranteedRetainedDepth?: number;
+    coalescingSupported: boolean;
+};
+export type OrderBookAcquisitionProfileInput = {
+    exchange: string;
+    requestedDepth: number | undefined;
+    archiveDepth: number;
+    enabledProfileIds?: ReadonlySet<string>;
+};
+export declare function resolveConservativeOrderBookAcquisitionProfile(input: OrderBookAcquisitionProfileInput): OrderBookAcquisitionProfile;
+export declare function resolveOrderBookAcquisitionProfile(input: OrderBookAcquisitionProfileInput): OrderBookAcquisitionProfile;
+export declare function projectOrderBookSnapshot(snapshot: NormalizedOrderBookSnapshot, requestedDepth: number | undefined): NormalizedOrderBookSnapshot;
+type SideCoverage = {
+    covered: boolean;
+    boundaryPrice: number;
+    farthestPrice?: number;
+    retainedCount: number;
+    exhausted: boolean;
+};
+export type OrderBookBandCoverage = {
+    covered: boolean;
+    mid: number;
+    bandBps: number;
+    bid: SideCoverage;
+    ask: SideCoverage;
+    diagnostics: string[];
+};
+export type ImmediateHedgeabilityEvidence = OrderBookBandCoverage & {
+    /** Base quantity that can be sold immediately into displayed bids. */
+    bidDepth: number;
+    /** Base quantity that can be bought immediately from displayed asks. */
+    askDepth: number;
+    limitingSide: "bid" | "ask" | "balanced";
+    liquidityCap: number;
+};
+export declare function evaluateOrderBookBandCoverage(snapshot: Pick<NormalizedOrderBookSnapshot, "bids" | "asks">, bandBps: number, options?: {
+    bidExhausted?: boolean;
+    askExhausted?: boolean;
+}): OrderBookBandCoverage;
+/**
+ * Derives the L2 inputs used to cap immediately hedgeable counterpart liquidity.
+ * A result is exact only when `covered` is true; otherwise the two depth values
+ * are conservative lower bounds because the retained book ends inside the band.
+ */
+export declare function evaluateImmediateHedgeability(snapshot: Pick<NormalizedOrderBookSnapshot, "bids" | "asks">, bandBps: number, options?: {
+    bidExhausted?: boolean;
+    askExhausted?: boolean;
+}): ImmediateHedgeabilityEvidence;
+export {};

package/dist/helpers/public-market-data-feed/subscriber-buffer.d.ts

@@ -0,0 +1,31 @@
+import type { SubscriptionType } from "../constants";
+export type PublicFeedFrame = {
+    data: string;
+    timestamp: number;
+    symbol: string;
+    type: SubscriptionType;
+};
+export declare const PUBLIC_FEED_SUBSCRIBER_FRAME_LIMIT = 16;
+export declare const PUBLIC_FEED_SUBSCRIBER_BYTE_LIMIT: number;
+export declare const PUBLIC_FEED_SUBSCRIBER_OVERFLOW_ERROR = "Public market-data subscriber fell behind";
+/** Returns the proto3 wire size of the complete SubscribeResponse message. */
+export declare function encodeSubscribeResponseWireSize(response: PublicFeedFrame): number;
+export type PublicFeedSubscriberBufferOptions = {
+    /** Test-only override. Production callers omit this value. */
+    frameLimit?: number;
+    /** Test-only override. Production callers omit this value. */
+    byteLimit?: number;
+};
+/** Fixed-capacity O(1) FIFO for disposable public gRPC subscriber frames. */
+export declare class PublicFeedSubscriberBuffer implements AsyncIterable<PublicFeedFrame> {
+    #private;
+    readonly frameLimit: number;
+    readonly byteLimit: number;
+    constructor(options?: PublicFeedSubscriberBufferOptions);
+    get queuedFrames(): number;
+    get queuedBytes(): number;
+    enqueue(frame: PublicFeedFrame): boolean;
+    close(): void;
+    fail(error: Error): void;
+    [Symbol.asyncIterator](): AsyncIterator<PublicFeedFrame>;
+}

package/dist/helpers/public-market-data-feed/supervisor.d.ts

@@ -0,0 +1,82 @@
+import type { Metadata } from "@grpc/grpc-js";
+import type { Exchange } from "@usherlabs/ccxt";
+import { type BrokerPoolEntry } from "../broker";
+import type { BrokerExecutionArchiver } from "../broker-execution-archive";
+import { type OhlcvArchiveInput, type OhlcvBarTracker, type OrderbookArchiveInput, type TickerArchiveInput, type TradesArchiveInput } from "../market-data-archive";
+import { type BrokerMarketType } from "../market-type";
+import type { OtelMetrics } from "../otel";
+import { type PublicFeedName } from "./identity";
+import { type OrderBookAcquisitionProfile, type OrderBookAcquisitionProfileInput } from "./orderbook-profile";
+import { type PublicFeedFrame, type PublicFeedSubscriberBufferOptions } from "./subscriber-buffer";
+export type PublicFeedArchiveContext = {
+    deploymentId: string;
+    exchange: string;
+    symbol: string;
+    assetType: BrokerMarketType;
+    accountSelector?: string;
+};
+export interface PublicMarketDataArchiveSink {
+    orderbook(input: OrderbookArchiveInput, options: {
+        sampledOut: boolean;
+    }): void;
+    ticker(input: TickerArchiveInput): void;
+    trades(input: TradesArchiveInput): void;
+    ohlcv(tracker: OhlcvBarTracker, input: OhlcvArchiveInput): void;
+    ohlcvBootstrap(tracker: OhlcvBarTracker, input: OhlcvArchiveInput): void;
+}
+type Metrics = Pick<OtelMetrics, "recordCounter"> & Partial<Pick<OtelMetrics, "recordGauge">>;
+export type PublicMarketDataFeedSupervisorOptions = {
+    brokers: Record<string, BrokerPoolEntry>;
+    brokerArchiver?: BrokerExecutionArchiver;
+    otelMetrics?: OtelMetrics;
+    archiveSink?: PublicMarketDataArchiveSink;
+    metrics?: Metrics;
+    bufferLimits?: PublicFeedSubscriberBufferOptions;
+    retirementTimeoutMs?: number;
+    createRequestBroker?: (exchange: string, metadata: Metadata | undefined) => Exchange | null;
+    createPublicBroker?: (exchange: string) => Exchange | null;
+    resolveOrderBookProfile?: (input: OrderBookAcquisitionProfileInput) => OrderBookAcquisitionProfile;
+    enabledOrderBookProfileIds?: ReadonlySet<string>;
+    observer?: PublicMarketDataFeedObserver;
+};
+export type PublicFeedObservation = {
+    key: string;
+    exchange: string;
+    feed: PublicFeedName;
+    marketType: BrokerMarketType;
+    profile?: string;
+    subscriberCount: number;
+};
+export interface PublicMarketDataFeedObserver {
+    workerStarted?(observation: PublicFeedObservation): void;
+    subscriberAttached?(observation: PublicFeedObservation): void;
+    physicalFrame?(observation: PublicFeedObservation): void;
+    archiveDecision?(observation: PublicFeedObservation): void;
+    delivered?(observation: PublicFeedObservation): void;
+    overflow?(observation: PublicFeedObservation): void;
+    workerRetired?(observation: PublicFeedObservation): void;
+}
+export type PublicFeedSubscribeOptions = {
+    exchange: string;
+    symbol: string;
+    marketType?: string;
+    feed: PublicFeedName;
+    depthLimit?: number;
+    timeframe?: string;
+    bootstrapLimit?: number;
+    metadata?: Metadata;
+};
+export interface PublicMarketDataSubscription extends AsyncIterable<PublicFeedFrame> {
+    readonly key: string;
+    readonly acquisitionProfileId?: string;
+    close(): void;
+}
+/** Owns one physical public CCXT watch/archive path per canonical runtime key. */
+export declare class PublicMarketDataFeedSupervisor {
+    #private;
+    private readonly options;
+    constructor(options: PublicMarketDataFeedSupervisorOptions);
+    subscribe(input: PublicFeedSubscribeOptions): Promise<PublicMarketDataSubscription>;
+    close(): Promise<void>;
+}
+export {};

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export default class CEXBroker {
     private userAssetArchivePoller?;
     private balanceUpdateArchiveConsumer?;
     private userDataStreamSupervisor?;
+    private publicMarketDataFeedSupervisor?;
     /**
      * Loads environment variables prefixed with CEX_BROKER_
      * Expected format: