viem 2.53.1 → 2.54.0

package/tempo/actions/wallet.ts

@@ -88,7 +88,7 @@ export declare namespace transfer {
     to: Address
     /**
      * Token to transfer, accepted as either a contract address or a curated
-     * tokenlist symbol (case-insensitive, for example `"pathUsd"`). Symbols
+     * tokenlist symbol (case-insensitive, for example `"pathusd"`). Symbols
      * are resolved against the curated tokenlist on the active chain.
      */
     token: Address | string
@@ -108,7 +108,7 @@ export declare namespace transfer {
     to?: Address | undefined
     /**
      * Token to pre-fill, accepted as either a contract address or a curated
-     * tokenlist symbol (case-insensitive, for example `"pathUsd"`). Symbols
+     * tokenlist symbol (case-insensitive, for example `"pathusd"`). Symbols
      * are resolved against the curated tokenlist on the active chain. Omit
      * to let the user choose.
      */
@@ -214,7 +214,7 @@ export declare namespace swap {
  *
  * const result = await Actions.wallet.deposit(client, {
  *   amount: '1.5',
- *   token: 'pathUsd',
+ *   token: 'pathusd',
  * })
  * ```
  *

package/tempo/internal/types.ts

@@ -1,4 +1,5 @@
 import type { Address } from 'abitype'
+import type { TokenId } from 'ox/tempo'
 import type { Account } from '../../accounts/types.js'
 import type { ReadContractParameters as viem_ReadContractParameters } from '../../actions/public/readContract.js'
 import type { WriteContractSyncParameters as viem_WriteContractSyncParameters } from '../../actions/wallet/writeContractSync.js'
@@ -10,6 +11,24 @@ import type {
 } from '../../types/utils.js'
 import type { TransactionRequestTempo } from '../Transaction.js'
 
+/**
+ * Selects a TIP20 token by `token`, which is either a TIP20 token id or a
+ * contract `address`.
+ */
+export type TokenParameter = {
+  /** Token to operate on: a TIP20 token id or a contract `address`. */
+  token: TokenId.TokenIdOrAddress
+}
+
+export type TokenParameters = TokenParameter & {
+  /**
+   * 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
+}
+
 export type GetAccountParameter<
   account extends Account | undefined = Account | undefined,
   accountOverride extends Account | Address | undefined = Account | Address,

package/tempo/internal/utils.ts

@@ -1,11 +1,215 @@
 import type { Abi, AbiStateMutability, Address } from 'abitype'
+import { TokenId } from 'ox/tempo'
+import { readContract } from '../../actions/public/readContract.js'
+import type { Client } from '../../clients/createClient.js'
+import type { Transport } from '../../clients/transports/createTransport.js'
+import type { ResolvedToken, Token } 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 { isAddressEqual } from '../../utils/address/isAddressEqual.js'
 import { encodeFunctionData } from '../../utils/index.js'
+import * as Abis from '../Abis.js'
+
+/**
+ * Resolves the token contract `address` and `decimals` from a `token`, which is
+ * a token symbol declared on the client's `tokens` array, a TIP20 token id, or
+ * a contract `address`.
+ *
+ * When `token` is a declared symbol, the `address` and `decimals` are read from
+ * the client's declared `tokens` (`decimals` can be overridden via the explicit
+ * `decimals`). When `token` is a token id or address, its `decimals` is inferred
+ * from the client's declared `tokens` 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
+
+  if (typeof token === 'string') {
+    const declared = findDeclaredTokenBySymbol(client, token)
+    if (declared)
+      return {
+        address: declared.address,
+        decimals: decimals ?? declared.decimals,
+      }
+  }
+
+  const address = TokenId.toAddress(token as TokenId.TokenIdOrAddress)
+  return {
+    address,
+    decimals: decimals ?? inferDecimals(client, address),
+  }
+}
+
+export namespace resolveToken {
+  export type Parameters = {
+    /** Decimals, if provided explicitly. */
+    decimals?: number | undefined
+    /** Token symbol (declared on the client's `tokens` array), TIP20 token id, or contract address. */
+    token: TokenId.TokenIdOrAddress | (string & {})
+  }
+}
+
+/**
+ * Finds the declared {@link ResolvedToken} on the client's `tokens` array matching
+ * `token`, which is either a token symbol, a TIP20 token id, or a contract
+ * `address`, resolved 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), TIP20 token id, or contract address.
+ * @returns The matching declared token config, or `undefined`.
+ */
+export function findDeclaredToken(
+  client: Client<Transport, Chain | undefined>,
+  token: TokenId.TokenIdOrAddress | (string & {}),
+): ResolvedToken | undefined {
+  const tokens = client.tokens
+  const chainId = client.chain?.id
+  if (!tokens || chainId === undefined) return undefined
+
+  if (typeof token === 'string') {
+    const declared = findDeclaredTokenBySymbol(client, token)
+    if (declared) return declared
+  }
+
+  const address = TokenId.toAddress(token as TokenId.TokenIdOrAddress)
+  for (const token_ of tokens) {
+    const resolved = resolveTokenForChain(token_, chainId)
+    if (resolved && isAddressEqual(resolved.address, address)) return resolved
+  }
+  return undefined
+}
+
+/**
+ * Finds a declared token by `symbol` (case-insensitively) on the client's
+ * `tokens` array, resolved for the client's `chain.id`. @internal
+ */
+function findDeclaredTokenBySymbol(
+  client: Client<Transport, Chain | undefined>,
+  symbol: string,
+): ResolvedToken | undefined {
+  const tokens = client.tokens
+  const chainId = client.chain?.id
+  if (!tokens || chainId === undefined) return undefined
+
+  const lowerSymbol = symbol.toLowerCase()
+  for (const token of tokens) {
+    if (token.symbol?.toLowerCase() === lowerSymbol)
+      return resolveTokenForChain(token, chainId)
+  }
+  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,
+  }
+}
+
+/**
+ * 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 chain.
+ * @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: Abis.tip20,
+      address,
+      functionName: 'decimals',
+    }),
+  }
+}
+
+/**
+ * Picks the transaction-override fields shared by Tempo write actions (including
+ * Tempo-specific fields), 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,
+    feePayer,
+    feeToken,
+    gas,
+    keyAuthorization,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    nonce,
+    nonceKey,
+    validAfter,
+    validBefore,
+  } = parameters
+  return {
+    account,
+    chain,
+    feePayer,
+    feeToken,
+    gas,
+    keyAuthorization,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    nonce,
+    nonceKey,
+    validAfter,
+    validBefore,
+  }
+}
 
 export function defineCall<
   const abi extends Abi,

package/tokens/defineToken.ts

@@ -0,0 +1,142 @@
+import type { Address } from 'abitype'
+
+/**
+ * A token created by {@link defineToken}: callable with a chain id to produce a
+ * chain-specific token config, and exposing the token metadata
+ * (`currency`, `decimals`, `name`, `popular`, `symbol`) and the full
+ * `addresses` map.
+ */
+export type Token<
+  token extends defineToken.Parameters = defineToken.Parameters,
+> = defineToken.ReturnType<token>
+
+/** Collection of tokens to declare on a Client. */
+export type Tokens = readonly Token[]
+
+/** A {@link Token} resolved to a specific chain id. */
+export type ResolvedToken = {
+  /** Token contract address. */
+  address: Address
+  /** Token currency denomination. */
+  currency?: string | undefined
+  /** Token decimals, used to parse human-readable `amount` strings. */
+  decimals: number
+  /** Token name. */
+  name?: string | undefined
+  /** Whether the token should be treated as popular in token lists. */
+  popular?: boolean | undefined
+  /** Token symbol. */
+  symbol?: string | undefined
+}
+
+/**
+ * Creates a token from shared metadata (`currency`, `decimals`, `name`,
+ * `popular`, `symbol`) and a map of per-chain contract `addresses`. The
+ * returned value is callable with a chain id to produce a chain-specific token
+ * config while also exposing the metadata and the full `addresses` map.
+ *
+ * @param token - {@link defineToken.Parameters}
+ * @returns The token. {@link defineToken.ReturnType}
+ *
+ * @example
+ * ```ts
+ * import { defineToken } from 'viem/tokens'
+ *
+ * const usdc = defineToken({
+ *   addresses: {
+ *     1: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *     8453: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+ *   },
+ *   currency: 'USD',
+ *   decimals: 6,
+ *   name: 'USD Coin',
+ *   popular: true,
+ *   symbol: 'USDC',
+ * })
+ *
+ * usdc(1)
+ * // {
+ * //   address: '0xA0b8…48',
+ * //   currency: 'USD',
+ * //   decimals: 6,
+ * //   name: 'USD Coin',
+ * //   popular: true,
+ * //   symbol: 'USDC',
+ * // }
+ *
+ * usdc.addresses[8453]
+ * // '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
+ * ```
+ */
+export function defineToken<const token extends defineToken.Parameters>(
+  token: token,
+): defineToken.ReturnType<token> {
+  const { addresses, currency, decimals, name, popular, symbol } = token
+  function fn(chainId: number): ResolvedToken {
+    const address = (addresses as Record<number, Address>)[chainId]
+    if (!address)
+      throw new Error(`Token has no address for chain id "${chainId}".`)
+    return { address, currency, decimals, name, popular, symbol }
+  }
+  return Object.defineProperties(fn, {
+    addresses: { enumerable: true, value: addresses },
+    currency: { enumerable: true, value: currency },
+    decimals: { enumerable: true, value: decimals },
+    name: { enumerable: true, value: name },
+    popular: { enumerable: true, value: popular },
+    symbol: { enumerable: true, value: symbol },
+  }) as never
+}
+
+export namespace defineToken {
+  type ParameterValue<
+    token extends Parameters,
+    key extends keyof Parameters,
+  > = token extends { [_ in key]?: infer value } ? value : undefined
+
+  export type Parameters<
+    addresses extends Record<number, Address> = Record<number, Address>,
+  > = {
+    /** Token contract addresses, keyed by chain id. */
+    addresses: addresses
+    /** Currency denomination of the token (e.g. `'USD'`). */
+    currency?: string | undefined
+    /** Number of decimals the token uses. */
+    decimals: number
+    /** Human-readable name of the token. */
+    name?: string | undefined
+    /** Whether the token should be treated as popular in token lists. */
+    popular?: boolean | undefined
+    /** Ticker symbol of the token. */
+    symbol?: string | undefined
+  }
+
+  export type ReturnType<token extends Parameters = Parameters> = {
+    /**
+     * Resolves the token config (`address`, `currency`, `decimals`, `name`,
+     * `popular`, `symbol`) for a chain id.
+     */
+    <chainId extends keyof token['addresses']>(
+      chainId: chainId,
+    ): {
+      address: token['addresses'][chainId]
+      currency: ParameterValue<token, 'currency'>
+      decimals: token['decimals']
+      name: ParameterValue<token, 'name'>
+      popular: ParameterValue<token, 'popular'>
+      symbol: ParameterValue<token, 'symbol'>
+    }
+    /** Token contract addresses, keyed by chain id. */
+    addresses: token['addresses']
+    /** Currency denomination of the token (e.g. `'USD'`). */
+    currency: ParameterValue<token, 'currency'>
+    /** Number of decimals the token uses. */
+    decimals: token['decimals']
+    /** Human-readable name of the token. */
+    name: ParameterValue<token, 'name'>
+    /** Whether the token should be treated as popular in token lists. */
+    popular: ParameterValue<token, 'popular'>
+    /** Ticker symbol of the token. */
+    symbol: ParameterValue<token, 'symbol'>
+  }
+}

package/tokens/definitions/alphausd.ts

@@ -0,0 +1,13 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const alphausd = /*#__PURE__*/ defineToken({
+  addresses: {
+    42431: '0x20c0000000000000000000000000000000000001', // tempoModerato
+  },
+  currency: 'USD',
+  decimals: 6,
+  name: 'AlphaUSD',
+  symbol: 'alphaUSD',
+})

package/tokens/definitions/betausd.ts

@@ -0,0 +1,13 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const betausd = /*#__PURE__*/ defineToken({
+  addresses: {
+    42431: '0x20c0000000000000000000000000000000000002', // tempoModerato
+  },
+  currency: 'USD',
+  decimals: 6,
+  name: 'BetaUSD',
+  symbol: 'betaUSD',
+})

package/tokens/definitions/brla.ts

@@ -0,0 +1,13 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const brla = /*#__PURE__*/ defineToken({
+  addresses: {
+    4217: '0x20c000000000000000000000f047dd7018e50367', // tempo
+  },
+  currency: 'BRL',
+  decimals: 6,
+  name: 'BRLA Token',
+  symbol: 'BRLA',
+})

package/tokens/definitions/cbbtc.ts

@@ -0,0 +1,13 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const cbbtc = /*#__PURE__*/ defineToken({
+  addresses: {
+    4217: '0x20c000000000000000000000c412ec89d0c08be5', // tempo
+  },
+  currency: 'BTC',
+  decimals: 6,
+  name: 'Coinbase Wrapped BTC',
+  symbol: 'cbBTC',
+})

package/tokens/definitions/chfau.ts

@@ -0,0 +1,13 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const chfau = /*#__PURE__*/ defineToken({
+  addresses: {
+    4217: '0x20c00000000000000000000042109aef2f8b28e1', // tempo
+  },
+  currency: 'CHF',
+  decimals: 6,
+  name: 'AllUnity CHF',
+  symbol: 'CHFAU',
+})

package/tokens/definitions/cusd.ts

@@ -0,0 +1,13 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const cusd = /*#__PURE__*/ defineToken({
+  addresses: {
+    4217: '0x20c0000000000000000000000520792dcccccccc', // tempo
+  },
+  currency: 'USD',
+  decimals: 6,
+  name: 'Cap USD',
+  symbol: 'cUSD',
+})

package/tokens/definitions/dlusd.ts

@@ -0,0 +1,13 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const dlusd = /*#__PURE__*/ defineToken({
+  addresses: {
+    4217: '0x20c0000000000000000000006fd9a167923ba194', // tempo
+  },
+  currency: 'USD',
+  decimals: 6,
+  name: 'Deel USD',
+  symbol: 'DLUSD',
+})

package/tokens/definitions/eurau.ts

@@ -0,0 +1,13 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const eurau = /*#__PURE__*/ defineToken({
+  addresses: {
+    4217: '0x20c0000000000000000000009a4a4b17e0dc6651', // tempo
+  },
+  currency: 'EUR',
+  decimals: 6,
+  name: 'AllUnity EUR',
+  symbol: 'EURAU',
+})

package/tokens/definitions/eurce.ts

@@ -0,0 +1,14 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const eurce = /*#__PURE__*/ defineToken({
+  addresses: {
+    4217: '0x20c0000000000000000000001621e21f71cf12fb', // tempo
+    42431: '0x20c000000000000000000000d72572838bbee59c', // tempoModerato
+  },
+  currency: 'EUR',
+  decimals: 6,
+  name: 'Bridged EURC (Stargate)',
+  symbol: 'EURC.e',
+})

package/tokens/definitions/frxusd.ts

@@ -0,0 +1,13 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const frxusd = /*#__PURE__*/ defineToken({
+  addresses: {
+    4217: '0x20c0000000000000000000003554d28269e0f3c2', // tempo
+  },
+  currency: 'USD',
+  decimals: 6,
+  name: 'Frax USD',
+  symbol: 'frxUSD',
+})

package/tokens/definitions/gbpa.ts

@@ -0,0 +1,13 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const gbpa = /*#__PURE__*/ defineToken({
+  addresses: {
+    4217: '0x20c0000000000000000000000a6da882d075a4c3', // tempo
+  },
+  currency: 'GBP',
+  decimals: 6,
+  name: 'Agant GBP',
+  symbol: 'GBPA',
+})

package/tokens/definitions/gusd.ts

@@ -0,0 +1,13 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const gusd = /*#__PURE__*/ defineToken({
+  addresses: {
+    4217: '0x20c0000000000000000000005c0bac7cef389a11', // tempo
+  },
+  currency: 'USD',
+  decimals: 6,
+  name: 'Generic USD',
+  symbol: 'GUSD',
+})

package/tokens/definitions/iusd.ts

@@ -0,0 +1,13 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const iusd = /*#__PURE__*/ defineToken({
+  addresses: {
+    4217: '0x20c000000000000000000000ab02d39df30bd17e', // tempo
+  },
+  currency: 'USD',
+  decimals: 6,
+  name: 'InfiniFi USD',
+  symbol: 'iUSD',
+})

package/tokens/definitions/pathusd.ts

@@ -0,0 +1,14 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const pathusd = /*#__PURE__*/ defineToken({
+  addresses: {
+    4217: '0x20c0000000000000000000000000000000000000', // tempo
+    42431: '0x20c0000000000000000000000000000000000000', // tempoModerato
+  },
+  currency: 'USD',
+  decimals: 6,
+  name: 'PathUSD',
+  symbol: 'pathUSD',
+})

package/tokens/definitions/reusd.ts

@@ -0,0 +1,13 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const reusd = /*#__PURE__*/ defineToken({
+  addresses: {
+    4217: '0x20c000000000000000000000383a23bacb546ab9', // tempo
+  },
+  currency: 'USD',
+  decimals: 6,
+  name: 'Re Protocol reUSD',
+  symbol: 'reUSD',
+})

package/tokens/definitions/rusd.ts

@@ -0,0 +1,13 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const rusd = /*#__PURE__*/ defineToken({
+  addresses: {
+    4217: '0x20c0000000000000000000007f7ba549dd0251b9', // tempo
+  },
+  currency: 'USD',
+  decimals: 6,
+  name: 'Reservoir Stablecoin',
+  symbol: 'rUSD',
+})

package/tokens/definitions/sbc.ts

@@ -0,0 +1,13 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const sbc = /*#__PURE__*/ defineToken({
+  addresses: {
+    4217: '0x20c000000000000000000000ae247a1130450f09', // tempo
+  },
+  currency: 'USD',
+  decimals: 6,
+  name: 'Stable Coin',
+  symbol: 'SBC',
+})

package/tokens/definitions/siusd.ts

@@ -0,0 +1,13 @@
+// Generated with `pnpm gen:tokenlist`. Do not modify manually.
+
+import { defineToken } from '../defineToken.js'
+
+export const siusd = /*#__PURE__*/ defineToken({
+  addresses: {
+    4217: '0x20c000000000000000000000048c8f36df1c9a4a', // tempo
+  },
+  currency: 'siUSD',
+  decimals: 6,
+  name: 'InfiniFi Staked USD',
+  symbol: 'siUSD',
+})