tapimo 0.0.0 → 0.0.2

package/src/apps/transactions.ts

@@ -0,0 +1,1363 @@
+import { Hono, type Context } from 'hono'
+import { Hex } from 'ox'
+import * as z from 'zod/mini'
+
+import type * as App from '../App.js'
+import * as Auth from '../internal/Auth.js'
+import * as Cache from '../internal/Cache.js'
+import * as Cursor from '../internal/Cursor.js'
+import * as OpenApi from '../internal/OpenApi.js'
+import * as Response from '../internal/Response.js'
+import * as Schema from '../internal/Schema.js'
+import * as Store from '../internal/Store.js'
+import type * as Tidx from '../internal/Tidx.js'
+import * as Timing from '../internal/Timing.js'
+import * as Ttl from '../internal/Ttl.js'
+import * as Value from '../internal/Value.js'
+import * as VerifiedTokens from '../internal/VerifiedTokens.js'
+import * as Receipts from './receipts.js'
+import * as Tokens from './tokens.js'
+
+/** Example transaction hash surfaced in OpenAPI docs. */
+const exampleHash = '0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665'
+
+/** A decoded transaction type name. */
+type TransactionType =
+  | 'legacy'
+  | 'eip2930'
+  | 'eip1559'
+  | 'eip4844'
+  | 'eip7702'
+  | 'tempo'
+  | 'unknown'
+
+/**
+ * Maps a transaction `type` byte (as a number) to its human-readable name. The
+ * raw `0x…` byte is always preserved under `rpc.type`.
+ */
+const transactionTypeByNumber: Record<number, TransactionType> = {
+  0: 'legacy',
+  1: 'eip2930',
+  2: 'eip1559',
+  3: 'eip4844',
+  4: 'eip7702',
+  118: 'tempo',
+}
+
+/** Decodes a transaction `type` (hex string or number) into its name. */
+export function decodeTransactionType(value: unknown): TransactionType {
+  const byte = typeof value === 'number' ? value : Value.hexToNumber(value)
+  return (byte !== undefined && transactionTypeByNumber[byte]) || 'unknown'
+}
+
+/** Zod schemas owned by the transaction handlers. */
+export namespace schema {
+  // TODO(ox/zod): replace with the zod schema for `ox`'s `AccessList.Item` once
+  // ox ships a `zod` entrypoint.
+  /** One EIP-2930 access list entry (RPC format). */
+  export const AccessListItem = z
+    .looseObject({
+      address: Schema.Address.check(
+        z.describe('The account whose storage slots are listed in this access-list entry.'),
+      ),
+      storageKeys: z
+        .array(Schema.Hash)
+        .check(z.describe('The storage slot keys the transaction plans to access.')),
+    })
+    .check(
+      z.describe('One EIP-2930 access-list entry that predeclares an account and storage slots.'),
+    )
+
+  // TODO(ox/zod): replace with the zod schema for the RPC `Call` in `ox/tempo`'s
+  // `TxEnvelopeTempo`/`Transaction` types once ox ships a `zod` entrypoint.
+  /** One call within a Tempo account-abstraction transaction (RPC format). */
+  export const Call = z
+    .looseObject({
+      data: z
+        .nullish(Schema.Hex)
+        .check(
+          z.describe(
+            'Call data for this call; this is the same bytes as `input` when both are present.',
+          ),
+          z.meta({ examples: ['0xdeadbeef'] }),
+        ),
+      input: z
+        .nullish(Schema.Hex)
+        .check(
+          z.describe('Call data sent to the contract, as `0x`-prefixed bytes.'),
+          z.meta({ examples: ['0xdeadbeef'] }),
+        ),
+      to: z
+        .nullish(Schema.Address)
+        .check(
+          z.describe('The address this call targets, or `null` when the call creates a contract.'),
+        ),
+      value: z
+        .nullish(Schema.Quantity)
+        .check(z.describe('Native value sent with this call, as a hex quantity.')),
+    })
+    .check(z.describe('One operation inside a Tempo account-abstraction transaction.'))
+
+  // TODO(ox/zod): replace with the zod schema for `ox/tempo`'s
+  // `SignatureEnvelope.Rpc` (the secp256k1 / p256 / webAuthn / keychain union)
+  // once ox ships a `zod` entrypoint.
+  /**
+   * A signature envelope (RPC format), passed through verbatim. Every field is
+   * optional because the envelope is a union (secp256k1 / p256 / webAuthn /
+   * keychain) whose shape — including whether a `type` discriminator is present —
+   * varies; the loose object preserves whatever the RPC returns.
+   */
+  export const SignatureEnvelope = z
+    .looseObject({
+      type: z
+        .optional(z.string())
+        .check(
+          z.describe(
+            'The signature scheme used by this envelope, such as `secp256k1`, `p256`, or `keychain` when the RPC includes it.',
+          ),
+          z.meta({ examples: ['secp256k1'] }),
+        ),
+    })
+    .check(z.describe('The signature envelope exactly as returned by JSON-RPC.'))
+
+  /** The verbatim JSON-RPC payloads, surfaced under each resource's `rpc` field. */
+  export namespace Rpc {
+    // TODO(ox/zod): replace with the zod schema for `ox/tempo`'s
+    // `Transaction.Rpc` union once ox ships a `zod` entrypoint.
+    /** A JSON-RPC transaction, passed through verbatim. */
+    export const Transaction = z
+      .looseObject({
+        aaAuthorizationList: z
+          .optional(z.array(z.looseObject({})))
+          .check(
+            z.describe('Tempo account-abstraction authorizations attached to the transaction.'),
+          ),
+        accessList: z
+          .optional(z.array(AccessListItem))
+          .check(
+            z.describe(
+              'EIP-2930 access list that predeclares accounts and storage slots for the transaction.',
+            ),
+          ),
+        authorizationList: z
+          .optional(z.array(z.looseObject({})))
+          .check(z.describe('EIP-7702 authorizations attached to the transaction.')),
+        blobVersionedHashes: z
+          .optional(z.array(Schema.Hash))
+          .check(z.describe('Versioned blob hashes for EIP-4844 blob data.')),
+        blockHash: z
+          .nullable(Schema.Hash)
+          .check(
+            z.describe('The block hash once included, or `null` while the transaction is pending.'),
+          ),
+        blockNumber: z
+          .nullable(Schema.Quantity)
+          .check(
+            z.describe(
+              'The block number once included, or `null` while the transaction is pending.',
+            ),
+          ),
+        blockTimestamp: z
+          .nullish(Schema.Quantity)
+          .check(z.describe('The block timestamp for the block that included this transaction.')),
+        calls: z
+          .optional(
+            z.union([
+              z.array(Call).check(
+                z.meta({
+                  examples: [[{ data: '0xdeadbeef', input: '0xdeadbeef', to: null, value: '0x0' }]],
+                }),
+              ),
+              z.null().check(z.meta({ examples: [null] })),
+            ]),
+          )
+          .check(
+            z.describe('Decoded calls for Tempo account-abstraction transactions.'),
+            z.meta({
+              examples: [[{ data: '0xdeadbeef', input: '0xdeadbeef', to: null, value: '0x0' }]],
+            }),
+          ),
+        chainId: z
+          .optional(Schema.Quantity)
+          .check(
+            z.describe(
+              'The chain ID that the transaction is valid on; legacy transactions may omit it.',
+            ),
+          ),
+        feePayerSignature: z
+          .nullish(SignatureEnvelope)
+          .check(
+            z.describe('Signature from the account that paid the transaction fee.'),
+            z.meta({ examples: [{ type: 'secp256k1' }] }),
+          ),
+        feeToken: z
+          .nullish(Schema.Address)
+          .check(
+            z.describe(
+              'The fee token requested by the transaction; Tempo fees are paid in USD stablecoins such as `pathUSD`.',
+            ),
+          ),
+        from: Schema.Address.check(
+          z.describe('The address that submitted or authorized the transaction.'),
+        ),
+        gas: Schema.Quantity.check(z.describe('Maximum gas the transaction is allowed to use.')),
+        gasPrice: z
+          .optional(Schema.Quantity)
+          .check(
+            z.describe(
+              'Gas price for legacy-style transactions, expressed as a decimal string when humanized.',
+            ),
+          ),
+        hash: Schema.Hash.check(
+          z.describe(
+            'A 32-byte hash, `0x`-prefixed and returned in lowercase, that identifies this transaction.',
+          ),
+        ),
+        input: z
+          .optional(Schema.Hex)
+          .check(
+            z.describe('Call data for non-Tempo transaction formats, as `0x`-prefixed bytes.'),
+            z.meta({ examples: ['0xdeadbeef'] }),
+          ),
+        keyAuthorization: z
+          .nullish(z.looseObject({}))
+          .check(
+            z.describe('Key authorization data attached to this Tempo transaction.'),
+            z.meta({ examples: [{}] }),
+          ),
+        maxFeePerBlobGas: z
+          .optional(Schema.Quantity)
+          .check(z.describe('Maximum fee per blob gas for EIP-4844 blob data.')),
+        maxFeePerGas: z
+          .optional(Schema.Quantity)
+          .check(z.describe('Maximum total fee per gas the sender is willing to pay.')),
+        maxPriorityFeePerGas: z
+          .optional(Schema.Quantity)
+          .check(z.describe('Maximum priority fee per gas for EIP-1559-style transactions.')),
+        nonce: Schema.Quantity.check(
+          z.describe('Nonce from the sender account that orders and de-duplicates transactions.'),
+        ),
+        nonceKey: z
+          .optional(Schema.Quantity)
+          .check(z.describe('Tempo two-dimensional nonce key used to group nonce sequences.')),
+        r: z
+          .optional(Schema.Quantity)
+          .check(z.describe('The `r` value from the transaction ECDSA signature.')),
+        s: z
+          .optional(Schema.Quantity)
+          .check(z.describe('The `s` value from the transaction ECDSA signature.')),
+        signature: z
+          .optional(SignatureEnvelope)
+          .check(z.describe('Signature from the sender authorizing this transaction.')),
+        to: z
+          .nullish(Schema.Address)
+          .check(
+            z.describe('The recipient address, or `null` when the transaction creates a contract.'),
+          ),
+        transactionIndex: z
+          .nullable(Schema.Quantity)
+          .check(z.describe('The transaction position within its block, or `null` while pending.')),
+        type: Schema.Hex.check(
+          z.describe('Raw transaction type byte, such as `0x2` for EIP-1559 or `0x76` for Tempo.'),
+          z.meta({ examples: ['0x2'] }),
+        ),
+        v: z
+          .optional(Schema.Quantity)
+          .check(z.describe('The `v` recovery value from the transaction ECDSA signature.')),
+        validAfter: z
+          .nullish(Schema.Quantity)
+          .check(
+            z.describe('Earliest Unix timestamp when this Tempo transaction may be included.'),
+            z.meta({ examples: ['0x0'] }),
+          ),
+        validBefore: z
+          .nullish(Schema.Quantity)
+          .check(
+            z.describe('Latest Unix timestamp when this Tempo transaction may be included.'),
+            z.meta({ examples: ['0xffffffff'] }),
+          ),
+        value: z
+          .optional(Schema.Quantity)
+          .check(z.describe('Native value sent by non-Tempo transaction formats.')),
+        yParity: z
+          .optional(Schema.Quantity)
+          .check(z.describe('The y-parity value from the transaction signature.')),
+      })
+      .check(z.describe('The transaction exactly as returned by JSON-RPC.'))
+  }
+
+  /**
+   * Metadata for a transaction: the verbatim JSON-RPC transaction (always
+   * present) plus resources embedded on demand via `include`.
+   *
+   * The `feeToken` and `receipt` schemas are wrapped in `z.lazy` because
+   * `tokens.ts`/`receipts.ts` and `transactions.ts` mutually reference each
+   * other's schemas; deferring these lookups avoids the import-cycle crash
+   * during module init.
+   */
+  export const TransactionMeta = z
+    .object({
+      feeToken: z
+        .optional(z.lazy(() => Tokens.schema.getToken.Response))
+        .check(z.describe('Fee-token details included only when you request `include=feeToken`.')),
+      receipt: z
+        .optional(z.lazy(() => Receipts.schema.Receipt))
+        .check(
+          z.describe('The transaction outcome included only when you request `include=receipt`.'),
+        ),
+      rpc: Rpc.Transaction.check(z.describe('The original JSON-RPC transaction payload.')),
+    })
+    .check(
+      z.describe(
+        'Metadata for this transaction: the original JSON-RPC payload plus any requested `include` resources.',
+      ),
+    )
+
+  /** Decoded transaction `type`; the raw `0x…` byte stays under `rpc.type`. */
+  export const TransactionType = z
+    .enum(['legacy', 'eip2930', 'eip1559', 'eip4844', 'eip7702', 'tempo', 'unknown'])
+    .check(
+      z.describe('Human-readable transaction type decoded from the raw JSON-RPC `type` byte.'),
+      z.meta({ examples: ['eip1559'] }),
+    )
+
+  /** One humanized call within a Tempo account-abstraction transaction. */
+  export const HumanCall = z
+    .object({
+      data: z
+        .optional(Schema.Hex)
+        .check(
+          z.describe('Call data sent to the contract, as `0x`-prefixed bytes.'),
+          z.meta({ examples: ['0xdeadbeef'] }),
+        ),
+      to: z
+        .nullable(Schema.Address)
+        .check(z.describe('The address this call targets, or `null` when it creates a contract.')),
+    })
+    .check(z.describe('One decoded call inside a Tempo account-abstraction transaction.'))
+
+  /**
+   * A humanized transaction: decoded `type`, decimal-string amounts, ISO 8601
+   * timestamps, and plain-number block fields. The verbatim JSON-RPC transaction
+   * is always available under `meta.rpc`.
+   */
+  export const Transaction = z
+    .object({
+      blockHash: z
+        .nullable(Schema.Hash)
+        .check(
+          z.describe('The block hash once included, or `null` while the transaction is pending.'),
+        ),
+      blockNumber: z
+        .nullable(z.number().check(z.int(), z.nonnegative()))
+        .check(
+          z.describe('The block number once included, or `null` while the transaction is pending.'),
+          z.meta({ examples: [23456789] }),
+        ),
+      calls: z
+        .optional(z.array(HumanCall))
+        .check(
+          z.describe('Decoded calls for Tempo account-abstraction transactions.'),
+          z.meta({ examples: [[{ data: '0xdeadbeef', to: null }]] }),
+        ),
+      chainId: z
+        .optional(z.number().check(z.int(), z.nonnegative()))
+        .check(
+          z.describe('The chain ID that this transaction belongs to.'),
+          z.meta({ examples: [4217] }),
+        ),
+      feeToken: z
+        .optional(Schema.Address)
+        .check(
+          z.describe(
+            'The fee token requested by the transaction; Tempo fees are paid in USD stablecoins such as `pathUSD`.',
+          ),
+        ),
+      gas: z
+        .number()
+        .check(
+          z.int(),
+          z.nonnegative(),
+          z.describe('Maximum gas the transaction is allowed to use.'),
+          z.meta({ examples: [21000] }),
+        ),
+      gasPrice: z
+        .optional(Schema.DecimalString)
+        .check(
+          z.describe(
+            'Gas price for legacy-style transactions, expressed as a decimal string when humanized.',
+          ),
+        ),
+      hash: Schema.Hash.check(
+        z.describe(
+          'A 32-byte hash, `0x`-prefixed and returned in lowercase, that identifies this transaction.',
+        ),
+      ),
+      id: Schema.Hash.check(
+        z.describe('Stable resource ID for this API response; it is the transaction hash.'),
+      ),
+      input: z
+        .optional(Schema.Hex)
+        .check(
+          z.describe('Call data for non-Tempo transaction formats, as `0x`-prefixed bytes.'),
+          z.meta({ examples: ['0xdeadbeef'] }),
+        ),
+      maxFeePerGas: z
+        .optional(Schema.DecimalString)
+        .check(z.describe('Maximum total fee per gas the sender is willing to pay.')),
+      maxPriorityFeePerGas: z
+        .optional(Schema.DecimalString)
+        .check(z.describe('Maximum priority fee per gas for EIP-1559-style transactions.')),
+      meta: TransactionMeta.check(
+        z.describe('The original JSON-RPC payload plus any resources requested with `include`.'),
+      ),
+      nonce: z
+        .number()
+        .check(
+          z.int(),
+          z.nonnegative(),
+          z.describe('Nonce from the sender account that orders and de-duplicates transactions.'),
+          z.meta({ examples: [0] }),
+        ),
+      nonceKey: z
+        .optional(Schema.Hex)
+        .check(
+          z.describe('Tempo two-dimensional nonce key used by Tempo transactions.'),
+          z.meta({ examples: ['0x0'] }),
+        ),
+      recipient: z
+        .nullable(Schema.Address)
+        .check(
+          z.describe('The recipient address, or `null` when the transaction creates a contract.'),
+        ),
+      sender: Schema.Address.check(
+        z.describe('The address that submitted or authorized the transaction.'),
+      ),
+      timestamp: z
+        .nullable(z.iso.datetime())
+        .check(
+          z.describe(
+            'The block timestamp as ISO 8601, or `null` while the transaction is pending.',
+          ),
+          z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+        ),
+      transactionIndex: z
+        .nullable(z.number().check(z.int(), z.nonnegative()))
+        .check(
+          z.describe('The transaction position within its block, or `null` while pending.'),
+          z.meta({ examples: [0] }),
+        ),
+      type: TransactionType,
+      validAfter: z
+        .nullish(z.iso.datetime())
+        .check(
+          z.describe('Earliest ISO 8601 time when this Tempo transaction may be included.'),
+          z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+        ),
+      validBefore: z
+        .nullish(z.iso.datetime())
+        .check(
+          z.describe('Latest ISO 8601 time when this Tempo transaction may be included.'),
+          z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+        ),
+      value: Schema.DecimalString.check(
+        z.describe('Native value transferred by this transaction, as a decimal string.'),
+      ),
+    })
+    .check(
+      z.describe(
+        'A transaction formatted for API clients, with decoded fields and the original JSON-RPC payload under `meta.rpc`.',
+      ),
+    )
+
+  /** Schemas for the getTransaction operation. */
+  export namespace getTransaction {
+    /** Path parameters for transaction requests. */
+    export const Params = z
+      .object({
+        transactionHash: Schema.Hash.check(
+          z.describe(
+            'A 32-byte hash, `0x`-prefixed and returned in lowercase, that identifies this transaction.',
+          ),
+          z.meta({ examples: [exampleHash] }),
+        ),
+      })
+      .check(z.describe('Path parameters used to look up a transaction.'))
+
+    /** Optional related resource that callers opt into via `include`. */
+    export const Include = z
+      .enum(['feeToken', 'receipt'])
+      .check(z.describe('Related resource you can opt into with the `include` query parameter.'))
+
+    /**
+     * Parses a comma-separated `include` query value into a list of optional
+     * resources to embed. Extra lookups (e.g. fee-token metadata, the receipt)
+     * only run when explicitly requested, keeping the base transaction response
+     * fast.
+     */
+    export const includeQuery = Schema.includeQuery(
+      Include,
+      'Comma-separated related resources to include, such as `feeToken,receipt`.',
+    )
+
+    /** Query parameters for transaction requests. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        include: includeQuery,
+      })
+      .check(z.describe('Query parameters for looking up a transaction.'))
+
+    /** A humanized transaction, with the verbatim JSON-RPC payload under `rpc`. */
+    export const Response = Transaction
+  }
+
+  /** Schemas for the getTransactions (list) operation. */
+  export namespace getTransactions {
+    /**
+     * Optional resources for the transaction list: the per-row `feeToken` /
+     * `receipt` embeds plus the response-wide capped `totalCount`. The detail
+     * route keeps its own {@link getTransaction.Include}.
+     */
+    export const Include = z
+      .enum(['feeToken', 'receipt', 'totalCount'])
+      .check(
+        z.describe('Related resources to include in each transaction row or in response metadata.'),
+      )
+
+    /** Parses the comma-separated `include` value for the transaction list. */
+    export const includeQuery = Schema.includeQuery(
+      Include,
+      'Comma-separated related resources to include, such as `feeToken,receipt,totalCount`.',
+    )
+
+    /** Query parameters for transaction list requests. */
+    export const Query = z
+      .strictObject({
+        address: z
+          .optional(Schema.Address)
+          .check(
+            z.describe(
+              'Filter to transactions where this address is either the sender or recipient.',
+            ),
+          ),
+        'blockNumber.from': Schema.blockNumberBound('transactions', 'from'),
+        'blockNumber.to': Schema.blockNumberBound('transactions', 'to'),
+        chainId: Schema.ChainIdQuery,
+        cursor: Schema.Cursor,
+        feePayer: z
+          .optional(Schema.Address)
+          .check(z.describe('Filter to transactions whose fee payer is this address.')),
+        feeToken: z
+          .optional(Schema.TokenAddress)
+          .check(z.describe('Filter to transactions whose fee was paid in this token address.')),
+        include: includeQuery,
+        limit: Schema.Limit,
+        order: Schema.Order,
+        page: Schema.Page,
+        recipient: z
+          .optional(Schema.Address)
+          .check(z.describe('Filter to transactions sent to this recipient address.')),
+        sender: z
+          .optional(Schema.Address)
+          .check(z.describe('Filter to transactions sent by this sender address.')),
+        status: z
+          .optional(z.enum(['success', 'reverted']))
+          .check(
+            z.describe('Filter to transactions whose receipt shows this execution status.'),
+            z.meta({ examples: ['success'] }),
+          ),
+        'timestamp.from': Schema.timestampBound('transactions', 'from'),
+        'timestamp.to': Schema.timestampBound('transactions', 'to'),
+      })
+      .check(...Schema.pageChecks(), z.describe('Query parameters for listing transactions.'))
+
+    /**
+     * Page of transactions. Each item reuses the humanized transaction returned
+     * by `GET /transactions/:transactionHash`, so the list and detail endpoints
+     * expose one identical shape. Indexed list rows omit fields the indexer does
+     * not store (signatures, access list), reflected in their `rpc` payload.
+     */
+    export const Response = z
+      .object({
+        data: z.array(getTransaction.Response).check(z.describe('Transactions on this page.')),
+        meta: z
+          .optional(Schema.CountMeta)
+          .check(
+            z.describe('Response-level metadata requested with `include`, such as `totalCount`.'),
+          ),
+        nextCursor: Schema.NextCursor,
+      })
+      .check(z.describe('A page of transactions ordered by block number and transaction position.'))
+  }
+}
+/** Creates transaction handlers. */
+export function transactions() {
+  return new Hono<App.Environment>()
+    .get(
+      '/',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('query', schema.getTransactions.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'List transactions across Tempo, with filters for addresses, blocks, timestamps, fees, and status.',
+        operationId: 'getTransactions',
+        responses: OpenApi.responses({
+          errors: { 502: 'Could not read indexed transaction data from TIDX.' },
+          success: {
+            description: 'A page of transactions.',
+            schema: schema.getTransactions.Response,
+          },
+        }),
+        summary: 'List transactions',
+        tags: ['Transactions'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.feed,
+        name: 'tempo-api:transactions:v1',
+        key: (c) => Cache.urlKey(c, schema.getTransactions.Query),
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Invalid query parameters',
+          })
+
+        const query = c.req.valid('query')
+        const chainId = query.chainId ?? c.get('chainId')
+
+        // A cursor page is anchored below the head, so its contents are
+        // append-only and effectively immutable; cache it aggressively. The head
+        // page (no cursor) keeps the route's short `feed` default.
+        if (query.cursor !== undefined) Cache.setPolicy(c, Cache.policies.immutable)
+
+        try {
+          // `totalCount` is opt-in and shares the page's filters; run it
+          // concurrently with the page. Best-effort: a count failure omits
+          // `meta` rather than failing the page.
+          const countPromise = query.include.includes('totalCount')
+            ? countTransactions(c, {
+                address: query.address,
+                chainId,
+                feePayer: query.feePayer,
+                feeToken: query.feeToken,
+                fromBlock: query['blockNumber.from'],
+                fromTimestamp: query['timestamp.from'],
+                recipient: query.recipient,
+                sender: query.sender,
+                status: query.status,
+                toBlock: query['blockNumber.to'],
+                toTimestamp: query['timestamp.to'],
+              }).catch(() => undefined)
+            : undefined
+
+          const transactions = await listTransactions(c, {
+            address: query.address,
+            chainId,
+            cursor: query.cursor,
+            feePayer: query.feePayer,
+            feeToken: query.feeToken,
+            fromBlock: query['blockNumber.from'],
+            fromTimestamp: query['timestamp.from'],
+            include: query.include.filter(
+              (resource): resource is z.output<typeof schema.getTransaction.Include> =>
+                resource !== 'totalCount',
+            ),
+            limit: query.limit,
+            order: query.order,
+            page: query.page,
+            recipient: query.recipient,
+            sender: query.sender,
+            status: query.status,
+            toBlock: query['blockNumber.to'],
+            toTimestamp: query['timestamp.to'],
+          })
+
+          const meta = countPromise ? await countPromise : undefined
+          return c.json(
+            Response.validated(schema.getTransactions.Response, {
+              ...transactions,
+              ...(meta ? { meta } : {}),
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/:transactionHash',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('param', schema.getTransaction.Params, {
+        code: 'transaction_invalid',
+        message: 'Invalid transaction hash',
+      }),
+      OpenApi.validate('query', schema.getTransaction.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description: 'Get one transaction by its 32-byte transaction hash.',
+        operationId: 'getTransaction',
+        responses: OpenApi.responses({
+          errors: {
+            404: {
+              description: 'No transaction was found for that hash.',
+              codes: ['transaction_not_found'],
+            },
+            502: 'Could not read transaction data from the upstream JSON-RPC node.',
+          },
+          success: {
+            description: 'A single transaction with decoded fields and original JSON-RPC data.',
+            schema: schema.getTransaction.Response,
+          },
+        }),
+        summary: 'Get a transaction by hash',
+        tags: ['Transactions'],
+      }),
+      Cache.response<App.Environment>({
+        // Default to no-store: a pending (or not-found) transaction must not be
+        // cached, or it would mask the mined result. The handler upgrades a mined
+        // transaction to `immutable` below.
+        cacheControl: Cache.policies.noStore,
+        name: 'tempo-api:transactions:v1',
+        key: (c) => Cache.urlKey(c, schema.getTransaction.Query),
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'transaction_invalid',
+            message: 'Invalid request parameters',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Invalid request parameters',
+          })
+
+        const { transactionHash } = c.req.valid('param')
+        const query = c.req.valid('query')
+        const chainId = query.chainId ?? c.get('chainId')
+        const client = c.get('getClient')(chainId)
+        // `Schema.Hash` lowercases to a plain string; re-narrow to the hex
+        // template literal viem requires at the RPC boundary.
+        const hash = transactionHash as Hex.Hex
+
+        try {
+          // Fetch the JSON-RPC transaction; a `null` result means the
+          // transaction is unknown rather than an error. The verbatim payload is
+          // surfaced under `rpc`, with humanized fields layered on top. Unmined
+          // lookups (pending or unknown hash) are deliberately never cached —
+          // confirmation polling must observe the mined result the moment the
+          // node does.
+          const rpc = await Timing.time(c, 'transaction', () =>
+            client.request({ method: 'eth_getTransactionByHash', params: [hash] }),
+          )
+          if (!rpc)
+            return Response.error(c, {
+              code: 'transaction_not_found',
+              message: 'Transaction not found',
+              status: 404,
+            })
+
+          let data = humanizeTransaction(Response.validated(schema.Rpc.Transaction, rpc))
+
+          // A mined transaction is immutable, so it can be cached aggressively; a
+          // pending one (no block yet) keeps the route's default no-store policy.
+          if (data.blockNumber !== null) Cache.setPolicy(c, Cache.policies.immutable)
+
+          // The receipt is opt-in: fetching it is an extra RPC, so it only runs
+          // when requested via `include=receipt` and the transaction is mined.
+          // A null receipt (still pending) is simply omitted.
+          if (query.include.includes('receipt') && data.blockNumber !== null) {
+            const receipt = await Timing.time(c, 'receipt', () =>
+              client.request({ method: 'eth_getTransactionReceipt', params: [hash] }),
+            )
+            if (receipt) {
+              const humanized = Receipts.humanizeReceipt(
+                Response.validated(Receipts.schema.Rpc.Receipt, receipt),
+              )
+              data = { ...data, meta: { ...data.meta, receipt: humanized } }
+            }
+          }
+
+          // Fee-token metadata is opt-in: resolving it is an extra RPC, so it
+          // only runs when requested via `include=feeToken` and the transaction
+          // declares a fee token (Tempo AA transactions).
+          const feeToken = data.feeToken
+          if (query.include.includes('feeToken') && feeToken !== undefined) {
+            const token = await Timing.time(c, 'fee_token', () =>
+              Tokens.resolveToken(c, { address: feeToken, chainId }).catch(() => undefined),
+            )
+            if (token) data = { ...data, meta: { ...data.meta, feeToken: token } }
+          }
+
+          return c.json(Response.validated(schema.getTransaction.Response, data), 200)
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+}
+
+/**
+ * Lists humanized transactions and embeds opt-in `include` resources
+ * (`feeToken`, `receipt`). A `status` filter routes the page through the
+ * receipts list instead of the `txs` scan, since execution status lives on
+ * receipts.
+ */
+export async function listTransactions(
+  c: Context<App.Environment>,
+  options: listTransactions.Options,
+) {
+  const { include, ...rest } = options
+
+  // `status` filters on the receipt's execution status, which `txs` does not
+  // store: page the receipts list (which already supports `status`) and hydrate
+  // each receipt's underlying transaction. The receipts `(block_num, tx_idx)`
+  // keyset cursor spans the same domain as the transactions `(block_num, idx)`
+  // cursor, so cursors stay interchangeable between the two paths.
+  const receiptPage =
+    rest.status === undefined
+      ? undefined
+      : await Receipts.getReceipts(c, {
+          address: rest.address,
+          chainId: rest.chainId,
+          cursor: rest.cursor,
+          feePayer: rest.feePayer,
+          feeToken: rest.feeToken,
+          fromBlock: rest.fromBlock,
+          fromTimestamp: rest.fromTimestamp,
+          limit: rest.limit,
+          order: rest.order,
+          page: rest.page,
+          recipient: rest.recipient,
+          sender: rest.sender,
+          status: rest.status,
+          toBlock: rest.toBlock,
+          toTimestamp: rest.toTimestamp,
+        })
+  const page = receiptPage
+    ? {
+        data: await transactionsForReceipts(c, {
+          chainId: rest.chainId,
+          receipts: receiptPage.data,
+        }),
+        nextCursor: receiptPage.nextCursor,
+      }
+    : await getTransactions(c, rest)
+
+  let data = page.data
+  if (include.includes('receipt') && data.length > 0) {
+    const receipts = await Receipts.embedReceipts(c, {
+      chainId: rest.chainId,
+      receipts: receiptPage?.data,
+      rows: data,
+    })
+    data = data.map((row) => {
+      const receipt = receipts.get(row.hash.toLowerCase())
+      return receipt ? { ...row, meta: { ...row.meta, receipt } } : row
+    })
+  }
+  if (include.includes('feeToken')) data = await embedFeeTokens(c, data, rest.chainId)
+  return { ...page, data }
+}
+
+export declare namespace listTransactions {
+  type Options = getTransactions.Options & {
+    /** Optional related resources to embed (e.g. `feeToken`, `receipt`). */
+    include: readonly z.output<typeof schema.getTransaction.Include>[]
+  }
+}
+
+/**
+ * Fetches the underlying transactions for a page of receipts in one indexed
+ * `txs` query and returns them humanized, ordered to match the receipt page.
+ * Receipts whose transaction row is missing (not yet indexed) are skipped.
+ * Backs the `status`-filtered transactions list, which pages receipts first.
+ */
+async function transactionsForReceipts(
+  c: Context<App.Environment>,
+  options: {
+    chainId: z.output<typeof Schema.ChainId>
+    receipts: readonly z.output<typeof Receipts.schema.Receipt>[]
+  },
+): Promise<z.output<typeof schema.Transaction>[]> {
+  const { chainId, receipts } = options
+  if (receipts.length === 0) return []
+  const tidx = c.get('getTidx')(chainId)
+  const blocks = [...new Set(receipts.map((receipt) => receipt.blockNumber))]
+  const hashes = [...new Set(receipts.map((receipt) => receipt.transactionHash))]
+
+  // `txs` is sorted by `(block_num, idx)` with no hash index, so the hash list
+  // must be paired with the page's block numbers — a bare `hash IN` full-scans
+  // the table. Raw-table query, so the inline SQL is cast to `string`.
+  const result = await Timing.time(c, 'transactions', () =>
+    tidx.fetch({
+      chainId,
+      query:
+        `SELECT ${transactionColumns} FROM txs WHERE block_num IN (${blocks.join(', ')}) AND hash IN (${hashes.map((hash) => `'${hash}'`).join(', ')})` as string,
+    }),
+  )
+
+  const byHash = new Map<string, z.output<typeof schema.Transaction>>()
+  for (const row of result.rows) {
+    const rpc = schema.Rpc.Transaction.safeParse(toRpcTransaction(row))
+    if (rpc.success) byHash.set(rpc.data.hash.toLowerCase(), humanizeTransaction(rpc.data))
+  }
+  return receipts
+    .map((receipt) => byHash.get(receipt.transactionHash.toLowerCase()))
+    .filter((transaction) => transaction !== undefined)
+}
+
+/**
+ * Resolves fee-token metadata for each row and embeds it under `meta.feeToken`,
+ * sharing a single verified-token fetch. Best-effort: a row whose fee token
+ * can't be resolved (or that has none) is returned unchanged. Shared by the
+ * transaction and receipt list endpoints (and their address-scoped variants),
+ * whose rows all carry an optional `feeToken` address and a `meta` object.
+ */
+export async function embedFeeTokens<
+  row extends { feeToken?: Hex.Hex | undefined; meta: Record<string, unknown> },
+>(c: Context<App.Environment>, rows: row[], chainId: z.output<typeof Schema.ChainId>) {
+  if (rows.length === 0) return rows
+  const uniqueTokens = Array.from(
+    new Set(
+      rows.map((row) => row.feeToken).filter((address): address is Hex.Hex => address != null),
+    ),
+  )
+  if (uniqueTokens.length === 0) return rows
+
+  const snapshot = await VerifiedTokens.snapshot(c, chainId)
+  const resolved = await Timing.time(c, 'tokens', () =>
+    Promise.all(
+      uniqueTokens.map((token) =>
+        Tokens.resolveToken(c, {
+          address: token,
+          chainId,
+          snapshot,
+        })
+          .then((metadata) => [token, metadata] as const)
+          .catch(() => [token, undefined] as const),
+      ),
+    ),
+  )
+  const tokensByAddress = new Map(resolved)
+  return rows.map((row) => {
+    const token = row.feeToken == null ? undefined : tokensByAddress.get(row.feeToken)
+    // The runtime shape stays `row`; the generic object spread just can't prove
+    // the override keeps it assignable to `row`.
+    return (token ? { ...row, meta: { ...row.meta, feeToken: token } } : row) as row
+  })
+}
+
+export function getTransactions(c: Context<App.Environment>, options: getTransactions.Options) {
+  const { chainId } = options
+  const store = c.get('store')
+  const tidx = c.get('getTidx')(chainId)
+  const cursor = options.cursor ? Cursor.decode(options.cursor, ['int', 'int']) : undefined
+
+  return Timing.time(c, 'transactions', () =>
+    Store.memoize(
+      async () => {
+        const page = await scanTransactions({ tidx }, options)
+        return {
+          data: page.items.map((item) => item.data),
+          nextCursor: page.nextCursor,
+        }
+      },
+      {
+        key: `transactions:v1:${chainId}:${options.order}:${options.address ?? ''}:${options.sender ?? ''}:${options.recipient ?? ''}:${options.feePayer ?? ''}:${options.feeToken ?? ''}:${options.fromBlock ?? ''}:${options.toBlock ?? ''}:${options.fromTimestamp ?? ''}:${options.toTimestamp ?? ''}:${cursor ? `cursor:${cursor[0]}:${cursor[1]}` : options.page !== undefined && options.page > 1 ? `page:${options.page}` : 'head'}:${options.limit}`,
+        store,
+        ttl: Ttl.seconds(15),
+      },
+    ),
+  )
+}
+
+/**
+ * Context-free core of {@link getTransactions}: builds the `txs` query (with the
+ * address-scoped `UNION` planner workaround), applies keyset pagination on
+ * `(block_num, idx)`, and reconstructs each row through the same
+ * `toRpcTransaction` → `humanizeTransaction` path the detail endpoint uses. Used
+ * by the Hono routes (via {@link getTransactions}, which adds Server-Timing +
+ * memoization) and by the webhook poller (uncached, ascending, per-row cursors).
+ */
+export async function scanTransactions(
+  deps: scanTransactions.Deps,
+  options: getTransactions.Options,
+): Promise<scanTransactions.Page> {
+  const {
+    address,
+    chainId,
+    feePayer,
+    feeToken,
+    fromBlock,
+    fromTimestamp,
+    includeCallRecipients,
+    limit,
+    order,
+    recipient,
+    sender,
+    toBlock,
+    toTimestamp,
+  } = options
+  const { tidx } = deps
+  const sortDirection = order === 'asc' ? 'ASC' : 'DESC'
+  // Keyset pagination: anchor the page below the previous row's `(block, idx)`
+  // position instead of a numeric offset, so rows arriving at the head can't
+  // shift items across pages. A malformed cursor decodes to `undefined` and
+  // falls back to the head page.
+  const cursor = options.cursor ? Cursor.decode(options.cursor, ['int', 'int']) : undefined
+  // Bounded positional lane (exclusive with `cursor` at the schema): page 1 is
+  // the head page, so it shares the head's SQL and cache entries; deeper pages
+  // translate to a SQL OFFSET of `(page - 1) * limit` rows.
+  const offset =
+    options.page !== undefined && options.page > 1 ? (options.page - 1) * limit : undefined
+
+  // Raw transactions from the `txs` table (Postgres engine). `txs` is a
+  // standard table, not a signature-decoded CTE, so the inline query is
+  // cast to `string` and needs no `signatures`. Order by block then
+  // in-block index so transactions stay stable across pages, and fetch one
+  // extra row to detect `hasMore` without a separate count query.
+  //
+  // Build the shared filters once (everything except the address-scope
+  // predicate); the `address` filter is special-cased below because the
+  // TIDX engine errors out on `(from = X OR to = X) ORDER BY ...` for
+  // contracts with non-trivial traffic and an index-friendly `UNION`
+  // over the two sides plans cleanly.
+  const filters: string[] = []
+  if (sender !== undefined) filters.push(`"from" = '${sender}'`)
+  if (recipient !== undefined)
+    // For Tempo AA transactions the meaningful recipient is often an inner call
+    // target, so `includeCallRecipients` also matches `calls[].to` (a JSONB array
+    // of `{ to, value, input }`). The `@>` containment hits the partial GIN index
+    // on `calls`; the root `"to"` branch covers non-AA and single-call AA txs
+    // (whose `"to"` mirrors `calls[0].to` and which the partial index omits).
+    filters.push(
+      includeCallRecipients
+        ? `("to" = '${recipient}' OR calls @> '[{"to": "${recipient}"}]')`
+        : `"to" = '${recipient}'`,
+    )
+  if (feePayer !== undefined) filters.push(`fee_payer = '${feePayer}'`)
+  if (feeToken !== undefined) filters.push(`fee_token = '${feeToken}'`)
+  if (fromBlock !== undefined) filters.push(`block_num >= ${fromBlock}`)
+  if (toBlock !== undefined) filters.push(`block_num <= ${toBlock}`)
+  if (fromTimestamp !== undefined) filters.push(`block_timestamp >= '${fromTimestamp}'`)
+  if (toTimestamp !== undefined) filters.push(`block_timestamp <= '${toTimestamp}'`)
+  if (cursor !== undefined)
+    filters.push(
+      Cursor.keyset([
+        { literal: Cursor.literal(cursor[0]!, 'int'), name: 'block_num', order },
+        { literal: Cursor.literal(cursor[1]!, 'int'), name: 'idx', order },
+      ]),
+    )
+
+  // For address-scoped queries, run one branch per side and `UNION` so
+  // each branch can use its own (`from`/`to`) index. The `ORDER BY` and
+  // `LIMIT` must live *inside* each branch — TIDX's planner crashes on
+  // a UNION whose outer query orders by `block_num, idx` for
+  // high-traffic contracts (and on the `(from = X OR to = X) ORDER BY`
+  // form). Pushing the sort+limit down means each branch returns at
+  // most `limit + 1` index-ordered rows, the outer query re-merges,
+  // and plain `UNION` dedupes the self-transfer case where
+  // `from = to = address`.
+  // In the offset lane each branch must over-fetch the full window
+  // (`offset + limit + 1` rows) because the skip applies to the merged set:
+  // the outer query re-sorts the union and discards the first `offset` rows.
+  const sideQuery = (side: 'from' | 'to', addr: string) => {
+    const where = [`"${side}" = '${addr}'`, ...filters].join(' AND ')
+    return `(SELECT ${transactionColumns} FROM txs WHERE ${where} ORDER BY block_num ${sortDirection}, idx ${sortDirection} LIMIT ${(offset ?? 0) + limit + 1})`
+  }
+  const skip = offset !== undefined ? ` OFFSET ${offset}` : ''
+  const query =
+    address !== undefined
+      ? `
+              ${sideQuery('from', address)}
+              UNION
+              ${sideQuery('to', address)}
+              ORDER BY block_num ${sortDirection}, idx ${sortDirection}
+              LIMIT ${limit + 1}${skip}
+            `
+      : `
+              SELECT ${transactionColumns}
+              FROM txs
+              ${filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : ''}
+              ORDER BY block_num ${sortDirection}, idx ${sortDirection}
+              LIMIT ${limit + 1}${skip}
+            `
+
+  const result = await tidx.fetch({ chainId, query: query as string })
+
+  // The next page anchors below the last fetched row's `(block, idx)`.
+  const page = Cursor.paginate({
+    rows: result.rows,
+    limit,
+    key: (row) => {
+      const block = Value.toNumber(row['block_num'])
+      const index = Value.toNumber(row['idx'])
+      return block !== undefined && index !== undefined ? [block, index] : undefined
+    },
+  })
+
+  // Reconstruct the RPC shape from the indexed columns, then humanize it
+  // through the same path as the detail endpoint so the list and detail
+  // responses are identical. Rows that fail to reconstruct are skipped.
+  const items: scanTransactions.Item[] = []
+  for (const row of page.rows) {
+    const rpc = schema.Rpc.Transaction.safeParse(toRpcTransaction(row))
+    const block = Value.toNumber(row['block_num'])
+    const index = Value.toNumber(row['idx'])
+    if (rpc.success && block !== undefined && index !== undefined)
+      items.push({ cursor: [block, index], data: humanizeTransaction(rpc.data) })
+  }
+
+  return { hasMore: page.hasMore, items, limit, nextCursor: page.nextCursor }
+}
+
+export declare namespace getTransactions {
+  type Options = {
+    address?: z.output<typeof Schema.Address> | undefined
+    chainId: z.output<typeof Schema.ChainId>
+    /** Opaque keyset cursor anchoring the page; omit for the head page. */
+    cursor?: string | undefined
+    feePayer?: z.output<typeof Schema.Address> | undefined
+    feeToken?: z.output<typeof Schema.Address> | undefined
+    fromBlock?: number | undefined
+    fromTimestamp?: string | undefined
+    /**
+     * When true, the `recipient` filter also matches any inner account-abstraction
+     * call target (`calls[].to`), not just the root `to`. Off by default so read
+     * endpoints keep root-level recipient semantics.
+     */
+    includeCallRecipients?: boolean | undefined
+    limit: number
+    /** 1-indexed page number (positional pagination; exclusive with `cursor`). */
+    page?: number | undefined
+    order: 'asc' | 'desc'
+    recipient?: z.output<typeof Schema.Address> | undefined
+    sender?: z.output<typeof Schema.Address> | undefined
+    /**
+     * Filter to transactions whose receipt shows this execution status.
+     * Handled by {@link listTransactions} via the receipts-driven path; the raw
+     * `txs` scan ignores it (`txs` does not store execution status).
+     */
+    status?: 'reverted' | 'success' | undefined
+    toBlock?: number | undefined
+    toTimestamp?: string | undefined
+  }
+}
+
+/**
+ * Builds the non-cursor, non-address-scope `txs` filters shared by the page
+ * ({@link scanTransactions}) and the capped count ({@link countTransactions}),
+ * so the count always matches the page it annotates. The address scope is
+ * handled separately (it `UNION`s the two sides, as the page does).
+ */
+function countFilters(options: countTransactions.Options): string[] {
+  const filters: string[] = []
+  if (options.sender !== undefined) filters.push(`"from" = '${options.sender}'`)
+  if (options.recipient !== undefined) filters.push(`"to" = '${options.recipient}'`)
+  if (options.feePayer !== undefined) filters.push(`fee_payer = '${options.feePayer}'`)
+  if (options.feeToken !== undefined) filters.push(`fee_token = '${options.feeToken}'`)
+  if (options.fromBlock !== undefined) filters.push(`block_num >= ${options.fromBlock}`)
+  if (options.toBlock !== undefined) filters.push(`block_num <= ${options.toBlock}`)
+  if (options.fromTimestamp !== undefined)
+    filters.push(`block_timestamp >= '${options.fromTimestamp}'`)
+  if (options.toTimestamp !== undefined) filters.push(`block_timestamp <= '${options.toTimestamp}'`)
+  return filters
+}
+
+/**
+ * Capped total count of transactions matching the same filters as the page.
+ *
+ * A `status` filter is delegated to {@link Receipts.countReceipts}, mirroring
+ * the page's receipts-driven `status` path (execution status lives on receipts,
+ * not `txs`). The address scope reuses the page's `UNION` of the two sides —
+ * each side hits its own (`from`/`to`) index, and the deduped keyset count
+ * avoids double-counting self-transactions (`from = to`). `totalCountCapped: true` is a
+ * lower bound — at least {@link Schema.countCap} matches.
+ */
+export function countTransactions(
+  c: Context<App.Environment>,
+  options: countTransactions.Options,
+): Promise<z.output<typeof Schema.CountMeta>> {
+  // Status lives on receipts, so route the count through the same path the page
+  // uses: count receipts under the identical filters.
+  if (options.status !== undefined) return Receipts.countReceipts(c, options)
+
+  const { address, chainId } = options
+  const store = c.get('store')
+  const tidx = c.get('getTidx')(chainId)
+  return Timing.time(c, 'transactions_count', () =>
+    Store.memoize(
+      async () => {
+        const filters = countFilters(options)
+        let query: string
+        if (address !== undefined) {
+          const fromWhere = [`"from" = '${address}'`, ...filters].join(' AND ')
+          const toWhere = [`"to" = '${address}'`, ...filters].join(' AND ')
+          query = `
+            SELECT count(*) AS total
+            FROM (
+              (SELECT block_num, idx FROM txs WHERE ${fromWhere} LIMIT ${Schema.countCap})
+              UNION
+              (SELECT block_num, idx FROM txs WHERE ${toWhere} LIMIT ${Schema.countCap})
+            ) AS capped
+          `
+        } else {
+          const where = filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : ''
+          query = `
+            SELECT count(*) AS total
+            FROM (
+              SELECT 1 FROM txs ${where} LIMIT ${Schema.countCap}
+            ) AS capped
+          `
+        }
+        const result = await tidx.fetch({ chainId, query: query as string })
+        const totalCount = Value.toNumber(result.rows[0]?.['total']) ?? 0
+        return { totalCountCapped: totalCount >= Schema.countCap, totalCount }
+      },
+      {
+        key: `transactions-count:v1:${chainId}:${address ?? ''}:${options.sender ?? ''}:${options.recipient ?? ''}:${options.feePayer ?? ''}:${options.feeToken ?? ''}:${options.fromBlock ?? ''}:${options.toBlock ?? ''}:${options.fromTimestamp ?? ''}:${options.toTimestamp ?? ''}`,
+        store,
+        ttl: Ttl.seconds(15),
+      },
+    ),
+  )
+}
+
+export declare namespace countTransactions {
+  /** Filters for {@link countTransactions}: the page filters minus pagination. */
+  type Options = Pick<
+    getTransactions.Options,
+    | 'address'
+    | 'chainId'
+    | 'feePayer'
+    | 'feeToken'
+    | 'fromBlock'
+    | 'fromTimestamp'
+    | 'recipient'
+    | 'sender'
+    | 'status'
+    | 'toBlock'
+    | 'toTimestamp'
+  >
+}
+
+export declare namespace scanTransactions {
+  /** Dependencies for {@link scanTransactions}. */
+  type Deps = {
+    /** TIDX query client for the target chain. */
+    tidx: Tidx.Client
+  }
+  /** A humanized transaction row plus its `(block_num, idx)` cursor. */
+  type Item = {
+    /** Keyset position of the row. */
+    cursor: readonly [blockNumber: number, transactionIndex: number]
+    /** The humanized transaction (same shape the read endpoint returns). */
+    data: z.output<typeof schema.Transaction>
+  }
+  /** A page of scanned transactions. */
+  type Page = {
+    hasMore: boolean
+    items: readonly Item[]
+    limit: number
+    nextCursor: string | null
+  }
+}
+
+/**
+ * The `txs` columns {@link toRpcTransaction} reconstructs a transaction from.
+ * Shared by the list scan and the receipt-driven `status` path so the two
+ * queries cannot drift from the reconstruction.
+ */
+const transactionColumns = `block_num, block_timestamp, idx, hash, type, "from", "to", value, input,
+                   gas_limit, max_fee_per_gas, max_priority_fee_per_gas,
+                   nonce_key, nonce, fee_token, fee_payer, valid_before, valid_after`
+
+/**
+ * Re-encodes a TIDX `txs` row into the JSON-RPC transaction shape, which becomes
+ * the `rpc` payload that the list endpoint humanizes through the same path as
+ * the detail endpoint. Numeric columns become `0x` quantities; fields the
+ * indexer does not store (signatures, access list) are omitted, and `blockHash`
+ * is null since the schema requires it. The all-zero `nonce_key` that the
+ * indexer records for non-Tempo transactions is dropped to match the RPC
+ * response, which omits it.
+ */
+function toRpcTransaction(row: Record<string, unknown>) {
+  const timestamp = Value.toIsoDateTime(row['block_timestamp'])
+  const nonceKey = row['nonce_key']
+  return {
+    blockHash: null,
+    blockNumber: Value.toHex(row['block_num']) ?? null,
+    blockTimestamp: timestamp ? Value.toHex(Math.floor(Date.parse(timestamp) / 1000)) : undefined,
+    feeToken: typeof row['fee_token'] === 'string' ? row['fee_token'] : undefined,
+    from: row['from'],
+    gas: Value.toHex(row['gas_limit']),
+    hash: row['hash'],
+    input: typeof row['input'] === 'string' ? row['input'] : undefined,
+    maxFeePerGas: Value.toHex(row['max_fee_per_gas']),
+    maxPriorityFeePerGas: Value.toHex(row['max_priority_fee_per_gas']),
+    nonce: Value.toHex(row['nonce']),
+    nonceKey: typeof nonceKey === 'string' && !/^0x0+$/.test(nonceKey) ? nonceKey : undefined,
+    to: typeof row['to'] === 'string' ? row['to'] : undefined,
+    transactionIndex: Value.toHex(row['idx']) ?? null,
+    type: Value.toHex(row['type']),
+    validAfter: Value.toHex(row['valid_after']),
+    validBefore: Value.toHex(row['valid_before']),
+    value: Value.toHex(row['value']),
+  }
+}
+
+/** Humanizes one call within a Tempo account-abstraction transaction. */
+function humanizeCall(call: z.output<typeof schema.Call>): z.output<typeof schema.HumanCall> {
+  return {
+    data: call.input ?? call.data ?? undefined,
+    to: call.to ?? null,
+  }
+}
+
+/**
+ * Humanizes a JSON-RPC transaction: decodes `type`, converts hex quantities to
+ * decimal strings, hex block fields to numbers, and timestamps to ISO 8601,
+ * while preserving the verbatim payload under `rpc`. The same function serves
+ * the detail endpoint (RPC source) and the list endpoint (reconstructed from the
+ * indexer), so both expose an identical shape.
+ */
+export function humanizeTransaction(
+  rpc: z.output<typeof schema.Rpc.Transaction>,
+): z.output<typeof schema.Transaction> {
+  return {
+    blockHash: rpc.blockHash,
+    blockNumber: Value.hexToNumber(rpc.blockNumber) ?? null,
+    calls: rpc.calls?.map(humanizeCall),
+    chainId: Value.hexToNumber(rpc.chainId),
+    feeToken: rpc.feeToken ?? undefined,
+    gas: Value.hexToNumber(rpc.gas) ?? 0,
+    gasPrice: Value.fromHex(rpc.gasPrice),
+    hash: rpc.hash,
+    id: rpc.hash,
+    input: rpc.input,
+    maxFeePerGas: Value.fromHex(rpc.maxFeePerGas),
+    maxPriorityFeePerGas: Value.fromHex(rpc.maxPriorityFeePerGas),
+    meta: { rpc },
+    nonce: Value.hexToNumber(rpc.nonce) ?? 0,
+    nonceKey: rpc.nonceKey,
+    recipient: rpc.to ?? null,
+    sender: rpc.from,
+    timestamp: Value.hexSecondsToIso(rpc.blockTimestamp) ?? null,
+    transactionIndex: Value.hexToNumber(rpc.transactionIndex) ?? null,
+    type: decodeTransactionType(rpc.type),
+    validAfter: rpc.validAfter == null ? undefined : Value.hexSecondsToIso(rpc.validAfter),
+    validBefore: rpc.validBefore == null ? undefined : Value.hexSecondsToIso(rpc.validBefore),
+    value: Value.fromHex(rpc.value) ?? '0',
+  }
+}