viem 2.53.1 → 2.54.0

package/actions/token/transferSync.ts

@@ -0,0 +1,99 @@
+import type { Account } from '../../accounts/types.js'
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { erc20Abi } from '../../constants/abis.js'
+import type { BaseErrorType } from '../../errors/base.js'
+import type { Tokens } from '../../tokens/defineToken.js'
+import type { Chain } from '../../types/chain.js'
+import type { GetEventArgs } from '../../types/contract.js'
+import type { TransactionReceipt } from '../../types/transaction.js'
+import type { Compute } from '../../types/utils.js'
+import { formatUnits } from '../../utils/unit/formatUnits.js'
+import { writeContractSync } from '../wallet/writeContractSync.js'
+import { resolveAmountDecimals, resolveToken } from './internal.js'
+import { transfer } from './transfer.js'
+
+/**
+ * Transfers ERC-20 tokens to another address, and waits for the transaction to
+ * be confirmed.
+ *
+ * Pass `from` to transfer on behalf of another address using an allowance
+ * (calls `transferFrom`); otherwise transfers from the caller (calls
+ * `transfer`).
+ *
+ * @example
+ * ```ts
+ * import { createClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { privateKeyToAccount } from 'viem/accounts'
+ * import { token } from 'viem/actions'
+ *
+ * const client = createClient({
+ *   account: privateKeyToAccount('0x...'),
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ *
+ * const { receipt, ...event } = await token.transferSync(client, {
+ *   amount: 100000000n,
+ *   to: '0x...',
+ *   token: '0x...',
+ * })
+ * ```
+ *
+ * @param client - Client.
+ * @param parameters - Parameters.
+ * @returns The transaction receipt and event data.
+ */
+export async function transferSync<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  tokens extends Tokens | undefined = undefined,
+>(
+  client: Client<Transport, chain, account, undefined, undefined, tokens>,
+  parameters: transferSync.Parameters<chain, account, tokens>,
+): Promise<transferSync.ReturnValue> {
+  const { amount, token, throwOnReceiptRevert = true } = parameters
+  const { decimals } = resolveToken(client, { token })
+  const resolved = resolveAmountDecimals(amount, decimals)
+  const receipt = await transfer.inner(writeContractSync, client, {
+    ...parameters,
+    throwOnReceiptRevert,
+  } as never)
+  const { args } = transfer.extractEvent(receipt.logs)
+  return {
+    ...args,
+    ...(resolved === undefined
+      ? {}
+      : { decimals: resolved, formatted: formatUnits(args.value, resolved) }),
+    receipt,
+  } as never
+}
+
+export namespace transferSync {
+  export type Parameters<
+    chain extends Chain | undefined = Chain | undefined,
+    account extends Account | undefined = Account | undefined,
+    tokens extends Tokens | undefined = Tokens | undefined,
+  > = transfer.Parameters<chain, account, tokens>
+  export type Args<
+    chain extends Chain | undefined = Chain | undefined,
+    tokens extends Tokens | undefined = Tokens | undefined,
+  > = transfer.Args<chain, tokens>
+  export type ReturnValue = Compute<
+    GetEventArgs<
+      typeof erc20Abi,
+      'Transfer',
+      { IndexedOnly: false; Required: true }
+    > & {
+      /** Token decimals used to derive `formatted`, if known. */
+      decimals?: number | undefined
+      /** Transferred amount formatted with the token's `decimals`, if known. */
+      formatted?: string | undefined
+      /** Transaction receipt. */
+      receipt: TransactionReceipt
+    }
+  >
+  // TODO: exhaustive error type
+  export type ErrorType = BaseErrorType
+}

package/chains/definitions/battlechain.ts

