@usherlabs/cex-broker 0.2.23 → 0.2.25

package/dist/helpers/account-balance-archive-poller.d.ts

@@ -0,0 +1,19 @@
+import type { BrokerPoolEntry } from "./broker";
+import { type BrokerExecutionArchiver } from "./broker-execution-archive";
+import type { OtelMetrics } from "./otel";
+export type AccountBalanceArchivePollerConfig = {
+    pollIntervalMs: number;
+};
+export declare class AccountBalanceArchivePoller {
+    #private;
+    private readonly params;
+    constructor(params: {
+        brokers: Record<string, BrokerPoolEntry>;
+        archiver: BrokerExecutionArchiver;
+        metrics?: OtelMetrics;
+        config?: Partial<AccountBalanceArchivePollerConfig>;
+    });
+    start(): void;
+    stop(): Promise<void>;
+    pollAllOnce(): Promise<boolean>;
+}

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

@@ -2,6 +2,7 @@ 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 { WithdrawalObservationTracker } from "./withdrawal-observation-tracker";
 import type { BrokerExecutionArchiver } from "./writer";
 export declare function archiveOrderExecutionInBackground(archiver: BrokerExecutionArchiver | undefined, context: OrderTelemetryContext, order: unknown, error?: unknown, options?: {
     marketMetadataHash?: string;
@@ -21,6 +22,11 @@ export declare function archiveTransferEventInBackground(archiver: BrokerExecuti
     brokerObservedTimestamp?: string;
     transfer: TransferArchiveFields;
 }): void;
+export declare function archiveWithdrawalObservationsInBackground(archiver: BrokerExecutionArchiver | undefined, tracker: WithdrawalObservationTracker, input: {
+    exchange: string;
+    accountSelector?: string;
+    transactions: unknown;
+}): 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,6 @@
-export { archiveOrderExecutionInBackground, archiveSubscribeStreamInBackground, archiveTransferEventInBackground, captureMarketMetadataSnapshot, captureMarketMetadataSnapshotInBackground, } from "./capture";
+export { archiveOrderExecutionInBackground, archiveSubscribeStreamInBackground, archiveTransferEventInBackground, archiveWithdrawalObservationsInBackground, captureMarketMetadataSnapshot, captureMarketMetadataSnapshotInBackground, } from "./capture";
 export { hashMarketMetadata, redactErrorForArchive, redactSecretLiterals, redactStreamPayload, } from "./redact";
-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";
+export { buildAccountBalanceSnapshotRow, buildCommonArchiveTags, buildFillEventArchiveRow, buildMarketMetadataSnapshotRow, buildOrderEventArchiveRow, buildSubscribeStreamArchiveRow, buildTransferEventArchiveRow, type FillArchiveFields, type NormalizedCcxtBalance, type NormalizedCcxtTransfer, normalizeCcxtBalanceForArchive, normalizeCcxtTradeForArchive, normalizeCcxtTransactionForArchive, type TransferArchiveFields, } from "./rows";
+export { ACCOUNT_BALANCE_PRECISION_BASIS, ACCOUNT_BALANCE_SCOPE, ARCHIVE_SCHEMA_VERSION, BROKER_WRITE_SOURCE, type BrokerArchiveCommonTags, type BrokerArchiveRow, type BrokerArchiveTable, type OrderArchiveAction, type SubscribeArchiveType, type TransferEventKind, type TransferLifecycleAction, } from "./types";
+export { DEFAULT_WITHDRAWAL_OBSERVATION_TRACKER_MAX_ENTRIES, WithdrawalObservationTracker, } from "./withdrawal-observation-tracker";
+export { BrokerExecutionArchiver, type BrokerExecutionArchiverOptions, createBrokerExecutionArchiverFromEnv, isArchiveOtelLogsEnabled, isBrokerExecutionArchiveTable, resolveArchiveForwarderUrlFromEnv, } from "./writer";

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

@@ -1,5 +1,22 @@
 import type { OrderExecutionTelemetry } from "../order-telemetry";
 import { type BrokerArchiveCommonTags, type BrokerArchiveRow, type OrderArchiveAction, type SubscribeArchiveType, type TransferEventKind, type TransferLifecycleAction } from "./types";
+type BalanceQuantityMap = Record<string, string>;
+export type NormalizedCcxtBalance = {
+    exchangeTimestamp?: string;
+    reportedAssets: string[];
+    assetEntryAssets: string[];
+    freeBalances: BalanceQuantityMap;
+    usedBalances: BalanceQuantityMap;
+    totalBalances: BalanceQuantityMap;
+    freeMapPresent: boolean;
+    usedMapPresent: boolean;
+    totalMapPresent: boolean;
+};
+export declare function normalizeCcxtBalanceForArchive(balance: unknown): NormalizedCcxtBalance;
+export declare function buildAccountBalanceSnapshotRow(input: {
+    tags: BrokerArchiveCommonTags;
+    balance: NormalizedCcxtBalance;
+}): BrokerArchiveRow;
 export declare function buildCommonArchiveTags(input: {
     deploymentId: string;
     accountSelector?: string;
@@ -83,3 +100,4 @@ export declare function buildMarketMetadataSnapshotRow(input: {
     idempotencyId?: string;
     marketSnapshot: unknown;
 }): BrokerArchiveRow;
+export {};

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

@@ -1,6 +1,6 @@
 export declare const BROKER_WRITE_SOURCE: "broker_write";
 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 BrokerArchiveTable = "broker_execution.order_events" | "broker_execution.market_metadata_snapshots" | "broker_execution.transfer_events" | "broker_execution.fill_events" | "broker_account.balance_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>;
@@ -16,5 +16,7 @@ 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 type TransferLifecycleAction = "submit_withdrawal" | "observe_withdrawal" | "observe_deposit" | "submit_internal_transfer";
 export declare const FILL_EVENT_KIND: "trade_history_fill";
+export declare const ACCOUNT_BALANCE_SCOPE: "spot";
+export declare const ACCOUNT_BALANCE_PRECISION_BASIS: "ccxt_normalized_number";

package/dist/helpers/broker-execution-archive/withdrawal-observation-tracker.d.ts

@@ -0,0 +1,23 @@
+import type { NormalizedCcxtTransfer } from "./rows";
+export declare const DEFAULT_WITHDRAWAL_OBSERVATION_TRACKER_MAX_ENTRIES = 10000;
+type WithdrawalObservation = {
+    exchange: string;
+    accountSelector?: string;
+    assetSymbol?: string;
+    transaction: unknown;
+    normalized: NormalizedCcxtTransfer;
+};
+/**
+ * Suppresses unchanged withdrawal-history observations within one broker process.
+ * The tracker intentionally persists no state: restart replay is absorbed by
+ * archive consumers, while the in-process bound prevents unbounded venue history.
+ */
+export declare class WithdrawalObservationTracker {
+    #private;
+    constructor(options?: {
+        maxEntries?: number;
+    });
+    shouldArchive(observation: WithdrawalObservation): boolean;
+    getSize(): number;
+}
+export {};

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

@@ -1,5 +1,6 @@
 import type { OtelLogs, OtelMetrics } from "../otel";
-import type { BrokerArchiveRow } from "./types";
+import type { BrokerArchiveRow, BrokerArchiveTable } from "./types";
+export declare function isBrokerExecutionArchiveTable(table: BrokerArchiveTable): boolean;
 export type BrokerExecutionArchiverOptions = {
     deploymentId?: string;
     otelLogs?: OtelLogs;
@@ -41,6 +42,7 @@ export declare class BrokerExecutionArchiver {
     getDeploymentId(): string;
     isEnabled(): boolean;
     canPersistMarketMetadataSnapshot(): boolean;
+    canPersistAccountBalanceSnapshots(): boolean;
     enqueue(row: BrokerArchiveRow): void;
     enqueueInBackground(row: BrokerArchiveRow): void;
     flush(): Promise<void>;

package/dist/index.d.ts

@@ -14,7 +14,9 @@ export default class CEXBroker {
     private brokerArchiver?;
     private depositReconciler?;
     private readonly orderActivityTracker;
+    private readonly withdrawalObservationTracker;
     private fillArchivePoller?;
+    private accountBalanceArchivePoller?;
     /**
      * Loads environment variables prefixed with CEX_BROKER_
      * Expected format: