tapimo 0.13.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'
 
@@ -161,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 = {
@@ -227,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,
@@ -276,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',
@@ -422,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'] } }),
@@ -590,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(
@@ -612,9 +858,15 @@ 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)
@@ -708,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) } : {}),
+            })
           }
         }
       }

package/src/apps/management/routes/webhooks.test.ts

@@ -11,7 +11,7 @@ import * as Webhooks from './webhooks.js'
 
 const origin = 'http://localhost'
 const webhook = {
-  applicationEventTypes: ['funding:deposit.updated'],
+  applicationEventTypes: ['funding:deposit.updated', 'funding:transfer.updated'],
   supportedChainIds: [4217, 42431],
 } satisfies App.Webhook
 
@@ -284,7 +284,7 @@ describe('webhooks', () => {
     `)
   })
 
-  test('creates funding deposit subscriptions without reading the RPC head', async () => {
+  test('creates funding transfer subscriptions without reading the RPC head', async () => {
     const db = TestApp.database()
     const app = createApp({ db })
     const cookie = await session(app)
@@ -295,7 +295,7 @@ describe('webhooks', () => {
         chainId: 4217,
         destination: { type: 'url', url: 'https://example.com/funding' },
         environment: 'production',
-        eventType: 'funding:deposit.updated',
+        eventType: 'funding:transfer.updated',
         filters: { status: 'completed' },
       }),
     )

package/src/apps/management/routes/webhooks.ts

@@ -8,7 +8,7 @@ import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as WebhookDestination from '../../../internal/WebhookDestination.js'
 import * as Webhooks from '../../../internal/Webhooks.js'
-import { schema as webhookSchema } from '../../data/routes/webhooks.js'
+import * as DataWebhooks from '../../data/routes/webhooks.js'
 import type { Environment } from '../App.js'
 
 const defaultMaxPerOwner = 100
@@ -21,11 +21,11 @@ export namespace schema {
   export const Subscription = OpenApi.component(
     z
       .object({
-        ...webhookSchema.Subscription.shape,
-        context: webhookSchema.Subscription.shape.context.check(
+        ...DataWebhooks.schema.Subscription.shape,
+        context: DataWebhooks.schema.Subscription.shape.context.check(
           z.meta({ examples: [{ title: 'Production transfers' }] }),
         ),
-        destination: webhookSchema.Subscription.shape.destination.check(
+        destination: DataWebhooks.schema.Subscription.shape.destination.check(
           z.meta({ examples: [{ type: 'url', url: 'https://example.com/webhooks' }] }),
         ),
       })
@@ -35,7 +35,7 @@ export namespace schema {
 
   /** Webhook delivery data returned in collection rows. */
   export const Delivery = OpenApi.component(
-    webhookSchema.Delivery,
+    DataWebhooks.schema.Delivery,
     'OrganizationWebhookDeliverySummary',
   )
 
@@ -44,7 +44,7 @@ export namespace schema {
     const Environment = z
       .enum(['production', 'sandbox'])
       .check(
-        z.describe('API-key environment whose private funding deposits are delivered.'),
+        z.describe('API-key environment whose private funding resources are delivered.'),
         z.meta({ examples: ['production'] }),
       )
 
@@ -52,24 +52,24 @@ export namespace schema {
     export const Body = OpenApi.component(
       z
         .intersection(
-          webhookSchema.createWebhook.Body,
+          DataWebhooks.schema.createWebhook.Body,
           z.object({
-            chainId: webhookSchema.Subscription.shape.chainId,
+            chainId: DataWebhooks.schema.Subscription.shape.chainId,
             environment: z.optional(Environment),
           }),
         )
         .check(
           z.refine(
             (body) =>
-              body.eventType !== 'funding:deposit.updated' || body.environment !== undefined,
-            { error: '`environment` is required for funding deposit subscriptions.' },
+              !DataWebhooks.isFundingEventType(body.eventType) || body.environment !== undefined,
+            { error: '`environment` is required for funding subscriptions.' },
           ),
           z.describe('Details for creating an organization webhook subscription.'),
         ),
       'CreateOrganizationWebhookRequest',
     )
 
-    const secret = webhookSchema.createWebhook.Response.shape.secret
+    const secret = DataWebhooks.schema.createWebhook.Response.shape.secret
     const urlDestination = z
       .object({
         type: z
@@ -192,7 +192,7 @@ export namespace schema {
   /** Schemas for listing an organization webhook's delivery attempts. */
   export namespace listWebhookDeliveries {
     export const Params = WebhookParams
-    export const Query = webhookSchema.listWebhookDeliveries.Query
+    export const Query = DataWebhooks.schema.listWebhookDeliveries.Query
     export const Response = OpenApi.component(
       z
         .object({
@@ -202,10 +202,10 @@ export namespace schema {
               z.describe('Webhook delivery attempts on this page.'),
               z.meta({ examples: [[]] }),
             ),
-          meta: webhookSchema.listWebhookDeliveries.Response.shape.meta.check(
+          meta: DataWebhooks.schema.listWebhookDeliveries.Response.shape.meta.check(
             z.meta({ examples: [{ totalCount: 1, totalCountCapped: false }] }),
           ),
-          nextCursor: webhookSchema.listWebhookDeliveries.Response.shape.nextCursor,
+          nextCursor: DataWebhooks.schema.listWebhookDeliveries.Response.shape.nextCursor,
         })
         .check(z.describe("A page of an organization's webhook delivery attempts.")),
       'OrganizationWebhookDeliveryList',
@@ -214,7 +214,7 @@ export namespace schema {
 
   const DeliveryParams = z
     .object({
-      deliveryId: webhookSchema.retryWebhookDelivery.Params.shape.deliveryId,
+      deliveryId: DataWebhooks.schema.retryWebhookDelivery.Params.shape.deliveryId,
       id: WebhookParams.shape.id,
       orgId: WebhookParams.shape.orgId,
     })
@@ -227,7 +227,7 @@ export namespace schema {
       z
         .object({
           ...Delivery.shape,
-          envelope: webhookSchema.Envelope,
+          envelope: DataWebhooks.schema.Envelope,
         })
         .check(z.describe('A webhook delivery attempt with the exact JSON payload Tempo sent.')),
       'OrganizationWebhookDelivery',
@@ -238,7 +238,7 @@ export namespace schema {
   export namespace retryWebhookDelivery {
     export const Params = DeliveryParams
     export const Response = OpenApi.component(
-      webhookSchema.retryWebhookDelivery.Response,
+      DataWebhooks.schema.retryWebhookDelivery.Response,
       'RetryOrganizationWebhookDeliveryResponse',
     )
   }
@@ -261,7 +261,7 @@ export namespace schema {
   /** Lifecycle state editable from the console. */
   export const UpdateBody = OpenApi.component(
     z
-      .object({ status: webhookSchema.Status })
+      .object({ status: DataWebhooks.schema.Status })
       .check(z.describe('New delivery state for a webhook subscription.')),
     'UpdateOrganizationWebhookRequest',
   )
@@ -344,7 +344,7 @@ export function webhooks(options: webhooks.Options = {}) {
 
         const body = c.req.valid('json')
         if (
-          body.eventType === 'funding:deposit.updated' &&
+          DataWebhooks.isFundingEventType(body.eventType) &&
           !options.webhook.applicationEventTypes?.includes(body.eventType)
         )
           return Response.error(c, {
@@ -364,17 +364,16 @@ export function webhooks(options: webhooks.Options = {}) {
           const owner_ = owner(Auth.org(c).id)
           if ((await Webhooks.countSubscriptions(db, owner_)) >= maxPerOwner)
             throw new Webhooks.LimitExceededError(maxPerOwner)
-          const startBlockNumber =
-            body.eventType === 'funding:deposit.updated'
-              ? undefined
-              : Number(await c.get('getClient')(chainId).getBlockNumber())
+          const startBlockNumber = DataWebhooks.isFundingEventType(body.eventType)
+            ? undefined
+            : Number(await c.get('getClient')(chainId).getBlockNumber())
           const subscription = await Webhooks.createSubscription(
             db,
             {
               chainId,
               ...(body.context === undefined ? {} : { context: body.context }),
               destination: body.destination,
-              ...(body.eventType === 'funding:deposit.updated' && body.environment !== undefined
+              ...(DataWebhooks.isFundingEventType(body.eventType) && body.environment !== undefined
                 ? { environment: body.environment }
                 : {}),
               eventType: body.eventType,
@@ -754,7 +753,7 @@ function publicSubscription(subscription: Webhooks.Subscription) {
     ...(subscription.context === undefined ? {} : { context: subscription.context }),
     createdAt: subscription.createdAt,
     destination,
-    ...(subscription.eventType === 'funding:deposit.updated' &&
+    ...(DataWebhooks.isFundingEventType(subscription.eventType) &&
     subscription.environment !== undefined
       ? { environment: subscription.environment }
       : {}),