viem 2.56.9 → 2.57.0

package/tempo/Relay.ts

@@ -0,0 +1,428 @@
+import type { Address } from 'abitype'
+import * as RpcResponse from 'ox/RpcResponse'
+import type { LocalAccount } from '../accounts/types.js'
+import type { Client as Client_ } from '../clients/createClient.js'
+import { ChainNotConfiguredError } from '../clients/createClientResolver.js'
+import type { EIP1193RequestOptions } from '../types/eip1193.js'
+import * as Sponsorship from './internal/relay/feePayer.js'
+import * as FeeToken from './internal/relay/feeToken.js'
+import * as Multisig from './internal/relay/multisig.js'
+import * as Request_ from './internal/relay/request.js'
+import * as Simulate from './internal/relay/simulate.js'
+import * as internal from './internal/relay.js'
+import type * as Store from './Store.js'
+
+/**
+ * Creates a relay with RPC and Fetch handlers backed by a client or chain resolver.
+ *
+ * Pass a chain-configured `client` for a single chain, or `getClient` for multiple
+ * chains. Plugins may resolve the chain before forwarding to the selected client.
+ *
+ * @example
+ * ```ts
+ * import { createClient, http } from 'viem'
+ * import { tempo } from 'viem/chains'
+ * import { Relay } from 'viem/tempo'
+ *
+ * const relay = Relay.create({
+ *   client: createClient({ chain: tempo, transport: http() }),
+ * })
+ * export default { fetch: relay.fetch }
+ * ```
+ *
+ * @param options - Client selection and relay plugins.
+ * @returns RPC and Fetch handlers sharing the same plugins.
+ */
+export function create<const chainId extends number>(
+  options: handleRequest.Options & {
+    client: Client & { chain: { id: chainId } }
+    getClient?: never
+  },
+): create.ReturnType<chainId>
+export function create<const chainId extends number = number>(
+  options: handleRequest.Options & {
+    client?: never
+    getClient: (options: { chainId: chainId }) => Client
+  },
+): create.ReturnType<chainId>
+export function create<getClient extends (options: never) => Client>(
+  options: handleRequest.Options & { client?: never; getClient: getClient },
+): create.ReturnType<
+  Parameters<getClient>[0] extends { chainId: infer chainId extends number }
+    ? chainId
+    : number
+>
+export function create(
+  options: handleRequest.Options & {
+    client?: Client | undefined
+    getClient?: ((options: never) => Client) | undefined
+  },
+): create.ReturnType {
+  if (Boolean(options.client) === Boolean(options.getClient))
+    throw new RpcResponse.InvalidParamsError({
+      message: 'Expected exactly one of client or getClient.',
+    })
+  const clientChainId = options.client?.chain?.id
+  if (
+    options.client &&
+    (!Number.isSafeInteger(clientChainId) ||
+      !clientChainId ||
+      clientChainId <= 0)
+  )
+    throw new RpcResponse.InvalidParamsError({
+      message: 'Expected a client with a configured chain.',
+    })
+
+  const getClient = (chainId: number) => {
+    try {
+      const client = options.client ?? options.getClient!({ chainId } as never)
+      if (client.chain.id !== chainId)
+        throw new RpcResponse.InvalidParamsError({
+          message: 'Conflicting chain ids.',
+        })
+      return client
+    } catch (error) {
+      if (error instanceof ChainNotConfiguredError)
+        throw new RpcResponse.InvalidParamsError({
+          message: error.shortMessage,
+        })
+      throw error
+    }
+  }
+  const handle = Request_.compose(
+    async (request, requestOptions) => {
+      const { chainId, response: _, ...rest } = requestOptions ?? {}
+      if (chainId === undefined)
+        throw new RpcResponse.InvalidParamsError({
+          message: 'A chain ID is required to resolve the downstream client.',
+        })
+      return getClient(chainId).request(request as never, rest)
+    },
+    options,
+    getClient,
+  )
+
+  const request: handleRequest.Handler = (request, requestOptions) => {
+    const chainId = requestOptions?.chainId ?? clientChainId
+    if (
+      chainId !== undefined &&
+      (!Number.isSafeInteger(chainId) || chainId <= 0)
+    )
+      return Promise.reject(
+        new RpcResponse.InvalidParamsError({
+          message: 'Expected a valid chain ID.',
+        }),
+      )
+    if (clientChainId !== undefined && chainId !== clientChainId)
+      return Promise.reject(
+        new RpcResponse.InvalidParamsError({
+          message: 'Conflicting chain ids.',
+        }),
+      )
+    return handle(request, { ...requestOptions, chainId })
+  }
+  return {
+    request,
+    fetch: (request_, options: create.RequestOptions = {}) =>
+      internal.fetch(request_, request, options),
+  }
+}
+
+export declare namespace create {
+  /** Client selection and middleware for a relay. */
+  export type Options<chainId extends number = number> = handleRequest.Options &
+    (
+      | {
+          /** Chain-configured client used for every forwarded request. */
+          client: Client & { chain: { id: chainId } }
+          getClient?: never
+        }
+      | {
+          client?: never
+          /** Resolves the client after plugins have selected the request's chain. */
+          getClient: (options: {
+            chainId: chainId
+          }) => Client & { chain: { id: number } }
+        }
+    )
+
+  /** Optional chain selection and RPC request options. */
+  export type RequestOptions<chainId extends number = number> = Omit<
+    handleRequest.RequestOptions,
+    'chainId'
+  > & { chainId?: chainId | undefined }
+
+  /** Handlers sharing one composed relay pipeline. */
+  export type ReturnType<chainId extends number = number> = {
+    /** Handles a POST JSON-RPC request, returning JSON or an empty 204 for notifications. */
+    fetch: {
+      (request: Request): Promise<Response>
+      (
+        request: Request,
+        options?: RequestOptions<chainId> | undefined,
+      ): Promise<Response>
+    }
+    /** Handles a parsed RPC call and returns its result. */
+    request: (
+      request: handleRequest.Request,
+      options?: RequestOptions<chainId> | undefined,
+    ) => Promise<unknown>
+  }
+}
+
+/**
+ * Creates an RPC request handler by composing relay plugins around a downstream handler.
+ *
+ * Requests enter plugins in array order, and responses return in reverse order.
+ * Post-fill hooks run concurrently after middleware finishes. Middleware sees
+ * the downstream result before post-fill enrichment and signing.
+ * Without plugins, the downstream handler is returned unchanged. Plugins decide
+ * whether to forward, transform, or handle a request. Errors propagate unchanged
+ * unless a plugin handles them.
+ *
+ * @example
+ * ```ts
+ * import { http } from 'viem'
+ * import { Relay } from 'viem/tempo'
+ *
+ * const rpc = http('https://rpc.tempo.xyz')({})
+ * const handle = Relay.handleRequest(rpc.request, {
+ *   plugins: [
+ *     {
+ *       async handleRequest(context, next) {
+ *         context.options.retryCount = 0
+ *         await next()
+ *       },
+ *     },
+ *   ],
+ * })
+ * const chainId = await handle({ method: 'eth_chainId' })
+ * // @log: '0x1079'
+ * ```
+ *
+ * @param next - Downstream RPC request handler, typically forwarding to the Tempo (Execution) RPC.
+ * @param options - Relay options.
+ * @returns The composed RPC request handler.
+ */
+export function handleRequest(
+  next: handleRequest.Handler,
+  options: handleRequest.Options = {},
+): handleRequest.Handler {
+  return Request_.compose(next, options)
+}
+
+export declare namespace handleRequest {
+  /** RPC request handler shared by relay plugins and the downstream execution RPC. */
+  export type Handler = (
+    request: Request,
+    options?: RequestOptions | undefined,
+  ) => Promise<unknown>
+
+  /** Options for {@link handleRequest}. */
+  export type Options = {
+    /** Plugins in request execution order. Defaults to an empty list. */
+    plugins?: readonly Plugin[] | undefined
+    /** Fee-token candidates shared by all plugins, memoized per request and chain. */
+    resolveTokens?:
+      | ((chainId: number) => readonly Address[] | Promise<readonly Address[]>)
+      | undefined
+    /** Deadline in milliseconds for a plugin-handled fill, including callbacks. Defaults to 10,000. */
+    timeout?: number | undefined
+  }
+
+  /** RPC request passed to a handler. */
+  export type Request = {
+    /** RPC method name. */
+    method: string
+    /** RPC method parameters. */
+    params?: readonly unknown[] | undefined
+  }
+
+  /** Options for one handled request. */
+  export type RequestOptions = EIP1193RequestOptions & {
+    /** Chain selected by the caller or resolved by a plugin. */
+    chainId?: number | undefined
+    /** Response metadata collected by the Fetch adapter. */
+    response?:
+      | { sponsorship_details?: Sponsorship.SponsorshipDetails | undefined }
+      | undefined
+  }
+}
+
+/** Hooks extending relay request processing and filled transaction responses. */
+export type Plugin = {
+  /** Processes an RPC request. Await next(), then read or replace context.result. */
+  handleRequest?:
+    | ((context: Plugin.Context, next: () => Promise<void>) => Promise<unknown>)
+    | undefined
+  /** Runs concurrently after the final fill. Returns capability fields to merge. */
+  afterFill?:
+    | ((
+        filled: Plugin.FillResult,
+        context: Plugin.Context,
+      ) => Promise<Plugin.Enrichment | undefined>)
+    | undefined
+  /** Signs the final fill concurrently with enrichment. Only one signer may be registered. */
+  signTransaction?:
+    | ((
+        filled: Plugin.FillResult,
+        context: Plugin.Context,
+      ) => Promise<Plugin.Signature | undefined>)
+    | undefined
+}
+
+export declare namespace Plugin {
+  /** State and services isolated to one RPC invocation. */
+  export type Context = {
+    /** Current RPC request. Changes are passed to next(). */
+    request: handleRequest.Request
+    /** Downstream result, populated by next(). */
+    result: unknown
+    /** Transport options and selected chain. */
+    options: handleRequest.RequestOptions
+    /** Downstream client for the selected chain. */
+    readonly client: Client_
+    /** Gets a downstream client for the selected or specified chain. */
+    getClient: (chainId?: number) => Client_
+    /** Gets the shared token candidates for the selected or specified chain. */
+    resolveTokens: (chainId?: number) => Promise<readonly Address[]>
+    /** Scopes a configured store to this invocation. */
+    getStore: (store: Store.Store | undefined) => Store.Store | undefined
+  }
+  /** Immutable RPC fill supplied to post-fill hooks. */
+  export type FillResult = {
+    readonly tx: Readonly<Record<string, unknown>>
+    readonly capabilities?: Readonly<Record<string, unknown>> | undefined
+    readonly sponsor?: unknown
+  }
+  /** Additional response capabilities. Duplicate keys from hooks are rejected. */
+  export type Enrichment = {
+    capabilities?: Record<string, unknown> | undefined
+  }
+  /** Fee-payer signature in RPC format. */
+  export type Signature = {
+    r: `0x${string}`
+    s: `0x${string}`
+    yParity: `0x${string}`
+  }
+}
+
+declare const multisigBrand: unique symbol
+
+/**
+ * Coordinates native multisig approvals using shared atomic storage.
+ *
+ * Memory storage is process-local. Independent clients and multiple server
+ * instances must use the same persistent store to share pending approvals.
+ *
+ * @example
+ * ```ts
+ * import { http } from 'viem'
+ * import { Relay, Store, withRelay } from 'viem/tempo'
+ *
+ * const transport = withRelay(http(), {
+ *   plugins: [Relay.multisig({ store: Store.memory() })],
+ * })
+ * ```
+ *
+ * @param options - Shared atomic storage.
+ * @returns A plugin that coordinates multisig requests and forwards other calls.
+ */
+export function multisig(options: multisig.Options): multisig.ReturnType {
+  return Multisig.create(options)
+}
+
+export declare namespace multisig {
+  /** Multisig coordination options. */
+  export type Options = {
+    /** Store shared by multisig coordinators, with atomic compare-and-set support. */
+    store: Store.Atomic
+  }
+  /** Middleware advertising native multisig coordination. */
+  export type ReturnType = Plugin & { readonly [multisigBrand]: true }
+}
+
+/**
+ * Sponsors transactions with a local account or an external fee-payer relay.
+ *
+ * Place multisig before this plugin and fee-token selection after it.
+ *
+ * @example
+ * ```ts
+ * import { privateKeyToAccount } from 'viem/accounts'
+ * import { Relay } from 'viem/tempo'
+ * const plugin = Relay.feePayer({ account: privateKeyToAccount('0x...') })
+ * ```
+ * @param options - Sponsor account, policy, and display metadata.
+ * @returns A fee-payer relay plugin.
+ */
+export function feePayer(options: feePayer.Options = {}): Plugin {
+  return Sponsorship.create(options)
+}
+
+export declare namespace feePayer {
+  /** Fee sponsorship configuration. */
+  export type Options = {
+    /** Local sponsor. Omit when requests use an external fee-payer URL. */
+    account?: LocalAccount | undefined
+    /** Trusted external fee-payer URLs. Matches the normalized full URL, including path and query. Defaults to none. */
+    allowedFeePayers?: readonly string[] | undefined
+    /** Sponsor's preferred fee token. Overrides the request token on sponsored fills. */
+    feeToken?: Address | undefined
+    /** Allow HTTP and private external relay hosts in trusted development environments. @default false */
+    internal_allowUnsafeUrls?: boolean | undefined
+    /** Display name returned in sponsor capabilities. */
+    name?: string | undefined
+    /** Called after signing and before returning or broadcasting. A thrown error aborts sponsorship. */
+    onSponsored?: Sponsorship.sign.Options['onSponsored'] | undefined
+    /** Sponsor display URL. */
+    url?: string | undefined
+    /** Only `true` authorizes sponsorship. Rejected fills fall back to sender-paid transactions. */
+    validate?: Sponsorship.Validate | undefined
+  }
+  /** Result of a sponsorship policy check. */
+  export type Validation = Sponsorship.Validation
+  /** Facts passed to the sponsorship callback. */
+  export type SponsoredEvent = Sponsorship.SponsoredEvent
+}
+
+/**
+ * Resolves fee tokens from user preferences and token balances.
+ *
+ * @example
+ * ```ts
+ * import { Relay } from 'viem/tempo'
+ * const plugin = Relay.feeToken()
+ * ```
+ * @returns A fee-token relay plugin.
+ */
+export function feeToken(): Plugin {
+  return FeeToken.create()
+}
+
+/**
+ * Adds balance changes, estimated fees, and execution errors to fill capabilities.
+ *
+ * Runs after transaction middleware to simulate the final filled result.
+ *
+ * @example
+ * ```ts
+ * import { Relay } from 'viem/tempo'
+ * const plugin = Relay.simulate()
+ * ```
+ * @param options - Optional metadata store.
+ * @returns A simulation relay plugin.
+ */
+export function simulate(options: simulate.Options = {}): Plugin {
+  return Simulate.create(options)
+}
+
+export declare namespace simulate {
+  /** Simulation configuration. */
+  export type Options = {
+    /** Store for cached metadata. Omit to read metadata for each request. */
+    store?: Store.Store | undefined
+  }
+}
+
+type Client = Pick<Client_, 'request'> & { chain: { id: number } }

