@usherlabs/cex-broker 0.2.40 → 0.2.42

package/dist/helpers/balance-update-archive-consumer.d.ts

@@ -0,0 +1,16 @@
+import type { BrokerPoolEntry } from "./broker";
+import { type BrokerExecutionArchiver } from "./broker-execution-archive";
+import type { UserDataStreamSupervisor } from "./user-data-stream-supervisor";
+type BalanceUpdateSubscriptionSource = Pick<UserDataStreamSupervisor, "subscribe">;
+export declare class BalanceUpdateArchiveConsumer {
+    #private;
+    private readonly params;
+    constructor(params: {
+        brokers: Record<string, BrokerPoolEntry>;
+        archiver: BrokerExecutionArchiver;
+        userDataStreamSupervisor: BalanceUpdateSubscriptionSource;
+    });
+    start(): void;
+    stop(): Promise<void>;
+}
+export {};

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

@@ -1,6 +1,6 @@
 export { archiveOrderExecutionInBackground, archiveSubscribeStreamInBackground, archiveTransferEventInBackground, archiveWithdrawalObservationsInBackground, captureMarketMetadataSnapshot, captureMarketMetadataSnapshotInBackground, } from "./capture";
 export { hashMarketMetadata, redactErrorForArchive, redactSecretLiterals, redactStreamPayload, } from "./redact";
-export { buildAccountBalanceSnapshotRow, buildCommonArchiveTags, buildFillEventArchiveRow, buildMarketMetadataSnapshotRow, buildOrderEventArchiveRow, buildSubscribeStreamArchiveRow, buildTransferEventArchiveRow, extractBinanceInternalTransferId, type FillArchiveFields, type NormalizedCcxtBalance, type NormalizedCcxtTransfer, normalizeCcxtBalanceForArchive, normalizeCcxtTradeForArchive, normalizeCcxtTransactionForArchive, normalizeTimestamp, type TransferArchiveFields, } from "./rows";
-export { ACCOUNT_BALANCE_PRECISION_BASIS, ACCOUNT_BALANCE_SCOPE, ARCHIVE_SCHEMA_VERSION, BROKER_READ_SOURCE, BROKER_WRITE_SOURCE, type BrokerArchiveCommonTags, type BrokerArchiveRow, type BrokerArchiveSource, type BrokerArchiveTable, type OrderArchiveAction, type SubscribeArchiveType, type TransferEventKind, type TransferLifecycleAction, } from "./types";
+export { buildAccountBalanceSnapshotRow, buildCommonArchiveTags, buildFillEventArchiveRow, buildMarketMetadataSnapshotRow, buildOrderEventArchiveRow, buildSubscribeStreamArchiveRow, buildTransferEventArchiveRow, buildUserAssetSnapshotRow, extractBinanceInternalTransferId, type FillArchiveFields, type NormalizedCcxtBalance, type NormalizedCcxtTransfer, type NormalizedUserAssets, normalizeBinanceUserAssetsForArchive, normalizeCcxtBalanceForArchive, normalizeCcxtTradeForArchive, normalizeCcxtTransactionForArchive, normalizeTimestamp, type TransferArchiveFields, } from "./rows";
+export { ACCOUNT_BALANCE_PRECISION_BASIS, ACCOUNT_BALANCE_SCOPE, ARCHIVE_SCHEMA_VERSION, BROKER_READ_SOURCE, BROKER_WRITE_SOURCE, type BrokerArchiveCommonTags, type BrokerArchiveRow, type BrokerArchiveSource, type BrokerArchiveTable, type OrderArchiveAction, type SubscribeArchiveType, type TransferEventKind, type TransferLifecycleAction, USER_ASSET_BALANCE_SCOPE, USER_ASSET_PRECISION_BASIS, } from "./types";
 export { DEFAULT_WITHDRAWAL_OBSERVATION_TRACKER_MAX_ENTRIES, WithdrawalObservationTracker, } from "./withdrawal-observation-tracker";
 export { BrokerExecutionArchiveDurabilityError, BrokerExecutionArchiver, type BrokerExecutionArchiverOptions, createBrokerExecutionArchiverFromEnv, isArchiveOtelLogsEnabled, isBrokerExecutionArchiveTable, resolveArchiveForwarderUrlFromEnv, rethrowArchiveDurabilityError, } from "./writer";

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

@@ -18,6 +18,30 @@ export declare function buildAccountBalanceSnapshotRow(input: {
     tags: BrokerArchiveCommonTags;
     balance: NormalizedCcxtBalance;
 }): BrokerArchiveRow;
