@0xsequence/marketplace-sdk 1.2.0 → 2.0.0

package/src/react/hooks/utils/useAutoSelectFeeOption.tsx

@@ -1,11 +1,12 @@
 'use client';
 
+import type { Address, Indexer } from '@0xsequence/api-client';
 import { useChain } from '@0xsequence/connect';
 import { useCallback, useEffect } from 'react';
-import { type Address, zeroAddress } from 'viem';
+import { zeroAddress } from 'viem';
 import { useAccount } from 'wagmi';
 import type { FeeOption } from '../../../types/waas-types';
-import { useCollectionBalanceDetails } from '../data/collections/useCollectionBalanceDetails';
+import { useCollectionBalanceDetails } from '../collection/balance-details';
 
 enum AutoSelectFeeOptionError {
 	UserNotConnected = 'User not connected',
@@ -87,18 +88,33 @@ type UseAutoSelectFeeOptionArgs = {
  * }
  * ```
  */
+/**
+ * Normalizes WaaS fee option token address to viem Address type
+ * - null represents native token (converted to zeroAddress)
+ * - string addresses from WaaS are validated and guaranteed to be hex addresses
+ */
+function normalizeWaasFeeTokenAddress(contractAddress: string | null): Address {
+	if (contractAddress === null) {
+		return zeroAddress;
+	}
+	// WaaS returns validated hex addresses, but TypeScript doesn't know they're `0x${string}`
+	// We validate to be safe and satisfy the type system
+	if (!contractAddress.startsWith('0x')) {
+		throw new Error(`Invalid address from WaaS: ${contractAddress}`);
+	}
+	return contractAddress as Address;
+}
+
 export function useAutoSelectFeeOption({
 	pendingFeeOptionConfirmation,
 	enabled,
 }: UseAutoSelectFeeOptionArgs) {
 	const { address: userAddress } = useAccount();
 
-	// one token that has null contract address is native token, so we need to replace it with zero address
+	const isEnabled = enabled ?? true;
+
 	const contractWhitelist = pendingFeeOptionConfirmation.options?.map(
-		(option) =>
-			option.token.contractAddress === null
-				? zeroAddress
-				: (option.token.contractAddress as Address),
+		(option) => normalizeWaasFeeTokenAddress(option.token.contractAddress),
 	);
 
 	const {
@@ -114,20 +130,20 @@ export function useAutoSelectFeeOption({
 		},
 		query: {
 			enabled:
-				!!pendingFeeOptionConfirmation.options && !!userAddress && enabled,
+				!!pendingFeeOptionConfirmation.options && !!userAddress && isEnabled,
 		},
 	});
 	const chain = useChain(pendingFeeOptionConfirmation.chainId);
 
 	// combine native balance and erc20 balances
 	const combinedBalances = balanceDetails && [
-		...balanceDetails.nativeBalances.map((b) => ({
+		...balanceDetails.nativeBalances.map((b: Indexer.NativeTokenBalance) => ({
 			chainId: pendingFeeOptionConfirmation.chainId,
 			balance: b.balance,
 			symbol: chain?.nativeCurrency.symbol,
 			contractAddress: zeroAddress,
 		})),
-		...balanceDetails.balances.map((b) => ({
+		...balanceDetails.balances.map((b: Indexer.TokenBalance) => ({
 			chainId: b.chainId,
 			balance: b.balance,
 			symbol: b.contractInfo?.symbol,
@@ -141,6 +157,7 @@ export function useAutoSelectFeeOption({
 		}
 	}, [combinedBalances]);
 
+	// eslint-disable-next-line @typescript-eslint/require-await -- Async for interface consistency
 	const autoSelectedOption = useCallback(async () => {
 		if (!userAddress) {
 			return {
@@ -169,13 +186,13 @@ export function useAutoSelectFeeOption({
 
 		const selectedOption = pendingFeeOptionConfirmation.options.find(
 			(option) => {
+				const normalizedAddress = normalizeWaasFeeTokenAddress(
+					option.token.contractAddress,
+				);
 				const tokenBalance = combinedBalances.find(
-					(balance) =>
+					(balance: { contractAddress: Address }) =>
 						balance.contractAddress.toLowerCase() ===
-						(option.token.contractAddress === null
-							? zeroAddress
-							: option.token.contractAddress
-						).toLowerCase(),
+						normalizedAddress.toLowerCase(),
 				);
 
 				if (!tokenBalance) return false;
@@ -191,8 +208,6 @@ export function useAutoSelectFeeOption({
 			};
 		}
 
-		console.debug('auto selected option', selectedOption);
-
 		return { selectedOption, error: null };
 	}, [
 		userAddress,
@@ -200,6 +215,7 @@ export function useAutoSelectFeeOption({
 		isBalanceDetailsLoading,
 		isBalanceDetailsError,
 		combinedBalances,
+		isEnabled,
 	]);
 
 	return autoSelectedOption();

package/src/react/hooks/utils/useRoyalty.test.tsx

@@ -9,7 +9,7 @@ describe('useRoyaltyPercentage', () => {
 		const { result } = renderHook(() => useRoyalty(TEST_COLLECTIBLE));
 
 		expect(result.current.isLoading).toBe(true);
-		expect(result.current.data).toBeNull();
+		expect(result.current.data).toBeUndefined();
 
 		await waitFor(
 			() => {

package/src/react/hooks/utils/useRoyalty.tsx

@@ -1,30 +1,105 @@
 'use client';
 
-import type { Address } from 'viem';
-import { useReadContract } from 'wagmi';
+import type { Address } from '@0xsequence/api-client';
+import { queryOptions, useQuery } from '@tanstack/react-query';
+import type { PublicClient } from 'viem';
+import { readContract } from 'viem/actions';
+import { usePublicClient } from 'wagmi';
 import { EIP2981_ABI } from '../../../utils';
 import type { QueryArg } from '../../_internal';
-import { collectableKeys } from '../../_internal';
+
+export interface RoyaltyInfo {
+	percentage: bigint;
+	recipient: Address;
+}
+
+export interface FetchRoyaltyParams {
+	chainId: number;
+	collectionAddress: Address;
+	tokenId: bigint;
+	publicClient: PublicClient | undefined;
+}
 
 export interface UseRoyaltyArgs {
 	chainId: number;
 	collectionAddress: Address;
-	collectibleId: string;
+	tokenId: bigint;
 	query?: QueryArg;
 }
 
+/**
+ * Fetches royalty information for a collectible using EIP-2981 standard
+ */
+async function fetchRoyalty(
+	params: FetchRoyaltyParams,
+): Promise<RoyaltyInfo | null> {
+	const { collectionAddress, tokenId, publicClient } = params;
+
+	if (!publicClient) {
+		throw new Error('Public client is required');
+	}
+
+	const result = await readContract(publicClient, {
+		abi: EIP2981_ABI,
+		address: collectionAddress,
+		functionName: 'royaltyInfo',
+		args: [BigInt(tokenId), BigInt(100)],
+	});
+
+	const [recipient, percentage] = result;
+
+	if (recipient && percentage) {
+		return {
+			percentage,
+			recipient,
+		};
+	}
+
+	return null;
+}
+
+function getRoyaltyQueryKey(params: Omit<FetchRoyaltyParams, 'publicClient'>) {
+	const apiArgs = {
+		chainId: String(params.chainId),
+		contractAddress: params.collectionAddress,
+		tokenId: params.tokenId,
+	};
+
+	return ['royalty-percentage', apiArgs] as const;
+}
+
+function royaltyQueryOptions(
+	params: FetchRoyaltyParams,
+	query?: UseRoyaltyArgs['query'],
+) {
+	const enabled = Boolean(
+		params.collectionAddress &&
+			params.chainId &&
+			params.tokenId &&
+			params.publicClient &&
+			(query?.enabled ?? true),
+	);
+
+	return queryOptions({
+		queryKey: getRoyaltyQueryKey(params),
+		queryFn: () => fetchRoyalty(params),
+		enabled,
+		...query,
+	});
+}
+
 /**
  * Hook to fetch royalty information for a collectible
  *
  * Reads royalty information from the blockchain using the EIP-2981 standard.
- * This hook queries the contract directly to get royalty percentage and recipient
- * address for a specific token.
+ * This hook uses TanStack Query to manage the blockchain call and caching,
+ * similar to other data fetching hooks in the SDK.
  *
  * @param args - Configuration parameters
  * @param args.chainId - The chain ID (must be number, e.g., 1 for Ethereum, 137 for Polygon)
  * @param args.collectionAddress - The collection contract address
- * @param args.collectibleId - The token ID within the collection
- * @param args.query - Optional React Query configuration
+ * @param args.tokenId - The token ID within the collection
+ * @param args.query - Optional TanStack Query configuration
  *
  * @returns Query result containing royalty information (percentage and recipient) or null
  *
@@ -34,7 +109,7 @@ export interface UseRoyaltyArgs {
  * const { data, isLoading } = useRoyalty({
  *   chainId: 137,
  *   collectionAddress: '0x...',
- *   collectibleId: '1'
+ *   tokenId: '1'
  * })
  *
  * if (data) {
@@ -48,7 +123,7 @@ export interface UseRoyaltyArgs {
  * const { data, isLoading } = useRoyalty({
  *   chainId: 1,
  *   collectionAddress: '0x...',
- *   collectibleId: '42',
+ *   tokenId: '42',
  *   query: {
  *     refetchInterval: 60000,
  *     enabled: hasTokenId
@@ -57,30 +132,20 @@ export interface UseRoyaltyArgs {
  * ```
  */
 export function useRoyalty(args: UseRoyaltyArgs) {
-	const { chainId, collectionAddress, collectibleId, query } = args;
-	const scopeKey = `${collectableKeys.royaltyPercentage.join('.')}-${chainId}-${collectionAddress}-${collectibleId}`;
+	const { chainId, collectionAddress, tokenId, query } = args;
+	const publicClient = usePublicClient({ chainId });
 
-	const contractResult = useReadContract({
-		scopeKey: scopeKey,
-		abi: EIP2981_ABI,
-		address: collectionAddress,
-		functionName: 'royaltyInfo',
-		args: [BigInt(collectibleId), BigInt(100)],
-		chainId,
-		query: query,
-	});
+	const queryOptions = royaltyQueryOptions(
+		{
+			chainId,
+			collectionAddress,
+			tokenId,
+			publicClient,
+		},
+		query,
+	);
 
-	const [recipient, percentage] = contractResult.data ?? [];
-	const formattedData =
-		recipient && percentage
-			? {
-					percentage,
-					recipient: recipient as Address,
-				}
-			: null;
-
-	return {
-		...contractResult,
-		data: formattedData,
-	};
+	return useQuery(queryOptions);
 }
+
+export { royaltyQueryOptions };

package/src/react/hooks/utils/useWaasFeeOptions.tsx

@@ -0,0 +1,234 @@
+'use client';
+
+import { ContractVerificationStatus } from '@0xsequence/indexer';
+import type { FeeOption } from '@0xsequence/waas';
+import { useEffect } from 'react';
+import { formatUnits } from 'viem';
+import type { Connection, Connector } from 'wagmi';
+import { useConnections } from 'wagmi';
+import type { SdkConfig } from '../../../types';
+import { getIndexerClient } from '../../_internal';
+import {
+	Deferred,
+	type FeeOptionConfirmationResult,
+	type FeeOptionExtended,
+	usePendingConfirmation,
+	type WaasFeeOptionConfirmation,
+	waasFeeOptionsStore,
+} from './waasFeeOptionsStore';
+
+// Re-export types for backward compatibility
+export type { FeeOptionExtended, WaasFeeOptionConfirmation };
+
+/**
+ * Return type for the useWaasFeeOptions hook
+ */
+export type UseWaasFeeOptionsReturnType = {
+	pendingFeeOptionConfirmation: WaasFeeOptionConfirmation | undefined;
+	confirmPendingFeeOption: (id: string, feeTokenAddress: string | null) => void;
+	rejectPendingFeeOption: (id: string) => void;
+};
+
+/**
+ * Options for the useWaasFeeOptions hook
+ *
+ * @property {boolean} skipFeeBalanceCheck - Whether to skip checking token balances (default: false)
+ */
+export interface WaasFeeOptionsConfig {
+	/** Whether to skip checking token balances (default: false) */
+	skipFeeBalanceCheck?: boolean;
+}
+
+/**
+ * Hook for handling WaaS (Wallet as a Service) fee options for unsponsored transactions
+ *
+ * This hook provides functionality to:
+ * - Get available fee options for a transaction in Native Token and ERC20's
+ * - Provide user wallet balances for each fee option
+ * - Confirm or reject fee selections
+ *
+ * @param options - Configuration options for the hook {@link WaasFeeOptionsConfig}
+ * @returns Array containing the confirmation state and control functions {@link UseWaasFeeOptionsReturnType}
+ *
+ * @example
+ * ```tsx
+ *   // Use the hook with default balance checking, this will fetch the user's wallet balances for each fee option and provide them in the UseWaasFeeOptionsReturn
+ *   const [
+ *     pendingFeeOptionConfirmation,
+ *     confirmPendingFeeOption,
+ *     rejectPendingFeeOption
+ *   ] = useWaasFeeOptions();
+ *
+ *   // Or skip balance checking if needed
+ *   // const [pendingFeeOptionConfirmation, confirmPendingFeeOption, rejectPendingFeeOption] =
+ *   //   useWaasFeeOptions({ skipFeeBalanceCheck: true });
+ *
+ *   const [selectedFeeOptionTokenName, setSelectedFeeOptionTokenName] = useState<string>();
+ *   const [feeOptionAlert, setFeeOptionAlert] = useState<AlertProps>();
+ *
+ *   // Initialize with first option when fee options become available
+ *   useEffect(() => {
+ *     if (pendingFeeOptionConfirmation) {
+ *       console.log('Pending fee options: ', pendingFeeOptionConfirmation.options)
+ *     }
+ *   }, [pendingFeeOptionConfirmation]);
+ *
+ * ```
+ */
+export function useWaasFeeOptions(
+	chainId: number,
+	config: SdkConfig,
+	options?: WaasFeeOptionsConfig,
+): UseWaasFeeOptionsReturnType {
+	const { skipFeeBalanceCheck = false } = options || {};
+	const connections = useConnections();
+	const waasConnector: Connector | undefined = connections.find(
+		(c: Connection) => c.connector.id.includes('waas'),
+	)?.connector;
+	const pendingFeeOptionConfirmation = usePendingConfirmation();
+
+	const isValidChainId = chainId > 0;
+	const indexerClient = isValidChainId
+		? getIndexerClient(chainId, config)
+		: null;
+	/**
+	 * Confirms the selected fee option
+	 * @param id - The fee confirmation ID
+	 * @param feeTokenAddress - The address of the token to use for fee payment (null for native token)
+	 */
+	function confirmPendingFeeOption(id: string, feeTokenAddress: string | null) {
+		waasFeeOptionsStore.send({
+			type: 'confirmFeeOption',
+			id,
+			feeTokenAddress,
+		});
+	}
+
+	/**
+	 * Rejects the current fee option confirmation
+	 * @param id - The fee confirmation ID to reject
+	 */
+	function rejectPendingFeeOption(id: string) {
+		waasFeeOptionsStore.send({
+			type: 'rejectFeeOption',
+			id,
+		});
+	}
+
+	useEffect(() => {
+		if (!waasConnector || !indexerClient) {
+			return;
+		}
+
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any -- sequenceWaasProvider is not typed on Connector
+		const waasProvider = (waasConnector as any).sequenceWaasProvider;
+		if (!waasProvider) {
+			return;
+		}
+
+		const originalHandler = waasProvider.feeConfirmationHandler;
+
+		waasProvider.feeConfirmationHandler = {
+			async confirmFeeOption(
+				id: string,
+				options: FeeOption[],
+				chainId: number,
+			): Promise<FeeOptionConfirmationResult> {
+				const pending = new Deferred<FeeOptionConfirmationResult>();
+
+				// Set the deferred in the store
+				waasFeeOptionsStore.send({
+					type: 'setDeferred',
+					deferred: pending,
+				});
+
+				// Clear any previous stale state immediately
+				waasFeeOptionsStore.send({
+					type: 'setPendingConfirmation',
+					confirmation: undefined,
+				});
+
+				const accountAddress = connections[0]?.accounts[0];
+				if (!accountAddress) {
+					throw new Error('No account address available');
+				}
+
+				if (!skipFeeBalanceCheck) {
+					const optionsWithBalances = await Promise.all(
+						options.map(async (option) => {
+							if (option.token.contractAddress) {
+								const tokenBalances =
+									await indexerClient.getTokenBalancesByContract({
+										filter: {
+											accountAddresses: [accountAddress],
+											contractStatus: ContractVerificationStatus.ALL,
+											contractAddresses: [option.token.contractAddress],
+										},
+										omitMetadata: true,
+									});
+								const tokenBalance = tokenBalances.balances[0]?.balance;
+								return {
+									...option,
+									balanceFormatted: option.token.decimals
+										? formatUnits(
+												BigInt(tokenBalances.balances[0]?.balance ?? '0'),
+												option.token.decimals,
+											)
+										: (tokenBalances.balances[0]?.balance ?? '0'),
+									balance: tokenBalances.balances[0]?.balance ?? '0',
+									hasEnoughBalanceForFee: tokenBalance
+										? BigInt(option.value) <= BigInt(tokenBalance)
+										: false,
+								};
+							}
+							const nativeBalance = await indexerClient.getNativeTokenBalance({
+								accountAddress,
+							});
+							return {
+								...option,
+								balanceFormatted: formatUnits(
+									BigInt(nativeBalance.balance.balance),
+									18,
+								),
+								balance: nativeBalance.balance.balance,
+								hasEnoughBalanceForFee:
+									BigInt(option.value) <= BigInt(nativeBalance.balance.balance),
+							};
+						}),
+					);
+
+					const confirmation: WaasFeeOptionConfirmation = {
+						id,
+						options: optionsWithBalances,
+						chainId,
+					};
+					waasFeeOptionsStore.send({
+						type: 'setPendingConfirmation',
+						confirmation,
+					});
+				} else {
+					const confirmation: WaasFeeOptionConfirmation = {
+						id,
+						options,
+						chainId,
+					};
+					waasFeeOptionsStore.send({
+						type: 'setPendingConfirmation',
+						confirmation,
+					});
+				}
+				return pending.promise;
+			},
+		};
+
+		return () => {
+			waasProvider.feeConfirmationHandler = originalHandler;
+		};
+	}, [waasConnector, indexerClient]);
+
+	return {
+		pendingFeeOptionConfirmation,
+		confirmPendingFeeOption,
+		rejectPendingFeeOption,
+	};
+}

package/src/react/hooks/utils/waasFeeOptionsStore.ts

@@ -0,0 +1,141 @@
+import type { FeeOption } from '@0xsequence/waas';
+import { createStore } from '@xstate/store';
+import { useSelector } from '@xstate/store/react';
+
+export class Deferred<T> {
+	private _resolve: (value: T) => void = () => {};
+	private _reject: (value: T) => void = () => {};
+
+	private _promise: Promise<T> = new Promise<T>((resolve, reject) => {
+		this._reject = reject;
+		this._resolve = resolve;
+	});
+
+	get promise(): Promise<T> {
+		return this._promise;
+	}
+
+	resolve(value: T) {
+		this._resolve(value);
+	}
+
+	reject(value: T) {
+		this._reject(value);
+	}
+}
+
+/**
+ * Extended FeeOption type that includes balance information
+ */
+export type FeeOptionExtended = FeeOption & {
+	/** Raw balance string */
+	balance: string;
+	/** Formatted balance with proper decimals */
+	balanceFormatted: string;
+	/** Indicates if the wallet has enough balance to pay the fee */
+	hasEnoughBalanceForFee: boolean;
+};
+
+/**
+ * Fee option confirmation data structure
+ */
+export type WaasFeeOptionConfirmation = {
+	/** Unique identifier for the fee confirmation */
+	id: string;
+	/** Available fee options with balance information */
+	options: FeeOptionExtended[] | FeeOption[];
+	/** Chain ID where the transaction will be executed */
+	chainId: number;
+};
+
+/**
+ * Result type for fee option confirmation
+ */
+export type FeeOptionConfirmationResult = {
+	id: string;
+	feeTokenAddress?: string | null;
+	confirmed: boolean;
+};
+
+export type WaasFeeOptionsState = {
+	pendingConfirmation: WaasFeeOptionConfirmation | undefined;
+	deferred: Deferred<FeeOptionConfirmationResult> | undefined;
+};
+
+const initialContext: WaasFeeOptionsState = {
+	pendingConfirmation: undefined,
+	deferred: undefined,
+};
+
+export const waasFeeOptionsStore = createStore({
+	context: initialContext,
+	on: {
+		setPendingConfirmation: (
+			context,
+			event: { confirmation: WaasFeeOptionConfirmation | undefined },
+		) => ({
+			...context,
+			pendingConfirmation: event.confirmation,
+		}),
+
+		setDeferred: (
+			context,
+			event: { deferred: Deferred<FeeOptionConfirmationResult> | undefined },
+		) => ({
+			...context,
+			deferred: event.deferred,
+		}),
+
+		confirmFeeOption: (
+			context,
+			event: { id: string; feeTokenAddress: string | null },
+		) => {
+			if (context.deferred && context.pendingConfirmation?.id === event.id) {
+				context.deferred.resolve({
+					id: event.id,
+					feeTokenAddress: event.feeTokenAddress,
+					confirmed: true,
+				});
+
+				return {
+					...context,
+					deferred: undefined,
+					pendingConfirmation: undefined,
+				};
+			}
+			return context;
+		},
+
+		rejectFeeOption: (context, event: { id: string }) => {
+			if (context.deferred && context.pendingConfirmation?.id === event.id) {
+				context.deferred.resolve({
+					id: event.id,
+					feeTokenAddress: undefined,
+					confirmed: false,
+				});
+
+				return {
+					...context,
+					deferred: undefined,
+					pendingConfirmation: undefined,
+				};
+			}
+			return context;
+		},
+
+		clear: () => initialContext,
+	},
+});
+
+// Selector hooks
+export const usePendingConfirmation = () =>
+	useSelector(
+		waasFeeOptionsStore,
+		(state) => state.context.pendingConfirmation,
+	);
+
+export const useDeferred = () =>
+	useSelector(waasFeeOptionsStore, (state) => state.context.deferred);
+
+export const useWaasFeeOptionsState = () =>
+	useSelector(waasFeeOptionsStore, (state) => state.context);

package/src/react/index.ts

@@ -1,3 +1,5 @@
+'use client';
+
 export * from './_internal/api/get-query-client';
 export * from './_internal/wagmi/create-config';
 export * from './hooks';
@@ -5,3 +7,4 @@ export * from './providers';
 export * from './queries';
 export * from './types/query';
 export * from './ui/index';
+export * from './utils';

package/src/react/providers/index.tsx

@@ -14,9 +14,9 @@ import { PROVIDER_ID } from '../_internal/get-provider';
 import { AnalyticsProvider } from './analytics-provider';
 import { ThemeProvider } from './theme-provider';
 
-export const MarketplaceSdkContext = createContext(
-	{} as MarketplaceSdkContextType,
-);
+export const MarketplaceSdkContext = createContext<
+	MarketplaceSdkContextType | undefined
+>(undefined);
 
 export type MarketplaceSdkProviderProps = {
 	config: SdkConfig;