ots: inject isOtsCommit on esplora-mode /api/tx/:txid via proxy

In production (BACKEND=esplora), bitcoin.routes.ts gates off
getTransaction, so /api/tx/<txid> is served by the electrs proxy and
attachIsOtsCommit never runs. Frontend's lazy probe in OtsKnowledgeService
rescues UX, but the wire-strip-fill was dead code on prod.

Buffer the small (~1-3 KB) tx-detail JSON inside the proxy, mutate via
attachIsOtsCommit, re-emit with corrected content-length. Other paths
(/tx/:txid/hex, /tx/:txid/status, non-200s, non-JSON bodies, POST,
/api/v1/*) stream through untouched. 6 new regression tests pin the
behaviour.

Also tighten Cache-Control on /resources/config.js + customize.js via a
Cloudflare Pages _headers file -- max-age=0, must-revalidate -- so the
window.__env GIT_COMMIT_HASH refreshes on revalidation instead of
lingering for 4 hours.

Updates ORDPOOL-FLAGS-ARCHITECTURE.md \xc2\xa74 to reflect the actual
strip-fill site on prod.

Author: hans-crypto

ORDPOOL-FLAGS-ARCHITECTURE.md

@@ -456,13 +456,31 @@ Tristate semantics:
 
 Where the field is populated on the wire:
 
-- **REST `GET /api/v1/tx/:txId`** — `bitcoin.routes.ts:getTransaction`
-  calls `ordpoolOtsTxidSet.has(req.params.txId)` after
-  `$getTransactionExtended` and writes the result to `transaction.isOtsCommit`.
-  O(1) Set.has() lookup, no DB round-trip.
-- **WebSocket track-tx** — `websocket-handler.ts:217` and `:227`
-  (both bitcoind and esplora backends) write `fullTx.isOtsCommit =
-  ordpoolOtsTxidSet.has(...)` before `JSON.stringify`.
+- **REST `GET /api/tx/:txId` (esplora-mode prod, the live shape)** —
+  `electrs-proxy-middleware.ts` matches `GET /tx/<64-hex>`, buffers the
+  electrs JSON response, calls `attachIsOtsCommit(tx)`, and re-emits with
+  a corrected `content-length`. Other paths (`/tx/:txid/hex`,
+  `/tx/:txid/status`, non-200s, non-JSON bodies, POST, `/api/v1/*`) stream
+  through untouched. Pinned by `__tests__/electrs-proxy-middleware.test.ts`.
+- **REST `GET /api/v1/tx/:txId` (bitcoind-mode dev only)** —
+  `bitcoin.routes.ts:getTransaction` calls `attachIsOtsCommit(transaction)`
+  inside the `if (config.MEMPOOL.BACKEND !== 'esplora')` block. Inactive
+  on prod, where the route itself is unregistered and the electrs proxy
+  serves the response instead.
+- **WebSocket track-tx** — `websocket-handler.ts:234-253` writes
+  `attachIsOtsCommit(tx)` in all three branches (mempool-pool hit on
+  esplora, full-tx fetch on bitcoind, full-tx fetch on miss). Not gated
+  against esplora — runs on prod.
+- **WebSocket track-txs (plural initial-subscribe)** —
+  `websocket-handler.ts:310` calls `setIsOtsCommitByTxid(txid, txInfo)`
+  per requested txid (the `TxTrackingInfo` shape has no `txid` field, so
+  we attach by argument). Also unguarded by backend mode.
+- **WebSocket `otsCommitFlipped` re-push** — when the OTS poller adds a
+  new txid to `ordpoolOtsTxidSet`, the subscribed broadcaster
+  (`broadcastOtsCommitFlippedToClients`) pushes `{otsCommitFlipped:
+  <txid>}` to every client tracking it. Frontend reacts in
+  `transaction.component.ts` / `tracker.component.ts` by re-running
+  `setFeatures()` / `checkAccelerationEligibility()`.
 
 Where it does **not** appear (still by design):
 
@@ -515,9 +533,12 @@ GET /api/v1/ordpool/ots/is-commit/<64-hex-txid>  ->  { result: boolean }
 
 - **Implementation**: validates txid with `isValidTxid()` (from
   ordpool-parser), then one `ordpoolOtsTxidSet.has(txid)` call.
-- **Cache header**: `Cache-Control: public, max-age=60` (the answer can
-  flip `false` → `true` as the poller catches up; never the reverse).
-  60 s matches the poller's cycle.
+- **Cache header**: `Cache-Control: public, max-age=60, stale-while-revalidate=60`.
+  The answer can flip `false` → `true` as the poller catches up (never
+  the reverse), so a 60 s fresh window matches the poller's cycle, and
+  SWR lets the edge serve the stale value while a fresh one is fetched
+  in the background. Live WS `otsCommitFlipped` re-push closes any
+  remaining lag for already-subscribed clients.
 - **Malformed txid**: HTTP 400 with body `invalid txid`. Pinned by the
   `$isOtsCommit route handler` describe block in
   `ordpool.routes.test.ts` (5 tests).

backend/.test-count-baseline.json

@@ -1,4 +1,4 @@
 {
-  "passing": 337,
+  "passing": 343,
   "note": "Floor for .github/workflows/test-count-floor-backend.yml. Count of passing tests from the single jest config (node). Only an ordpool core maintainer is authorised to lower this number; every other change that reduces test count is treated as an accident and rejected. To raise the floor after legitimately adding tests, bump this value and commit. See also workspace CLAUDE.md, HARD RULE 'Never delete a passing test without explicit permission'."
 }

backend/src/__tests__/electrs-proxy-middleware.test.ts

@@ -8,6 +8,23 @@ jest.mock('../logger', () => ({
   default: { warn: jest.fn(), info: jest.fn(), err: jest.fn(), debug: jest.fn() },
 }));
 
+// Mock the ordpool OTS flag module so we don't drag in the database / poller
+// chain. The mock keeps a controllable set of "known OTS txids" that tests
+// can mutate via `__setOtsTxids`. `attachIsOtsCommit` mirrors the real
+// behaviour: writes `isOtsCommit = set.has(tx.txid)` and returns the tx.
+const otsTxids = new Set<string>();
+jest.mock('../api/ordpool-ots-flag', () => ({
+  __esModule: true,
+  attachIsOtsCommit: jest.fn(<T extends { txid: string; isOtsCommit?: boolean | null }>(tx: T): T => {
+    tx.isOtsCommit = otsTxids.has(tx.txid);
+    return tx;
+  }),
+}));
+
+beforeEach(() => {
+  otsTxids.clear();
+});
+
 type FakeHandler = (req: http.IncomingMessage, res: http.ServerResponse) => void;
 
 function startServer(app: Express): Promise<{ server: http.Server, url: string }> {
@@ -90,6 +107,150 @@ describe('electrs-proxy-middleware', () => {
     }
   });
 
+  test('injects isOtsCommit=true on GET /tx/<txid> when the txid is in the OTS set', async () => {
+    const TXID = 'a'.repeat(64);
+    otsTxids.add(TXID);
+
+    const electrs = await startFakeElectrs((req, res) => {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ txid: TXID, fee: 76, status: { confirmed: true } }));
+    });
+
+    const app = express();
+    app.use('/api', createElectrsProxyMiddleware(electrs.url));
+
+    const { server, url } = await startServer(app);
+    try {
+      const r = await fetchText(`${url}/api/tx/${TXID}`);
+      expect(r.status).toBe(200);
+      const body = JSON.parse(r.body);
+      expect(body.isOtsCommit).toBe(true);
+      expect(body.txid).toBe(TXID);
+      expect(body.fee).toBe(76); // existing fields preserved
+      // content-length must reflect the re-serialized body, not the original.
+      expect(Number(r.headers['content-length'])).toBe(Buffer.byteLength(r.body));
+    } finally {
+      await close(server);
+      await close(electrs.server);
+    }
+  });
+
+  test('injects isOtsCommit=false on GET /tx/<txid> when the txid is NOT in the OTS set', async () => {
+    const TXID = 'b'.repeat(64);
+
+    const electrs = await startFakeElectrs((_req, res) => {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ txid: TXID }));
+    });
+
+    const app = express();
+    app.use('/api', createElectrsProxyMiddleware(electrs.url));
+
+    const { server, url } = await startServer(app);
+    try {
+      const r = await fetchText(`${url}/api/tx/${TXID}`);
+      expect(r.status).toBe(200);
+      expect(JSON.parse(r.body)).toEqual({ txid: TXID, isOtsCommit: false });
+    } finally {
+      await close(server);
+      await close(electrs.server);
+    }
+  });
+
+  test('does NOT touch GET /tx/<txid>/hex (different path, plain text body)', async () => {
+    const TXID = 'c'.repeat(64);
+    otsTxids.add(TXID);
+
+    const electrs = await startFakeElectrs((_req, res) => {
+      res.writeHead(200, { 'content-type': 'text/plain' });
+      res.end('0200000001abcdef'); // raw hex blob, not JSON
+    });
+
+    const app = express();
+    app.use('/api', createElectrsProxyMiddleware(electrs.url));
+
+    const { server, url } = await startServer(app);
+    try {
+      const r = await fetchText(`${url}/api/tx/${TXID}/hex`);
+      expect(r.status).toBe(200);
+      expect(r.body).toBe('0200000001abcdef');
+      expect(r.body).not.toContain('isOtsCommit');
+    } finally {
+      await close(server);
+      await close(electrs.server);
+    }
+  });
+
+  test('passes through non-200 GET /tx/<txid> unchanged (no JSON parse attempt)', async () => {
+    const TXID = 'd'.repeat(64);
+    otsTxids.add(TXID);
+
+    const electrs = await startFakeElectrs((_req, res) => {
+      res.writeHead(404, { 'content-type': 'text/plain' });
+      res.end('Transaction not found.');
+    });
+
+    const app = express();
+    app.use('/api', createElectrsProxyMiddleware(electrs.url));
+
+    const { server, url } = await startServer(app);
+    try {
+      const r = await fetchText(`${url}/api/tx/${TXID}`);
+      expect(r.status).toBe(404);
+      expect(r.body).toBe('Transaction not found.');
+    } finally {
+      await close(server);
+      await close(electrs.server);
+    }
+  });
+
+  test('falls back to passthrough when electrs body is not parseable JSON', async () => {
+    const TXID = 'e'.repeat(64);
+    otsTxids.add(TXID);
+
+    const electrs = await startFakeElectrs((_req, res) => {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end('{not json'); // malformed
+    });
+
+    const app = express();
+    app.use('/api', createElectrsProxyMiddleware(electrs.url));
+
+    const { server, url } = await startServer(app);
+    try {
+      const r = await fetchText(`${url}/api/tx/${TXID}`);
+      expect(r.status).toBe(200);
+      expect(r.body).toBe('{not json');
+    } finally {
+      await close(server);
+      await close(electrs.server);
+    }
+  });
+
+  test('does NOT touch POST /tx (only GET tx-detail is intercepted)', async () => {
+    let receivedMethod: string | undefined;
+    const electrs = await startFakeElectrs((req, res) => {
+      receivedMethod = req.method;
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ txid: 'broadcast-result-txid' }));
+    });
+
+    const app = express();
+    app.use('/api', createElectrsProxyMiddleware(electrs.url));
+
+    const { server, url } = await startServer(app);
+    try {
+      const r = await fetchText(`${url}/api/tx`, { method: 'POST' });
+      expect(r.status).toBe(200);
+      expect(receivedMethod).toBe('POST');
+      // POSTed broadcasts come back without `isOtsCommit` injection.
+      expect(JSON.parse(r.body)).toEqual({ txid: 'broadcast-result-txid' });
+    } finally {
+      await close(server);
+      await close(electrs.server);
+    }
+  });
+
   test('returns 502 when electrs is unreachable', async () => {
     const app = express();
     // 127.0.0.1:1 is reserved/closed — connection refused, immediate ECONNREFUSED.

backend/src/electrs-proxy-middleware.ts

@@ -1,6 +1,7 @@
 import { NextFunction, Request, RequestHandler, Response } from 'express';
 import * as http from 'http';
 import logger from './logger';
+import { attachIsOtsCommit } from './api/ordpool-ots-flag';
 
 // HACK --- Ordpool: cheap nginx replacement.
 // Mempool's upstream production runs nginx in front of backend + electrs to path-route
@@ -16,6 +17,16 @@ import logger from './logger';
 // overhead vs. nginx's ~50µs is invisible relative to electrs's 10-100ms response time.
 // If we ever scale to where the proxy itself becomes the bottleneck, this gets replaced
 // by nginx in front of cloudflared and these lines deleted.
+//
+// HACK -- Ordpool: when `MEMPOOL.BACKEND === 'esplora'` (prod), upstream's
+// `bitcoin.routes.ts:75-80` gates off `getTransaction`, so `/api/tx/<txid>`
+// is served by this proxy. We intercept GET /tx/<64-hex> here, buffer the
+// JSON body, and inject the tristate `isOtsCommit` field via
+// `attachIsOtsCommit` so the frontend's OtsKnowledgeService can skip the
+// lazy probe on the strip wire. Everything else streams through untouched.
+// See ORDPOOL-FLAGS-ARCHITECTURE.md §4.
+const TX_DETAIL_PATH = /^\/tx\/[0-9a-f]{64}$/i;
+
 export function createElectrsProxyMiddleware(electrsBaseUrl: string | undefined): RequestHandler {
   const electrsHost = new URL(electrsBaseUrl || 'http://127.0.0.1:3000');
   const port = electrsHost.port || '80';
@@ -25,15 +36,58 @@ export function createElectrsProxyMiddleware(electrsBaseUrl: string | undefined)
     if (req.path === '/v1' || req.path.startsWith('/v1/')) {
       return next();
     }
+    const injectOtsCommit = req.method === 'GET' && TX_DETAIL_PATH.test(req.path);
     const proxyReq = http.request({
       host: electrsHost.hostname,
       port: Number(port),
       path: req.url,
       method: req.method,
       headers: { ...req.headers, host: hostHeader },
     }, (electrsRes) => {
-      res.writeHead(electrsRes.statusCode || 502, electrsRes.headers);
-      electrsRes.pipe(res);
+      if (!injectOtsCommit) {
+        res.writeHead(electrsRes.statusCode || 502, electrsRes.headers);
+        electrsRes.pipe(res);
+        return;
+      }
+      // Buffer the small (~1-3 KB) tx-detail JSON so we can inject
+      // `isOtsCommit`. If anything looks off (non-200, content-encoding,
+      // unparseable body, missing txid), fall back to a clean passthrough
+      // so we never corrupt a response we don't understand.
+      const status = electrsRes.statusCode || 502;
+      const encoding = electrsRes.headers['content-encoding'];
+      if (status !== 200 || encoding) {
+        res.writeHead(status, electrsRes.headers);
+        electrsRes.pipe(res);
+        return;
+      }
+      const chunks: Buffer[] = [];
+      electrsRes.on('data', (c: Buffer) => chunks.push(c));
+      electrsRes.on('end', () => {
+        const body = Buffer.concat(chunks);
+        try {
+          const tx = JSON.parse(body.toString('utf8'));
+          if (!tx || typeof tx.txid !== 'string') {
+            res.writeHead(status, electrsRes.headers);
+            res.end(body);
+            return;
+          }
+          attachIsOtsCommit(tx);
+          const out = Buffer.from(JSON.stringify(tx));
+          const headers: http.OutgoingHttpHeaders = { ...electrsRes.headers };
+          headers['content-length'] = String(out.length);
+          delete headers['transfer-encoding'];
+          res.writeHead(status, headers);
+          res.end(out);
+        } catch {
+          res.writeHead(status, electrsRes.headers);
+          res.end(body);
+        }
+      });
+      electrsRes.on('error', () => {
+        if (!res.headersSent) {
+          res.status(502).send('electrs proxy stream error');
+        }
+      });
     });
     proxyReq.on('error', (err) => {
       logger.warn(`electrs proxy error for ${req.method} ${req.url}: ${err.message}`);

frontend/angular.json

@@ -173,6 +173,7 @@
               "src/customize.js",
               "src/config.template.js",
               "src/_redirects",
+              "src/_headers",
               {
                 "glob": "*.css",
                 "input": ".theme-build",
@@ -198,7 +199,8 @@
               "assets": [
                 "src/favicon.ico",
                 "src/robots.txt",
-                "src/_redirects"
+                "src/_redirects",
+                "src/_headers"
               ],
               "fileReplacements": [
                 {

frontend/src/_headers

@@ -0,0 +1,13 @@
+# Cloudflare Pages _headers — Cache-Control overrides for files that
+# change on every deploy but aren't fingerprinted in the URL. Wired into
+# the build via angular.json (assets) and shipped in dist/.
+#
+# Without this, Pages defaults to a multi-hour TTL on .js files, so
+# already-open tabs keep reading the previous build's window.__env
+# (GIT_COMMIT_HASH, BASE_MODULE, etc.) until their cache expires. ETag
+# revalidation closes the gap to one 304 round-trip per page load.
+/resources/config.js
+  Cache-Control: public, max-age=0, must-revalidate
+
+/resources/customize.js
+  Cache-Control: public, max-age=0, must-revalidate