tapimo 0.12.0 → 0.13.0

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

@@ -70,6 +70,8 @@ export namespace schema {
       z.describe('One EIP-2930 access-list entry that predeclares an account and storage slots.'),
     )
 
+  const rpcAccessListItem = OpenApi.component(AccessListItem, 'RpcTransactionAccessListItem')
+
   // 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). */
@@ -100,6 +102,8 @@ export namespace schema {
     })
     .check(z.describe('One operation inside a Tempo account-abstraction transaction.'))
 
+  const rpcCall = OpenApi.component(Call, 'RpcTransactionCall')
+
   // 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.
@@ -122,6 +126,11 @@ export namespace schema {
     })
     .check(z.describe('The signature envelope exactly as returned by JSON-RPC.'))
 
+  const rpcSignatureEnvelope = OpenApi.component(
+    SignatureEnvelope,
+    'RpcTransactionSignatureEnvelope',
+  )
+
   /** 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
@@ -135,7 +144,7 @@ export namespace schema {
             z.describe('Tempo account-abstraction authorizations attached to the transaction.'),
           ),
         accessList: z
-          .optional(z.array(AccessListItem))
+          .optional(z.array(rpcAccessListItem))
           .check(
             z.describe(
               'EIP-2930 access list that predeclares accounts and storage slots for the transaction.',
@@ -165,7 +174,7 @@ export namespace schema {
         calls: z
           .optional(
             z.union([
-              z.array(Call).check(
+              z.array(rpcCall).check(
                 z.meta({
                   examples: [[{ data: '0xdeadbeef', input: '0xdeadbeef', to: null, value: '0x0' }]],
                 }),
@@ -193,9 +202,9 @@ export namespace schema {
             z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] }),
           ),
         feePayerSignature: z
-          .nullish(SignatureEnvelope)
+          .nullish(rpcSignatureEnvelope)
           .check(
-            z.describe('Signature from the account that paid the transaction fee.'),
+            z.describe('A signature envelope exactly as returned by JSON-RPC.'),
             z.meta({ examples: [{ type: 'secp256k1' }] }),
           ),
         feeToken: z
@@ -255,8 +264,8 @@ export namespace schema {
           .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.')),
+          .optional(rpcSignatureEnvelope)
+          .check(z.describe('A signature envelope exactly as returned by JSON-RPC.')),
         to: z
           .nullish(Schema.Address)
           .check(
@@ -294,15 +303,17 @@ export namespace schema {
       .check(z.describe('The transaction exactly as returned by JSON-RPC.'))
   }
 
+  const rpcTransaction = OpenApi.component(Rpc.Transaction, 'RpcTransaction')
+
   /** Transaction metadata with the raw RPC transaction and optional receipt. */
   export const TransactionMeta = z
     .object({
       receipt: z
-        .optional(z.lazy(() => Receipts.schema.Receipt))
+        .optional(z.lazy(() => Receipts.schema.TransactionReceipt))
         .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.')),
+      rpc: rpcTransaction.check(z.describe('The original JSON-RPC transaction payload.')),
     })
     .check(
       z.describe(
@@ -310,13 +321,18 @@ export namespace schema {
       ),
     )
 
+  const transactionMeta = OpenApi.component(TransactionMeta, 'TransactionMeta')
+
   /** 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'] }),
-    )
+  export const TransactionType = OpenApi.component(
+    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'] }),
+      ),
+    'TransactionType',
+  )
 
   /** One humanized call within a Tempo account-abstraction transaction. */
   export const HumanCall = z
@@ -333,6 +349,8 @@ export namespace schema {
     })
     .check(z.describe('One decoded call inside a Tempo account-abstraction transaction.'))
 
