viem 2.53.1 → 2.54.0

package/actions/token/getTotalSupply.ts

@@ -0,0 +1,97 @@
+import type { Account } from '../../accounts/types.js'
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import { erc20Abi } from '../../constants/abis.js'
+import type { Tokens } from '../../tokens/defineToken.js'
+import type { Chain } from '../../types/chain.js'
+import { readContract } from '../public/readContract.js'
+import {
+  type Amount,
+  defineCall,
+  type ReadParameters,
+  resolveToken,
+  resolveTokenWithDecimals,
+  type TokenParameters,
+  toAmount,
+} from './internal.js'
+
+/**
+ * Gets the total supply of an ERC-20 token.
+ *
+ * @example
+ * ```ts
+ * import { createClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { token } from 'viem/actions'
+ *
+ * const client = createClient({ chain: mainnet, transport: http() })
+ *
+ * const totalSupply = await token.getTotalSupply(client, {
+ *   token: '0x...',
+ * })
+ * ```
+ *
+ * @param client - Client.
+ * @param parameters - Parameters.
+ * @returns The token total supply, in base units and human-readable form.
+ */
+export async function getTotalSupply<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  tokens extends Tokens | undefined = undefined,
+>(
+  client: Client<Transport, chain, account, undefined, undefined, tokens>,
+  parameters: getTotalSupply.Parameters<chain, tokens>,
+): Promise<getTotalSupply.ReturnValue> {
+  const { decimals, token, ...rest } = parameters
+  const [amount, { decimals: resolved }] = await Promise.all([
+    readContract(client, {
+      ...rest,
+      ...getTotalSupply.call(client, { token } as never),
+    }),
+    resolveTokenWithDecimals(client, {
+      decimals,
+      token,
+    }),
+  ])
+  return toAmount(amount as bigint, resolved)
+}
+
+export namespace getTotalSupply {
+  export type Args<
+    chain extends Chain | undefined = Chain | undefined,
+    tokens extends Tokens | undefined = Tokens | undefined,
+  > = TokenParameters<chain, tokens>
+  export type Parameters<
+    chain extends Chain | undefined = Chain | undefined,
+    tokens extends Tokens | undefined = Tokens | undefined,
+  > = Omit<ReadParameters, 'account'> & Args<chain, tokens>
+  export type ReturnValue = Amount
+
+  /**
+   * Defines a call to the `totalSupply` function.
+   *
+   * Can be passed as a parameter to `multicall`, `simulateContract`, or any
+   * other action that accepts a contract call. The token is selected by `token`
+   * symbol (resolved from the client's `tokens` array) or contract address.
+   *
+   * @param client - Client.
+   * @param args - Arguments.
+   * @returns The call.
+   */
+  export function call<
+    chain extends Chain | undefined,
+    account extends Account | undefined,
+    tokens extends Tokens | undefined = undefined,
+  >(
+    client: Client<Transport, chain, account, undefined, undefined, tokens>,
+    args: Args<chain, tokens>,
+  ) {
+    return defineCall({
+      address: resolveToken(client, args).address,
+      abi: erc20Abi,
+      args: [],
+      functionName: 'totalSupply',
+    })
+  }
+}

package/actions/token/index.ts

@@ -0,0 +1,9 @@
+// biome-ignore lint/performance/noBarrelFile: entrypoint module
+export { approve } from './approve.js'
+export { approveSync } from './approveSync.js'
+export { getAllowance } from './getAllowance.js'
+export { getBalance } from './getBalance.js'
+export { getMetadata } from './getMetadata.js'
+export { getTotalSupply } from './getTotalSupply.js'
+export { transfer } from './transfer.js'
+export { transferSync } from './transferSync.js'

package/actions/token/internal.ts

