@kehtus/proportion-sdk 1.2.0 → 1.4.1

package/dist/indexer.js

@@ -7,11 +7,39 @@ export class IndexerModule {
     subscriptions = new Map();
     reconnectTimer = null;
     reconnectDelay = 1000;
+    // "Connected" = socket open AND Hasura acked connection_init — only then are
+    // subscriptions actually live (graphql-transport-ws forbids subscribe before ack).
+    wsConnected = false;
+    connStateHandlers = new Set();
+    subErrorHandlers = new Set();
+    // Liveness watchdog: Hasura pings every few seconds, so a healthy socket is never
+    // silent for long. A half-open TCP path (sleep/wake, NAT rebind) keeps readyState
+    // OPEN with no close event for minutes — the watchdog declares it dead instead.
+    watchdogTimer = null;
+    lastInboundAt = 0;
+    // Per-op resubscribe after a server-terminated operation (error/complete frame).
+    // The socket stays alive in that case, so the reconnect-ack flush alone would
+    // never retry the op — these timers do, with backoff, on the SAME connection.
+    opRetryTimers = new Map();
+    opRetryAttempts = new Map();
+    static WS_SILENCE_TIMEOUT_MS = 45_000;
+    static WS_WATCHDOG_INTERVAL_MS = 15_000;
+    static OP_RETRY_BASE_DELAY_MS = 5_000;
+    static OP_RETRY_MAX_DELAY_MS = 60_000;
     cachedProtocol; // undefined = not fetched yet
     constructor(graphqlUrl, graphqlWsUrl, transports = {}) {
         this.graphqlUrl = graphqlUrl;
         this.graphqlWsUrl = graphqlWsUrl;
         this.transports = transports;
+        // Derive the subscription URL from the HTTP URL when omitted (http→ws, https→wss) so a
+        // missing graphqlWsUrl doesn't silently disable subscriptions; then validate the scheme so
+        // a wrong-but-valid URL fails loud instead of looping in silent reconnects while HTTP works.
+        if (!this.graphqlWsUrl) {
+            this.graphqlWsUrl = this.graphqlUrl.replace(/^http(s?):\/\//i, "ws$1://");
+        }
+        if (!/^wss?:\/\//i.test(this.graphqlWsUrl)) {
+            throw new Error(`graphqlWsUrl must be a ws:// or wss:// URL (got: ${this.graphqlWsUrl})`);
+        }
     }
     static PAGE_SIZE = 1000;
     static VAULT_FIELDS = `id address totalDeposits totalWithdrawals totalActivationFees cumulativeActivationFeesToVault totalAllocated totalShares cumulativeProfitShares cumulativeCancelledProfit cumulativeSubscriptionFees cumulativeProtocolFeesRouted cumulativeHypercoreFees cumulativeAccountGains cumulativeAccountLosses cumulativeRescuedFunds totalAccountsActivated totalAccountsActive totalAccountsClosed paused subscriptionFeeMultiplier protocolFeeBps protocolFeeReceiver updatedAt`;
@@ -24,9 +52,10 @@ export class IndexerModule {
     static VAULT_DAY_DATA_FIELDS = `id date dayNumber evmBalance totalAllocated totalAssets totalShares sharePrice dailyDeposits dailyWithdrawals dailyNetLpFlow dailyActivationFees dailyActivationFeesToVault dailyProfitShares dailyCancelledProfit dailySubscriptionFees dailyProtocolFeesRouted dailyHypercoreFees dailyRescuedFunds dailyAccountReturnAmount dailyAccountPrincipalReturned dailyAccountGains dailyAccountLosses dailyPerformancePnl dailyClosedAccountNetPnl cumulativeRealizedPnl totalAccountsActivated totalAccountsActive totalAccountsClosed accountsActivatedToday accountsClosedToday navChange24h sharePriceChange24h return24hBps realizedReturn24hBps paused updatedAt`;
     static LP_DAY_DATA_FIELDS = `id lp { id } date dayNumber shares sharesValue dailyDeposits dailyWithdrawals depositCount withdrawCount`;
     // ── Challenge / B-book field sets (envio-unified schema) ──
-    static CHALLENGE_FIELDS = `id trader { id } builder { id address } payer vaultAddress allocation6 initialBalance6 phase failReason currentPhase reduceOnly totalPhases targetProfitBps finalTargetProfitBps drawdownBps dailyDrawdownEnabled tradingDaysEnabled profitableDaysRequired maxLeverageBps maxNotional6 maxOpenPositions minHoldBlocks freeBalance6 realizedPnl6 totalTradingFees6 equity6 highWaterMark6 dayStartEquity6 profitableDaysCount positionCount openPositionCount liquidationCount tradeCount totalVolume6 challengeFee6 builderAmount6 quoteHash quoteNonce quoteDeadline totalPayoutGross6 payoutCount promotedFundedAccount { id } activationFeePaid6 activatedAt challengeExpiry passedAt paperFundedAt failedAt closedAt promotedAt createdAt updatedAt`;
+    static CHALLENGE_FIELDS = `id trader { id } builder { id address } payer vaultAddress allocation6 initialBalance6 phase failReason currentPhase reduceOnly totalPhases targetProfitBps finalTargetProfitBps drawdownBps dailyDrawdownEnabled tradingDaysEnabled profitableDaysRequired maxLeverageBps maxNotional6 maxOpenPositions minHoldBlocks freeBalance6 realizedPnl6 totalTradingFees6 equity6 highWaterMark6 dayStartEquity6 profitableDaysCount positionCount openPositionCount liquidationCount tradeCount totalVolume6 challengeFee6 builderAmount6 quoteHash quoteNonce quoteDeadline totalPayoutGross6 payoutCount promotedFundedAccount { id } activationFeePaid6 activatedAt challengeExpiry passedAt paperFundedAt failedAt closedAt promotedAt createdAt updatedAt lastUpdatedBlock`;
     static CHALLENGE_BUILDER_FIELDS = `id address balance6 pendingPayouts6 delinquentSince isDelinquent activeChallengeExposure6 passedExposure6 paperFundedExposure6 queuedPayoutExposure6 pendingPassedAccounts pendingPayoutCount quoteEpoch totalFeesCollected6 totalDeposited6 totalWithdrawn6 totalInstantPaid6 totalQueuedPaid6 totalActivationFeesDebited6 challengesSold challengesPassed challengesPromoted registeredAt updatedAt`;
-    static CHALLENGE_POSITION_FIELDS = `id challenge { id } positionId market isLong status entryPrice marginOpen6 notionalOpen6 marginCurrent6 notionalCurrent6 cumulativeReducedNotional6 realizedPnl6 openFee6 closeFee6 exitPrice stopLossPrice takeProfitPrice exitOrderExecutedKind exitOrderTriggerPrice exitOrderRiskPrice exitOrderExecutedAt openedAtBlock openTx closeTx openedAt closedAt updatedAt`;
+    static CHALLENGE_POSITION_FIELDS = `id challenge { id } positionId market isLong status entryPrice marginOpen6 notionalOpen6 marginCurrent6 notionalCurrent6 cumulativeReducedNotional6 realizedPnl6 openFee6 closeFee6 exitPrice stopLossPrice takeProfitPrice exitOrderExecutedKind exitOrderTriggerPrice exitOrderRiskPrice exitOrderExecutedAt openedAtBlock openTx closeTx openedAt closedAt updatedAt lastUpdatedBlock`;
+    static CHALLENGE_SESSION_KEY_FIELDS = `id challenge { id } key expiry permissions active registeredAt revokedAt updatedAt`;
     static CHALLENGE_TRADE_FIELDS = `id challenge { id } positionId kind market isLong margin6 notional6 price pnl6 fee6 freeBalanceAfter6 blockNumber timestamp txHash`;
     static CHALLENGE_CHECKPOINT_FIELDS = `id challenge { id } kind equity6 highWaterMark6 dayStartEquity6 profitableDaysCount blockNumber timestamp txHash`;
     static CHALLENGE_PAYOUT_FIELDS = `id challenge { id } trader { id } builderAddress requestedGross6 instantPaid6 queuedGross6 queuedPaid6 queueId fullyPaid requestedAt blockNumber txHash`;
@@ -442,26 +471,31 @@ export class IndexerModule {
         return data.AllowedPerp;
     }
     // ── CHALLENGE / B-BOOK (envio-unified) ────────────
+    // NB: challenge-family ids (Challenge.id, Trader.id, ChallengeBuilder.id and the
+    // FK columns derived from them) are canonically LOWERCASE in envio-unified — so
+    // these paths lowercase the argument and filter with `_eq`, which lets Postgres
+    // use the FK btree indexes. `_ilike` (still used on funded/checksummed columns)
+    // defeats those indexes — fatal for the ~1s Hasura live-query refetch loop.
     async getChallenge(address) {
         const data = await this.query(`
-      query($id: String!) { Challenge(where: { id: { _ilike: $id } }) { ${IndexerModule.CHALLENGE_FIELDS} } }
-    `, { id: address });
+      query($id: String!) { Challenge(where: { id: { _eq: $id } }) { ${IndexerModule.CHALLENGE_FIELDS} } }
+    `, { id: address.toLowerCase() });
         return data.Challenge[0] ?? null;
     }
     async getChallengesByTrader(trader, p) {
         const data = await this.query(`
       query($trader: String!, $limit: Int, $offset: Int) {
-        Challenge(where: { trader_id: { _ilike: $trader } }, order_by: { createdAt: desc }, limit: $limit, offset: $offset) { ${IndexerModule.CHALLENGE_FIELDS} }
+        Challenge(where: { trader_id: { _eq: $trader } }, order_by: [{ createdAt: desc }, { id: desc }], limit: $limit, offset: $offset) { ${IndexerModule.CHALLENGE_FIELDS} }
       }
-    `, { trader, limit: p?.limit ?? 50, offset: p?.offset ?? 0 });
+    `, { trader: trader.toLowerCase(), limit: p?.limit ?? 50, offset: p?.offset ?? 0 });
         return data.Challenge;
     }
     async getChallengesByBuilder(builder, p) {
         const data = await this.query(`
       query($builder: String!, $limit: Int, $offset: Int) {
-        Challenge(where: { builder_id: { _ilike: $builder } }, order_by: { createdAt: desc }, limit: $limit, offset: $offset) { ${IndexerModule.CHALLENGE_FIELDS} }
+        Challenge(where: { builder_id: { _eq: $builder } }, order_by: [{ createdAt: desc }, { id: desc }], limit: $limit, offset: $offset) { ${IndexerModule.CHALLENGE_FIELDS} }
       }
-    `, { builder, limit: p?.limit ?? 50, offset: p?.offset ?? 0 });
+    `, { builder: builder.toLowerCase(), limit: p?.limit ?? 50, offset: p?.offset ?? 0 });
         return data.Challenge;
     }
     async getChallengesByPhase(phase, p) {
@@ -474,35 +508,52 @@ export class IndexerModule {
     }
     async getChallengeBuilder(address) {
         const data = await this.query(`
-      query($id: String!) { ChallengeBuilder(where: { id: { _ilike: $id } }) { ${IndexerModule.CHALLENGE_BUILDER_FIELDS} } }
-    `, { id: address });
+      query($id: String!) { ChallengeBuilder(where: { id: { _eq: $id } }) { ${IndexerModule.CHALLENGE_BUILDER_FIELDS} } }
+    `, { id: address.toLowerCase() });
         return data.ChallengeBuilder[0] ?? null;
     }
+    // positionId tiebreaker: block-second timestamps tie on netting flips (Close+Open
+    // in one tx) — without it Postgres may permute equal-key rows between refetches.
     async getChallengePositions(challenge, p) {
         const openFilter = p?.openOnly ? `status: { _eq: Open }` : "";
         const data = await this.query(`
       query($challenge: String!, $limit: Int, $offset: Int) {
-        ChallengePosition(where: { challenge_id: { _ilike: $challenge } ${openFilter} }, order_by: { openedAt: desc }, limit: $limit, offset: $offset) { ${IndexerModule.CHALLENGE_POSITION_FIELDS} }
+        ChallengePosition(where: { challenge_id: { _eq: $challenge } ${openFilter} }, order_by: [{ openedAt: desc }, { positionId: desc }], limit: $limit, offset: $offset) { ${IndexerModule.CHALLENGE_POSITION_FIELDS} }
       }
-    `, { challenge, limit: p?.limit ?? 50, offset: p?.offset ?? 0 });
+    `, { challenge: challenge.toLowerCase(), limit: p?.limit ?? 50, offset: p?.offset ?? 0 });
         return data.ChallengePosition;
     }
     async getChallengeTrades(challenge, p) {
         const data = await this.query(`
       query($challenge: String!, $limit: Int, $offset: Int) {
-        ChallengeTrade(where: { challenge_id: { _ilike: $challenge } }, order_by: { timestamp: desc }, limit: $limit, offset: $offset) { ${IndexerModule.CHALLENGE_TRADE_FIELDS} }
+        ChallengeTrade(where: { challenge_id: { _eq: $challenge } }, order_by: [{ timestamp: desc }, { id: desc }], limit: $limit, offset: $offset) { ${IndexerModule.CHALLENGE_TRADE_FIELDS} }
       }
-    `, { challenge, limit: p?.limit ?? 50, offset: p?.offset ?? 0 });
+    `, { challenge: challenge.toLowerCase(), limit: p?.limit ?? 50, offset: p?.offset ?? 0 });
         return data.ChallengeTrade;
     }
     async getChallengeCheckpoints(challenge, p) {
         const data = await this.query(`
       query($challenge: String!, $limit: Int, $offset: Int) {
-        ChallengeCheckpoint(where: { challenge_id: { _ilike: $challenge } }, order_by: { timestamp: desc }, limit: $limit, offset: $offset) { ${IndexerModule.CHALLENGE_CHECKPOINT_FIELDS} }
+        ChallengeCheckpoint(where: { challenge_id: { _eq: $challenge } }, order_by: [{ timestamp: desc }, { id: desc }], limit: $limit, offset: $offset) { ${IndexerModule.CHALLENGE_CHECKPOINT_FIELDS} }
       }
-    `, { challenge, limit: p?.limit ?? 50, offset: p?.offset ?? 0 });
+    `, { challenge: challenge.toLowerCase(), limit: p?.limit ?? 50, offset: p?.offset ?? 0 });
         return data.ChallengeCheckpoint;
     }
+    /**
+     * Session keys registered on a challenge clone. The indexer is the ONLY
+     * enumeration source (on-chain `getSessionKey(key)` needs the key upfront);
+     * per-key caps/marketMask are NOT in events by contract design — enrich a
+     * selected key via RPC `challenge.getSessionKey` when displaying details.
+     */
+    async getChallengeSessionKeys(challenge, opts) {
+        const activeFilter = opts?.activeOnly ? ` active: { _eq: true }` : "";
+        const data = await this.query(`
+      query($challenge: String!, $limit: Int, $offset: Int) {
+        ChallengeSessionKey(where: { challenge_id: { _eq: $challenge }${activeFilter} }, order_by: [{ registeredAt: desc }, { id: desc }], limit: $limit, offset: $offset) { ${IndexerModule.CHALLENGE_SESSION_KEY_FIELDS} }
+      }
+    `, { challenge: challenge.toLowerCase(), limit: opts?.limit ?? 50, offset: opts?.offset ?? 0 });
+        return data.ChallengeSessionKey;
+    }
     async getChallengePayouts(filter, p) {
         const clauses = [];
         const variableDefs = ["$limit: Int", "$offset: Int"];
@@ -534,9 +585,9 @@ export class IndexerModule {
     async getPayoutQueue(builder, p) {
         const data = await this.query(`
       query($builder: String!, $limit: Int, $offset: Int) {
-        ChallengePayoutQueueEntry(where: { builder_id: { _ilike: $builder } fullyPaid: { _eq: false } }, order_by: { queueId: asc }, limit: $limit, offset: $offset) { ${IndexerModule.CHALLENGE_QUEUE_ENTRY_FIELDS} }
+        ChallengePayoutQueueEntry(where: { builder_id: { _eq: $builder } fullyPaid: { _eq: false } }, order_by: { queueId: asc }, limit: $limit, offset: $offset) { ${IndexerModule.CHALLENGE_QUEUE_ENTRY_FIELDS} }
       }
-    `, { builder, limit: p?.limit ?? 50, offset: p?.offset ?? 0 });
+    `, { builder: builder.toLowerCase(), limit: p?.limit ?? 50, offset: p?.offset ?? 0 });
         return data.ChallengePayoutQueueEntry;
     }
     async getChallengeDayData(p) {
@@ -622,23 +673,175 @@ export class IndexerModule {
         return data.FounderWeeklyBoost;
     }
     // ── SUBSCRIPTIONS (Hasura graphql-transport-ws) ───
+    setWsConnected(connected) {
+        if (this.wsConnected === connected)
+            return;
+        this.wsConnected = connected;
+        for (const cb of this.connStateHandlers) {
+            try {
+                cb(connected);
+            }
+            catch {
+                // A throwing listener must not break the WS pump or other listeners.
+            }
+        }
+    }
+    detachSocket(ws) {
+        ws.onopen = null;
+        ws.onmessage = null;
+        ws.onclose = null;
+        ws.onerror = null;
+    }
+    stopWatchdog() {
+        if (this.watchdogTimer) {
+            clearInterval(this.watchdogTimer);
+            this.watchdogTimer = null;
+        }
+    }
+    clearOpRetry(id) {
+        const timer = this.opRetryTimers.get(id);
+        if (timer) {
+            clearTimeout(timer);
+            this.opRetryTimers.delete(id);
+        }
+        this.opRetryAttempts.delete(id);
+    }
+    clearAllOpRetries() {
+        for (const timer of this.opRetryTimers.values())
+            clearTimeout(timer);
+        this.opRetryTimers.clear();
+        this.opRetryAttempts.clear();
+    }
+    /** Resubscribe a server-terminated op on the live socket, with backoff. */
+    scheduleOpRetry(id) {
+        if (!this.subscriptions.has(id) || this.opRetryTimers.has(id))
+            return;
+        const attempts = this.opRetryAttempts.get(id) ?? 0;
+        this.opRetryAttempts.set(id, attempts + 1);
+        const delay = Math.min(IndexerModule.OP_RETRY_BASE_DELAY_MS * 2 ** attempts, IndexerModule.OP_RETRY_MAX_DELAY_MS);
+        const timer = setTimeout(() => {
+            this.opRetryTimers.delete(id);
+            const sub = this.subscriptions.get(id);
+            if (!sub)
+                return;
+            const WebSocketCtor = (this.transports.webSocketCtor ?? globalThis.WebSocket);
+            // Same socket, same id — the server freed the id when it terminated the op.
+            // If the socket is down/pre-ack instead, the ack flush re-sends it anyway.
+            if (this.wsConnected && this.ws && WebSocketCtor && this.ws.readyState === WebSocketCtor.OPEN) {
+                this.ws.send(JSON.stringify({
+                    id: String(id),
+                    type: "subscribe",
+                    payload: { query: sub.query, variables: sub.variables },
+                }));
+            }
+        }, delay);
+        this.opRetryTimers.set(id, timer);
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        // NB: ±20% reconnect jitter (anti-thundering-herd after a shared CF/Hasura blip) is
+        // deliberately NOT added here — it would need a seedable RNG to keep the fake-timer
+        // reconnect tests deterministic. The load-bearing fix is resetting the backoff on
+        // connection_ack (not socket OPEN), which caps the reconnect storm on its own.
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.reconnectDelay = Math.min(this.reconnectDelay * 2, 30000);
+            // Nothing to serve and nobody watching → stay closed; the next subscribe()
+            // re-opens the socket on demand.
+            if (this.subscriptions.size > 0 || this.connStateHandlers.size > 0)
+                this.ensureWs();
+        }, this.reconnectDelay);
+    }
+    /** Single exit path of a socket. Identity-guarded: superseded sockets are inert. */
+    handleSocketDown(ws, reconnect) {
+        if (this.ws !== ws)
+            return;
+        this.detachSocket(ws);
+        this.ws = null;
+        this.stopWatchdog();
+        this.clearAllOpRetries();
+        this.setWsConnected(false);
+        if (reconnect)
+            this.scheduleReconnect();
+    }
+    startWatchdog(ws) {
+        this.stopWatchdog();
+        this.lastInboundAt = Date.now();
+        this.watchdogTimer = setInterval(() => {
+            if (this.ws !== ws) {
+                this.stopWatchdog();
+                return;
+            }
+            if (Date.now() - this.lastInboundAt <= IndexerModule.WS_SILENCE_TIMEOUT_MS)
+                return;
+            // No inbound frames past the silence budget (Hasura pings every few seconds,
+            // and a CONNECTING socket that never opens lands here too): half-open/dead.
+            // The close event may never fire on its own — tear down and reconnect now.
+            this.handleSocketDown(ws, true);
+            try {
+                ws.close();
+            }
+            catch {
+                // Socket may be beyond closing — state is already torn down above.
+            }
+        }, IndexerModule.WS_WATCHDOG_INTERVAL_MS);
+    }
     ensureWs() {
         const WebSocketCtor = (this.transports.webSocketCtor ?? globalThis.WebSocket);
         if (!WebSocketCtor)
             throw new Error("WebSocket is not available; pass webSocketCtor in SDKConfig");
-        if (this.ws && this.ws.readyState === WebSocketCtor.OPEN)
+        // CONNECTING(0) or OPEN(1) — reuse the in-flight socket instead of racing a
+        // second one against it (readyState numeric order is WHATWG-fixed).
+        if (this.ws && this.ws.readyState <= WebSocketCtor.OPEN)
             return this.ws;
         if (!this.graphqlWsUrl)
             throw new Error("graphqlWsUrl required for subscriptions");
+        if (this.ws) {
+            // Superseding a CLOSING/CLOSED socket: detach its handlers so late events on
+            // it can't mutate the replacement's state machine (identity guards in the
+            // handlers are the backstop for already-queued events).
+            this.detachSocket(this.ws);
+            this.ws = null;
+        }
         const ws = new WebSocketCtor(this.graphqlWsUrl, "graphql-transport-ws");
         this.ws = ws;
+        // Not acked on the new socket by definition — subscribe() must defer its frame
+        // to the ack flush (guards the pre-ack window against a stale `true`). Emitted
+        // AFTER installing the replacement: a reentrant subscribe() from a conn-state
+        // listener then reuses this CONNECTING socket instead of racing a second one.
+        this.setWsConnected(false);
+        this.startWatchdog(ws);
         ws.onopen = () => {
-            this.reconnectDelay = 1000;
+            if (this.ws !== ws)
+                return;
+            // NB: backoff is reset on connection_ack, NOT here. Resetting on OPEN would pin an
+            // accept-then-drop endpoint (a redeploying/at-capacity Hasura that completes the WS
+            // upgrade but closes before acking) at a ~1s reconnect storm with no exponential relief.
             ws.send(JSON.stringify({ type: "connection_init" }));
         };
         ws.onmessage = (event) => {
-            const msg = JSON.parse(String(event.data));
+            if (this.ws !== ws)
+                return;
+            this.lastInboundAt = Date.now();
+            let msg;
+            try {
+                msg = JSON.parse(String(event.data));
+            }
+            catch {
+                // Non-JSON / binary / truncated frame (e.g. a proxy error page injected into the
+                // stream). Ignore rather than throw out of the handler, which would surface as an
+                // uncaught exception in a Node consumer and can terminate the process. The
+                // lastInboundAt bump above already keeps the watchdog honest.
+                return;
+            }
             if (msg.type === "connection_ack") {
+                // A usable graphql-transport-ws session now exists → reset the reconnect backoff
+                // here (not on socket OPEN), so an accept-then-drop endpoint keeps backing off.
+                this.reconnectDelay = 1000;
+                // Pending per-op retries would double-send on top of this flush (duplicate
+                // ids ⇒ server closes with 4409) — the flush IS the retry for all of them.
+                this.clearAllOpRetries();
                 for (const [id, sub] of this.subscriptions) {
                     ws.send(JSON.stringify({
                         id: String(id),
@@ -646,30 +849,67 @@ export class IndexerModule {
                         payload: { query: sub.query, variables: sub.variables },
                     }));
                 }
+                // Flip AFTER resubscribing: a conn-state listener reacting to `true` may
+                // rely on every pre-existing subscription already being live.
+                this.setWsConnected(true);
             }
-            if (msg.type === "next" && msg.id && msg.payload?.data) {
+            if (msg.type === "next" && msg.id) {
+                // Data flows ⇒ the op recovered: reset its retry backoff.
+                this.opRetryAttempts.delete(Number(msg.id));
+                const data = msg.payload?.data;
                 const sub = this.subscriptions.get(Number(msg.id));
-                if (sub)
-                    sub.cb(msg.payload.data);
+                if (sub && data)
+                    sub.cb(data);
+            }
+            // Server terminated ONE operation (`error`: invalid/rejected op, e.g. after a
+            // Hasura metadata redeploy; `complete`: out-of-band end of stream). The socket
+            // stays up, so connection-state fallbacks won't fire — surface it. The entry
+            // is kept and retried: with backoff on this same socket (scheduleOpRetry) and
+            // by the resubscribe flush on the next reconnect.
+            if ((msg.type === "error" || msg.type === "complete") && msg.id) {
+                const sub = this.subscriptions.get(Number(msg.id));
+                if (sub) {
+                    const info = {
+                        query: sub.query,
+                        variables: sub.variables,
+                        errors: msg.type === "error" ? msg.payload : undefined,
+                    };
+                    for (const cb of this.subErrorHandlers) {
+                        try {
+                            cb(info);
+                        }
+                        catch {
+                            // Listener errors are the listener's problem.
+                        }
+                    }
+                    this.scheduleOpRetry(Number(msg.id));
+                }
+            }
+            // graphql-transport-ws keepalive: Hasura pings at the protocol level (JSON
+            // frames, not WS opcodes) and the spec requires a pong, else the server may
+            // drop the socket as unresponsive.
+            if (msg.type === "ping") {
+                ws.send(JSON.stringify({ type: "pong" }));
             }
         };
-        ws.onclose = () => {
-            this.reconnectTimer = setTimeout(() => {
-                this.reconnectDelay = Math.min(this.reconnectDelay * 2, 30000);
-                this.ensureWs();
-            }, this.reconnectDelay);
-        };
+        ws.onclose = () => this.handleSocketDown(ws, true);
         ws.onerror = () => {
+            // close() routes through onclose → handleSocketDown; on a superseded socket
+            // the handlers are detached, so this is inert.
             ws.close();
         };
         return ws;
     }
     subscribe(query, variables, cb) {
         const id = ++this.wsId;
-        this.subscriptions.set(id, { query, variables, cb: cb });
+        // ensureWs BEFORE registering: in no-WS environments it throws, and a phantom
+        // map entry with no returned unsubscriber would leak on every attempt.
         const ws = this.ensureWs();
+        this.subscriptions.set(id, { query, variables, cb: cb });
         const WebSocketCtor = (this.transports.webSocketCtor ?? globalThis.WebSocket);
-        if (WebSocketCtor && ws.readyState === WebSocketCtor.OPEN) {
+        // Send only after connection_ack (graphql-transport-ws forbids earlier);
+        // pre-ack subscriptions are flushed by the ack handler above.
+        if (this.wsConnected && WebSocketCtor && ws.readyState === WebSocketCtor.OPEN) {
             ws.send(JSON.stringify({
                 id: String(id),
                 type: "subscribe",
@@ -678,6 +918,7 @@ export class IndexerModule {
         }
         return () => {
             this.subscriptions.delete(id);
+            this.clearOpRetry(id);
             const WebSocketCtor = (this.transports.webSocketCtor ?? globalThis.WebSocket);
             if (this.ws && WebSocketCtor && this.ws.readyState === WebSocketCtor.OPEN) {
                 this.ws.send(JSON.stringify({ id: String(id), type: "complete" }));
@@ -700,25 +941,96 @@ export class IndexerModule {
     subscribeAllowedPerps(cb) {
         return this.subscribe(`subscription { AllowedPerp(where: { allowed: { _eq: true } }) { id vaultAddress perpIndex allowed } }`, undefined, (data) => cb(data.AllowedPerp));
     }
+    /** True once the socket is open AND Hasura acked connection_init (subscriptions are live). */
+    isWsConnected() {
+        return this.wsConnected;
+    }
+    /**
+     * Watch the subscription-socket state. Fires immediately with the current state on
+     * register, then on every transition (connection_ack → true, close → false).
+     * Reconnect + resubscribe is automatic; consumers typically fall back to HTTP
+     * polling while `connected === false` and rely on the first post-reconnect
+     * emission of each live query (a full snapshot) to self-heal.
+     */
+    onConnectionStateChange(cb) {
+        this.connStateHandlers.add(cb);
+        try {
+            cb(this.wsConnected);
+        }
+        catch {
+            // Symmetric with setWsConnected: listener errors are the listener's problem.
+        }
+        return () => {
+            this.connStateHandlers.delete(cb);
+        };
+    }
+    /**
+     * Watch for server-terminated subscription operations (graphql-transport-ws
+     * `error` frames or out-of-band `complete`). The socket usually STAYS connected
+     * in this case, so poll fallbacks keyed on `onConnectionStateChange` alone never
+     * fire — consumers should degrade the affected dataset to polling when this
+     * fires. The subscription entry is kept and retried on the next reconnect ack.
+     */
+    onSubscriptionError(cb) {
+        this.subErrorHandlers.add(cb);
+        return () => {
+            this.subErrorHandlers.delete(cb);
+        };
+    }
     subscribeChallenge(address, cb) {
-        return this.subscribe(`subscription($id: String!) { Challenge(where: { id: { _ilike: $id } }) { ${IndexerModule.CHALLENGE_FIELDS} } }`, { id: address }, (data) => { if (data.Challenge[0])
+        return this.subscribe(`subscription($id: String!) { Challenge(where: { id: { _eq: $id } }) { ${IndexerModule.CHALLENGE_FIELDS} } }`, { id: address.toLowerCase() }, (data) => { if (data.Challenge[0])
             cb(data.Challenge[0]); });
     }
+    /**
+     * Live query over a challenge's positions: Hasura pushes the FULL current list on
+     * every relevant indexed block — replace state, don't merge. Filter/select set
+     * mirror `getChallengePositions`, so rows are shape-identical to the poll path.
+     */
+    subscribeChallengePositions(challenge, cb, opts) {
+        const openFilter = opts?.openOnly ? ` status: { _eq: Open }` : "";
+        return this.subscribe(`subscription($challenge: String!) { ChallengePosition(where: { challenge_id: { _eq: $challenge }${openFilter} }, order_by: [{ openedAt: desc }, { positionId: desc }], limit: 100) { ${IndexerModule.CHALLENGE_POSITION_FIELDS} } }`, { challenge: challenge.toLowerCase() }, (data) => cb(data.ChallengePosition));
+    }
+    /**
+     * Newest trades of a challenge (live query pushing the full `limit` window, newest
+     * first — mirrors `getChallengeTrades`). ChallengeTrade is append-only, so a Hasura
+     * streaming subscription (`ChallengeTrade_stream`, cursor on timestamp) pushing only
+     * deltas is the designated upgrade path once needed (see arch.md).
+     */
+    subscribeChallengeTrades(challenge, cb, opts) {
+        return this.subscribe(`subscription($challenge: String!, $limit: Int!) { ChallengeTrade(where: { challenge_id: { _eq: $challenge } }, order_by: [{ timestamp: desc }, { id: desc }], limit: $limit) { ${IndexerModule.CHALLENGE_TRADE_FIELDS} } }`, { challenge: challenge.toLowerCase(), limit: opts?.limit ?? 100 }, (data) => cb(data.ChallengeTrade));
+    }
+    /** Live list of a trader's challenges (newest first) — push variant of `getChallengesByTrader`. */
+    subscribeChallengesByTrader(trader, cb) {
+        return this.subscribe(`subscription($trader: String!) { Challenge(where: { trader_id: { _eq: $trader } }, order_by: [{ createdAt: desc }, { id: desc }], limit: 100) { ${IndexerModule.CHALLENGE_FIELDS} } }`, { trader: trader.toLowerCase() }, (data) => cb(data.Challenge));
+    }
     /** Live view of a builder's unpaid FIFO payout queue. */
     subscribePayoutQueue(builder, cb) {
-        return this.subscribe(`subscription($builder: String!) { ChallengePayoutQueueEntry(where: { builder_id: { _ilike: $builder } fullyPaid: { _eq: false } }, order_by: { queueId: asc }) { ${IndexerModule.CHALLENGE_QUEUE_ENTRY_FIELDS} } }`, { builder }, (data) => cb(data.ChallengePayoutQueueEntry));
+        return this.subscribe(`subscription($builder: String!) { ChallengePayoutQueueEntry(where: { builder_id: { _eq: $builder } fullyPaid: { _eq: false } }, order_by: { queueId: asc }) { ${IndexerModule.CHALLENGE_QUEUE_ENTRY_FIELDS} } }`, { builder: builder.toLowerCase() }, (data) => cb(data.ChallengePayoutQueueEntry));
     }
     disconnect() {
         if (this.reconnectTimer) {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
+        this.stopWatchdog();
+        this.clearAllOpRetries();
         this.subscriptions.clear();
         if (this.ws) {
-            this.ws.onclose = null;
-            this.ws.close();
+            const ws = this.ws;
+            // Full detach (not just onclose): no event on this socket may reach the
+            // state machine after disconnect.
+            this.detachSocket(ws);
             this.ws = null;
+            try {
+                ws.close();
+            }
+            catch {
+                // Already dead — nothing to close.
+            }
         }
+        // Handlers are detached — notify conn-state listeners explicitly. They stay
+        // registered: a later subscribe() re-opens the socket and they keep working.
+        this.setWsConnected(false);
     }
 }
 //# sourceMappingURL=indexer.js.map