+  const transactionCall = OpenApi.component(HumanCall, 'TransactionCall')
+
   /**
    * A humanized transaction: decoded `type`, decimal-string amounts, ISO 8601
    * timestamps, and plain-number block fields. The verbatim JSON-RPC transaction
@@ -352,7 +370,7 @@ export namespace schema {
           z.meta({ examples: [23456789] }),
         ),
       calls: z
-        .optional(z.array(HumanCall))
+        .optional(z.array(transactionCall))
         .check(
           z.describe('Decoded calls for Tempo account-abstraction transactions.'),
           z.meta({ examples: [[{ data: '0xdeadbeef', to: null }]] }),
@@ -405,7 +423,7 @@ export namespace schema {
       maxPriorityFeePerGas: z
         .optional(Schema.DecimalString)
         .check(z.describe('Maximum priority fee per gas for EIP-1559-style transactions.')),
-      meta: TransactionMeta.check(
+      meta: transactionMeta.check(
         z.describe('The original JSON-RPC payload plus any resources requested with `include`.'),
       ),
       nonce: z
@@ -467,6 +485,8 @@ export namespace schema {
       ),
     )
 
+  const transaction = OpenApi.component(Transaction, 'Transaction')
+
   /** Schemas for the getTransaction operation. */
   export namespace getTransaction {
     /** Path parameters for transaction requests. */
@@ -505,7 +525,7 @@ export namespace schema {
       .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
+    export const Response = transaction
   }
 
   /** Schemas for the getTransactions (list) operation. */
@@ -567,23 +587,31 @@ export namespace schema {
       })
       .check(...Schema.pageChecks(), z.describe('Query parameters for listing transactions.'))
 
+    /** Response metadata requested through `include`, such as capped counts. */
+    export const Meta = OpenApi.component(Schema.CountMeta, 'TransactionListMeta')
+
     /**
      * 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.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z.array(getTransaction.Response).check(z.describe('Transactions on this page.')),
+          meta: z
+            .optional(Meta)
+            .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.'),
+        ),
+      'TransactionList',
+    )
   }
 }
 /** Creates transaction handlers. */
