tapimo 0.11.0 → 0.13.0

package/src/apps/data/routes/blocks.test.ts

@@ -10,6 +10,539 @@ import * as Viem from '../../../../test/Viem.js'
 import * as Blocks from './blocks.js'
 import * as Transactions from './transactions.js'
 
+describe('OpenAPI', () => {
+  test('publishes generator-ready block, transaction, and receipt contracts', async () => {
+    const app = TestApp.create({ auth: false })
+    const spec = await (await app.request('/openapi.json')).json()
+    const operations = {
+      block: spec.paths['/v1/blocks/{block}'].get,
+      blocks: spec.paths['/v1/blocks'].get,
+      receipt: spec.paths['/v1/transactions/{transactionHash}/receipt'].get,
+      receipts: spec.paths['/v1/transactions/receipts'].get,
+      transaction: spec.paths['/v1/transactions/{transactionHash}'].get,
+      transactions: spec.paths['/v1/transactions'].get,
+    }
+    const summarizeError = (
+      response: (typeof operations)[keyof typeof operations]['responses'][number],
+    ) => {
+      const schema = response.$ref ?? response.content?.['application/json']?.schema
+      if (!schema || typeof schema === 'string' || !('$ref' in schema)) return schema
+      const name = schema.$ref.split('/').at(-1)!
+      return {
+        codes: spec.components.schemas[name].properties.error.properties.code.enum,
+        schema,
+      }
+    }
+    const summarize = (operation: (typeof operations)[keyof typeof operations]) => ({
+      errors: Object.fromEntries(
+        [400, 401, 403, 404, 429, 500, 502]
+          .filter((status) => operation.responses[status])
+          .map((status) => [status, summarizeError(operation.responses[status])]),
+      ),
+      operationId: operation.operationId,
+      response: operation.responses[200].content['application/json'].schema,
+    })
+
+    expect({
+      components: [
+        'Block',
+        'BlockList',
+        'BlockMeta',
+        'BlockSummary',
+        'RpcBlock',
+        'RpcTransaction',
+        'RpcTransactionAccessListItem',
+        'RpcTransactionCall',
+        'RpcTransactionLog',
+        'RpcTransactionReceipt',
+        'RpcTransactionSignatureEnvelope',
+        'Transaction',
+        'TransactionCall',
+        'TransactionList',
+        'TransactionListMeta',
+        'TransactionMeta',
+        'TransactionReceipt',
+        'TransactionReceiptFeeAmount',
+        'TransactionReceiptList',
+        'TransactionReceiptListMeta',
+        'TransactionReceiptMeta',
+        'TransactionType',
+      ].filter((name) => spec.components.schemas[name]),
+      descriptions: {
+        signature: spec.components.schemas.RpcTransactionSignatureEnvelope.description,
+      },
+      formats: {
+        block: spec.components.schemas.Block.properties.timestamp.format,
+        blockSummary: spec.components.schemas.BlockSummary.properties.timestamp.format,
+        receipt: spec.components.schemas.TransactionReceipt.properties.timestamp.anyOf[0].format,
+        transaction: spec.components.schemas.Transaction.properties.timestamp.anyOf[0].format,
+        validAfter: spec.components.schemas.Transaction.properties.validAfter.anyOf[0].format,
+        validBefore: spec.components.schemas.Transaction.properties.validBefore.anyOf[0].format,
+      },
+      hiddenCompatibilityRoute: spec.paths['/chains/{chainId}/blocks/by-timestamp'],
+      models: {
+        blockList: spec.components.schemas.BlockList.properties.data.items,
+        blockMeta: spec.components.schemas.Block.properties.meta,
+        blockRpc: spec.components.schemas.BlockMeta.properties.rpc,
+        receiptFeeAmount: spec.components.schemas.TransactionReceipt.properties.feeAmount,
+        receiptList: spec.components.schemas.TransactionReceiptList.properties.data.items,
+        receiptListMeta: spec.components.schemas.TransactionReceiptList.properties.meta,
+        receiptLogs: spec.components.schemas.TransactionReceipt.properties.logs.items,
+        receiptMeta: spec.components.schemas.TransactionReceipt.properties.meta,
+        receiptRpc: spec.components.schemas.TransactionReceiptMeta.properties.rpc,
+        receiptType: spec.components.schemas.TransactionReceipt.properties.type,
+        rpcReceiptLogs: spec.components.schemas.RpcTransactionReceipt.properties.logs.items,
+        rpcTransactionAccessList:
+          spec.components.schemas.RpcTransaction.properties.accessList.items,
+        rpcTransactionCalls: spec.components.schemas.RpcTransaction.properties.calls.anyOf[0].items,
+        rpcTransactionFeePayerSignature:
+          spec.components.schemas.RpcTransaction.properties.feePayerSignature.anyOf[0],
+        rpcTransactionSignature: spec.components.schemas.RpcTransaction.properties.signature,
+        transactionCalls: spec.components.schemas.Transaction.properties.calls.items,
+        transactionList: spec.components.schemas.TransactionList.properties.data.items,
+        transactionListMeta: spec.components.schemas.TransactionList.properties.meta,
+        transactionMeta: spec.components.schemas.Transaction.properties.meta,
+        transactionReceipt: spec.components.schemas.TransactionMeta.properties.receipt,
+        transactionRpc: spec.components.schemas.TransactionMeta.properties.rpc,
+        transactionType: spec.components.schemas.Transaction.properties.type,
+      },
+      operations: Object.fromEntries(
+        Object.entries(operations).map(([name, operation]) => [name, summarize(operation)]),
+      ),
+    }).toMatchInlineSnapshot(`
+      {
+        "components": [
+          "Block",
+          "BlockList",
+          "BlockMeta",
+          "BlockSummary",
+          "RpcBlock",
+          "RpcTransaction",
+          "RpcTransactionAccessListItem",
+          "RpcTransactionCall",
+          "RpcTransactionLog",
+          "RpcTransactionReceipt",
+          "RpcTransactionSignatureEnvelope",
+          "Transaction",
+          "TransactionCall",
+          "TransactionList",
+          "TransactionListMeta",
+          "TransactionMeta",
+          "TransactionReceipt",
+          "TransactionReceiptFeeAmount",
+          "TransactionReceiptList",
+          "TransactionReceiptListMeta",
+          "TransactionReceiptMeta",
+          "TransactionType",
+        ],
+        "descriptions": {
+          "signature": "A signature envelope exactly as returned by JSON-RPC.",
+        },
+        "formats": {
+          "block": "date-time",
+          "blockSummary": "date-time",
+          "receipt": "date-time",
+          "transaction": "date-time",
+          "validAfter": "date-time",
+          "validBefore": "date-time",
+        },
+        "hiddenCompatibilityRoute": undefined,
+        "models": {
+          "blockList": {
+            "$ref": "#/components/schemas/BlockSummary",
+          },
+          "blockMeta": {
+            "$ref": "#/components/schemas/BlockMeta",
+          },
+          "blockRpc": {
+            "$ref": "#/components/schemas/RpcBlock",
+          },
+          "receiptFeeAmount": {
+            "$ref": "#/components/schemas/TransactionReceiptFeeAmount",
+          },
+          "receiptList": {
+            "$ref": "#/components/schemas/TransactionReceipt",
+          },
+          "receiptListMeta": {
+            "$ref": "#/components/schemas/TransactionReceiptListMeta",
+          },
+          "receiptLogs": {
+            "$ref": "#/components/schemas/RpcTransactionLog",
+          },
+          "receiptMeta": {
+            "$ref": "#/components/schemas/TransactionReceiptMeta",
+          },
+          "receiptRpc": {
+            "$ref": "#/components/schemas/RpcTransactionReceipt",
+          },
+          "receiptType": {
+            "$ref": "#/components/schemas/TransactionType",
+          },
+          "rpcReceiptLogs": {
+            "$ref": "#/components/schemas/RpcTransactionLog",
+          },
+          "rpcTransactionAccessList": {
+            "$ref": "#/components/schemas/RpcTransactionAccessListItem",
+          },
+          "rpcTransactionCalls": {
+            "$ref": "#/components/schemas/RpcTransactionCall",
+          },
+          "rpcTransactionFeePayerSignature": {
+            "$ref": "#/components/schemas/RpcTransactionSignatureEnvelope",
+          },
+          "rpcTransactionSignature": {
+            "$ref": "#/components/schemas/RpcTransactionSignatureEnvelope",
+          },
+          "transactionCalls": {
+            "$ref": "#/components/schemas/TransactionCall",
+          },
+          "transactionList": {
+            "$ref": "#/components/schemas/Transaction",
+          },
+          "transactionListMeta": {
+            "$ref": "#/components/schemas/TransactionListMeta",
+          },
+          "transactionMeta": {
+            "$ref": "#/components/schemas/TransactionMeta",
+          },
+          "transactionReceipt": {
+            "$ref": "#/components/schemas/TransactionReceipt",
+          },
+          "transactionRpc": {
+            "$ref": "#/components/schemas/RpcTransaction",
+          },
+          "transactionType": {
+            "$ref": "#/components/schemas/TransactionType",
+          },
+        },
+        "operations": {
+          "block": {
+            "errors": {
+              "400": {
+                "codes": [
+                  "api_key_malformed",
+                  "block_invalid",
+                  "chain_id_invalid",
+                  "chain_id_unsupported",
+                  "query_invalid",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/ApiKeyMalformedOrBlockInvalidOrChainIdInvalidOrChainIdUnsupportedOrQueryInvalidError",
+                },
+              },
+              "401": {
+                "codes": [
+                  "api_key_invalid",
+                  "api_key_missing",
+                  "unauthorized",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/AuthenticationError",
+                },
+              },
+              "403": {
+                "codes": [
+                  "api_key_forbidden",
+                  "api_key_ip_forbidden",
+                  "forbidden",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/ForbiddenError",
+                },
+              },
+              "404": {
+                "codes": [
+                  "block_not_found",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/BlockNotFoundError",
+                },
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "502": {
+                "codes": [
+                  "upstream_error",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/UpstreamError",
+                },
+              },
+            },
+            "operationId": "getBlock",
+            "response": {
+              "$ref": "#/components/schemas/Block",
+            },
+          },
+          "blocks": {
+            "errors": {
+              "400": {
+                "codes": [
+                  "api_key_malformed",
+                  "chain_id_invalid",
+                  "chain_id_unsupported",
+                  "query_invalid",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/ApiKeyMalformedOrChainIdInvalidOrChainIdUnsupportedOrQueryInvalidError",
+                },
+              },
+              "401": {
+                "codes": [
+                  "api_key_invalid",
+                  "api_key_missing",
+                  "unauthorized",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/AuthenticationError",
+                },
+              },
+              "403": {
+                "codes": [
+                  "api_key_forbidden",
+                  "api_key_ip_forbidden",
+                  "forbidden",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/ForbiddenError",
+                },
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "502": {
+                "codes": [
+                  "upstream_error",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/UpstreamError",
+                },
+              },
+            },
+            "operationId": "getBlocks",
+            "response": {
+              "$ref": "#/components/schemas/BlockList",
+            },
+          },
+          "receipt": {
+            "errors": {
+              "400": {
+                "codes": [
+                  "api_key_malformed",
+                  "chain_id_invalid",
+                  "chain_id_unsupported",
+                  "query_invalid",
+                  "transaction_invalid",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/ApiKeyMalformedOrChainIdInvalidOrChainIdUnsupportedOrQueryInvalidOrTransactionInvalidError",
+                },
+              },
+              "401": {
+                "codes": [
+                  "api_key_invalid",
+                  "api_key_missing",
+                  "unauthorized",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/AuthenticationError",
+                },
+              },
+              "403": {
+                "codes": [
+                  "api_key_forbidden",
+                  "api_key_ip_forbidden",
+                  "forbidden",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/ForbiddenError",
+                },
+              },
+              "404": {
+                "codes": [
+                  "receipt_not_found",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/ReceiptNotFoundError",
+                },
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "502": {
+                "codes": [
+                  "upstream_error",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/UpstreamError",
+                },
+              },
+            },
+            "operationId": "getReceipt",
+            "response": {
+              "$ref": "#/components/schemas/TransactionReceipt",
+            },
+          },
+          "receipts": {
+            "errors": {
+              "400": {
+                "codes": [
+                  "api_key_malformed",
+                  "chain_id_invalid",
+                  "chain_id_unsupported",
+                  "query_invalid",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/ApiKeyMalformedOrChainIdInvalidOrChainIdUnsupportedOrQueryInvalidError",
+                },
+              },
+              "401": {
+                "codes": [
+                  "api_key_invalid",
+                  "api_key_missing",
+                  "unauthorized",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/AuthenticationError",
+                },
+              },
+              "403": {
+                "codes": [
+                  "api_key_forbidden",
+                  "api_key_ip_forbidden",
+                  "forbidden",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/ForbiddenError",
+                },
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "502": {
+                "codes": [
+                  "upstream_error",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/UpstreamError",
+                },
+              },
+            },
+            "operationId": "getReceipts",
+            "response": {
+              "$ref": "#/components/schemas/TransactionReceiptList",
+            },
+          },
+          "transaction": {
+            "errors": {
+              "400": {
+                "codes": [
+                  "api_key_malformed",
+                  "chain_id_invalid",
+                  "chain_id_unsupported",
+                  "query_invalid",
+                  "transaction_invalid",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/ApiKeyMalformedOrChainIdInvalidOrChainIdUnsupportedOrQueryInvalidOrTransactionInvalidError",
+                },
+              },
+              "401": {
+                "codes": [
+                  "api_key_invalid",
+                  "api_key_missing",
+                  "unauthorized",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/AuthenticationError",
+                },
+              },
+              "403": {
+                "codes": [
+                  "api_key_forbidden",
+                  "api_key_ip_forbidden",
+                  "forbidden",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/ForbiddenError",
+                },
+              },
+              "404": {
+                "codes": [
+                  "transaction_not_found",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/TransactionNotFoundError",
+                },
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "502": {
+                "codes": [
+                  "upstream_error",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/UpstreamError",
+                },
+              },
+            },
+            "operationId": "getTransaction",
+            "response": {
+              "$ref": "#/components/schemas/Transaction",
+            },
+          },
+          "transactions": {
+            "errors": {
+              "400": {
+                "codes": [
+                  "api_key_malformed",
+                  "chain_id_invalid",
+                  "chain_id_unsupported",
+                  "query_invalid",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/ApiKeyMalformedOrChainIdInvalidOrChainIdUnsupportedOrQueryInvalidError",
+                },
+              },
+              "401": {
+                "codes": [
+                  "api_key_invalid",
+                  "api_key_missing",
+                  "unauthorized",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/AuthenticationError",
+                },
+              },
+              "403": {
+                "codes": [
+                  "api_key_forbidden",
+                  "api_key_ip_forbidden",
+                  "forbidden",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/ForbiddenError",
+                },
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "502": {
+                "codes": [
+                  "upstream_error",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/UpstreamError",
+                },
+              },
+            },
+            "operationId": "getTransactions",
+            "response": {
+              "$ref": "#/components/schemas/TransactionList",
+            },
+          },
+        },
+      }
+    `)
+  })
+})
+
 let recent: { number: bigint; hash: Hex.Hex } | undefined
 let recentNonEmpty: { number: bigint; hash: Hex.Hex } | undefined
 

