@usherlabs/cex-broker 0.2.20 → 0.2.22

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

@@ -5,6 +5,7 @@ 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 { OrderActivityTracker } from "../../helpers/order-activity-tracker";
 import type { OtelMetrics } from "../../helpers/otel";
 import type { PolicyConfig } from "../../types";
 import type { ActionRequest, ActionResponse } from "../types";
@@ -29,6 +30,7 @@ export type ExecuteActionContext = {
     verityProverUrl: string;
     otelMetrics?: OtelMetrics;
     brokerArchiver?: BrokerExecutionArchiver;
+    orderActivityTracker?: OrderActivityTracker;
 };
 export declare function requireSymbol(ctx: ExecuteActionContext, message?: string): ctx is ExecuteActionContext & {
     symbol: string;
@@ -38,5 +40,10 @@ export declare function rejectWithGrpcError(ctx: ExecuteActionContext, error: un
     message?: string;
     prefix?: string;
     preferStableMessageOnly?: boolean;
+    /** Append the caught error's class name (e.g. InsufficientFunds) as a
+     * suffix. It goes last, not in front, because the gRPC status code is
+     * derived from the raw message via stableGrpcErrorCode; prepending the
+     * class name would break that prefix match. */
+    appendClassName?: boolean;
 }): void;
 export declare function successWithProof(ctx: ExecuteActionContext, result: unknown): void;

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

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

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

@@ -1,5 +1,6 @@
 import type { Exchange } from "@usherlabs/ccxt";
 import { type OrderTelemetryAction, type OrderTelemetryContext } from "../order-telemetry";
