feat(server): add fee payer policy hook

src/server/Handler.test.ts

@@ -1,7 +1,7 @@
 import { Elysia } from 'elysia'
 import express from 'express'
 import { Hono } from 'hono'
-import type { RpcRequest } from 'ox'
+import { type RpcRequest, RpcResponse } from 'ox'
 import * as Base64 from 'ox/Base64'
 import * as Hex from 'ox/Hex'
 import { sendTransactionSync } from 'viem/actions'
@@ -1165,6 +1165,71 @@ describe('feePayer', () => {
       expect(data.error.name).toBe('RpcResponse.InvalidParamsError')
     })
 
+    test('behavior: policy receives parsed transaction context', async () => {
+      let policyContext: Handler.feePayer.PolicyContext | undefined
+      const policyServer = await createServer(
+        Handler.feePayer({
+          account: feePayerAccount,
+          client: getClient(),
+          policy: (context) => {
+            policyContext = context
+          },
+        }).listener,
+      )
+
+      try {
+        const client = getClient({
+          account: userAccount,
+          transport: withFeePayer(http(), http(policyServer.url)),
+        })
+
+        const receipt = await sendTransactionSync(client, {
+          feePayer: true,
+          to: '0x0000000000000000000000000000000000000000',
+        })
+
+        expect(receipt.feePayer).toBe(feePayerAccount.address.toLowerCase())
+        expect(policyContext?.account.address).toBe(feePayerAccount.address)
+        expect(policyContext?.method).toBe('eth_signRawTransaction')
+        expect(policyContext?.request.method).toBe('eth_signRawTransaction')
+        expect(policyContext?.transaction.from).toBe(userAccount.address.toLowerCase())
+        expect(policyContext?.transaction.to).toBe('0x0000000000000000000000000000000000000000')
+      } finally {
+        policyServer.close()
+      }
+    })
+
+    test('behavior: policy can reject sponsorship with rpc error', async () => {
+      const policyServer = await createServer(
+        Handler.feePayer({
+          account: feePayerAccount,
+          client: getClient(),
+          policy: ({ transaction }) => {
+            if (transaction.to === '0x0000000000000000000000000000000000000000')
+              throw new RpcResponse.InvalidParamsError({
+                message: 'Destination is not sponsorable.',
+              })
+          },
+        }).listener,
+      )
+
+      try {
+        const client = getClient({
+          account: userAccount,
+          transport: withFeePayer(http(), http(policyServer.url)),
+        })
+
+        await expect(
+          sendTransactionSync(client, {
+            feePayer: true,
+            to: '0x0000000000000000000000000000000000000000',
+          }),
+        ).rejects.toThrow('Destination is not sponsorable.')
+      } finally {
+        policyServer.close()
+      }
+    })
+
     test('behavior: unsupported method', async () => {
       await expect(
         fetch(server.url, {

src/server/Handler.ts

@@ -515,7 +515,7 @@ export declare namespace keyManager {
  * @returns Request handler.
  */
 export function feePayer(options: feePayer.Options) {
-  const { account, onRequest, path = '/' } = options
+  const { account, onRequest, path = '/', policy } = options
 
   const client = (() => {
     if ('client' in options) return options.client!
@@ -566,6 +566,14 @@ export function feePayer(options: feePayer.Options) {
           message: 'Transaction must be signed by the sender before fee payer signing.',
         })
 
+      await policy?.({
+        account,
+        client,
+        method,
+        request,
+        transaction,
+      })
+
       const serializedTransaction = await signTransaction(client, {
         ...transaction,
         account,
@@ -582,6 +590,13 @@ export function feePayer(options: feePayer.Options) {
 
       return Response.json(RpcResponse.from({ result }, { request }))
     } catch (error) {
+      if (
+        error instanceof RpcResponse.InternalError ||
+        error instanceof RpcResponse.InvalidParamsError ||
+        error instanceof RpcResponse.MethodNotSupportedError
+      )
+        return Response.json(RpcResponse.from({ error }, { request }))
+
       return Response.json(
         RpcResponse.from(
           {
@@ -599,11 +614,26 @@ export function feePayer(options: feePayer.Options) {
 }
 
 export declare namespace feePayer {
+  export type PolicyContext = {
+    /** Account used to sponsor the request. */
+    account: LocalAccount
+    /** Client used to sign and forward the request. */
+    client: Client
+    /** Parsed JSON-RPC method. */
+    method: 'eth_signRawTransaction' | 'eth_sendRawTransaction' | 'eth_sendRawTransactionSync'
+    /** Original JSON-RPC request. */
+    request: RpcRequest.RpcRequest
+    /** Parsed Tempo transaction. */
+    transaction: ReturnType<typeof Transaction.deserialize>
+  }
+
   export type Options = from.Options & {
     /** Account to use as the fee payer. */
     account: LocalAccount
     /** Function to call before handling the request. */
     onRequest?: (request: RpcRequest.RpcRequest) => Promise<void>
+    /** Policy hook to validate sponsorship before fee payer signing. */
+    policy?: (context: PolicyContext) => Promise<void> | void
     /** Path to use for the handler. */
     path?: string | undefined
   } & OneOf<