tapimo 0.0.0 → 0.0.2

package/src/apps/receipts.ts

@@ -0,0 +1,1193 @@
+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 * as Timing from '../internal/Timing.js'
+import * as Ttl from '../internal/Ttl.js'
+import * as Value from '../internal/Value.js'
+import * as Tokens from './tokens.js'
+
+// Receipts and transactions deliberately form an import cycle (receipts reuses
+// the transaction-type decoder and fee-token embedder; transactions embeds
+// receipts). Neither module may touch the other's exports during module
+// evaluation: schema references across the cycle must stay inside `z.lazy`, and
+// function references are call-time only.
+import { decodeTransactionType, embedFeeTokens, schema as txSchema } from './transactions.js'
+
+/** Example transaction hash surfaced in OpenAPI docs. */
+const exampleHash = '0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665'
+
+// Tempo gas prices are denominated in attodollars (10^-18 USD) while fee-token
+// balances use 6 decimals (microdollars, 10^-6 USD), so the fee charged to the
+// fee payer — in the fee token's base units — is
+// `ceil(gasUsed * effectiveGasPrice / 10^12)` (ceiling division). Mirrors
+// `calc_gas_balance_spending` in tempoxyz/tempo.
+const feeScalingFactor = 10n ** 12n
+
+/**
+ * Computes the fee charged to the fee payer, in the fee token's base units, from
+ * the receipt's `gasUsed` and decimal `effectiveGasPrice`. Returns undefined
+ * when either input is missing.
+ */
+function computeFeeAmount(gasUsed: number | undefined, effectiveGasPrice: string | undefined) {
+  if (gasUsed === undefined || effectiveGasPrice === undefined) return undefined
+  const product = BigInt(gasUsed) * BigInt(effectiveGasPrice)
+  return ((product + feeScalingFactor - 1n) / feeScalingFactor).toString()
+}
+
+/** Zod schemas owned by the receipt handlers. */
+export namespace schema {
+  // TODO(ox/zod): replace with the zod schema for `ox`'s `Log.Rpc` once ox ships
+  // a `zod` entrypoint.
+  /** One event log emitted by a transaction (RPC format). */
+  export const Log = z
+    .looseObject({
+      address: Schema.Address.check(
+        z.describe('The contract address that emitted this event log.'),
+      ),
+      blockHash: z
+        .nullable(Schema.Hash)
+        .check(z.describe('The block hash once included, or `null` while pending.')),
+      blockNumber: z
+        .nullable(Schema.Quantity)
+        .check(z.describe('The block number once included, or `null` while pending.')),
+      blockTimestamp: z
+        .nullish(Schema.Quantity)
+        .check(z.describe('Tempo-provided block timestamp for this log.')),
+      data: Schema.Hex.check(
+        z.describe('ABI-encoded data for the event parameters that are not indexed.'),
+        z.meta({ examples: ['0xdeadbeef'] }),
+      ),
+      logIndex: z
+        .nullable(Schema.Quantity)
+        .check(z.describe('The log position within the block, or `null` while pending.')),
+      removed: z
+        .boolean()
+        .check(
+          z.describe(
+            'Whether this log was removed by a chain reorganization; Tempo finality means finalized logs do not reorg.',
+          ),
+          z.meta({ examples: [false] }),
+        ),
+      topics: z
+        .array(Schema.Hash)
+        .check(
+          z.describe(
+            'Indexed event topics, including the event signature hash as the first topic.',
+          ),
+        ),
+      transactionHash: z
+        .nullable(Schema.Hash)
+        .check(z.describe('The transaction hash for this log, or `null` while pending.')),
+      transactionIndex: z
+        .nullable(Schema.Quantity)
+        .check(z.describe('The transaction position within the block, or `null` while pending.')),
+    })
+    .check(z.describe('One event log emitted by a contract during transaction execution.'))
+
+  /** 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
+    // `TransactionReceipt.Rpc` once ox ships a `zod` entrypoint. `blockHash`,
+    // `logsBloom`, and `blockTimestamp` are nullish/optional so the receipt
+    // *list* (reconstructed from the indexer, which stores neither block hash nor
+    // bloom but does carry the block timestamp) reuses this same shape; the
+    // detail endpoint's verbatim RPC receipt populates all of them.
+    /** A JSON-RPC transaction receipt, passed through verbatim. */
+    export const Receipt = z
+      .looseObject({
+        blobGasPrice: z
+          .optional(Schema.Quantity)
+          .check(z.describe('Blob gas price for EIP-4844 blob data.')),
+        blobGasUsed: z
+          .optional(Schema.Quantity)
+          .check(z.describe('Blob gas used by EIP-4844 blob data.')),
+        blockHash: z
+          .nullable(Schema.Hash)
+          .check(
+            z.describe('The block hash, or `null` for receipts reconstructed from the index.'),
+          ),
+        blockNumber: Schema.Quantity.check(
+          z.describe('The block number that included this receipt.'),
+        ),
+        blockTimestamp: z
+          .nullish(Schema.Quantity)
+          .check(
+            z.describe(
+              'Block timestamp added when this receipt is reconstructed from indexed data.',
+            ),
+          ),
+        contractAddress: z
+          .nullish(Schema.Address)
+          .check(
+            z.describe(
+              'The created contract address, or `null` if the transaction did not create a contract.',
+            ),
+          ),
+        cumulativeGasUsed: Schema.Quantity.check(
+          z.describe('Total gas used in the block up to and including this transaction.'),
+        ),
+        effectiveGasPrice: Schema.Quantity.check(
+          z.describe('Effective gas price paid for this transaction.'),
+        ),
+        feePayer: z
+          .nullish(Schema.Address)
+          .check(z.describe('The address that paid the transaction fee.')),
+        feeToken: z
+          .nullish(Schema.Address)
+          .check(
+            z.describe(
+              'The token used to pay the fee; on Tempo this is a USD stablecoin such as `pathUSD`.',
+            ),
+          ),
+        from: Schema.Address.check(
+          z.describe('The address that sent or authorized the transaction.'),
+        ),
+        gasUsed: Schema.Quantity.check(z.describe('Gas actually used to execute the transaction.')),
+        logs: z
+          .array(Log)
+          .check(z.describe('Event logs emitted by contracts while this transaction executed.')),
+        logsBloom: z
+          .optional(Schema.Hex)
+          .check(
+            z.describe('Bloom filter summarizing the logs in this receipt.'),
+            z.meta({ examples: ['0x00'] }),
+          ),
+        root: z.optional(Schema.Hex).check(
+          z.describe('Post-transaction state root used by pre-Byzantium Ethereum receipts.'),
+          z.meta({
+            examples: ['0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665'],
+          }),
+        ),
+        status: Schema.Quantity.check(
+          z.describe(
+            'Execution status as a hex quantity: `0x1` means success and `0x0` means reverted.',
+          ),
+          z.meta({ examples: ['0x1'] }),
+        ),
+        to: z
+          .nullable(Schema.Address)
+          .check(
+            z.describe('The recipient address, or `null` when the transaction created a contract.'),
+          ),
+        transactionHash: Schema.Hash.check(
+          z.describe(
+            'A 32-byte hash, `0x`-prefixed and returned in lowercase, that identifies the transaction.',
+          ),
+        ),
+        transactionIndex: Schema.Quantity.check(
+          z.describe('The transaction position within its block.'),
+        ),
+        type: Schema.Hex.check(
+          z.describe('Raw transaction type byte, such as `0x2` for EIP-1559 or `0x76` for Tempo.'),
+          z.meta({ examples: ['0x2'] }),
+        ),
+      })
+      .check(z.describe('The transaction receipt exactly as returned by JSON-RPC.'))
+  }
+
+  /**
+   * Metadata for a receipt: the verbatim JSON-RPC receipt (always present) plus
+   * resources embedded on demand via `include`.
+   */
+  export const ReceiptMeta = z
+    .object({
+      feeToken: z
+        .optional(z.lazy(() => Tokens.schema.getToken.Response))
+        .check(z.describe('Fee-token details included only when you request `include=feeToken`.')),
+      rpc: Rpc.Receipt.check(z.describe('The original JSON-RPC receipt payload.')),
+    })
+    .check(
+      z.describe(
+        'Metadata for this receipt: the original JSON-RPC payload plus any requested `include` resources.',
+      ),
+    )
+
+  /**
+   * A humanized transaction receipt: decoded `status`/`type`, plain-number gas
+   * and block fields, and decimal-string fee/price values. The raw event logs
+   * are surfaced verbatim under `logs`, and the full JSON-RPC receipt under
+   * `meta.rpc`.
+   */
+  export const Receipt = z
+    .object({
+      blockHash: z
+        .nullable(Schema.Hash)
+        .check(
+          z.describe(
+            'The block hash, or `null` when the receipt was reconstructed from indexed data.',
+          ),
+        ),
+      blockNumber: z
+        .number()
+        .check(
+          z.int(),
+          z.nonnegative(),
+          z.describe('The block number that included this receipt.'),
+          z.meta({ examples: [23456789] }),
+        ),
+      contractAddress: z
+        .nullable(Schema.Address)
+        .check(
+          z.describe(
+            'The created contract address, or `null` if the transaction did not create a contract.',
+          ),
+        ),
+      cumulativeGasUsed: z
+        .number()
+        .check(
+          z.int(),
+          z.nonnegative(),
+          z.describe('Total gas used in the block up to and including this transaction.'),
+          z.meta({ examples: [21000] }),
+        ),
+      effectiveGasPrice: Schema.DecimalString.check(
+        z.describe('Effective gas price paid for this transaction, in attodollars per gas.'),
+      ),
+      feeAmount: Schema.DecimalString.check(
+        z.describe(
+          'Fee charged to the fee payer, as a decimal integer string in the fee token’s base units.',
+        ),
+      ),
+      feePayer: z
+        .optional(Schema.Address)
+        .check(z.describe('The address that paid the transaction fee.')),
+      feeToken: z
+        .optional(Schema.Address)
+        .check(
+          z.describe(
+            'The token used to pay the fee; on Tempo this is a USD stablecoin such as `pathUSD`.',
+          ),
+        ),
+      gasUsed: z
+        .number()
+        .check(
+          z.int(),
+          z.nonnegative(),
+          z.describe('Gas actually used to execute the transaction.'),
+          z.meta({ examples: [21000] }),
+        ),
+      id: Schema.Hash.check(
+        z.describe('Stable resource ID for this API response; it is the transaction hash.'),
+      ),
+      logs: z
+        .array(Log)
+        .check(
+          z.describe('Event logs emitted by this transaction, returned in JSON-RPC log format.'),
+        ),
+      meta: ReceiptMeta.check(
+        z.describe('The original JSON-RPC payload plus any resources requested with `include`.'),
+      ),
+      recipient: z
+        .nullable(Schema.Address)
+        .check(
+          z.describe('The recipient address, or `null` when the transaction created a contract.'),
+        ),
+      sender: Schema.Address.check(
+        z.describe('The address that sent or authorized the transaction.'),
+      ),
+      status: z
+        .enum(['success', 'reverted'])
+        .check(
+          z.describe('Whether the transaction succeeded or reverted.'),
+          z.meta({ examples: ['success'] }),
+        ),
+      timestamp: z
+        .nullable(z.iso.datetime())
+        .check(
+          z.describe('The block timestamp as ISO 8601, or `null` when it is unavailable.'),
+          z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+        ),
+      transactionHash: Schema.Hash.check(
+        z.describe(
+          'A 32-byte hash, `0x`-prefixed and returned in lowercase, that identifies the transaction.',
+        ),
+      ),
+      transactionIndex: z
+        .number()
+        .check(
+          z.int(),
+          z.nonnegative(),
+          z.describe('The transaction position within its block.'),
+          z.meta({ examples: [0] }),
+        ),
+      type: z.lazy(() => txSchema.TransactionType).check(z.meta({ examples: ['eip1559'] })),
+    })
+    .check(
+      z.describe(
+        'A transaction outcome formatted for API clients, with status, gas, fees, logs, and the original JSON-RPC receipt under `meta.rpc`.',
+      ),
+    )
+
+  /** Schemas for the getReceipt operation. */
+  export namespace getReceipt {
+    /** Path parameters for receipt requests. */
+    export const Params = z
+      .object({
+        transactionHash: Schema.Hash.check(
+          z.describe(
+            'A 32-byte hash, `0x`-prefixed and returned in lowercase, that identifies the transaction.',
+          ),
+          z.meta({ examples: [exampleHash] }),
+        ),
+      })
+      .check(z.describe('Path parameters used to look up a receipt by transaction hash.'))
+
+    /** Optional related resource that callers opt into via `include`. */
+    export const Include = z
+      .enum(['feeToken'])
+      .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) only run when
+     * explicitly requested, keeping the base receipt response fast.
+     */
+    export const includeQuery = Schema.includeQuery(
+      Include,
+      'Comma-separated related resources to include, such as `feeToken`.',
+    )
+
+    /** Query parameters for receipt requests. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        include: includeQuery,
+      })
+      .check(z.describe('Query parameters for looking up a receipt.'))
+
+    /** A humanized receipt, with the verbatim JSON-RPC payload under `meta.rpc`. */
+    export const Response = Receipt
+  }
+
+  /** Schemas for the getReceipts (list) operation. */
+  export namespace getReceipts {
+    /**
+     * Optional resources for the receipt list: the per-row `feeToken` embed
+     * plus the response-wide capped `totalCount`. The detail route keeps its
+     * own `feeToken`-only {@link getReceipt.Include}.
+     */
+    export const Include = z
+      .enum(['feeToken', 'totalCount'])
+      .check(
+        z.describe('Related resources to include in each receipt row or in response metadata.'),
+      )
+
+    /** Parses the comma-separated `include` value for the receipt list. */
+    export const includeQuery = Schema.includeQuery(
+      Include,
+      'Comma-separated related resources to include, such as `feeToken,totalCount`.',
+    )
+
+    /** Query parameters for receipt list requests. */
+    export const Query = z
+      .strictObject({
+        address: z
+          .optional(Schema.Address)
+          .check(
+            z.describe(
+              'Filter to receipts whose transaction has this address as sender or recipient.',
+            ),
+          ),
+        'blockNumber.from': Schema.blockNumberBound('receipts', 'from'),
+        'blockNumber.to': Schema.blockNumberBound('receipts', 'to'),
+        chainId: Schema.ChainIdQuery,
+        cursor: Schema.Cursor,
+        feePayer: z
+          .optional(Schema.Address)
+          .check(z.describe('Filter to receipts whose transaction fee was paid by this address.')),
+        feeToken: z
+          .optional(Schema.TokenAddress)
+          .check(
+            z.describe('Filter to receipts whose transaction 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 receipts for transactions sent to this recipient address.')),
+        sender: z
+          .optional(Schema.Address)
+          .check(z.describe('Filter to receipts for transactions sent by this sender address.')),
+        status: z
+          .optional(z.enum(['success', 'reverted']))
+          .check(
+            z.describe('Filter to receipts with this execution status.'),
+            z.meta({ examples: ['success'] }),
+          ),
+        'timestamp.from': Schema.timestampBound('receipts', 'from'),
+        'timestamp.to': Schema.timestampBound('receipts', 'to'),
+      })
+      .check(...Schema.pageChecks(), z.describe('Query parameters for listing receipts.'))
+
+    /**
+     * Page of receipts. Each item reuses the humanized receipt returned by
+     * `GET /transactions/:transactionHash/receipt`, so the list and detail endpoints expose one
+     * identical shape. Indexed list rows are reconstructed from the indexer,
+     * which stores neither the block hash nor the event logs, so those fields are
+     * `null`/empty in the list `meta.rpc` payload.
+     */
+    export const Response = z
+      .object({
+        data: z.array(getReceipt.Response).check(z.describe('Receipts 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 receipts ordered by block number and transaction position.'))
+  }
+}
+
+/** Creates receipt handlers. */
+export function receipts() {
+  return new Hono<App.Environment>()
+    .get(
+      '/receipts',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('query', schema.getReceipts.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'List transaction receipts across Tempo, with filters for addresses, blocks, timestamps, fees, and status.',
+        operationId: 'getReceipts',
+        responses: OpenApi.responses({
+          errors: { 502: 'Could not read indexed receipt data from TIDX.' },
+          success: {
+            description: 'A page of transaction receipts.',
+            schema: schema.getReceipts.Response,
+          },
+        }),
+        summary: 'List transaction receipts',
+        tags: ['Transactions'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.feed,
+        name: 'tempo-api:receipts:v1',
+        key: (c) => Cache.urlKey(c, schema.getReceipts.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')
+
+        // Cursor pages are anchored below the head and effectively immutable, so
+        // cache them longer; the head page 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')
+            ? countReceipts(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 receipts = await listReceipts(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.includes('feeToken') ? ['feeToken'] : [],
+            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.getReceipts.Response, {
+              ...receipts,
+              ...(meta ? { meta } : {}),
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/:transactionHash/receipt',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('param', schema.getReceipt.Params, {
+        code: 'transaction_invalid',
+        message: 'Invalid transaction hash',
+      }),
+      OpenApi.validate('query', schema.getReceipt.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description: 'Get the outcome of one transaction by its transaction hash.',
+        operationId: 'getReceipt',
+        responses: OpenApi.responses({
+          errors: {
+            404: {
+              description: 'No receipt was found for that transaction hash.',
+              codes: ['receipt_not_found'],
+            },
+            502: 'Could not read receipt data from the upstream JSON-RPC node.',
+          },
+          success: {
+            description: 'A single transaction receipt with status, gas, fees, and logs.',
+            schema: schema.getReceipt.Response,
+          },
+        }),
+        summary: 'Get a transaction receipt',
+        tags: ['Transactions'],
+      }),
+      Cache.response<App.Environment>({
+        // A receipt exists only once the transaction is mined: the lookup is
+        // either a 404 (unknown / not-yet-mined hash) or a final 200, never a
+        // pending 200. Default to no-store so the 404 isn't cached with a
+        // long-lived header (which would mask the receipt once mined); the handler
+        // unconditionally upgrades the 200 to `immutable` below.
+        cacheControl: Cache.policies.noStore,
+        name: 'tempo-api:receipts:v1',
+        key: (c) => Cache.urlKey(c, schema.getReceipt.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 receipt; a `null` result means the receipt is
+          // unknown or the tx is still pending. The verbatim payload is surfaced
+          // under `meta.rpc`, with humanized fields layered on top. Unmined
+          // lookups are deliberately never cached — confirmation polling must
+          // observe the receipt the moment the node has it.
+          const rpc = await Timing.time(c, 'transaction_receipt', () =>
+            client.request({ method: 'eth_getTransactionReceipt', params: [hash] }),
+          )
+          if (!rpc)
+            return Response.error(c, {
+              code: 'receipt_not_found',
+              message: 'Transaction receipt not found',
+              status: 404,
+            })
+
+          const data = humanizeReceipt(Response.validated(schema.Rpc.Receipt, rpc))
+
+          // A receipt is only returned once the transaction is mined, so it is
+          // immutable and can be cached aggressively.
+          Cache.setPolicy(c, Cache.policies.immutable)
+
+          // Fee-token metadata is opt-in: resolving it is an extra lookup, so it
+          // only runs when requested via `include=feeToken` and the receipt
+          // declares a fee token.
+          const feeToken = data.feeToken
+          if (!query.include.includes('feeToken') || feeToken === undefined)
+            return c.json(Response.validated(schema.getReceipt.Response, data), 200)
+
+          const token = await Timing.time(c, 'fee_token', () =>
+            Tokens.resolveToken(c, { address: feeToken, chainId }).catch(() => undefined),
+          )
+          return c.json(
+            Response.validated(
+              schema.getReceipt.Response,
+              token ? { ...data, meta: { ...data.meta, feeToken: token } } : data,
+            ),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+}
+
+/**
+ * Lists humanized receipts and embeds opt-in `include` resources (currently
+ * `feeToken`).
+ */
+export async function listReceipts(c: Context<App.Environment>, options: listReceipts.Options) {
+  const { include, ...rest } = options
+  const page = await getReceipts(c, rest)
+  const data = include.includes('feeToken')
+    ? await embedFeeTokens(c, page.data, rest.chainId)
+    : page.data
+  return { ...page, data }
+}
+
+export declare namespace listReceipts {
+  type Options = getReceipts.Options & {
+    /** Optional related resources to embed (e.g. `feeToken`). */
+    include: readonly z.output<typeof schema.getReceipt.Include>[]
+  }
+}
+
+export function getReceipts(c: Context<App.Environment>, options: getReceipts.Options) {
+  const {
+    address,
+    chainId,
+    feePayer,
+    feeToken,
+    fromBlock,
+    fromTimestamp,
+    limit,
+    order,
+    recipient,
+    sender,
+    status,
+    toBlock,
+    toTimestamp,
+  } = options
+  const store = c.get('store')
+  const tidx = c.get('getTidx')(chainId)
+  const sortDirection = order === 'asc' ? 'ASC' : 'DESC'
+  // Keyset pagination: anchor the page below the previous row's `(block, tx_idx)`
+  // position instead of a numeric offset, so rows arriving at the head can't
+  // shift items across pages. A malformed cursor 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
+
+  return Timing.time(c, 'receipts', () =>
+    Store.memoize(
+      async () => {
+        // Page the `receipts` table alone, then enrich each row with the
+        // `type`/`fee_token` it does not store via a follow-up `txs` lookup
+        // (the blocks-feed pattern). Paging straight off `receipts` avoids the
+        // `receipts JOIN txs` shape, which TIDX's planner cannot execute under
+        // address scope: a `UNION` of two JOINs (or the `(from = X OR to = X)`
+        // form) reliably returns `db error` (HTTP 422) for high-traffic
+        // addresses. Two index-friendly single-table queries plan cleanly.
+        //
+        // Build the shared filters once (everything except the address-scope
+        // predicate, which is special-cased below).
+        const filters: string[] = []
+        if (sender !== undefined) filters.push(`"from" = '${sender}'`)
+        if (recipient !== undefined) filters.push(`"to" = '${recipient}'`)
+        if (feePayer !== undefined) filters.push(`fee_payer = '${feePayer}'`)
+        // `fee_token` lives on `txs`, not `receipts`; filter via a subquery so
+        // the page query stays single-table.
+        if (feeToken !== undefined)
+          filters.push(`tx_hash IN (SELECT hash FROM txs WHERE 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 (status !== undefined) filters.push(`status = ${status === 'success' ? 1 : 0}`)
+        if (cursor !== undefined)
+          filters.push(
+            Cursor.keyset([
+              { literal: Cursor.literal(cursor[0]!, 'int'), name: 'block_num', order },
+              { literal: Cursor.literal(cursor[1]!, 'int'), name: 'tx_idx', order },
+            ]),
+          )
+
+        const columns = `block_num, block_timestamp, tx_idx, tx_hash, "from", "to",
+                   contract_address, gas_used, cumulative_gas_used, effective_gas_price,
+                   status, fee_payer`
+
+        // For address-scoped queries, run one branch per side and `UNION` so
+        // each branch returns at most `limit + 1` index-ordered rows, the outer
+        // query re-merges, and plain `UNION` dedupes the self-receipt case
+        // where `from = to = address`. The sort+limit live *inside* each branch
+        // so the merge stays bounded.
+        //
+        // The `receipts` table only indexes `from`, not `to` (a `to` scan over
+        // ~25M rows hits the indexer's statement timeout and returns `db error`,
+        // HTTP 422). The `from` branch filters `receipts` directly; the `to`
+        // branch resolves matching transaction hashes from `txs` (which indexes
+        // `to`) and looks them up by the indexed `receipts.tx_hash`.
+        const sideQuery = (side: 'from' | 'to', addr: string) => {
+          const predicate =
+            side === 'from'
+              ? `"from" = '${addr}'`
+              : `tx_hash IN (SELECT hash FROM txs WHERE "to" = '${addr}')`
+          const where = [predicate, ...filters].join(' AND ')
+          // In the offset lane each branch over-fetches 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.
+          return `(SELECT ${columns} FROM receipts WHERE ${where} ORDER BY block_num ${sortDirection}, tx_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}, tx_idx ${sortDirection}
+              LIMIT ${limit + 1}${skip}
+            `
+            : `
+              SELECT ${columns}
+              FROM receipts
+              ${filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : ''}
+              ORDER BY block_num ${sortDirection}, tx_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, tx_idx)`.
+        const page = Cursor.paginate({
+          rows: result.rows,
+          limit,
+          key: (row) => {
+            const block = Value.toNumber(row['block_num'])
+            const index = Value.toNumber(row['tx_idx'])
+            return block !== undefined && index !== undefined ? [block, index] : undefined
+          },
+        })
+
+        // Enrich the page with `type`/`fee_token` from `txs` in a single
+        // `IN (...)` lookup scoped to the page's transaction hashes. `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.
+        const hashes = [
+          ...new Set(
+            page.rows
+              .map((row) => row['tx_hash'])
+              .filter((hash): hash is string => typeof hash === 'string'),
+          ),
+        ]
+        const blocks = [
+          ...new Set(
+            page.rows
+              .map((row) => Value.toNumber(row['block_num']))
+              .filter((block): block is number => block !== undefined),
+          ),
+        ]
+        const txByHash = new Map<string, { feeToken: unknown; type: unknown }>()
+        if (hashes.length > 0 && blocks.length > 0) {
+          const txs = await tidx.fetch({
+            chainId,
+            query: `SELECT hash, type, fee_token FROM txs WHERE block_num IN (${blocks.join(
+              ', ',
+            )}) AND hash IN (${hashes.map((hash) => `'${hash}'`).join(', ')})` as string,
+          })
+          for (const row of txs.rows) {
+            const hash = row['hash']
+            if (typeof hash === 'string')
+              txByHash.set(hash, { feeToken: row['fee_token'], type: row['type'] })
+          }
+        }
+
+        // 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 data: z.output<typeof schema.Receipt>[] = []
+        for (const row of page.rows) {
+          const tx = typeof row['tx_hash'] === 'string' ? txByHash.get(row['tx_hash']) : undefined
+          const merged = { ...row, fee_token: tx?.feeToken, type: tx?.type }
+          const rpc = schema.Rpc.Receipt.safeParse(toRpcReceipt(merged))
+          if (rpc.success) data.push(humanizeReceipt(rpc.data))
+        }
+
+        return { data, nextCursor: page.nextCursor }
+      },
+      {
+        key: `receipts:v1:${chainId}:${order}:${address ?? ''}:${sender ?? ''}:${recipient ?? ''}:${feePayer ?? ''}:${feeToken ?? ''}:${fromBlock ?? ''}:${toBlock ?? ''}:${fromTimestamp ?? ''}:${toTimestamp ?? ''}:${status ?? ''}:${cursor ? `cursor:${cursor[0]}:${cursor[1]}` : offset !== undefined ? `page:${options.page}` : 'head'}:${limit}`,
+        store,
+        ttl: Ttl.seconds(15),
+      },
+    ),
+  )
+}
+
+export declare namespace getReceipts {
+  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
+    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
+    /** Only include receipts whose execution status matches. */
+    status?: 'reverted' | 'success' | undefined
+    toBlock?: number | undefined
+    toTimestamp?: string | undefined
+  }
+}
+
+/**
+ * Builds the non-cursor, non-address-scope filters shared by the receipt page
+ * ({@link getReceipts}) and the capped count ({@link countReceipts}), so the
+ * count always matches the page it annotates. The address scope is handled
+ * separately (its `UNION` workaround differs between page and count).
+ */
+function countFilters(options: countReceipts.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(`tx_hash IN (SELECT hash FROM txs WHERE 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}'`)
+  if (options.status !== undefined) filters.push(`status = ${options.status === 'success' ? 1 : 0}`)
+  return filters
+}
+
+/**
+ * Capped total count of receipts matching the same filters as the page. The
+ * address scope reuses the page's `UNION` workaround (`receipts` indexes `from`
+ * but not `to`, so the `to` side resolves hashes via the `txs` index), counting
+ * the deduped keyset so self-receipts (`from = to`) aren't double-counted.
+ * `totalCountCapped: true` is a lower bound — at least {@link Schema.countCap} matches.
+ */
+export function countReceipts(
+  c: Context<App.Environment>,
+  options: countReceipts.Options,
+): Promise<z.output<typeof Schema.CountMeta>> {
+  const { address, chainId } = options
+  const store = c.get('store')
+  const tidx = c.get('getTidx')(chainId)
+  return Timing.time(c, 'receipts_count', () =>
+    Store.memoize(
+      async () => {
+        const filters = countFilters(options)
+        let query: string
+        if (address !== undefined) {
+          const fromWhere = [`"from" = '${address}'`, ...filters].join(' AND ')
+          const toWhere = [
+            `tx_hash IN (SELECT hash FROM txs WHERE "to" = '${address}')`,
+            ...filters,
+          ].join(' AND ')
+          query = `
+            SELECT count(*) AS total
+            FROM (
+              (SELECT block_num, tx_idx FROM receipts WHERE ${fromWhere} LIMIT ${Schema.countCap})
+              UNION
+              (SELECT block_num, tx_idx FROM receipts 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 receipts ${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: `receipts-count:v1:${chainId}:${address ?? ''}:${options.sender ?? ''}:${options.recipient ?? ''}:${options.feePayer ?? ''}:${options.feeToken ?? ''}:${options.fromBlock ?? ''}:${options.toBlock ?? ''}:${options.fromTimestamp ?? ''}:${options.toTimestamp ?? ''}:${options.status ?? ''}`,
+        store,
+        ttl: Ttl.seconds(15),
+      },
+    ),
+  )
+}
+
+export declare namespace countReceipts {
+  /** Filters for {@link countReceipts}: the page filters minus pagination. */
+  type Options = Pick<
+    getReceipts.Options,
+    | 'address'
+    | 'chainId'
+    | 'feePayer'
+    | 'feeToken'
+    | 'fromBlock'
+    | 'fromTimestamp'
+    | 'recipient'
+    | 'sender'
+    | 'status'
+    | 'toBlock'
+    | 'toTimestamp'
+  >
+}
+
+/**
+ * Resolves humanized receipts — including their event logs — for a page of
+ * transactions, keyed by lowercased transaction hash. Rows without a receipt
+ * (pending, or not yet indexed) are simply absent from the map.
+ *
+ * Receipt rows come from the indexed `receipts` table (skipped when the caller
+ * already paged receipts via the `status` path) and event logs from the raw
+ * `logs` table, both fetched once for the whole page. No `Store.memoize` here:
+ * the route-level response cache (`Cache.response`) already absorbs repeated
+ * requests for the same page.
+ */
+export async function embedReceipts(
+  c: Context<App.Environment>,
+  options: embedReceipts.Options,
+): Promise<Map<string, z.output<typeof schema.Receipt>>> {
+  const { chainId, rows } = options
+  const found = new Map<string, z.output<typeof schema.Receipt>>()
+
+  // Only mined rows can have a receipt; their block numbers also feed the
+  // block bound the `logs` lookup requires.
+  const blocks: number[] = []
+  const hashes = new Set<string>()
+  for (const row of rows) {
+    if (row.blockNumber === null) continue
+    blocks.push(row.blockNumber)
+    hashes.add(row.hash.toLowerCase())
+  }
+  if (hashes.size === 0) return found
+
+  const tidx = c.get('getTidx')(chainId)
+  const inList = [...hashes].map((hash) => `'${hash}'`).join(', ')
+
+  // Raw-table queries (no signature-decoded CTE), so the inline SQL is cast to
+  // `string`. The receipts lookup needs no block bound (`receipts.tx_hash` is
+  // indexed — see the `sideQuery` comment in `getReceipts`); the logs lookup
+  // REQUIRES one: `logs` is sorted by block position, so a bare `tx_hash IN`
+  // scans to genesis (see `blockBound` in `transfers.ts`).
+  const [receipts_result, logs_result] = await Timing.time(c, 'receipts_embed', () =>
+    Promise.all([
+      options.receipts
+        ? undefined
+        : tidx.fetch({
+            chainId,
+            query:
+              `SELECT block_num, block_timestamp, tx_idx, tx_hash, "from", "to", contract_address, gas_used, cumulative_gas_used, effective_gas_price, status, fee_payer FROM receipts WHERE tx_hash IN (${inList})` as string,
+          }),
+      tidx.fetch({
+        chainId,
+        query:
+          `SELECT tx_hash, block_num, tx_idx, log_idx, address, selector, topic1, topic2, topic3, data, block_timestamp FROM logs WHERE block_num BETWEEN ${Math.min(...blocks)} AND ${Math.max(...blocks)} AND tx_hash IN (${inList}) ORDER BY block_num ASC, log_idx ASC` as string,
+      }),
+    ]),
+  )
+
+  // Reconstruct each raw `logs` row into the RPC log shape `schema.Log`
+  // consumes (the postgres `logs` table names `topic0` `selector`), grouped by
+  // transaction hash. Logs that fail to reconstruct are skipped.
+  const logsByHash = new Map<string, z.output<typeof schema.Log>[]>()
+  for (const row of logs_result.rows) {
+    const hash = Value.toText(row['tx_hash'])?.toLowerCase()
+    if (!hash) continue
+    const timestamp = Value.toIsoDateTime(row['block_timestamp'])
+    const log = schema.Log.safeParse({
+      address: row['address'],
+      blockHash: null,
+      blockNumber: Value.toHex(row['block_num']),
+      blockTimestamp: timestamp ? Value.toHex(Math.floor(Date.parse(timestamp) / 1000)) : undefined,
+      data: Value.toText(row['data']) ?? '0x',
+      logIndex: Value.toHex(row['log_idx']),
+      removed: false,
+      topics: [row['selector'], row['topic1'], row['topic2'], row['topic3']].filter(
+        (topic): topic is string => typeof topic === 'string' && topic.length > 0,
+      ),
+      transactionHash: hash,
+      transactionIndex: Value.toHex(row['tx_idx']),
+    })
+    if (!log.success) continue
+    const logs = logsByHash.get(hash)
+    if (logs) logs.push(log.data)
+    else logsByHash.set(hash, [log.data])
+  }
+
+  // Status path: the caller already paged humanized receipts, which the
+  // receipts list reconstructs without logs — rebuild each with the page's
+  // logs attached (both on the row and inside its `meta.rpc` payload).
+  if (options.receipts) {
+    for (const receipt of options.receipts) {
+      const hash = receipt.transactionHash.toLowerCase()
+      const logs = logsByHash.get(hash) ?? []
+      found.set(hash, {
+        ...receipt,
+        logs,
+        meta: { ...receipt.meta, rpc: { ...receipt.meta.rpc, logs } },
+      })
+    }
+    return found
+  }
+
+  const receiptRowByHash = new Map<string, Record<string, unknown>>()
+  for (const row of receipts_result?.rows ?? []) {
+    const hash = Value.toText(row['tx_hash'])?.toLowerCase()
+    if (hash) receiptRowByHash.set(hash, row)
+  }
+
+  // Per transaction row, merge in the `type`/`fee_token` the `receipts` table
+  // does not store from the transaction row itself (saving the `txs` follow-up
+  // lookup the receipts list needs), inject the reconstructed logs, and
+  // humanize through the same path as the receipt endpoints.
+  for (const row of rows) {
+    const hash = row.hash.toLowerCase()
+    const receipt = receiptRowByHash.get(hash)
+    if (!receipt) continue
+    const merged = {
+      ...receipt,
+      fee_token: row.feeToken,
+      // `toRpcReceipt` hex-encodes numeric columns; decode the row's raw hex
+      // `type` byte so it round-trips through the same path.
+      type: Value.hexToNumber(row.meta.rpc.type),
+    }
+    const rpc = schema.Rpc.Receipt.safeParse({
+      ...toRpcReceipt(merged),
+      logs: logsByHash.get(hash) ?? [],
+    })
+    if (rpc.success) found.set(hash, humanizeReceipt(rpc.data))
+  }
+  return found
+}
+
+export declare namespace embedReceipts {
+  /** Options for {@link embedReceipts}. */
+  type Options = {
+    /** Target chain id. */
+    chainId: z.output<typeof Schema.ChainId>
+    /**
+     * Pre-fetched humanized receipts for the page (the `status`-filtered
+     * transactions path). When provided, the receipts query is skipped and only
+     * the page's event logs are fetched and reattached.
+     */
+    receipts?: readonly z.output<typeof schema.Receipt>[] | undefined
+    /**
+     * The page's humanized transaction rows. Typed structurally (rather than as
+     * the transactions schema output) so this module never touches the
+     * transaction schemas eagerly across the import cycle.
+     */
+    rows: readonly {
+      /** Block number, or null if pending (pending rows have no receipt). */
+      blockNumber: number | null
+      /** Fee-token preference declared on the transaction. */
+      feeToken?: Hex.Hex | undefined
+      /** Transaction hash. */
+      hash: string
+      /** Verbatim RPC payload carrying the raw `type` byte. */
+      meta: { rpc: { type: Hex.Hex } }
+    }[]
+  }
+}
+
+/**
+ * Humanizes a JSON-RPC transaction receipt: decodes `status`/`type`, converts
+ * hex quantities to decimal strings and block fields to numbers, and derives the
+ * block `timestamp` from the top-level `blockTimestamp` (present when
+ * reconstructed from the index) or the (shared) per-log timestamp — `null` when
+ * neither is available. The verbatim payload is preserved under `meta.rpc` and
+ * the raw logs under `logs`. Shared by the receipt detail (RPC source) and list
+ * (reconstructed from the indexer) endpoints, so both expose an identical shape.
+ */
+export function humanizeReceipt(
+  rpc: z.output<typeof schema.Rpc.Receipt>,
+): z.output<typeof schema.Receipt> {
+  const gasUsed = Value.hexToNumber(rpc.gasUsed) ?? 0
+  const effectiveGasPrice = Value.fromHex(rpc.effectiveGasPrice) ?? '0'
+  return {
+    blockHash: rpc.blockHash,
+    blockNumber: Value.hexToNumber(rpc.blockNumber) ?? 0,
+    contractAddress: rpc.contractAddress ?? null,
+    cumulativeGasUsed: Value.hexToNumber(rpc.cumulativeGasUsed) ?? 0,
+    effectiveGasPrice,
+    feeAmount: computeFeeAmount(gasUsed, effectiveGasPrice) ?? '0',
+    feePayer: rpc.feePayer ?? undefined,
+    feeToken: rpc.feeToken ?? undefined,
+    gasUsed,
+    id: rpc.transactionHash,
+    logs: rpc.logs,
+    meta: { rpc },
+    recipient: rpc.to,
+    sender: rpc.from,
+    status: Value.hexToNumber(rpc.status) === 1 ? 'success' : 'reverted',
+    timestamp: Value.hexSecondsToIso(rpc.blockTimestamp ?? rpc.logs[0]?.blockTimestamp) ?? null,
+    transactionHash: rpc.transactionHash,
+    transactionIndex: Value.hexToNumber(rpc.transactionIndex) ?? 0,
+    type: decodeTransactionType(rpc.type),
+  }
+}
+
+/**
+ * Re-encodes a TIDX `receipts` row (joined to `txs`) into the JSON-RPC receipt
+ * shape, which becomes the `rpc` payload the list endpoint humanizes through the
+ * same path as the detail endpoint. Numeric columns become `0x` quantities;
+ * fields the indexer does not store — the block hash, logs bloom, and event logs
+ * — are null/empty since the `receipts` table records neither.
+ */
+export function toRpcReceipt(row: Record<string, unknown>) {
+  const timestamp = Value.toIsoDateTime(row['block_timestamp'])
+  return {
+    blockHash: null,
+    blockNumber: Value.toHex(row['block_num']),
+    blockTimestamp: timestamp ? Value.toHex(Math.floor(Date.parse(timestamp) / 1000)) : undefined,
+    contractAddress: typeof row['contract_address'] === 'string' ? row['contract_address'] : null,
+    cumulativeGasUsed: Value.toHex(row['cumulative_gas_used']),
+    effectiveGasPrice: Value.toHex(row['effective_gas_price']),
+    feePayer: typeof row['fee_payer'] === 'string' ? row['fee_payer'] : undefined,
+    feeToken: typeof row['fee_token'] === 'string' ? row['fee_token'] : undefined,
+    from: row['from'],
+    gasUsed: Value.toHex(row['gas_used']),
+    logs: [],
+    status: Value.toHex(row['status']),
+    to: typeof row['to'] === 'string' ? row['to'] : null,
+    transactionHash: row['tx_hash'],
+    transactionIndex: Value.toHex(row['tx_idx']),
+    type: Value.toHex(row['type']),
+  }
+}