tapimo 0.12.0 → 0.14.0

package/src/apps/funding/routes/transfers.ts

@@ -11,11 +11,13 @@ import * as Cache from '../../../internal/Cache.js'
 import * as FundingCatalog from '../../../internal/funding/Catalog.js'
 import * as FundingProvider from '../../../internal/funding/Provider.js'
 import * as FundingTransfer from '../../../internal/funding/Transfer.js'
+import * as FundingTransferReconciliation from '../../../internal/funding/TransferReconciliation.js'
 import * as Idempotency from '../../../internal/Idempotency.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
 import * as Value from '../../../internal/Value.js'
+import type * as Webhooks from '../../../internal/Webhooks.js'
 import * as Access from '../Access.js'
 import * as ProviderAttempts from '../ProviderAttempts.js'
 
@@ -36,15 +38,20 @@ export namespace schema {
       .check(z.describe('Query parameters for listing funding transfers.'))
 
     /** Paginated funding transfer list. */
-    export const Response = z
-      .object({
-        data: z.array(Transfer).check(z.describe('Funding transfers on this page, newest first.')),
-        meta: z
-          .optional(Schema.CountMeta)
-          .check(z.describe('Extra response metadata requested with `include`.')),
-        nextCursor: Schema.NextCursor,
-      })
-      .check(z.describe('A page of funding transfers.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z
+            .array(Transfer)
+            .check(z.describe('Funding transfers on this page, newest first.')),
+          meta: z
+            .optional(Schema.CountMeta)
+            .check(z.describe('Extra response metadata requested with `include`.')),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of funding transfers.')),
+      'FundingTransferList',
+    )
   }
 
   /** Schemas for the createFundingTransfer operation. */
@@ -82,18 +89,21 @@ export namespace schema {
   /** Schemas for the createFundingTransferVault operation. */
   export namespace createFundingTransferVault {
     /** Funding transfer creation request for an Earn vault destination. */
-    export const Body = z
-      .strictObject({
-        ...destinationCreateFields,
-        vaultAddress: z
-          .string()
-          .check(
-            z.regex(/^0x[0-9a-fA-F]{40}$/),
-            z.describe('Tempo Earn vault contract address.'),
-            z.meta({ examples: [`0x${'f4'.repeat(20)}`] }),
-          ),
-      })
-      .check(z.describe('Vault funding transfer creation request.'))
+    export const Body = OpenApi.component(
+      z
+        .strictObject({
+          ...destinationCreateFields,
+          vaultAddress: z
+            .string()
+            .check(
+              z.regex(/^0x[0-9a-fA-F]{40}$/),
+              z.describe('Tempo Earn vault contract address.'),
+              z.meta({ examples: [`0x${'f4'.repeat(20)}`] }),
+            ),
+        })
+        .check(z.describe('Vault funding transfer creation request.')),
+      'CreateFundingTransferVaultRequest',
+    )
 
     /** Required headers for vault funding transfer creation. */
     export const Headers = createFundingTransfer.Headers
@@ -102,32 +112,35 @@ export namespace schema {
   /** Schemas for the createFundingTransferZone operation. */
   export namespace createFundingTransferZone {
     /** Funding transfer creation request for a Zone destination. */
-    export const Body = z
-      .strictObject({
-        amount: destinationCreateFields.amount,
-        destinationChain: z
-          .string()
-          .check(
-            z.regex(/^eip155:\d+$/),
-            z.describe('Configured Zone CAIP-2 id.'),
-            z.meta({ examples: ['eip155:1424310001'] }),
-          ),
-        destinationToken: FundingTransfer.schema.CreateRequest.shape.destinationToken,
-        mode: destinationCreateFields.mode,
-        recipient: destinationCreateFields.recipient,
-        recipientFallback: z
-          .string()
-          .check(
-            z.regex(/^0x[0-9a-fA-F]{40}$/),
-            z.describe('Public Tempo recipient used if the Zone credit cannot complete.'),
-            z.meta({ examples: [`0x${'22'.repeat(20)}`] }),
-          ),
-        sender: destinationCreateFields.sender,
-        slippageBps: destinationCreateFields.slippageBps,
-        sourceChain: destinationCreateFields.sourceChain,
-        sourceToken: destinationCreateFields.sourceToken,
-      })
-      .check(z.describe('Zone funding transfer creation request.'))
+    export const Body = OpenApi.component(
+      z
+        .strictObject({
+          amount: destinationCreateFields.amount,
+          destinationChain: z
+            .string()
+            .check(
+              z.regex(/^eip155:\d+$/),
+              z.describe('Configured Zone CAIP-2 id.'),
+              z.meta({ examples: ['eip155:1424310003'] }),
+            ),
+          destinationToken: FundingTransfer.schema.CreateRequest.shape.destinationToken,
+          mode: destinationCreateFields.mode,
+          recipient: destinationCreateFields.recipient,
+          recipientFallback: z
+            .string()
+            .check(
+              z.regex(/^0x[0-9a-fA-F]{40}$/),
+              z.describe('Public Tempo recipient used if the Zone credit cannot complete.'),
+              z.meta({ examples: [`0x${'22'.repeat(20)}`] }),
+            ),
+          sender: destinationCreateFields.sender,
+          slippageBps: destinationCreateFields.slippageBps,
+          sourceChain: destinationCreateFields.sourceChain,
+          sourceToken: destinationCreateFields.sourceToken,
+        })
+        .check(z.describe('Zone funding transfer creation request.')),
+      'CreateFundingTransferZoneRequest',
+    )
 
     /** Required headers for Zone funding transfer creation. */
     export const Headers = createFundingTransfer.Headers
@@ -150,6 +163,25 @@ export namespace schema {
     /** The funding transfer resource, returned directly. */
     export const Response = Transfer
   }
+
+  /** Schemas for the registerFundingTransferSourceTransaction operation. */
+  export namespace registerFundingTransferSourceTransaction {
+    /** Source transaction registration request body. */
+    export const Body = OpenApi.component(
+      z
+        .strictObject({
+          transactionHash: Schema.hash(`0x${'51'.repeat(32)}`),
+        })
+        .check(z.describe('Verified source transaction to associate with the transfer.')),
+      'RegisterFundingTransferSourceTransactionRequest',
+    )
+
+    /** Path parameters for source transaction registration. */
+    export const Params = getFundingTransfer.Params
+
+    /** The transfer after source transaction registration. */
+    export const Response = Transfer
+  }
 }
 
 const baseChainExample = {
@@ -216,6 +248,14 @@ const fundingTransferExample = {
   version: 1,
 } satisfies z.output<typeof schema.Transfer>
 
+const registeredFundingTransferExample = {
+  ...fundingTransferExample,
+  sourceTransactionHashes: [`0x${'51'.repeat(32)}`],
+  status: 'processing',
+  updatedAt: '2026-01-01T00:00:20.000Z',
+  version: 2,
+} satisfies z.output<typeof schema.registerFundingTransferSourceTransaction.Response>
+
 const listFundingTransfersResponseExample = {
   data: [fundingTransferExample],
   nextCursor: null,
@@ -265,9 +305,17 @@ const idempotencyReplayTtlMs = 86_400_000
 // Pending claims only cover the bounded provider preparation window.
 const idempotencyPendingTtlMs = 60_000
 const fundingEtag = etag()
+const bodyValidation = {
+  code: 'body_invalid',
+  message: 'Check the request body and try again.',
+} as const
+const paramValidation = {
+  code: 'param_invalid',
+  message: 'Check the path parameters and try again.',
+} as const
 
 /** Mounts durable funding transfer routes. */
-export function transfers() {
+export function transfers(options: transfers.Options = {}) {
   return new Hono<App.Environment>()
     .get(
       '/v1/funding/transfers',
@@ -411,6 +459,209 @@ export function transfers() {
         }
       },
     )
+    .post(
+      '/v1/funding/transfers/:id{ftr_[A-Za-z0-9_-]+}/source-transactions',
+      Auth.policy({ apiKey: { scopes: ['funding:write'] } }),
+      OpenApi.validate(
+        'param',
+        schema.registerFundingTransferSourceTransaction.Params,
+        paramValidation,
+      ),
+      OpenApi.validate(
+        'json',
+        schema.registerFundingTransferSourceTransaction.Body,
+        bodyValidation,
+      ),
+      OpenApi.describeRoute({
+        description: 'Registers and verifies a funding source transaction.',
+        operationId: 'registerFundingTransferSourceTransaction',
+        responses: OpenApi.responses({
+          errors: {
+            400: {
+              codes: ['body_invalid', 'param_invalid', 'source_transaction_invalid'],
+              description: 'The path, body, or submitted source transaction is invalid.',
+            },
+            404: {
+              codes: ['funding_transfer_not_found'],
+              description: 'No visible funding transfer exists for the identifier.',
+            },
+            409: {
+              codes: [
+                'funding_transfer_not_awaiting_source',
+                'source_transaction_conflict',
+                'source_transaction_pending',
+              ],
+              description: 'The transfer or source transaction cannot be registered yet.',
+            },
+            501: {
+              codes: ['not_implemented'],
+              description: 'Source transaction reconciliation is not configured.',
+            },
+            502: {
+              codes: ['upstream_error'],
+              description: 'Source verification or reconciliation dispatch failed.',
+            },
+          },
+          success: {
+            description: 'The transfer with its verified source transaction.',
+            example: registeredFundingTransferExample,
+            schema: schema.registerFundingTransferSourceTransaction.Response,
+          },
+        }),
+        summary: 'Register source transaction',
+        tags: ['Funding Transfers'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation) return OpenApi.validationError(c, paramValidation)
+        if (OpenApi.narrowValidation) return OpenApi.validationError(c, bodyValidation)
+
+        const owner = Access.owner(c)
+        if (!owner) return Access.unauthorized(c)
+        c.header('Cache-Control', Cache.policies.noStore)
+        c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key')
+
+        const dispatch = options.dispatchTransferReconciliation
+        if (!dispatch)
+          return Response.error(c, {
+            code: 'not_implemented',
+            message: 'Source transaction reconciliation is not configured',
+            status: 501,
+          })
+
+        const db = Db.get(c.get('db'))
+        const { id } = c.req.valid('param')
+        const { transactionHash } = c.req.valid('json')
+        try {
+          const record = await FundingTransfers.getOwned(db, owner, id)
+          if (!record)
+            return Response.error(c, {
+              code: 'funding_transfer_not_found',
+              message: 'Funding transfer not found',
+              status: 404,
+            })
+          if (
+            record.snapshot.sourceTransactionHashes?.some(
+              (candidate) => candidate.toLowerCase() === transactionHash,
+            )
+          ) {
+            if (record.status === 'processing')
+              await dispatch({ transferId: record.id, type: 'funding:transfer:reconcile' })
+            return c.json(
+              Response.validated(
+                schema.registerFundingTransferSourceTransaction.Response,
+                FundingTransfer.toPublic(record),
+              ),
+              200,
+            )
+          }
+          const provider = c
+            .get('providers')
+            .filter(FundingProvider.is)
+            .find((candidate) => candidate.id === record.providerId)
+          if (!provider || !FundingProvider.canVerifySourceTransaction(provider))
+            return Response.error(c, {
+              code: 'funding_transfer_not_awaiting_source',
+              message: 'Funding transfer does not accept source transactions',
+              status: 409,
+            })
+          if (record.status !== 'awaiting-source')
+            return Response.error(c, {
+              code: 'funding_transfer_not_awaiting_source',
+              message: 'Funding transfer is not awaiting a source transaction',
+              status: 409,
+            })
+
+          const catalog = await FundingCatalog.snapshot(c)
+          const destinationChain = catalog.chainsByKey.get(record.snapshot.destinationChain.id)
+          const sourceChain = catalog.chainsByKey.get(record.snapshot.sourceChain.id)
+          const routeConfiguration = catalog.routesByProvider
+            .get(record.providerId)
+            ?.find(
+              (candidate) =>
+                candidate.route.source.chain.id === record.snapshot.sourceChain.id &&
+                candidate.route.source.address.toLowerCase() ===
+                  record.snapshot.sourceToken.address.toLowerCase() &&
+                candidate.route.destination.chain.id === record.snapshot.destinationChain.id &&
+                candidate.route.destination.address.toLowerCase() ===
+                  record.snapshot.destinationToken.address.toLowerCase(),
+            )?.configuration
+          if (!destinationChain || !sourceChain)
+            return Response.error(c, {
+              code: 'funding_transfer_not_awaiting_source',
+              message: 'Funding transfer route chains are no longer configured',
+              status: 409,
+            })
+
+          const evidence = await provider.verifySourceTransaction(
+            {
+              destinationChain,
+              providerState: record.providerState ?? undefined,
+              routeConfiguration,
+              sourceChain,
+              transactionHash,
+              transfer: record.snapshot,
+            },
+            c.req.raw.signal,
+          )
+          if (evidence.type === 'pending')
+            return Response.error(c, {
+              code: 'source_transaction_pending',
+              message: 'Source transaction is not confirmed yet',
+              status: 409,
+            })
+          if (evidence.type === 'invalid')
+            return Response.error(c, {
+              code: 'source_transaction_invalid',
+              message: 'Source transaction does not match the funding transfer',
+              status: 400,
+            })
+
+          const registered = await FundingTransfer.registerSourceTransaction(db, {
+            chainId: record.snapshot.sourceChain.id,
+            id: record.id,
+            providerState: evidence.providerState ?? {},
+            transactionHash,
+          })
+          if (registered.type === 'not_found')
+            return Response.error(c, {
+              code: 'funding_transfer_not_found',
+              message: 'Funding transfer not found',
+              status: 404,
+            })
+          if (registered.type === 'conflict')
+            return Response.error(c, {
+              code: 'source_transaction_conflict',
+              message: 'Source transaction is already assigned to another funding transfer',
+              status: 409,
+            })
+          if (registered.type === 'invalid')
+            return Response.error(c, {
+              code: 'funding_transfer_not_awaiting_source',
+              message: 'Funding transfer is not awaiting a source transaction',
+              status: 409,
+            })
+
+          await Promise.all([
+            dispatch({ transferId: record.id, type: 'funding:transfer:reconcile' }),
+            registered.type === 'registered' &&
+            options.dispatchTransferUpdates &&
+            registered.references.length > 0
+              ? options.dispatchTransferUpdates(registered.references)
+              : undefined,
+          ])
+          return c.json(
+            Response.validated(
+              schema.registerFundingTransferSourceTransaction.Response,
+              FundingTransfer.toPublic(registered.record),
+            ),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
     .post(
       '/v1/funding/transfers',
       Auth.policy({ apiKey: { scopes: ['funding:write'] } }),
@@ -516,6 +767,7 @@ export function transfers() {
             method: 'transaction',
             mode: body.mode,
             onAttempt: (attempt) => attempts.push(attempt),
+            provider: body.provider,
             providers,
             recipient: body.recipient,
             sender: body.sender,
@@ -532,8 +784,6 @@ export function transfers() {
           }
 
           const { candidate, result } = selected
-          const feeToken = (side: 'destination' | 'source') =>
-            side === 'source' ? candidate.sourceToken : candidate.destinationToken
           const snapshot: FundingTransfer.Snapshot = {
             destinationAmount: Value.tokenAmount({
               baseUnits: result.destinationAmount,
@@ -547,16 +797,21 @@ export function transfers() {
             }),
             destinationChain: candidate.destinationChain,
             destinationToken: candidate.destinationToken,
-            fees: result.fees.map((fee) => ({
-              amount: Value.tokenAmount({
-                baseUnits: fee.amount,
-                currency: feeToken(fee.side).currency,
-                decimals: feeToken(fee.side).decimals,
-              }),
-              side: fee.side,
-              token: feeToken(fee.side),
-              type: 'provider',
-            })),
+            fees: result.fees.map((fee) => {
+              const token =
+                fee.token ??
+                (fee.side === 'source' ? candidate.sourceToken : candidate.destinationToken)
+              return {
+                amount: Value.tokenAmount({
+                  baseUnits: fee.amount,
+                  currency: token.currency,
+                  decimals: token.decimals,
+                }),
+                side: fee.side,
+                token,
+                type: 'provider',
+              }
+            }),
             method: 'transaction',
             mode: body.mode,
             provider: candidate.provider,
@@ -575,12 +830,18 @@ export function transfers() {
           // The transfer row, its version-1 event, and the replay body commit
           // atomically so a crash cannot leave a claimed key without a replay.
           const created = await db.transaction(async (tx) => {
-            const record = await FundingTransfer.createIn(tx, {
+            const { record, references } = await FundingTransfer.createIn(tx, {
               apiKeyId: principal.id,
               environment: owner.environment,
               orgId: owner.orgId,
               projectId: owner.projectId,
-              providerState: result.correlation,
+              providerState:
+                result.correlation || result.providerState
+                  ? {
+                      ...result.correlation,
+                      ...result.providerState,
+                    }
+                  : undefined,
               snapshot,
             })
             const validated = Response.validated(
@@ -597,13 +858,21 @@ export function transfers() {
             })
             if (!completion)
               throw new IdempotencyLeaseLostError('Funding transfer creation lease was lost.')
-            return validated
+            return { references, response: validated }
           })
-          return c.json(created, 200)
+          if (options.dispatchTransferUpdates && created.references.length > 0)
+            try {
+              await options.dispatchTransferUpdates(created.references)
+            } catch (cause) {
+              return Response.upstream(c, cause)
+            }
+          return c.json(created.response, 200)
         } catch (cause) {
           await release()
           if (cause instanceof FundingProvider.InvalidAmountError)
             return Response.error(c, { code: 'body_invalid', message: 'Invalid `amount`.', status: 400 }) // prettier-ignore
+          if (cause instanceof FundingProvider.UnsupportedProviderError)
+            return Response.error(c, { code: 'body_invalid', message: 'Unsupported `provider`.', status: 400 }) // prettier-ignore
           if (cause instanceof FundingProvider.UnsupportedSourceChainError)
             return quoteNotAvailable(c)
           if (cause instanceof FundingProvider.ProviderQuoteError) {
@@ -691,6 +960,20 @@ export function transfers() {
     )
 }
 
+export declare namespace transfers {
+  /** Funding transfer route dependencies. */
+  type Options = {
+    /** Enqueues one registered transfer for destination reconciliation. */
+    dispatchTransferReconciliation?:
+      | ((message: FundingTransferReconciliation.Message) => Promise<void>)
+      | undefined
+    /** Enqueues webhook updates staged with transfer mutations. */
+    dispatchTransferUpdates?:
+      | ((references: readonly Webhooks.QueueReference[]) => Promise<number>)
+      | undefined
+  }
+}
+
 function quoteNotAvailable(c: Context<App.Environment>) {
   return Response.error(c, {
     code: 'quote_not_available',

package/src/apps/management/Billing.ts

@@ -1,7 +1,7 @@
 import { Hash, Hex, Value } from 'ox'
 import type Stripe from 'stripe'
 
-import type * as Store from '../../internal/Store.js'
+import * as ApiKey from '../../ApiKey.js'
 import * as ApiKeys from '../../ApiKeys.js'
 import type * as BillingSettings from '../../db/tables/billingSettings.js'
 import * as Db from '../../db/Db.js'
@@ -9,6 +9,7 @@ import * as Fees from '../../internal/Fees.js'
 import * as RequestUsage from '../../db/tables/requestUsage.js'
 import type * as Scope from '../../Scope.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
+import type * as Store from '../../internal/Store.js'
 import * as StripeCustomers from '../../db/tables/stripeCustomers.js'
 import * as Viem from '../../internal/Viem.js'
 
@@ -567,10 +568,22 @@ export function createRequestUsageReporter(
               reported++
           } catch (error) {
             failed++
-            console.error(
-              `Billing.createRequestUsageReporter: reporting ${environment} bucket ${orgId}/${bucketStart} failed`,
-              error,
-            )
+            // Cloudflare flattens multiple console arguments, so keep the driver details on one structured entry.
+            const cause = error instanceof Error ? error : undefined
+            console.error({
+              bucketStart,
+              component: 'request_usage_meter',
+              environment,
+              error: ApiKey.redact(cause?.message ?? String(error)).slice(0, 500),
+              ...(cause &&
+              'code' in cause &&
+              (typeof cause.code === 'string' || typeof cause.code === 'number')
+                ? { errorCode: ApiKey.redact(String(cause.code)).slice(0, 100) }
+                : {}),
+              errorType: cause?.name ?? typeof error,
+              orgId,
+              ...(cause?.stack ? { stack: ApiKey.redact(cause.stack).slice(0, 4_000) } : {}),
+            })
           }
         }
       }