+import { type TransferArchiveFields } from "./rows";
 import type { SubscribeArchiveType } from "./types";
 import type { BrokerExecutionArchiver } from "./writer";
 export declare function archiveOrderExecutionInBackground(archiver: BrokerExecutionArchiver | undefined, context: OrderTelemetryContext, order: unknown, error?: unknown, options?: {
@@ -13,6 +14,13 @@ export declare function archiveSubscribeStreamInBackground(archiver: BrokerExecu
     streamPayload: unknown;
     secretLiterals?: readonly string[];
 }): void;
+export declare function archiveTransferEventInBackground(archiver: BrokerExecutionArchiver | undefined, input: {
+    exchange: string;
+    accountSelector?: string;
+    assetSymbol?: string;
+    brokerObservedTimestamp?: string;
+    transfer: TransferArchiveFields;
+}): void;
 export declare function captureMarketMetadataSnapshot(archiver: BrokerExecutionArchiver | undefined, broker: Exchange, input: {
     exchange: string;
     accountSelector?: string;

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

@@ -1,5 +1,5 @@
-export { archiveOrderExecutionInBackground, archiveSubscribeStreamInBackground, captureMarketMetadataSnapshot, captureMarketMetadataSnapshotInBackground, } from "./capture";
+export { archiveOrderExecutionInBackground, archiveSubscribeStreamInBackground, archiveTransferEventInBackground, 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 { buildCommonArchiveTags, buildFillEventArchiveRow, buildMarketMetadataSnapshotRow, buildOrderEventArchiveRow, buildSubscribeStreamArchiveRow, buildTransferEventArchiveRow, type FillArchiveFields, normalizeCcxtTradeForArchive, normalizeCcxtTransactionForArchive, type NormalizedCcxtTransfer, type TransferArchiveFields, } from "./rows";
+export { ARCHIVE_SCHEMA_VERSION, BROKER_WRITE_SOURCE, type BrokerArchiveCommonTags, type BrokerArchiveRow, type BrokerArchiveTable, type OrderArchiveAction, type SubscribeArchiveType, type TransferEventKind, type TransferLifecycleAction, } from "./types";
 export { BrokerExecutionArchiver, type BrokerExecutionArchiverOptions, createBrokerExecutionArchiverFromEnv, isArchiveOtelLogsEnabled, resolveArchiveForwarderUrlFromEnv, } from "./writer";

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

@@ -1,5 +1,5 @@
 import type { OrderExecutionTelemetry } from "../order-telemetry";
-import { type BrokerArchiveCommonTags, type BrokerArchiveRow, type OrderArchiveAction, type SubscribeArchiveType } from "./types";
+import { type BrokerArchiveCommonTags, type BrokerArchiveRow, type OrderArchiveAction, type SubscribeArchiveType, type TransferEventKind, type TransferLifecycleAction } from "./types";
 export declare function buildCommonArchiveTags(input: {
     deploymentId: string;
     accountSelector?: string;
@@ -21,6 +21,60 @@ export declare function buildSubscribeStreamArchiveRow(input: {
     streamPayload: unknown;
     secretLiterals?: readonly string[];
 }): BrokerArchiveRow;
+export type TransferArchiveFields = {
+    eventKind: TransferEventKind;
+    lifecycleAction: TransferLifecycleAction;
+    status?: string;
+    amount?: string;
+    address?: string;
+    network?: string;
+    externalId?: string;
+    txid?: string;
+    resultIndex?: number;
+    feeAmount?: string;
+    feeCurrency?: string;
+    exchangeTimestamp?: string;
+    errorSummary?: string;
+    payload: unknown;
+};
+export declare function buildTransferEventArchiveRow(input: {
+    tags: BrokerArchiveCommonTags;
+    transfer: TransferArchiveFields;
+}): BrokerArchiveRow;
+export type NormalizedCcxtTransfer = {
+    externalId?: string;
+    txid?: string;
+    address?: string;
+    network?: string;
+    amount?: string;
+    assetSymbol?: string;
+    status?: string;
+    feeAmount?: string;
+    feeCurrency?: string;
+    exchangeTimestamp?: string;
+};
+export declare function normalizeCcxtTransactionForArchive(transaction: unknown): NormalizedCcxtTransfer;
+export type FillArchiveFields = {
+    orderId?: string;
+    clientOrderId?: string;
+    fillId?: string;
+    fillIndex?: number;
+    side?: string;
+    orderType?: string;
+    price?: string;
+    baseQuantity?: string;
+    quoteQuantity?: string;
+    feeAmount?: string;
+    feeCurrency?: string;
+    feeRate?: string;
+    exchangeTimestamp?: string;
+    payload: unknown;
+};
+export declare function buildFillEventArchiveRow(input: {
+    tags: BrokerArchiveCommonTags;
+    fill: FillArchiveFields;
+}): BrokerArchiveRow;
+export declare function normalizeCcxtTradeForArchive(trade: unknown): FillArchiveFields;
 export declare function buildMarketMetadataSnapshotRow(input: {
     tags: BrokerArchiveCommonTags;
     clientOrderId?: string;

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

@@ -1,5 +1,6 @@
 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 declare const ARCHIVE_SCHEMA_VERSION: "1";
+export type BrokerArchiveTable = "broker_execution.order_events" | "broker_execution.market_metadata_snapshots" | "broker_execution.transfer_events" | "broker_execution.fill_events" | "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>;
@@ -14,3 +15,6 @@ export type BrokerArchiveCommonTags = {
 };
 export type OrderArchiveAction = "CreateOrder" | "CancelOrder" | "GetOrderDetails";
 export type SubscribeArchiveType = "ORDERS" | "BALANCE";
+export type TransferEventKind = "withdrawal" | "deposit" | "internal_transfer";
+export type TransferLifecycleAction = "submit_withdrawal" | "observe_deposit" | "submit_internal_transfer";
+export declare const FILL_EVENT_KIND: "trade_history_fill";

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

@@ -49,7 +49,9 @@ export declare class BrokerExecutionArchiver {
     getQueueDepth(): number;
     private enforceQueueBound;
     private flushBatch;
+    private recordFlushHealth;
     private recordArchiveMetric;
+    private recordArchiveGauge;
     private emitOtelLog;
     private postToForwarder;
 }

package/dist/helpers/fill-archive-poller.d.ts

@@ -0,0 +1,42 @@
+import type { BrokerPoolEntry } from "./broker";
+import { type BrokerExecutionArchiver } from "./broker-execution-archive";
+import type { OrderActivityTracker } from "./order-activity-tracker";
+import type { OtelMetrics } from "./otel";
+export type FillArchivePollerConfig = {
+    pollIntervalMs: number;
+    lookbackMs: number;
+    tradesLimit: number;
+};
+/**
+ * Advances a since-cursor past the newest trade in a batch. The next poll asks for
+ * trades strictly after the last one seen (+1ms) so the same trade is not refetched
+ * every tick, while still tolerating out-of-order timestamps within a batch.
+ */
+export declare function nextFillCursor(trades: unknown[], currentSince: number): number;
+/**
+ * Broker-internal periodic capture of per-fill facts. For each (account, symbol)
+ * that saw recent order activity it calls the venue trade-history endpoint
+ * (fetchMyTrades) with a since-cursor and archives each trade to
+ * broker_execution.fill_events. Started at bootstrap only when archiving is
+ * enabled; symbols are staggered by sequential awaits so one tick never bursts the
+ * venue rate limit. Mirrors the TravelRuleDepositReconciler lifecycle.
+ */
+export declare class FillArchivePoller {
+    #private;
+    private readonly params;
+    constructor(params: {
+        brokers: Record<string, BrokerPoolEntry>;
+        archiver: BrokerExecutionArchiver;
+        tracker: OrderActivityTracker;
+        metrics?: OtelMetrics;
+        config?: Partial<FillArchivePollerConfig>;
+    });
+    start(): void;
+    stop(): void;
+    /**
+     * Runs one poll pass over every tracked (account, symbol), sequentially so the
+     * per-symbol awaits stagger venue calls. Exposed for tests (the timer loop calls
+     * it every tick).
+     */
+    pollTrackedOnce(): Promise<void>;
+}

package/dist/helpers/order-activity-tracker.d.ts

@@ -0,0 +1,22 @@
+export type OrderActivityEntry = {
+    exchangeId: string;
+    accountLabel: string;
+    symbol: string;
+    lastActivityAt: number;
+};
+/**
+ * Records the (exchange, account, symbol) tuples that saw order activity through
+ * the execute-action path, so the fill poller scans only those markets instead of
+ * the whole exchange. Process-lifetime, in-memory only (no persistence needed: on
+ * restart the poller re-derives the set from fresh order activity and read-time
+ * dedup absorbs the lookback re-scan).
+ */
+export declare class OrderActivityTracker {
+    #private;
+    constructor(options?: {
+        maxAgeMs?: number;
+    });
+    record(exchangeId: string, accountLabel: string, symbol: string, now?: number): void;
+    /** Active entries (seen within maxAge). Prunes stale entries as a side effect. */
+    list(now?: number): OrderActivityEntry[];
+}

package/dist/helpers/shared/errors.d.ts

@@ -1,2 +1,12 @@
 export declare function getErrorMessage(error: unknown): string;
+/** Constructor/class name of a caught error (ccxt classes like InsufficientFunds,
+ * BadSymbol, OrderNotFound carry the actionable signal). The generic `Error` name
+ * adds nothing, so it is dropped; returns undefined for non-Error values. */
+export declare function errorClassName(error: unknown): string | undefined;
+/** Sanitized, single-line, length-capped detail for a caught error: the venue
+ * error class name plus its message. Safe to return to gRPC callers — it carries
+ * only the exchange's own error text (class + message), never a stack or payload,
+ * so downstream consumers can distinguish e.g. InsufficientFunds from BadSymbol
+ * instead of an opaque "<action> failed". */
+export declare function sanitizeErrorDetail(error: unknown): string;
 export declare function safeLogError(context: string, error: unknown): void;

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export default class CEXBroker {
     private otelLogs?;
     private brokerArchiver?;
     private depositReconciler?;
+    private readonly orderActivityTracker;
+    private fillArchivePoller?;
     /**
      * Loads environment variables prefixed with CEX_BROKER_
      * Expected format: