tapimo 0.12.0 → 0.14.0

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

@@ -122,17 +122,23 @@ export namespace schema {
       ),
     )
 
-  /** A token amount carrying its nominal value in the requested denomination. */
-  const ValuedAmount = z.extend(Schema.TokenAmount, {
-    valuation: z
-      .optional(z.nullable(Valuation.schema.Value))
-      .check(
-        z.describe(
-          'The amount’s nominal value in the requested `valuation.currency`. `null` when the token is ' +
-            'unverified, its display currency has no rate, or rates were unavailable.',
+  const transferToken = OpenApi.component(SourceToken, 'TokenTransferToken')
+
+  const ValuedAmount = Schema.describe(
+    z.extend(Schema.TokenAmount, {
+      valuation: z
+        .optional(z.nullable(Valuation.schema.Value))
+        .check(
+          z.describe(
+            'The amount’s nominal value in the requested `valuation.currency`. `null` when the token is ' +
+              'unverified, its display currency has no rate, or rates were unavailable.',
+          ),
         ),
-      ),
-  })
+    }),
+    'A token amount carrying its nominal value in the requested denomination.',
+  )
+
+  const valuedTokenAmount = OpenApi.component(ValuedAmount, 'ValuedTokenAmount')
 
   /**
    * Filter predicates shared verbatim by the `GET /transfers` list query
@@ -243,14 +249,14 @@ export namespace schema {
             z.meta({ examples: [23456789] }),
           ),
         destinationAmount: z
-          .optional(ValuedAmount)
+          .optional(valuedTokenAmount)
           .check(
             z.describe(
               'Amount delivered to the recipient for a cross-token transfer. Omitted with `destinationToken` for a same-token transfer.',
             ),
           ),
         destinationToken: z
-          .optional(schema.SourceToken)
+          .optional(transferToken)
           .check(
             z.describe(
               'The token delivered to the recipient when it differs from `sourceToken`. Omitted for same-token transfers and returned only with `include=crossToken`.',
@@ -284,8 +290,8 @@ export namespace schema {
           z.describe('The account address that received the tokens.'),
         ),
         sender: Schema.Address.check(z.describe('The account address that sent the tokens.')),
-        sourceAmount: ValuedAmount.check(z.describe('Amount associated with `sourceToken`.')),
-        sourceToken: schema.SourceToken.check(z.describe('The token that moved.')),
+        sourceAmount: valuedTokenAmount,
+        sourceToken: transferToken.check(z.describe('The token that moved.')),
         timestamp: z.iso
           .datetime()
           .check(
@@ -310,6 +316,8 @@ export namespace schema {
         ),
       )
 
+    const transfer = OpenApi.component(Transfer, 'TokenTransfer')
+
     /** Page-level resources: opt-in counts plus valuation rate provenance. */
     export const Meta = z
       .object({
@@ -326,19 +334,26 @@ export namespace schema {
       })
       .check(z.describe('Page-level resources attached to this response.'))
 
+    const meta = OpenApi.component(Meta, 'TokenTransferListMeta')
+
     /** Page of TIP-20 token transfers across the chain, ordered by block then log index. */
-    export const Response = z
-      .object({
-        data: z.array(Transfer).check(z.describe('The transfers in this page.')),
-        // Response-wide `meta` carries the opt-in capped total count
-        // (`include=totalCount`) and valuation rate provenance; per-row embeds
-        // (`memo`, `token`) attach to each `data` item, not here.
-        meta: z
-          .optional(Meta)
-          .check(z.describe('Page-level resources: opt-in counts and valuation rate provenance.')),
-        nextCursor: Schema.NextCursor,
-      })
-      .check(z.describe('A page of TIP-20 token transfer events across the chain.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z.array(transfer).check(z.describe('The transfers in this page.')),
+          // Response-wide `meta` carries the opt-in capped total count
+          // (`include=totalCount`) and valuation rate provenance; per-row embeds
+          // (`memo`, `token`) attach to each `data` item, not here.
+          meta: z
+            .optional(meta)
+            .check(
+              z.describe('Page-level resources: opt-in counts and valuation rate provenance.'),
+            ),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of TIP-20 token transfer events across the chain.')),
+      'TokenTransferList',
+    )
   }
 }
 
@@ -364,7 +379,10 @@ export function transfers(options: transfers.Options = {}) {
       description: 'List token transfer events across Tempo.',
       operationId: 'getTransfers',
       responses: OpenApi.responses({
-        errors: { 502: 'The indexer or Tempo RPC could not serve this request.' },
+        errors: {
+          400: { codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid'] },
+          502: 'The indexer or Tempo RPC could not serve this request.',
+        },
         success: {
           description: 'A page of token transfer events.',
           schema: schema.getTransfers.Response,

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

@@ -23,47 +23,55 @@ const tokenReadChunkSize = 20
 /** Zod schemas owned by the valuation handlers. */
 export namespace schema {
   /** A holding's nominal value in the requested denomination. */
-  export const Value = z
-    .object({
-      amount: z
-        .string()
-        .check(
-          z.regex(/^\d+(\.\d+)?$/),
-          z.describe('The holding’s nominal value, as a decimal string in `currency`.'),
-          z.meta({ examples: ['1.50'] }),
-        ),
-      currency: z
-        .string()
-        .check(
-          z.describe('The denomination currency of this value.'),
-          z.meta({ examples: ['USD'] }),
-        ),
-    })
-    .check(z.describe('The holding’s nominal value in the requested denomination.'))
+  export const Value = OpenApi.component(
+    z
+      .object({
+        amount: z
+          .string()
+          .check(
+            z.regex(/^\d+(\.\d+)?$/),
+            z.describe('The holding’s nominal value, as a decimal string in `currency`.'),
+            z.meta({ examples: ['1.50'] }),
+          ),
+        currency: z
+          .string()
+          .check(
+            z.describe('The denomination currency of this value.'),
+            z.meta({ examples: ['USD'] }),
+          ),
+      })
+      .check(z.describe('The holding’s nominal value in the requested denomination.')),
+    'ValuationValue',
+  )
 
   /** Rate provenance for a converted valuation. */
-  export const Pricing = z
-    .object({
-      asOf: z.iso
-        .datetime()
-        .check(
-          z.describe('Publication date of the rate set as an ISO 8601 timestamp.'),
-          z.meta({ examples: ['2026-07-20T00:00:00.000Z'] }),
-        ),
-      basis: z
-        .literal('nominal')
-        .check(
-          z.describe('Valuation basis: one token unit counts as one unit of its display currency.'),
-          z.meta({ examples: ['nominal'] }),
-        ),
-      source: z
-        .string()
-        .check(
-          z.describe('FX rate oracle that supplied the conversion rates.'),
-          z.meta({ examples: ['ecb'] }),
-        ),
-    })
-    .check(z.describe('Rate provenance for a converted valuation.'))
+  export const Pricing = OpenApi.component(
+    z
+      .object({
+        asOf: z.iso
+          .datetime()
+          .check(
+            z.describe('Publication date of the rate set as an ISO 8601 timestamp.'),
+            z.meta({ examples: ['2026-07-20T00:00:00.000Z'] }),
+          ),
+        basis: z
+          .literal('nominal')
+          .check(
+            z.describe(
+              'Valuation basis: one token unit counts as one unit of its display currency.',
+            ),
+            z.meta({ examples: ['nominal'] }),
+          ),
+        source: z
+          .string()
+          .check(
+            z.describe('FX rate oracle that supplied the conversion rates.'),
+            z.meta({ examples: ['ecb'] }),
+          ),
+      })
+      .check(z.describe('Rate provenance for a converted valuation.')),
+    'ValuationPricing',
+  )
 
   /** Schemas for the getAddressValuation operation. */
   export namespace getAddressValuation {
@@ -89,47 +97,50 @@ export namespace schema {
       .check(z.describe('Query parameters for valuing an account’s verified holdings.'))
 
     /** The nominal valuation of an account's verified holdings. */
-    export const Response = z
-      .object({
-        address: Schema.Address.check(z.describe('The account address this valuation covers.')),
-        amount: z
-          .string()
-          .check(
-            z.regex(/^\d+(\.\d+)?$/),
-            z.describe(
-              'The total value of the account’s verified holdings, as a decimal string in `currency`.',
+    export const Response = OpenApi.component(
+      z
+        .object({
+          address: Schema.Address.check(z.describe('The account address this valuation covers.')),
+          amount: z
+            .string()
+            .check(
+              z.regex(/^\d+(\.\d+)?$/),
+              z.describe(
+                'The total value of the account’s verified holdings, as a decimal string in `currency`.',
+              ),
+              z.meta({ examples: ['160.50'] }),
             ),
-            z.meta({ examples: ['160.50'] }),
-          ),
-        currency: z
-          .string()
-          .check(
-            z.describe('The denomination currency of `amount`.'),
-            z.meta({ examples: ['USD'] }),
-          ),
-        id: z
-          .string()
-          .check(
-            z.describe('A stable resource ID for this valuation, equal to the account address.'),
-            z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] }),
-          ),
-        pricing: z
-          .nullable(Pricing)
-          .check(
-            z.describe(
-              'Rate provenance, or `null` when every valued holding was already denominated in `currency`.',
+          currency: z
+            .string()
+            .check(
+              z.describe('The denomination currency of `amount`.'),
+              z.meta({ examples: ['USD'] }),
             ),
-          ),
-        unpriced: z
-          .array(z.string())
-          .check(
-            z.describe(
-              'Display currencies excluded from `amount` because the FX oracle has no rate for them.',
+          id: z
+            .string()
+            .check(
+              z.describe('A stable resource ID for this valuation, equal to the account address.'),
+              z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] }),
             ),
-            z.meta({ examples: [['BTC']] }),
-          ),
-      })
-      .check(z.describe('The nominal valuation of an account’s verified token holdings.'))
+          pricing: z
+            .nullable(Pricing)
+            .check(
+              z.describe(
+                'Rate provenance, or `null` when every valued holding was already denominated in `currency`.',
+              ),
+            ),
+          unpriced: z
+            .array(z.string())
+            .check(
+              z.describe(
+                'Display currencies excluded from `amount` because the FX oracle has no rate for them.',
+              ),
+              z.meta({ examples: [['BTC']] }),
+            ),
+        })
+        .check(z.describe('The nominal valuation of an account’s verified token holdings.')),
+      'AddressValuation',
+    )
   }
 }
 
@@ -155,7 +166,12 @@ export function addresses(options: addresses.Options = {}) {
         'Values every verified TIP-20 token an account holds as one unit of its display currency, converts each currency into the requested denomination using the configured FX rates, and returns the total.',
       operationId: 'getAddressValuation',
       responses: OpenApi.responses({
-        errors: { 502: 'Could not read balances or exchange rates from an upstream service.' },
+        errors: {
+          400: {
+            codes: ['address_invalid', 'chain_id_invalid', 'chain_id_unsupported', 'query_invalid'],
+          },
+          502: 'Could not read balances or exchange rates from an upstream service.',
+        },
         success: {
           description: 'The valuation of this account’s verified holdings.',
           schema: schema.getAddressValuation.Response,

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

@@ -130,6 +130,9 @@ describe('feature gate', () => {
     expect(catalogBody.data.map((eventType) => eventType.type)).not.toContain(
       'funding:deposit.updated',
     )
+    expect(catalogBody.data.map((eventType) => eventType.type)).not.toContain(
+      'funding:transfer.updated',
+    )
     expect(created.status).toBe(400)
   })
 })
@@ -209,6 +212,7 @@ describe('access matrix', () => {
       [
         "block:created",
         "funding:deposit.updated",
+        "funding:transfer.updated",
         "log:emitted",
         "token:transfer",
         "transaction:included",
@@ -261,7 +265,7 @@ describe('CRUD lifecycle', () => {
     expect(body.error?.code).toBe('api_key_forbidden')
   })
 
-  test('captures funding deposit ownership scope without reading the RPC head', async () => {
+  test('captures funding transfer ownership scope without reading the RPC head', async () => {
     const db = TestApp.database()
     const projectWriter = {
       id: 'key_funding_webhook_project',
@@ -275,7 +279,7 @@ describe('CRUD lifecycle', () => {
       {
         json: {
           destination: { type: 'url', url: 'https://example.com/funding' },
-          eventType: 'funding:deposit.updated',
+          eventType: 'funding:transfer.updated',
           filters: { status: 'completed' },
         },
       },
@@ -341,7 +345,7 @@ describe('CRUD lifecycle', () => {
       chainId: 4217,
       destination: { type: 'url', url: 'https://example.com/project-b' },
       environment: 'production',
-      eventType: 'funding:deposit.updated',
+      eventType: 'funding:transfer.updated',
       owner: { orgId: shared.orgId, type: 'api_key' },
       projectId: projectB.projectId,
     })
@@ -1158,8 +1162,12 @@ describe('retry delivery', () => {
       auth: { keys: [writer, reader, other] },
       db,
     })
-    const created = await app.v1.webhooks.$post({ json: validBody }, as(writer))
-    const { id } = await TestApp.json(created, Webhooks.schema.createWebhook.Response)
+    const { id } = await Core.createSubscription(db, {
+      chainId: 4217,
+      destination: validBody.destination,
+      eventType: validBody.eventType,
+      owner: { orgId: writer.orgId, type: 'api_key' },
+    })
     await Core.recordDelivery(db, {
       attempt: 1,
       createdAt: new Date(1_700_000_000_000).toISOString(),
@@ -1316,6 +1324,7 @@ describe('OpenAPI visibility', () => {
         "Log event",
         "Block event",
         "Funding deposit updated event",
+        "Funding transfer updated event",
         "Ping (test delivery)",
       ]
     `)
@@ -1422,6 +1431,13 @@ describe('OpenAPI visibility', () => {
           ],
           "title": "Funding deposit subscription",
         },
+        {
+          "filters": [
+            "id",
+            "status",
+          ],
+          "title": "Funding transfer subscription",
+        },
       ]
     `)
   })

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

@@ -18,6 +18,7 @@ import * as WebhookDestination from '../../../internal/WebhookDestination.js'
 import * as WebhookTransfer from '../../../internal/WebhookTransfer.js'
 import * as Webhooks from '../../../internal/Webhooks.js'
 import * as FundingDeposit from '../../../internal/funding/Deposit.js'
+import * as FundingTransfer from '../../../internal/funding/Transfer.js'
 import * as Transactions from './transactions.js'
 import * as Transfers from './transfers.js'
 
@@ -42,6 +43,7 @@ const redactedSlackUrl = 'https://hooks.slack.com/…'
 export const eventTypes = [
   'block:created',
   'funding:deposit.updated',
+  'funding:transfer.updated',
   'log:emitted',
   'token:transfer',
   'transaction:included',
@@ -50,6 +52,20 @@ export const eventTypes = [
 /** Event types a subscription can listen to. Derived from {@link eventTypes}. */
 export type EventType = (typeof eventTypes)[number]
 
+/** Funding resource events produced by the API instead of chain scans. */
+export const fundingEventTypes = [
+  'funding:deposit.updated',
+  'funding:transfer.updated',
+] as const satisfies readonly EventType[]
+
+/** Event type carrying an owner-scoped funding resource. */
+export type FundingEventType = (typeof fundingEventTypes)[number]
+
+/** Returns whether an event type carries an owner-scoped funding resource. */
+export function isFundingEventType(eventType: EventType): eventType is FundingEventType {
+  return (fundingEventTypes as readonly EventType[]).includes(eventType)
+}
+
 /** Subscribable event types surfaced by `GET /webhooks/event-types`. */
 const eventTypeDescriptions = [
   {
@@ -62,6 +78,11 @@ const eventTypeDescriptions = [
       'A funding deposit materially changed after verified reconciliation, filterable by deposit address, recipient, or status.',
     type: 'funding:deposit.updated',
   },
+  {
+    description:
+      'A funding transfer materially changed, filterable by transfer ID or lifecycle status.',
+    type: 'funding:transfer.updated',
+  },
   {
     description:
       'Any contract event log, filtered by emitting address, event signature/topics, or decoded arguments.',
@@ -465,6 +486,17 @@ export namespace schema {
       z.meta({ title: 'Funding deposit filters' }),
     )
 
+  /** `funding:transfer.updated` subscription filters. All are optional and AND-combined. */
+  export const FundingTransferFilters = z
+    .strictObject({
+      id: z.optional(FundingTransfer.schema.FundingTransfer.shape.id),
+      status: z.optional(FundingTransfer.schema.Status),
+    })
+    .check(
+      z.describe('Filters that narrow which funding transfer changes trigger this webhook.'),
+      z.meta({ title: 'Funding transfer filters' }),
+    )
+
   /**
    * Optional human context describing what a subscription is for. Surfaced by
    * destinations (Slack header + description, Better Stack log fields) and echoed
@@ -917,6 +949,9 @@ export namespace schema {
   /** Public funding deposit after a committed material change. */
   export const FundingDepositEvent = FundingDeposit.schema.FundingDeposit
 
+  /** Public funding transfer after a committed material change. */
+  export const FundingTransferEvent = FundingTransfer.schema.FundingTransfer
+
   /** A `ping` (synthetic test-delivery) payload, sent by `POST /webhooks/:id/ping`. */
   export const PingEvent = z
     .object({
@@ -982,6 +1017,13 @@ export namespace schema {
           type: z.literal('funding:deposit.updated'),
         })
         .check(z.meta({ title: 'Funding deposit updated event' })),
+      z
+        .object({
+          ...envelopeBase,
+          data: FundingTransferEvent,
+          type: z.literal('funding:transfer.updated'),
+        })
+        .check(z.meta({ title: 'Funding transfer updated event' })),
       z
         .object({ ...envelopeBase, data: PingEvent, type: z.literal('ping') })
         .check(z.meta({ title: 'Ping (test delivery)' })),
@@ -1089,6 +1131,20 @@ export namespace schema {
             filters: z.optional(FundingDepositFilters),
           })
           .check(z.meta({ title: 'Funding deposit subscription' })),
+        z
+          .object({
+            chainId: z.optional(Schema.ChainId).check(z.meta({ examples: [4217] })),
+            context: z.optional(Context),
+            destination: Destination,
+            eventType: z
+              .literal('funding:transfer.updated')
+              .check(
+                z.describe('Event type for committed funding transfer changes.'),
+                z.meta({ examples: ['funding:transfer.updated'] }),
+              ),
+            filters: z.optional(FundingTransferFilters),
+          })
+          .check(z.meta({ title: 'Funding transfer subscription' })),
       ])
       .check(z.describe('Details for creating a webhook subscription.'))
 
@@ -1293,7 +1349,7 @@ export function webhooks(options: webhooks.Options = {}) {
   const hidden = !options.enabled
   const availableEventTypes = eventTypeDescriptions.filter(
     (eventType) =>
-      eventType.type !== 'funding:deposit.updated' ||
+      !isFundingEventType(eventType.type) ||
       options.applicationEventTypes?.includes(eventType.type),
   )
   const availableEventTypeSet = new Set(availableEventTypes.map((eventType) => eventType.type))
@@ -1410,7 +1466,7 @@ export function webhooks(options: webhooks.Options = {}) {
               message: 'Webhook event type is not available in this deployment',
               status: 400,
             })
-          if (body.eventType === 'funding:deposit.updated') {
+          if (isFundingEventType(body.eventType)) {
             if (principal?.type !== 'api_key') return unauthorized(c)
             if (
               !principal.apiKey.scopes.some(
@@ -1434,10 +1490,9 @@ export function webhooks(options: webhooks.Options = {}) {
             const maxPerOwner = webhook.maxPerOwner ?? defaultMaxPerOwner
             if ((await Webhooks.countSubscriptions(db, owner)) >= maxPerOwner)
               throw new Webhooks.LimitExceededError(maxPerOwner)
-            const startBlockNumber =
-              body.eventType === 'funding:deposit.updated'
-                ? undefined
-                : await getRpcHead(c.get('getClient')(chainId))
+            const startBlockNumber = isFundingEventType(body.eventType)
+              ? undefined
+              : await getRpcHead(c.get('getClient')(chainId))
             const subscription = await Webhooks.createSubscription(
               db,
               {
@@ -2089,6 +2144,7 @@ export async function getRpcHead(client: Viem.getClient.ReturnType): Promise<num
 const filterSchemas = {
   'block:created': schema.BlockFilters,
   'funding:deposit.updated': schema.FundingDepositFilters,
+  'funding:transfer.updated': schema.FundingTransferFilters,
   'log:emitted': schema.LogFilters,
   'token:transfer': schema.TransferFilters,
   'transaction:included': schema.TxFilters,
@@ -2611,8 +2667,7 @@ function toPublic(subscription: Webhooks.Subscription) {
     ...(subscription.context === undefined ? {} : { context: subscription.context }),
     createdAt: subscription.createdAt,
     destination: redactDestination(subscription.destination),
-    ...(subscription.eventType === 'funding:deposit.updated' &&
-    subscription.environment !== undefined
+    ...(isFundingEventType(subscription.eventType) && subscription.environment !== undefined
       ? { environment: subscription.environment }
       : {}),
     eventType: subscription.eventType,

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

@@ -335,7 +335,7 @@ describe('GET /v1/zones/withdrawals/:senderTag', () => {
     expect(response.status).toBe(403)
     expect(body.error.code).toBe('api_key_forbidden')
     expect(body.error.message).toBe(
-      `Chain id ${runtime.zone.chainId} is a zone. Use an API key granting \`zone:${runtime.zone.chainId}:read\` or \`zone:${runtime.zone.chainId}:write\`.`,
+      `Chain ID ${runtime.zone.chainId} is a Zone. Use an API key granting \`zone:${runtime.zone.chainId}:read\` or \`zone:${runtime.zone.chainId}:write\`.`,
     )
   })
 
@@ -423,7 +423,7 @@ describe('GET /v1/zones/withdrawals/:senderTag', () => {
         },
         {
           "examples": [
-            1424310001,
+            1424310003,
           ],
           "name": "chainId",
           "required": true,

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

@@ -43,7 +43,7 @@ export namespace schema {
       .strictObject({
         chainId: Schema.ChainId.check(
           z.describe('The chain id of the Zone where the withdrawal originated.'),
-          z.meta({ examples: [1_424_310_001] }),
+          z.meta({ examples: [1_424_310_003] }),
         ),
       })
       .check(z.describe('Query parameters used to select the originating Zone.'))

package/src/apps/funding/App.ts

@@ -3,6 +3,8 @@ import { Hono } from 'hono'
 import type * as App from '../../App.js'
 import type * as FundingDepositAddress from '../../internal/funding/DepositAddress.js'
 import type * as FundingProvider from '../../internal/funding/Provider.js'
+import type * as FundingTransferReconciliation from '../../internal/funding/TransferReconciliation.js'
+import type * as Webhooks from '../../internal/Webhooks.js'
 import * as Metadata from '../metadata.js'
 import { chains } from './routes/chains.js'
 import { depositAddresses } from './routes/deposit-addresses.js'
@@ -24,7 +26,7 @@ export function funding(options: funding.Options = {}) {
     .route('/', chains())
     .route('/', providers())
     .route('/', depositAddresses(options))
-    .route('/', transfers())
+    .route('/', transfers(options))
   return Metadata.defaultChain(Metadata.attach(app, openapi))
 }
 
@@ -32,9 +34,17 @@ export declare namespace funding {
   /** Inbound funding route configuration. */
   type Options = {
     /** Enqueues one deposit address for asynchronous reconciliation. */
-    dispatchReconciliation?:
+    dispatchDepositReconciliation?:
       | ((message: FundingProvider.Webhook.receive.Dispatchable) => Promise<void>)
       | undefined
+    /** 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
     /** Registers a created address with a source-chain observer. */
     registerDepositAddress?: ((address: FundingDepositAddress.Public) => Promise<void>) | undefined
   }