tapimo 0.11.0 → 0.13.0

package/src/internal/Webhooks.test.ts

@@ -348,6 +348,41 @@ describe('recordSuccess / recordFailure', () => {
     expect(read?.lastDeliveryAt).toBe('2026-01-01T00:00:00.000Z')
   })
 
+  test('recordSuccess refreshes the stamp at most once per precision window', async () => {
+    const db = TestApp.database()
+    const created = await Webhooks.createSubscription(db, createInput())
+    const stamped = await Webhooks.recordSuccess(db, created, { now: fixedNow })
+    expect(stamped.lastDeliveryAt).toBe(fixedNow().toISOString())
+
+    // A success moments later has nothing to move: the counter is already zero
+    // and the stamp is inside its window, so the row is never rewritten.
+    const soon = new Date(fixedNow().getTime() + 1_000)
+    await Webhooks.recordSuccess(db, stamped, { now: () => soon })
+    const unmoved = await Webhooks.getSubscription(db, apiKeyOwner, created.id)
+    expect(unmoved?.lastDeliveryAt, 'the stored stamp must not move').toBe(fixedNow().toISOString())
+
+    // Past any plausible window; the exact bound is internal.
+    const later = new Date(fixedNow().getTime() + 3_600_000)
+    await Webhooks.recordSuccess(db, stamped, { now: () => later })
+    const moved = await Webhooks.getSubscription(db, apiKeyOwner, created.id)
+    expect(moved?.lastDeliveryAt).toBe(later.toISOString())
+  })
+
+  test('recordSuccess always resets a non-zero failure counter', async () => {
+    const db = TestApp.database()
+    const created = await Webhooks.createSubscription(db, createInput())
+    // Stamp first, so only the counter is out of date: the reset must not be
+    // suppressed by a fresh stamp.
+    const stamped = await Webhooks.recordSuccess(db, created, { now: fixedNow })
+    const failed = await Webhooks.recordFailure(db, stamped, { now: fixedNow })
+    expect(failed.failureCount).toBe(1)
+
+    await Webhooks.recordSuccess(db, failed, { now: fixedNow })
+
+    const read = await Webhooks.getSubscription(db, apiKeyOwner, created.id)
+    expect(read?.failureCount, 'a pending reset must never be skipped').toBe(0)
+  })
+
   test('recordFailure auto-disables at the threshold and drops from the active index', async () => {
     const db = TestApp.database()
     let subscription = await Webhooks.createSubscription(db, createInput())
@@ -375,6 +410,37 @@ describe('recordSuccess / recordFailure', () => {
       await Webhooks.listActiveForChain(db, { chainId: 4217, eventTypes: ['token:transfer'] }),
     ).toMatchInlineSnapshot(`[]`)
   })
+
+  test('recordFailure leaves an already-disabled subscription alone at the cap', async () => {
+    const db = TestApp.database()
+    let subscription = await Webhooks.createSubscription(db, createInput())
+    subscription = await Webhooks.recordFailure(db, subscription, { maxFailures: 2, now: fixedNow })
+    subscription = await Webhooks.recordFailure(db, subscription, { maxFailures: 2, now: fixedNow })
+    expect(subscription.status).toBe('disabled')
+
+    // A straggler failing after the disable has nothing to move: the row is
+    // never rewritten.
+    const later = new Date(fixedNow().getTime() + 1_000)
+    await Webhooks.recordFailure(db, subscription, { maxFailures: 2, now: () => later })
+
+    const read = await Webhooks.getSubscription(db, apiKeyOwner, subscription.id)
+    expect(read?.failureCount, 'the stored counter must not move').toBe(2)
+    expect(read?.updatedAt, 'the stored stamp must not move').toBe(fixedNow().toISOString())
+  })
+
+  test('recordFailure re-disables a re-enabled subscription still at the cap', async () => {
+    const db = TestApp.database()
+    let subscription = await Webhooks.createSubscription(db, createInput())
+    subscription = await Webhooks.recordFailure(db, subscription, { maxFailures: 1, now: fixedNow })
+    expect(subscription.status).toBe('disabled')
+
+    await Webhooks.updateSubscription(db, apiKeyOwner, subscription.id, { status: 'active' })
+
+    // The counter still sits at the cap, so this failure must write again.
+    await Webhooks.recordFailure(db, subscription, { maxFailures: 1, now: fixedNow })
+    const read = await Webhooks.getSubscription(db, apiKeyOwner, subscription.id)
+    expect(read?.status).toBe('disabled')
+  })
 })
 
 describe('sign / verify', () => {
@@ -1015,7 +1081,7 @@ describe('ensureQueueEvents', () => {
     expect(await Webhooks.getQueueEvent(db, reference)).toBeNull()
   })
 
-  test('replaces an expired terminal row so replays stay deliverable', async () => {
+  test('stages a replay once its completion has expired', async () => {
     vi.useFakeTimers({ toFake: ['Date'] })
     vi.setSystemTime(fixedNow())
     try {
@@ -1031,9 +1097,9 @@ describe('ensureQueueEvents', () => {
         }),
       ).toBe(true)
 
-      // Past the dedupe window an unpruned terminal row must not suppress a
+      // Past the dedupe window an unpruned completion must not suppress a
       // replay.
-      vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.deliveryRetentionMs + 1_000))
+      vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.dedupeRetentionMs + 1_000))
       const replay = await Webhooks.ensureQueueEvents(db, [{ envelope, subscription }])
       expect(replay.created).toBe(1)
       await expect(Webhooks.claimQueueEvent(db, reference)).resolves.toMatchObject({
@@ -1044,7 +1110,7 @@ describe('ensureQueueEvents', () => {
     }
   })
 
-  test('refreshes the observation stamp when a replay replaces an expired row', async () => {
+  test('stamps a fresh observation on a post-expiry replay', async () => {
     vi.useFakeTimers({ toFake: ['Date'] })
     vi.setSystemTime(fixedNow())
     try {
@@ -1057,7 +1123,7 @@ describe('ensureQueueEvents', () => {
         status: 'succeeded',
       })
 
-      vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.deliveryRetentionMs + 1_000))
+      vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.dedupeRetentionMs + 1_000))
       const observedAt = Date.now() - 250
       await Webhooks.ensureQueueEvents(db, [{ envelope, subscription }], { observedAt })
 
@@ -1070,6 +1136,38 @@ describe('ensureQueueEvents', () => {
       vi.useRealTimers()
     }
   })
+
+  test('suppresses only the completed obligation when staging a mixed batch', async () => {
+    const db = TestApp.database()
+    const done = await stagedObligation(db, 4)
+    const claim = await Webhooks.claimQueueEvent(db, done.reference)
+    if (claim.type !== 'claimed') throw new Error(`Unexpected claim: ${claim.type}`)
+    await Webhooks.completeQueueEvent(db, done.reference, {
+      claimedAt: claim.record.attemptingAt!,
+      status: 'failed',
+    })
+
+    const fresh = Webhooks.buildEnvelope({
+      blockNumber: 124,
+      createdAt: new Date(),
+      data: { amount: '1' },
+      logIndex: 5,
+      subscription: done.subscription,
+    })
+    const batch = await Webhooks.ensureQueueEvents(db, [
+      { envelope: done.envelope, subscription: done.subscription },
+      { envelope: fresh, subscription: done.subscription },
+    ])
+
+    expect(batch.created).toBe(1)
+    await expect(Webhooks.claimQueueEvent(db, done.reference)).resolves.toEqual({
+      status: 'failed',
+      type: 'terminal',
+    })
+    await expect(Webhooks.claimQueueEvent(db, batch.references[1]!)).resolves.toMatchObject({
+      type: 'claimed',
+    })
+  })
 })
 
 describe('claimQueueEvent', () => {
@@ -1082,6 +1180,22 @@ describe('claimQueueEvent', () => {
     vi.useRealTimers()
   })
 
+  test('reads an expired completion as missing', async () => {
+    const db = TestApp.database()
+    const { reference } = await stagedObligation(db)
+    const claim = await Webhooks.claimQueueEvent(db, reference)
+    if (claim.type !== 'claimed') throw new Error(`Unexpected claim: ${claim.type}`)
+    await Webhooks.completeQueueEvent(db, reference, {
+      claimedAt: claim.record.attemptingAt!,
+      status: 'succeeded',
+    })
+
+    // Matches a pruned terminal row: past the dedupe window the completion is
+    // invisible everywhere, not only to staging.
+    vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.dedupeRetentionMs + 1_000))
+    await expect(Webhooks.claimQueueEvent(db, reference)).resolves.toEqual({ type: 'missing' })
+  })
+
   test('claims a due obligation once and reclaims after staleness', async () => {
     const db = TestApp.database()
     const { reference } = await stagedObligation(db)
@@ -1146,17 +1260,17 @@ describe('claimQueueEvent', () => {
 
     // Pending obligations never expire; only terminal transitions stamp a
     // dedupe deadline.
-    vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.deliveryRetentionMs * 3))
+    vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.dedupeRetentionMs * 3))
     await expect(Webhooks.claimQueueEvent(db, reference)).resolves.toMatchObject({
       type: 'claimed',
     })
   })
 
