tapimo 0.0.2 → 0.2.0

package/src/apps/relay/Sponsorships.test.ts

@@ -0,0 +1,375 @@
+import { nanoid } from 'nanoid'
+import { TxEnvelopeTempo } from 'ox/tempo'
+import type { Client } from 'viem'
+
+import { postgresUrl } from '../../../test/containers.js'
+import * as Db from '../../db/Db.js'
+import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
+import * as Sponsorships from './Sponsorships.js'
+
+const create = () => Db.postgres({ connectionString: postgresUrl, schema: `t_${nanoid()}` })
+
+/** Baseline insert input; tests override per case. */
+const input = {
+  apiKeyId: 'key_1',
+  billable: true,
+  chainId: 42431,
+  environment: 'production',
+  orgId: 'org_1',
+  projectId: 'prj_1',
+  signPayload: `0x${'bb'.repeat(32)}`,
+  transaction: `0x76${'cc'.repeat(16)}`,
+  transactionHash: `0x${'aa'.repeat(32)}`,
+} satisfies SponsoredTransactions.upsert.Input
+
+/** Stubs the receipt lookup: hashes present in `receipts` resolve, others null. */
+function client(receipts: Record<string, { effectiveGasPrice: string; gasUsed: string }>): Client {
+  return {
+    request: async ({ params }: { params: readonly [string] }) => receipts[params[0]] ?? null,
+  } as never
+}
+
+describe('finalize', () => {
+  test('behavior: finalizes mined rows with gasUsed × effectiveGasPrice', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await SponsoredTransactions.upsert(db, input)
+
+    const result = await Sponsorships.finalize(db, {
+      getClient: () =>
+        client({ [input.transactionHash]: { effectiveGasPrice: '0x3', gasUsed: '0x5208' } }),
+    })
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "failed": 0,
+        "finalized": 1,
+        "pending": 0,
+      }
+    `)
+    const finalized = await SponsoredTransactions.get(db, record.id)
+    expect(finalized?.status).toMatchInlineSnapshot(`"finalized"`)
+    // 21000 gas × 3 = 63000 base units.
+    expect(finalized?.feeAmount).toMatchInlineSnapshot(`"63000"`)
+    expect(finalized?.finalizedAt).not.toBeNull()
+    await db.close()
+  })
+
+  test('behavior: leaves young unmined rows pending', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await SponsoredTransactions.upsert(db, input)
+
+    const result = await Sponsorships.finalize(db, { getClient: () => client({}) })
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "failed": 0,
+        "finalized": 0,
+        "pending": 1,
+      }
+    `)
+    expect((await SponsoredTransactions.get(db, record.id))?.status).toMatchInlineSnapshot(
+      `"pending"`,
+    )
+    await db.close()
+  })
+
+  test('behavior: hash-less fill intents settle by TTL without a receipt lookup', async () => {
+    const db = create()
+    await db.migrate()
+    const { transactionHash: _, ...intent } = input
+    const record = await SponsoredTransactions.upsert(db, intent)
+
+    // Young intent: left pending; the stub client would throw if queried.
+    const young = await Sponsorships.finalize(db, {
+      getClient: () => {
+        throw new Error('unexpected receipt lookup for a hash-less intent')
+      },
+    })
+    expect(young).toMatchInlineSnapshot(`
+      {
+        "failed": 0,
+        "finalized": 0,
+        "pending": 1,
+      }
+    `)
+
+    // Past the TTL: fails with no fee.
+    const settled = await Sponsorships.finalize(db, {
+      getClient: () => {
+        throw new Error('unexpected receipt lookup for a hash-less intent')
+      },
+      now: () => new Date(Date.now() + 2 * 3_600_000),
+    })
+    expect(settled).toMatchInlineSnapshot(`
+      {
+        "failed": 1,
+        "finalized": 0,
+        "pending": 0,
+      }
+    `)
+    expect((await SponsoredTransactions.get(db, record.id))?.status).toMatchInlineSnapshot(
+      `"failed"`,
+    )
+    await db.close()
+  })
+
+  test('behavior: fails unmined rows past the pending TTL', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await SponsoredTransactions.upsert(db, input)
+
+    const result = await Sponsorships.finalize(db, {
+      getClient: () => client({}),
+      now: () => new Date(Date.now() + 2 * 3_600_000),
+    })
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "failed": 1,
+        "finalized": 0,
+        "pending": 0,
+      }
+    `)
+    const failed = await SponsoredTransactions.get(db, record.id)
+    expect(failed?.status).toMatchInlineSnapshot(`"failed"`)
+    expect(failed?.feeAmount).toBeNull()
+    await db.close()
+  })
+
+  test('behavior: an erroring receipt lookup leaves the row pending, even past the TTL', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await SponsoredTransactions.upsert(db, input)
+
+    const result = await Sponsorships.finalize(db, {
+      getClient: () =>
+        ({
+          request: async () => {
+            throw new Error('rpc outage')
+          },
+        }) as never,
+      now: () => new Date(Date.now() + 2 * 3_600_000),
+    })
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "failed": 0,
+        "finalized": 0,
+        "pending": 1,
+      }
+    `)
+    expect((await SponsoredTransactions.get(db, record.id))?.status).toMatchInlineSnapshot(
+      `"pending"`,
+    )
+    await db.close()
+  })
+
+  test('behavior: an erroring receipt lookup fails past the error TTL', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await SponsoredTransactions.upsert(db, input)
+
+    const result = await Sponsorships.finalize(db, {
+      getClient: () =>
+        ({
+          request: async () => {
+            throw new Error('rpc outage')
+          },
+        }) as never,
+      now: () => new Date(Date.now() + 25 * 3_600_000),
+    })
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "failed": 1,
+        "finalized": 0,
+        "pending": 0,
+      }
+    `)
+    expect((await SponsoredTransactions.get(db, record.id))?.status).toMatchInlineSnapshot(
+      `"failed"`,
+    )
+    await db.close()
+  })
+
+  test('behavior: batchSize caps rows processed per pass', async () => {
+    const db = create()
+    await db.migrate()
+    await SponsoredTransactions.upsert(db, { ...input, signPayload: `0x${'b1'.repeat(32)}`, transactionHash: `0x${'a1'.repeat(32)}` }) // prettier-ignore
+    await SponsoredTransactions.upsert(db, { ...input, signPayload: `0x${'b2'.repeat(32)}`, transactionHash: `0x${'a2'.repeat(32)}` }) // prettier-ignore
+
+    // Both hashes are mined so the outcome is order-independent.
+    const receipts = {
+      [`0x${'a1'.repeat(32)}`]: { effectiveGasPrice: '0x1', gasUsed: '0x1' },
+      [`0x${'a2'.repeat(32)}`]: { effectiveGasPrice: '0x1', gasUsed: '0x1' },
+    }
+    const result = await Sponsorships.finalize(db, {
+      batchSize: 1,
+      getClient: () => client(receipts),
+    })
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "failed": 0,
+        "finalized": 1,
+        "pending": 0,
+      }
+    `)
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(1)
+    await db.close()
+  })
+})
+
+describe('reconcile', () => {
+  const sender = '0x407368320192a21238825437c02c2e2a34ffc38d'
+  const minedHash = `0x${'dd'.repeat(32)}`
+
+  /** The mined sponsored envelope, in ox form. */
+  const mined = TxEnvelopeTempo.from({
+    calls: [{ data: '0x', to: '0x20c0000000000000000000000000000000000001', value: 0n }],
+    chainId: 42431,
+    gas: 100_000n,
+    maxFeePerGas: 1_000_000n,
+    maxPriorityFeePerGas: 0n,
+    nonce: 0n,
+    nonceKey: 0n,
+  })
+
+  /** The intent's identity, computed exactly as the recording sites do. */
+  const signPayload = TxEnvelopeTempo.getFeePayerSignPayload(mined, { sender })
+
+  /** Fakes the node: `eth_getRawTransactionByHash` serves the mined bytes. */
+  const rpc = {
+    request: async () => TxEnvelopeTempo.serialize(mined),
+  } as never as Client
+
+  /** Fakes the indexer: the fee payer's recent transactions. */
+  const tidx = (rows: readonly { from: string; hash: string }[]) =>
+    ({ fetch: async () => ({ rows }) }) as never
+
+  test('behavior: matches intents by sign payload and fills the hash', async () => {
+    const db = create()
+    await db.migrate()
+    const { transactionHash: _, ...rest } = input
+    const intent = await SponsoredTransactions.upsert(db, { ...rest, signPayload })
+
+    const result = await Sponsorships.reconcile(db, {
+      feePayer: '0xFee0000000000000000000000000000000000000',
+      getClient: () => rpc,
+      getTidx: () => tidx([{ from: sender, hash: minedHash }]),
+    })
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "matched": 1,
+        "scanned": 1,
+      }
+    `)
+    const matched = await SponsoredTransactions.get(db, intent.id)
+    expect(matched?.transactionHash).toBe(minedHash)
+    expect(matched?.status).toMatchInlineSnapshot(`"pending"`)
+    await db.close()
+  })
+
+  test('behavior: recovers recently failed intents by sign payload', async () => {
+    const db = create()
+    await db.migrate()
+    const { transactionHash: _, ...rest } = input
+    const intent = await SponsoredTransactions.upsert(db, { ...rest, signPayload })
+    await SponsoredTransactions.fail(db, intent.id, '2026-01-01T00:00:00.000Z')
+
+    vi.useFakeTimers({ now: new Date('2026-01-01T00:01:00.000Z') })
+    const result = await (async () => {
+      try {
+        return await Sponsorships.reconcile(db, {
+          feePayer: '0xFee0000000000000000000000000000000000000',
+          getClient: () => rpc,
+          getTidx: () => tidx([{ from: sender, hash: minedHash }]),
+        })
+      } finally {
+        vi.useRealTimers()
+      }
+    })()
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "matched": 1,
+        "scanned": 1,
+      }
+    `)
+    const matched = await SponsoredTransactions.get(db, intent.id)
+    expect(matched?.transactionHash).toBe(minedHash)
+    expect(matched?.status).toMatchInlineSnapshot(`"pending"`)
+    expect(matched?.finalizedAt).toBeNull()
+    await db.close()
+  })
+
+  test('behavior: unmatched candidates leave intents pending', async () => {
+    const db = create()
+    await db.migrate()
+    const { transactionHash: _, ...rest } = input
+    const intent = await SponsoredTransactions.upsert(db, { ...rest, signPayload: `0x${'ee'.repeat(32)}` }) // prettier-ignore
+
+    const result = await Sponsorships.reconcile(db, {
+      feePayer: '0xFee0000000000000000000000000000000000000',
+      getClient: () => rpc,
+      getTidx: () => tidx([{ from: sender, hash: minedHash }]),
+    })
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "matched": 0,
+        "scanned": 1,
+      }
+    `)
+    expect((await SponsoredTransactions.get(db, intent.id))?.transactionHash).toBeNull()
+    await db.close()
+  })
+
+  test('behavior: queries on-chain candidates oldest first', async () => {
+    const db = create()
+    await db.migrate()
+    const { transactionHash: _, ...rest } = input
+    await SponsoredTransactions.upsert(db, { ...rest, signPayload })
+    let query: string | undefined
+
+    await Sponsorships.reconcile(db, {
+      candidateCap: 17,
+      feePayer: '0xFee0000000000000000000000000000000000000',
+      getClient: () => rpc,
+      getTidx: () =>
+        ({
+          fetch: async (options: { query: string }) => {
+            query = options.query
+            return { rows: [] }
+          },
+        }) as never,
+    })
+
+    expect(
+      query?.replace(/block_timestamp >= '[^']+'/, "block_timestamp >= '<since>'"),
+    ).toMatchInlineSnapshot(
+      `"SELECT hash, "from" FROM txs WHERE fee_payer = '0xfee0000000000000000000000000000000000000' AND block_timestamp >= '<since>' ORDER BY block_timestamp ASC LIMIT 17"`,
+    )
+    await db.close()
+  })
+
+  test('behavior: an indexer error leaves intents for the next pass', async () => {
+    const db = create()
+    await db.migrate()
+    const { transactionHash: _, ...rest } = input
+    await SponsoredTransactions.upsert(db, { ...rest, signPayload })
+
+    const result = await Sponsorships.reconcile(db, {
+      feePayer: '0xFee0000000000000000000000000000000000000',
+      getClient: () => rpc,
+      getTidx: () =>
+        ({
+          fetch: async () => {
+            throw new Error('indexer outage')
+          },
+        }) as never,
+    })
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "matched": 0,
+        "scanned": 0,
+      }
+    `)
+    expect(await SponsoredTransactions.listIntents(db)).toHaveLength(1)
+    await db.close()
+  })
+})

