tapimo 0.13.0 → 0.14.0

package/src/db/tables/webhookSubscriptions.ts

@@ -310,11 +310,11 @@ function privateResourceAccess(access: Webhooks.Access) {
   )
   return (eb: ExpressionBuilder<Db.Database, 'webhook_subscriptions'>) =>
     eb.or([
-      eb('eventType', '!=', 'funding:deposit.updated'),
+      sql<boolean>`${eb.ref('eventType')} not like ${'funding:%'}`,
       ...(fundingRead
         ? [
             eb.and([
-              eb('eventType', '=', 'funding:deposit.updated'),
+              sql<boolean>`${eb.ref('eventType')} like ${'funding:%'}`,
               eb('environment', '=', access.environment),
               ...(access.projectId === undefined ? [] : [eb('projectId', '=', access.projectId)]),
             ]),
@@ -390,41 +390,48 @@ export declare namespace listActiveForChain {
   }
 }
 
-/** Lists live funding deposit subscriptions visible to one deposit owner. */
-export async function listActiveForFundingDeposit(
+/** Lists live funding subscriptions visible to one resource owner. */
+export async function listActiveForFundingEvent(
   db: Db.Db,
-  options: listActiveForFundingDeposit.Options,
+  options: listActiveForFundingEvent.Options,
 ): Promise<Webhooks.Subscription[]> {
   let query = db.kysely
     .selectFrom('webhook_subscriptions')
     .selectAll()
     .where('chainId', '=', options.chainId)
     .where('environment', '=', options.environment)
-    .where('eventType', '=', 'funding:deposit.updated')
+    .where('eventType', '=', options.eventType)
     .where('ownerId', '=', options.orgId)
     .where('ownerType', '=', 'api_key')
     .where('status', '=', 'active')
     .where(live(options.now))
+  if (options.eventCreatedAt !== undefined)
+    query = query.where('createdAt', '<=', options.eventCreatedAt)
   const projectId = options.projectId
   query =
     projectId === undefined
       ? query.where('projectId', 'is', null)
       : query.where((eb) => eb.or([eb('projectId', 'is', null), eb('projectId', '=', projectId)]))
-  return (await query.orderBy('id').execute()).map(toSubscription)
+  // Keep subscriptions present until their staged queue events commit.
+  return (await query.orderBy('id').forKeyShare().execute()).map(toSubscription)
 }
 
-export declare namespace listActiveForFundingDeposit {
-  /** Ownership scope and chain for a funding deposit event. */
+export declare namespace listActiveForFundingEvent {
+  /** Ownership scope and chain for a funding resource event. */
   type Options = {
     /** Destination Tempo chain id. */
     chainId: number
-    /** Deposit API-key environment. */
+    /** Resource API-key environment. */
     environment: 'production' | 'sandbox'
+    /** Event timestamp used to keep subscriptions future-only, when supplied. */
+    eventCreatedAt?: string | undefined
+    /** Funding event type to match. */
+    eventType: Extract<Webhooks.EventType, `funding:${string}`>
     /** ISO timestamp used to exclude expired subscriptions. */
     now: string
     /** Owning organization id. */
     orgId: string
-    /** Attributed deposit project, when present. */
+    /** Attributed funding resource project, when present. */
     projectId?: string | undefined
   }
 }

package/src/internal/EarnVaults.ts

@@ -157,7 +157,7 @@ export namespace schema {
       ),
       vaultAddress: Schema.Address.check(
         z.describe('Earn vault contract address.'),
-        z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] }),
+        z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
       ),
     })
     .check(z.describe('Onchain identity of an Earn vault.'))
