@usherlabs/cex-broker 0.2.15 → 0.2.17

package/dist/helpers/index.d.ts

@@ -3,7 +3,8 @@ import type { PolicyConfig } from "../types";
 import { type BrokerAccount } from "./broker";
 export { authenticateRequest } from "./auth";
 export { applyCommonExchangeConfig, type BrokerAccount, BrokerAccountPreconditionError, type BrokerPoolEntry, createBroker, createBrokerPool, createPublicBroker, getCurrentBrokerSelector, resolveBrokerAccount, selectBroker, selectBrokerAccount, } from "./broker";
-export { australiaQuestionnaireSchema, registerBinanceTravelRuleWithdrawEndpoint, resolveTravelRuleDecision, type TravelRuleDecision, withdrawViaLocalEntity, } from "./travel-rule";
+export { australiaDepositQuestionnaireSchema, australiaQuestionnaireSchema, getEnabledTravelRuleDepositConfig, registerBinanceTravelRuleDepositEndpoints, registerBinanceTravelRuleWithdrawEndpoint, resolveDepositOriginatorQuestionnaire, resolveTravelRuleDecision, type TravelRuleDecision, withdrawViaLocalEntity, } from "./travel-rule";
+export { loadTravelRuleDepositReconcilerConfigFromEnv, resolveOnChainSender, TravelRuleDepositReconciler, } from "./travel-rule-deposit-reconciler";
 export { buildHttpClientOverrideFromMetadata, createVerityHttpClientOverride, verityHttpClientOverridePredicate, } from "./verity";
 /**
  * Loads and validates policy configuration

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

@@ -0,0 +1,152 @@
+import type { PolicyConfig, TravelRuleDepositConfig, TravelRuleDepositQuestionnaire } from "../types";
+import type { BrokerPoolEntry } from "./broker";
+import type { OtelMetrics } from "./otel";
+/**
+ * Auto-clear reconciler for Binance travel-rule-frozen DEPOSITS.
+ *
+ * Under the AUSTRAC travel rule Binance credits an inbound deposit but holds it
+ * in `getUserAsset.freeze` (invisible to free+locked balances) until a per-deposit
+ * questionnaire is answered. This reconciler polls `localentity/deposit/history`
+ * for such frozen deposits and submits the questionnaire — but only for deposits
+ * whose on-chain sender is PROVEN (via `eth_getTransactionByHash`) to be one of
+ * our configured originator wallets. Everything else is left frozen and surfaced.
+ *
+ * Compliance invariant: a deposit is NEVER auto-declared unless its origin is
+ * proven ours. Undeclared origin, unresolvable sender, entity drift, or any
+ * uncertainty all fail closed (skip + surface), never "declare anyway".
+ *
+ * This runs entirely broker-internal (not through the gRPC verity path), so
+ * provide-info carries no verity proof — acceptable for a compliance attestation
+ * that is not a trading action; see the plan's edge-case notes.
+ */
+export type LocalEntityDeposit = {
+    tranId: string;
+    coin: string;
+    amount: string;
+    network: string;
+    txId: string;
+    travelRuleStatus: string;
+    requireQuestionnaire: boolean;
+    raw: Record<string, unknown>;
+};
+/**
+ * Parses one raw `localentity/deposit/history` row. Returns null when the row
+ * lacks a tranId (the only id valid for provide-info — the `capital/deposit/hisrec`
+ * id is a different id space and yields "Deposit request not found").
+ */
+export declare function parseLocalEntityDeposit(raw: Record<string, unknown>): LocalEntityDeposit | null;
+/**
+ * Resolves the on-chain sender (`tx.from`) of a deposit's transaction hash via a
+ * JSON-RPC `eth_getTransactionByHash`. Returns the lowercased sender, or null
+ * when the hash is not a well-formed EVM tx hash or the tx is not found (pruned
+ * node / reorg / not yet mined) — both of which mean the origin is UNPROVEN and
+ * the caller must skip rather than assume.
+ *
+ * `tx.from` is the EOA that signed the deposit transaction. For our funding
+ * 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.
+ */
+export declare function resolveOnChainSender(rpcUrl: string, txHash: string, timeoutMs?: number): Promise<string | null>;
+/** Binance rate-limit signals (-1003 / HTTP 429 / DDoS guard). */
+export declare function isRateLimitError(error: unknown): boolean;
+/**
+ * A provide-info call that Binance treats as already-satisfied. Re-submitting a
+ * tranId that was already provided (a manual release, or a reconciler restart)
+ * must be idempotent, so these responses/errors count as success.
+ */
+export declare function isAlreadyProvidedError(error: unknown): boolean;
+export type ReconcilerAccountState = {
+    submittedTranIds: Set<string>;
+    surfacedFailed: Set<string>;
+    backoffUntil: Map<string, number>;
+    rateLimitedUntil: number;
+};
+export declare function createAccountState(): ReconcilerAccountState;
+export type ReconcileOutcome = {
+    kind: "submitted";
+    deposit: LocalEntityDeposit;
+    sender: string;
+} | {
+    kind: "already-provided";
+    deposit: LocalEntityDeposit;
+    sender: string;
+} | {
+    kind: "undeclared-origin";
+    deposit: LocalEntityDeposit;
+    sender: string;
+} | {
+    kind: "unproven-origin";
+    deposit: LocalEntityDeposit;
+} | {
+    kind: "entity-drift";
+    deposit: LocalEntityDeposit;
+    country: string | null;
+} | {
+    kind: "failed-terminal";
+    deposit: LocalEntityDeposit;
+} | {
+    kind: "submit-error";
+    deposit: LocalEntityDeposit;
+    error: string;
+} | {
+    kind: "poll-error";
+    error: string;
+};
+export type ReconcileAccountReport = {
+    accountLabel: string;
+    frozenDeposits: LocalEntityDeposit[];
+    outcomes: ReconcileOutcome[];
+    hadActionableWork: boolean;
+};
+export type ReconcileAccountDeps = {
+    accountLabel: string;
+    depositConfig: TravelRuleDepositConfig;
+    expectedCountry: string;
+    failureBackoffMs: number;
+    rateLimitCooldownMs: number;
+    now: number;
+    state: ReconcilerAccountState;
+    fetchDepositHistory: () => Promise<Array<Record<string, unknown>>>;
+    fetchQuestionnaireCountry: () => Promise<string | null>;
+    resolveSender: (network: string, txId: string) => Promise<string | null>;
+    submitProvideInfo: (tranId: string, questionnaire: TravelRuleDepositQuestionnaire) => Promise<Record<string, unknown>>;
+    resolveQuestionnaire: (config: TravelRuleDepositConfig, sender: string) => TravelRuleDepositQuestionnaire | null;
+};
+/**
+ * Reconciles a single account once. Pure orchestration: all I/O is injected so
+ * the compliance invariants (never submit an unproven/undeclared/entity-drifted
+ * deposit) are unit-testable without a network. Fetch/poll errors are captured
+ * as outcomes rather than thrown so one bad account never stalls the loop.
+ */
+export declare function reconcileAccountOnce(deps: ReconcileAccountDeps): Promise<ReconcileAccountReport>;
+export type TravelRuleDepositReconcilerConfig = {
+    rpcUrlsByNetwork: Record<string, string>;
+    pollIntervalActiveMs: number;
+    pollIntervalIdleMs: number;
+    expectedQuestionnaireCountry: string;
+    failureBackoffMs: number;
+    rateLimitCooldownMs: number;
+};
+/**
+ * Builds reconciler config from the environment. RPC URLs are read from
+ * `TRAVEL_RULE_RPC_URL_<NETWORK>` vars (network suffix must match Binance's
+ * network code, e.g. `TRAVEL_RULE_RPC_URL_ARBITRUM`). These are intentionally NOT
+ * `CEX_BROKER_`-prefixed so the credential env scan ignores them. Cadence and the
+ * expected questionnaire country are overridable but default to the AU rollout.
+ */
+export declare function loadTravelRuleDepositReconcilerConfigFromEnv(env: Record<string, string | undefined>): TravelRuleDepositReconcilerConfig;
+export declare class TravelRuleDepositReconciler {
+    #private;
+    private readonly params;
+    constructor(params: {
+        policy: PolicyConfig;
+        brokers: Record<string, BrokerPoolEntry>;
+        config: TravelRuleDepositReconcilerConfig;
+        metrics?: OtelMetrics;
+    });
+    /** True when at least one exchange has deposit auto-clear enabled in policy. */
+    static hasEnabledExchange(policy: PolicyConfig): boolean;
+    start(): void;
+    stop(): void;
+}

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

