thirdweb 5.69.0 → 5.70.0-nightly-ecaa304a812188da3c81888bb52ca6064093c139-20241121000332

package/src/react/web/ui/prebuilt/Token/name.tsx

@@ -0,0 +1,201 @@
+"use client";
+
+import { type UseQueryOptions, useQuery } from "@tanstack/react-query";
+import type React from "react";
+import type { JSX } from "react";
+import { getChainMetadata } from "../../../../../chains/utils.js";
+import { NATIVE_TOKEN_ADDRESS } from "../../../../../constants/addresses.js";
+import { getContract } from "../../../../../contract/contract.js";
+import { getContractMetadata } from "../../../../../extensions/common/read/getContractMetadata.js";
+import { name } from "../../../../../extensions/common/read/name.js";
+import { useTokenContext } from "./provider.js";
+
+/**
+ * Props for the TokenName component
+ * @component
+ * @token
+ */
+export interface TokenNameProps
+  extends Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> {
+  /**
+   * This prop can be a string or a (async) function that resolves to a string, representing the name of the token
+   * This is particularly useful if you already have a way to fetch the token name.
+   */
+  nameResolver?: string | (() => string) | (() => Promise<string>);
+  /**
+   * A function to format the name's display value
+   * Particularly useful to avoid overflowing-UI issues
+   *
+   * ```tsx
+   * <TokenName formatFn={(str: string) => doSomething()} />
+   * ```
+   */
+  formatFn?: (str: string) => string;
+  /**
+   * This component will be shown while the name of the token is being fetched
+   * If not passed, the component will return `null`.
+   *
+   * You can/should pass a loading sign or spinner to this prop.
+   * @example
+   * ```tsx
+   * <TokenName loadingComponent={<Spinner />} />
+   * ```
+   */
+  loadingComponent?: JSX.Element;
+  /**
+   * This component will be shown if the name fails to be retreived
+   * If not passed, the component will return `null`.
+   *
+   * You can/should pass a descriptive text/component to this prop, indicating that the
+   * name was not fetched succesfully
+   * @example
+   * ```tsx
+   * <TokenName fallbackComponent={"Failed to load"}
+   * />
+   * ```
+   */
+  fallbackComponent?: JSX.Element;
+  /**
+   * Optional `useQuery` params
+   */
+  queryOptions?: Omit<UseQueryOptions<string>, "queryFn" | "queryKey">;
+}
+
+/**
+ * This component fetches then shows the name of a token. For ERC20 tokens, it calls the `name` function in the ERC20 contract.
+ * It inherits all the attributes of a HTML <span> component, hence you can style it just like how you would style a normal <span>
+ *
+ *
+ * @example
+ * ### Basic usage
+ * ```tsx
+ * import { TokenProvider, TokenName } from "thirdweb/react";
+ * import { ethereum } from "thirdweb/chains";
+ *
+ * <TokenProvider {...props}>
+ *   <TokenName  />
+ * </TokenProvider>
+ * ```
+ * Result:
+ * ```html
+ * <span>Ether</span>
+ * ```
+ *
+ * ### Custom name resolver
+ * By default TokenName will call the `name` method of the token contract.
+ * However if you have a different way to fetch the name, you can pass the function to the `nameResolver` prop.
+ * Note: nameResolver should either be a string or a function (async) that returns a string.
+ * ```tsx
+ * async function fetchNameMethod() {
+ *   // your own fetching logic
+ *   return "the token name";
+ * }
+ *
+ * <TokenName nameResolver={fetchNameMethod} />
+ * ```
+ *
+ * Alternatively you can also pass in a string directly:
+ * ```tsx
+ * <TokenName nameResolver="USD Coin Circle" />
+ * ```
+ *
+ *
+ * ### Format the name (capitalize, truncate, etc.)
+ * The TokenName component accepts a `formatFn` which takes in a string and outputs a string
+ * The function is used to modify the name of the token
+ *
+ * ```tsx
+ * const concatStr = (str: string):string => str + "Token"
+ *
+ * <TokenName formatFn={concatStr} />
+ * ```
+ *
+ * Result:
+ * ```html
+ * <span>Ether Token</span>
+ * ```
+ *
+ * ### Show a loading sign when the name is being fetched
+ * ```tsx
+ * import { TokenProvider, TokenName } from "thirdweb/react";
+ *
+ * <TokenProvider address="0x...">
+ *   <TokenName loadingComponent={<Spinner />} />
+ * </TokenProvider>
+ * ```
+ *
+ * ### Fallback to something when the name fails to resolve
+ * ```tsx
+ * <TokenProvider address="0x...">
+ *   <TokenName fallbackComponent={"Failed to load"} />
+ * </TokenProvider>
+ * ```
+ *
+ * ### Custom query options for useQuery
+ * This component uses `@tanstack-query`'s useQuery internally.
+ * You can use the `queryOptions` prop for more fine-grained control
+ * ```tsx
+ * <TokenName
+ *   queryOptions={{
+ *     enabled: isEnabled,
+ *     retry: 4,
+ *   }}
+ * />
+ * ```
+ *
+ * @component
+ * @token
+ * @beta
+ */
+export function TokenName({
+  nameResolver,
+  formatFn,
+  loadingComponent,
+  fallbackComponent,
+  queryOptions,
+  ...restProps
+}: TokenNameProps) {
+  const { address, client, chain } = useTokenContext();
+  const nameQuery = useQuery({
+    queryKey: ["_internal_token_name_", chain.id, address] as const,
+    queryFn: async () => {
+      if (typeof nameResolver === "string") {
+        return nameResolver;
+      }
+      if (typeof nameResolver === "function") {
+        return nameResolver();
+      }
+      if (address.toLowerCase() === NATIVE_TOKEN_ADDRESS.toLowerCase()) {
+        // Don't wanna use `getChainNativeCurrencyName` because it has some side effect (it catches error and defaults to "ETH")
+        return getChainMetadata(chain).then((data) => data.nativeCurrency.name);
+      }
+      // Try to fetch the name from both the `name()` function and the contract metadata
+      // then prioritize the `name()`
+      const contract = getContract({ address, client, chain });
+      const [_name, contractMetadata] = await Promise.all([
+        name({ contract }),
+        getContractMetadata({ contract }),
+      ]);
+      if (!_name && !contractMetadata.name) {
+        throw new Error(
+          "Failed to resolve name from both name() and contract metadata",
+        );
+      }
+
+      return _name || contractMetadata.name;
+    },
+    ...queryOptions,
+  });
+
+  if (nameQuery.isLoading) {
+    return loadingComponent || null;
+  }
+
+  if (!nameQuery.data) {
+    return fallbackComponent || null;
+  }
+
+  const displayValue = formatFn ? formatFn(nameQuery.data) : nameQuery.data;
+
+  return <span {...restProps}>{displayValue}</span>;
+}

