inscription atlas: tests for first-image resolver, route dispatch, quadtree

53 new tests across three files:

- ordpool-quadtree-allocator.spec.ts (frontend, 18 tests): bud/insert/remove
  paths, full-flag propagation, parent collapse on free, packSlot encoding
  with shader-mirrored decode round-trip, packing-pressure stress that fills
  the atlas with 1024 minimum-size slots and asserts no rectangle overlap.

- ordpool-inscriptions.api.test.ts (+15 tests): the `$getFirstImageInscription`
  resolver. Covers single-image txs, batch reveals where the image sits at
  index 1 or 2 behind JSON/text, multi-image first-wins, every common image
  MIME variant we serve, all rejection cases (non-image content types,
  delegate stubs with no contentType, empty inscription list, 404 from RPC,
  non-404 rethrow), mempool short-circuit, delegate handoff, recursion cap,
  and the skipConversion=false call-shape regression guard.

- ordpool.routes.content-dispatch.test.ts (frontend-driven, 17 tests): the
  isBareTxid regex (10 cases including uppercase/lowercase/mixed hex,
  multi-digit indices, off-by-one lengths, non-hex), and the route
  handler's dispatch (bare txid -> first-image, txid+iN -> existing
  resolver, both 400/404/500 paths).

Author: hans-crypto

backend/src/api/explorer/_ordpool/ordpool-inscriptions.api.test.ts

@@ -1,3 +1,5 @@
+import { InscriptionParserService } from 'ordpool-parser';
+
 import bitcoinApi from '../../bitcoin/bitcoin-api-factory';
 import memPool from '../../mempool';
 import ordpoolInscriptionsApi from './ordpool-inscriptions.api';
@@ -15,9 +17,18 @@ jest.mock('../../mempool', () => ({
   __esModule: true,
   default: { getMempool: jest.fn() },
 }));
-// ordpool-parser is left unmocked: isValidInscriptionId is pure regex
-// validation, and InscriptionParserService.parse on a fake tx with no
-// witness data returns [] without side effects.
+// Synthetic ParsedInscription shape — only the fields the API code under
+// test reads. Tests for $getFirstImageInscription install
+// jest.spyOn(InscriptionParserService, 'parse') and hand-craft these.
+function fakeInscription(overrides: { contentType?: string; delegates?: string[] } = {}): any {
+  return {
+    contentType: overrides.contentType,
+    getDelegates: () => overrides.delegates || [],
+    contentSize: 0,
+    getContentEncoding: () => undefined,
+    getDataRaw: () => new Uint8Array(),
+  };
+}
 
 // Real mainnet txid (image/png inscription); used here for shape only,
 // the parser sees a stub transaction we hand it via the mocked bitcoinApi.
@@ -86,3 +97,182 @@ describe('OrdpoolInscriptionsApi.$getInscriptionById call shape', () => {
     ).rejects.toThrow('connection refused');
   });
 });