@@ -167,7 +167,7 @@ export namespace schema {
     .strictObject({
       chainId: Schema.ChainId.check(
         z.describe('Private Zone chain id.'),
-        z.meta({ examples: [1424310003] }),
+        z.meta({ examples: [421700001] }),
       ),
       deploymentBlock: z
         .number()
@@ -175,11 +175,11 @@ export namespace schema {
           z.int(),
           z.nonnegative(),
           z.describe('Parent-chain block that deployed the Earn router.'),
-          z.meta({ examples: [31730087] }),
+          z.meta({ examples: [35816964] }),
         ),
       earnRouter: Schema.Address.check(
         z.describe('Parent-chain router for this Zone and Earn vault.'),
-        z.meta({ examples: ['0xebedc74ffeead186acc6cac05eb82fb9e093a7c7'] }),
+        z.meta({ examples: ['0x8117e0ba6239b9695f780deb010f72a2fa4bdfb6'] }),
       ),
     })
     .check(z.describe('Curated Earn route through one private Zone.'))
@@ -239,7 +239,7 @@ export namespace schema {
       state,
       vaultAddress: Schema.Address.check(
         z.describe('Earn vault contract address.'),
-        z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] }),
+        z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
       ),
     })
     .check(z.describe('Live state resolved from an Earn vault.'))

package/src/internal/Log.test-d.ts

