@usherlabs/cex-broker 0.2.17 → 0.2.19

package/dist/handlers/execute-action/context.d.ts

@@ -3,6 +3,7 @@ import type { Metadata } from "@grpc/grpc-js";
 import type { Exchange } from "@usherlabs/ccxt";
 import type { z } from "zod";
 import type { BrokerAccount, BrokerPoolEntry } from "../../helpers";
+import type { BrokerExecutionArchiver } from "../../helpers/broker-execution-archive";
 import type { Action as ActionType } from "../../helpers/constants";
 import type { OtelMetrics } from "../../helpers/otel";
 import type { PolicyConfig } from "../../types";
@@ -27,6 +28,7 @@ export type ExecuteActionContext = {
     useVerity: boolean;
     verityProverUrl: string;
     otelMetrics?: OtelMetrics;
+    brokerArchiver?: BrokerExecutionArchiver;
 };
 export declare function requireSymbol(ctx: ExecuteActionContext, message?: string): ctx is ExecuteActionContext & {
     symbol: string;

package/dist/handlers/execute-action/handler.d.ts

@@ -1,5 +1,6 @@
 import * as grpc from "@grpc/grpc-js";
 import { type BrokerPoolEntry } from "../../helpers/broker";
+import type { BrokerExecutionArchiver } from "../../helpers/broker-execution-archive";
 import type { OtelMetrics } from "../../helpers/otel";
 import type { PolicyConfig } from "../../types";
 import type { ActionRequest, ActionResponse } from "../types";
@@ -10,5 +11,6 @@ export type ExecuteActionDeps = {
     useVerity: boolean;
     verityProverUrl: string;
     otelMetrics?: OtelMetrics;
+    brokerArchiver?: BrokerExecutionArchiver;
 };
 export declare function createExecuteActionHandler(deps: ExecuteActionDeps): (call: grpc.ServerUnaryCall<ActionRequest, ActionResponse>, callback: grpc.sendUnaryData<ActionResponse>) => Promise<void>;

package/dist/handlers/subscribe/handler.d.ts

@@ -1,11 +1,13 @@
 import * as grpc from "@grpc/grpc-js";
 import { type BrokerPoolEntry } from "../../helpers/broker";
+import type { BrokerExecutionArchiver } from "../../helpers/broker-execution-archive";
 import type { OtelMetrics } from "../../helpers/otel";
 import type { SubscribeRequest, SubscribeResponse } from "../types";
 export type SubscribeDeps = {
     brokers: Record<string, BrokerPoolEntry>;
     whitelistIps: string[];
     otelMetrics?: OtelMetrics;
+    brokerArchiver?: BrokerExecutionArchiver;
 };
 type SubscribeCall = grpc.ServerWritableStream<SubscribeRequest, SubscribeResponse>;
 export declare function createSubscribeHandler(deps: SubscribeDeps): (call: SubscribeCall) => Promise<void>;

package/dist/helpers/broker-execution-archive/capture.d.ts

@@ -0,0 +1,27 @@
+import type { Exchange } from "@usherlabs/ccxt";
+import { type OrderTelemetryAction, type OrderTelemetryContext } from "../order-telemetry";
+import type { SubscribeArchiveType } from "./types";
+import type { BrokerExecutionArchiver } from "./writer";
+export declare function archiveOrderExecutionInBackground(archiver: BrokerExecutionArchiver | undefined, context: OrderTelemetryContext, order: unknown, error?: unknown, options?: {
+    marketMetadataHash?: string;
+}): void;
+export declare function archiveSubscribeStreamInBackground(archiver: BrokerExecutionArchiver | undefined, input: {
+    exchange: string;
+    accountSelector?: string;
+    symbol: string;
+    subscriptionType: SubscribeArchiveType;
+    streamPayload: unknown;
+    secretLiterals?: readonly string[];
+}): void;
+export declare function captureMarketMetadataSnapshot(archiver: BrokerExecutionArchiver | undefined, broker: Exchange, input: {
+    exchange: string;
+    accountSelector?: string;
+    symbol: string;
+    action: OrderTelemetryAction;
+    clientOrderId?: string;
+    orderId?: string;
+    makerActionId?: string;
+    idempotencyId?: string;
+    brokerObservedTimestamp?: string;
+}): Promise<string | undefined>;
+export declare function captureMarketMetadataSnapshotInBackground(archiver: BrokerExecutionArchiver | undefined, broker: Exchange, input: Parameters<typeof captureMarketMetadataSnapshot>[2]): void;

package/dist/helpers/broker-execution-archive/index.d.ts

@@ -0,0 +1,5 @@
+export { archiveOrderExecutionInBackground, archiveSubscribeStreamInBackground, captureMarketMetadataSnapshot, captureMarketMetadataSnapshotInBackground, } from "./capture";
+export { hashMarketMetadata, redactErrorForArchive, redactSecretLiterals, redactStreamPayload, } from "./redact";
+export { buildCommonArchiveTags, buildMarketMetadataSnapshotRow, buildOrderEventArchiveRow, buildSubscribeStreamArchiveRow, } from "./rows";
+export { BROKER_WRITE_SOURCE, type BrokerArchiveCommonTags, type BrokerArchiveRow, type BrokerArchiveTable, type OrderArchiveAction, type SubscribeArchiveType, } from "./types";
+export { BrokerExecutionArchiver, type BrokerExecutionArchiverOptions, createBrokerExecutionArchiverFromEnv, isArchiveOtelLogsEnabled, resolveArchiveForwarderUrlFromEnv, } from "./writer";

package/dist/helpers/broker-execution-archive/redact.d.ts

@@ -0,0 +1,7 @@
+export declare function redactErrorForArchive(error: unknown): {
+    error_type?: string;
+    error_message?: string;
+};
+export declare function redactSecretLiterals(value: string, secretLiterals?: readonly string[]): string;
+export declare function redactStreamPayload(payload: unknown, secretLiterals?: readonly string[]): Record<string, unknown>;
+export declare function hashMarketMetadata(payload: unknown): string | undefined;

package/dist/helpers/broker-execution-archive/rows.d.ts

@@ -0,0 +1,31 @@
+import type { OrderExecutionTelemetry } from "../order-telemetry";
+import { type BrokerArchiveCommonTags, type BrokerArchiveRow, type OrderArchiveAction, type SubscribeArchiveType } from "./types";
+export declare function buildCommonArchiveTags(input: {
+    deploymentId: string;
+    accountSelector?: string;
+    exchange: string;
+    symbol?: string;
+    brokerObservedTimestamp?: string;
+}): BrokerArchiveCommonTags;
+export declare function buildOrderEventArchiveRow(input: {
+    tags: BrokerArchiveCommonTags;
+    action: OrderArchiveAction;
+    telemetry: OrderExecutionTelemetry;
+    eventKind?: "execute_action" | "subscribe_stream";
+    subscriptionType?: SubscribeArchiveType;
+    marketMetadataHash?: string;
+}): BrokerArchiveRow;
+export declare function buildSubscribeStreamArchiveRow(input: {
+    tags: BrokerArchiveCommonTags;
+    subscriptionType: SubscribeArchiveType;
+    streamPayload: unknown;
+    secretLiterals?: readonly string[];
+}): BrokerArchiveRow;
+export declare function buildMarketMetadataSnapshotRow(input: {
+    tags: BrokerArchiveCommonTags;
+    clientOrderId?: string;
+    orderId?: string;
+    makerActionId?: string;
+    idempotencyId?: string;
+    marketSnapshot: unknown;
+}): BrokerArchiveRow;

package/dist/helpers/broker-execution-archive/types.d.ts

@@ -0,0 +1,16 @@
+export declare const BROKER_WRITE_SOURCE: "broker_write";
+export type BrokerArchiveTable = "broker_execution.order_events" | "broker_execution.market_metadata_snapshots" | "market_data.orderbook_snapshots" | "market_data.candles" | "market_data.cex_stream_events" | "market_data.cex_ticker_events" | "market_data.cex_trades";
+export type BrokerArchiveRow = {
+    table: BrokerArchiveTable;
+    row: Record<string, unknown>;
+};
+export type BrokerArchiveCommonTags = {
+    source: typeof BROKER_WRITE_SOURCE;
+    deployment_id: string;
+    account_selector: string;
+    exchange: string;
+    symbol: string;
+    broker_observed_timestamp: string;
+};
+export type OrderArchiveAction = "CreateOrder" | "CancelOrder" | "GetOrderDetails";
+export type SubscribeArchiveType = "ORDERS" | "BALANCE";

package/dist/helpers/broker-execution-archive/writer.d.ts

@@ -0,0 +1,57 @@
+import type { OtelLogs, OtelMetrics } from "../otel";
+import type { BrokerArchiveRow } from "./types";
+export type BrokerExecutionArchiverOptions = {
+    deploymentId?: string;
+    otelLogs?: OtelLogs;
+    otelMetrics?: OtelMetrics;
+    forwarderUrl?: string;
+    maxQueueSize?: number;
+    batchSize?: number;
+    flushIntervalMs?: number;
+    forwarderTimeoutMs?: number;
+};
+type ArchiverStats = {
+    enqueued: number;
+    shed: number;
+    flushed: number;
+    forwarderFailures: number;
+};
+export declare function isArchiveOtelLogsEnabled(): boolean;
+export declare function resolveArchiveForwarderUrlFromEnv(): string | undefined;
+export declare class BrokerExecutionArchiver {
+    private readonly deploymentId;
+    private readonly otelLogs?;
+    private readonly otelMetrics?;
+    private readonly forwarderUrl?;
+    private readonly maxQueueSize;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private readonly forwarderTimeoutMs;
+    private readonly queue;
+    private readonly stats;
+    private flushTimer;
+    private flushInFlight;
+    private closed;
+    private loggedMissingMarketForwarder;
+    private readonly enabled;
+    private readonly forwarderAuthToken?;
+    private constructor();
+    static disabled(): BrokerExecutionArchiver;
+    static create(options: BrokerExecutionArchiverOptions): BrokerExecutionArchiver;
+    getDeploymentId(): string;
+    isEnabled(): boolean;
+    canPersistMarketMetadataSnapshot(): boolean;
+    enqueue(row: BrokerArchiveRow): void;
+    enqueueInBackground(row: BrokerArchiveRow): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    getStats(): Readonly<ArchiverStats>;
+    getQueueDepth(): number;
+    private enforceQueueBound;
+    private flushBatch;
+    private recordArchiveMetric;
+    private emitOtelLog;
+    private postToForwarder;
+}
+export declare function createBrokerExecutionArchiverFromEnv(otelLogs?: OtelLogs, otelMetrics?: OtelMetrics): BrokerExecutionArchiver;
+export {};

package/dist/helpers/market-data-archive/capture.d.ts

@@ -0,0 +1,20 @@
+import type { OtelMetrics } from "../otel";
+import type { BrokerExecutionArchiver } from "../broker-execution-archive/writer";
+import { OhlcvBarTracker } from "./ohlcv-bar-tracker";
+import { OrderbookSampler } from "./orderbook-sampler";
+import type { CexStreamArchiveInput, OhlcvArchiveInput, OrderbookArchiveInput, TickerArchiveInput, TradesArchiveInput } from "./types";
+export declare function archiveOrderbookInBackground(archiver: BrokerExecutionArchiver | undefined, otelMetrics: OtelMetrics | undefined, input: OrderbookArchiveInput, options?: {
+    sampledOut?: boolean;
+}): void;
+/** @deprecated Use archiveOrderbookInBackground */
+export declare const archiveOrderbookSnapshotInBackground: typeof archiveOrderbookInBackground;
+/** @deprecated Use archiveOrderbookInBackground */
+export declare const archiveOrderbookTobInBackground: typeof archiveOrderbookInBackground;
+export declare function archiveOhlcvInBackground(archiver: BrokerExecutionArchiver | undefined, otelMetrics: OtelMetrics | undefined, tracker: OhlcvBarTracker, input: OhlcvArchiveInput): void;
+export declare function createOrderbookSampler(): OrderbookSampler;
+/** @deprecated Use createOrderbookSampler */
+export declare const createOrderbookTobSampler: typeof createOrderbookSampler;
+export declare function createOhlcvBarTracker(): OhlcvBarTracker;
+export declare function archiveTradesInBackground(archiver: BrokerExecutionArchiver | undefined, otelMetrics: OtelMetrics | undefined, input: TradesArchiveInput): void;
+export declare function archiveTickerInBackground(archiver: BrokerExecutionArchiver | undefined, otelMetrics: OtelMetrics | undefined, input: TickerArchiveInput): void;
+export declare function archiveCexStreamEventInBackground(archiver: BrokerExecutionArchiver | undefined, otelMetrics: OtelMetrics | undefined, input: CexStreamArchiveInput): void;

package/dist/helpers/market-data-archive/index.d.ts

@@ -0,0 +1,9 @@
+export { archiveCexStreamEventInBackground, archiveOhlcvInBackground, archiveOrderbookInBackground, archiveOrderbookSnapshotInBackground, archiveOrderbookTobInBackground, archiveTickerInBackground, archiveTradesInBackground, createOhlcvBarTracker, createOrderbookSampler, createOrderbookTobSampler, } from "./capture";
+export { extractLatestOhlcvBar, extractOhlcvBars, OhlcvBarTracker, parseOhlcvBar, } from "./ohlcv-bar-tracker";
+export { bootstrapOhlcvHistory } from "./ohlcv-history";
+export { resolveOhlcvBootstrapLimit } from "./ohlcv-bootstrap";
+export { extractTrades, parseTicker, parseTrade } from "./parse-stream";
+export { getOrderbookIntervalMs, getOrderbookTobIntervalMs, isMarketArchiveEnabled, OrderbookSampler, OrderbookTobSampler, } from "./orderbook-sampler";
+export { buildCandleRow, buildCexStreamEventRow, buildCexTickerEventRow, buildCexTradeRow, buildOrderbookDepthRow, buildOrderbookSnapshotRow, buildOrderbookTobRow, } from "./rows";
+export { getOrderbookArchiveDepthLimit, splitOrderBookSide, } from "./orderbook-depth";
+export type { CexStreamArchiveInput, CexStreamType, MarketArchiveContext, OhlcvArchiveCandidate, OhlcvArchiveInput, OrderbookArchiveInput, OrderbookSnapshotArchiveInput, OrderbookTobArchiveInput, ParsedOhlcvBar, TickerArchiveInput, TradesArchiveInput, } from "./types";

package/dist/helpers/market-data-archive/ohlcv-bar-tracker.d.ts

@@ -0,0 +1,11 @@
+import type { OhlcvArchiveCandidate, ParsedOhlcvBar } from "./types";
+export declare function parseOhlcvBar(value: unknown): ParsedOhlcvBar | null;
+export declare function extractOhlcvBars(payload: unknown): ParsedOhlcvBar[];
+export declare function extractLatestOhlcvBar(payload: unknown): ParsedOhlcvBar | null;
+export declare class OhlcvBarTracker {
+    private lastOpenTimeMs;
+    private lastBar;
+    process(payload: unknown, brokerVersion: number): OhlcvArchiveCandidate[];
+    private processSingleBar;
+    private processBatch;
+}

package/dist/helpers/market-data-archive/ohlcv-bootstrap.d.ts

@@ -0,0 +1 @@
+export declare function resolveOhlcvBootstrapLimit(optionValue: string | undefined): number;

package/dist/helpers/market-data-archive/ohlcv-history.d.ts

@@ -0,0 +1,8 @@
+import type { Exchange } from "@usherlabs/ccxt";
+import type { OtelMetrics } from "../otel";
+import type { BrokerExecutionArchiver } from "../broker-execution-archive/writer";
+import type { OhlcvBarTracker } from "./ohlcv-bar-tracker";
+import type { OhlcvArchiveInput } from "./types";
+export declare function bootstrapOhlcvHistory(broker: Exchange, archiver: BrokerExecutionArchiver | undefined, otelMetrics: OtelMetrics | undefined, tracker: OhlcvBarTracker, input: OhlcvArchiveInput, options?: {
+    bootstrapLimit?: string;
+}): Promise<unknown | null>;

package/dist/helpers/market-data-archive/orderbook-depth.d.ts

@@ -0,0 +1,5 @@
+export declare function getOrderbookArchiveDepthLimit(): number;
+export declare function splitOrderBookSide(levels: number[][], limit: number): {
+    prices: number[];
+    sizes: number[];
+};

package/dist/helpers/market-data-archive/orderbook-sampler.d.ts

@@ -0,0 +1,12 @@
+export declare function getOrderbookIntervalMs(): number;
+export declare function isMarketArchiveEnabled(): boolean;
+export declare class OrderbookSampler {
+    private readonly intervalMs;
+    private lastEmitMs;
+    constructor(intervalMs?: number);
+    shouldEmit(nowMs?: number): boolean;
+}
+/** @deprecated Use getOrderbookIntervalMs */
+export declare const getOrderbookTobIntervalMs: typeof getOrderbookIntervalMs;
+/** @deprecated Use OrderbookSampler */
+export declare const OrderbookTobSampler: typeof OrderbookSampler;

package/dist/helpers/market-data-archive/parse-stream.d.ts

@@ -0,0 +1,26 @@
+export type ParsedTrade = {
+    tradeId: string;
+    eventTimeMs: number;
+    side: string;
+    price: number;
+    amount: number;
+    cost?: number;
+    takerOrMaker?: string;
+};
+export type ParsedTicker = {
+    eventTimeMs: number;
+    last?: number;
+    bid?: number;
+    ask?: number;
+    high?: number;
+    low?: number;
+    open?: number;
+    close?: number;
+    baseVolume?: number;
+    quoteVolume?: number;
+    change?: number;
+    percentage?: number;
+};
+export declare function parseTrade(value: unknown, fallbackMs?: number): ParsedTrade | null;
+export declare function extractTrades(payload: unknown, fallbackMs?: number): ParsedTrade[];
+export declare function parseTicker(value: unknown, fallbackMs: number): ParsedTicker | null;

package/dist/helpers/market-data-archive/rows.d.ts

@@ -0,0 +1,18 @@
+import { type BrokerArchiveRow } from "../broker-execution-archive/types";
+import type { ParsedTicker, ParsedTrade } from "./parse-stream";
+import type { CexStreamArchiveInput, MarketArchiveContext, OrderbookArchiveInput, ParsedOhlcvBar, TickerArchiveInput, TradesArchiveInput } from "./types";
+export declare function buildOrderbookSnapshotRow(input: OrderbookArchiveInput): BrokerArchiveRow | null;
+/** @deprecated Use buildOrderbookSnapshotRow */
+export declare const buildOrderbookTobRow: typeof buildOrderbookSnapshotRow;
+/** @deprecated Use buildOrderbookSnapshotRow */
+export declare const buildOrderbookDepthRow: typeof buildOrderbookSnapshotRow;
+export declare function buildCandleRow(input: {
+    context: MarketArchiveContext;
+    bar: ParsedOhlcvBar;
+    isClosed: boolean;
+    brokerVersion: number;
+    receivedTimestamp: number;
+}): BrokerArchiveRow;
+export declare function buildCexStreamEventRow(input: CexStreamArchiveInput): BrokerArchiveRow;
+export declare function buildCexTickerEventRow(input: TickerArchiveInput, ticker: ParsedTicker): BrokerArchiveRow;
+export declare function buildCexTradeRow(input: TradesArchiveInput, trade: ParsedTrade): BrokerArchiveRow;

package/dist/helpers/market-data-archive/types.d.ts

@@ -0,0 +1,55 @@
+import type { BrokerMarketType } from "../market-type";
+import type { NormalizedOrderBookSnapshot } from "../order-book";
+import type { BrokerArchiveRow } from "../broker-execution-archive/types";
+export type MarketArchiveTable = "market_data.orderbook_snapshots" | "market_data.candles" | "market_data.cex_stream_events" | "market_data.cex_ticker_events" | "market_data.cex_trades";
+export type CexStreamType = "BALANCE" | "ORDERS" | "ORDERBOOK" | "TRADES" | "TICKER" | "OHLCV";
+export type ParsedOhlcvBar = {
+    openTimeMs: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+    quoteVolume?: number;
+};
+export type OhlcvArchiveCandidate = {
+    bar: ParsedOhlcvBar;
+    isClosed: boolean;
+    brokerVersion: number;
+};
+export type MarketArchiveContext = {
+    exchange: string;
+    symbol: string;
+    assetType: BrokerMarketType;
+    timeframe?: string;
+    accountSelector?: string;
+    deploymentId: string;
+};
+export type OrderbookArchiveInput = MarketArchiveContext & {
+    snapshot: NormalizedOrderBookSnapshot;
+};
+/** @deprecated Use OrderbookArchiveInput */
+export type OrderbookSnapshotArchiveInput = OrderbookArchiveInput;
+/** @deprecated Use OrderbookArchiveInput */
+export type OrderbookTobArchiveInput = OrderbookArchiveInput;
+export type OhlcvArchiveInput = MarketArchiveContext & {
+    payload: unknown;
+    receivedTimestamp: number;
+    timeframe: string;
+};
+export type TradesArchiveInput = MarketArchiveContext & {
+    payload: unknown;
+    receivedTimestamp: number;
+};
+export type TickerArchiveInput = MarketArchiveContext & {
+    payload: unknown;
+    receivedTimestamp: number;
+};
+export type CexStreamArchiveInput = MarketArchiveContext & {
+    streamType: CexStreamType;
+    payload: unknown;
+    receivedTimestamp: number;
+    eventTimeMs?: number;
+};
+export declare function isMarketArchiveTable(table: string): table is MarketArchiveTable;
+export type { BrokerArchiveRow };

package/dist/helpers/order-telemetry.d.ts

@@ -1,5 +1,5 @@
 import type { OtelMetrics } from "./otel";
-export type OrderTelemetryAction = "CreateOrder" | "GetOrderDetails";
+export type OrderTelemetryAction = "CreateOrder" | "CancelOrder" | "GetOrderDetails";
 export type OrderTelemetryContext = {
     action: OrderTelemetryAction;
     cex: string;

package/dist/helpers/travel-rule-deposit-reconciler.d.ts

@@ -46,6 +46,12 @@ export declare function parseLocalEntityDeposit(raw: Record<string, unknown>): L
  * churn (owner wallet → Binance via a direct ERC20 transfer) that equals the
  * token originator. A transfer routed through a contract could differ; hardening
  * to the ERC20 Transfer event's `from` is possible later if that case arises.
+ *
+ * Uses `node:https` rather than the global `fetch`: inside the Gramine SGX
+ * enclave undici (which backs global fetch) fails to establish outbound
+ * connections — the same failure mode as the enclave's dead Binance user-data
+ * WebSocket — while the ccxt HTTP path (node http/https) works. Using node's
+ * request keeps this on the transport that is proven to work in the enclave.
  */
 export declare function resolveOnChainSender(rpcUrl: string, txHash: string, timeoutMs?: number): Promise<string | null>;
 /** Binance rate-limit signals (-1003 / HTTP 429 / DDoS guard). */
@@ -78,6 +84,7 @@ export type ReconcileOutcome = {
 } | {
     kind: "unproven-origin";
     deposit: LocalEntityDeposit;
+    error?: string;
 } | {
     kind: "entity-drift";
     deposit: LocalEntityDeposit;

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export default class CEXBroker {
     private useVerity;
     private otelMetrics?;
     private otelLogs?;
+    private brokerArchiver?;
     private depositReconciler?;
     /**
      * Loads environment variables prefixed with CEX_BROKER_