tapimo 0.12.0 → 0.14.0

package/src/apps/relay/App.ts

@@ -7,9 +7,11 @@ import { Addresses, TokenId, Transaction } from 'viem/tempo'
 import type * as App from '../../App.js'
 import * as BillingSettings from '../../db/tables/billingSettings.js'
 import * as Db from '../../db/Db.js'
+import * as Organizations from '../../db/tables/organizations.js'
+import * as Projects from '../../db/tables/projects.js'
+import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as Fees from '../../internal/Fees.js'
 import * as Log from '../../internal/Log.js'
-import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as Billing from '../management/Billing.js'
 import * as Handler from '../../Handler.js'
 import * as Auth from '../../internal/Auth.js'
@@ -85,6 +87,7 @@ function middleware(options: middleware.Options) {
     : 0n
   return createMiddleware<App.Environment>(async (c) => {
     const principal = Auth.getPrincipal(c)
+    const requestedAt = new Date().toISOString()
     const verifiedTokens = c.get('verifiedTokens')
     const zoneToken_header = c.req.header(ZoneRpcAuthentication.headerName)
     const zoneToken = zoneToken_header?.trim() ? zoneToken_header : undefined
@@ -97,7 +100,11 @@ function middleware(options: middleware.Options) {
 
     const recordRejection = (options: middleware.Rejection) => {
       const id =
-        Number.isSafeInteger(options.chainId) && options.chainId >= 0 ? options.chainId : null
+        options.chainId !== undefined &&
+        Number.isSafeInteger(options.chainId) &&
+        options.chainId >= 0
+          ? options.chainId
+          : null
       if (chainId !== null) chainId = chainId === undefined || chainId === id ? id : null
       if (options.reason === 'internal_error') internalErrors = Math.min(internalErrors + 1, 65_535)
       if (reason !== null)
@@ -121,22 +128,49 @@ function middleware(options: middleware.Options) {
       throw new Error('Internal error', { cause: new Error(options.message) })
     }
 
-    const feePayer = (() => {
+    const feePayer = await (async () => {
       if (!options.feePayer) return undefined
-      const attribution =
-        principal?.type === 'api_key'
-          ? {
-              apiKeyId: principal.id,
-              environment: principal.environment,
-              orgId: principal.orgId,
-              ...(principal.projectId === undefined ? {} : { projectId: principal.projectId }),
-            }
-          : undefined
+      const resolved = await resolveAttribution(Db.get(c.get('db')), {
+        principal,
+        projectId: c.req.header('tempo-project-id')?.trim(),
+      })
+      const attribution = resolved?.attribution
+      const attributionError = resolved?.error
       const sponsorable =
         attribution !== undefined &&
         principal?.type === 'api_key' &&
         (principal.apiKey.scopes.includes('rpc-relay:sponsor') ||
           principal.apiKey.scopes.includes(Scope.wildcard))
+      let promotionState_promise: Promise<middleware.PromotionState>
+      const promotionState = () =>
+        (promotionState_promise ??= (async () => {
+          if (!attribution) return { status: 'inactive' }
+          const db = Db.get(c.get('db'))
+          const organization = await Organizations.get(db, attribution.orgId)
+          if (!organization || organization.sponsorshipSubsidyDurationDays === null)
+            return { status: 'inactive' }
+          // Missing project attribution opts out of the subsidy but must not interrupt sponsorship.
+          if (!attribution.projectId) return { status: 'inactive' }
+          const project = await Projects.get(db, attribution.projectId)
+          if (!project) return { message: 'Attributed project disappeared.', status: 'error' }
+          if (project.orgId !== attribution.orgId)
+            return { message: 'Attributed project changed ownership.', status: 'error' }
+          if (
+            (project.sponsorshipSubsidyStartsAt === null) !==
+            (project.sponsorshipSubsidyEndsAt === null)
+          )
+            return { message: 'Project promotion window is inconsistent.', status: 'error' }
+          if (
+            project.sponsorshipSubsidyEndsAt !== null &&
+            Date.parse(requestedAt) >= Date.parse(project.sponsorshipSubsidyEndsAt)
+          )
+            return { status: 'inactive' }
+          return { status: 'active' }
+        })())
+      const validatePromotion = async (chainId: number) => {
+        const state = await promotionState()
+        if (state.status === 'error') failSponsorship({ chainId, message: state.message })
+      }
       // Lifted so validation and the sponsored-token default read one value.
       const feeToken_sponsor = options.feePayer.feeToken ?? Addresses.pathUsd
       return {
@@ -147,6 +181,12 @@ function middleware(options: middleware.Options) {
           // only mainnet: the relay resolves chainId from the request body, so
           // the query-string chain guard never sees it.
           const id = Number(transaction.chainId)
+          if (attributionError)
+            rejectSponsorship({
+              chainId: id,
+              message: 'Project attribution rejected.',
+              reason: attributionError,
+            })
           if (!attribution) {
             if (sponsorshipRequired)
               rejectSponsorship({
@@ -186,15 +226,9 @@ function middleware(options: middleware.Options) {
               })
             return false
           }
-
-          // Enforcement reads hit the primary, never the cached replica: a
-          // stale `past_due`, a lowered limit, or another isolate's pending
-          // spend must not keep the gate open.
           const db = Db.get(c.get('db'))
-          // Mainnet sponsorship requires an active billing source; deployments
-          // without billing configured have no rows, so mainnet stays closed.
-          // `past_due` gets its own reason: the caller must settle an invoice,
-          // not attach a card.
+          // Enforcement reads hit the primary, never the cached replica: a
+          // stale `past_due` or another isolate's state must not keep the gate open.
           const billing = await Billing.status(db, attribution.orgId)
           if (billing === 'past_due') {
             if (sponsorshipRequired)
@@ -214,6 +248,7 @@ function middleware(options: middleware.Options) {
               })
             return 'billing_required'
           }
+          await validatePromotion(id)
 
           const feeToken = (() => {
             try {
@@ -286,7 +321,6 @@ function middleware(options: middleware.Options) {
           // reconciliation convention; pending rows charge it to spend limits.
           const feeMax = Fees.maxOf(Transaction.deserialize(event.transaction as `0x76${string}`))
           const db = Db.get(c.get('db'))
-
           const feeToken = (() => {
             try {
               return event.feeToken !== undefined ? TokenId.toAddress(event.feeToken) : undefined
@@ -318,13 +352,54 @@ function middleware(options: middleware.Options) {
           // Re-read settings on the authoritative path: the limit may have
           // changed since `validate`, and only mainnet spend is limited.
           const settings = mainnet ? await BillingSettings.get(db, attribution.orgId) : undefined
-          if (settings?.spendLimit == null) return void (await SponsoredTransactions.upsert(db, input)) // prettier-ignore
+          const billingLimit =
+            settings?.spendLimit == null
+              ? undefined
+              : {
+                  chainIds: [Viem.chainId.mainnet],
+                  max: Billing.toBaseUnits(settings.spendLimit),
+                  since: Billing.periodStart(settings.period),
+                }
+          if (
+            mainnet &&
+            attribution.environment === 'production' &&
+            attribution.projectId !== undefined
+          )
+            try {
+              const promotion = await SponsoredTransactions.reservePromotion(
+                db,
+                { ...input, billable: false },
+                {
+                  at: new Date().toISOString(),
+                  ...(billingLimit ? { billingLimit } : {}),
+                  chainIds: [Viem.chainId.mainnet],
+                  projectId: attribution.projectId,
+                },
+              )
+              if (promotion.status !== 'ineligible') return
+            } catch (error) {
+              if (error instanceof SponsoredTransactions.AttributionConflictError)
+                rejectSponsorship({
+                  chainId: event.chainId,
+                  message: 'Project attribution rejected.',
+                  reason: 'project_id_invalid',
+                })
+              if (error instanceof SponsoredTransactions.PromotionActivationError)
+                failSponsorship({
+                  chainId: event.chainId,
+                  message: 'Project promotion activation failed.',
+                })
+              if (error instanceof SponsoredTransactions.PeriodSpendLimitError)
+                rejectSponsorship({
+                  chainId: event.chainId,
+                  message: 'Spend limit exceeded.',
+                  reason: 'spend_limit_exceeded',
+                })
+              throw error
+            }
+          if (!billingLimit) return void (await SponsoredTransactions.upsert(db, input))
           try {
-            await SponsoredTransactions.reserve(db, input, {
-              chainIds: [Viem.chainId.mainnet],
-              max: Billing.toBaseUnits(settings.spendLimit),
-              since: Billing.periodStart(settings.period),
-            })
+            await SponsoredTransactions.reserve(db, input, billingLimit)
           } catch (error) {
             if (error instanceof SponsoredTransactions.PeriodSpendLimitError)
               rejectSponsorship({
@@ -518,6 +593,57 @@ function sponsorshipMethod(value: unknown): Log.SponsorshipMethod | undefined {
   }
 }
 
+/** Resolves optional request-level project attribution within the API key's organization. */
+async function resolveAttribution(
+  db: Db.Db,
+  options: resolveAttribution.Options,
+): Promise<resolveAttribution.Result | undefined> {
+  if (options.principal?.type !== 'api_key') return undefined
+  const { principal } = options
+  const attribution = {
+    apiKeyId: principal.id,
+    environment: principal.environment,
+    orgId: principal.orgId,
+    ...(principal.projectId === undefined ? {} : { projectId: principal.projectId }),
+  }
+  if (!options.projectId) return { attribution }
+  if (principal.projectId !== undefined) return { attribution, error: 'project_id_invalid' }
+  const project = await Projects.get(db, options.projectId)
+  if (!project || project.orgId !== principal.orgId)
+    return { attribution, error: 'project_id_invalid' }
+  return { attribution: { ...attribution, projectId: project.id } }
+}
+
+declare namespace resolveAttribution {
+  /** Inputs for resolving API-key project attribution. */
+  type Options = {
+    /** Authenticated request principal. */
+    principal: Auth.Principal | null
+    /** Optional project id supplied by the caller. */
+    projectId?: string | undefined
+  }
+
+  /** Resolved API-key attribution. */
+  type Attribution = {
+    /** API key id. */
+    apiKeyId: string
+    /** API key environment. */
+    environment: 'production' | 'sandbox'
+    /** API key organization id. */
+    orgId: string
+    /** Attributed project id. */
+    projectId?: string | undefined
+  }
+
+  /** Attribution result with an optional policy error. */
+  type Result = {
+    /** Attribution retained for request diagnostics. */
+    attribution: Attribution
+    /** Project attribution error detected before transaction validation. */
+    error?: 'project_id_invalid' | undefined
+  }
+}
+
 declare namespace middleware {
   /** One invariant sponsorship failure. */
   type Failure = {
@@ -535,10 +661,13 @@ declare namespace middleware {
     path: 'rpc/relay' | 'rpc/sponsor'
   }
 
+  /** Cached promotion validation state; request accounting is applied per batch item. */
+  type PromotionState = { status: 'active' | 'inactive' } | { message: string; status: 'error' }
+
   /** One sponsorship rejection recorded for request logging. */
   type Rejection = {
     /** Candidate transaction chain, validated before it enters the log entry. */
-    chainId: number
+    chainId?: number | undefined
     /** Stable client error code. */
     reason: Log.SponsorshipReason
   }
@@ -546,7 +675,7 @@ declare namespace middleware {
   /** One client-visible sponsorship refusal. */
   type Refusal = {
     /** Candidate transaction chain. */
-    chainId: number
+    chainId?: number | undefined
     /** Client-safe error message. */
     message: string
     /** Stable client error code. */

package/src/apps/relay/Sponsorships.ts

@@ -11,6 +11,7 @@ import { getTransactionReceipt } from 'viem/actions'
 
 import * as Db from '../../db/Db.js'
 import * as BillingSettings from '../../db/tables/billingSettings.js'
+import * as Projects from '../../db/tables/projects.js'
 import * as Fees from '../../internal/Fees.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as Tidx from '../../internal/Tidx.js'
@@ -292,7 +293,29 @@ export function createFinalizer(options: createFinalizer.Options): createFinaliz
               getClient,
               getTidx: (chainId) => getTidx(chainId as Viem.ChainId),
               limitFor: async (intent) => {
-                if (!intent.billable || !Viem.isMainnet(intent.chainId)) return undefined
+                if (!Viem.isMainnet(intent.chainId)) return undefined
+                if (!intent.billable) {
+                  if (!intent.projectId) return undefined
+                  const project = await Projects.get(db, intent.projectId)
+                  // Missing promotion state cannot prove the intent remains within Tempo's budget.
+                  if (!project || project.sponsorshipSubsidyStartsAt === null)
+                    return {
+                      billable: false,
+                      chainIds: [Viem.chainId.mainnet],
+                      max: -1n,
+                      projectId: intent.projectId,
+                      since: intent.createdAt,
+                    }
+                  if (project.sponsorshipSpendLimit === null) return undefined
+                  return {
+                    billable: false,
+                    chainIds: [Viem.chainId.mainnet],
+                    max: BigInt(project.sponsorshipSpendLimit),
+                    projectId: intent.projectId,
+                    since: project.sponsorshipSubsidyStartsAt,
+                  }
+                }
+                if (!intent.billable) return undefined
                 const settings = await BillingSettings.get(db, intent.orgId)
                 if (settings?.spendLimit == null) return undefined
                 return {

package/src/db/Db.ts

@@ -1483,6 +1483,46 @@ export const migrations: readonly Migration[] = [
         sql`ALTER TABLE earn_vaults ADD COLUMN IF NOT EXISTS zones jsonb NOT NULL DEFAULT '[]'::jsonb`,
       ),
   },
+  {
+    name: '0137_funding_routes_configuration',
+    up: (db) =>
+      raw(db, sql`ALTER TABLE funding_routes ADD COLUMN IF NOT EXISTS configuration jsonb`),
+  },
+  {
+    name: '0138_organizations_sponsorship_subsidy',
+    up: (db) =>
+      raw(
+        db,
+        sql`ALTER TABLE organizations
+          ADD COLUMN IF NOT EXISTS sponsorship_subsidy_duration_days integer,
+          ADD COLUMN IF NOT EXISTS sponsorship_subsidy_project_spend_limit text`,
+      ),
+  },
+  {
+    name: '0139_projects_sponsorship_activation',
+    up: (db) =>
+      raw(
+        db,
+        sql`ALTER TABLE projects
+          ADD COLUMN IF NOT EXISTS sponsorship_subsidy_starts_at text,
+          ADD COLUMN IF NOT EXISTS sponsorship_subsidy_ends_at text,
+          DROP CONSTRAINT IF EXISTS projects_sponsorship_subsidy_window_consistent,
+          ADD CONSTRAINT projects_sponsorship_subsidy_window_consistent CHECK ((sponsorship_subsidy_starts_at IS NULL) = (sponsorship_subsidy_ends_at IS NULL))`,
+      ),
+  },
+  {
+    name: '0140_projects_sponsorship_spend_limit',
+    up: (db) =>
+      raw(db, sql`ALTER TABLE projects ADD COLUMN IF NOT EXISTS sponsorship_spend_limit text`),
+  },
+  {
+    name: '0141_sponsored_transactions_promotion_spend_index',
+    up: (db) =>
+      raw(
+        db,
+        sql`CREATE INDEX IF NOT EXISTS sponsored_transactions_promotion_spend_idx ON sponsored_transactions (org_id, project_id, status, created_at) WHERE NOT billable`,
+      ),
+  },
 ]
 
 /**
@@ -1620,7 +1660,14 @@ declare namespace fromDialect {
  */
 export function postgres(options: postgres.Options): Db {
   const { connectionString, schema } = options
-  const pool = new pg.Pool(schema ? { connectionString, max: 1 } : { connectionString })
+  // Bounded connect and pool-checkout wait: the pg default (0) waits forever,
+  // so an unresponsive origin parks callers and their invocation memory
+  // invisibly instead of failing into the retry paths.
+  const pool = new pg.Pool({
+    connectionString,
+    connectionTimeoutMillis: 30_000,
+    ...(schema ? { max: 1 } : {}),
+  })
   return fromDialect(new PostgresDialect({ pool }), { schema })
 }
 

package/src/db/Schema.ts

@@ -219,6 +219,12 @@ export const Organization = z.object({
   name: z
     .string()
     .check(z.describe('Human-readable organization name.'), z.meta({ examples: ['Acme, Inc.'] })),
+  sponsorshipSubsidyDurationDays: z
+    .nullable(z.number().check(z.int(), z.positive()))
+    .check(z.describe('Promotional sponsorship duration in days, or null when disabled.')),
+  sponsorshipSubsidyProjectSpendLimit: z
+    .nullable(z.string())
+    .check(z.describe('Per-project promotional spend cap in decimal USD, or null when disabled.')),
   updatedAt: z.string().check(z.describe('When the organization was last updated (ISO 8601).')),
   userId: z
     .nullable(z.string())
@@ -243,6 +249,15 @@ export const Project = z.object({
     .string()
     .check(z.describe('Human-readable project name.'), z.meta({ examples: ['Checkout'] })),
   orgId: z.string().check(z.describe('Owning organization id (`org_…`).')),
+  sponsorshipSubsidyStartsAt: z
+    .nullable(z.string())
+    .check(z.describe('When the project first activated promotional sponsorship, or null.')),
+  sponsorshipSubsidyEndsAt: z
+    .nullable(z.string())
+    .check(z.describe('When the project promotional sponsorship ends, or null.')),
+  sponsorshipSpendLimit: z
+    .nullable(z.string())
+    .check(z.describe('Promotional spend cap in fee-token base units, or null.')),
   updatedAt: z.string().check(z.describe('When the project was last updated (ISO 8601).')),
 })
 
@@ -453,11 +468,14 @@ export type FundingChainToken = z.output<typeof FundingChainToken>
 
 /** One source-to-destination route supported by a funding provider. */
 export const FundingRoute = z.object({
-  destinationChainId: z.string().check(z.describe('Destination funding chain identifier.')),
-  destinationTokenId: z.string().check(z.describe('Destination funding token identifier.')),
   capabilities: z
     .nullable(z.custom<funding_Catalog.Capabilities>())
     .check(z.describe('Executable capability (`jsonb`), or null for indicative-only routes.')),
+  configuration: z
+    .nullable(z.custom<funding_Catalog.Configuration>())
+    .check(z.describe('Provider-specific route configuration (`jsonb`), or null.')),
+  destinationChainId: z.string().check(z.describe('Destination funding chain identifier.')),
+  destinationTokenId: z.string().check(z.describe('Destination funding token identifier.')),
   providerId: z.string().check(z.describe('Funding provider identifier.')),
   sourceChainId: z.string().check(z.describe('Source funding chain identifier.')),
   sourceTokenId: z.string().check(z.describe('Source funding token identifier.')),
@@ -637,8 +655,8 @@ export const FundingTransfer = z.object({
     .check(z.describe('Attributed project id (`prj_…`), or null for organization-attributed keys.')), // prettier-ignore
   providerId: z.string().check(z.describe('Selected funding provider id.')),
   providerState: z
-    .nullable(z.custom<funding_Provider.prepareTransfer.Correlation>())
-    .check(z.describe('Private provider correlation (`jsonb`), or null. Never serialized publicly.')), // prettier-ignore
+    .nullable(z.custom<funding_Transfer.ProviderState>())
+    .check(z.describe('Private provider state (`jsonb`), or null. Never serialized publicly.')), // prettier-ignore
   quoteExpiresAt: z
     .string()
     .check(z.describe('When the quoted terms stop being executable (ISO 8601).')),

package/src/db/tables/earnVaults.test.ts

@@ -13,9 +13,9 @@ const input = {
   vaultAddress: '0x2f05f4d3625B2eFFb383eFbEDAFd2D8F04371636',
   zones: [
     {
-      chainId: 1_424_310_001,
-      deploymentBlock: 31_039_238,
-      earnRouter: '0x9144086A79dea966d8bf1B52125eBED8919fC45c',
+      chainId: 1_424_310_003,
+      deploymentBlock: 31_730_087,
+      earnRouter: '0xeBEdC74FFeEAD186ACC6caC05Eb82fB9e093a7c7',
     },
   ],
 } as const satisfies EarnVaults.upsert.Options
@@ -45,9 +45,9 @@ describe('upsert', () => {
           "vaultAddress": "0x2f05f4d3625b2effb383efbedafd2d8f04371636",
           "zones": [
             {
-              "chainId": 1424310001,
-              "deploymentBlock": 31039238,
-              "earnRouter": "0x9144086a79dea966d8bf1b52125ebed8919fc45c",
+              "chainId": 1424310003,
+              "deploymentBlock": 31730087,
+              "earnRouter": "0xebedc74ffeead186acc6cac05eb82fb9e093a7c7",
             },
           ],
         }
@@ -93,9 +93,9 @@ describe('upsert', () => {
           "updatedAt": "2026-01-02T00:00:00.000Z",
           "zones": [
             {
-              "chainId": 1424310001,
-              "deploymentBlock": 31039238,
-              "earnRouter": "0x9144086a79dea966d8bf1b52125ebed8919fc45c",
+              "chainId": 1424310003,
+              "deploymentBlock": 31730087,
+              "earnRouter": "0xebedc74ffeead186acc6cac05eb82fb9e093a7c7",
             },
           ],
         }

package/src/db/tables/fundingCatalog.test.ts

@@ -71,8 +71,12 @@ describe('publish', () => {
       catalog: head,
       chainTokens: catalog.chainTokens,
       chains: catalog.chains,
-      // Absent `capabilities` persists as null (indicative-only).
-      routes: catalog.routes.map((route) => ({ ...route, capabilities: null })),
+      // Optional route JSON persists as null.
+      routes: catalog.routes.map((route) => ({
+        ...route,
+        capabilities: null,
+        configuration: null,
+      })),
       tokens: catalog.tokens,
     })
   })
@@ -87,6 +91,16 @@ describe('publish', () => {
     expect((await FundingCatalog.read(db)).routes[0]?.capabilities).toStrictEqual(capabilities)
   })
 
+  test('round-trips route configuration', async () => {
+    const db = TestApp.database()
+    const configuration = { poolAddress: `0x${'11'.repeat(20)}` }
+    await FundingCatalog.publish(db, {
+      ...catalog,
+      routes: [{ ...catalog.routes[0]!, configuration }],
+    })
+    expect((await FundingCatalog.read(db)).routes[0]?.configuration).toStrictEqual(configuration)
+  })
+
   test('replaces rows and advances the catalog version', async () => {
     const db = TestApp.database()
     const first = await FundingCatalog.publish(db, catalog)

package/src/db/tables/fundingCatalog.ts

@@ -28,10 +28,12 @@ export type ChainTokenTable = db_Schema.FundingChainToken
 /** Columns of the `funding_routes` table. */
 export type RouteTable = db_Schema.FundingRoute
 
-/** A route row whose `capabilities` may be absent (validated input, fixtures). */
-export type RouteRow = Omit<db_Schema.FundingRoute, 'capabilities'> & {
+/** A route row whose optional JSON fields may be absent in validated input. */
+export type RouteRow = Omit<db_Schema.FundingRoute, 'capabilities' | 'configuration'> & {
   /** Executable capability; absent and null both mean indicative-only. */
   capabilities?: db_Schema.FundingRoute['capabilities'] | undefined
+  /** Provider-specific route configuration; absent and null are equivalent. */
+  configuration?: db_Schema.FundingRoute['configuration'] | undefined
 }
 
 /** Stored funding catalog rows and version metadata. */
@@ -117,7 +119,11 @@ export function publish(db: Db.Db, input: publish.Input): Promise<db_Schema.Fund
       await tx.kysely
         .insertInto('funding_routes')
         .values(
-          input.routes.map((route) => ({ ...route, capabilities: route.capabilities ?? null })),
+          input.routes.map((route) => ({
+            ...route,
+            capabilities: route.capabilities ?? null,
+            configuration: route.configuration ?? null,
+          })),
         )
         .execute()
 

package/src/db/tables/fundingTransferTransactions.test.ts

@@ -67,3 +67,46 @@ describe('insert', () => {
     ])
   })
 })
+
+describe('claimSource', () => {
+  test('returns claimed, replayed, and conflicting ownership outcomes', async () => {
+    const first = await createTransfer('ftr_claim_first')
+    const second = await createTransfer('ftr_claim_second')
+    const record = {
+      chainId: 'eip155:8453',
+      createdAt: '2026-01-01T00:00:01.000Z',
+      role: 'source' as const,
+      transactionRef: `0x${'cd'.repeat(32)}`,
+      transferId: first.id,
+    }
+    const claimed = await FundingTransferTransactions.claimSource(db, record)
+    const replayed = await FundingTransferTransactions.claimSource(db, record)
+    const conflict = await FundingTransferTransactions.claimSource(db, {
+      ...record,
+      transferId: second.id,
+    })
+    expect([claimed.type, replayed.type, conflict.type]).toEqual([
+      'claimed',
+      'replayed',
+      'conflict',
+    ])
+  })
+})
+
+describe('getSource', () => {
+  test('resolves EVM hashes case-insensitively', async () => {
+    const transfer = await createTransfer('ftr_get_source')
+    await FundingTransferTransactions.claimSource(db, {
+      chainId: 'eip155:8453',
+      createdAt: '2026-01-01T00:00:01.000Z',
+      role: 'source',
+      transactionRef: `0x${'ce'.repeat(32)}`,
+      transferId: transfer.id,
+    })
+    const record = await FundingTransferTransactions.getSource(db, {
+      chainId: 'eip155:8453',
+      transactionRef: `0x${'CE'.repeat(32)}`,
+    })
+    expect(record?.transferId).toBe(transfer.id)
+  })
+})