tapimo 0.14.0 → 0.15.0

package/src/handlers/internal/sponsorship.ts

@@ -25,6 +25,12 @@ export type Validation =
   | 'spend_limit_exceeded'
   | 'tx_fee_limit_exceeded'
 
+/** Details recorded for a sponsored transaction. */
+export type SponsorshipDetails = {
+  /** Whether Tempo subsidizes the sponsorship instead of charging the API-key organization. */
+  subsidized: boolean
+}
+
 /** Refusal messages keyed by named validation reason. */
 const refusalMessages = {
   billing_past_due: 'Billing past due.',
@@ -133,7 +139,7 @@ export async function sign(options: sign.Options) {
   // broadcast anywhere (even directly to a node), so the commitment records as
   // an intent — no transaction hash until the sender signs.
   const feeToken = transaction['feeToken'] as Address | null | undefined
-  await options.onSponsored?.({
+  const sponsorshipDetails = await options.onSponsored?.({
     chainId,
     ...(feeToken ? { feeToken } : {}),
     method: 'eth_fillTransaction',
@@ -142,7 +148,10 @@ export async function sign(options: sign.Options) {
     transaction: TxEnvelopeTempo.serialize(envelope, { feePayerSignature }),
   })
 
-  return { ...prepared, feePayerSignature }
+  return {
+    ...(sponsorshipDetails ? { sponsorshipDetails } : {}),
+    transaction: { ...prepared, feePayerSignature },
+  }
 }
 
 export declare namespace sign {
@@ -150,7 +159,9 @@ export declare namespace sign {
     /** Account used as the fee payer. */
     account: LocalAccount
     /** Called once the fee payer has signed the fill. Awaited: a throw aborts the fill. */
-    onSponsored?: ((event: SponsoredEvent) => Promise<void> | void) | undefined
+    onSponsored?:
+      | ((event: SponsoredEvent) => SponsorshipDetails | Promise<SponsorshipDetails | void> | void)
+      | undefined
     /** Filled transaction to sign. */
     transaction: Record<string, unknown>
     /** Sender address from the original request. */
@@ -208,7 +219,7 @@ export async function handleRawTransaction(options: handleRawTransaction.Options
 
   // Awaited before any broadcast so a recording failure refuses sponsorship —
   // no sponsored transaction ever reaches the chain unrecorded.
-  await options.onSponsored?.({
+  const sponsorshipDetails = await options.onSponsored?.({
     chainId: transaction.chainId,
     ...(feeToken ? { feeToken } : {}),
     method,
@@ -219,11 +230,14 @@ export async function handleRawTransaction(options: handleRawTransaction.Options
   })
 
   // Raw-sign requests stop after fee-payer signature is added; send methods broadcast it.
-  if (method === 'eth_signRawTransaction') return serializedTransaction
-  return await client.request({
-    method: method as never,
-    params: [serializedTransaction],
-  })
+  const result =
+    method === 'eth_signRawTransaction'
+      ? serializedTransaction
+      : await client.request({
+          method: method as never,
+          params: [serializedTransaction],
+        })
+  return { result, ...(sponsorshipDetails ? { sponsorshipDetails } : {}) }
 }
 
 export declare namespace handleRawTransaction {
@@ -239,7 +253,9 @@ export declare namespace handleRawTransaction {
     /** Raw transaction method to handle. */
     method: 'eth_signRawTransaction' | 'eth_sendRawTransaction' | 'eth_sendRawTransactionSync'
     /** Called once the fee payer has signed, before any broadcast. Awaited: a throw aborts the request. */
-    onSponsored?: ((event: SponsoredEvent) => Promise<void> | void) | undefined
+    onSponsored?:
+      | ((event: SponsoredEvent) => SponsorshipDetails | Promise<SponsorshipDetails | void> | void)
+      | undefined
     /** Incoming JSON-RPC request. */
     request: { params?: readonly unknown[] | undefined }
     /** Sender address to use if it cannot be recovered from the raw envelope. */

package/src/handlers/relay.test-d.ts

@@ -1,8 +1,16 @@
-import { Handler } from 'tapimo'
+import { Handler } from 'tapimo/server'
 
 describe('Handler.relay', () => {
   test('accepts Tempo API defaults', () => {
     expectTypeOf(Handler.relay()).toEqualTypeOf<Handler.Handler>()
     expectTypeOf(Handler.relay({ apiKey: 'secret_api_key' })).toEqualTypeOf<Handler.Handler>()
   })
+
+  test('accepts a sponsorship details callback', () => {
+    type OnSponsored = NonNullable<NonNullable<Handler.relay.Options['feePayer']>['onSponsored']>
+
+    expectTypeOf<ReturnType<OnSponsored>>().toEqualTypeOf<
+      { subsidized: boolean } | Promise<{ subsidized: boolean } | void> | void
+    >()
+  })
 })