@mantle-rwa/react 0.1.0

package/src/components/YieldCalculator/index.tsx

@@ -0,0 +1,541 @@
+/**
+ * YieldCalculator Component
+ * Preview and calculate yield distributions before execution
+ * 
+ * @see Requirements 13.1, 13.2, 13.3, 13.4
+ */
+
+import React, { useState, useCallback, useMemo } from 'react';
+import type { YieldCalculatorProps, DistributionPreviewEntry, DistributionConfig, PaymentToken } from '../../types';
+
+/**
+ * Calculate proportional yield distribution for holders
+ * This is the core calculation function for Property 26
+ * 
+ * @param totalAmount - Total amount to distribute (in smallest unit)
+ * @param holders - Array of holder addresses and balances
+ * @returns Array of distribution preview entries
+ */
+export function calculateDistribution(
+    totalAmount: bigint,
+    holders: Array<{ address: string; balance: bigint }>
+): DistributionPreviewEntry[] {
+    if (holders.length === 0 || totalAmount <= BigInt(0)) {
+        return [];
+    }
+
+    const totalSupply = holders.reduce((sum, h) => sum + h.balance, BigInt(0));
+
+    if (totalSupply === BigInt(0)) {
+        return [];
+    }
+
+    // Property 26: Yield Calculator Distribution Accuracy
+    // Sum of per-holder amounts must equal total amount (within rounding)
+    return holders.map((holder) => {
+        // Calculate percentage with 2 decimal precision (multiply by 10000, then divide by 100)
+        const percentage = Number(holder.balance * BigInt(10000) / totalSupply) / 100;
+
+        // Calculate yield amount proportionally
+        const yieldAmount = (totalAmount * holder.balance) / totalSupply;
+
+        return {
+            address: holder.address,
+            balance: holder.balance,
+            yieldAmount,
+            percentage,
+        };
+    });
+}
+
+/**
+ * Calculate the sum of all yield amounts in a distribution
+ * Used to verify Property 26 (distribution accuracy)
+ */
+export function sumDistributionAmounts(entries: DistributionPreviewEntry[]): bigint {
+    return entries.reduce((sum, entry) => sum + entry.yieldAmount, BigInt(0));
+}
+
+/**
+ * Format a bigint amount for display with decimals
+ */
+export function formatAmount(value: bigint, decimals: number): string {
+    if (decimals <= 0) {
+        return value.toLocaleString();
+    }
+
+    const divisor = BigInt(10 ** decimals);
+    const integerPart = value / divisor;
+    const fractionalPart = value % divisor;
+    const fractionalStr = fractionalPart.toString().padStart(decimals, '0').slice(0, 2);
+    return `${integerPart.toLocaleString()}.${fractionalStr}`;
+}
+
+/**
+ * Parse a decimal string amount to bigint with given decimals
+ */
+export function parseAmount(value: string, decimals: number): bigint {
+    const num = parseFloat(value);
+    if (isNaN(num) || num < 0) {
+        return BigInt(0);
+    }
+    return BigInt(Math.floor(num * (10 ** decimals)));
+}
+
+/**
+ * Export distribution preview to CSV format
+ */
+export function exportToCSV(
+    entries: DistributionPreviewEntry[],
+    tokenSymbol: string,
+    decimals: number
+): string {
+    const headers = 'Address,Balance,Yield Amount,Percentage\n';
+    const rows = entries.map((entry) =>
+        `${entry.address},${entry.balance.toString()},${formatAmount(entry.yieldAmount, decimals)} ${tokenSymbol},${entry.percentage.toFixed(2)}%`
+    ).join('\n');
+    return headers + rows;
+}
+
+/**
+ * Export distribution preview to JSON format
+ */
+export function exportToJSON(entries: DistributionPreviewEntry[]): string {
+    return JSON.stringify(entries.map((entry) => ({
+        address: entry.address,
+        balance: entry.balance.toString(),
+        yieldAmount: entry.yieldAmount.toString(),
+        percentage: entry.percentage,
+    })), null, 2);
+}
+
+/**
+ * Generate colors for pie chart segments
+ */
+function generateChartColors(count: number): string[] {
+    const baseColors = [
+        '#3B82F6', // blue
+        '#10B981', // green
+        '#F59E0B', // amber
+        '#EF4444', // red
+        '#8B5CF6', // purple
+        '#EC4899', // pink
+        '#06B6D4', // cyan
+        '#F97316', // orange
+    ];
+
+    const colors: string[] = [];
+    for (let i = 0; i < count; i++) {
+        colors.push(baseColors[i % baseColors.length]);
+    }
+    return colors;
+}
+
+/**
+ * YieldCalculator component for previewing yield distributions
+ * Shows per-holder breakdown with optional chart visualization
+ * 
+ * @example
+ * ```tsx
+ * <YieldCalculator
+ *   tokenAddress="0x..."
+ *   yieldDistributorAddress="0x..."
+ *   supportedPaymentTokens={[{ address: '0x...', symbol: 'USDC', decimals: 6 }]}
+ *   onDistribute={(config) => console.log('Distributing:', config)}
+ * />
+ * ```
+ */
+export function YieldCalculator({
+    tokenAddress,
+    yieldDistributorAddress: _yieldDistributorAddress, // Reserved for future contract interaction
+    supportedPaymentTokens,
+    onDistribute,
+    showChart = true,
+    allowExport = true,
+    theme = 'light',
+}: YieldCalculatorProps): React.ReactElement {
+    const [totalAmount, setTotalAmount] = useState('');
+    const [selectedToken, setSelectedToken] = useState(supportedPaymentTokens[0]?.address ?? '');
+    const [snapshotDate, setSnapshotDate] = useState<string>(new Date().toISOString().split('T')[0]);
+    const [claimWindowDays, setClaimWindowDays] = useState('30');
+    const [preview, setPreview] = useState<DistributionPreviewEntry[]>([]);
+    const [isCalculating, setIsCalculating] = useState(false);
+    const [chartType, setChartType] = useState<'bar' | 'pie'>('bar');
+
+    const isDark = theme === 'dark';
+
+    const selectedTokenInfo = useMemo<PaymentToken | undefined>(() =>
+        supportedPaymentTokens.find((t) => t.address === selectedToken),
+        [supportedPaymentTokens, selectedToken]
+    );
+
+    const calculatePreview = useCallback(async () => {
+        if (!totalAmount || parseFloat(totalAmount) <= 0) return;
+
+        setIsCalculating(true);
+
+        try {
+            // Placeholder: In full implementation, this would fetch actual holder data
+            await new Promise((resolve) => setTimeout(resolve, 500));
+
+            // Mock holder data for preview
+            const mockHolders = [
+                { address: '0x1234567890123456789012345678901234567890', balance: BigInt(500) * BigInt(10 ** 18) },
+                { address: '0x2345678901234567890123456789012345678901', balance: BigInt(300) * BigInt(10 ** 18) },
+                { address: '0x3456789012345678901234567890123456789012', balance: BigInt(200) * BigInt(10 ** 18) },
+            ];
+
+            const totalAmountBigInt = parseAmount(totalAmount, selectedTokenInfo?.decimals ?? 6);
+            const previewEntries = calculateDistribution(totalAmountBigInt, mockHolders);
+
+            setPreview(previewEntries);
+        } catch (error) {
+            console.error('Failed to calculate preview:', error);
+        } finally {
+            setIsCalculating(false);
+        }
+    }, [totalAmount, selectedTokenInfo]);
+
+    const handleDistribute = useCallback(() => {
+        if (!selectedTokenInfo || !totalAmount) return;
+
+        const config: DistributionConfig = {
+            tokenAddress,
+            paymentToken: selectedToken,
+            totalAmount,
+            snapshotDate: new Date(snapshotDate),
+            claimWindowDays: parseInt(claimWindowDays, 10),
+        };
+
+        onDistribute?.(config);
+    }, [tokenAddress, selectedToken, totalAmount, snapshotDate, claimWindowDays, onDistribute, selectedTokenInfo]);
+
+    const handleExport = useCallback((format: 'csv' | 'json') => {
+        if (preview.length === 0) return;
+
+        let content: string;
+        let filename: string;
+        let mimeType: string;
+
+        if (format === 'csv') {
+            content = exportToCSV(preview, selectedTokenInfo?.symbol ?? '', selectedTokenInfo?.decimals ?? 6);
+            filename = `yield-distribution-${Date.now()}.csv`;
+            mimeType = 'text/csv';
+        } else {
+            content = exportToJSON(preview);
+            filename = `yield-distribution-${Date.now()}.json`;
+            mimeType = 'application/json';
+        }
+
+        const blob = new Blob([content], { type: mimeType });
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = filename;
+        a.click();
+        URL.revokeObjectURL(url);
+    }, [preview, selectedTokenInfo]);
+
+    // Calculate total distributed for verification
+    const totalDistributed = useMemo(() => sumDistributionAmounts(preview), [preview]);
+
+    // Generate chart colors
+    const chartColors = useMemo(() => generateChartColors(preview.length), [preview.length]);
+
+    // Calculate pie chart segments
+    const pieSegments = useMemo(() => {
+        if (preview.length === 0) return [];
+
+        let cumulativePercentage = 0;
+        return preview.map((entry, index) => {
+            const startAngle = cumulativePercentage * 3.6; // Convert percentage to degrees
+            cumulativePercentage += entry.percentage;
+            const endAngle = cumulativePercentage * 3.6;
+
+            return {
+                ...entry,
+                startAngle,
+                endAngle,
+                color: chartColors[index],
+            };
+        });
+    }, [preview, chartColors]);
+
+    return (
+        <div
+            className={`rwa-card ${isDark ? 'dark' : ''}`}
+            data-testid="yield-calculator"
+            data-theme={theme}
+        >
+            <h2 className="text-lg font-semibold mb-4">Yield Calculator</h2>
+
+            {/* Configuration Form */}
+            <div className="space-y-4 mb-6">
+                <div className="grid grid-cols-2 gap-4">
+                    <div>
+                        <label htmlFor="total-amount" className="rwa-label">
+                            Total Distribution Amount
+                        </label>
+                        <input
+                            id="total-amount"
+                            type="number"
+                            className="rwa-input mt-1"
+                            placeholder="0.00"
+                            value={totalAmount}
+                            onChange={(e) => setTotalAmount(e.target.value)}
+                            min="0"
+                            step="any"
+                            data-testid="total-amount-input"
+                        />
+                    </div>
+
+                    <div>
+                        <label htmlFor="payment-token" className="rwa-label">
+                            Payment Token
+                        </label>
+                        <select
+                            id="payment-token"
+                            className="rwa-input mt-1"
+                            value={selectedToken}
+                            onChange={(e) => setSelectedToken(e.target.value)}
+                            data-testid="payment-token-select"
+                        >
+                            {supportedPaymentTokens.map((token) => (
+                                <option key={token.address} value={token.address}>
+                                    {token.symbol}
+                                </option>
+                            ))}
+                        </select>
+                    </div>
+                </div>
+
+                <div className="grid grid-cols-2 gap-4">
+                    <div>
+                        <label htmlFor="snapshot-date" className="rwa-label">
+                            Snapshot Date
+                        </label>
+                        <input
+                            id="snapshot-date"
+                            type="date"
+                            className="rwa-input mt-1"
+                            value={snapshotDate}
+                            onChange={(e) => setSnapshotDate(e.target.value)}
+                            data-testid="snapshot-date-input"
+                        />
+                    </div>
+
+                    <div>
+                        <label htmlFor="claim-window" className="rwa-label">
+                            Claim Window (days)
+                        </label>
+                        <input
+                            id="claim-window"
+                            type="number"
+                            className="rwa-input mt-1"
+                            value={claimWindowDays}
+                            onChange={(e) => setClaimWindowDays(e.target.value)}
+                            min="1"
+                            max="365"
+                            data-testid="claim-window-input"
+                        />
+                    </div>
+                </div>
+
+                <button
+                    type="button"
+                    className="rwa-button-secondary w-full"
+                    onClick={calculatePreview}
+                    disabled={isCalculating || !totalAmount}
+                    aria-busy={isCalculating}
+                    data-testid="calculate-preview-btn"
+                >
+                    {isCalculating ? 'Calculating...' : 'Calculate Preview'}
+                </button>
+            </div>
+
+            {/* Preview Results */}
+            {preview.length > 0 && (
+                <div className="space-y-4" data-testid="distribution-preview">
+                    <div className="flex justify-between items-center">
+                        <h3 className="text-sm font-medium">Distribution Preview</h3>
+                        <div className="flex items-center space-x-4">
+                            {/* Chart Type Toggle */}
+                            {showChart && (
+                                <div className="flex space-x-1" role="group" aria-label="Chart type">
+                                    <button
+                                        type="button"
+                                        className={`px-2 py-1 text-xs rounded ${chartType === 'bar' ? 'bg-mantle-600 text-white' : 'bg-gray-200 dark:bg-gray-700'}`}
+                                        onClick={() => setChartType('bar')}
+                                        data-testid="chart-type-bar"
+                                    >
+                                        Bar
+                                    </button>
+                                    <button
+                                        type="button"
+                                        className={`px-2 py-1 text-xs rounded ${chartType === 'pie' ? 'bg-mantle-600 text-white' : 'bg-gray-200 dark:bg-gray-700'}`}
+                                        onClick={() => setChartType('pie')}
+                                        data-testid="chart-type-pie"
+                                    >
+                                        Pie
+                                    </button>
+                                </div>
+                            )}
+                            {allowExport && (
+                                <div className="flex space-x-2">
+                                    <button
+                                        type="button"
+                                        className="text-xs text-mantle-600 hover:text-mantle-700"
+                                        onClick={() => handleExport('csv')}
+                                        data-testid="export-csv-btn"
+                                    >
+                                        Export CSV
+                                    </button>
+                                    <button
+                                        type="button"
+                                        className="text-xs text-mantle-600 hover:text-mantle-700"
+                                        onClick={() => handleExport('json')}
+                                        data-testid="export-json-btn"
+                                    >
+                                        Export JSON
+                                    </button>
+                                </div>
+                            )}
+                        </div>
+                    </div>
+
+                    {/* Chart Visualization */}
+                    {showChart && (
+                        <div data-testid="distribution-chart">
+                            {chartType === 'bar' ? (
+                                /* Bar Chart */
+                                <div className="space-y-2" role="img" aria-label="Distribution bar chart" data-testid="bar-chart">
+                                    {preview.map((entry, index) => (
+                                        <div key={entry.address} className="flex items-center space-x-2">
+                                            <span className="text-xs w-24 truncate" title={entry.address}>
+                                                {entry.address.slice(0, 6)}...{entry.address.slice(-4)}
+                                            </span>
+                                            <div className="flex-1 h-4 bg-gray-200 dark:bg-gray-700 rounded-full overflow-hidden">
+                                                <div
+                                                    className="h-full rounded-full transition-all duration-300"
+                                                    style={{
+                                                        width: `${entry.percentage}%`,
+                                                        backgroundColor: chartColors[index],
+                                                    }}
+                                                    data-testid={`bar-segment-${index}`}
+                                                />
+                                            </div>
+                                            <span className="text-xs w-16 text-right">
+                                                {entry.percentage.toFixed(1)}%
+                                            </span>
+                                        </div>
+                                    ))}
+                                </div>
+                            ) : (
+                                /* Pie Chart (SVG-based) */
+                                <div className="flex items-center justify-center" data-testid="pie-chart">
+                                    <svg viewBox="0 0 100 100" className="w-48 h-48" role="img" aria-label="Distribution pie chart">
+                                        {pieSegments.map((segment, index) => {
+                                            // Convert angles to radians and calculate arc path
+                                            const startRad = (segment.startAngle - 90) * Math.PI / 180;
+                                            const endRad = (segment.endAngle - 90) * Math.PI / 180;
+
+                                            const x1 = 50 + 40 * Math.cos(startRad);
+                                            const y1 = 50 + 40 * Math.sin(startRad);
+                                            const x2 = 50 + 40 * Math.cos(endRad);
+                                            const y2 = 50 + 40 * Math.sin(endRad);
+
+                                            const largeArc = segment.percentage > 50 ? 1 : 0;
+
+                                            const pathD = `M 50 50 L ${x1} ${y1} A 40 40 0 ${largeArc} 1 ${x2} ${y2} Z`;
+
+                                            return (
+                                                <path
+                                                    key={segment.address}
+                                                    d={pathD}
+                                                    fill={segment.color}
+                                                    stroke="white"
+                                                    strokeWidth="0.5"
+                                                    data-testid={`pie-segment-${index}`}
+                                                >
+                                                    <title>{`${segment.address.slice(0, 6)}...${segment.address.slice(-4)}: ${segment.percentage.toFixed(1)}%`}</title>
+                                                </path>
+                                            );
+                                        })}
+                                    </svg>
+                                    {/* Legend */}
+                                    <div className="ml-4 space-y-1">
+                                        {preview.map((entry, index) => (
+                                            <div key={entry.address} className="flex items-center text-xs">
+                                                <div
+                                                    className="w-3 h-3 rounded-sm mr-2"
+                                                    style={{ backgroundColor: chartColors[index] }}
+                                                />
+                                                <span className="truncate max-w-[100px]" title={entry.address}>
+                                                    {entry.address.slice(0, 6)}...{entry.address.slice(-4)}
+                                                </span>
+                                                <span className="ml-2 text-gray-500">
+                                                    {entry.percentage.toFixed(1)}%
+                                                </span>
+                                            </div>
+                                        ))}
+                                    </div>
+                                </div>
+                            )}
+                        </div>
+                    )}
+
+                    {/* Detailed Table */}
+                    <div className="overflow-x-auto" data-testid="distribution-table">
+                        <table className="w-full text-sm">
+                            <thead>
+                                <tr className="border-b dark:border-gray-700">
+                                    <th className="text-left py-2">Address</th>
+                                    <th className="text-right py-2">Yield Amount</th>
+                                    <th className="text-right py-2">%</th>
+                                </tr>
+                            </thead>
+                            <tbody>
+                                {preview.map((entry, index) => (
+                                    <tr key={entry.address} className="border-b dark:border-gray-700" data-testid={`table-row-${index}`}>
+                                        <td className="py-2">
+                                            <span title={entry.address}>
+                                                {entry.address.slice(0, 10)}...{entry.address.slice(-8)}
+                                            </span>
+                                        </td>
+                                        <td className="text-right py-2" data-testid={`yield-amount-${index}`}>
+                                            {formatAmount(entry.yieldAmount, selectedTokenInfo?.decimals ?? 6)} {selectedTokenInfo?.symbol}
+                                        </td>
+                                        <td className="text-right py-2" data-testid={`percentage-${index}`}>
+                                            {entry.percentage.toFixed(2)}%
+                                        </td>
+                                    </tr>
+                                ))}
+                            </tbody>
+                            <tfoot>
+                                <tr className="font-medium">
+                                    <td className="py-2">Total</td>
+                                    <td className="text-right py-2" data-testid="total-distributed">
+                                        {formatAmount(totalDistributed, selectedTokenInfo?.decimals ?? 6)} {selectedTokenInfo?.symbol}
+                                    </td>
+                                    <td className="text-right py-2" data-testid="total-percentage">100%</td>
+                                </tr>
+                            </tfoot>
+                        </table>
+                    </div>
+
+                    {/* Distribute Button */}
+                    <button
+                        type="button"
+                        className="rwa-button-primary w-full"
+                        onClick={handleDistribute}
+                        data-testid="execute-distribution-btn"
+                    >
+                        Execute Distribution
+                    </button>
+                </div>
+            )}
+        </div>
+    );
+}
+
+export default YieldCalculator;