@@ -0,0 +1,28 @@
+import { defineChain } from '../../utils/chain/defineChain.js'
+import { chainConfig } from '../../zksync/chainConfig.js'
+
+export const battlechain = /*#__PURE__*/ defineChain({
+  ...chainConfig,
+  id: 626,
+  name: 'BattleChain Mainnet',
+  network: 'battlechain',
+  nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+  rpcUrls: {
+    default: {
+      http: ['https://mainnet.battlechain.com'],
+    },
+  },
+  blockExplorers: {
+    default: {
+      name: 'BattleChain Explorer',
+      url: 'https://explorer.battlechain.com',
+      apiUrl: 'https://block-explorer-api.battlechain.com/api',
+    },
+  },
+  contracts: {
+    multicall3: {
+      address: '0xcA11bde05977b3631167028862bE2a173976CA11',
+      blockCreated: 40,
+    },
+  },
+})

package/chains/definitions/marooTestnet.ts

@@ -0,0 +1,27 @@
+import { defineChain } from '../../utils/chain/defineChain.js'
+
+export const marooTestnet = /*#__PURE__*/ defineChain({
+  id: 450_815,
+  name: 'Maroo Testnet',
+  nativeCurrency: { name: 'Testnet OKRW', symbol: 'tOKRW', decimals: 18 },
+  rpcUrls: {
+    default: {
+      http: ['https://rpc-testnet.maroo.io'],
+      webSocket: ['wss://ws-testnet.maroo.io'],
+    },
+  },
+  blockExplorers: {
+    default: {
+      name: 'Blockscout',
+      url: 'https://explorer-testnet.maroo.io',
+      apiUrl: 'https://explorer-testnet.maroo.io/blockscout/api',
+    },
+  },
+  contracts: {
+    multicall3: {
+      address: '0xcA11bde05977b3631167028862bE2a173976CA11',
+      blockCreated: 0,
+    },
+  },
+  testnet: true,
+})

package/chains/index.ts

@@ -63,6 +63,7 @@ export { base, basePreconf } from './definitions/base.js'
 export { basecampTestnet } from './definitions/basecampTestnet.js'
 export { baseGoerli } from './definitions/baseGoerli.js'
 export { baseSepolia, baseSepoliaPreconf } from './definitions/baseSepolia.js'
+export { battlechain } from './definitions/battlechain.js'
 export { battlechainTestnet } from './definitions/battlechainTestnet.js'
 export { beam } from './definitions/beam.js'
 export { beamTestnet } from './definitions/beamTestnet.js'
@@ -390,6 +391,7 @@ export { mantleTestnet } from './definitions/mantleTestnet.js'
 export { mantraDuKongEVMTestnet } from './definitions/mantraDuKongEVMTestnet.js'
 export { mantraEVM } from './definitions/mantraEVM.js'
 export { mapProtocol } from './definitions/mapProtocol.js'
+export { marooTestnet } from './definitions/marooTestnet.js'
 export { matchain } from './definitions/matchain.js'
 export { matchainTestnet } from './definitions/matchainTestnet.js'
 export { mchVerse } from './definitions/mchVerse.js'

package/clients/createClient.ts

@@ -6,6 +6,7 @@ import {
   parseAccount,
 } from '../accounts/utils/parseAccount.js'
 import type { ErrorType } from '../errors/utils.js'
+import type { Tokens } from '../tokens/defineToken.js'
 import type { Account } from '../types/account.js'
 import type { BlockTag } from '../types/block.js'
 import type { Chain } from '../types/chain.js'
@@ -33,6 +34,7 @@ export type ClientConfig<
     | Address
     | undefined,
   rpcSchema extends RpcSchema | undefined = undefined,