@@ -29,6 +29,8 @@ test('bounds sponsorship diagnostics', () => {
     'fee_token_unsupported',
     'internal_error',
     'production_api_key_required',
+    'project_id_invalid',
+    'project_id_required',
     'spend_limit_exceeded',
     'tx_fee_limit_exceeded',
   ] as const satisfies readonly Log.SponsorshipReason[]

package/src/internal/Log.ts

@@ -104,6 +104,8 @@ export type SponsorshipReason =
   | 'fee_token_unsupported'
   | 'internal_error'
   | 'production_api_key_required'
+  | 'project_id_invalid'
+  | 'project_id_required'
   | 'spend_limit_exceeded'
   | 'tx_fee_limit_exceeded'
 

package/src/internal/Viem.ts

@@ -1,6 +1,12 @@
 import { ZoneRpcAuthentication } from 'ox/tempo'
-import { createClient, http, publicActions } from 'viem'
-import type { Chain as core_Chain, Client as core_Client, HttpTransport, PublicActions } from 'viem'
+import { createClient as core_createClient, fallback, http, publicActions } from 'viem'
+import type {
+  Chain as core_Chain,
+  Client as core_Client,
+  FallbackTransport,
+  HttpTransport,
+  PublicActions,
+} from 'viem'
 import { tempoActions } from 'viem/tempo'
 import type { TempoActions } from 'viem/tempo'
 import { tempoMainnet, tempoTestnet } from 'viem/tempo/chains'
@@ -51,6 +57,36 @@ export type UrlResolver =
 /** Headers required when connecting to a Zone upstream. */
 export type ZoneHeaders = Record<string, string>
 
+/** Creates a generic EVM client with ordered RPC endpoint fallback. */
+export function createEvmClient(options: createEvmClient.Options): createEvmClient.ReturnType {
+  return core_createClient({
+    transport: fallback(
+      options.urls.map((url) =>
+        http(url, {
+          fetchFn: options.fetch,
+          ...(options.signal ? { fetchOptions: { signal: options.signal } } : {}),
+          retryCount: 0,
+        }),
+      ),
+    ),
+  })
+}
+
+export declare namespace createEvmClient {
+  /** Generic EVM RPC client configuration. */
+  type Options = {
+    /** Fetch implementation used for RPC requests. */
+    fetch: typeof globalThis.fetch
+    /** Optional request cancellation signal. */
+    signal?: AbortSignal | undefined
+    /** Ordered RPC endpoint URLs. */
+    urls: readonly string[]
+  }
+
+  /** Generic EVM client with fallback transport. */
+  type ReturnType = core_Client<FallbackTransport, undefined, undefined>
+}
+
 /** Returns chain ids declared by a static chain-id-to-URL map. */
 export function configuredChainIds(value: UrlResolver | undefined): number[] {
   const urls = parseUrls(value)
@@ -158,7 +194,7 @@ export function getClient(options: getClient.Options): getClient.ReturnType {
         }
       : undefined
 
-  return createClient({
+  return core_createClient({
     // Auto-batch `eth_call`s within the same macrotask into a single
     // deployless multicall. Lets call sites issue `Promise.all` of N reads
     // (e.g. `balanceOf` across many tokens) and pay one RPC round-trip.

package/src/internal/Webhooks.test.ts

@@ -1,5 +1,7 @@
 import { Webhooks } from 'tapimo'
+import { sql } from 'kysely'
 import * as TestApp from '../../test/App.js'
+import * as WebhookSubscriptions from '../db/tables/webhookSubscriptions.js'
 import * as Metrics from '../Metrics.js'
 import * as Cursor from './Cursor.js'
 
@@ -170,6 +172,49 @@ describe('createSubscription', () => {
   })
 })
 
+describe('listActiveForFundingEvent', () => {
+  test('keeps selected subscriptions until the caller transaction commits', async () => {
+    const getDb = TestApp.databaseFactory()
+    const owner = { orgId: 'org_funding_subscription_lock', type: 'api_key' } as const
+    const subscription = await Webhooks.createSubscription(
+      getDb(),
+      createInput({
+        environment: 'production',
+        eventType: 'funding:transfer.updated',
+        owner,
+      }),
+    )
+    const locked = Promise.withResolvers<void>()
+    const release = Promise.withResolvers<void>()
+    const read = getDb().transaction(async (tx) => {
+      const subscriptions = await WebhookSubscriptions.listActiveForFundingEvent(tx, {
+        chainId: 4217,
+        environment: 'production',
+        eventType: 'funding:transfer.updated',
+        now: new Date().toISOString(),
+        orgId: owner.orgId,
+      })
+      locked.resolve()
+      await release.promise
+      return subscriptions
+    })
+    await locked.promise
+
+    const deletion = await getDb()
+      .transaction(async (tx) => {
+        await sql`select set_config('lock_timeout', '100ms', true)`.execute(tx.kysely)
+        return Webhooks.deleteSubscription(tx, owner, subscription.id)
+      })
+      .catch((cause: unknown) => cause)
+    release.resolve()
+
+    await expect(read).resolves.toEqual([subscription])
+    expect(deletion).toBeInstanceOf(Error)
+    expect(String(deletion)).toContain('lock timeout')
+    await expect(Webhooks.deleteSubscription(getDb(), owner, subscription.id)).resolves.toBe(true)
+  })
+})
+
 describe('owner isolation', () => {
   test('an owner cannot read or list another owner subscriptions', async () => {
     const db = TestApp.database()

package/src/internal/funding/DepositWebhook.ts

@@ -37,9 +37,10 @@ export async function stage(
   for (const record of unique(options.records)) {
     const chainId = destinationChainId(record)
     if (chainId === undefined) continue
-    const subscriptions = await WebhookSubscriptions.listActiveForFundingDeposit(db, {
+    const subscriptions = await WebhookSubscriptions.listActiveForFundingEvent(db, {
       chainId,
       environment: record.environment,
+      eventType: 'funding:deposit.updated',
       now,
       orgId: record.orgId,
       ...(record.projectId === null ? {} : { projectId: record.projectId }),

package/src/internal/funding/Evidence.ts

@@ -1,5 +1,5 @@
 import { AbiEvent, Address, Base58, Bytes, Hash, Hex, RpcSchema, RpcTransport } from 'ox'
-import { createClient, custom, fallback, TransactionReceiptNotFoundError } from 'viem'
+import { TransactionReceiptNotFoundError } from 'viem'
 import { getBlockNumber, getTransactionReceipt } from 'viem/actions'
 import * as z from 'zod/mini'
 
@@ -195,7 +195,7 @@ async function verifyEvm(
   parameters: Reconciliation.VerifyTransfers.Parameters,
   options: FetchOptions & { confirmations: number },
 ): Promise<readonly Reconciliation.TransferEvidence[]> {
-  const client = jsonRpcClient(options)
+  const client = Viem.createEvmClient(options)
   const [receipt, head] = await Promise.all([
     getTransactionReceipt(client, { hash: parameters.transactionHash as Hex.Hex }).catch(
       (cause) => {
@@ -334,17 +334,6 @@ async function verifyTron(
   })
 }
 
-function jsonRpcClient(options: FetchOptions) {
-  return createClient({
-    transport: fallback(
-      options.urls.map((url) => {
-        const transport = RpcTransport.fromHttp(url, { fetchFn: options.fetch })
-        return custom(transport, { retryCount: 0 })
-      }),
-    ),
-  })
-}
-
 async function requestSolana(
   options: FetchOptions,
   request: SolanaRpcSchema['Request'],

package/src/internal/funding/Provider.ts

@@ -232,6 +232,7 @@ export namespace schema {
         token: z.optional(TokenRef),
       }),
     ),
+    providerState: z.optional(z.record(z.string(), z.unknown())),
     quality: GetQuoteResult.shape.quality,
     sampledAt: z.iso.datetime(),
   })
@@ -485,6 +486,36 @@ export declare namespace validateTransferAction {
   }
 }
 
+/** Contract for provider-specific source transaction verification. */
+export declare namespace verifySourceTransaction {
+  /** Stored transfer terms and submitted source transaction. */
+  type Parameters = {
+    /** Configured chain that receives the provider delivery. */
+    destinationChain: Chain
+    /** Private provider state captured while preparing the transfer. */
+    providerState?: Transfer.ProviderState | undefined
+    /** Current configuration for the stored provider route. */
+    routeConfiguration?: core_Catalog.Configuration | undefined
+    /** Configured chain containing the submitted transaction. */
+    sourceChain: Chain
+    /** Submitted transaction reference. */
+    transactionHash: string
+    /** Stored public transfer terms. */
+    transfer: Transfer.Snapshot
+  }
+
+  /** Source transaction verification outcome. */
+  type ReturnType =
+    | { type: 'invalid' }
+    | { type: 'pending' }
+    | {
+        /** Private provider evidence retained for reconciliation. */
+        providerState?: Transfer.ProviderState | undefined
+        /** The transaction matches the stored transfer terms. */
+        type: 'verified'
+      }
+}
+
 /** Contract of the provider `createDepositAddress` method. */
 export declare namespace createDepositAddress {
   /** Input passed to a provider provisioning one reusable deposit address. */
@@ -705,6 +736,11 @@ export type Provider<id extends string = string> = core_Provider.Provider<id, 'f
   validateTransferAction?(
     input: validateTransferAction.Parameters,
   ): validateTransferAction.ReturnType
+  /** Verifies a submitted source transaction, when supported. */
+  verifySourceTransaction?(
+    input: verifySourceTransaction.Parameters,
+    signal: AbortSignal,
+  ): Promise<verifySourceTransaction.ReturnType>
   /** Receives authenticated provider status events, when configured. */
   webhook?: Webhook | undefined
 }
@@ -756,6 +792,13 @@ export function canObserveDepositAddressRequest(provider: Provider): provider is
   return typeof provider.observeDepositAddressRequest === 'function'
 }
 
+/** Narrows a funding provider to one that verifies submitted source transactions. */
+export function canVerifySourceTransaction(provider: Provider): provider is Provider & {
+  verifySourceTransaction: NonNullable<Provider['verifySourceTransaction']>
+} {
+  return typeof provider.verifySourceTransaction === 'function'
+}
+
 /** Narrows a funding provider to one with authenticated webhook receipt. */
 export function canReceiveWebhook(provider: Provider): provider is Provider & {
   webhook: Webhook

package/src/internal/funding/SourceObservation.ts

@@ -1,10 +1,10 @@
-import { AbiEvent, Address, RpcTransport } from 'ox'
-import { createClient, custom, fallback } from 'viem'
+import { AbiEvent, Address } from 'ox'
 import { getBlockNumber, getLogs } from 'viem/actions'
 
 import type * as Db from '../../db/Db.js'
 import * as FundingDepositAddresses from '../../db/tables/fundingDepositAddresses.js'
 import * as FundingDeposits from '../../db/tables/fundingDeposits.js'
+import * as Viem from '../Viem.js'
 import * as Value from '../Value.js'
 import * as Deposit from './Deposit.js'
 
@@ -52,13 +52,9 @@ export async function scan(options: scan.Options): Promise<scan.Result> {
     throw new ConfigurationError('source token address')
   if (options.rpcUrls.length === 0) throw new ConfigurationError('source RPC URL')
 
-  const client = createClient({
-    transport: fallback(
-      options.rpcUrls.map((url) => {
-        const transport = RpcTransport.fromHttp(url, { fetchFn: options.fetch ?? globalThis.fetch })
-        return custom(transport, { retryCount: 0 })
-      }),
-    ),
+  const client = Viem.createEvmClient({
+    fetch: options.fetch ?? globalThis.fetch,
+    urls: options.rpcUrls,
   })
   const head = await getBlockNumber(client, { cacheTime: 0 })
   const confirmations = BigInt(options.confirmations ?? defaultConfirmations)

package/src/internal/funding/Transfer.test.ts

@@ -42,6 +42,7 @@ describe('canTransition', () => {
         "completed": [],
         "expired": [],
         "processing": [
+          "awaiting-source",
           "refunding",
           "completed",
           "action-required",
@@ -129,6 +130,160 @@ describe('create', () => {
   })
 })
 
+describe('registerSourceTransaction', () => {
+  const transactionHash = `0x${'a2'.repeat(32)}`
+
+  test('atomically assigns source evidence and starts reconciliation', async () => {
+    const record = await Transfer.create(
+      db,
+      createInput({
+        providerState: {
+          routeConfiguration: {
+            destinationPoolAddress: `0x${'cc'.repeat(20)}`,
+            poolAddress: `0x${'dd'.repeat(20)}`,
+            sourceEid: 30_184,
+          },
+        },
+        snapshot: TestFunding.transferSnapshot({ provider: { id: 'stargate', name: 'Stargate' } }),
+      }),
+    )
+    vi.setSystemTime(new Date('2026-01-01T00:00:10.000Z'))
+    const result = await Transfer.registerSourceTransaction(db, {
+      chainId: 'eip155:8453',
+      id: record.id,
+      providerState: { stargate: { guid: `0x${'bb'.repeat(32)}`, sourceEid: 30_184 } },
+      transactionHash: `0x${'a1'.repeat(32)}`,
+    })
+    expect(result.type).toBe('registered')
+    if (result.type !== 'registered') return
+    expect({
+      providerState: result.record.providerState,
+      sourceTransactionHashes: result.record.snapshot.sourceTransactionHashes,
+      status: result.record.status,
+      version: result.record.version,
+    }).toMatchInlineSnapshot(`
+      {
+        "providerState": {
+          "routeConfiguration": {
+            "destinationPoolAddress": "0xcccccccccccccccccccccccccccccccccccccccc",
+            "poolAddress": "0xdddddddddddddddddddddddddddddddddddddddd",
+            "sourceEid": 30184,
+          },
+          "stargate": {
+            "guid": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+            "sourceEid": 30184,
+          },
+        },
+        "sourceTransactionHashes": [
+          "0xa1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
+        ],
+        "status": "processing",
+        "version": 2,
+      }
+    `)
+  })
+
+  test('replays the same assignment and rejects reuse by another transfer', async () => {
+    const first = await Transfer.create(db, createInput())
+    const second = await Transfer.create(db, createInput())
+    const options = {
+      chainId: 'eip155:8453',
+      id: first.id,
+      providerState: { stargate: { guid: `0x${'bb'.repeat(32)}`, sourceEid: 30_184 } },
+      transactionHash,
+    }
+    await Transfer.registerSourceTransaction(db, options)
+    const replayed = await Transfer.registerSourceTransaction(db, options)
+    const conflict = await Transfer.registerSourceTransaction(db, { ...options, id: second.id })
+    expect({
+      conflict: conflict.type,
+      replayed: replayed.type,
+      replayedVersion: replayed.type === 'replayed' ? replayed.record.version : undefined,
+    }).toEqual({ conflict: 'conflict', replayed: 'replayed', replayedVersion: 2 })
+  })
+})
+
+describe('reopenSourceTransaction', () => {
+  test('removes invalidated source evidence and accepts a replacement', async () => {
+    const record = await Transfer.create(db, createInput())
+    const transactionHash = `0x${'a4'.repeat(32)}`
+    await Transfer.registerSourceTransaction(db, {
+      chainId: 'eip155:8453',
+      id: record.id,
+      providerState: { stargate: { guid: `0x${'bb'.repeat(32)}`, sourceEid: 30_184 } },
+      transactionHash,
+    })
+
+    const reopened = await Transfer.reopenSourceTransaction(db, {
+      chainId: 'eip155:8453',
+      id: record.id,
+      providerState: { routeConfiguration: { poolAddress: `0x${'cc'.repeat(20)}` } },
+      transactionHash: transactionHash.toUpperCase(),
+    })
+    expect(reopened.type).toBe('reopened')
+    if (reopened.type !== 'reopened') return
+    expect({
+      providerState: reopened.record.providerState,
+      sourceTransactionHashes: reopened.record.snapshot.sourceTransactionHashes,
+      status: reopened.record.status,
+      version: reopened.record.version,
+    }).toEqual({
+      providerState: { routeConfiguration: { poolAddress: `0x${'cc'.repeat(20)}` } },
+      sourceTransactionHashes: undefined,
+      status: 'awaiting-source',
+      version: 3,
+    })
+
+    const replacement = await Transfer.registerSourceTransaction(db, {
+      chainId: 'eip155:8453',
+      id: record.id,
+      providerState: { stargate: { guid: `0x${'dd'.repeat(32)}`, sourceEid: 30_184 } },
+      transactionHash: `0x${'a5'.repeat(32)}`,
+    })
+    expect(replacement.type).toBe('registered')
+  })
+})
+
+describe('complete', () => {
+  test('records verified destination evidence and completes once', async () => {
+    const record = await Transfer.create(db, createInput())
+    await Transfer.registerSourceTransaction(db, {
+      chainId: 'eip155:8453',
+      id: record.id,
+      providerState: { stargate: { guid: `0x${'bb'.repeat(32)}`, sourceEid: 30_184 } },
+      transactionHash: `0x${'a3'.repeat(32)}`,
+    })
+    const options = {
+      chainId: 'eip155:4217',
+      destinationAmount: TestFunding.transferSnapshot().destinationAmount!,
+      id: record.id,
+      transactionHash: `0x${'cc'.repeat(32)}`,
+    }
+    const completed = await Transfer.complete(db, options)
+    const replayed = await Transfer.complete(db, options)
+    expect({
+      completed: completed.type,
+      destinationTransactionHashes:
+        completed.type === 'completed'
+          ? completed.record.snapshot.destinationTransactionHashes
+          : undefined,
+      replayed: replayed.type,
+      status: completed.type === 'completed' ? completed.record.status : undefined,
+      version: completed.type === 'completed' ? completed.record.version : undefined,
+    }).toMatchInlineSnapshot(`
+      {
+        "completed": "completed",
+        "destinationTransactionHashes": [
+          "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+        ],
+        "replayed": "replayed",
+        "status": "completed",
+        "version": 3,
+      }
+    `)
+  })
+})
+
 describe('transition', () => {
   test('applies a guarded status change and appends an event', async () => {
     const record = await Transfer.create(db, createInput())