@@ -0,0 +1,367 @@
+import type { Abi, AbiStateMutability, Address } from 'abitype'
+import type { Account } from '../../accounts/types.js'
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import { erc20Abi } from '../../constants/abis.js'
+import type { ResolvedToken, Token, Tokens } from '../../tokens/defineToken.js'
+import type { Chain } from '../../types/chain.js'
+import type {
+  ContractFunctionName,
+  ContractFunctionParameters,
+  ExtractAbiItem,
+} from '../../types/contract.js'
+import type { Hex } from '../../types/misc.js'
+import type { UnionPick } from '../../types/utils.js'
+import { isAddress } from '../../utils/address/isAddress.js'
+import { isAddressEqual } from '../../utils/address/isAddressEqual.js'
+import { encodeFunctionData } from '../../utils/index.js'
+import { formatUnits } from '../../utils/unit/formatUnits.js'
+import { parseUnits } from '../../utils/unit/parseUnits.js'
+import type { ReadContractParameters as viem_ReadContractParameters } from '../public/readContract.js'
+import { readContract } from '../public/readContract.js'
+import type { WriteContractSyncParameters as viem_WriteContractSyncParameters } from '../wallet/writeContractSync.js'
+
+/**
+ * Union of symbols of the Client's declared `tokens` whose `addresses` include
+ * the Client's `chain.id`. Collapses to `never` when there is no chain mapping
+ * (no `tokens`, no `chain`, a widened `chain.id`, or widened token symbols).
+ *
+ * @internal
+ */
+export type TokenName<
+  chain extends Chain | undefined,
+  tokens extends Tokens | undefined,
+> = chain extends { id: infer chainId extends number }
+  ? number extends chainId
+    ? never
+    : tokens extends Tokens
+      ? TokenSymbolForChain<tokens[number], chainId>
+      : never
+  : never
+
+type TokenSymbolForChain<token, chainId extends number> = token extends Token
+  ? chainId extends keyof token['addresses']
+    ? token['symbol'] extends string
+      ? string extends token['symbol']
+        ? never
+        : Lowercase<token['symbol']>
+      : never
+    : never
+  : never
+
+/**
+ * Selects an ERC-20 token by `token`, which is either the symbol of a token
+ * declared on the Client's `tokens` array or a contract `address`.
+ *
+ * When `token` is a declared symbol (or an address that matches a declared
+ * token), token metadata is resolved from the Client's `tokens` array.
+ */
+export type TokenParameter<
+  chain extends Chain | undefined,
+  tokens extends Tokens | undefined,
+> = {
+  /**
+   * Token to operate on: either the symbol of a token declared on the Client's
+   * `tokens` array (with an address for the Client's `chain.id`), or a
+   * contract `address`.
+   */
+  token: TokenName<chain, tokens> | Address
+}
+
+export type TokenParameters<
+  chain extends Chain | undefined,
+  tokens extends Tokens | undefined,
+> = TokenParameter<chain, tokens> & {
+  /**
+   * Decimals used to convert between base units and the human-readable amount.
+   * Inferred from the Client's `tokens` array when `token` matches a declared
+   * token; otherwise fetched from the token contract when needed.
+   */
+  decimals?: number | undefined
+}
+
+/**
+ * A token amount, expressed both in the token's base units (`amount`) and as a
+ * human-readable decimal string (`formatted`, derived from the token's
+ * `decimals`).
+ */
+export type Amount = {
+  /** Amount in the token's base units. */
+  amount: bigint
+  /** Token decimals used to derive `formatted`. */
+  decimals: number
+  /** Amount formatted as a human-readable decimal string. */
+  formatted: string
+}
+
+/** A write amount: a base-unit bigint, or an explicit formatted helper. */
+export type AmountInput =
+  | bigint
+  | {
+      /** Token decimals used to parse `formatted`. */
+      decimals?: number | undefined
+      /** Human-readable decimal amount. */
+      formatted: string
+    }
+
+/**
+ * Shapes a base-unit value into an {@link Amount} (base units, `decimals`, and
+ * human-readable `formatted` string).
+ *
+ * @param amount - Amount in base units.
+ * @param decimals - Token decimals used to format the amount.
+ * @returns The {@link Amount}.
+ */
+export function toAmount(amount: bigint, decimals: number): Amount {
+  return { amount, decimals, formatted: formatUnits(amount, decimals) }
+}
+
+/**
+ * Resolves a write amount to base units.
+ *
+ * @param amount - Base-unit amount, or formatted helper.
+ * @param decimals - Token decimals used to parse formatted amounts.
+ * @returns Amount in base units.
+ */
+export function toBaseUnits(
+  amount: AmountInput,
+  decimals: number | undefined,
+): bigint {
+  if (typeof amount === 'bigint') return amount
+  const resolved = amount.decimals ?? decimals
+  return parseUnits(amount.formatted, requireTokenDecimals(resolved))
+}
+
+/**
+ * Requires resolved token decimals for parsing or formatting amounts.
+ *
+ * @param decimals - Token decimals.
+ * @returns Token decimals.
+ * @internal
+ */
+export function requireTokenDecimals(decimals: number | undefined): number {
+  if (decimals === undefined)
+    throw new Error(
+      'Token decimals are required. Pass `amount.decimals` or select a declared token.',
+    )
+  return decimals
+}
+
+/**
+ * Resolves the decimals used for formatting a write amount.
+ *
+ * @param amount - Base-unit amount, or formatted helper.
+ * @param decimals - Token decimals.
+ * @returns Token decimals, overridden by the formatted helper when present.
+ */
+export function resolveAmountDecimals(
+  amount: AmountInput,
+  decimals: number | undefined,
+): number | undefined {
+  if (typeof amount === 'bigint') return decimals
+  return amount.decimals ?? decimals
+}
+
+/**
+ * Resolves the token contract `address` and `decimals` from a `token`, which is
+ * either the symbol of a token declared on the client's `tokens` array or a
+ * contract `address`.
+ *
+ * When `token` is a declared symbol, the `address` and `decimals` are resolved
+ * from the Client's `tokens` array for the Client's `chain.id` (`decimals` can
+ * be overridden via the explicit `decimals`). When `token` is an address, its
+ * `decimals` is inferred from the Client's `tokens` array when the address
+ * matches a declared token, otherwise taken from the explicit `decimals`.
+ *
+ * @param client - Client.
+ * @param parameters - Parameters.
+ * @returns The resolved `address` and `decimals`.
+ */
+export function resolveToken(
+  client: Client<Transport, Chain | undefined>,
+  parameters: resolveToken.Parameters,
+): { address: Address; decimals: number | undefined } {
+  const { decimals, token } = parameters
+
+  const declared = findDeclaredToken(client, token)
+  if (declared)
+    return {
+      address: declared.address,
+      decimals: decimals ?? declared.decimals,
+    }
+
+  if (isAddress(token, { strict: false }))
+    return {
+      address: token,
+      decimals: decimals ?? inferDecimals(client, token),
+    }
+
+  throw new Error(
+    `Token "${token}" is not a declared ERC-20 token on the client's \`tokens\` array (with an address for the client's chain), and is not a valid address.`,
+  )
+}
+
+export namespace resolveToken {
+  export type Parameters = {
+    /** Decimals, if provided explicitly. */
+    decimals?: number | undefined
+    /** Token symbol (declared on the client's `tokens` array) or contract address. */
+    token: string
+  }
+}
+
+/**
+ * Finds the declared token on the Client's `tokens` array matching `token`
+ * (either a token symbol or contract `address`), resolved to a {@link ResolvedToken}
+ * for the Client's `chain.id`. Returns `undefined` when no declared token
+ * matches, or the matching token has no address for the Client's chain.
+ *
+ * @param client - Client.
+ * @param token - Token symbol (declared on the client's `tokens` array) or contract address.
+ * @returns The matching resolved token config, or `undefined`.
+ */
+export function findDeclaredToken(
+  client: Client<Transport, Chain | undefined>,
+  token: string,
+): ResolvedToken | undefined {
+  const tokens = client.tokens
+  const chainId = client.chain?.id
+  if (!tokens || chainId === undefined) return undefined
+
+  const bySymbol = findTokenBySymbol(tokens, token)
+  if (bySymbol) return resolveTokenForChain(bySymbol, chainId)
+
+  if (isAddress(token, { strict: false }))
+    for (const token_ of tokens) {
+      const resolved = resolveTokenForChain(token_, chainId)
+      if (resolved && isAddressEqual(resolved.address, token)) return resolved
+    }
+  return undefined
+}
+
+/**
+ * Resolves a {@link Token} to a {@link ResolvedToken} for `chainId`, or
+ * `undefined` when the token has no address for `chainId`. @internal
+ */
+function resolveTokenForChain(
+  token: Token,
+  chainId: number,
+): ResolvedToken | undefined {
+  const address = (token.addresses as Record<number, Address>)[chainId]
+  if (!address) return undefined
+  return {
+    address,
+    currency: token.currency,
+    decimals: token.decimals,
+    name: token.name,
+    popular: token.popular,
+    symbol: token.symbol,
+  }
+}
+
+/** Finds a {@link Token} by symbol (case-insensitively) on a `tokens` array. @internal */
+function findTokenBySymbol(tokens: Tokens, symbol: string): Token | undefined {
+  const lowerSymbol = symbol.toLowerCase()
+  for (const token of tokens) {
+    if (token.symbol?.toLowerCase() === lowerSymbol) return token
+  }
+  return undefined
+}
+
+/**
+ * Infers a token's `decimals` from the Client's `tokens` array by matching
+ * `address` against each token's address for the Client's `chain.id`.
+ * @internal
+ */
+function inferDecimals(
+  client: Client<Transport, Chain | undefined>,
+  address: Address,
+): number | undefined {
+  const tokens = client.tokens
+  const chainId = client.chain?.id
+  if (tokens && chainId !== undefined)
+    for (const token of tokens) {
+      const resolved = resolveTokenForChain(token, chainId)
+      if (resolved && isAddressEqual(resolved.address, address))
+        return resolved.decimals
+    }
+  return undefined
+}
+
+/**
+ * Resolves token decimals, fetching from the token contract when they are not
+ * provided explicitly or declared on the client.
+ * @internal
+ */
+export async function resolveTokenWithDecimals(
+  client: Client<Transport, Chain | undefined>,
+  parameters: resolveToken.Parameters,
+): Promise<{ address: Address; decimals: number }> {
+  const { address, decimals } = resolveToken(client, parameters)
+  if (decimals !== undefined) return { address, decimals }
+  return {
+    address,
+    decimals: await readContract(client, {
+      abi: erc20Abi,
+      address,
+      functionName: 'decimals',
+    }),
+  }
+}
+
+/**
+ * Picks the transaction-override fields shared by write actions, so the
+ * action-specific args (`token`, `amount`, `to`, etc.) don't leak into
+ * `estimateContractGas` / `simulateContract` requests. @internal
+ */
+export function pickWriteParameters(parameters: Record<string, unknown>) {
+  const { account, chain, gas, maxFeePerGas, maxPriorityFeePerGas, nonce } =
+    parameters
+  return { account, chain, gas, maxFeePerGas, maxPriorityFeePerGas, nonce }
+}
+
+export type ReadParameters = Pick<
+  viem_ReadContractParameters<never, never, never>,
+  'account' | 'blockNumber' | 'blockOverrides' | 'blockTag' | 'stateOverride'
+>
+
+export type WriteParameters<
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+> = UnionPick<
+  viem_WriteContractSyncParameters<never, never, never, chain, account>,
+  | 'account'
+  | 'chain'
+  | 'gas'
+  | 'maxFeePerGas'
+  | 'maxPriorityFeePerGas'
+  | 'nonce'
+  | 'throwOnReceiptRevert'
+>
+
+export function defineCall<
+  const abi extends Abi,
+  const functionName extends ContractFunctionName<abi, AbiStateMutability>,
+  call extends ContractFunctionParameters<
+    abi,
+    AbiStateMutability,
+    functionName
+  >,
+>(
+  call:
+    | call
+    | ContractFunctionParameters<abi, AbiStateMutability, functionName>,
+): ContractFunctionParameters<
+  [ExtractAbiItem<abi, functionName>],
+  AbiStateMutability,
+  functionName
+> & {
+  data: Hex
+  to: Address
+} {
+  return {
+    ...(call as any),
+    data: encodeFunctionData(call as never),
+    to: call.address,
+  } as const
+}

