tapimo 0.1.0 → 0.2.0

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

@@ -0,0 +1,484 @@
+import { Hash, Secp256k1 } from 'ox'
+import { createClient, http } from 'viem'
+import { prepareTransactionRequest, sendRawTransactionSync, signTransaction } from 'viem/actions'
+import { Account as TempoAccount, Actions, Transaction, withRelay } from 'viem/tempo'
+
+import * as TestApp from '../../../test/App.js'
+import * as Relay from '../../../test/Relay.js'
+import * as Runtime from '../../../test/runtime.js'
+import * as Tempo from '../../../test/Tempo.js'
+import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
+import * as RequestListener from '../../handlers/internal/requestListener.js'
+import * as Sponsorships from './Sponsorships.js'
+
+const runtime = Runtime.get()
+
+const feePayerAccount = Tempo.accounts[10]!
+const senderAccount = Tempo.accounts[9]!
+
+/** Keys covering the sponsorship policy matrix; all hold the base relay scope. */
+const keys = [
+  {
+    id: 'key_sponsor',
+    orgId: 'org_1',
+    projectId: 'prj_1',
+    environment: 'sandbox',
+    scopes: ['rpc-relay:read', 'rpc-relay:sponsor'],
+    token: 'secret_sponsor',
+  },
+  {
+    id: 'key_sponsor_prod',
+    orgId: 'org_1',
+    projectId: 'prj_1',
+    environment: 'production',
+    scopes: ['rpc-relay:read', 'rpc-relay:sponsor'],
+    token: 'secret_sponsor_prod',
+  },
+  {
+    id: 'key_wildcard',
+    orgId: 'org_2',
+    projectId: 'prj_2',
+    environment: 'sandbox',
+    scopes: ['*'],
+    token: 'secret_wildcard',
+  },
+  {
+    id: 'key_unscoped',
+    orgId: 'org_1',
+    projectId: 'prj_1',
+    environment: 'sandbox',
+    scopes: ['rpc-relay:read'],
+    token: 'secret_unscoped',
+  },
+  {
+    id: 'key_unattributed',
+    orgId: 'org_1',
+    environment: 'sandbox',
+    scopes: ['rpc-relay:read', 'rpc-relay:sponsor'],
+    token: 'secret_unattributed',
+  },
+] as const satisfies readonly TestApp.kvStore.Key[]
+
+describe.skipIf(runtime.mode !== 'localnet')('behavior: sponsorship', () => {
+  test('behavior: scoped keys sponsor, recorded with attribution', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable()],
+      token: 'secret_sponsor',
+    })
+    expect(body.error).toBeUndefined()
+    // The relay returned the envelope counter-signed by the fee payer.
+    const signed = Transaction.deserialize(body.result as `0x76${string}`)
+    expect(signed.feePayerSignature).toBeDefined()
+
+    const [row] = await SponsoredTransactions.listPending(db)
+    expect(row?.transactionHash).toBe(Hash.keccak256(body.result!))
+    expect(row?.signPayload).toMatch(/^0x/)
+    expect(row?.chainId).toBe(runtime.chainId)
+    // The stored envelope is exactly the counter-signed transaction returned.
+    expect(row?.transaction).toBe(body.result)
+    expect({ ...row, chainId: '<chainId>', createdAt: '<timestamp>', id: '<id>', signPayload: '<hash>', transaction: '<hex>', transactionHash: '<hash>' }) // prettier-ignore
+      .toMatchInlineSnapshot(`
+        {
+          "apiKeyId": "key_sponsor",
+          "billable": false,
+          "chainId": "<chainId>",
+          "createdAt": "<timestamp>",
+          "environment": "sandbox",
+          "feeAmount": null,
+          "feeToken": "0x20c0000000000000000000000000000000000000",
+          "finalizedAt": null,
+          "id": "<id>",
+          "orgId": "org_1",
+          "projectId": "prj_1",
+          "signPayload": "<hash>",
+          "status": "pending",
+          "transaction": "<hex>",
+          "transactionHash": "<hash>",
+        }
+      `)
+  })
+
+  test('behavior: production keys record billable rows', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable()],
+      token: 'secret_sponsor_prod',
+    })
+    expect(body.error).toBeUndefined()
+
+    const [row] = await SponsoredTransactions.listPending(db)
+    expect(row?.billable).toBe(true)
+    expect(row?.environment).toMatchInlineSnapshot(`"production"`)
+  })
+
+  test('behavior: the wildcard scope grants sponsorship', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable()],
+      token: 'secret_wildcard',
+    })
+    expect(body.error).toBeUndefined()
+
+    const [row] = await SponsoredTransactions.listPending(db)
+    expect(row?.orgId).toMatchInlineSnapshot(`"org_2"`)
+  })
+
+  test('behavior: keys without the sponsor scope are refused', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable()],
+      token: 'secret_unscoped',
+    })
+    // "Sponsorship rejected." surfaces as invalid params (-32602).
+    expect(body.result).toBeUndefined()
+    expect(body.error?.code).toBe(-32602)
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
+  test('behavior: keys without project attribution are refused', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable()],
+      token: 'secret_unattributed',
+    })
+    expect(body.result).toBeUndefined()
+    expect(body.error?.code).toBe(-32602)
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
+  test('behavior: super admin principals are refused', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys, superAdmin: { secret: 'super-admin-secret' } },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable()],
+      token: 'super-admin-secret',
+    })
+    expect(body.result).toBeUndefined()
+    expect(body.error?.code).toBe(-32602)
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
+  test('behavior: sponsorship stays closed without a fee payer', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({ auth: { keys }, db })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable()],
+      token: 'secret_sponsor',
+    })
+    expect(body.error?.code).toBe(-32601)
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
+  test('behavior: mainnet sponsorship is refused until billing ships', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [
+        await senderAccount.signTransaction({
+          chainId: 4217,
+          feePayer: true,
+          gas: 100_000n,
+          maxFeePerGas: 1_000_000n,
+          maxPriorityFeePerGas: 0n,
+          nonce: 0,
+          to: Tempo.accounts[8]!.address,
+          value: 0n,
+        }),
+      ],
+      token: 'secret_sponsor',
+    })
+    expect(body.result).toBeUndefined()
+    expect(body.error?.code).toBe(-32602)
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
+  test('behavior: an app-provided fee payer URL cannot trigger the managed fee payer', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_fillTransaction',
+      params: [
+        {
+          calls: [{ to: Tempo.accounts[8]!.address, value: '0x0' }],
+          chainId: `0x${runtime.chainId.toString(16)}`,
+          feePayer: 'https://example.com',
+          from: senderAccount.address,
+          gas: '0x186a0',
+          maxFeePerGas: '0xf4240',
+          maxPriorityFeePerGas: '0x0',
+          nonce: '0x0',
+        },
+      ],
+      token: 'secret_unscoped',
+    })
+    const result = body.result as unknown as
+      | { capabilities?: { sponsored?: boolean }; tx?: { feePayerSignature?: string | null } }
+      | undefined
+    expect(result?.tx?.feePayerSignature ?? null).toBeNull()
+    expect(result?.capabilities?.sponsored).toBe(false)
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
+  test('behavior: sponsorship is refused for chains this deployment does not serve', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [
+        await senderAccount.signTransaction({
+          chainId: 999_999,
+          feePayer: true,
+          gas: 100_000n,
+          maxFeePerGas: 1_000_000n,
+          maxPriorityFeePerGas: 0n,
+          nonce: 0,
+          to: Tempo.accounts[8]!.address,
+          value: 0n,
+        }),
+      ],
+      token: 'secret_sponsor',
+    })
+    expect(body.result).toBeUndefined()
+    expect(body.error?.code).toBe(-32602)
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+})
+
+describe.skipIf(runtime.mode !== 'localnet')('behavior: sponsorship (viem)', () => {
+  const alphaUsd = '0x20c0000000000000000000000000000000000001'
+  const feePayer = TempoAccount.fromSecp256k1(Secp256k1.randomPrivateKey())
+  const sender = TempoAccount.fromSecp256k1(Secp256k1.randomPrivateKey())
+  const relayClient = Relay.getClient()
+
+  let db: ReturnType<typeof TestApp.database>
+  let server: Relay.Server
+
+  function getClient(policy?: 'sign-and-broadcast' | 'sign-only') {
+    return createClient({
+      account: sender,
+      chain: Tempo.chain,
+      transport: withRelay(
+        Relay.http(),
+        http(`${server.url}/rpc/relay`, {
+          fetchOptions: { headers: { 'tempo-api-key': 'secret_sponsor' } },
+        }),
+        policy ? { policy } : {},
+      ),
+    })
+  }
+
+  beforeAll(async () => {
+    await Promise.all(
+      [feePayer, sender].map((account) =>
+        Actions.faucet.fundSync(relayClient, { account, timeout: 60_000 }),
+      ),
+    )
+    db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      // Explicit fee token: exercises the consumer override of the pathUSD default.
+      relay: { feePayer: { account: feePayer, feeToken: alphaUsd } },
+    })
+    server = await Relay.createServer(RequestListener.fromFetchHandler((req) => app.fetch(req)))
+  }, 120_000)
+
+  afterAll(async () => {
+    await server.closeAsync()
+  })
+
+  test('behavior: transferSync sponsors end-to-end, recording a fill intent', async () => {
+    const { receipt } = await Actions.token.transferSync(getClient(), {
+      amount: 1n,
+      feePayer: true,
+      to: Tempo.accounts[8]!.address,
+      token: alphaUsd,
+    })
+
+    // Sponsored on-chain: the fee payer paid, the sender's transfer landed.
+    expect(receipt.status).toBe('success')
+    expect(receipt.feePayer?.toLowerCase()).toBe(feePayer.address.toLowerCase())
+
+    const intent = (await SponsoredTransactions.listPending(db)).find(
+      (row) => row.transactionHash === null,
+    )
+    expect(intent?.apiKeyId).toBe('key_sponsor')
+    expect(intent?.orgId).toBe('org_1')
+    expect(intent?.billable).toBe(false)
+    expect(intent?.feeToken?.toLowerCase()).toBe(alphaUsd)
+
+    const finalizer = Sponsorships.createFinalizer({
+      db,
+      defaultChainId: runtime.chainId,
+      feePayer: feePayer.address,
+      rpc: TestApp.rpc,
+      tidx: { baseUrl: runtime.tidxUrl! },
+    })
+    let finalized: Awaited<ReturnType<typeof SponsoredTransactions.get>>
+    for (let attempt = 0; attempt < 30; attempt++) {
+      await finalizer.tick()
+      finalized = await SponsoredTransactions.get(db, intent!.id)
+      if (finalized?.status === 'finalized') break
+      await new Promise((resolve) => setTimeout(resolve, 1_000))
+    }
+    expect(finalized?.status).toBe('finalized')
+    expect(finalized?.transactionHash).toBe(receipt.transactionHash)
+    expect(finalized?.feeAmount).toBe((receipt.gasUsed * receipt.effectiveGasPrice).toString())
+  }, 60_000)
+
+  test('behavior: sign-only sends record and finalize from the real receipt', async () => {
+    const request = await prepareTransactionRequest(relayClient, {
+      account: sender,
+      calls: [
+        Actions.token.transfer.call(relayClient, {
+          amount: 1n,
+          to: Tempo.accounts[8]!.address,
+          token: alphaUsd,
+        }),
+      ],
+      feePayer: true,
+    })
+    const signed = await signTransaction(relayClient, request)
+
+    const receipt = await sendRawTransactionSync(getClient(), {
+      serializedTransaction: signed,
+    })
+
+    const row = (await SponsoredTransactions.listPending(db)).find(
+      (row) => row.transactionHash === receipt.transactionHash,
+    )
+    expect(row?.apiKeyId).toBe('key_sponsor')
+    expect(row?.orgId).toBe('org_1')
+    expect(row?.transaction.startsWith('0x76')).toBe(true)
+
+    // The finalizer resolves the row against the real localnet receipt.
+    const result = await Sponsorships.finalize(db, { getClient: () => relayClient })
+    expect(result.failed).toBe(0)
+    expect(result.finalized).toBeGreaterThanOrEqual(1)
+    const finalized = await SponsoredTransactions.get(db, row!.id)
+    expect(finalized?.status).toBe('finalized')
+    expect(finalized?.feeAmount).toBe((receipt.gasUsed * receipt.effectiveGasPrice).toString())
+  }, 30_000)
+
+  test('behavior: sign-and-broadcast sends record through the relay', async () => {
+    const request = await prepareTransactionRequest(relayClient, {
+      account: sender,
+      calls: [
+        Actions.token.transfer.call(relayClient, {
+          amount: 2n,
+          to: Tempo.accounts[8]!.address,
+          token: alphaUsd,
+        }),
+      ],
+      feePayer: true,
+    })
+    const signed = await signTransaction(relayClient, request)
+
+    const receipt = await sendRawTransactionSync(getClient('sign-and-broadcast'), {
+      serializedTransaction: signed,
+    })
+
+    const rows = await SponsoredTransactions.listPending(db)
+    expect(rows.find((row) => row.transactionHash === receipt.transactionHash)).toBeDefined()
+  }, 30_000)
+})
+
+/**
+ * Signs a sponsorship-requesting Tempo transaction (fee-payer slot present but
+ * empty; the serializer strips `feeToken`, the sponsor picks it) entirely
+ * offline: `eth_signRawTransaction` never touches the chain, so the suite
+ * runs without a node.
+ */
+async function signSponsorable() {
+  return await senderAccount.signTransaction({
+    chainId: runtime.chainId,
+    feePayer: true,
+    gas: 100_000n,
+    maxFeePerGas: 1_000_000n,
+    maxPriorityFeePerGas: 0n,
+    nonce: 0,
+    to: Tempo.accounts[8]!.address,
+    value: 0n,
+  })
+}
+
+/** Posts one JSON-RPC request to the composed app's relay mount. */
+async function relayRequest(
+  app: ReturnType<typeof TestApp.create>,
+  options: { method: string; params: readonly unknown[]; token?: string | undefined },
+) {
+  const response = await app.fetch(
+    new Request('http://tempo-api.test/rpc/relay', {
+      body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: options.method, params: options.params }), // prettier-ignore
+      headers: {
+        'content-type': 'application/json',
+        ...(options.token ? { 'tempo-api-key': options.token } : {}),
+      },
+      method: 'POST',
+    }),
+  )
+  return (await response.json()) as {
+    error?: { code: number; message: string } | undefined
+    result?: `0x${string}` | undefined
+  }
+}

package/src/apps/relay/App.ts

@@ -0,0 +1,128 @@
+import { Hono } from 'hono'
+import { createMiddleware } from 'hono/factory'
+import { Addresses } from 'viem/tempo'
+
+import type * as App from '../../App.js'
+import * as Db from '../../db/Db.js'
+import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.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'
+        >
+      | 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 = {}) {
+  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))
+      return {
+        ...options.feePayer,
+        feeToken: options.feePayer.feeToken ?? Addresses.pathUsd,
+        validate: ({ chainId }) => {
+          // 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. Mainnet stays closed
+          // until billing ships; nothing meters real fee-payer spend yet.
+          const id = Number(chainId)
+          return sponsorable && c.get('supportedChainIds').has(id) && !Viem.isMainnet(id)
+        },
+        onSponsored: async (event) => {
+          if (!attribution) return
+          await SponsoredTransactions.upsert(Db.get(c.get('db')), {
+            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,
+            ...(event.feeToken ? { feeToken: event.feeToken } : {}),
+            ...(event.transactionHash ? { transactionHash: event.transactionHash } : {}),
+          })
+        },
+      } 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)
+  })
+}