viem 2.53.1 → 2.54.0

package/actions/token/approve.ts

@@ -0,0 +1,202 @@
+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'
+
+/**
+ * Approves a spender to transfer ERC-20 tokens on behalf of the caller.
+ *
+ * @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.approve(client, {
+ *   amount: 100000000n,
+ *   spender: '0x...',
+ *   token: '0x...',
+ * })
+ * ```
+ *
+ * @param client - Client.
+ * @param parameters - Parameters.
+ * @returns The transaction hash.
+ */
+export async function approve<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  tokens extends Tokens | undefined = undefined,
+>(
+  client: Client<Transport, chain, account, undefined, undefined, tokens>,
+  parameters: approve.Parameters<chain, account, tokens>,
+): Promise<approve.ReturnValue> {
+  return approve.inner(writeContract, client, parameters)
+}
+
+export namespace approve {
+  export type Args<
+    chain extends Chain | undefined = Chain | undefined,
+    tokens extends Tokens | undefined = Tokens | undefined,
+  > = {
+    /** Amount to approve in base units, or as a formatted helper. */
+    amount: AmountInput
+    /** Address of the spender. */
+    spender: 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: approve.Parameters<chain, account, tokens>,
+  ): Promise<ReturnType<action>> {
+    return (await action(client, {
+      ...parameters,
+      ...approve.call(client, parameters as never),
+    } as never)) as never
+  }
+
+  /**
+   * Defines a call to the `approve` 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 approve.Args))
+  }
+
+  /**
+   * Estimates the gas required to approve a spender. `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: approve.Parameters<chain, account, tokens>,
+  ): Promise<bigint> {
+    return estimateContractGas(client, {
+      ...pickWriteParameters(parameters as never),
+      ...approve.call(client, parameters as never),
+    } as never)
+  }
+
+  /**
+   * Simulates an approval of a spender. `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: approve.Parameters<chain, account, tokens>,
+  ): Promise<SimulateContractReturnType<typeof erc20Abi, 'approve'>> {
+    return simulateContract(client, {
+      ...pickWriteParameters(parameters as never),
+      ...approve.call(client, parameters as never),
+    } as never) as never
+  }
+
+  /**
+   * Extracts the `Approval` event from logs.
+   *
+   * @param logs - The logs.
+   * @returns The `Approval` event.
+   */
+  export function extractEvent(logs: Log[]) {
+    const [log] = parseEventLogs({
+      abi: erc20Abi,
+      logs,
+      eventName: 'Approval',
+      strict: true,
+    })
+    if (!log) throw new Error('`Approval` event not found.')
+    return log
+  }
+}
+
+/** Builds the underlying `approve` contract call. @internal */
+function getCall(
+  client: Client<Transport, Chain | undefined>,
+  parameters: approve.Args,
+) {
+  const { amount, spender, token } = parameters
+  const { address, decimals } = resolveToken(client, { token })
+  return {
+    abi: erc20Abi,
+    address,
+    args: [spender, toBaseUnits(amount, decimals)],
+    functionName: 'approve',
+  } as const
+}

package/actions/token/approveSync.ts