package/actions/token/transfer.ts

@@ -0,0 +1,230 @@
+import type { Address } from 'abitype'
+import type { Account } from '../../accounts/types.js'
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import { 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 { Log } from '../../types/log.js'
+import { parseEventLogs } from '../../utils/abi/parseEventLogs.js'
+import { estimateContractGas } from '../public/estimateContractGas.js'
+import {
+  type SimulateContractReturnType,
+  simulateContract,
+} from '../public/simulateContract.js'
+import type { WriteContractReturnType } from '../wallet/writeContract.js'
+import { writeContract } from '../wallet/writeContract.js'
+import type { writeContractSync } from '../wallet/writeContractSync.js'
+import {
+  type AmountInput,
+  defineCall,
+  pickWriteParameters,
+  resolveToken,
+  type TokenParameter,
+  toBaseUnits,
+  type WriteParameters,
+} from './internal.js'
+
+/**
+ * Transfers ERC-20 tokens to another address.
+ *
+ * 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 hash = await token.transfer(client, {
+ *   amount: 100000000n,
+ *   to: '0x...',
+ *   token: '0x...',
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Transfer on behalf of another address (via an allowance).
+ * const hash = await token.transfer(client, {
+ *   amount: 100000000n,
+ *   from: '0x...',
+ *   to: '0x...',
+ *   token: '0x...',
+ * })
+ * ```
+ *
+ * @param client - Client.
+ * @param parameters - Parameters.
+ * @returns The transaction hash.
+ */
+export async function transfer<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  tokens extends Tokens | undefined = undefined,
+>(
+  client: Client<Transport, chain, account, undefined, undefined, tokens>,
+  parameters: transfer.Parameters<chain, account, tokens>,
+): Promise<transfer.ReturnValue> {
+  return transfer.inner(writeContract, client, parameters)
+}
+
+export namespace transfer {
+  export type Args<
+    chain extends Chain | undefined = Chain | undefined,
+    tokens extends Tokens | undefined = Tokens | undefined,
+  > = {
+    /** Amount to transfer in base units, or as a formatted helper. */
+    amount: AmountInput
+    /** Address to transfer tokens from (uses an allowance via `transferFrom`). */
+    from?: Address | undefined
+    /** Address to transfer tokens to. */
+    to: Address
+  } & TokenParameter<chain, tokens>
+  export type Parameters<
+    chain extends Chain | undefined = Chain | undefined,
+    account extends Account | undefined = Account | undefined,
+    tokens extends Tokens | undefined = Tokens | undefined,
+  > = WriteParameters<chain, account> & Args<chain, tokens>
+  export type ReturnValue = WriteContractReturnType
+  // TODO: exhaustive error type
+  export type ErrorType = BaseErrorType
+
+  /** @internal */
+  export async function inner<
+    action extends typeof writeContract | typeof writeContractSync,
+    chain extends Chain | undefined,
+    account extends Account | undefined,
+    tokens extends Tokens | undefined = undefined,
+  >(
+    action: action,
+    client: Client<Transport, chain, account, undefined, undefined, tokens>,
+    parameters: transfer.Parameters<chain, account, tokens>,
+  ): Promise<ReturnType<action>> {
+    return (await action(client, {
+      ...parameters,
+      ...transfer.call(client, parameters as never),
+    } as never)) as never
+  }
+
+  /**
+   * Defines a call to the `transfer` (or `transferFrom`, when `from` is given)
+   * function.
+   *
+   * Can be passed as a parameter to `estimateContractGas`, `simulateContract`,
+   * `sendCalls`, `sendTransaction` (`calls`), or `multicall`. The token is
+   * selected by `token`, which is either a token symbol (resolved from the
+   * client's `tokens` array) or a contract `address`; `amount.decimals`
+   * is inferred from declared client tokens when omitted.
+   *
+   * @param client - Client.
+   * @param parameters - Parameters.
+   * @returns The call.
+   */
+  export function call<
+    chain extends Chain | undefined,
+    account extends Account | undefined,
+    tokens extends Tokens | undefined = undefined,
+  >(
+    client: Client<Transport, chain, account, undefined, undefined, tokens>,
+    parameters: Args<chain, tokens>,
+  ) {
+    return defineCall(getCall(client, parameters as transfer.Args))
+  }
+
+  /**
+   * Estimates the gas required to transfer ERC-20 tokens. `amount.decimals` is
+   * inferred from declared client tokens when omitted.
+   *
+   * @param client - Client.
+   * @param parameters - Parameters.
+   * @returns The gas estimate.
+   */
+  export async function estimateGas<
+    chain extends Chain | undefined,
+    account extends Account | undefined,
+    tokens extends Tokens | undefined = undefined,
+  >(
+    client: Client<Transport, chain, account, undefined, undefined, tokens>,
+    parameters: transfer.Parameters<chain, account, tokens>,
+  ): Promise<bigint> {
+    return estimateContractGas(client, {
+      ...pickWriteParameters(parameters as never),
+      ...transfer.call(client, parameters as never),
+    } as never)
+  }
+
+  /**
+   * Simulates a transfer of ERC-20 tokens. `amount.decimals` is inferred from
+   * declared client tokens when omitted.
+   *
+   * @param client - Client.
+   * @param parameters - Parameters.
+   * @returns The simulation result and write request.
+   */
+  export async function simulate<
+    chain extends Chain | undefined,
+    account extends Account | undefined,
+    tokens extends Tokens | undefined = undefined,
+  >(
+    client: Client<Transport, chain, account, undefined, undefined, tokens>,
+    parameters: transfer.Parameters<chain, account, tokens>,
+  ): Promise<
+    SimulateContractReturnType<typeof erc20Abi, 'transfer' | 'transferFrom'>
+  > {
+    return simulateContract(client, {
+      ...pickWriteParameters(parameters as never),
+      ...transfer.call(client, parameters as never),
+    } as never) as never
+  }
+
+  /**
+   * Extracts the `Transfer` event from logs.
+   *
+   * @param logs - The logs.
+   * @returns The `Transfer` event.
+   */
+  export function extractEvent(logs: Log[]) {
+    const [log] = parseEventLogs({
+      abi: erc20Abi,
+      logs,
+      eventName: 'Transfer',
+      strict: true,
+    })
+    if (!log) throw new Error('`Transfer` event not found.')
+    return log
+  }
+}
+
+/** Builds the underlying `transfer`/`transferFrom` contract call. @internal */
+function getCall(
+  client: Client<Transport, Chain | undefined>,
+  parameters: transfer.Args,
+) {
+  const { amount, from, to, token } = parameters
+  const { address, decimals } = resolveToken(client, { token })
+  const value = toBaseUnits(amount, decimals)
+  if (from)
+    return {
+      abi: erc20Abi,
+      address,
+      args: [from, to, value],
+      functionName: 'transferFrom',
+    } as const
+  return {
+    abi: erc20Abi,
+    address,
+    args: [to, value],
+    functionName: 'transfer',
+  } as const
+}