@usherlabs/cex-broker 0.2.24 → 0.2.26

package/dist/commands/cli.js

@@ -315208,6 +315208,9 @@ function compactUndefined(record) {
   return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined));
 }
 
+// src/helpers/broker-execution-archive/rows.ts
+import { createHash as createHash2 } from "node:crypto";
+
 // src/helpers/broker-execution-archive/redact.ts
 import { createHash } from "node:crypto";
 var SECRET_KEY_PATTERN = /\b(api[_-]?key|api[_-]?secret|secret|signature|passphrase|password|token|credential)\b/i;
@@ -315280,6 +315283,8 @@ function hashMarketMetadata(payload) {
 var BROKER_WRITE_SOURCE = "broker_write";
 var ARCHIVE_SCHEMA_VERSION = "1";
 var FILL_EVENT_KIND = "trade_history_fill";
+var ACCOUNT_BALANCE_SCOPE = "spot";
+var ACCOUNT_BALANCE_PRECISION_BASIS = "ccxt_normalized_number";
 
 // src/helpers/broker-execution-archive/rows.ts
 function firstString2(...values2) {
@@ -315313,6 +315318,151 @@ function normalizeTimestamp2(value) {
   const date = new Date(ms);
   return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
 }
+function decimalString(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return;
+  }
+  if (Object.is(value, -0)) {
+    return "0";
+  }
+  const rendered = String(value).toLowerCase();
+  if (!rendered.includes("e")) {
+    return rendered;
+  }
+  const [coefficient = "", rawExponent = "0"] = rendered.split("e");
+  const exponent = Number.parseInt(rawExponent, 10);
+  const negative = coefficient.startsWith("-");
+  const unsigned = negative ? coefficient.slice(1) : coefficient;
+  const [integer = "0", fraction = ""] = unsigned.split(".");
+  const digits = `${integer}${fraction}`;
+  const decimalIndex = integer.length + exponent;
+  let expanded;
+  if (decimalIndex <= 0) {
+    expanded = `0.${"0".repeat(-decimalIndex)}${digits}`;
+  } else if (decimalIndex >= digits.length) {
+    expanded = `${digits}${"0".repeat(decimalIndex - digits.length)}`;
+  } else {
+    expanded = `${digits.slice(0, decimalIndex)}.${digits.slice(decimalIndex)}`;
+  }
+  return negative ? `-${expanded}` : expanded;
+}
+function normalizedBalanceMap(value) {
+  const record = asRecord(value);
+  if (!record) {
+    return {};
+  }
+  const entries = [];
+  for (const [rawAsset, quantity] of Object.entries(record)) {
+    const asset = rawAsset.trim();
+    const normalized = decimalString(quantity);
+    if (asset && normalized !== undefined) {
+      entries.push([asset, normalized]);
+    }
+  }
+  return Object.fromEntries(entries.sort(([left], [right]) => left.localeCompare(right)));
+}
+function sortedBalanceMap(map) {
+  return Object.fromEntries(Object.entries(map).sort(([left], [right]) => left.localeCompare(right)));
+}
+var BALANCE_METADATA_KEYS = new Set([
+  "info",
+  "timestamp",
+  "datetime",
+  "free",
+  "used",
+  "total",
+  "debt"
+]);
+function normalizeCcxtBalanceForArchive(balance) {
+  const record = asRecord(balance) ?? {};
+  const aggregateRecords = {
+    free: asRecord(record.free),
+    used: asRecord(record.used),
+    total: asRecord(record.total)
+  };
+  const maps = {
+    free: normalizedBalanceMap(record.free),
+    used: normalizedBalanceMap(record.used),
+    total: normalizedBalanceMap(record.total)
+  };
+  const assetEntryAssets = new Set;
+  for (const [rawAsset, value] of Object.entries(record)) {
+    if (BALANCE_METADATA_KEYS.has(rawAsset)) {
+      continue;
+    }
+    const asset = rawAsset.trim();
+    const assetEntry = asRecord(value);
+    if (!asset || !assetEntry || !(("free" in assetEntry) || ("used" in assetEntry) || ("total" in assetEntry))) {
+      continue;
+    }
+    assetEntryAssets.add(asset);
+    for (const field of ["free", "used", "total"]) {
+      const normalized = decimalString(assetEntry[field]);
+      if (normalized !== undefined && maps[field][asset] === undefined) {
+        maps[field][asset] = normalized;
+      }
+    }
+  }
+  const reportedAssets = new Set(assetEntryAssets);
+  for (const aggregateRecord of Object.values(aggregateRecords)) {
+    for (const rawAsset of Object.keys(aggregateRecord ?? {})) {
+      const asset = rawAsset.trim();
+      if (asset) {
+        reportedAssets.add(asset);
+      }
+    }
+  }
+  for (const map of Object.values(maps)) {
+    for (const asset of Object.keys(map)) {
+      reportedAssets.add(asset);
+    }
+  }
+  return {
+    exchangeTimestamp: normalizeTimestamp2(record.timestamp ?? record.datetime),
+    reportedAssets: [...reportedAssets].sort(),
+    assetEntryAssets: [...assetEntryAssets].sort(),
+    freeBalances: sortedBalanceMap(maps.free),
+    usedBalances: sortedBalanceMap(maps.used),
+    totalBalances: sortedBalanceMap(maps.total),
+    freeMapPresent: aggregateRecords.free !== undefined,
+    usedMapPresent: aggregateRecords.used !== undefined,
+    totalMapPresent: aggregateRecords.total !== undefined
+  };
+}
+function buildAccountBalanceSnapshotRow(input) {
+  const { tags, balance } = input;
+  const observationId = createHash2("sha256").update(JSON.stringify({
+    deployment_id: tags.deployment_id,
+    exchange: tags.exchange,
+    account_selector: tags.account_selector,
+    balance_scope: ACCOUNT_BALANCE_SCOPE,
+    broker_observed_timestamp: tags.broker_observed_timestamp,
+    balance
+  })).digest("hex");
+  return {
+    table: "broker_account.balance_snapshots",
+    row: compactUndefined2({
+      broker_observed_timestamp: tags.broker_observed_timestamp,
+      exchange_timestamp: balance.exchangeTimestamp,
+      source: tags.source,
+      deployment_id: tags.deployment_id,
+      schema_version: ARCHIVE_SCHEMA_VERSION,
+      exchange: tags.exchange,
+      account_selector: tags.account_selector,
+      balance_scope: ACCOUNT_BALANCE_SCOPE,
+      observation_id: observationId,
+      reported_assets: balance.reportedAssets,
+      asset_entry_assets: balance.assetEntryAssets,
+      free_balances: balance.freeBalances,
+      used_balances: balance.usedBalances,
+      total_balances: balance.totalBalances,
+      aggregate_free_map_present: Number(balance.freeMapPresent),
+      aggregate_used_map_present: Number(balance.usedMapPresent),
+      aggregate_total_map_present: Number(balance.totalMapPresent),
+      precision_basis: ACCOUNT_BALANCE_PRECISION_BASIS
+    })
+  };
+}
 function compactUndefined2(record) {
   return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined));
 }