package/src/components/index.ts

@@ -0,0 +1,8 @@
+/**
+ * React components for RWA tokenization
+ */
+
+export { KYCFlow } from './KYCFlow';
+export { InvestorDashboard } from './InvestorDashboard';
+export { TokenMintForm } from './TokenMintForm';
+export { YieldCalculator } from './YieldCalculator';

package/src/hooks/index.ts

@@ -0,0 +1,5 @@
+/**
+ * React hooks for RWA functionality
+ */
+
+export { useRWA } from './useRWA';

package/src/hooks/useRWA.ts

@@ -0,0 +1,70 @@
+/**
+ * useRWA hook for accessing RWA SDK functionality in React components
+ */
+
+import { useState, useEffect } from 'react';
+import type { UseRWAReturn } from '../types';
+
+/**
+ * Hook for accessing RWA SDK functionality
+ * Provides connection status and SDK client access
+ */
+export function useRWA(): UseRWAReturn {
+    const [isInitialized, setIsInitialized] = useState(false);
+    const [chainId, setChainId] = useState<number | undefined>(undefined);
+    const [address, setAddress] = useState<string | undefined>(undefined);
+    const [isConnected, setIsConnected] = useState(false);
+    const [error, setError] = useState<Error | null>(null);
+
+    useEffect(() => {
+        // Initialize SDK client
+        const initializeSDK = async () => {
+            try {
+                // Check if window.ethereum is available (browser wallet)
+                if (typeof window !== 'undefined' && window.ethereum) {
+                    const accounts = await window.ethereum.request?.({
+                        method: 'eth_accounts',
+                    }) as string[] | undefined;
+
+                    if (accounts && accounts.length > 0) {
+                        setAddress(accounts[0]);
+                        setIsConnected(true);
+                    }
+
+                    const chainIdHex = await window.ethereum.request?.({
+                        method: 'eth_chainId',
+                    }) as string | undefined;
+
+                    if (chainIdHex) {
+                        setChainId(parseInt(chainIdHex, 16));
+                    }
+                }
+
+                setIsInitialized(true);
+            } catch (err) {
+                setError(err instanceof Error ? err : new Error('Failed to initialize RWA SDK'));
+            }
+        };
+
+        initializeSDK();
+    }, []);
+
+    return {
+        isInitialized,
+        chainId,
+        address,
+        isConnected,
+        error,
+    };
+}
+
+// Extend Window interface for ethereum provider
+declare global {
+    interface Window {
+        ethereum?: {
+            request?: (args: { method: string; params?: unknown[] }) => Promise<unknown>;
+            on?: (event: string, callback: (...args: unknown[]) => void) => void;
+            removeListener?: (event: string, callback: (...args: unknown[]) => void) => void;
+        };
+    }
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @mantle-rwa/react
+ * React components for Real-World Asset tokenization on Mantle Network
+ */
+
+// Components
+export { KYCFlow } from './components/KYCFlow';
+export { InvestorDashboard } from './components/InvestorDashboard';
+export { TokenMintForm } from './components/TokenMintForm';
+export { YieldCalculator } from './components/YieldCalculator';
+
+// Hooks
+export { useRWA } from './hooks/useRWA';
+
+// Types
+export type {
+    Theme,
+    KYCProviderType,
+    KYCRequiredField,
+    KYCResult,
+    KYCFlowProps,
+    KYCFlowStyles,
+    InvestorDashboardProps,
+    YieldHistoryEntry,
+    TokenMintFormProps,
+    BatchMintEntry,
+    YieldCalculatorProps,
+    PaymentToken,
+    DistributionConfig,
+    DistributionPreviewEntry,
+    UseRWAReturn,
+} from './types';