package/src/react/web/ui/prebuilt/Token/provider.tsx

@@ -0,0 +1,86 @@
+"use client";
+
+import type { Address } from "abitype";
+import type React from "react";
+import { createContext, useContext } from "react";
+import type { Chain } from "../../../../../chains/types.js";
+import type { ThirdwebClient } from "../../../../../client/client.js";
+
+/**
+ * Props for the <TokenProvider /> component
+ * @component
+ * @token
+ */
+export type TokenProviderProps = {
+  /**
+   * The token (ERC20) contract address
+   */
+  address: Address;
+  /**
+   * thirdweb Client
+   */
+  client: ThirdwebClient;
+  /**
+   * The chain (network) that the token is on
+   */
+  chain: Chain;
+};
+
+const TokenProviderContext = /* @__PURE__ */ createContext<
+  TokenProviderProps | undefined
+>(undefined);
+
+/**
+ * A React context provider component that supplies Token-related data to its child components.
+ *
+ * This component serves as a wrapper around the `TokenProviderContext.Provider` and passes
+ * the provided token data down to all of its child components through the context API.
+ *
+ * @example
+ * ### Basic usage
+ * ```tsx
+ * import { TokenProvider, TokenIcon, TokenName  } from "thirdweb/react";
+ * import { ethereum } from "thirdweb/chains";
+ *
+ * <TokenProvider address="0x..." client={...} chain={ethereum}>
+ *   <TokenIcon />
+ *   <TokenName />
+ * </TokenProvider>
+ * ```
+ *
+ * ### This component also works with native token!
+ * ```tsx
+ * import { NATIVE_TOKEN_ADDRESS} from "thirdweb";
+ * import { ethereum } from "thirdweb/chains";
+ *
+ * <TokenProvider address={NATIVE_TOKEN_ADDRESS} chain={ethereum} client={client}>
+ *   <TokenSymbol /> // "ETH"
+ * </TokenProvider>
+ * ```
+ *
+ * @component
+ * @token
+ * @beta
+ */
+export function TokenProvider(
+  props: React.PropsWithChildren<TokenProviderProps>,
+) {
+  return (
+    <TokenProviderContext.Provider value={props}>
+      {props.children}
+    </TokenProviderContext.Provider>
+  );
+}
+
+/**
+ * @internal
+ */
+export function useTokenContext() {
+  const ctx = useContext(TokenProviderContext);
+  if (!ctx) {
+    throw new Error(
+      "TokenProviderContext not found. Make sure you are using TokenName, TokenIcon, TokenSymbol etc. inside a <TokenProvider /> component",
+    );
+  }
+  return ctx;
+}