+  tokens extends Tokens | undefined = Tokens | undefined,
 > = {
   /** The Account to use for the Client. This will be used for Actions that require an account as an argument. */
   account?: accountOrAddress | Account | Address | undefined
@@ -90,6 +92,12 @@ export type ClientConfig<
    * Typed JSON-RPC schema for the client.
    */
   rpcSchema?: rpcSchema | undefined
+  /**
+   * Collection of tokens to declare on the Client. A token's symbol becomes
+   * available to token Actions (e.g. `token.transfer`) only when its `addresses`
+   * map includes the Client's `chain.id`.
+   */
+  tokens?: tokens | undefined
   /** The RPC transport */
   transport: transport
   /** The type of client. */
@@ -104,8 +112,9 @@ type ExtendableProtectedActions<
   transport extends Transport = Transport,
   chain extends Chain | undefined = Chain | undefined,
   account extends Account | undefined = Account | undefined,
+  tokens extends Tokens | undefined = Tokens | undefined,
 > = Pick<
-  PublicActions<transport, chain, account>,
+  PublicActions<transport, chain, account, tokens>,
   | 'call'
   | 'createContractEventFilter'
   | 'createEventFilter'
@@ -130,7 +139,10 @@ type ExtendableProtectedActions<
   | 'watchBlockNumber'
   | 'watchContractEvent'
 > &
-  Pick<WalletActions<chain, account>, 'sendTransaction' | 'writeContract'>
+  Pick<
+    WalletActions<chain, account, tokens>,
+    'sendTransaction' | 'writeContract'
+  >
 
 // TODO: Move `transport` to slot index 2 since `chain` and `account` used more frequently.
 // Otherwise, we end up with a lot of `Client<Transport, chain, account>` in actions.
@@ -140,21 +152,25 @@ export type Client<
   account extends Account | undefined = Account | undefined,
   rpcSchema extends RpcSchema | undefined = undefined,
   extended extends Extended | undefined = Extended | undefined,
-> = Client_Base<transport, chain, account, rpcSchema> &
+  tokens extends Tokens | undefined = Tokens | undefined,
+> = Client_Base<transport, chain, account, rpcSchema, tokens> &
   (extended extends Extended ? extended : unknown) & {
     extend: <
       const client extends Extended &
-        ExactPartial<ExtendableProtectedActions<transport, chain, account>>,
+        ExactPartial<
+          ExtendableProtectedActions<transport, chain, account, tokens>
+        >,
     >(
       fn: (
-        client: Client<transport, chain, account, rpcSchema, extended>,
+        client: Client<transport, chain, account, rpcSchema, extended, tokens>,
       ) => client,
     ) => Client<
       transport,
       chain,
       account,
       rpcSchema,
-      Prettify<client> & (extended extends Extended ? extended : unknown)
+      Prettify<client> & (extended extends Extended ? extended : unknown),
+      tokens
     >
   }
 
@@ -163,6 +179,7 @@ type Client_Base<
   chain extends Chain | undefined = Chain | undefined,
   account extends Account | undefined = Account | undefined,
   rpcSchema extends RpcSchema | undefined = undefined,
+  tokens extends Tokens | undefined = Tokens | undefined,
 > = {
   /** The Account of the Client. */
   account: account
@@ -188,6 +205,8 @@ type Client_Base<
   request: EIP1193RequestFn<
     rpcSchema extends undefined ? EIP1474Methods : rpcSchema
   >
+  /** Collection of tokens declared on the Client. */
+  tokens: tokens
   /** The RPC transport */
   transport: ReturnType<transport>['config'] & ReturnType<transport>['value']
   /** The type of client. */
@@ -219,8 +238,15 @@ export function createClient<
   chain extends Chain | undefined = undefined,
   accountOrAddress extends Account | Address | undefined = undefined,
   rpcSchema extends RpcSchema | undefined = undefined,
+  const tokens extends Tokens | undefined = undefined,
 >(
-  parameters: ClientConfig<transport, chain, accountOrAddress, rpcSchema>,
+  parameters: ClientConfig<
+    transport,
+    chain,
+    accountOrAddress,
+    rpcSchema,
+    tokens
+  >,
 ): Prettify<
   Client<
     transport,
@@ -228,7 +254,9 @@ export function createClient<
     accountOrAddress extends Address
       ? Prettify<JsonRpcAccount<accountOrAddress>>
       : accountOrAddress,
-    rpcSchema
+    rpcSchema,
+    undefined,
+    tokens
   >
 >
 
@@ -240,6 +268,7 @@ export function createClient(parameters: ClientConfig): Client {
     dataSuffix,
     key = 'base',
     name = 'Base Client',
+    tokens,
     type = 'base',
   } = parameters
 
@@ -278,6 +307,7 @@ export function createClient(parameters: ClientConfig): Client {
     name,
     pollingInterval,
     request,
+    tokens,
     transport,
     type,
     uid: uid(),
@@ -290,6 +320,17 @@ export function createClient(parameters: ClientConfig): Client {
       const extended = extendFn(base) as Extended
       for (const key in client) delete extended[key]
       const combined = { ...base, ...extended }
+      // For keys that exist on both the base client and the extension and
+      // resolve to plain objects (e.g. namespaces like `token`), shallow-merge
+      // their members instead of overwriting. This lets decorators contribute
+      // to the same namespace (e.g. `publicActions` adds read actions and
+      // `walletActions` adds write actions to `client.token`).
+      for (const key in extended) {
+        const a = (base as Record<string, unknown>)[key]
+        const b = (extended as Record<string, unknown>)[key]
+        if (isPlainObject(a) && isPlainObject(b))
+          (combined as Record<string, unknown>)[key] = { ...a, ...b }
+      }
       return Object.assign(combined, { extend: extend(combined as any) })
     }
   }
@@ -297,6 +338,47 @@ export function createClient(parameters: ClientConfig): Client {
   return Object.assign(client, { extend: extend(client) as any })
 }
 
+/** Whether `value` is a plain object (`{}`), as opposed to a function, array,
+ * or class instance. Used to decide which extension namespaces to merge. */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+/**
+ * Binds an action function to a `client`, returning a parameter-only version
+ * along with any helpers the action exposes. Helpers that need a client
+ * (`.call`, `.calls`, `.callWithPeriod`, `.estimateGas`, `.simulate`) are bound
+ * to `client`; pure helpers (`.extractEvent`, `.extractEvents`) are copied
+ * as-is. Used by decorators that attach namespaced actions to a Client.
+ * @internal
+ */
+export function bindActionDecorators(
+  client: Client<Transport, Chain | undefined, any>,
+  action: any,
+) {
+  const wrapped: any = (parameters: any = {}) => action(client, parameters)
+  for (const key of [
+    'call',
+    'calls',
+    'callWithPeriod',
+    'estimateGas',
+    'simulate',
+  ] as const)
+    if (Object.hasOwn(action, key)) {
+      const helper = action[key]
+      wrapped[key] = (args: any = {}) => {
+        if (helper.length >= 2) return helper(client, args)
+        if (helper.length === 0) return helper()
+        return helper(args)
+      }
+    }
+  for (const key of ['extractEvent', 'extractEvents'] as const)
+    if (Object.hasOwn(action, key)) wrapped[key] = action[key]
+  return wrapped
+}
+
 /**
  * Defines a typed JSON-RPC schema for the client.
  * Note: This is a runtime noop function.

package/clients/createPublicClient.ts

@@ -1,5 +1,6 @@
 import type { Address } from 'abitype'
 import type { ErrorType } from '../errors/utils.js'
+import type { Tokens } from '../tokens/defineToken.js'
 import type { Account, ParseAccount } from '../types/account.js'
 import type { Chain } from '../types/chain.js'
 import type { PublicRpcSchema, RpcSchema } from '../types/eip1193.js'
@@ -18,9 +19,10 @@ export type PublicClientConfig<
   chain extends Chain | undefined = Chain | undefined,
   accountOrAddress extends Account | Address | undefined = undefined,
   rpcSchema extends RpcSchema | undefined = undefined,
+  tokens extends Tokens | undefined = Tokens | undefined,
 > = Prettify<
   Pick<
-    ClientConfig<transport, chain, accountOrAddress, rpcSchema>,
+    ClientConfig<transport, chain, accountOrAddress, rpcSchema, tokens>,
     | 'batch'
     | 'cacheTime'
     | 'ccipRead'
@@ -30,6 +32,7 @@ export type PublicClientConfig<
     | 'name'
     | 'pollingInterval'
     | 'rpcSchema'
+    | 'tokens'
     | 'transport'
   >
 >
@@ -39,6 +42,7 @@ export type PublicClient<
   chain extends Chain | undefined = Chain | undefined,
   accountOrAddress extends Account | undefined = undefined,
   rpcSchema extends RpcSchema | undefined = undefined,
+  tokens extends Tokens | undefined = Tokens | undefined,
 > = Prettify<
   Client<
     transport,
@@ -47,7 +51,8 @@ export type PublicClient<
     rpcSchema extends RpcSchema
       ? [...PublicRpcSchema, ...rpcSchema]
       : PublicRpcSchema,
-    PublicActions<transport, chain>
+    PublicActions<transport, chain, accountOrAddress, tokens>,
+    tokens
   >
 >
 
@@ -77,9 +82,22 @@ export function createPublicClient<
   chain extends Chain | undefined = undefined,
   accountOrAddress extends Account | Address | undefined = undefined,
   rpcSchema extends RpcSchema | undefined = undefined,
+  const tokens extends Tokens | undefined = undefined,
 >(
-  parameters: PublicClientConfig<transport, chain, accountOrAddress, rpcSchema>,
-): PublicClient<transport, chain, ParseAccount<accountOrAddress>, rpcSchema> {
+  parameters: PublicClientConfig<
+    transport,
+    chain,
+    accountOrAddress,
+    rpcSchema,
+    tokens
+  >,
+): PublicClient<
+  transport,
+  chain,
+  ParseAccount<accountOrAddress>,
+  rpcSchema,
+  tokens
+> {
   const { key = 'public', name = 'Public Client' } = parameters
   const client = createClient({
     ...parameters,

package/clients/createWalletClient.ts

@@ -2,6 +2,7 @@ import type { Address } from 'abitype'
 
 import type { Account } from '../accounts/types.js'
 import type { ErrorType } from '../errors/utils.js'
+import type { Tokens } from '../tokens/defineToken.js'
 import type { ParseAccount } from '../types/account.js'
 import type { Chain } from '../types/chain.js'
 import type { RpcSchema, WalletRpcSchema } from '../types/eip1193.js'
@@ -23,9 +24,10 @@ export type WalletClientConfig<
     | Address
     | undefined,
   rpcSchema extends RpcSchema | undefined = undefined,
+  tokens extends Tokens | undefined = Tokens | undefined,
 > = Prettify<
   Pick<
-    ClientConfig<transport, chain, accountOrAddress, rpcSchema>,
+    ClientConfig<transport, chain, accountOrAddress, rpcSchema, tokens>,
     | 'account'
     | 'cacheTime'
     | 'ccipRead'
@@ -35,6 +37,7 @@ export type WalletClientConfig<
     | 'name'
     | 'pollingInterval'
     | 'rpcSchema'
+    | 'tokens'
     | 'transport'
   >
 >
@@ -44,6 +47,7 @@ export type WalletClient<
   chain extends Chain | undefined = Chain | undefined,
   account extends Account | undefined = Account | undefined,
   rpcSchema extends RpcSchema | undefined = undefined,
+  tokens extends Tokens | undefined = Tokens | undefined,
 > = Prettify<
   Client<
     transport,
@@ -52,7 +56,8 @@ export type WalletClient<
     rpcSchema extends RpcSchema
       ? [...WalletRpcSchema, ...rpcSchema]
       : WalletRpcSchema,
-    WalletActions<chain, account>
+    WalletActions<chain, account, tokens>,
+    tokens
   >
 >
 
@@ -99,9 +104,22 @@ export function createWalletClient<
   chain extends Chain | undefined = undefined,
   accountOrAddress extends Account | Address | undefined = undefined,
   rpcSchema extends RpcSchema | undefined = undefined,
+  const tokens extends Tokens | undefined = undefined,
 >(
-  parameters: WalletClientConfig<transport, chain, accountOrAddress, rpcSchema>,
-): WalletClient<transport, chain, ParseAccount<accountOrAddress>, rpcSchema>
+  parameters: WalletClientConfig<
+    transport,
+    chain,
+    accountOrAddress,
+    rpcSchema,
+    tokens
+  >,
+): WalletClient<
+  transport,
+  chain,
+  ParseAccount<accountOrAddress>,
+  rpcSchema,
+  tokens
+>
 
 export function createWalletClient(
   parameters: WalletClientConfig,