tapimo 0.0.0 → 0.0.2

package/src/apps/blocks.test.ts

@@ -0,0 +1,385 @@
+import { Schema } from 'cadent'
+import { Hex } from 'ox'
+import { zeroHash } from 'viem'
+
+import * as TestApp from '../../test/App.js'
+import * as Runtime from '../../test/runtime.js'
+import * as Viem from '../../test/Viem.js'
+import * as Blocks from './blocks.js'
+import * as Transactions from './transactions.js'
+
+let recent: { number: bigint; hash: Hex.Hex } | undefined
+let recentNonEmpty: { number: bigint; hash: Hex.Hex } | undefined
+
+beforeAll(async () => {
+  const runtime = Runtime.get()
+  if (runtime.mode === 'localnet') {
+    const blockNumber = runtime.fixtures!.faucetBlockNumbers[0]
+    if (blockNumber !== undefined) {
+      recent = await blockByNumber(BigInt(blockNumber)).catch(() => undefined)
+      recentNonEmpty = recent
+    }
+    return
+  }
+
+  recent = await findRecentBlock().catch(() => undefined)
+  recentNonEmpty = await findRecentNonEmptyBlock().catch(() => undefined)
+})
+
+describe('GET /blocks/:block (latest tag)', () => {
+  test('humanizes the head block and keeps the raw RPC under `meta.rpc`', async () => {
+    const client = TestApp.client()
+    const response = await client.v1.blocks[':block'].$get(
+      { param: { block: 'latest' }, query: {} },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Blocks.schema.getBlock.Response)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('server-timing')?.includes('block;dur=')).toBe(true)
+    // The response is humanized: decimal-string amounts, plain numbers for
+    // block fields, and ISO-8601 timestamps.
+    expect(typeof body.number).toBe('number')
+    expect(body.number).toBeGreaterThan(0)
+    expect(body.hash).toMatch(/^0x[0-9a-f]{64}$/)
+    expect(body.parentHash).toMatch(/^0x[0-9a-f]{64}$/)
+    expect(body.miner).toMatch(/^0x[0-9a-f]{40}$/)
+    expect(typeof body.gasLimit).toBe('number')
+    expect(typeof body.gasUsed).toBe('number')
+    expect(typeof body.size).toBe('number')
+    expect(typeof body.timestamp).toBe('string')
+    expect(new Date(body.timestamp).getTime()).toBeGreaterThan(0)
+    expect(typeof body.transactionCount).toBe('number')
+    // The verbatim JSON-RPC block is always available under `meta.rpc`,
+    // where quantities stay hex-encoded.
+    expect(body.meta.rpc.number).toMatch(/^0x[0-9a-f]+$/)
+    expect(body.meta.rpc.gasUsed).toMatch(/^0x[0-9a-f]+$/)
+    expect(body.meta.rpc.timestamp).toMatch(/^0x[0-9a-f]+$/)
+  })
+})
+
+describe('GET /blocks/:block', () => {
+  test('resolves a decimal block number', async () => {
+    expect(recent).toBeDefined()
+    const client = TestApp.client()
+    const response = await client.v1.blocks[':block'].$get(
+      { param: { block: recent!.number.toString() }, query: {} },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Blocks.schema.getBlock.Response)
+    expect(response.status).toBe(200)
+    expect(body.number).toBe(Number(recent!.number))
+    expect(body.hash).toBe(recent!.hash)
+  })
+
+  test('resolves a 0x-prefixed hex block number', async () => {
+    expect(recent).toBeDefined()
+    const hex = `0x${recent!.number.toString(16)}`
+    const client = TestApp.client()
+    const response = await client.v1.blocks[':block'].$get(
+      { param: { block: hex }, query: {} },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Blocks.schema.getBlock.Response)
+    expect(response.status).toBe(200)
+    expect(body.number).toBe(Number(recent!.number))
+    expect(body.hash).toBe(recent!.hash)
+  })
+
+  test('resolves a 32-byte block hash', async () => {
+    expect(recent).toBeDefined()
+    const client = TestApp.client()
+    const response = await client.v1.blocks[':block'].$get(
+      { param: { block: recent!.hash }, query: {} },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Blocks.schema.getBlock.Response)
+    expect(response.status).toBe(200)
+    expect(body.number).toBe(Number(recent!.number))
+    expect(body.hash).toBe(recent!.hash)
+  })
+
+  test('returns 404 for an unknown block number', async () => {
+    // 2^60 is far beyond any plausible head; the node returns null.
+    const client = TestApp.client()
+    const response = await client.v1.blocks[':block'].$get(
+      { param: { block: '1152921504606846976' }, query: {} },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    expect(response.status).toBe(404)
+    expect(body.error.code).toBe('block_not_found')
+  })
+
+  test('returns 404 for an unknown block hash', async () => {
+    const client = TestApp.client()
+    const response = await client.v1.blocks[':block'].$get(
+      { param: { block: zeroHash }, query: {} },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    expect(response.status).toBe(404)
+    expect(body.error.code).toBe('block_not_found')
+  })
+
+  test('returns 400 for an invalid block identifier', async () => {
+    const client = TestApp.client()
+    const response = await client.v1.blocks[':block'].$get(
+      { param: { block: 'not-a-block' }, query: {} },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    expect(response.status).toBe(400)
+    expect(body.error.code).toBe('block_invalid')
+  })
+})
+
+describe('GET /blocks', () => {
+  test('returns a paginated, descending list of lightweight block rows', async () => {
+    const client = TestApp.client()
+    const response = await client.v1.blocks.$get({ query: { limit: '5' } }, TestApp.auth)
+    const body = await TestApp.json(response, Blocks.schema.getBlocks.Response)
+    expect(response.status).toBe(200)
+    expect(Array.isArray(body.data)).toBe(true)
+    expect(body.data.length).toBeGreaterThan(0)
+    expect(body.data.length).toBeLessThanOrEqual(5)
+    for (const row of body.data) {
+      expect(typeof row.number).toBe('number')
+      expect(typeof row.timestamp).toBe('string')
+      expect(typeof row.transactionCount).toBe('number')
+      // Empty blocks are included in the list and correctly report `0`.
+      expect(row.transactionCount).toBeGreaterThanOrEqual(0)
+    }
+    // Default ordering is descending by block number; rows are consecutive
+    // (no gaps, since every block — empty or not — appears).
+    for (let i = 1; i < body.data.length; i++) {
+      expect(body.data[i - 1]!.number).toBeGreaterThan(body.data[i]!.number)
+      expect(body.data[i - 1]!.number - body.data[i]!.number).toBe(1)
+    }
+  })
+
+  test('only sets a Cache-Control header for cursor pages', async () => {
+    const client = TestApp.client()
+    // Head page: a point-in-time read of the live tip, never cached and with
+    // no Cache-Control header at all.
+    const headResponse = await client.v1.blocks.$get({ query: { limit: '5' } }, TestApp.auth)
+    const head = await TestApp.json(headResponse, Blocks.schema.getBlocks.Response)
+    expect(headResponse.status).toBe(200)
+    expect(headResponse.headers.get('Cache-Control')).toBeNull()
+
+    // Cursor page: anchored below the head and effectively immutable.
+    const cursorResponse = await client.v1.blocks.$get(
+      { query: { limit: '5', cursor: head.nextCursor! } },
+      TestApp.auth,
+    )
+    expect(cursorResponse.status).toBe(200)
+    expect(cursorResponse.headers.get('Cache-Control')).toContain('max-age=86400')
+  })
+
+  test('round-trips an opaque cursor across pages', async () => {
+    const client = TestApp.client()
+    const firstResponse = await client.v1.blocks.$get({ query: { limit: '5' } }, TestApp.auth)
+    const first = await TestApp.json(firstResponse, Blocks.schema.getBlocks.Response)
+    expect(typeof first.nextCursor).toBe('string')
+
+    const secondResponse = await client.v1.blocks.$get(
+      { query: { limit: '5', cursor: first.nextCursor! } },
+      TestApp.auth,
+    )
+    const second = await TestApp.json(secondResponse, Blocks.schema.getBlocks.Response)
+    expect(second.data.length).toBeGreaterThan(0)
+    // The cursor anchors strictly below the last row of the previous page,
+    // so the first row of the next page must be older.
+    expect(second.data[0]!.number).toBeLessThan(first.data[first.data.length - 1]!.number)
+  })
+
+  test('serves a bounded positional page via `page`', async () => {
+    const client = TestApp.client()
+    // Ascending order anchors the feed at the first indexed block, so
+    // positional pages are deterministic: the offset page must equal the
+    // matching slice of the head page.
+    const headResponse = await client.v1.blocks.$get(
+      { query: { limit: '10', order: 'asc' } },
+      TestApp.auth,
+    )
+    const head = await TestApp.json(headResponse, Blocks.schema.getBlocks.Response)
+    expect(headResponse.status).toBe(200)
+    expect(head.data.length).toBe(10)
+
+    const offsetResponse = await client.v1.blocks.$get(
+      { query: { limit: '5', order: 'asc', page: '2' } },
+      TestApp.auth,
+    )
+    const page = await TestApp.json(offsetResponse, Blocks.schema.getBlocks.Response)
+    expect(offsetResponse.status).toBe(200)
+    expect(page.data.map((row) => row.number)).toEqual(
+      head.data.slice(5, 10).map((row) => row.number),
+    )
+    // Offset pages still return a keyset cursor, so a client can jump
+    // positionally and then continue deep traversal by cursor.
+    expect(typeof page.nextCursor).toBe('string')
+
+    const continuedResponse = await client.v1.blocks.$get(
+      { query: { cursor: page.nextCursor!, limit: '5', order: 'asc' } },
+      TestApp.auth,
+    )
+    const continued = await TestApp.json(continuedResponse, Blocks.schema.getBlocks.Response)
+    expect(continuedResponse.status).toBe(200)
+    expect(continued.data[0]!.number).toBe(page.data[page.data.length - 1]!.number + 1)
+  })
+})
+
+describe('GET /blocks/:block (ISO 8601 timestamp)', () => {
+  test('resolves an ISO 8601 timestamp to the first block at or after it', async () => {
+    expect(recent).toBeDefined()
+    const recentBlock = await Viem.getClient().getBlock({ blockNumber: recent!.number })
+    const seconds = Number(recentBlock.timestamp)
+    const iso = new Date(seconds * 1000).toISOString()
+    const client = TestApp.client()
+    const response = await client.v1.blocks[':block'].$get(
+      { param: { block: iso }, query: {} },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Blocks.schema.getBlock.Response)
+    expect(response.status).toBe(200)
+    expect(typeof body.number).toBe('number')
+    // The returned block's timestamp must be >= the requested timestamp.
+    expect(new Date(body.timestamp).getTime() / 1000).toBeGreaterThanOrEqual(seconds)
+  })
+
+  test('returns 404 for a far-future timestamp with no indexed block', async () => {
+    // Year 3000+ — there will not be an indexed block past this point.
+    const client = TestApp.client()
+    const response = await client.v1.blocks[':block'].$get(
+      { param: { block: '3000-01-01T00:00:00Z' }, query: {} },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    expect(response.status).toBe(404)
+    expect(body.error.code).toBe('block_not_found')
+  })
+})
+
+describe('GET /chains/:chainId/blocks/by-timestamp (legacy compatibility)', () => {
+  test('resolves the latest block at or before the timestamp (default)', async () => {
+    expect(recent).toBeDefined()
+    const recentBlock = await Viem.getClient().getBlock({ blockNumber: recent!.number })
+    const seconds = Number(recentBlock.timestamp)
+    const client = TestApp.client()
+    const response = await client.chains[':chainId'].blocks['by-timestamp'].$get(
+      { param: { chainId: String(Runtime.get().chainId) }, query: { timestamp: String(seconds) } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Blocks.schema.getBlockByTimestamp.Response)
+    expect(response.status).toBe(200)
+    expect(typeof body.block.blockNumber).toBe('number')
+    // `before` returns a block at or before the requested instant, within window.
+    expect(body.block.blockTimestamp).toBeLessThanOrEqual(seconds)
+    expect(body.block.blockTimestamp).toBeGreaterThanOrEqual(seconds - 60)
+  })
+
+  test('resolves the earliest block at or after the timestamp with closest=after', async () => {
+    expect(recent).toBeDefined()
+    const recentBlock = await Viem.getClient().getBlock({ blockNumber: recent!.number })
+    const seconds = Number(recentBlock.timestamp)
+    const client = TestApp.client()
+    const response = await client.chains[':chainId'].blocks['by-timestamp'].$get(
+      {
+        param: { chainId: String(Runtime.get().chainId) },
+        query: { timestamp: String(seconds), closest: 'after' },
+      },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Blocks.schema.getBlockByTimestamp.Response)
+    expect(response.status).toBe(200)
+    expect(body.block.blockTimestamp).toBeGreaterThanOrEqual(seconds)
+    expect(body.block.blockTimestamp).toBeLessThanOrEqual(seconds + 60)
+  })
+
+  test('returns 404 when no indexed block falls within the window', async () => {
+    // Year 3000+ — there will not be an indexed block past this point.
+    const client = TestApp.client()
+    const response = await client.chains[':chainId'].blocks['by-timestamp'].$get(
+      { param: { chainId: String(Runtime.get().chainId) }, query: { timestamp: '32503680000' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    expect(response.status).toBe(404)
+    expect(body.error.code).toBe('block_not_found')
+  })
+})
+
+describe('GET /transactions (single-block listing)', () => {
+  test('lists transactions in a block via equal `blockNumber.*` bounds', async () => {
+    expect(recentNonEmpty).toBeDefined()
+    const block = recentNonEmpty!.number.toString()
+    const client = TestApp.client()
+    const response = await client.v1.transactions.$get(
+      { query: { 'blockNumber.from': block, 'blockNumber.to': block, limit: '10' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Transactions.schema.getTransactions.Response)
+    expect(response.status).toBe(200)
+    expect(Array.isArray(body.data)).toBe(true)
+    expect(body.data.length).toBeGreaterThan(0)
+    // Every returned transaction belongs to the requested block.
+    for (const tx of body.data) expect(tx.blockNumber).toBe(Number(recentNonEmpty!.number))
+  })
+
+  test('a block hash composes via GET /blocks/:block, then the bounds', async () => {
+    expect(recentNonEmpty).toBeDefined()
+    const client = TestApp.client()
+    // Resolve the hash to a number through the blocks resource…
+    const blockResponse = await client.v1.blocks[':block'].$get(
+      { param: { block: recentNonEmpty!.hash }, query: {} },
+      TestApp.auth,
+    )
+    const block = await TestApp.json(blockResponse, Blocks.schema.getBlock.Response)
+    expect(blockResponse.status).toBe(200)
+    expect(block.number).toBe(Number(recentNonEmpty!.number))
+
+    // …then list its transactions with equal bounds.
+    const number = block.number.toString()
+    const response = await client.v1.transactions.$get(
+      { query: { 'blockNumber.from': number, 'blockNumber.to': number, limit: '10' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Transactions.schema.getTransactions.Response)
+    expect(response.status).toBe(200)
+    expect(body.data.length).toBeGreaterThan(0)
+    for (const tx of body.data) expect(tx.blockNumber).toBe(block.number)
+  })
+})
+
+// Walk back from the chain head to find a recent mined block with a stable
+// hash + number. The latest block could change between requests, so seed a
+// concrete identifier once for the dispatch tests. The Tempo RPC node serves
+// the test chain (`42431` → `rpc.testnet.tempo.xyz`).
+async function findRecentBlock() {
+  const client = Viem.getClient()
+  const latest = await client.getBlockNumber()
+  // Step a couple of blocks back from the head to avoid racing against a
+  // re-orged head.
+  const number = latest > 2n ? latest - 2n : latest
+  return await blockByNumber(number)
+}
+
+async function blockByNumber(number: bigint) {
+  const block = await Viem.getClient().getBlock({ blockNumber: number })
+  return { number, hash: block.hash }
+}
+
+// Walk backwards from a small offset below the head until we find a block
+// with at least one transaction. Stepping below the head gives the indexer
+// time to ingest the block before tidx-backed endpoints query it.
+async function findRecentNonEmptyBlock() {
+  const client = Viem.getClient()
+  const latest = await client.getBlockNumber()
+  let cursor = latest > 10n ? latest - 10n : latest
+  for (let i = 0; i < 500; i++) {
+    const block = await client.getBlock({ blockNumber: cursor })
+    if (block.transactions.length > 0) return { number: cursor, hash: block.hash }
+    if (cursor === 0n) break
+    cursor = cursor - 1n
+  }
+  return undefined
+}