+export type NormalizedUserAssets = {
+    reportedAssets: string[];
+    incompleteAssets: string[];
+    freeBalances: BalanceQuantityMap;
+    lockedBalances: BalanceQuantityMap;
+    freezeBalances: BalanceQuantityMap;
+    withdrawingBalances: BalanceQuantityMap;
+};
+/**
+ * Normalizes a `POST /sapi/v3/asset/getUserAsset` response into one coherent
+ * snapshot.
+ *
+ * Fails closed on a response shape we cannot account for: a non-array body or a
+ * duplicate/unkeyed asset entry would each drop owned quantity on the floor, and
+ * an under-counted NAV is worse than an absent one. Per-bucket uncertainty is
+ * narrower and is reported rather than thrown: the asset is listed in
+ * `incompleteAssets` and its key is left out of the bucket map, so a reader sees
+ * "unknown", never an implicit zero.
+ */
+export declare function normalizeBinanceUserAssetsForArchive(response: unknown): NormalizedUserAssets;
+export declare function buildUserAssetSnapshotRow(input: {
+    tags: BrokerArchiveCommonTags;
+    userAssets: NormalizedUserAssets;
+}): BrokerArchiveRow;
 export declare function buildCommonArchiveTags(input: {
     source?: BrokerArchiveSource;
     deploymentId: string;
@@ -46,6 +70,7 @@ export type TransferArchiveFields = {
     eventKind: TransferEventKind;
     lifecycleAction: TransferLifecycleAction;
     status?: string;
+    assetSymbol?: string;
     amount?: string;
     address?: string;
     network?: string;

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

@@ -2,7 +2,7 @@ export declare const BROKER_READ_SOURCE: "broker_read";
 export declare const BROKER_WRITE_SOURCE: "broker_write";
 export type BrokerArchiveSource = typeof BROKER_READ_SOURCE | typeof BROKER_WRITE_SOURCE;
 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" | "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" | "market_data.cex_ohlcv" | "market_data.cex_order_book_levels" | "market_data.cex_order_book_depth_summary";
+export type BrokerArchiveTable = "broker_execution.order_events" | "broker_execution.market_metadata_snapshots" | "broker_execution.transfer_events" | "broker_execution.fill_events" | "broker_account.balance_snapshots" | "broker_account.user_asset_snapshots" | "market_data.orderbook_snapshots" | "market_data.candles" | "market_data.cex_stream_events" | "market_data.cex_ticker_events" | "market_data.cex_trades" | "market_data.cex_ohlcv" | "market_data.cex_order_book_levels" | "market_data.cex_order_book_depth_summary";
 export type BrokerArchiveRow = {
     table: BrokerArchiveTable;
     row: Record<string, unknown>;
@@ -17,8 +17,10 @@ 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_withdrawal" | "observe_deposit" | "submit_internal_transfer";
+export type TransferEventKind = "withdrawal" | "deposit" | "internal_transfer" | "balance_delta";
+export type TransferLifecycleAction = "submit_withdrawal" | "observe_withdrawal" | "observe_deposit" | "observe_balance_update" | "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";
+export declare const USER_ASSET_BALANCE_SCOPE: "user_asset";
+export declare const USER_ASSET_PRECISION_BASIS: "venue_raw_string";

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

@@ -23,6 +23,19 @@ type ArchiverStats = {
     flushed: number;
     forwarderFailures: number;
 };
+export type BrokerExecutionArchiveHealthSnapshot = {
+    healthy: boolean;
+    queue_depth: number;
+    oldest_pending_age_ms: number;
+    shed_total: number;
+    last_failure_at: number | null;
+    last_shed_at: number | null;
+    last_success_at: number | null;
+    sink_latency_ms: number | null;
+    sink_errors_total: number;
+    in_flight: boolean;
+    in_flight_age_ms: number;
+};
 export declare function isArchiveOtelLogsEnabled(): boolean;
 export declare function resolveArchiveForwarderUrlFromEnv(): string | undefined;
 export declare function resolveArchiveSourceFromEnv(value?: string | undefined): BrokerArchiveSource;
@@ -39,9 +52,21 @@ export declare class BrokerExecutionArchiver {
     private readonly flushIntervalMs;
     private readonly forwarderTimeoutMs;
     private readonly queue;
+    private readonly enqueueTimes;
     private readonly stats;
+    private pendingRetry;
     private flushTimer;
     private flushInFlight;
+    private inFlightBatch;
+    private inFlightStartedAtMs;
+    private lastFailureAtMs;
+    private lastShedAtMs;
+    private lastSuccessAtMs;
+    private lastFailureEventSequence;
+    private lastShedEventSequence;
+    private lastSuccessEventSequence;
+    private lastSinkLatencyMs;
+    private healthEventSequence;
     private lastShedWarnAtMs;
     private closing;
     private closed;
@@ -61,13 +86,18 @@ export declare class BrokerExecutionArchiver {
     close(): Promise<void>;
     getStats(): Readonly<ArchiverStats>;
     getQueueDepth(): number;
+    getHealthSnapshot(): Readonly<BrokerExecutionArchiveHealthSnapshot>;
+    private oldestPendingEnqueueAtMs;
+    private recordHealthEvent;
+    private emitArchiveHealthMetrics;
     private closeLossJournal;
-    private enforceQueueBound;
     private appendLossRecords;
     private flushBatch;
+    private clearInFlightBatch;
     private recordFlushHealth;
     private recordArchiveMetric;
     private recordArchiveGauge;
+    private recordArchiveObservableGauge;
     private emitOtelLog;
     private postToForwarder;
 }

package/dist/helpers/user-asset-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 UserAssetArchivePollerConfig = {
+    pollIntervalMs: number;
+};
+export declare class UserAssetArchivePoller {
+    #private;
+    private readonly params;
+    constructor(params: {
+        brokers: Record<string, BrokerPoolEntry>;
+        archiver: BrokerExecutionArchiver;
+        metrics?: OtelMetrics;
+        config?: Partial<UserAssetArchivePollerConfig>;
+    });
+    start(): void;
+    stop(): Promise<void>;
+    pollAllOnce(): Promise<boolean>;
+}

package/dist/index.d.ts

@@ -18,6 +18,8 @@ export default class CEXBroker {
     private fillArchivePoller?;
     private depositArchivePoller?;
     private accountBalanceArchivePoller?;
+    private userAssetArchivePoller?;
+    private balanceUpdateArchiveConsumer?;
     private userDataStreamSupervisor?;
     /**
      * Loads environment variables prefixed with CEX_BROKER_