tapimo 0.0.0 → 0.0.2

package/src/apps/transactions.test.ts

@@ -0,0 +1,408 @@
+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 Transactions from './transactions.js'
+
+/** The decoded `type` names a humanized transaction may report. */
+const transactionTypes = ['legacy', 'eip2930', 'eip1559', 'eip4844', 'eip7702', 'tempo', 'unknown']
+
+let transactionHash: Hex.Hex | undefined
+
+beforeAll(async () => {
+  const runtime = Runtime.get()
+  transactionHash =
+    runtime.mode === 'localnet'
+      ? runtime.fixtures!.faucetTransactionHashes[0]
+      : await findRecentTransactionHash().catch(() => undefined)
+})
+
+describe('GET /transactions/:transactionHash', () => {
+  test('humanizes the transaction, keeps the raw RPC under `meta.rpc`, and embeds the fee token on demand', async () => {
+    if (!transactionHash) {
+      console.warn('[live-rpc] no recent transaction found; skipping transaction happy path')
+      return
+    }
+
+    const client = TestApp.client()
+    const response = await client.v1.transactions[':transactionHash'].$get(
+      { param: { transactionHash: transactionHash }, query: {} },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Transactions.schema.getTransaction.Response)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('server-timing')?.includes('transaction;dur=')).toBe(true)
+    expect(body.hash).toBe(transactionHash.toLowerCase())
+    // The response is humanized: decoded `type`, decimal-string amounts, plain
+    // numbers for block/nonce, and ISO-8601 timestamps.
+    expect(body.sender).toMatch(/^0x[0-9a-f]{40}$/)
+    expect(transactionTypes).toContain(body.type)
+    expect(typeof body.gas).toBe('number')
+    expect(typeof body.nonce).toBe('number')
+    // The verbatim JSON-RPC transaction is always available under `meta.rpc`,
+    // where quantities stay hex-encoded and `type` is the raw `0x…` byte.
+    expect(body.meta.rpc.hash).toBe(transactionHash.toLowerCase())
+    expect(body.meta.rpc.type).toMatch(/^0x[0-9a-f]+$/)
+    expect(body.meta.rpc.gas).toMatch(/^0x[0-9a-f]+$/)
+    // Receipt-derived fields (execution status, gas used) are not on the
+    // transaction; they live on `/transactions/:transactionHash/receipt` instead.
+    expect('status' in body).toBe(false)
+    expect('gasUsed' in body).toBe(false)
+    // Fee-token metadata is opt-in: the base response must not embed it.
+    expect(body.meta.feeToken).toBeUndefined()
+
+    // include=feeToken: resolved metadata is embedded under meta (best-effort).
+    const includedResponse = await client.v1.transactions[':transactionHash'].$get(
+      { param: { transactionHash: transactionHash }, query: { include: 'feeToken' } },
+      TestApp.auth,
+    )
+    const includedBody = await TestApp.json(
+      includedResponse,
+      Transactions.schema.getTransaction.Response,
+    )
+    expect(includedResponse.status).toBe(200)
+    if (includedBody.feeToken) {
+      expect(includedBody.feeToken).toMatch(/^0x[0-9a-f]{40}$/)
+      // When metadata resolves, it must describe the fee token itself.
+      if (includedBody.meta?.feeToken) {
+        expect(includedBody.meta.feeToken.address).toBe(includedBody.feeToken)
+        expect(typeof includedBody.meta.feeToken.symbol).toBe('string')
+      }
+    }
+  })
+
+  test('embeds the receipt on demand via include=receipt', async () => {
+    const client = TestApp.client()
+    // Seed a recent mined hash from the list page so the fixture stays stable
+    // across runs.
+    const seedResponse = await client.v1.transactions.$get({ query: { limit: '5' } }, TestApp.auth)
+    const seed = await TestApp.json(seedResponse, Transactions.schema.getTransactions.Response)
+    expect(seedResponse.status).toBe(200)
+    const hash = seed.data[0]?.hash
+    expect(hash).toBeDefined()
+
+    const response = await client.v1.transactions[':transactionHash'].$get(
+      { param: { transactionHash: hash! }, query: { include: 'receipt' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Transactions.schema.getTransaction.Response)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('server-timing')?.includes('receipt;dur=')).toBe(true)
+    // The verbatim RPC receipt is humanized and embedded under `meta.receipt`,
+    // describing the transaction itself; its raw event logs come straight from
+    // the RPC response.
+    expect({
+      logsIsArray: Array.isArray(body.meta.receipt?.logs),
+      matchesHash: body.meta.receipt?.transactionHash === body.hash,
+      statusDecoded: ['success', 'reverted'].includes(body.meta.receipt?.status ?? ''),
+    }).toMatchInlineSnapshot(`
+      {
+        "logsIsArray": true,
+        "matchesHash": true,
+        "statusDecoded": true,
+      }
+    `)
+  })
+
+  test('returns 404 for an unknown transaction', async () => {
+    const client = TestApp.client()
+    const response = await client.v1.transactions[':transactionHash'].$get(
+      { param: { transactionHash: zeroHash }, query: {} },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    expect(response.status).toBe(404)
+    expect(body.error.code).toBe('transaction_not_found')
+  })
+
+  test('returns 400 for an invalid transaction hash', async () => {
+    // The typed client requires `transaction: `Hex.Hex`` so a literal
+    // non-hash input cannot pass through it; exercise the validator via
+    // `app.request` for this negative case.
+    const response = await TestApp.create().request('/v1/transactions/not-a-hash', {
+      headers: { authorization: `Bearer ${TestApp.key.token}` },
+    })
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    expect(response.status).toBe(400)
+    expect(body.error.code).toBe('transaction_invalid')
+  })
+})
+
+describe('GET /transactions', () => {
+  test('returns a humanized transaction page, embedding fee tokens on demand', async () => {
+    const client = TestApp.client()
+    const response = await client.v1.transactions.$get({ query: { limit: '5' } }, TestApp.auth)
+    const body = await TestApp.json(response, Transactions.schema.getTransactions.Response)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('server-timing')?.includes('transactions;dur=')).toBe(true)
+    expect(Array.isArray(body.data)).toBe(true)
+    // Cursor (keyset) pagination: the head page has no `page`, but carries an
+    // opaque `nextCursor` (a string when more rows follow, else null).
+    expect('page' in body).toBe(false)
+    expect(body.nextCursor === null || typeof body.nextCursor === 'string').toBe(true)
+    expect(body.data.length).toBeLessThanOrEqual(5)
+
+    // Walking the cursor must yield a disjoint next page (no offset-style overlap).
+    if (body.nextCursor) {
+      const next = await client.v1.transactions.$get(
+        { query: { limit: '5', cursor: body.nextCursor } },
+        TestApp.auth,
+      )
+      const nextBody = await TestApp.json(next, Transactions.schema.getTransactions.Response)
+      expect(next.status).toBe(200)
+      const firstHashes = new Set(body.data.map((t) => t.hash))
+      for (const t of nextBody.data) expect(firstHashes.has(t.hash)).toBe(false)
+    }
+
+    if (body.data.length > 0) {
+      const [transaction] = body.data
+      // List rows reuse the detail endpoint's humanized shape: decoded `type`,
+      // decimal amounts, plain-number block/nonce, and the verbatim payload
+      // under `meta.rpc`.
+      expect(transaction!.hash).toMatch(/^0x[0-9a-f]{64}$/)
+      expect(transaction!.sender).toMatch(/^0x[0-9a-f]{40}$/)
+      expect(transactionTypes).toContain(transaction!.type)
+      expect(typeof transaction!.gas).toBe('number')
+      expect(typeof transaction!.nonce).toBe('number')
+      expect(transaction!.meta.rpc.type).toMatch(/^0x[0-9a-f]+$/)
+      // Receipt-derived fields are not on the list payload, matching the detail
+      // endpoint; fee-token metadata is opt-in.
+      expect('status' in transaction!).toBe(false)
+      expect(transaction!.meta.feeToken).toBeUndefined()
+    }
+
+    const includedResponse = await client.v1.transactions.$get(
+      { query: { limit: '5', include: 'feeToken' } },
+      TestApp.auth,
+    )
+    const includedBody = await TestApp.json(
+      includedResponse,
+      Transactions.schema.getTransactions.Response,
+    )
+    expect(includedResponse.status).toBe(200)
+    const withFeeToken = includedBody.data.find((transaction) => transaction.meta?.feeToken)
+    if (withFeeToken) {
+      // When metadata resolves, it must describe the transaction's fee token.
+      expect(withFeeToken.meta.feeToken!.address).toBe(withFeeToken.feeToken)
+      expect(typeof withFeeToken.meta.feeToken!.symbol).toBe('string')
+    }
+  })
+
+  test('embeds receipts on demand via include=receipt', async () => {
+    const client = TestApp.client()
+    const response = await client.v1.transactions.$get(
+      { query: { include: 'receipt', limit: '5' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Transactions.schema.getTransactions.Response)
+    expect(response.status).toBe(200)
+    expect(body.data.length).toBeGreaterThan(0)
+    // Every mined row carries its own receipt under `meta.receipt`, matched by
+    // hash, with a decoded status and the page's event logs reattached (the
+    // head of the feed reliably contains at least one log-emitting transfer).
+    expect({
+      everyReceiptMatchesHash: body.data.every(
+        (transaction) => transaction.meta.receipt?.transactionHash === transaction.hash,
+      ),
+      everyStatusDecoded: body.data.every((transaction) =>
+        ['success', 'reverted'].includes(transaction.meta.receipt?.status ?? ''),
+      ),
+      someReceiptHasLogs: body.data.some(
+        (transaction) => (transaction.meta.receipt?.logs.length ?? 0) > 0,
+      ),
+    }).toMatchInlineSnapshot(`
+      {
+        "everyReceiptMatchesHash": true,
+        "everyStatusDecoded": true,
+        "someReceiptHasLogs": true,
+      }
+    `)
+  })
+
+  test('filters by execution status and paginates the receipts-driven path', async () => {
+    const client = TestApp.client()
+    const response = await client.v1.transactions.$get(
+      { query: { include: 'receipt', limit: '5', status: 'success' } },
+      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 transaction of body.data) expect(transaction.meta.receipt?.status).toBe('success')
+
+    // The receipts `(block_num, tx_idx)` cursor pages the status path: page 2
+    // parses against the same schema and stays disjoint from page 1.
+    expect(typeof body.nextCursor).toBe('string')
+    const next = await client.v1.transactions.$get(
+      { query: { cursor: body.nextCursor!, include: 'receipt', limit: '5', status: 'success' } },
+      TestApp.auth,
+    )
+    const nextBody = await TestApp.json(next, Transactions.schema.getTransactions.Response)
+    expect(next.status).toBe(200)
+    const firstHashes = new Set(body.data.map((transaction) => transaction.hash))
+    expect({
+      page2Disjoint: nextBody.data.every((transaction) => !firstHashes.has(transaction.hash)),
+      page2EveryReceiptSuccessful: nextBody.data.every(
+        (transaction) => transaction.meta.receipt?.status === 'success',
+      ),
+    }).toMatchInlineSnapshot(`
+      {
+        "page2Disjoint": true,
+        "page2EveryReceiptSuccessful": true,
+      }
+    `)
+  })
+
+  test('filters reverted transactions by execution status', async () => {
+    const client = TestApp.client()
+    const response = await client.v1.transactions.$get(
+      { query: { include: 'receipt', limit: '5', status: 'reverted' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Transactions.schema.getTransactions.Response)
+    expect(response.status).toBe(200)
+    // The head of the feed may contain no reverted transactions; every returned
+    // row must be reverted (vacuously true on an empty page).
+    expect(
+      body.data.every(
+        (transaction) =>
+          transaction.meta.receipt?.status === 'reverted' &&
+          transaction.meta.receipt.transactionHash === transaction.hash,
+      ),
+    ).toBe(true)
+  })
+
+  test('returns 400 for an invalid filter address', async () => {
+    // The typed client requires `sender: `Hex.Hex`` so an invalid literal
+    // cannot pass through it; exercise the validator via `app.request`.
+    const response = await TestApp.create().request('/v1/transactions?sender=not-an-address', {
+      headers: { authorization: `Bearer ${TestApp.key.token}` },
+    })
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    expect(response.status).toBe(400)
+    expect(body.error.code).toBe('query_invalid')
+  })
+
+  test('embeds a capped total count on demand via include=totalCount', async () => {
+    const client = TestApp.client()
+
+    // Seed a real account so the count exercises the address-scope `UNION` path.
+    const seed = await client.v1.transactions.$get({ query: { limit: '5' } }, TestApp.auth)
+    const seedBody = await TestApp.json(seed, Transactions.schema.getTransactions.Response)
+    const account = seedBody.data[0]?.sender
+    if (!account) return
+
+    const response = await client.v1.transactions.$get(
+      { query: { address: account, include: 'totalCount', limit: '5' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Transactions.schema.getTransactions.Response)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('server-timing')?.includes('transactions_count;dur=')).toBe(true)
+    expect(body.meta).toBeDefined()
+    expect(Number.isInteger(body.meta?.totalCount)).toBe(true)
+    expect(body.meta!.totalCount).toBeGreaterThanOrEqual(body.data.length)
+    expect(body.meta!.totalCount).toBeLessThanOrEqual(Schema.countCap)
+    expect(body.meta!.totalCountCapped).toBe(body.meta!.totalCount >= Schema.countCap)
+
+    // Without `include=totalCount`, the same page omits `meta` and the count.
+    const bare = await client.v1.transactions.$get(
+      { query: { address: account, limit: '5' } },
+      TestApp.auth,
+    )
+    const bareBody = await TestApp.json(bare, Transactions.schema.getTransactions.Response)
+    expect(bare.status).toBe(200)
+    expect(bareBody.meta).toBeUndefined()
+  })
+})
+
+// Walk back from the chain head to find a recent mined transaction hash. This
+// keeps the fixture stable across runs without hard-coding a hash that the
+// testnet might prune. The Tempo RPC node serves the test chain
+// (`42431` → `rpc.testnet.tempo.xyz`).
+async function findRecentTransactionHash() {
+  const client = Viem.getClient()
+  const latest = await client.getBlockNumber()
+  for (let n = latest; n > latest - 40n && n >= 0n; n--) {
+    const block = await client.getBlock({ blockNumber: n, includeTransactions: true })
+    const hash = block.transactions[0]?.hash
+    if (hash) return hash
+  }
+  return undefined
+}
+
+describe('GET /transactions?address=…', () => {
+  test('returns transactions involving an address', async () => {
+    const client = TestApp.client()
+    // Seed a real sender from the global transaction feed.
+    const seedResponse = await client.v1.transactions.$get({ query: { limit: '5' } }, TestApp.auth)
+    const seed = await TestApp.json(seedResponse, Transactions.schema.getTransactions.Response)
+    expect(seedResponse.status).toBe(200)
+    const account = seed.data[0]!.sender
+    expect(account).toMatch(/^0x[0-9a-f]{40}$/)
+
+    const baseResponse = await client.v1.transactions.$get(
+      { query: { address: account, limit: '5' } },
+      TestApp.auth,
+    )
+    const base = await TestApp.json(baseResponse, Transactions.schema.getTransactions.Response)
+
+    expect(baseResponse.status).toBe(200)
+    expect(baseResponse.headers.get('server-timing')?.includes('transactions;dur=')).toBe(true)
+    expect(Array.isArray(base.data)).toBe(true)
+    expect(base.data.length).toBeLessThanOrEqual(5)
+    // Pagination fields stay at the response root; the feed is cursor (keyset)
+    // paginated, so there's no `page` but an opaque `nextCursor`.
+    expect('page' in base).toBe(false)
+    expect(base.nextCursor === null || typeof base.nextCursor === 'string').toBe(true)
+    // Each item is the humanized transaction shape, with the verbatim RPC payload
+    // under `meta.rpc`.
+    expect(
+      base.data.every(
+        (entry) =>
+          /^0x[0-9a-f]{64}$/.test(entry.hash) &&
+          /^0x[0-9a-f]{40}$/.test(entry.sender) &&
+          (entry.recipient === null || /^0x[0-9a-f]{40}$/.test(entry.recipient)) &&
+          typeof entry.meta.rpc === 'object',
+      ),
+    ).toBe(true)
+    // Every row touches the subject address on one side or the other.
+    expect(
+      base.data.every((entry) => entry.sender === account || entry.recipient === account),
+    ).toBe(true)
+  })
+
+  test('serves a bounded positional page for an address scope via `page`', async () => {
+    const client = TestApp.client()
+    // Seed a real sender from the global feed. Ascending order anchors the
+    // scoped feed at the address's first transaction, so positional pages are
+    // deterministic against the head page. This exercises the offset lane of
+    // the per-side `UNION` query (branches over-fetch the full window, the
+    // outer merge applies the skip).
+    const seedResponse = await client.v1.transactions.$get({ query: { limit: '5' } }, TestApp.auth)
+    const seed = await TestApp.json(seedResponse, Transactions.schema.getTransactions.Response)
+    expect(seedResponse.status).toBe(200)
+    const account = seed.data[0]!.sender
+
+    const headResponse = await client.v1.transactions.$get(
+      { query: { address: account, limit: '10', order: 'asc' } },
+      TestApp.auth,
+    )
+    const head = await TestApp.json(headResponse, Transactions.schema.getTransactions.Response)
+    expect(headResponse.status).toBe(200)
+    if (head.data.length < 10) return
+
+    const offsetResponse = await client.v1.transactions.$get(
+      { query: { address: account, limit: '5', order: 'asc', page: '2' } },
+      TestApp.auth,
+    )
+    const page = await TestApp.json(offsetResponse, Transactions.schema.getTransactions.Response)
+    expect(offsetResponse.status).toBe(200)
+    expect(page.data.map((entry) => entry.hash)).toEqual(
+      head.data.slice(5, 10).map((entry) => entry.hash),
+    )
+  })
+})