+
+describe('OrdpoolInscriptionsApi.$getFirstImageInscription', () => {
+
+  let parseSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    parseSpy = jest.spyOn(InscriptionParserService, 'parse');
+    (memPool.getMempool as jest.Mock).mockReturnValue({});
+    (bitcoinApi.$getRawTransaction as jest.Mock).mockResolvedValue({
+      txid: VALID_TXID,
+      vin: [{ witness: [], scriptsig: '' }],
+      vout: [{ scriptpubkey: '', value: 0 }],
+    });
+  });
+
+  afterEach(() => {
+    parseSpy.mockRestore();
+  });
+
+  it('returns the only inscription when the tx has a single image', async () => {
+    const image = fakeInscription({ contentType: 'image/png' });
+    parseSpy.mockReturnValue([image]);
+
+    const result = await ordpoolInscriptionsApi.$getFirstImageInscription(VALID_TXID);
+
+    expect(result).toBe(image);
+  });
+
+  it('skips a JSON inscription at index 0 and returns the image at index 1', async () => {
+    // Batch reveal: the parser sets ordpool_inscription_image because index 1
+    // is image/png, but a flat /content/<txid>i0 lookup hits the JSON. The
+    // first-image resolver is the fix.
+    const json = fakeInscription({ contentType: 'application/json' });
+    const image = fakeInscription({ contentType: 'image/webp' });
+    parseSpy.mockReturnValue([json, image]);
+
+    const result = await ordpoolInscriptionsApi.$getFirstImageInscription(VALID_TXID);
+
+    expect(result).toBe(image);
+  });
+
+  it('skips text and JSON to return the image at index 2', async () => {
+    const text = fakeInscription({ contentType: 'text/plain' });
+    const json = fakeInscription({ contentType: 'application/json' });
+    const image = fakeInscription({ contentType: 'image/gif' });
+    parseSpy.mockReturnValue([text, json, image]);
+
+    const result = await ordpoolInscriptionsApi.$getFirstImageInscription(VALID_TXID);
+
+    expect(result).toBe(image);
+  });
+
+  it('returns the FIRST image when multiple images are present', async () => {
+    const a = fakeInscription({ contentType: 'image/jpeg' });
+    const b = fakeInscription({ contentType: 'image/png' });
+    parseSpy.mockReturnValue([a, b]);
+
+    const result = await ordpoolInscriptionsApi.$getFirstImageInscription(VALID_TXID);
+
+    expect(result).toBe(a);
+  });
+
+  it('matches every common image MIME variant we serve', async () => {
+    for (const contentType of ['image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/svg+xml', 'image/avif']) {
+      const ins = fakeInscription({ contentType });
+      parseSpy.mockReturnValue([ins]);
+      const result = await ordpoolInscriptionsApi.$getFirstImageInscription(VALID_TXID);
+      expect(result).toBe(ins);
+    }
+  });
+
+  it('does NOT match non-image content types', async () => {
+    for (const contentType of ['application/json', 'text/plain', 'text/html', 'application/octet-stream', 'video/mp4', 'audio/mpeg']) {
+      const ins = fakeInscription({ contentType });
+      parseSpy.mockReturnValue([ins]);
+      const result = await ordpoolInscriptionsApi.$getFirstImageInscription(VALID_TXID);
+      expect(result).toBeUndefined();
+    }
+  });
+
+  it('treats inscriptions with no contentType (delegate stubs) as non-image', async () => {
+    const stub = fakeInscription({ contentType: undefined });
+    parseSpy.mockReturnValue([stub]);
+
+    const result = await ordpoolInscriptionsApi.$getFirstImageInscription(VALID_TXID);
+
+    expect(result).toBeUndefined();
+  });
+
+  it('returns undefined when the tx contains no inscriptions at all', async () => {
+    parseSpy.mockReturnValue([]);
+
+    const result = await ordpoolInscriptionsApi.$getFirstImageInscription(VALID_TXID);
+
+    expect(result).toBeUndefined();
+  });
+
+  it('returns undefined when the tx is not on chain (bitcoin API 404)', async () => {
+    (bitcoinApi.$getRawTransaction as jest.Mock).mockRejectedValue(
+      Object.assign(new Error('not found'), { response: { status: 404 } }),
+    );
+
+    const result = await ordpoolInscriptionsApi.$getFirstImageInscription(VALID_TXID);
+
+    expect(result).toBeUndefined();
+  });
+
+  it('rethrows non-404 errors from the bitcoin API', async () => {
+    (bitcoinApi.$getRawTransaction as jest.Mock).mockRejectedValue(new Error('connection refused'));
+
+    await expect(
+      ordpoolInscriptionsApi.$getFirstImageInscription(VALID_TXID),
+    ).rejects.toThrow('connection refused');
+  });
+
+  it('uses the mempool entry when present and skips the bitcoin API', async () => {
+    const mempoolTx = { txid: VALID_TXID, vin: [{ witness: [], scriptsig: '' }], vout: [] };
+    (memPool.getMempool as jest.Mock).mockReturnValue({ [VALID_TXID]: mempoolTx });
+    const image = fakeInscription({ contentType: 'image/png' });
+    parseSpy.mockReturnValue([image]);
+
+    const result = await ordpoolInscriptionsApi.$getFirstImageInscription(VALID_TXID);
+
+    expect(bitcoinApi.$getRawTransaction).not.toHaveBeenCalled();
+    expect(parseSpy).toHaveBeenCalledWith(mempoolTx);
+    expect(result).toBe(image);
+  });
+
+  it('resolves a delegate when the first image points at one', async () => {
+    // The image we find has a delegate; the resolver should chase it via the
+    // existing $getInscriptionOrDelegeate path and return the delegate's
+    // inscription. We mock that downstream call directly to keep the test
+    // focused on the delegate-handoff edge.
+    const imageWithDelegate = fakeInscription({
+      contentType: 'image/png',
+      delegates: ['aaaa1111aaaa1111aaaa1111aaaa1111aaaa1111aaaa1111aaaa1111aaaa1111i0'],
+    });
+    parseSpy.mockReturnValue([imageWithDelegate]);
+
+    const delegated = fakeInscription({ contentType: 'image/svg+xml' });
+    const delegateSpy = jest
+      .spyOn(ordpoolInscriptionsApi, '$getInscriptionOrDelegeate')
+      .mockResolvedValue(delegated as any);
+
+    const result = await ordpoolInscriptionsApi.$getFirstImageInscription(VALID_TXID);
+
+    expect(delegateSpy).toHaveBeenCalledWith(
+      'aaaa1111aaaa1111aaaa1111aaaa1111aaaa1111aaaa1111aaaa1111aaaa1111i0',
+      1, // recursive level incremented
+    );
+    expect(result).toBe(delegated);
+    delegateSpy.mockRestore();
+  });
+
+  it('throws after 4 levels of delegate recursion', async () => {
+    const looping = fakeInscription({
+      contentType: 'image/png',
+      delegates: ['bbbb2222bbbb2222bbbb2222bbbb2222bbbb2222bbbb2222bbbb2222bbbb2222i0'],
+    });
+    parseSpy.mockReturnValue([looping]);
+
+    await expect(
+      ordpoolInscriptionsApi.$getFirstImageInscription(VALID_TXID, 5),
+    ).rejects.toThrow('Too many delegate levels');
+  });
+
+  it('passes skipConversion=false to the bitcoin API (Esplora-shape conversion regression guard)', async () => {
+    const image = fakeInscription({ contentType: 'image/png' });
+    parseSpy.mockReturnValue([image]);
+
+    await ordpoolInscriptionsApi.$getFirstImageInscription(VALID_TXID);
+
+    expect(bitcoinApi.$getRawTransaction).toHaveBeenCalledTimes(1);
+    const args = (bitcoinApi.$getRawTransaction as jest.Mock).mock.calls[0];
+    expect(args[0]).toBe(VALID_TXID);
+    expect(args[1]).toBe(false); // skipConversion MUST be false
+  });
+});