package/src/apps/data/routes/blocks.ts

@@ -115,23 +115,28 @@ export namespace schema {
       .check(z.describe('The block exactly as returned by JSON-RPC.'))
   }
 
+  const rpcBlock = OpenApi.component(Rpc.Block, 'RpcBlock')
+
   /**
    * Metadata for a block: the verbatim JSON-RPC block (always present). Held in
    * a `meta` envelope so future opt-in `include` resources (e.g. embedded
    * transactions) can layer in without breaking the response shape.
    */
-  export const BlockMeta = Schema.describe(
-    z.object({
-      rpc: Rpc.Block.check(z.describe('The original JSON-RPC block payload.')),
-    }),
-    'Metadata for this block: the original JSON-RPC payload plus any future `include` resources.',
+  export const BlockMeta = OpenApi.component(
+    Schema.describe(
+      z.object({
+        rpc: rpcBlock.check(z.describe('The original JSON-RPC block payload.')),
+      }),
+      'Metadata for this block: the original JSON-RPC payload plus any future `include` resources.',
+    ),
+    'BlockMeta',
   )
 
   /**
    * A humanized block: decimal-string amounts, ISO 8601 timestamps, and plain
    * numbers for block fields. The verbatim JSON-RPC payload is always
-   * available under `meta.rpc`. Transactions are omitted from the response —
-   * clients fetch them via `GET /blocks/:block/transactions`.
+   * available under `meta.rpc`. Transactions are omitted from the response;
+   * clients filter `GET /v1/transactions` to this block number.
    */
   export const Block = z
     .object({
@@ -210,6 +215,8 @@ export namespace schema {
       ),
     )
 
+  const block = OpenApi.component(Block, 'Block')
+
   /**
    * A lightweight block row, returned by the `/blocks` list endpoint. Full
    * fields (parentHash, miner, gasUsed/gasLimit, …) would require one RPC
@@ -252,6 +259,8 @@ export namespace schema {
     })
     .check(z.describe('A lightweight block summary for list responses.'))
 
+  const blockSummary = OpenApi.component(BlockSummary, 'BlockSummary')
+
   /** Schemas for the getBlocks operation. */
   export namespace getBlocks {
     /** Query parameters for `GET /blocks`. */
@@ -266,12 +275,15 @@ export namespace schema {
       .check(...Schema.pageChecks(), z.describe('Query parameters for listing blocks.'))
 
     /** Page of lightweight block rows, including empty blocks. */
-    export const Response = z
-      .object({
-        data: z.array(BlockSummary).check(z.describe('Blocks on this page.')),
-        nextCursor: Schema.NextCursor,
-      })
-      .check(z.describe('A page of blocks ordered by block number.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z.array(blockSummary).check(z.describe('Blocks on this page.')),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of blocks ordered by block number.')),
+      'BlockList',
+    )
   }
 
   /** Schemas for the getBlock operation. */
@@ -311,7 +323,7 @@ export namespace schema {
       .check(z.describe('Query parameters for looking up a block.'))
 
     /** A humanized block, with the verbatim JSON-RPC payload under `meta.rpc`. */
-    export const Response = Block
+    export const Response = block
   }
 
   /**
@@ -392,7 +404,10 @@ export function blocks() {
         description: 'List the ordered batches of transactions that make up Tempo.',
         operationId: 'getBlocks',
         responses: OpenApi.responses({
-          errors: { 502: 'Could not read indexed block data from TIDX.' },
+          errors: {
+            400: { codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid'] },
+            502: 'Could not read indexed block data from TIDX.',
+          },
           success: { description: 'A page of block summaries.', schema: schema.getBlocks.Response },
         }),
         summary: 'List blocks',
@@ -420,7 +435,7 @@ export function blocks() {
           })
           return c.json(Response.validated(schema.getBlocks.Response, page), 200)
         } catch (cause) {
-          return Response.upstream(c, cause)
+          return Response.upstream(c, cause, { page: query.page })
         }
       },
     )
@@ -440,6 +455,9 @@ export function blocks() {
         operationId: 'getBlock',
         responses: OpenApi.responses({
           errors: {
+            400: {
+              codes: ['block_invalid', 'chain_id_invalid', 'chain_id_unsupported', 'query_invalid'],
+            },
             404: {
               description:
                 'No block matched the selector, or no indexed block exists at or after the timestamp.',
@@ -450,7 +468,7 @@ export function blocks() {
           success: {
             description:
               'A single block with number, timestamp, gas usage, producer, and original JSON-RPC data.',
-            schema: schema.Block,
+            schema: schema.getBlock.Response,
           },
         }),
         summary: 'Get a block by selector',
@@ -604,6 +622,7 @@ export function blocksByTimestampCompat() {
       operationId: 'getBlockByTimestamp',
       responses: OpenApi.responses({
         errors: {
+          400: { codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid'] },
           404: {
             description: 'No indexed block was found within the timestamp search window.',
             codes: ['block_not_found'],