-  test('never prunes pending work', async () => {
+  test('leaves pending obligations claimable across a prune', async () => {
     const db = TestApp.database()
     const { reference } = await stagedObligation(db)
 
-    vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.deliveryRetentionMs + 1_000))
+    vi.setSystemTime(new Date(fixedNow().getTime() + Webhooks.dedupeRetentionMs + 1_000))
     await Webhooks.pruneExpired(db)
     const claim = await Webhooks.claimQueueEvent(db, reference)
     expect(claim.type).toBe('claimed')

package/src/internal/Webhooks.ts

@@ -3,6 +3,7 @@ import { Hash, Hex } from 'ox'
 import type * as app_Webhooks from '../apps/data/routes/webhooks.js'
 import type * as Db from '../db/Db.js'
 import * as WebhookDeliveries from '../db/tables/webhookDeliveries.js'
+import * as WebhookQueueCompletions from '../db/tables/webhookQueueCompletions.js'
 import * as WebhookQueueEvents from '../db/tables/webhookQueueEvents.js'
 import * as WebhookSubscriptions from '../db/tables/webhookSubscriptions.js'
 import type * as Metrics from '../Metrics.js'
@@ -95,7 +96,8 @@ export type Subscription = {
   filters: Record<string, unknown>
   /** Subscription id (`wh_…`). */
   id: string
-  /** ISO timestamp of the last successful delivery, if any. */
+  /** ISO timestamp of the last successful delivery, if any. Display only:
+   * refreshed at most once per precision window. */
   lastDeliveryAt?: string | undefined
   /** Authenticated owner. */
   owner: Owner
@@ -105,7 +107,8 @@ export type Subscription = {
   secret: string
   /** Lifecycle status. */
   status: Status
-  /** ISO timestamp of the last mutation. */
+  /** ISO timestamp of the last mutation. May lag repeat deliveries; see
+   * `lastDeliveryAt`. */
   updatedAt: string
 }
 
@@ -406,11 +409,18 @@ export async function getCursor(db: Db.Db, subscriptionId: string): Promise<stri
  * deliveries past retention. Reads already filter expiry at query time; this
  * is the janitor reclaiming space, run best-effort on a schedule.
  */
-export async function pruneExpired(db: Db.Db, options: pruneExpired.Options = {}): Promise<void> {
+export async function pruneExpired(
+  db: Db.Db,
+  options: pruneExpired.Options = {},
+): Promise<pruneExpired.Result> {
   const iso = (options.now ?? (() => new Date()))().toISOString()
-  await WebhookDeliveries.pruneExpired(db, iso)
-  await WebhookQueueEvents.pruneExpired(db, iso)
-  await WebhookSubscriptions.pruneExpired(db, iso)
+  // Sequential on purpose: the subscription delete cascades into the other
+  // tables, so overlapping it with their prunes risks deadlocks.
+  return {
+    completions: await WebhookQueueCompletions.pruneExpired(db, iso),
+    deliveries: await WebhookDeliveries.pruneExpired(db, iso),
+    subscriptions: await WebhookSubscriptions.pruneExpired(db, iso),
+  }
 }
 
 export declare namespace pruneExpired {
@@ -419,6 +429,16 @@ export declare namespace pruneExpired {
     /** Clock used for expiry evaluation; injectable for tests. */
     now?: (() => Date) | undefined
   }
+
+  /** Rows deleted per table; a count pinned at the batch bound means expiry is outpacing pruning. */
+  type Result = {
+    /** Deleted `webhook_queue_completions` rows. */
+    completions: number
+    /** Deleted `webhook_deliveries` rows. */
+    deliveries: number
+    /** Deleted `webhook_subscriptions` rows. */
+    subscriptions: number
+  }
 }
 
 /**
@@ -427,6 +447,13 @@ export declare namespace pruneExpired {
  */
 export const deliveryRetentionMs = 7 * 24 * 60 * 60 * 1_000
 
+/**
+ * Completions dedupe window: replays of a completed obligation are suppressed
+ * this long. Deliberately its own literal so per-deployment log-retention
+ * tuning cannot move it.
+ */
+export const dedupeRetentionMs = 7 * 24 * 60 * 60 * 1_000
+
 /** A compact Cloudflare Queue message referencing a durable staged envelope. */
 export type QueueReference = {
   /** Idempotent event id of the staged envelope. */
@@ -441,8 +468,6 @@ export type QueueEvent = QueueReference & {
   createdAt: string
   /** Full envelope loaded by the Queue consumer. */
   envelope: Envelope
-  /** ISO timestamp after which an unconsumed envelope may be pruned. */
-  expiresAt: string
 }
 
 /** A claim newer than this counts as an in-flight attempt; above the 10s destination timeout default. */
@@ -467,7 +492,6 @@ export async function ensureQueueEvents(
   options: ensureQueueEvents.Options = {},
 ): Promise<ensureQueueEvents.Result> {
   const now = (options.now ?? (() => new Date()))()
-  const expiresAt = new Date(now.getTime() + (options.ttl ?? deliveryRetentionMs)).toISOString()
   // Carried so the delivery worker can measure observation-to-attempt without
   // re-reading the block; replays have no observation and stay null.
   const observedAt =
@@ -476,9 +500,6 @@ export async function ensureQueueEvents(
     createdAt: now.toISOString(),
     envelope,
     eventId: envelope.id,
-    // Inert while pending; the meaningful dedupe deadline is stamped at
-    // terminal transitions.
-    expiresAt,
     // Due immediately; the value orders the sweep so it is never null here.
     nextAttemptAt: now.toISOString(),
     observedAt,
@@ -499,14 +520,12 @@ export declare namespace ensureQueueEvents {
     subscription: Subscription
   }
 
-  /** Staged-envelope retention options. */
+  /** Staging options. */
   type Options = {
     /** Clock used for staging timestamps. */
     now?: (() => Date) | undefined
     /** Epoch ms the head owing these events was observed; absent on replays. */
     observedAt?: number | undefined
-    /** Staged-envelope TTL in ms; defaults to {@link deliveryRetentionMs}. */
-    ttl?: number | undefined
   }
 
   /** Created-row count plus references for every requested obligation. */
@@ -542,7 +561,7 @@ export function completeQueueEvent(
 ): Promise<boolean> {
   return WebhookQueueEvents.complete(db, reference, {
     ...options,
-    expiresAt: new Date(Date.now() + deliveryRetentionMs).toISOString(),
+    expiresAt: new Date(Date.now() + dedupeRetentionMs).toISOString(),
   })
 }
 
@@ -552,7 +571,7 @@ export declare namespace completeQueueEvent {
     /** Claim marker from the claimed record's `attemptingAt`. */
     claimedAt: string
     /** Terminal obligation outcome. */
-    status: WebhookQueueEvents.TerminalStatus
+    status: WebhookQueueCompletions.TerminalStatus
   }
 }
 
@@ -766,10 +785,17 @@ export async function getDelivery(
  */
 export const maxFailures = 10
 
+/**
+ * How stale `lastDeliveryAt` may get before a success rewrites it. Read only
+ * for display, so exactness is traded for not rewriting the row per delivery.
+ */
+const lastDeliveryPrecisionMs = 60_000
+
 /**
  * Records a successful delivery: resets the consecutive-failure counter and
- * stamps `lastDeliveryAt`. A column-targeted update, so a concurrent patch is
- * never clobbered by the stale copy carried through the delivery queue.
+ * refreshes `lastDeliveryAt` at most once per precision window. Returns the
+ * written row, or the caller's snapshot when the write was skipped or the row
+ * deleted.
  */
 export async function recordSuccess(
   db: Db.Db,
@@ -777,11 +803,13 @@ export async function recordSuccess(
   options: recordSuccess.Options = {},
 ): Promise<Subscription> {
   const now = (options.now ?? (() => new Date()))()
-  const iso = now.toISOString()
-  const next = await WebhookSubscriptions.recordSuccess(db, subscription.id, iso)
-  // A concurrently deleted subscription is not resurrected; return the
-  // optimistic next state so the caller still observes the outcome.
-  return next ?? { ...subscription, failureCount: 0, lastDeliveryAt: iso, updatedAt: iso }
+  const next = await WebhookSubscriptions.recordSuccess(db, subscription.id, {
+    now: now.toISOString(),
+    staleBefore: new Date(now.getTime() - lastDeliveryPrecisionMs).toISOString(),
+  })
+  // No row means the write was skipped or the row was deleted; neither
+  // resurrects, so keep the caller's timestamps.
+  return next ?? { ...subscription, failureCount: 0 }
 }
 
 export declare namespace recordSuccess {
@@ -796,7 +824,9 @@ export declare namespace recordSuccess {
  * Records a failed delivery: atomically increments the consecutive-failure
  * counter and, once it reaches `maxFailures`, sets `status: 'disabled'` so the
  * subscription drops out of the partial active index (surfaced via the API).
- * Returns the updated subscription.
+ * Once disabled at the cap the row is left alone, so an outage's in-flight
+ * failures stop contending on its lock. Returns the written row, or the
+ * caller's snapshot advanced optimistically.
  */
 export async function recordFailure(
   db: Db.Db,
@@ -808,14 +838,14 @@ export async function recordFailure(
   const max = options.maxFailures ?? maxFailures
   const next = await WebhookSubscriptions.recordFailure(db, subscription.id, max, iso)
   if (next) return next
-  // A concurrently deleted subscription is not resurrected; return the
-  // optimistic next state so the caller still observes the outcome.
-  const failureCount = subscription.failureCount + 1
+  // No row means skipped (already disabled at the cap) or deleted; neither
+  // resurrects, so keep the caller's timestamps. Capped so chained skips
+  // cannot grow the counter past what the store would hold.
+  const failureCount = Math.min(subscription.failureCount + 1, max)
   return {
     ...subscription,
     failureCount,
     ...(failureCount >= max ? { status: 'disabled' as const } : {}),
-    updatedAt: iso,
   }
 }
 

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

@@ -132,7 +132,47 @@ describe('validateEvmCalls', () => {
         sourceTokenAddress: sourceToken,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[Funding.Action.InvalidActionError: Stablecoin funding calls must not carry native value.]`,
+      `[Funding.Action.InvalidActionError: Native value must match a validated provider fee.]`,
     )
   })
+
+  test('accepts an exact provider-validated native value', () => {
+    Action.validateEvmCalls({
+      action: {
+        calls: [approveCall(1_000_000n), { ...depositCall, value: '0x10' }],
+        type: 'evm:calls',
+      },
+      nativeValues: [{ to: spender, value: '0x10' }],
+      sourceAmount: '1000000',
+      sourceTokenAddress: sourceToken,
+    })
+  })
+
+  test('rejects malformed native value allowances', () => {
+    expect(() =>
+      Action.validateEvmCalls({
+        action: { calls: [approveCall(1_000_000n), depositCall], type: 'evm:calls' },
+        nativeValues: [{ to: spender, value: '10' }],
+        sourceAmount: '1000000',
+        sourceTokenAddress: sourceToken,
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Funding.Action.InvalidActionError: Malformed native value allowance.]`,
+    )
+  })
+
+  test('rejects native values outside the exact provider allowance', () => {
+    for (const call of [
+      { ...depositCall, to: `0x${'99'.repeat(20)}`, value: '0x10' },
+      { ...depositCall, value: '0x11' },
+    ])
+      expect(() =>
+        Action.validateEvmCalls({
+          action: { calls: [approveCall(1_000_000n), call], type: 'evm:calls' },
+          nativeValues: [{ to: spender, value: '0x10' }],
+          sourceAmount: '1000000',
+          sourceTokenAddress: sourceToken,
+        }),
+      ).toThrow(Action.InvalidActionError)
+  })
 })

package/src/internal/funding/Action.ts

@@ -1,6 +1,8 @@
 import { AbiFunction, Address, type Hex, Solidity } from 'ox'
 import * as z from 'zod/mini'
 
+import * as OpenApi from '../OpenApi.js'
+
 /**
  * Executable source-chain actions returned by funding transfer creation. A
  * strict discriminated union: transfer reads never include an action.
@@ -12,49 +14,58 @@ const approveSelector = AbiFunction.getSelector(approve)
 /** Zod schemas owned by funding actions. */
 export namespace schema {
   /** One unsigned EVM call, in the exchange quote API's call shape. */
-  export const Call = z
-    .object({
-      data: z
-        .string()
-        .check(
-          z.regex(/^0x(?:[0-9a-fA-F]{2})*$/),
-          z.describe('ABI-encoded calldata.'),
-          z.meta({ examples: ['0x095ea7b3'] }),
-        ),
-      to: z
-        .string()
-        .check(
-          z.regex(/^0x[0-9a-fA-F]{40}$/),
-          z.describe('Contract the call targets.'),
-          z.meta({ examples: [`0x${'44'.repeat(20)}`] }),
-        ),
-      value: z
-        .string()
-        .check(
-          z.regex(/^0x[0-9a-fA-F]+$/),
-          z.describe('Native value to send, as hex.'),
-          z.meta({ examples: ['0x0'] }),
-        ),
-    })
-    .check(z.describe('One unsigned EVM call.'))
+  export const Call = OpenApi.component(
+    z
+      .object({
+        data: z
+          .string()
+          .check(
+            z.regex(/^0x(?:[0-9a-fA-F]{2})*$/),
+            z.describe('ABI-encoded calldata.'),
+            z.meta({ examples: ['0x095ea7b3'] }),
+          ),
+        to: z
+          .string()
+          .check(
+            z.regex(/^0x[0-9a-fA-F]{40}$/),
+            z.describe('Contract the call targets.'),
+            z.meta({ examples: [`0x${'44'.repeat(20)}`] }),
+          ),
+        value: z
+          .string()
+          .check(
+            z.regex(/^0x[0-9a-fA-F]+$/),
+            z.describe('Native value to send, as hex.'),
+            z.meta({ examples: ['0x0'] }),
+          ),
+      })
+      .check(z.describe('One unsigned EVM call.')),
+    'FundingActionCall',
+  )
 
   /** Ordered unsigned EVM calls the caller signs and submits on the source chain. */
-  export const EvmCalls = z
-    .object({
-      calls: z
-        .array(Call)
-        .check(
-          z.minLength(1),
-          z.describe('Calls in submission order; they may require separate transactions.'),
-        ),
-      type: z.literal('evm:calls').check(z.describe('Action kind.')),
-    })
-    .check(z.describe('Ordered unsigned EVM calls to sign and submit on the source chain.'))
+  export const EvmCalls = OpenApi.component(
+    z
+      .object({
+        calls: z
+          .array(Call)
+          .check(
+            z.minLength(1),
+            z.describe('Calls in submission order; they may require separate transactions.'),
+          ),
+        type: z.literal('evm:calls').check(z.describe('Action kind.')),
+      })
+      .check(z.describe('Ordered unsigned EVM calls to sign and submit on the source chain.')),
+    'FundingEvmCallsAction',
+  )
 
   /** Executable source-chain action attached to a creation response. */
-  export const Action = z
-    .discriminatedUnion('type', [EvmCalls])
-    .check(z.describe('Executable source-chain action. Never returned by transfer reads.'))
+  export const Action = OpenApi.component(
+    z
+      .discriminatedUnion('type', [EvmCalls])
+      .check(z.describe('Executable source-chain action. Never returned by transfer reads.')),
+    'FundingAction',
+  )
 }
 
 /** One unsigned EVM call (see {@link schema.Call}). */
@@ -66,6 +77,14 @@ export type EvmCalls = z.output<typeof schema.EvmCalls>
 /** Executable source-chain action (see {@link schema.Action}). */
 export type Action = z.output<typeof schema.Action>
 
+/** One exact native-value allowance established by provider-specific validation. */
+export type NativeValue = {
+  /** Contract that may receive the native value. */
+  to: string
+  /** Exact native value allowed, as a JSON-RPC quantity. */
+  value: string
+}
+
 /**
  * Validates prepared EVM calls before persistence. Token calls, approval
  * targets, spenders, amounts, selectors, and native value must match the route.
@@ -73,9 +92,16 @@ export type Action = z.output<typeof schema.Action>
 export function validateEvmCalls(options: validateEvmCalls.Options): void {
   const action = schema.EvmCalls.safeParse(options.action)
   if (!action.success) throw new InvalidActionError('Malformed EVM calls.')
+  const nativeValues = new Set<string>()
+  for (const { to, value } of options.nativeValues ?? []) {
+    if (!Address.validate(to, { strict: false }) || !/^0x[0-9a-fA-F]+$/.test(value))
+      throw new InvalidActionError('Malformed native value allowance.')
+    nativeValues.add(`${to.toLowerCase()}:${BigInt(value).toString()}`)
+  }
   for (const [index, call] of action.data.calls.entries()) {
-    if (BigInt(call.value) !== 0n)
-      throw new InvalidActionError('Stablecoin funding calls must not carry native value.')
+    const callValue = BigInt(call.value)
+    if (callValue > 0n && !nativeValues.has(`${call.to.toLowerCase()}:${callValue.toString()}`))
+      throw new InvalidActionError('Native value must match a validated provider fee.')
     const targetsSourceToken = Address.isEqual(
       call.to as Address.Address,
       options.sourceTokenAddress as Address.Address,
@@ -104,6 +130,8 @@ export declare namespace validateEvmCalls {
   type Options = {
     /** The prepared action to validate. */
     action: EvmCalls
+    /** Exact native values established by provider-specific validation. */
+    nativeValues?: readonly NativeValue[] | undefined
     /** Source amount in base units. */
     sourceAmount: string
     /** Source token contract address. */

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

@@ -309,3 +309,37 @@ describe('route capabilities', () => {
     ).toThrow()
   })
 })
+
+describe('route configuration', () => {
+  const configuration = { poolAddress: `0x${'11'.repeat(20)}` }
+
+  test('carries configuration into hydrated provider routes', () => {
+    const snapshot = Catalog.compile(rows({ routes: [{ ...data.routes[0]!, configuration }] }))
+    expect(snapshot.routes[0]?.configuration).toStrictEqual(configuration)
+    expect(snapshot.routesByProvider.get('relay')?.[0]?.configuration).toStrictEqual(configuration)
+  })
+
+  test('omits configuration when it is absent or null', () => {
+    const absent = Catalog.compile(rows())
+    const nulled = Catalog.compile(rows({ routes: [{ ...data.routes[0]!, configuration: null }] }))
+    expect('configuration' in absent.routes[0]!).toBe(false)
+    expect('configuration' in nulled.routes[0]!).toBe(false)
+  })
+
+  test('publishes configuration through the write boundary', async () => {
+    const db = TestApp.database()
+    const snapshot = await Catalog.publish(db, {
+      ...data,
+      routes: [{ ...data.routes[0]!, configuration }],
+    })
+    expect(snapshot.routes[0]?.configuration).toStrictEqual(configuration)
+  })
+
+  test('rejects non-object configuration', () => {
+    expect(() =>
+      Catalog.compile(
+        rows({ routes: [{ ...data.routes[0]!, configuration: 'invalid' as never }] }),
+      ),
+    ).toThrow()
+  })
+})