@@ -601,7 +629,10 @@ export function transactions() {
           'List transactions across Tempo, with filters for addresses, blocks, timestamps, fees, and status.',
         operationId: 'getTransactions',
         responses: OpenApi.responses({
-          errors: { 502: 'Could not read transaction or token data from an upstream service.' },
+          errors: {
+            400: { codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid'] },
+            502: 'Could not read transaction or token data from an upstream service.',
+          },
           success: {
             description: 'A page of transactions.',
             schema: schema.getTransactions.Response,
@@ -707,6 +738,14 @@ export function transactions() {
         operationId: 'getTransaction',
         responses: OpenApi.responses({
           errors: {
+            400: {
+              codes: [
+                'chain_id_invalid',
+                'chain_id_unsupported',
+                'query_invalid',
+                'transaction_invalid',
+              ],
+            },
             404: {
               description: 'No transaction was found for that hash.',
               codes: ['transaction_not_found'],

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

@@ -21,6 +21,427 @@ const fixed = FxOracle.from({
   }),
 })
 
+describe('OpenAPI', () => {
+  test('publishes generator-ready transfer, activity, and valuation contracts', async () => {
+    const app = TestApp.create({ auth: false })
+    const spec = await (await app.request('/openapi.json')).json()
+    const operations = {
+      addressActivities: spec.paths['/v1/addresses/{address}/activities'].get,
+      addressValuation: spec.paths['/v1/addresses/{address}/valuation'].get,
+      transactionActivities: spec.paths['/v1/transactions/{transactionHash}/activities'].get,
+      transfers: spec.paths['/v1/transfers'].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, 409, 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,
+    })
+    type ActivityVariant = { $ref?: string }
+    const activityVariants = spec.components.schemas.ActivityItem.anyOf as ActivityVariant[]
+    const firstActivityVariant = activityVariants[0]!.$ref!.split('/').at(-1)!
+
+    expect({
+      components: [
+        'ActivityEntry',
+        'ActivityEvent',
+        'ActivityGroup',
+        'ActivityItem',
+        'ActivityMeta',
+        'ActivityToken',
+        'ActivityTransfer',
+        'ActivityValuedAmount',
+        'AddressActivityList',
+        'AddressValuation',
+        'TokenTransfer',
+        'TokenTransferList',
+        'TokenTransferListMeta',
+        'TokenTransferToken',
+        'TransactionActivityList',
+        'ValuationPricing',
+        'ValuationValue',
+        'ValuedTokenAmount',
+      ].filter((name) => spec.components.schemas[name]),
+      descriptions: {
+        activityValuedAmount: spec.components.schemas.ActivityValuedAmount.description,
+        valuedTokenAmount: spec.components.schemas.ValuedTokenAmount.description,
+      },
+      formats: {
+        activityTransfer: spec.components.schemas.ActivityTransfer.properties.timestamp.format,
+        pricing: spec.components.schemas.ValuationPricing.properties.asOf.format,
+        transfer: spec.components.schemas.TokenTransfer.properties.timestamp.format,
+      },
+      models: {
+        activityEntry: spec.components.schemas.ActivityEntry.anyOf,
+        activityGroupItems:
+          spec.components.schemas.ActivityGroup.properties.data.properties.items.items,
+        activityItemEvents: spec.components.schemas[firstActivityVariant].properties.events.items,
+        activityItemVariants: {
+          count: activityVariants.length,
+          first: activityVariants[0],
+          last: activityVariants.at(-1),
+          referenced: activityVariants.every((variant) => variant.$ref),
+          stableName:
+            spec.components.schemas.ActivityItemSharesRedemptionRequested.properties.type.const,
+        },
+        activityList: spec.components.schemas.AddressActivityList.properties.data.items,
+        activityListMeta: spec.components.schemas.AddressActivityList.properties.meta,
+        activityTransferSourceAmount:
+          spec.components.schemas.ActivityTransfer.properties.sourceAmount,
+        activityTransferSourceToken:
+          spec.components.schemas.ActivityTransfer.properties.sourceToken,
+        transactionActivityList:
+          spec.components.schemas.TransactionActivityList.properties.data.items,
+        transferDestinationAmount:
+          spec.components.schemas.TokenTransfer.properties.destinationAmount,
+        transferDestinationToken: spec.components.schemas.TokenTransfer.properties.destinationToken,
+        transferList: spec.components.schemas.TokenTransferList.properties.data.items,
+        transferListMeta: spec.components.schemas.TokenTransferList.properties.meta,
+        transferSourceAmount: spec.components.schemas.TokenTransfer.properties.sourceAmount,
+        transferSourceToken: spec.components.schemas.TokenTransfer.properties.sourceToken,
+        valuationPricing: spec.components.schemas.AddressValuation.properties.pricing,
+      },
+      operations: Object.fromEntries(
+        Object.entries(operations).map(([name, operation]) => [name, summarize(operation)]),
+      ),
+    }).toMatchInlineSnapshot(`
+      {
+        "components": [
+          "ActivityEntry",
+          "ActivityEvent",
+          "ActivityGroup",
+          "ActivityItem",
+          "ActivityMeta",
+          "ActivityToken",
+          "ActivityTransfer",
+          "ActivityValuedAmount",
+          "AddressActivityList",
+          "AddressValuation",
+          "TokenTransfer",
+          "TokenTransferList",
+          "TokenTransferListMeta",
+          "TokenTransferToken",
+          "TransactionActivityList",
+          "ValuationPricing",
+          "ValuationValue",
+          "ValuedTokenAmount",
+        ],
+        "descriptions": {
+          "activityValuedAmount": "A token amount carrying its nominal value in the requested denomination.",
+          "valuedTokenAmount": "A token amount carrying its nominal value in the requested denomination.",
+        },
+        "formats": {
+          "activityTransfer": "date-time",
+          "pricing": "date-time",
+          "transfer": "date-time",
+        },
+        "models": {
+          "activityEntry": [
+            {
+              "$ref": "#/components/schemas/ActivityItem",
+            },
+            {
+              "$ref": "#/components/schemas/ActivityGroup",
+            },
+          ],
+          "activityGroupItems": {
+            "$ref": "#/components/schemas/ActivityItem",
+          },
+          "activityItemEvents": {
+            "$ref": "#/components/schemas/ActivityEvent",
+          },
+          "activityItemVariants": {
+            "count": 65,
+            "first": {
+              "$ref": "#/components/schemas/ActivityItemAssetsDeposited",
+            },
+            "last": {
+              "$ref": "#/components/schemas/ActivityItemUnknown",
+            },
+            "referenced": true,
+            "stableName": "shares-redemption-requested",
+          },
+          "activityList": {
+            "$ref": "#/components/schemas/ActivityEntry",
+          },
+          "activityListMeta": {
+            "$ref": "#/components/schemas/ActivityMeta",
+          },
+          "activityTransferSourceAmount": {
+            "$ref": "#/components/schemas/ActivityValuedAmount",
+          },
+          "activityTransferSourceToken": {
+            "$ref": "#/components/schemas/ActivityToken",
+          },
+          "transactionActivityList": {
+            "$ref": "#/components/schemas/ActivityItem",
+          },
+          "transferDestinationAmount": {
+            "$ref": "#/components/schemas/ValuedTokenAmount",
+          },
+          "transferDestinationToken": {
+            "$ref": "#/components/schemas/TokenTransferToken",
+          },
+          "transferList": {
+            "$ref": "#/components/schemas/TokenTransfer",
+          },
+          "transferListMeta": {
+            "$ref": "#/components/schemas/TokenTransferListMeta",
+          },
+          "transferSourceAmount": {
+            "$ref": "#/components/schemas/ValuedTokenAmount",
+          },
+          "transferSourceToken": {
+            "$ref": "#/components/schemas/TokenTransferToken",
+          },
+          "valuationPricing": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/ValuationPricing",
+              },
+              {
+                "type": "null",
+              },
+            ],
+            "description": "Rate provenance, or \`null\` when every valued holding was already denominated in \`currency\`.",
+          },
+        },
+        "operations": {
+          "addressActivities": {
+            "errors": {
+              "400": {
+                "codes": [
+                  "address_invalid",
+                  "api_key_malformed",
+                  "chain_id_invalid",
+                  "chain_id_unsupported",
+                  "query_invalid",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/AddressInvalidOrApiKeyMalformedOrChainIdInvalidOrChainIdUnsupportedOrQueryInvalidError",
+                },
+              },
+              "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": "getAddressActivities",
+            "response": {
+              "$ref": "#/components/schemas/AddressActivityList",
+            },
+          },
+          "addressValuation": {
+            "errors": {
+              "400": {
+                "codes": [
+                  "address_invalid",
+                  "api_key_malformed",
+                  "chain_id_invalid",
+                  "chain_id_unsupported",
+                  "query_invalid",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/AddressInvalidOrApiKeyMalformedOrChainIdInvalidOrChainIdUnsupportedOrQueryInvalidError",
+                },
+              },
+              "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": "getAddressValuation",
+            "response": {
+              "$ref": "#/components/schemas/AddressValuation",
+            },
+          },
+          "transactionActivities": {
+            "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",
+                },
+              },
+              "409": {
+                "codes": [
+                  "transaction_ambiguous",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/TransactionAmbiguousError",
+                },
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "502": {
+                "codes": [
+                  "upstream_error",
+                ],
+                "schema": {
+                  "$ref": "#/components/schemas/UpstreamError",
+                },
+              },
+            },
+            "operationId": "getTransactionActivities",
+            "response": {
+              "$ref": "#/components/schemas/TransactionActivityList",
+            },
+          },
+          "transfers": {
+            "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": "getTransfers",
+            "response": {
+              "$ref": "#/components/schemas/TokenTransferList",
+            },
+          },
+        },
+      }
+    `)
+  })
+})
+
 describe('GET /transfers', () => {
   test('parses granular token includes', () => {
     expect(