package/tempo/Transaction.ts

@@ -130,7 +130,8 @@ export type TransactionRequestTempo<
     accessList?: AccessList | undefined
     calls?: readonly TxTempo.Call<quantity, TempoAddress.Address>[] | undefined
     capabilities?: ExtractCapabilities<'fillTransaction', 'Request'> | undefined
-    feePayer?: Account | true | undefined
+    /** Fee-payer account, external relay URL, or sponsorship preference. */
+    feePayer?: Account | boolean | string | undefined
     feeToken?: TempoAddress.Address | bigint | undefined
     hash?: Hex.Hex | undefined
     keyAuthorization?: KeyAuthorization.Signed<quantity, index> | undefined

package/tempo/Transport.ts

@@ -23,7 +23,9 @@ import {
 } from '../errors/rpc.js'
 import type { Chain } from '../types/chain.js'
 import type { ChainConfig } from './chainConfig.js'
-import * as Multisig from './Multisig.js'
+import * as Plugin_ from './internal/relay/plugin.js'
+import * as Request_ from './internal/relay/request.js'
+import type * as Relay_ from './Relay.js'
 import type { Store } from './Store.js'
 import * as Store_ from './Store.js'
 import * as Transaction from './Transaction.js'
@@ -86,63 +88,6 @@ type RelayProxyParameters = {
 export type FeePayer = Transport<typeof withFeePayer.type>
 export type Relay = Transport<typeof withRelay.type, { multisig: true }>
 
-/**
- * Wraps a transport with native multisig request handling.
- *
- * @example
- * ```ts
- * import { http, Store, withMultisig } from 'viem/tempo'
- *
- * const transport = withMultisig(http(), {
- *   store: Store.memory(),
- * })
- * ```
- *
- * @param transport - Transport to wrap.
- * @param parameters - Multisig request handler parameters.
- * @returns The wrapped transport.
- * @experimental
- */
-export function withMultisig<transport extends Transport>(
-  transport: transport,
-  parameters: withMultisig.Parameters,
-): withMultisig.ReturnValue<transport> {
-  return ((options: Parameters<Transport>[0]) => {
-    const value = transport(options)
-    return {
-      ...value,
-      request: Multisig.handleRequest(
-        (request, requestOptions) =>
-          value.request(request as never, requestOptions),
-        parameters,
-      ) as typeof value.request,
-      value: { ...value.value, multisig: true },
-    }
-  }) as withMultisig.ReturnValue<transport>
-}
-
-export declare namespace withMultisig {
-  /** Multisig transport parameters. */
-  export type Parameters = Multisig.handleRequest.Parameters
-
-  /** Multisig transport return type. */
-  export type ReturnValue<transport extends Transport = Transport> =
-    transport extends Transport<
-      infer type,
-      infer rpcAttributes,
-      infer eip1193RequestFn
-    >
-      ? Transport<
-          type,
-          rpcAttributes & {
-            /** Whether the transport coordinates native multisig approvals. */
-            multisig: true
-          },
-          eip1193RequestFn
-        >
-      : never
-}
-
 /**
  * Creates a relay transport that routes requests between
  * the default transport or the relay transport.
@@ -156,16 +101,57 @@ export declare namespace withMultisig {
  * - `'sign-only'`: Relay co-signs the transaction and returns it to the client transport, which then broadcasts it via the default transport
  * - `'sign-and-broadcast'`: Relay co-signs and broadcasts the transaction directly
  *
+ * Local plugin options wrap the default transport directly, preserving its attributes.
+ * Local mode enables fee sponsorship only when a `Relay.feePayer` plugin is configured.
+ *
  * @param defaultTransport - The default transport to use.
- * @param relayTransport - The relay transport to use.
+ * @param relayTransport - The remote relay transport or local plugin options.
  * @param parameters - Configuration parameters.
  * @returns A relay transport.
  */
+export function withRelay<
+  transport extends Transport,
+  const plugins extends readonly Relay_.Plugin[] = readonly [],
+>(
+  defaultTransport: transport,
+  options: withRelay.LocalOptions<plugins>,
+): withRelay.LocalReturnValue<transport, plugins>
 export function withRelay(
   defaultTransport: Transport,
   relayTransport: Transport,
   parameters?: withRelay.Parameters,
-): withRelay.ReturnValue {
+): withRelay.ReturnValue
+export function withRelay(
+  defaultTransport: Transport,
+  relayTransport: Transport | withRelay.LocalOptions,
+  parameters?: withRelay.Parameters,
+): Transport {
+  if (typeof relayTransport !== 'function')
+    return (config) => {
+      const transport = defaultTransport(config)
+      const next: Relay_.handleRequest.Handler = (request, options) =>
+        transport.request(request as never, options)
+      const request = Request_.compose(
+        next,
+        relayTransport,
+        config.chain ? () => ({ chain: config.chain! }) : undefined,
+      )
+      return {
+        ...transport,
+        request: ((request_, options) =>
+          request(request_ as Relay_.handleRequest.Request, {
+            chainId: config.chain?.id,
+            ...options,
+          })) as typeof transport.request,
+        value: {
+          ...transport.value,
+          ...(relayTransport.plugins?.some(Plugin_.isMultisig)
+            ? { multisig: true }
+            : {}),
+        },
+      }
+    }
+
   const { policy = 'sign-only' } = parameters ?? {}
 
   return (config) => {
@@ -282,6 +268,29 @@ export declare namespace withRelay {
 
   export type Parameters = RelayProxyParameters
 
+  /** Plugins applied directly to the default transport. */
+  export type LocalOptions<
+    plugins extends readonly Relay_.Plugin[] = readonly Relay_.Plugin[],
+  > = Pick<Relay_.handleRequest.Options, 'resolveTokens'> & {
+    /** Ordered relay plugins. Defaults to an empty list. */
+    plugins?: plugins | undefined
+  }
+
+  /** Wrapped transport preserving its attributes and RPC request schema. */
+  export type LocalReturnValue<
+    transport extends Transport,
+    plugins extends readonly Relay_.Plugin[] = readonly [],
+  > = transport extends Transport<infer type, infer attributes, infer request>
+    ? Transport<
+        type,
+        attributes &
+          (Extract<plugins[number], Relay_.multisig.ReturnType> extends never
+            ? {}
+            : { multisig: true }),
+        request
+      >
+    : never
+
   export type ReturnValue = Relay
 }
 

package/tempo/chainConfig.ts

@@ -119,6 +119,10 @@ export const chainConfig = {
           throw new Error('Multisig operation hash does not match transaction.')
         return {
           ...storedTransaction,
+          // Serialized zero values must not trigger a new fill of an approved transaction.
+          gas: storedTransaction.gas ?? 0n,
+          maxFeePerGas: storedTransaction.maxFeePerGas ?? 0n,
+          maxPriorityFeePerGas: storedTransaction.maxPriorityFeePerGas ?? 0n,
           account: request.account,
           from: operation.account,
           multisigSimulation: getMultisigSimulation({

package/tempo/index.ts

@@ -67,14 +67,19 @@ export {
   type Decorator as TempoActions,
   decorator as tempoActions,
 } from './Decorator.js'
+/** Decodes Tempo precompile reverts into readable execution errors. */
+export * as ExecutionError from './ExecutionError.js'
 export * as Expiry from './Expiry.js'
 export * from './errors.js'
 export * as Formatters from './Formatters.js'
 export * as Hardfork from './Hardfork.js'
 export * as KeyAuthorizationManager from './KeyAuthorizationManager.js'
-/** @experimental */
-export * as Multisig from './Multisig.js'
 export * as P256 from './P256.js'
+/**
+ * Composable relay request handlers alongside the Tempo (Execution) RPC.
+ * @experimental
+ */
+export * as Relay from './Relay.js'
 /** @experimental */
 export * as Scopes from './Scopes.js'
 /** @experimental */
@@ -117,7 +122,6 @@ export {
   http,
   walletNamespaceCompat,
   withFeePayer,
-  withMultisig,
   withRelay,
 } from './Transport.js'
 export * as WebAuthnP256 from './WebAuthnP256.js'