package/src/react/web/ui/prebuilt/Token/symbol.tsx

@@ -0,0 +1,201 @@
+"use client";
+
+import { type UseQueryOptions, useQuery } from "@tanstack/react-query";
+import type React from "react";
+import type { JSX } from "react";
+import { getChainMetadata } from "../../../../../chains/utils.js";
+import { NATIVE_TOKEN_ADDRESS } from "../../../../../constants/addresses.js";
+import { getContract } from "../../../../../contract/contract.js";
+import { getContractMetadata } from "../../../../../extensions/common/read/getContractMetadata.js";
+import { symbol } from "../../../../../extensions/common/read/symbol.js";
+import { useTokenContext } from "./provider.js";
+
+/**
+ * Props for the TokenSymbol component
+ * @component
+ * @token
+ */
+export interface TokenSymbolProps
+  extends Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> {
+  /**
+   * This prop can be a string or a (async) function that resolves to a string, representing the symbol of the token
+   * This is particularly useful if you already have a way to fetch the token symbol.
+   */
+  symbolResolver?: string | (() => string) | (() => Promise<string>);
+  /**
+   * A function to format the symbol's value
+   * Particularly useful to avoid overflowing-UI issues
+   *
+   * ```tsx
+   * <TokenSymbol formatFn={(str: string) => doSomething()} />
+   * ```
+   */
+  formatFn?: (str: string) => string;
+  /**
+   * This component will be shown while the symbol of the token is being fetched
+   * If not passed, the component will return `null`.
+   *
+   * You can/should pass a loading sign or spinner to this prop.
+   * @example
+   * ```tsx
+   * <TokenSymbol loadingComponent={<Spinner />} />
+   * ```
+   */
+  loadingComponent?: JSX.Element;
+  /**
+   * This component will be shown if the symbol fails to be retreived
+   * If not passed, the component will return `null`.
+   *
+   * You can/should pass a descriptive text/component to this prop, indicating that the
+   * symbol was not fetched succesfully
+   * @example
+   * ```tsx
+   * <TokenSymbol fallbackComponent={"Failed to load"}
+   * />
+   * ```
+   */
+  fallbackComponent?: JSX.Element;
+  /**
+   * Optional `useQuery` params
+   */
+  queryOptions?: Omit<UseQueryOptions<string>, "queryFn" | "queryKey">;
+}
+
+/**
+ * This component fetches then shows the symbol of a token. For ERC20 tokens, it calls the `symbol` function in the ERC20 contract.
+ * It inherits all the attributes of a HTML <span> component, hence you can style it just like how you would style a normal <span>
+ *
+ *
+ * @example
+ * ### Basic usage
+ * ```tsx
+ * import { TokenProvider, TokenSymbol } from "thirdweb/react";
+ * import { ethereum } from "thirdweb/chains";
+ *
+ * <TokenProvider {...props}>
+ *   <TokenSymbol  />
+ * </TokenProvider>
+ * ```
+ * Result:
+ * ```html
+ * <span>ETH</span>
+ * ```
+ *
+ * ### Custom symbol resolver
+ * By default, TokenSymbol calls the `symbol` function of your contract,
+ * however, if your token as an unconventional way to fetch the symbol, you can pass the custom logic to the `symbolResolver` prop.
+ * It can either be a string or a function (async) that returns or resolves to a string.
+ * ```tsx
+ * async function getSymbol() {
+ *   // your own fetching logic
+ *   return "the symbol";
+ * }
+ *
+ * <TokenSymbol symbolResolver={getSymbol} />
+ * ```
+ * Alternatively, you can pass in a string directly:
+ * ```tsx
+ * <TokenSymbol symbolResolver="USDC.e" />
+ * ```
+ *
+ * ### Format the symbol (capitalize, truncate, etc.)
+ * The TokenSymbol component accepts a `formatFn` which takes in a string and outputs a string
+ * The function is used to modify the symbol of the token
+ *
+ * ```tsx
+ * const concatStr = (str: string):string => str + "Token"
+ *
+ * <TokenSymbol formatFn={concatStr} />
+ * ```
+ *
+ * Result:
+ * ```html
+ * <span>Ether Token</span>
+ * ```
+ *
+ * ### Show a loading sign when the symbol is being fetched
+ * ```tsx
+ * import { TokenProvider, TokenSymbol } from "thirdweb/react";
+ *
+ * <TokenProvider address="0x...">
+ *   <TokenSymbol loadingComponent={<Spinner />} />
+ * </TokenProvider>
+ * ```
+ *
+ * ### Fallback to something when the symbol fails to resolve
+ * ```tsx
+ * <TokenProvider address="0x...">
+ *   <TokenSymbol fallbackComponent={"Failed to load"} />
+ * </TokenProvider>
+ * ```
+ *
+ * ### Custom query options for useQuery
+ * This component uses `@tanstack-query`'s useQuery internally.
+ * You can use the `queryOptions` prop for more fine-grained control
+ * ```tsx
+ * <TokenSymbol queryOptions={{
+ *     enabled: isEnabled,
+ *     retry: 4,
+ *   }}
+ * />
+ * ```
+ *
+ * @component
+ * @token
+ * @beta
+ */
+export function TokenSymbol({
+  symbolResolver,
+  formatFn,
+  loadingComponent,
+  fallbackComponent,
+  queryOptions,
+  ...restProps
+}: TokenSymbolProps) {
+  const { address, client, chain } = useTokenContext();
+  const symbolQuery = useQuery({
+    queryKey: ["_internal_token_symbol_", chain.id, address] as const,
+    queryFn: async () => {
+      if (typeof symbolResolver === "string") {
+        return symbolResolver;
+      }
+      if (typeof symbolResolver === "function") {
+        return symbolResolver();
+      }
+      if (address.toLowerCase() === NATIVE_TOKEN_ADDRESS.toLowerCase()) {
+        // Don't wanna use `getChainSymbol` because it has some side effect (it catches error and defaults to "ETH")
+        return getChainMetadata(chain).then(
+          (data) => data.nativeCurrency.symbol,
+        );
+      }
+
+      // Try to fetch the symbol from both the `symbol` function and the contract metadata
+      // then prioritize the `symbol()`
+      const contract = getContract({ address, client, chain });
+      const [_symbol, contractMetadata] = await Promise.all([
+        symbol({ contract }),
+        getContractMetadata({ contract }),
+      ]);
+      if (!_symbol && !contractMetadata.symbol) {
+        throw new Error(
+          "Failed to resolve symbol from both symbol() and contract metadata",
+        );
+      }
+
+      return _symbol || contractMetadata.symbol;
+    },
+    ...queryOptions,
+  });
+
+  if (symbolQuery.isLoading) {
+    return loadingComponent || null;
+  }
+
+  if (!symbolQuery.data) {
+    return fallbackComponent || null;
+  }
+
+  const displayValue = formatFn ? formatFn(symbolQuery.data) : symbolQuery.data;
+
+  return <span {...restProps}>{displayValue}</span>;
+}

