@mantle-rwa/react 0.1.1 → 0.1.3

package/src/components/YieldCalculator.tsx

@@ -0,0 +1,250 @@
+'use client';
+
+/**
+ * YieldCalculator - Calculator for previewing yield distributions
+ * 
+ * Shows how yields will be allocated to token holders before creating a distribution.
+ */
+
+import { useState, useCallback, useEffect, useRef } from 'react';
+import { formatUnits } from 'viem';
+import { useRWA } from '../hooks/useRWA';
+import type { YieldCalculatorProps } from '../types';
+import type { DistributionPreview, HolderDistribution } from '@mantle-rwa/sdk';
+
+/**
+ * Format address for display
+ */
+function formatAddress(address: string): string {
+    return `${address.slice(0, 6)}...${address.slice(-4)}`;
+}
+
+/**
+ * Format token amount for display
+ */
+function formatAmount(amount: bigint, decimals: number = 18): string {
+    const formatted = formatUnits(amount, decimals);
+    const num = parseFloat(formatted);
+    return num.toLocaleString(undefined, { maximumFractionDigits: 4 });
+}
+
+/**
+ * YieldCalculator component
+ */
+export function YieldCalculator({
+    tokenAddress,
+    yieldDistributorAddress: _yieldDistributorAddress,
+    holderAddresses,
+    onCalculate,
+    onError,
+    className = '',
+}: YieldCalculatorProps): JSX.Element {
+    const { client, isInitialized } = useRWA();
+
+    const [amount, setAmount] = useState<string>('');
+    const [preview, setPreview] = useState<DistributionPreview | null>(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState<Error | null>(null);
+
+    // Debounce timer ref
+    const debounceRef = useRef<NodeJS.Timeout | null>(null);
+
+    // Calculate preview
+    const calculatePreview = useCallback(async (distributionAmount: string) => {
+        if (!client || !isInitialized || !distributionAmount || parseFloat(distributionAmount) <= 0) {
+            setPreview(null);
+            return;
+        }
+
+        setIsLoading(true);
+        setError(null);
+
+        try {
+            const result = await client.yield.previewDistribution(
+                tokenAddress,
+                distributionAmount,
+                undefined, // snapshotId
+                holderAddresses
+            );
+            setPreview(result);
+            onCalculate?.(result);
+        } catch (err) {
+            const errorObj = err instanceof Error ? err : new Error('Failed to calculate preview');
+            setError(errorObj);
+            onError?.(errorObj);
+            setPreview(null);
+        } finally {
+            setIsLoading(false);
+        }
+    }, [client, isInitialized, tokenAddress, holderAddresses, onCalculate, onError]);
+
+    // Handle amount change with debounce
+    const handleAmountChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+        const value = e.target.value;
+        setAmount(value);
+
+        // Clear previous debounce
+        if (debounceRef.current) {
+            clearTimeout(debounceRef.current);
+        }
+
+        // Debounce the calculation
+        debounceRef.current = setTimeout(() => {
+            calculatePreview(value);
+        }, 500);
+    }, [calculatePreview]);
+
+    // Cleanup debounce on unmount
+    useEffect(() => {
+        return () => {
+            if (debounceRef.current) {
+                clearTimeout(debounceRef.current);
+            }
+        };
+    }, []);
+
+    // Recalculate when holder addresses change
+    useEffect(() => {
+        if (amount && parseFloat(amount) > 0) {
+            calculatePreview(amount);
+        }
+    }, [holderAddresses]); // eslint-disable-line react-hooks/exhaustive-deps
+
+    // Handle manual calculate button
+    const handleCalculate = useCallback(() => {
+        calculatePreview(amount);
+    }, [amount, calculatePreview]);
+
+    return (
+        <div className={`rwa-yield-calculator ${className}`}>
+            <div className="space-y-6">
+                {/* Amount Input */}
+                <div>
+                    <label htmlFor="distribution-amount" className="block text-sm font-medium text-gray-700 dark:text-gray-300">
+                        Total Distribution Amount
+                    </label>
+                    <div className="mt-1 flex rounded-md shadow-sm">
+                        <input
+                            type="text"
+                            id="distribution-amount"
+                            value={amount}
+                            onChange={handleAmountChange}
+                            placeholder="Enter amount to distribute"
+                            className="flex-1 block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-l-md focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-blue-500 dark:bg-gray-800 dark:text-white"
+                        />
+                        <button
+                            type="button"
+                            onClick={handleCalculate}
+                            disabled={isLoading || !amount}
+                            className="px-4 py-2 bg-blue-600 hover:bg-blue-700 disabled:bg-gray-400 text-white rounded-r-md transition-colors"
+                        >
+                            {isLoading ? 'Calculating...' : 'Calculate'}
+                        </button>
+                    </div>
+                </div>
+
+                {/* Loading State */}
+                {isLoading && (
+                    <div className="flex items-center justify-center p-4">
+                        <div className="animate-spin rounded-full h-6 w-6 border-b-2 border-blue-600" />
+                        <span className="ml-2 text-gray-600 dark:text-gray-300">Calculating distribution...</span>
+                    </div>
+                )}
+
+                {/* Error State */}
+                {error && (
+                    <div className="p-4 bg-red-50 dark:bg-red-900/20 rounded-lg border border-red-200 dark:border-red-800">
+                        <p className="text-red-700 dark:text-red-300">{error.message}</p>
+                        <button
+                            onClick={handleCalculate}
+                            className="mt-2 text-sm text-red-600 dark:text-red-400 underline hover:no-underline"
+                        >
+                            Retry
+                        </button>
+                    </div>
+                )}
+
+                {/* Preview Results */}
+                {preview && !isLoading && (
+                    <div className="space-y-4">
+                        {/* Summary */}
+                        <div className="p-4 bg-gray-50 dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700">
+                            <h4 className="text-sm font-medium text-gray-700 dark:text-gray-300">Distribution Summary</h4>
+                            <div className="mt-2 grid grid-cols-2 gap-4">
+                                <div>
+                                    <p className="text-xs text-gray-500 dark:text-gray-400">Total Holders</p>
+                                    <p className="text-lg font-semibold text-gray-900 dark:text-white">{preview.totalHolders}</p>
+                                </div>
+                                <div>
+                                    <p className="text-xs text-gray-500 dark:text-gray-400">Total Supply</p>
+                                    <p className="text-lg font-semibold text-gray-900 dark:text-white">
+                                        {formatAmount(preview.totalSupplyAtSnapshot)}
+                                    </p>
+                                </div>
+                            </div>
+                        </div>
+
+                        {/* Holder Distributions Table */}
+                        {preview.distributions.length > 0 && (
+                            <div className="overflow-hidden rounded-lg border border-gray-200 dark:border-gray-700">
+                                <table className="min-w-full divide-y divide-gray-200 dark:divide-gray-700">
+                                    <thead className="bg-gray-50 dark:bg-gray-800">
+                                        <tr>
+                                            <th className="px-4 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
+                                                Address
+                                            </th>
+                                            <th className="px-4 py-3 text-right text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
+                                                Balance
+                                            </th>
+                                            <th className="px-4 py-3 text-right text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
+                                                Yield Amount
+                                            </th>
+                                            <th className="px-4 py-3 text-right text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
+                                                Share
+                                            </th>
+                                        </tr>
+                                    </thead>
+                                    <tbody className="bg-white dark:bg-gray-900 divide-y divide-gray-200 dark:divide-gray-700">
+                                        {preview.distributions.map((dist: HolderDistribution) => (
+                                            <tr key={dist.address}>
+                                                <td className="px-4 py-3 whitespace-nowrap text-sm font-mono text-gray-900 dark:text-white">
+                                                    {formatAddress(dist.address)}
+                                                </td>
+                                                <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-600 dark:text-gray-300">
+                                                    {formatAmount(dist.balance)}
+                                                </td>
+                                                <td className="px-4 py-3 whitespace-nowrap text-sm text-right font-medium text-green-600 dark:text-green-400">
+                                                    {formatAmount(dist.yieldAmount)}
+                                                </td>
+                                                <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-600 dark:text-gray-300">
+                                                    {dist.percentage.toFixed(2)}%
+                                                </td>
+                                            </tr>
+                                        ))}
+                                    </tbody>
+                                </table>
+                            </div>
+                        )}
+
+                        {preview.distributions.length === 0 && (
+                            <div className="p-4 bg-yellow-50 dark:bg-yellow-900/20 rounded-lg border border-yellow-200 dark:border-yellow-800">
+                                <p className="text-yellow-700 dark:text-yellow-300">
+                                    No holder addresses provided or no holders have balances.
+                                </p>
+                            </div>
+                        )}
+                    </div>
+                )}
+
+                {/* Empty State */}
+                {!preview && !isLoading && !error && (
+                    <div className="p-6 text-center text-gray-500 dark:text-gray-400">
+                        <p>Enter a distribution amount to preview how yields will be allocated.</p>
+                    </div>
+                )}
+            </div>
+        </div>
+    );
+}
+
+export default YieldCalculator;