@@ -1,6 +1,6 @@
 import type { Exchange } from "@usherlabs/ccxt";
 import Joi from "joi";
-import type { PolicyConfig, TravelRuleQuestionnaire } from "../types";
+import type { PolicyConfig, TravelRuleDepositConfig, TravelRuleDepositQuestionnaire, TravelRuleQuestionnaire } from "../types";
 export declare const australiaQuestionnaireSchema: Joi.ObjectSchema<any>;
 export type TravelRuleDecision = {
     mode: "standard";
@@ -26,6 +26,37 @@ export declare function resolveTravelRuleDecision(policy: PolicyConfig, exchange
  * the generated implicit method if called again.
  */
 export declare function registerBinanceTravelRuleWithdrawEndpoint(exchange: Exchange): void;
+export declare const australiaDepositQuestionnaireSchema: Joi.ObjectSchema<any>;
+/**
+ * Returns the enabled deposit travel-rule config for an exchange, or null when
+ * the feature is absent or disabled. Gated solely by `deposits.enabled` (not the
+ * entry's withdraw `enabled` flag): when null the reconciler does nothing for the
+ * exchange, preserving exact pre-feature behavior.
+ */
+export declare function getEnabledTravelRuleDepositConfig(policy: PolicyConfig, exchange: string): TravelRuleDepositConfig | null;
+/**
+ * Looks up the questionnaire for a PROVEN on-chain sender. Matching is
+ * case-insensitive. Returns null when the sender is not a declared originator —
+ * the reconciler must then leave the deposit frozen and surface an anomaly
+ * rather than attest an origin it cannot prove is ours.
+ */
+export declare function resolveDepositOriginatorQuestionnaire(config: TravelRuleDepositConfig, senderAddress: string): TravelRuleDepositQuestionnaire | null;
+/**
+ * Registers Binance's localentity deposit endpoints used by the reconciler:
+ * the two read endpoints (deposit history + questionnaire requirements) and the
+ * provide-info write. No-op for non-Binance exchanges. Idempotent.
+ *
+ * `localentity/deposit/provide-info` must be signed with the questionnaire JSON
+ * RAW (unencoded) — see the @usherlabs/ccxt patch (`binance.sign` rawencode
+ * branch). Signing it url-encoded yields Binance error -1022. The two GETs carry
+ * only simple params and sign fine either way.
+ *
+ * provide-info is a 600-weight UID-limited write (same class as
+ * capital/withdraw/apply), so it carries ccxt-binance's `4.0002` cost encoding
+ * (`.0002` = charge the UID limiter) rather than a naive `1`, which would
+ * under-throttle the write and invite -1003 once attestation is active.
+ */
+export declare function registerBinanceTravelRuleDepositEndpoints(exchange: Exchange): void;
 type LocalEntityWithdrawArgs = {
     code: string;
     amount: number;

package/dist/index.d.ts

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