backend/src/api/explorer/_ordpool/ordpool.routes.content-dispatch.test.ts

@@ -0,0 +1,149 @@
+import { Request, Response } from 'express';
+
+import generalOrdpoolRoutes, { isBareTxid } from './ordpool.routes';
+import ordpoolInscriptionsApi from './ordpool-inscriptions.api';
+import { InscriptionPreviewService } from 'ordpool-parser';
+
+// Same factory-mock pattern as ordpool.routes.test.ts: short-circuit the
+// module-load chain so the suite boots without a real config file.
+jest.mock('../../blocks', () => ({ __esModule: true, default: { getCurrentBlockHeight: jest.fn() } }));
+jest.mock('../../ordpool-missing-stats', () => ({ __esModule: true, default: { getLastSuccessAt: jest.fn(), getBlocksPerMinute: jest.fn() } }));
+jest.mock('../../../repositories/OrdpoolBlocksRepository', () => ({ __esModule: true, default: {} }));
+jest.mock('../../../repositories/OrdpoolSkippedBlocksRepository', () => ({ __esModule: true, default: {} }));
+jest.mock('./ordpool-inscriptions.api', () => ({
+  __esModule: true,
+  default: {
+    $getInscriptionOrDelegeate: jest.fn(),
+    $getFirstImageInscription: jest.fn(),
+  },
+}));
+jest.mock('./ordpool-statistics.api', () => ({ __esModule: true, default: {} }));
+jest.mock('../../../config', () => ({
+  __esModule: true,
+  default: { MEMPOOL: { NETWORK: 'mainnet', API_URL_PREFIX: '/api/v1/' } },
+}));
+
+const TXID = '6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799';
+
+function makeRes() {
+  const res: Partial<Response> = {};
+  res.setHeader = jest.fn();
+  res.status = jest.fn().mockImplementation(() => res);
+  res.json = jest.fn().mockImplementation(() => res);
+  res.send = jest.fn().mockImplementation(() => res);
+  return res as Response & { status: jest.Mock; send: jest.Mock; setHeader: jest.Mock };
+}
+
+function fakeInscription(): any {
+  return {
+    contentType: 'image/png',
+    contentSize: 0,
+    getContentEncoding: () => undefined,
+    getDataRaw: () => new Uint8Array(),
+    getDelegates: () => [],
+  };
+}
+
+describe('isBareTxid', () => {
+  it.each([
+    ['64 lowercase hex chars', '6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799', true],
+    ['64 uppercase hex chars', 'A'.repeat(64), true],
+    ['64 mixed-case hex chars', 'aBcDeF12'.repeat(8), true],
+    ['txid with i0 suffix', '6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0', false],
+    ['txid with i37 suffix', '6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i37', false],
+    ['63 hex chars (one short)', 'a'.repeat(63), false],
+    ['65 hex chars (one too many)', 'a'.repeat(65), false],
+    ['64 chars with one non-hex letter', 'g' + 'a'.repeat(63), false],
+    ['empty string', '', false],
+    ['just an integer index', '0', false],
+  ])('%s -> %s', (_label, value, expected) => {
+    expect(isBareTxid(value)).toBe(expected);
+  });
+});
+
+describe('getInscriptionContent route handler dispatch', () => {
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    // The fragment shader / atlas test plan: bare txid path must reach
+    // $getFirstImageInscription, full inscription-id path must reach the
+    // existing $getInscriptionOrDelegeate. Each test verifies one branch.
+  });
+
+  it('routes a bare txid to $getFirstImageInscription', async () => {
+    (ordpoolInscriptionsApi.$getFirstImageInscription as jest.Mock).mockResolvedValue(fakeInscription());
+    const req = { params: { inscriptionId: TXID } } as unknown as Request;
+    const res = makeRes();
+
+    await (generalOrdpoolRoutes as any).getInscriptionContent(req, res);
+
+    expect(ordpoolInscriptionsApi.$getFirstImageInscription).toHaveBeenCalledWith(TXID);
+    expect(ordpoolInscriptionsApi.$getInscriptionOrDelegeate).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(200);
+  });
+
+  it('routes a txid+iN to $getInscriptionOrDelegeate', async () => {
+    (ordpoolInscriptionsApi.$getInscriptionOrDelegeate as jest.Mock).mockResolvedValue(fakeInscription());
+    const req = { params: { inscriptionId: `${TXID}i0` } } as unknown as Request;
+    const res = makeRes();
+
+    await (generalOrdpoolRoutes as any).getInscriptionContent(req, res);
+
+    expect(ordpoolInscriptionsApi.$getInscriptionOrDelegeate).toHaveBeenCalledWith(`${TXID}i0`);
+    expect(ordpoolInscriptionsApi.$getFirstImageInscription).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(200);
+  });
+
+  it('routes txid+i37 to $getInscriptionOrDelegeate (multi-digit indices stay on the inscription path)', async () => {
+    (ordpoolInscriptionsApi.$getInscriptionOrDelegeate as jest.Mock).mockResolvedValue(fakeInscription());
+    const req = { params: { inscriptionId: `${TXID}i37` } } as unknown as Request;
+    const res = makeRes();
+
+    await (generalOrdpoolRoutes as any).getInscriptionContent(req, res);
+
+    expect(ordpoolInscriptionsApi.$getInscriptionOrDelegeate).toHaveBeenCalledWith(`${TXID}i37`);
+    expect(ordpoolInscriptionsApi.$getFirstImageInscription).not.toHaveBeenCalled();
+  });
+
+  it('returns 404 when first-image lookup yields nothing', async () => {
+    (ordpoolInscriptionsApi.$getFirstImageInscription as jest.Mock).mockResolvedValue(undefined);
+    const req = { params: { inscriptionId: TXID } } as unknown as Request;
+    const res = makeRes();
+
+    await (generalOrdpoolRoutes as any).getInscriptionContent(req, res);
+
+    expect(res.status).toHaveBeenCalledWith(404);
+    expect(res.send).toHaveBeenCalledWith('Transaction or inscription not found.');
+  });
+
+  it('returns 404 when inscription-id lookup yields nothing', async () => {
+    (ordpoolInscriptionsApi.$getInscriptionOrDelegeate as jest.Mock).mockResolvedValue(undefined);
+    const req = { params: { inscriptionId: `${TXID}i0` } } as unknown as Request;
+    const res = makeRes();
+
+    await (generalOrdpoolRoutes as any).getInscriptionContent(req, res);
+
+    expect(res.status).toHaveBeenCalledWith(404);
+  });
+
+  it('returns 400 when no id is supplied at all', async () => {
+    const req = { params: {} } as unknown as Request;
+    const res = makeRes();
+
+    await (generalOrdpoolRoutes as any).getInscriptionContent(req, res);
+
+    expect(res.status).toHaveBeenCalledWith(400);
+    expect(ordpoolInscriptionsApi.$getFirstImageInscription).not.toHaveBeenCalled();
+    expect(ordpoolInscriptionsApi.$getInscriptionOrDelegeate).not.toHaveBeenCalled();
+  });
+
+  it('returns 500 when the resolver throws', async () => {
+    (ordpoolInscriptionsApi.$getFirstImageInscription as jest.Mock).mockRejectedValue(new Error('boom'));
+    const req = { params: { inscriptionId: TXID } } as unknown as Request;
+    const res = makeRes();
+
+    await (generalOrdpoolRoutes as any).getInscriptionContent(req, res);
+
+    expect(res.status).toHaveBeenCalledWith(500);
+  });
+});

backend/src/api/explorer/_ordpool/ordpool.routes.ts

@@ -190,7 +190,10 @@ class GeneralOrdpoolRoutes {
 }
 
 
-function isBareTxid(value: string): boolean {
+// Exported for testing. Bare txid = 64 hex chars with no `iN` suffix.
+// The /content/ route uses this to decide whether to look up a specific
+// inscription index or pick the first image-bearing one in the tx.
+export function isBareTxid(value: string): boolean {
   return /^[0-9a-fA-F]{64}$/.test(value);
 }