package/src/hooks/useRWA.ts

@@ -0,0 +1,110 @@
+'use client';
+
+/**
+ * useRWA - Core hook for accessing the RWA SDK client
+ * 
+ * Provides access to the @mantle-rwa/sdk RWAClient instance with
+ * automatic wagmi wallet integration.
+ * 
+ * @example
+ * ```typescript
+ * import { useRWA } from '@mantle-rwa/react';
+ * 
+ * function MyComponent() {
+ *   const { client, isInitialized, hasSigner } = useRWA();
+ *   
+ *   if (!isInitialized) return <div>Loading...</div>;
+ *   
+ *   // Use client.token, client.kyc, client.yield, client.compliance
+ * }
+ * ```
+ */
+
+import { useState, useEffect, useCallback, useMemo } from 'react';
+import { useAccount, useWalletClient } from 'wagmi';
+import { BrowserProvider } from 'ethers';
+import { RWAClient } from '@mantle-rwa/sdk';
+import type { UseRWAConfig, UseRWAReturn, ContractAddresses } from '../types';
+
+// Default contract addresses (can be overridden via config)
+const DEFAULT_CONTRACTS: ContractAddresses = {
+    token: undefined,
+    kycRegistry: undefined,
+    yieldDistributor: undefined,
+    assetVault: undefined,
+    factory: undefined,
+};
+
+/**
+ * Hook for initializing and managing the RWA SDK client
+ * 
+ * @param config - Optional configuration for network and contract addresses
+ * @returns UseRWAReturn object with client, state, and utilities
+ */
+export function useRWA(config?: UseRWAConfig): UseRWAReturn {
+    const { isConnected } = useAccount();
+    const { data: walletClient } = useWalletClient();
+
+    const [client, setClient] = useState<RWAClient | null>(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState<Error | null>(null);
+
+    const network = config?.network ?? 'mantle-sepolia';
+
+    // Initialize or reinitialize the client
+    const initializeClient = useCallback(async () => {
+        setIsLoading(true);
+        setError(null);
+
+        try {
+            let rwaClient: RWAClient;
+
+            if (walletClient && isConnected) {
+                // Create client with wallet signer for write operations
+                const provider = new BrowserProvider(walletClient.transport);
+                const signer = await provider.getSigner();
+
+                rwaClient = new RWAClient({
+                    network,
+                    signer,
+                });
+            } else {
+                // Create read-only client (no signer)
+                rwaClient = new RWAClient({
+                    network,
+                });
+            }
+
+            setClient(rwaClient);
+        } catch (err) {
+            const errorMessage = err instanceof Error ? err.message : 'Failed to initialize RWA client';
+            setError(new Error(errorMessage));
+            setClient(null);
+        } finally {
+            setIsLoading(false);
+        }
+    }, [walletClient, isConnected, network]);
+
+    // Initialize client on mount and when wallet changes
+    useEffect(() => {
+        initializeClient();
+    }, [initializeClient]);
+
+    // Memoized contract addresses
+    const contracts = useMemo<ContractAddresses>(() => ({
+        ...DEFAULT_CONTRACTS,
+        ...config?.contracts,
+    }), [config?.contracts]);
+
+    return {
+        client,
+        isInitialized: client !== null && !isLoading,
+        isLoading,
+        error,
+        hasSigner: client?.hasSigner ?? false,
+        contracts,
+        reinitialize: initializeClient,
+    };
+}
+
+export default useRWA;

package/src/index.ts

@@ -7,7 +7,11 @@
 export { KYCFlow } from './components/KYCFlow';
 export { InvestorDashboard } from './components/InvestorDashboard';
 export { TokenMintForm } from './components/TokenMintForm';
+export { isValidAddress, isValidAmount } from './components/TokenMintForm';
 export { YieldCalculator } from './components/YieldCalculator';
+export { ErrorDisplay, formatErrorMessage } from './components/ErrorDisplay';
+export { LoadingSpinner } from './components/LoadingSpinner';
+export { ConnectWalletPrompt } from './components/ConnectWalletPrompt';
 
 // Hooks
 export { useRWA } from './hooks/useRWA';

package/src/styles/index.css

@@ -1,28 +1,82 @@
+/**
+ * @mantle-rwa/react - Default Styles
+ * 
+ * Tailwind CSS styles for RWA React components.
+ * Import this file in your application to use default styling.
+ */
+
 @tailwind base;
 @tailwind components;
 @tailwind utilities;
 
-/* Custom component styles */
-.rwa-card {
-    @apply rounded-lg border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-700 dark:bg-gray-800;
-}
+/* Base component styles */
+@layer components {
+
+    /* KYC Flow */
+    .rwa-kyc-flow {
+        @apply w-full;
+    }
+
+    /* Investor Dashboard */
+    .rwa-investor-dashboard {
+        @apply w-full;
+    }
+
+    /* Token Mint Form */
+    .rwa-token-mint-form {
+        @apply w-full max-w-md;
+    }
 
-.rwa-button {
-    @apply inline-flex items-center justify-center rounded-md px-4 py-2 text-sm font-medium transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2;
+    /* Yield Calculator */
+    .rwa-yield-calculator {
+        @apply w-full;
+    }
+
+    /* Error Display */
+    .rwa-error-display {
+        @apply w-full;
+    }
+
+    /* Loading Spinner */
+    .rwa-loading-spinner {
+        @apply inline-flex items-center justify-center;
+    }
+
+    /* Connect Wallet Prompt */
+    .rwa-connect-wallet-prompt {
+        @apply w-full;
+    }
 }
 
-.rwa-button-primary {
-    @apply rwa-button bg-mantle-600 text-white hover:bg-mantle-700 focus:ring-mantle-500;
+/* Dark mode support */
+@layer utilities {
+
+    .dark .rwa-kyc-flow,
+    .dark .rwa-investor-dashboard,
+    .dark .rwa-token-mint-form,
+    .dark .rwa-yield-calculator {
+        @apply text-gray-100;
+    }
 }
 
-.rwa-button-secondary {
-    @apply rwa-button border border-gray-300 bg-white text-gray-700 hover:bg-gray-50 focus:ring-mantle-500 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700;
+/* Custom animations */
+@keyframes rwa-spin {
+    to {
+        transform: rotate(360deg);
+    }
 }
 
-.rwa-input {
-    @apply block w-full rounded-md border border-gray-300 px-3 py-2 text-sm placeholder-gray-400 focus:border-mantle-500 focus:outline-none focus:ring-1 focus:ring-mantle-500 dark:border-gray-600 dark:bg-gray-800 dark:text-white dark:placeholder-gray-500;
+.rwa-animate-spin {
+    animation: rwa-spin 1s linear infinite;
 }
 
-.rwa-label {
-    @apply block text-sm font-medium text-gray-700 dark:text-gray-200;
+/* Focus styles for accessibility */
+@layer utilities {
+    .rwa-focus-ring {
+        @apply focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2;
+    }
+
+    .dark .rwa-focus-ring {
+        @apply focus:ring-offset-gray-900;
+    }
 }

package/src/types/index.ts

@@ -0,0 +1,200 @@
+/**
+ * Type definitions for @mantle-rwa/react
+ */
+
+// Re-export relevant types from SDK
+export {
+    AccreditationTier,
+    type TokenInfo,
+    type InvestorData,
+    type TransactionResult,
+    type Distribution,
+    type DistributionPreview,
+    type HolderDistribution,
+    type PendingClaim,
+    type VerificationSession,
+    type NetworkConfig,
+} from '@mantle-rwa/sdk';
+
+import type { RWAClient, TransactionResult, AccreditationTier, DistributionPreview } from '@mantle-rwa/sdk';
+
+/*//////////////////////////////////////////////////////////////
+                        CONTRACT ADDRESSES
+//////////////////////////////////////////////////////////////*/
+
+/**
+ * Contract addresses configuration
+ */
+export interface ContractAddresses {
+    /** RWA token contract address */
+    token?: string;
+    /** KYC registry contract address */
+    kycRegistry?: string;
+    /** Yield distributor contract address */
+    yieldDistributor?: string;
+    /** Asset vault contract address */
+    assetVault?: string;
+    /** RWA factory contract address */
+    factory?: string;
+}
+
+/*//////////////////////////////////////////////////////////////
+                        HOOK TYPES
+//////////////////////////////////////////////////////////////*/
+
+/**
+ * Configuration for useRWA hook
+ */
+export interface UseRWAConfig {
+    /** Network to connect to (default: 'mantle-sepolia') */
+    network?: 'mantle' | 'mantle-sepolia';
+    /** Contract addresses configuration */
+    contracts?: ContractAddresses;
+}
+
+/**
+ * Return type for useRWA hook
+ */
+export interface UseRWAReturn {
+    /** The RWAClient instance (null if not initialized) */
+    client: RWAClient | null;
+    /** Whether the client is initialized and ready */
+    isInitialized: boolean;
+    /** Whether the client is currently initializing */
+    isLoading: boolean;
+    /** Error that occurred during initialization */
+    error: Error | null;
+    /** Whether a signer is available (wallet connected) */
+    hasSigner: boolean;
+    /** Contract addresses */
+    contracts: ContractAddresses;
+    /** Reinitialize the client */
+    reinitialize: () => Promise<void>;
+}
+
+/*//////////////////////////////////////////////////////////////
+                        COMPONENT PROPS
+//////////////////////////////////////////////////////////////*/
+
+/**
+ * Verification status for KYC flow
+ */
+export type VerificationStatus = 'idle' | 'pending' | 'in_progress' | 'completed' | 'failed';
+
+/**
+ * Props for KYCFlow component
+ */
+export interface KYCFlowProps {
+    /** KYC registry contract address */
+    registryAddress: string;
+    /** Investor address to verify (defaults to connected wallet) */
+    investorAddress?: string;
+    /** Callback when verification status changes */
+    onStatusChange?: (status: VerificationStatus) => void;
+    /** Callback when verification completes successfully */
+    onComplete?: (tier: AccreditationTier) => void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+    /** Custom CSS class */
+    className?: string;
+}
+
+/**
+ * Props for InvestorDashboard component
+ */
+export interface InvestorDashboardProps {
+    /** RWA token contract address */
+    tokenAddress: string;
+    /** KYC registry contract address */
+    kycRegistryAddress: string;
+    /** Yield distributor contract address */
+    yieldDistributorAddress: string;
+    /** Investor address (defaults to connected wallet) */
+    investorAddress?: string;
+    /** Callback when yield claim succeeds */
+    onClaimSuccess?: (result: TransactionResult) => void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+    /** Custom CSS class */
+    className?: string;
+}
+
+/**
+ * Props for TokenMintForm component
+ */
+export interface TokenMintFormProps {
+    /** RWA token contract address */
+    tokenAddress: string;
+    /** KYC registry contract address */
+    kycRegistryAddress: string;
+    /** Callback when mint succeeds */
+    onSuccess?: (result: TransactionResult) => void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+    /** Custom CSS class */
+    className?: string;
+}
+
+/**
+ * Props for YieldCalculator component
+ */
+export interface YieldCalculatorProps {
+    /** RWA token contract address */
+    tokenAddress: string;
+    /** Yield distributor contract address */
+    yieldDistributorAddress: string;
+    /** Optional list of holder addresses to include in preview */
+    holderAddresses?: string[];
+    /** Callback when calculation completes */
+    onCalculate?: (preview: DistributionPreview) => void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+    /** Custom CSS class */
+    className?: string;
+}
+
+/*//////////////////////////////////////////////////////////////
+                        UTILITY TYPES
+//////////////////////////////////////////////////////////////*/
+
+/**
+ * Common loading state interface
+ */
+export interface LoadingState {
+    /** Whether data is loading */
+    isLoading: boolean;
+    /** Error that occurred */
+    error: Error | null;
+}
+
+/**
+ * Transaction state interface
+ */
+export interface TransactionState extends LoadingState {
+    /** Whether a transaction is pending */
+    isPending: boolean;
+    /** Transaction hash if available */
+    txHash: string | null;
+}
+
+/**
+ * Props for ErrorDisplay component
+ */
+export interface ErrorDisplayProps {
+    /** Error to display */
+    error: Error;
+    /** Callback for retry action */
+    onRetry?: () => void;
+    /** Custom CSS class */
+    className?: string;
+}
+
+/**
+ * Props for LoadingSpinner component
+ */
+export interface LoadingSpinnerProps {
+    /** Size of the spinner */
+    size?: 'sm' | 'md' | 'lg';
+    /** Custom CSS class */
+    className?: string;
+}