package/src/apps/relay/Sponsorships.ts

@@ -0,0 +1,305 @@
+import type { Hex } from 'ox'
+import { TxEnvelopeTempo } from 'ox/tempo'
+import {
+  type Address,
+  type Client,
+  type EIP1193RequestFn,
+  type TransactionReceipt,
+  TransactionReceiptNotFoundError,
+} from 'viem'
+import { getTransactionReceipt } from 'viem/actions'
+
+import * as Db from '../../db/Db.js'
+import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
+import * as Tidx from '../../internal/Tidx.js'
+import * as Viem from '../../internal/Viem.js'
+
+/**
+ * Runs one finalization pass over pending sponsored transactions: rows with a
+ * receipt finalize with the actual fee (`gasUsed × effectiveGasPrice`, in
+ * fee-token base units); rows still unmined past the pending TTL fail, as do
+ * hash-less fill intents the TTL outlives. Rows whose receipt lookup errors
+ * persist past the error TTL fail so they cannot monopolize every batch.
+ *
+ * @param db - The database holding `sponsored_transactions`.
+ * @param options - Finalization options.
+ * @returns Counters for the pass.
+ */
+export async function finalize(db: Db.Db, options: finalize.Options): Promise<finalize.Result> {
+  const {
+    batchSize = 100,
+    getClient,
+    now = () => new Date(),
+    pendingTtlMs = 3_600_000,
+    receiptErrorTtlMs = 86_400_000,
+  } = options
+
+  const rows = await SponsoredTransactions.listPending(db, { limit: batchSize })
+  const result = { failed: 0, finalized: 0, pending: 0 }
+
+  for (const row of rows) {
+    // Fill intents carry no hash until reconciliation matches them on-chain;
+    // here only the TTL can settle them.
+    if (row.transactionHash === null) {
+      if (Date.parse(row.createdAt) + pendingTtlMs <= now().getTime()) {
+        await SponsoredTransactions.fail(db, row.id, now().toISOString())
+        result.failed++
+      } else result.pending++
+      continue
+    }
+
+    let receipt: TransactionReceipt | null
+    try {
+      receipt = await getTransactionReceipt(getClient(row.chainId), {
+        hash: row.transactionHash as Hex.Hex,
+      })
+    } catch (error) {
+      // Unmined transactions surface as a typed not-found; let the TTL decide.
+      if (error instanceof TransactionReceiptNotFoundError) receipt = null
+      else {
+        if (Date.parse(row.createdAt) + receiptErrorTtlMs <= now().getTime()) {
+          await SponsoredTransactions.fail(db, row.id, now().toISOString())
+          result.failed++
+        } else result.pending++
+        continue
+      }
+    }
+
+    if (receipt) {
+      // A reverted transaction still finalizes: the fee payer paid its fees.
+      const feeAmount = receipt.gasUsed * receipt.effectiveGasPrice
+      await SponsoredTransactions.finalize(db, row.id, {
+        feeAmount: feeAmount.toString(),
+        finalizedAt: now().toISOString(),
+      })
+      result.finalized++
+    } else if (Date.parse(row.createdAt) + pendingTtlMs <= now().getTime()) {
+      await SponsoredTransactions.fail(db, row.id, now().toISOString())
+      result.failed++
+    } else result.pending++
+  }
+
+  return result
+}
+
+export declare namespace finalize {
+  /** Options for {@link finalize}. */
+  type Options = {
+    /** Maximum pending rows processed per pass. @default 100 */
+    batchSize?: number | undefined
+    /** Client resolver keyed by the row's chain id. */
+    getClient: (chainId: number) => Client
+    /** Clock; injectable for tests. */
+    now?: (() => Date) | undefined
+    /** Age after which an unmined sponsorship fails. @default 1 hour */
+    pendingTtlMs?: number | undefined
+    /** Age after which repeated receipt lookup errors fail a row. @default 24 hours */
+    receiptErrorTtlMs?: number | undefined
+  }
+
+  /** Counters returned by one finalization pass. */
+  type Result = {
+    /** Rows marked failed (unmined past the pending TTL). */
+    failed: number
+    /** Rows finalized with an actual fee. */
+    finalized: number
+    /** Rows left pending (unmined, or receipt lookup errored within the error TTL). */
+    pending: number
+  }
+}
+
+/**
+ * Runs one reconciliation pass over pending fill intents (rows with no
+ * transaction hash): fetches the fee payer's recent on-chain transactions
+ * from TIDX, recomputes each candidate's fee-payer sign payload, and fills
+ * matching intents' hashes so the receipt pass can finalize them. Query or
+ * candidate errors leave intents for the next pass.
+ *
+ * @param db - The database holding `sponsored_transactions`.
+ * @param options - Reconciliation options.
+ * @returns Counters for the pass.
+ */
+export async function reconcile(db: Db.Db, options: reconcile.Options): Promise<reconcile.Result> {
+  const {
+    batchSize = 100,
+    candidateCap = 500,
+    failedIntentTtlMs = 86_400_000,
+    feePayer,
+    getClient,
+    getTidx,
+    skewMs = 120_000,
+  } = options
+
+  const intents = await SponsoredTransactions.listIntents(db, {
+    failedSince: new Date(Date.now() - failedIntentTtlMs).toISOString(),
+    limit: batchSize,
+  })
+  const result = { matched: 0, scanned: 0 }
+  if (intents.length === 0) return result
+
+  const chains = new Map<number, SponsoredTransactions.Record[]>()
+  for (const intent of intents) chains.set(intent.chainId, [...(chains.get(intent.chainId) ?? []), intent]) // prettier-ignore
+
+  for (const [chainId, rows] of chains) {
+    const bySignPayload = new Map(rows.map((row) => [row.signPayload, row]))
+    // The intent set bounds the scan window: no cursor state to persist.
+    const since = new Date(
+      Math.min(...rows.map((row) => Date.parse(row.createdAt))) - skewMs,
+    ).toISOString()
+
+    let candidates: readonly globalThis.Record<string, unknown>[]
+    try {
+      // Dynamic filter values; the tidx client's query type wants literals.
+      const fetched = await getTidx(chainId).fetch({
+        chainId,
+        query:
+          `SELECT hash, "from" FROM txs WHERE fee_payer = '${feePayer.toLowerCase()}' AND block_timestamp >= '${since}' ORDER BY block_timestamp ASC LIMIT ${candidateCap}` as string,
+      })
+      candidates = fetched.rows
+    } catch {
+      // Indexer outage must not fail intents; retry on the next pass.
+      continue
+    }
+
+    for (const candidate of candidates) {
+      if (bySignPayload.size === 0) break
+      const hash = candidate['hash'] as Hex.Hex | undefined
+      const sender = candidate['from'] as Address | undefined
+      if (!hash || !sender) continue
+      result.scanned++
+      try {
+        const serialized = await getRawTransaction(getClient(chainId), hash)
+        if (!serialized?.startsWith(TxEnvelopeTempo.serializedType)) continue
+        const signPayload = TxEnvelopeTempo.getFeePayerSignPayload(
+          TxEnvelopeTempo.deserialize(serialized as TxEnvelopeTempo.Serialized),
+          { sender },
+        )
+        const intent = bySignPayload.get(signPayload)
+        if (!intent) continue
+        await SponsoredTransactions.assignTransactionHash(db, intent.id, hash)
+        bySignPayload.delete(signPayload)
+        result.matched++
+      } catch {
+        // Unresolvable candidate (lookup error, malformed envelope): skip it.
+      }
+    }
+  }
+
+  return result
+}
+
+export declare namespace reconcile {
+  /** Options for {@link reconcile}. */
+  type Options = {
+    /** Maximum intents considered per pass. @default 100 */
+    batchSize?: number | undefined
+    /** Maximum on-chain candidates fetched per chain per pass. @default 500 */
+    candidateCap?: number | undefined
+    /** How long failed intents remain reconciliation candidates. @default 24 hours */
+    failedIntentTtlMs?: number | undefined
+    /** Fee payer address whose on-chain transactions are candidates. */
+    feePayer: Address
+    /** Client resolver keyed by the intent's chain id. */
+    getClient: (chainId: number) => Client
+    /** TIDX client resolver keyed by the intent's chain id. */
+    getTidx: (chainId: number) => Tidx.Client
+    /** Lookback slack before the oldest intent's creation. @default 2 minutes */
+    skewMs?: number | undefined
+  }
+
+  /** Counters returned by one reconciliation pass. */
+  type Result = {
+    /** Intents matched to an on-chain transaction. */
+    matched: number
+    /** On-chain candidates inspected. */
+    scanned: number
+  }
+}
+
+/**
+ * Fetches a mined transaction's canonical envelope bytes.
+ * `eth_getRawTransactionByHash` is a node extension absent from viem's typed
+ * RPC schema, hence the request-fn narrowing.
+ */
+function getRawTransaction(client: Client, hash: Hex.Hex) {
+  type Request = EIP1193RequestFn<
+    [
+      {
+        Method: 'eth_getRawTransactionByHash'
+        Parameters: readonly [Hex.Hex]
+        ReturnType: Hex.Hex | null
+      },
+    ]
+  >
+  return (client.request as Request)({ method: 'eth_getRawTransactionByHash', params: [hash] })
+}
+
+/**
+ * Builds a scheduled sponsorship finalizer bound to a database and RPC config.
+ * A host runtime drives {@link createFinalizer.Finalizer.tick} on a timer (a
+ * Cloudflare `scheduled` cron handler, a self-host `setInterval`, …); each
+ * tick reconciles fill intents (when `feePayer` + `tidx` are configured) and
+ * runs one {@link finalize} pass, with memoized per-chain clients.
+ */
+export function createFinalizer(options: createFinalizer.Options): createFinalizer.Finalizer {
+  const clients = new Map<number, Viem.getClient.ReturnType>()
+  const getClient = (chainId: number) => {
+    let client = clients.get(chainId)
+    if (!client) {
+      client = Viem.getClient({ chainId: chainId as Viem.ChainId, rpc: options.rpc })
+      clients.set(chainId, client)
+    }
+    return client
+  }
+  const getTidx = options.tidx
+    ? Tidx.createGetClient({ defaultChainId: options.defaultChainId, tidx: options.tidx })
+    : undefined
+  const feePayer = options.feePayer
+
+  return {
+    async tick() {
+      // Resolve per tick so Workers factories build a fresh Hyperdrive-pooled
+      // connection each run.
+      const db = Db.get(options.db)
+      // Reconcile first so freshly matched intents finalize in the same tick.
+      const reconciled =
+        feePayer && getTidx
+          ? await reconcile(db, {
+              batchSize: options.batchSize,
+              feePayer,
+              getClient,
+              getTidx: (chainId) => getTidx(chainId as Viem.ChainId),
+            })
+          : { matched: 0, scanned: 0 }
+      const finalized = await finalize(db, {
+        batchSize: options.batchSize,
+        getClient,
+        now: options.now,
+        pendingTtlMs: options.pendingTtlMs,
+      })
+      return { ...finalized, ...reconciled }
+    },
+  }
+}
+
+export declare namespace createFinalizer {
+  /** Options for {@link createFinalizer}. */
+  type Options = Pick<finalize.Options, 'batchSize' | 'now' | 'pendingTtlMs'> & {
+    /** Database holding sponsorship rows, or a factory resolved per tick (Workers/Hyperdrive). */
+    db: Db.Source
+    /** Default chain id for the TIDX client resolver. */
+    defaultChainId?: Viem.ChainId | undefined
+    /** Fee payer address whose on-chain transactions reconcile fill intents; omit to skip reconciliation. */
+    feePayer?: Address | undefined
+    /** RPC options for the receipt-lookup clients. */
+    rpc?: Viem.getClient.Rpc | undefined
+    /** TIDX query client options for intent reconciliation; omit to skip reconciliation. */
+    tidx?: Tidx.getClient.Tidx | undefined
+  }
+
+  /** A scheduled sponsorship finalizer. */
+  type Finalizer = {
+    /** Runs one reconcile + finalize pass. */
+    tick(): Promise<finalize.Result & reconcile.Result>
+  }
+}

package/src/apps/relay/index.ts

@@ -0,0 +1,2 @@
+export { relay } from './App.js'
+export * as Sponsorships from './Sponsorships.js'