@@ -0,0 +1,95 @@
+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 { approve } from './approve.js'
+import { resolveAmountDecimals, resolveToken } from './internal.js'
+
+/**
+ * Approves a spender to transfer ERC-20 tokens on behalf of the caller, and
+ * waits for the transaction to be confirmed.
+ *
+ * @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.approveSync(client, {
+ *   amount: 100000000n,
+ *   spender: '0x...',
+ *   token: '0x...',
+ * })
+ * ```
+ *
+ * @param client - Client.
+ * @param parameters - Parameters.
+ * @returns The transaction receipt and event data.
+ */
+export async function approveSync<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  tokens extends Tokens | undefined = undefined,
+>(
+  client: Client<Transport, chain, account, undefined, undefined, tokens>,
+  parameters: approveSync.Parameters<chain, account, tokens>,
+): Promise<approveSync.ReturnValue> {
+  const { amount, token, throwOnReceiptRevert = true } = parameters
+  const { decimals } = resolveToken(client, { token })
+  const resolved = resolveAmountDecimals(amount, decimals)
+  const receipt = await approve.inner(writeContractSync, client, {
+    ...parameters,
+    throwOnReceiptRevert,
+  } as never)
+  const { args } = approve.extractEvent(receipt.logs)
+  return {
+    ...args,
+    ...(resolved === undefined
+      ? {}
+      : { decimals: resolved, formatted: formatUnits(args.value, resolved) }),
+    receipt,
+  } as never
+}
+
+export namespace approveSync {
+  export type Parameters<
+    chain extends Chain | undefined = Chain | undefined,
+    account extends Account | undefined = Account | undefined,
+    tokens extends Tokens | undefined = Tokens | undefined,
+  > = approve.Parameters<chain, account, tokens>
+  export type Args<
+    chain extends Chain | undefined = Chain | undefined,
+    tokens extends Tokens | undefined = Tokens | undefined,
+  > = approve.Args<chain, tokens>
+  export type ReturnValue = Compute<
+    GetEventArgs<
+      typeof erc20Abi,
+      'Approval',
+      { IndexedOnly: false; Required: true }
+    > & {
+      /** Token decimals used to derive `formatted`, if known. */
+      decimals?: number | undefined
+      /** Approved 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/actions/token/getAllowance.ts

@@ -0,0 +1,105 @@
+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 { 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 ERC-20 allowance a spender has over an account's tokens.
+ *
+ * @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 allowance = await token.getAllowance(client, {
+ *   account: '0x...',
+ *   spender: '0x...',
+ *   token: '0x...',
+ * })
+ * ```
+ *
+ * @param client - Client.
+ * @param parameters - Parameters.
+ * @returns The allowance, in base units and human-readable form.
+ */
+export async function getAllowance<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  tokens extends Tokens | undefined = undefined,
+>(
+  client: Client<Transport, chain, account, undefined, undefined, tokens>,
+  parameters: getAllowance.Parameters<chain, tokens>,
+): Promise<getAllowance.ReturnValue> {
+  const { account, decimals, spender, token, ...rest } = parameters
+  const [amount, { decimals: resolved }] = await Promise.all([
+    readContract(client, {
+      ...rest,
+      ...getAllowance.call(client, { account, spender, token } as never),
+    }),
+    resolveTokenWithDecimals(client, {
+      decimals,
+      token,
+    }),
+  ])
+  return toAmount(amount as bigint, resolved)
+}
+
+export namespace getAllowance {
+  export type Args<
+    chain extends Chain | undefined = Chain | undefined,
+    tokens extends Tokens | undefined = Tokens | undefined,
+  > = {
+    /** Account that owns the tokens. */
+    account: Address
+    /** Spender of the tokens. */
+    spender: Address
+  } & TokenParameters<chain, tokens>
+  export type Parameters<
+    chain extends Chain | undefined = Chain | undefined,
+    tokens extends Tokens | undefined = Tokens | undefined,
+  > = ReadParameters & Args<chain, tokens>
+  export type ReturnValue = Amount
+
+  /**
+   * Defines a call to the `allowance` 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,
+      functionName: 'allowance',
+      args: [args.account, args.spender],
+    })
+  }
+}

package/actions/token/getBalance.ts

@@ -0,0 +1,115 @@
+import type { Address } from 'abitype'
+import type { Account } from '../../accounts/types.js'
+import { parseAccount } from '../../accounts/utils/parseAccount.js'
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import { erc20Abi } from '../../constants/abis.js'
+import { AccountNotFoundError } from '../../errors/account.js'
+import type { Tokens } from '../../tokens/defineToken.js'
+import type { GetAccountParameter } from '../../types/account.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 ERC-20 token balance of an account.
+ *
+ * @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 balance = await token.getBalance(client, {
+ *   account: '0x...',
+ *   token: '0x...',
+ * })
+ * ```
+ *
+ * @param client - Client.
+ * @param parameters - Parameters.
+ * @returns The token balance, in base units and human-readable form.
+ */
+export async function getBalance<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  tokens extends Tokens | undefined = undefined,
+>(
+  client: Client<Transport, chain, account, undefined, undefined, tokens>,
+  parameters: getBalance.Parameters<chain, account, tokens>,
+): Promise<getBalance.ReturnValue> {
+  const {
+    account: account_ = client.account,
+    decimals,
+    token,
+    ...rest
+  } = parameters
+  if (!account_) throw new AccountNotFoundError()
+  const account = parseAccount(account_).address
+  const [amount, { decimals: resolved }] = await Promise.all([
+    readContract(client, {
+      ...rest,
+      ...getBalance.call(client, { account, token } as never),
+    }),
+    resolveTokenWithDecimals(client, {
+      decimals,
+      token,
+    }),
+  ])
+  return toAmount(amount, resolved)
+}
+
+export namespace getBalance {
+  export type Args<
+    chain extends Chain | undefined = Chain | undefined,
+    account extends Account | undefined = Account | undefined,
+    tokens extends Tokens | undefined = Tokens | undefined,
+  > = GetAccountParameter<account, Account | Address> &
+    TokenParameters<chain, tokens>
+  export type Parameters<
+    chain extends Chain | undefined = Chain | undefined,
+    account extends Account | undefined = Account | undefined,
+    tokens extends Tokens | undefined = Tokens | undefined,
+  > = Omit<ReadParameters, 'account'> & Args<chain, account, tokens>
+  export type ReturnValue = Amount
+
+  /**
+   * Defines a call to the `balanceOf` 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, account, tokens>,
+  ) {
+    const account_ = args.account ?? client.account
+    if (!account_) throw new AccountNotFoundError()
+    const account = parseAccount(account_).address
+    return defineCall({
+      address: resolveToken(client, args).address,
+      abi: erc20Abi,
+      functionName: 'balanceOf',
+      args: [account],
+    })
+  }
+}

package/actions/token/getMetadata.ts

@@ -0,0 +1,98 @@
+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 {
+  findDeclaredToken,
+  type ReadParameters,
+  resolveToken,
+  type TokenParameter,
+} from './internal.js'
+
+/**
+ * Gets the metadata (`decimals`, `name`, `symbol`) of an ERC-20 token.
+ *
+ * Fields declared on the Client's `tokens` array are used as-is; any missing
+ * field is fetched from the token contract.
+ *
+ * @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 metadata = await token.getMetadata(client, {
+ *   token: '0x...',
+ * })
+ * ```
+ *
+ * @param client - Client.
+ * @param parameters - Parameters.
+ * @returns The token metadata (`decimals`, `name`, `symbol`).
+ */
+export async function getMetadata<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  tokens extends Tokens | undefined = undefined,
+>(
+  client: Client<Transport, chain, account, undefined, undefined, tokens>,
+  parameters: getMetadata.Parameters<chain, tokens>,
+): Promise<getMetadata.ReturnValue> {
+  const { token, ...rest } = parameters
+  const { address } = resolveToken(client, { token })
+  const declared = findDeclaredToken(client, token)
+
+  const [decimals_, name, symbol] = await Promise.all([
+    declared?.decimals ??
+      readContract(client, {
+        ...rest,
+        abi: erc20Abi,
+        address,
+        functionName: 'decimals',
+      }),
+    declared?.name ??
+      readContract(client, {
+        ...rest,
+        abi: erc20Abi,
+        address,
+        functionName: 'name',
+      }),
+    declared?.symbol ??
+      readContract(client, {
+        ...rest,
+        abi: erc20Abi,
+        address,
+        functionName: 'symbol',
+      }),
+  ])
+
+  return {
+    decimals: decimals_ as number,
+    name: name as string,
+    symbol: symbol as string,
+  }
+}
+
+export namespace getMetadata {
+  export type Args<
+    chain extends Chain | undefined = Chain | undefined,
+    tokens extends Tokens | undefined = Tokens | undefined,
+  > = TokenParameter<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 = {
+    /** Number of decimals the token uses. */
+    decimals: number
+    /** Human-readable name of the token. */
+    name: string
+    /** Ticker symbol of the token. */
+    symbol: string
+  }
+}