tapimo 0.1.0 → 0.3.0

package/src/apps/relay/App.ts

@@ -0,0 +1,236 @@
+import { Hono } from 'hono'
+import { createMiddleware } from 'hono/factory'
+import { RpcResponse } from 'ox'
+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 Fees from '../../internal/Fees.js'
+import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
+import * as Billing from '../platform/Billing.js'
+import * as Handler from '../../Handler.js'
+import * as Auth from '../../internal/Auth.js'
+import * as OpenApi from '../../internal/OpenApi.js'
+import * as Path from '../../internal/Path.js'
+import * as VerifiedTokens from '../../internal/VerifiedTokens.js'
+import * as Viem from '../../internal/Viem.js'
+import * as Scope from '../../Scope.js'
+
+/**
+ * The relay route group: the wallet relay at `/rpc/relay`. Mount
+ * after `data()`, whose published chain clients and supported-chain set the
+ * middleware reads from request context.
+ *
+ * ```ts
+ * App.create(options).route('/', data()).route('/', relay())
+ * ```
+ */
+export function relay(options: relay.Options = {}) {
+  const handler = middleware(options)
+  return new Hono<App.Environment>()
+    .use(
+      '/rpc/relay',
+      Auth.policy({ apiKey: { scopes: ['rpc-relay:read'] }, mpp: false, public: false }),
+      OpenApi.describeRoute({ hide: true, summary: 'Relay RPC' }),
+    )
+    .use(
+      '/rpc/relay/*',
+      Auth.policy({ apiKey: { scopes: ['rpc-relay:read'] }, mpp: false, public: false }),
+      OpenApi.describeRoute({ hide: true, summary: 'Relay RPC' }),
+    )
+    .all('/rpc/relay', handler)
+    .all('/rpc/relay/:chainId', handler)
+}
+
+export declare namespace relay {
+  /** Options for the relay route group. */
+  type Options = {
+    feePayer?:
+      | (Pick<
+          NonNullable<Handler.relay.Options['feePayer']>,
+          'account' | 'feeToken' | 'name' | 'url'
+        > & {
+          /** Per-transaction fee cap (decimal USD string); orgs tighten it, never loosen. @default '1.00' */
+          txFeeLimit?: string | undefined
+        })
+      | undefined
+  }
+}
+
+// The wallet relay middleware: proxies wallet JSON-RPC (fills, sponsored
+// sends) with wallet-aware enrichment. Built per request from context rather
+// than closed over group locals; relay traffic is low-QPS and the viem
+// clients are memoized upstream, so per-request handler construction is cheap.
+function middleware(options: relay.Options = {}) {
+  // Platform-wide per-transaction cap; org settings tighten it, never loosen.
+  const txFeeLimit = options.feePayer
+    ? Billing.toBaseUnits(options.feePayer.txFeeLimit ?? '1.00')
+    : 0n
+  return createMiddleware<App.Environment>(async (c) => {
+    const verifiedTokens = c.get('verifiedTokens')
+
+    const feePayer = (() => {
+      if (!options.feePayer) return undefined
+      const principal = Auth.getPrincipal(c)
+      const attribution =
+        principal?.type === 'api_key' && principal.projectId !== undefined
+          ? {
+              apiKeyId: principal.id,
+              environment: principal.environment,
+              orgId: principal.orgId,
+              projectId: principal.projectId,
+            }
+          : undefined
+      const sponsorable =
+        attribution !== undefined &&
+        principal?.type === 'api_key' &&
+        (principal.apiKey.scopes.includes('rpc-relay:sponsor') ||
+          principal.apiKey.scopes.includes(Scope.wildcard))
+      // Lifted so validation and the sponsored-token default read one value.
+      const feeToken_sponsor = options.feePayer.feeToken ?? Addresses.pathUsd
+      return {
+        ...options.feePayer,
+        feeToken: feeToken_sponsor,
+        validate: async (transaction) => {
+          // Allowlist the chains this deployment serves rather than denylisting
+          // 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 (!attribution || !sponsorable || !c.get('supportedChainIds').has(id)) return false
+          if (!Viem.isMainnet(id)) return true
+          // Mainnet is production-only: a sandbox key resolves chainId from the
+          // request body, so the auth-layer sandbox/mainnet guard never sees
+          // it. Refuse here, or sandbox spend would sponsor mainnet unbilled.
+          if (attribution.environment !== 'production') 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.
+          const billing = await Billing.status(db, attribution.orgId)
+          if (billing === 'past_due') return 'billing_past_due'
+          if (billing !== 'active') return 'billing_required'
+
+          const feeToken = (() => {
+            try {
+              return TokenId.toAddress(transaction.feeToken ?? feeToken_sponsor)
+            } catch {
+              return undefined
+            }
+          })()
+          const verified = feeToken
+            ? (await VerifiedTokens.read(Db.get(c.get('dbCached')), id))?.byAddress.get(feeToken.toLowerCase()) // prettier-ignore
+            : undefined
+          if (
+            !verified ||
+            verified.currency.toLowerCase() !== 'usd' ||
+            verified.decimals !== Fees.tokenDecimals
+          )
+            // prettier-ignore
+            return 'fee_token_unsupported'
+
+          // Fail closed: a transaction whose signed cap cannot be computed
+          // cannot be bounded, so it never sponsors on mainnet.
+          const feeMax = Fees.maxOf(transaction)
+          if (feeMax === undefined) return 'tx_fee_limit_exceeded'
+          const settings = await BillingSettings.get(db, attribution.orgId)
+          const cap = (() => {
+            if (settings?.txFeeLimit == null) return txFeeLimit
+            const org = Billing.toBaseUnits(settings.txFeeLimit)
+            return org < txFeeLimit ? org : txFeeLimit
+          })()
+          if (feeMax > cap) return 'tx_fee_limit_exceeded'
+          // The period spend limit is enforced atomically at recording time
+          // (`onSponsored` → `SponsoredTransactions.reserve`); a check here
+          // would be a check-then-act race a burst could slip through.
+          return true
+        },
+        onSponsored: async (event) => {
+          if (!attribution) return
+          const mainnet = Viem.isMainnet(event.chainId)
+          // Defense in depth: `validate` already refuses non-production
+          // mainnet, so reaching here with that pair is a wiring bug.
+          if (mainnet && attribution.environment !== 'production')
+            throw new RpcResponse.InvalidParamsError({ message: 'Sponsorship rejected.' })
+
+          // The cap recomputes from canonical envelope bytes, mirroring the
+          // 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
+            } catch {
+              return undefined
+            }
+          })()
+
+          const currency = feeToken
+            ? (await VerifiedTokens.read(Db.get(c.get('dbCached')), event.chainId))?.byAddress
+                .get(feeToken.toLowerCase())
+                ?.currency.toLowerCase()
+            : undefined
+
+          const input = {
+            apiKeyId: attribution.apiKeyId,
+            billable: attribution.environment === 'production',
+            chainId: event.chainId,
+            environment: attribution.environment,
+            orgId: attribution.orgId,
+            projectId: attribution.projectId,
+            signPayload: event.signPayload,
+            transaction: event.transaction,
+            ...(currency ? { currency } : {}),
+            ...(feeMax !== undefined ? { feeMax: feeMax.toString() } : {}),
+            ...(feeToken ? { feeToken } : {}),
+            ...(event.transactionHash ? { transactionHash: event.transactionHash } : {}),
+          }
+          // 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
+          try {
+            await SponsoredTransactions.reserve(db, input, {
+              chainIds: [Viem.chainId.mainnet],
+              max: Billing.toBaseUnits(settings.spendLimit),
+              since: Billing.periodStart(settings.period),
+            })
+          } catch (error) {
+            if (error instanceof SponsoredTransactions.PeriodSpendLimitError)
+              throw new RpcResponse.InvalidParamsError({
+                data: { code: 'spend_limit_exceeded' },
+                message: 'Spend limit exceeded.',
+              })
+            throw error
+          }
+        },
+      } satisfies Handler.relay.Options['feePayer']
+    })()
+
+    // Dispatching a standalone Hono via `fetch(c.req.raw)` bypasses Hono's
+    // mount-path stripping, so its internal routes register at the request's
+    // full external path (`basePath` + `/rpc/relay`).
+    const handler = Handler.relay({
+      cache: c.get('store'),
+      features: 'all',
+      getClient: (chainId) => c.get('getClient')(chainId as Viem.ChainId | undefined),
+      path: Path.join(c.get('basePath'), 'rpc/relay'),
+      ...(feePayer ? { feePayer } : {}),
+      ...(verifiedTokens
+        ? {
+            resolveTokens: async (chainId: number) => {
+              const snapshot = await VerifiedTokens.read(Db.get(c.get('dbCached')), chainId)
+              return snapshot?.list.map((token) => token.address) ?? []
+            },
+          }
+        : {}),
+    })
+    return handler.fetch(c.req.raw)
+  })
+}

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(`"1"`)
+    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()
+  })
+})