@@ -315766,6 +315916,15 @@ function isMarketArchiveTable(table) {
 }
 
 // src/helpers/broker-execution-archive/writer.ts
+var BROKER_EXECUTION_ARCHIVE_TABLES = new Set([
+  "broker_execution.order_events",
+  "broker_execution.market_metadata_snapshots",
+  "broker_execution.transfer_events",
+  "broker_execution.fill_events"
+]);
+function isBrokerExecutionArchiveTable(table) {
+  return BROKER_EXECUTION_ARCHIVE_TABLES.has(table);
+}
 var DEFAULT_MAX_QUEUE_SIZE = 1e4;
 var DEFAULT_BATCH_SIZE = 10;
 var DEFAULT_FLUSH_INTERVAL_MS = 1000;
@@ -315850,6 +316009,9 @@ class BrokerExecutionArchiver {
   canPersistMarketMetadataSnapshot() {
     return this.isEnabled() && (Boolean(this.otelLogs?.isOtelEnabled()) || Boolean(this.forwarderUrl));
   }
+  canPersistAccountBalanceSnapshots() {
+    return this.isEnabled() && Boolean(this.forwarderUrl);
+  }
   enqueue(row) {
     if (!this.enabled || this.closed || !this.otelLogs && !this.forwarderUrl) {
       return;
@@ -315861,6 +316023,9 @@ class BrokerExecutionArchiver {
       }
       return;
     }
+    if (row.table === "broker_account.balance_snapshots" && !this.forwarderUrl) {
+      return;
+    }
     if (this.queue.length >= this.maxQueueSize) {
       this.queue.shift();
       this.stats.shed += 1;
@@ -315939,7 +316104,7 @@ class BrokerExecutionArchiver {
       return true;
     }
     for (const entry of batch) {
-      if (!isMarketArchiveTable(entry.table)) {
+      if (isBrokerExecutionArchiveTable(entry.table)) {
         this.emitOtelLog(entry);
       }
     }
@@ -316075,8 +316240,138 @@ function parsePositiveInt(value, fallback) {
   const parsed = Number.parseInt(value, 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
-// src/helpers/fill-archive-poller.ts
+// src/helpers/account-balance-archive-poller.ts
 var DEFAULT_CONFIG = {
+  pollIntervalMs: 60000
+};
+var metricLabels = (target) => ({
+  exchange: target.exchangeId,
+  account_selector: target.account.label,
+  balance_scope: ACCOUNT_BALANCE_SCOPE
+});
+
+class AccountBalanceArchivePoller {
+  params;
+  #timer = null;
+  #stopped = false;
+  #running = null;
+  #lastSuccessMs = new Map;
+  #config;
+  constructor(params) {
+    this.params = params;
+    this.#config = { ...DEFAULT_CONFIG, ...params.config };
+  }
+  start() {
+    if (this.#timer || this.#stopped || !this.params.archiver.canPersistAccountBalanceSnapshots()) {
+      return;
+    }
+    log.info("\uD83D\uDCB0 Account balance archive poller started", {
+      balanceScope: ACCOUNT_BALANCE_SCOPE
+    });
+    this.#schedule(0);
+  }
+  async stop() {
+    this.#stopped = true;
+    if (this.#timer) {
+      clearTimeout(this.#timer);
+      this.#timer = null;
+    }
+    await this.#running;
+  }
+  async pollAllOnce() {
+    if (this.#stopped || this.#running || !this.params.archiver.canPersistAccountBalanceSnapshots()) {
+      return false;
+    }
+    this.#running = this.#pollAllSequentially();
+    try {
+      return await this.#running;
+    } finally {
+      this.#running = null;
+    }
+  }
+  #targets() {
+    const targets = [];
+    for (const [exchangeId, pool] of Object.entries(this.params.brokers)) {
+      for (const account of [pool.primary, ...pool.secondaryBrokers]) {
+        targets.push({ exchangeId, account });
+      }
+    }
+    return targets;
+  }
+  async#pollAllSequentially() {
+    for (const target of this.#targets()) {
+      if (this.#stopped) {
+        break;
+      }
+      await this.#pollOne(target);
+    }
+    return true;
+  }
+  async#pollOne(target) {
+    const labels = metricLabels(target);
+    this.params.metrics?.recordCounter("cex_account_balance_poll_attempts_total", 1, labels);
+    try {
+      const exchange = target.account.exchange;
+      const balance = await exchange.fetchBalance({
+        type: ACCOUNT_BALANCE_SCOPE
+      });
+      const observedAt = new Date;
+      const normalized = normalizeCcxtBalanceForArchive(balance);
+      this.params.archiver.enqueue(buildAccountBalanceSnapshotRow({
+        tags: buildCommonArchiveTags({
+          deploymentId: this.params.archiver.getDeploymentId(),
+          accountSelector: target.account.label,
+          exchange: target.exchangeId,
+          brokerObservedTimestamp: observedAt.toISOString()
+        }),
+        balance: normalized
+      }));
+      const successMs = Date.now();
+      this.#lastSuccessMs.set(this.#targetKey(target), successMs);
+      this.params.metrics?.recordCounter("cex_account_balance_poll_successes_total", 1, labels);
+      this.params.metrics?.recordGauge("cex_account_balance_poll_last_success_timestamp_seconds", Math.floor(successMs / 1000), labels);
+      this.#recordFreshness(labels, successMs, successMs);
+    } catch (error) {
+      this.params.metrics?.recordCounter("cex_account_balance_poll_failures_total", 1, labels);
+      const now3 = Date.now();
+      const lastSuccess = this.#lastSuccessMs.get(this.#targetKey(target));
+      if (lastSuccess !== undefined) {
+        this.#recordFreshness(labels, lastSuccess, now3);
+      }
+      log.warn("Account balance archive poll failed", {
+        exchange: target.exchangeId,
+        account: target.account.label,
+        balanceScope: ACCOUNT_BALANCE_SCOPE,
+        errorType: error instanceof Error ? error.name : "unknown"
+      });
+    }
+  }
+  #recordFreshness(labels, lastSuccessMs, nowMs) {
+    this.params.metrics?.recordGauge("cex_account_balance_poll_freshness_seconds", Math.max(0, (nowMs - lastSuccessMs) / 1000), labels);
+  }
+  #targetKey(target) {
+    return `${target.exchangeId}|${target.account.label}|${ACCOUNT_BALANCE_SCOPE}`;
+  }
+  #schedule(delayMs) {
+    this.#timer = setTimeout(() => void this.#tick(), delayMs);
+    this.#timer.unref?.();
+  }
+  async#tick() {
+    this.#timer = null;
+    try {
+      await this.pollAllOnce();
+    } catch (error) {
+      log.error("Account balance archive poller tick failed", error);
+    } finally {
+      if (!this.#stopped) {
+        this.#schedule(this.#config.pollIntervalMs);
+      }
+    }
+  }
+}
+
+// src/helpers/fill-archive-poller.ts
+var DEFAULT_CONFIG2 = {
   pollIntervalMs: 60000,
   lookbackMs: 24 * 60 * 60 * 1000,
   tradesLimit: 500
@@ -316101,7 +316396,7 @@ class FillArchivePoller {
   #config;
   constructor(params) {
     this.params = params;
-    this.#config = { ...DEFAULT_CONFIG, ...params.config };
+    this.#config = { ...DEFAULT_CONFIG2, ...params.config };
   }
   start() {
     if (this.#timer || this.#stopped) {
@@ -332125,6 +332420,59 @@ function createExecuteActionHandler(deps) {
     }
   };
 }
+// src/handlers/subscribe/broker-lifecycle.ts
+class SubscribeBrokerLifecycle {
+  #brokers = new Map;
+  #closing = new Map;
+  #shuttingDown = false;
+  register(broker, context2) {
+    this.#brokers.set(broker, context2);
+    if (this.#shuttingDown) {
+      this.close(broker);
+    }
+  }
+  close(broker) {
+    const existing = this.#closing.get(broker);
+    if (existing) {
+      return existing;
+    }
+    const context2 = this.#brokers.get(broker) ?? {
+      cex: "unknown",
+      symbol: "unknown"
+    };
+    this.#brokers.delete(broker);
+    const closing = (async () => {
+      try {
+        await broker.close();
+        log.debug("Request-scoped Subscribe broker closed", context2);
+        return "closed";
+      } catch (error48) {
+        log.warn("Failed to close request-scoped Subscribe broker", {
+          ...context2,
+          error: error48
+        });
+        return "failed";
+      } finally {
+        this.#closing.delete(broker);
+      }
+    })();
+    this.#closing.set(broker, closing);
+    return closing;
+  }
+  async closeAll() {
+    this.#shuttingDown = true;
+    let failed = 0;
+    while (this.#brokers.size > 0 || this.#closing.size > 0) {
+      const inFlight = [...this.#closing.values()];
+      const fresh = [...this.#brokers.keys()].map((broker) => this.close(broker));
+      const outcomes = await Promise.all([...fresh, ...inFlight]);
+      failed += outcomes.filter((outcome) => outcome === "failed").length;
+    }
+    if (failed > 0) {
+      throw new Error(`${failed} request-scoped Subscribe broker(s) failed to close`);
+    }
+  }
+}
 // src/handlers/subscribe/handler.ts
 var grpc13 = __toESM(require_src3(), 1);
 
@@ -332134,6 +332482,7 @@ import { createHmac } from "node:crypto";
 var BINANCE_SPOT_WS_API_URL = "wss://ws-api.binance.com:443/ws-api/v3";
 var DEFAULT_BINANCE_USER_DATA_MAX_BUFFERED_EVENTS = 16;
 var createWebSocket = (url3) => new wrapper_default(url3);
+var userDataRequestCounter = 0;
 function getExchangeString(exchange, key) {
   const value = exchange[key];
   if (typeof value !== "string" || value.length === 0) {
@@ -332240,7 +332589,7 @@ class BinanceSpotUserDataStream {
   exchange;
   ws;
   secretValues;
-  requestId = `user-data-${Date.now()}-${Math.random()}`;
+  requestId = `user-data-${Date.now()}-${userDataRequestCounter++}`;
   maxBufferedEvents;
   queue = [];
   waiters = [];
@@ -332318,6 +332667,12 @@ class BinanceSpotUserDataStream {
       this.subscriptionId = message.result?.subscriptionId ?? null;
       return;
     }
+    if ("status" in message && typeof message.status === "number" && message.status !== 200) {
+      const errorMessage = message.error?.msg ?? message.error?.message ?? `Binance user-data request failed with status ${message.status}`;
+      const errorCode = message.error?.code;
+      this.fail(new Error(typeof errorCode === "number" ? `${errorMessage} (code ${errorCode})` : errorMessage));
+      return;
+    }
     if (!("event" in message) || !message.event) {
       return;
     }
@@ -333194,15 +333549,34 @@ async function runCcxtSubscribeLoop(call, isClosed, symbol2, subscriptionType, w
 }
 function createSubscribeHandler(deps) {
   const { brokers, whitelistIps, otelMetrics, brokerArchiver } = deps;
+  const brokerLifecycle = deps.brokerLifecycle ?? new SubscribeBrokerLifecycle;
   return async (call) => {
     const subscribeStartTime = Date.now();
     let streamClosed = false;
+    let ownedBroker = null;
+    let ownedBrokerClosePromise;
     const markStreamClosed = () => {
       streamClosed = true;
     };
-    const isStreamClosed = () => streamClosed || call.destroyed;
-    call.once("close", markStreamClosed);
+    const isStreamClosed = () => streamClosed || call.cancelled || call.writableEnded;
+    const closeOwnedBroker = () => {
+      if (ownedBrokerClosePromise) {
+        return ownedBrokerClosePromise;
+      }
+      if (!ownedBroker) {
+        return Promise.resolve();
+      }
+      const broker = ownedBroker;
+      ownedBroker = null;
+      ownedBrokerClosePromise = brokerLifecycle.close(broker);
+      return ownedBrokerClosePromise;
+    };
+    const closeOwnedBrokerOnCallEnd = () => {
+      closeOwnedBroker();
+    };
     call.once("cancelled", markStreamClosed);
+    call.once("cancelled", closeOwnedBrokerOnCallEnd);
+    call.once("error", closeOwnedBrokerOnCallEnd);
     call.once("end", () => {
       markStreamClosed();
       log.info("Subscribe stream ended");
@@ -333274,6 +333648,17 @@ function createSubscribeHandler(deps) {
         });
         return;
       }
+      if (!selectedBrokerAccount) {
+        ownedBroker = broker;
+        brokerLifecycle.register(broker, {
+          cex: normalizedCex,
+          symbol: symbol2
+        });
+        if (isStreamClosed()) {
+          await closeOwnedBroker();
+          return;
+        }
+      }
       const resolvedSymbol = await resolveSubscriptionSymbol(broker, symbol2, options?.marketType);
       const assetType = parseMarketType(options?.marketType);
       const deploymentId = brokerArchiver?.getDeploymentId() ?? "unknown";
@@ -333538,6 +333923,10 @@ function createSubscribeHandler(deps) {
         symbol: "",
         type: subscriptionType
       });
+    } finally {
+      call.off("cancelled", closeOwnedBrokerOnCallEnd);
+      call.off("error", closeOwnedBrokerOnCallEnd);
+      await closeOwnedBroker();
     }
   };
 }
@@ -333688,7 +334077,7 @@ var CEX_BROKER_PACKAGE_DEFINITION = protoLoader.fromJSON(node_descriptor_default
 // src/server.ts
 var grpcObj = grpc14.loadPackageDefinition(CEX_BROKER_PACKAGE_DEFINITION);
 var cexNode = grpcObj.cex_broker;
-function getServer(policy, brokers, whitelistIps, useVerity, verityProverUrl, otelMetrics, brokerArchiver, orderActivityTracker, withdrawalObservationTracker) {
+function getServer(policy, brokers, whitelistIps, useVerity, verityProverUrl, otelMetrics, brokerArchiver, orderActivityTracker, withdrawalObservationTracker, subscribeBrokerLifecycle) {
   const server = new grpc14.Server;
   server.addService(cexNode.cex_service.service, {
     ExecuteAction: createExecuteActionHandler({
@@ -333706,7 +334095,8 @@ function getServer(policy, brokers, whitelistIps, useVerity, verityProverUrl, ot
       brokers,
       whitelistIps,
       otelMetrics,
-      brokerArchiver
+      brokerArchiver,
+      brokerLifecycle: subscribeBrokerLifecycle
     })
   });
   return server;
@@ -333848,6 +334238,7 @@ class CEXBroker {
   orderActivityTracker = new OrderActivityTracker;
   withdrawalObservationTracker = new WithdrawalObservationTracker;
   fillArchivePoller;
+  accountBalanceArchivePoller;
   loadEnvConfig() {
     log.info("\uD83D\uDD27 Loading CEX_BROKER_ environment variables:");
     const configMap = {};
@@ -333992,6 +334383,10 @@ class CEXBroker {
       this.fillArchivePoller.stop();
       this.fillArchivePoller = undefined;
     }
+    if (this.accountBalanceArchivePoller) {
+      await this.accountBalanceArchivePoller.stop();
+      this.accountBalanceArchivePoller = undefined;
+    }
     if (this.server) {
       await this.server.forceShutdown();
     }
@@ -334017,6 +334412,10 @@ class CEXBroker {
       this.fillArchivePoller.stop();
       this.fillArchivePoller = undefined;
     }
+    if (this.accountBalanceArchivePoller) {
+      await this.accountBalanceArchivePoller.stop();
+      this.accountBalanceArchivePoller = undefined;
+    }
     log.info(`Running CEXBroker at ${new Date().toISOString()}`);
     if (this.otelMetrics?.isOtelEnabled()) {
       await this.otelMetrics.initialize();
@@ -334045,6 +334444,14 @@ class CEXBroker {
       });
       this.fillArchivePoller.start();
     }
+    if (this.brokerArchiver?.canPersistAccountBalanceSnapshots()) {
+      this.accountBalanceArchivePoller = new AccountBalanceArchivePoller({
+        brokers: this.brokers,
+        archiver: this.brokerArchiver,
+        metrics: this.otelMetrics
+      });
+      this.accountBalanceArchivePoller.start();
+    }
     return this;
   }
 }

package/dist/handlers/subscribe/broker-lifecycle.d.ts

@@ -0,0 +1,13 @@
+import type { Exchange } from "@usherlabs/ccxt";
+type BrokerContext = {
+    cex: string;
+    symbol: string;
+};
+export type BrokerCloseOutcome = "closed" | "failed";
+export declare class SubscribeBrokerLifecycle {
+    #private;
+    register(broker: Exchange, context: BrokerContext): void;
+    close(broker: Exchange): Promise<BrokerCloseOutcome>;
+    closeAll(): Promise<void>;
+}
+export {};

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

@@ -3,11 +3,13 @@ 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";
+import { SubscribeBrokerLifecycle } from "./broker-lifecycle";
 export type SubscribeDeps = {
     brokers: Record<string, BrokerPoolEntry>;
     whitelistIps: string[];
     otelMetrics?: OtelMetrics;
     brokerArchiver?: BrokerExecutionArchiver;
+    brokerLifecycle?: SubscribeBrokerLifecycle;
 };
 type SubscribeCall = grpc.ServerWritableStream<SubscribeRequest, SubscribeResponse>;
 export declare function createSubscribeHandler(deps: SubscribeDeps): (call: SubscribeCall) => Promise<void>;

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

@@ -1 +1,2 @@
+export { SubscribeBrokerLifecycle } from "./broker-lifecycle";
 export { createSubscribeHandler, type SubscribeDeps } from "./handler";

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/index.d.ts

@@ -1,6 +1,6 @@
 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, type NormalizedCcxtTransfer, normalizeCcxtTradeForArchive, normalizeCcxtTransactionForArchive, 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 { 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, resolveArchiveForwarderUrlFromEnv, } from "./writer";
+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>;
@@ -18,3 +18,5 @@ 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 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";