package/src/react/web/ui/prebuilt/thirdweb/BuyDirectListingButton/index.tsx

@@ -79,6 +79,7 @@ export type BuyDirectListingButtonProps = Omit<
  * For error handling & callbacks on transaction-sent and transaction-confirmed,
  * please refer to the TransactionButton docs.
  * @component
+ * @transaction
  */
 export function BuyDirectListingButton(props: BuyDirectListingButtonProps) {
   const {

package/src/react/web/ui/prebuilt/thirdweb/ClaimButton/index.tsx

@@ -106,6 +106,7 @@ import type {
  *
  * For error handling & callbacks on transaction-sent and transaction-confirmed,
  * please refer to the TransactionButton docs.
+ * @transaction
  */
 export function ClaimButton(props: ClaimButtonProps) {
   const { children, contractAddress, client, chain, claimParams, payModal } =

package/src/react/web/ui/prebuilt/thirdweb/CreateDirectListingButton/index.tsx

@@ -55,6 +55,7 @@ export type CreateDirectListingButtonProps = Omit<
  * For error handling & callbacks on transaction-sent and transaction-confirmed,
  * please refer to the TransactionButton docs.
  * @component
+ * @transaction
  */
 export function CreateDirectListingButton(
   props: CreateDirectListingButtonProps,

package/src/storage/unpin.ts

@@ -9,7 +9,7 @@ export type UnpinOptions = {
 
 /**
  * Unpins a file from IPFS.
- * @note For security purposes, this method requires a secret key to be set in the ThirdwebClient instance.
+ *  For security purposes, this method requires a secret key to be set in the ThirdwebClient instance.
  * @param options - The options for unpinning the file.
  * @param options.client - The Thirdweb client instance.
  * @param options.cid - The content identifier (CID) of the file to unpin.

package/src/storage/upload.ts

@@ -49,6 +49,7 @@ type UploadReturnType<TFiles extends UploadableFile[]> = TFiles extends {
  *    },
  *  ],
  * });
+ * ```
  *
  * ### Uploading files
  *

package/src/transaction/actions/to-serializable-transaction.ts

@@ -25,7 +25,7 @@ export type ToSerializableTransactionOptions = {
  * @param options - The transaction and additional options for conversion
  * @returns A serializable transaction for inspection or submission to an account.
  *
- * @note For easier transaction sending, {@see sendTransaction}
+ *  For easier transaction sending, {@see sendTransaction}
  * @example
  * ```ts
  * import { prepareTransaction, toSerializableTransaction } from "thirdweb";

package/src/transaction/actions/zksync/send-eip712-transaction.ts

@@ -84,6 +84,11 @@ export async function signEip712Transaction(options: {
   });
 }
 
+/**
+ * Populate a prepared transaction to be serialized as a EIP712 transaction
+ * @param options
+ * @internal
+ */
 export async function populateEip712Transaction(
   options: SendEip712TransactionOptions,
 ): Promise<EIP721TransactionSerializable> {

package/src/utils/any-evm/zksync/isZkSyncChain.ts

@@ -1,5 +1,10 @@
 import type { Chain } from "../../../chains/types.js";
 
+/**
+ * Checks whether the given chain is part of the zksync stack
+ * @param chain
+ * @chain
+ */
 export async function isZkSyncChain(chain: Chain) {
   if (chain.id === 1337 || chain.id === 31337) {
     return false;

package/src/utils/config.ts

@@ -8,6 +8,9 @@ let transactionDecorator:
     }) => Promise<{ account: Account; transaction: PreparedTransaction }>)
   | null = null;
 
+/**
+ * @internal
+ */
 export function setTransactionDecorator(
   decoratorFunction: (args: {
     account: Account;
@@ -17,10 +20,16 @@ export function setTransactionDecorator(
   transactionDecorator = decoratorFunction;
 }
 
+/**
+ * @internal
+ */
 export function clearTransactionDecorator() {
   transactionDecorator = null;
 }
 
+/**
+ * @internal
+ */
 export function getTransactionDecorator() {
   return transactionDecorator;
 }

package/src/utils/json.ts

@@ -14,7 +14,13 @@
  * ```
  * @utils
  */
-export const stringify: typeof JSON.stringify = (value, replacer, space) => {
+export function stringify(
+  // biome-ignore lint/suspicious/noExplicitAny: JSON.stringify signature
+  value: any,
+  // biome-ignore lint/suspicious/noExplicitAny: JSON.stringify signature
+  replacer?: ((this: any, key: string, value: any) => any) | null,
+  space?: string | number,
+) {
   const res = JSON.stringify(
     value,
     (key, value_) => {
@@ -24,4 +30,4 @@ export const stringify: typeof JSON.stringify = (value, replacer, space) => {
     space,
   );
   return res;
-};
+}

package/src/version.ts

@@ -1 +1 @@
-export const version = "5.69.0";
+export const version = "5.70.0-nightly-ecaa304a812188da3c81888bb52ca6064093c139-20241121000332";

package/src/wallets/eip5792/get-calls-status.ts

@@ -16,7 +16,7 @@ export type GetCallsStatusOptions = {
 /**
  * Get the status of an [EIP-5792](https://eips.ethereum.org/EIPS/eip-5792) bundle.
  *
- * @note This function is dependent on the wallet's support for EIP-5792 and could fail.
+ *  This function is dependent on the wallet's support for EIP-5792 and could fail.
  *
  * @param {GetCallsStatusOptions} options
  * @param {Wallet} options.wallet - The wallet that send the original calls.

package/src/wallets/eip5792/get-capabilities.ts

@@ -19,7 +19,7 @@ export type GetCapabilitiesResult = Prettify<
 /**
  * Get the capabilities of a wallet based on the [EIP-5792](https://eips.ethereum.org/EIPS/eip-5792) specification.
  *
- * @note This function is dependent on the wallet's support for EIP-5792, but will not throw.
+ *  This function is dependent on the wallet's support for EIP-5792, but will not throw.
  * **The returned object contains a `message` field detailing any issues with the wallet's support for EIP-5792.**
  *
  * @param {GetCapabilitiesOptions} options

package/src/wallets/eip5792/send-calls.ts

@@ -59,7 +59,7 @@ export type SendCallsResult = WalletSendCallsId;
  * This function works with all Thirdweb wallets (in-app and smart) and certain injected wallets that already support EIP-5792.
  * Transactions will be bundled and sponsored when those capabilities are supported, otherwise they will be sent as individual transactions.
  *
- * @note This function is dependent on the wallet's support for EIP-5792 and could fail.
+ *  This function is dependent on the wallet's support for EIP-5792 and could fail.
  *
  * @param {SendCallsOptions} options
  * @param {Wallet} options.wallet - The wallet to send the calls to.
@@ -109,7 +109,7 @@ export type SendCallsResult = WalletSendCallsId;
  *     }
  *   }
  * });
- * @note We recommend proxying any paymaster calls via an API route you setup and control.
+ *  We recommend proxying any paymaster calls via an API route you setup and control.
  * ```
  * @extension EIP5792
  */

package/src/wallets/eip5792/wait-for-bundle.ts

@@ -21,7 +21,7 @@ export type WaitForBundleOptions = Prettify<{
 /**
  * Waits for the [EIP-5792](https://eips.ethereum.org/EIPS/eip-5792) bundle to be confirmed.
  *
- * @note This function is dependent on the wallet's support for EIP-5792 and could fail.
+ *  This function is dependent on the wallet's support for EIP-5792 and could fail.
  *
  * @param options - The options for waiting for the bundle.
  * By default, the max wait time is 100 blocks.

package/src/wallets/in-app/core/users/getUser.ts

@@ -16,7 +16,7 @@ export type GetUserResult = {
 
 /**
  * Gets user based on the provided query parameters.
- * @note This function is only available on the server (a secret key is required in the client).
+ *  This function is only available on the server (a secret key is required in the client).
  *
  * @param options - The options for the get user function.
  * @param options.client - The Thirdweb client with a secret key included.