@mantle-rwa/sdk 0.1.0

package/src/errors/index.ts

@@ -0,0 +1,291 @@
+/**
+ * Error handling for the Mantle RWA SDK
+ * Provides descriptive error messages with suggested fixes
+ */
+
+/**
+ * Error codes for categorizing errors
+ */
+export enum ErrorCode {
+    // Contract errors
+    NOT_VERIFIED = 'NOT_VERIFIED',
+    KYC_EXPIRED = 'KYC_EXPIRED',
+    TRANSFER_RESTRICTED = 'TRANSFER_RESTRICTED',
+    TOKENS_PAUSED = 'TOKENS_PAUSED',
+    UNAUTHORIZED = 'UNAUTHORIZED',
+    INSUFFICIENT_BALANCE = 'INSUFFICIENT_BALANCE',
+    INVALID_RECIPIENT = 'INVALID_RECIPIENT',
+    CLAIM_WINDOW_EXPIRED = 'CLAIM_WINDOW_EXPIRED',
+    ALREADY_CLAIMED = 'ALREADY_CLAIMED',
+    WITHDRAWAL_THRESHOLD_NOT_MET = 'WITHDRAWAL_THRESHOLD_NOT_MET',
+    EMERGENCY_NOT_DECLARED = 'EMERGENCY_NOT_DECLARED',
+    REENTRANCY = 'REENTRANCY',
+
+    // Network errors
+    RPC_ERROR = 'RPC_ERROR',
+    TIMEOUT = 'TIMEOUT',
+    NONCE_TOO_LOW = 'NONCE_TOO_LOW',
+    INSUFFICIENT_FUNDS = 'INSUFFICIENT_FUNDS',
+    GAS_ESTIMATION_FAILED = 'GAS_ESTIMATION_FAILED',
+    NETWORK_MISMATCH = 'NETWORK_MISMATCH',
+
+    // Validation errors
+    INVALID_ADDRESS = 'INVALID_ADDRESS',
+    INVALID_AMOUNT = 'INVALID_AMOUNT',
+    MISSING_PARAMETER = 'MISSING_PARAMETER',
+    INVALID_CONFIGURATION = 'INVALID_CONFIGURATION',
+
+    // Provider errors
+    PROVIDER_NOT_CONFIGURED = 'PROVIDER_NOT_CONFIGURED',
+    SIGNER_REQUIRED = 'SIGNER_REQUIRED',
+
+    // Unknown
+    UNKNOWN = 'UNKNOWN',
+}
+
+/**
+ * Suggested fixes for common errors
+ */
+const ERROR_SUGGESTIONS: Record<ErrorCode, string> = {
+    [ErrorCode.NOT_VERIFIED]:
+        'Ensure the address is registered in the KYC registry. Use kycModule.updateRegistry() to add the investor.',
+    [ErrorCode.KYC_EXPIRED]:
+        'The KYC verification has expired. Update the investor expiry using kycModule.updateRegistry().',
+    [ErrorCode.TRANSFER_RESTRICTED]:
+        'Check compliance requirements using complianceModule.checkTransferEligibility() before attempting transfer.',
+    [ErrorCode.TOKENS_PAUSED]:
+        'Token transfers are currently paused. Contact the token issuer or wait for tokens to be unpaused.',
+    [ErrorCode.UNAUTHORIZED]:
+        'The connected account does not have the required role. Ensure you are using the correct signer.',
+    [ErrorCode.INSUFFICIENT_BALANCE]:
+        'The account does not have enough tokens. Check balance using tokenInstance.balanceOf().',
+    [ErrorCode.INVALID_RECIPIENT]:
+        'The recipient address is invalid or the zero address. Verify the address format.',
+    [ErrorCode.CLAIM_WINDOW_EXPIRED]:
+        'The claim window for this distribution has expired. Unclaimed funds may have been handled.',
+    [ErrorCode.ALREADY_CLAIMED]:
+        'This distribution has already been claimed by this account.',
+    [ErrorCode.WITHDRAWAL_THRESHOLD_NOT_MET]:
+        'Not enough signers have approved this withdrawal. Additional approvals are required.',
+    [ErrorCode.EMERGENCY_NOT_DECLARED]:
+        'Emergency mode must be declared before emergency withdrawals can be executed.',
+    [ErrorCode.REENTRANCY]:
+        'Reentrancy detected. This is a security measure. Do not call vault functions from within callbacks.',
+    [ErrorCode.RPC_ERROR]:
+        'Failed to connect to the RPC endpoint. Check your network configuration and try again.',
+    [ErrorCode.TIMEOUT]:
+        'The request timed out. The network may be congested. Try again with higher gas price.',
+    [ErrorCode.NONCE_TOO_LOW]:
+        'Transaction nonce is too low. A pending transaction may exist. Wait for it to confirm or increase nonce.',
+    [ErrorCode.INSUFFICIENT_FUNDS]:
+        'Insufficient funds for gas. Ensure the account has enough native tokens (MNT) for transaction fees.',
+    [ErrorCode.GAS_ESTIMATION_FAILED]:
+        'Gas estimation failed. The transaction may revert. Check parameters and try again.',
+    [ErrorCode.NETWORK_MISMATCH]:
+        'Connected to wrong network. Ensure your wallet is connected to the correct chain.',
+    [ErrorCode.INVALID_ADDRESS]:
+        'The provided address is not a valid Ethereum address. Check the format (0x followed by 40 hex characters).',
+    [ErrorCode.INVALID_AMOUNT]:
+        'The amount is invalid. Ensure it is a positive number and properly formatted.',
+    [ErrorCode.MISSING_PARAMETER]:
+        'A required parameter is missing. Check the function documentation for required parameters.',
+    [ErrorCode.INVALID_CONFIGURATION]:
+        'The configuration is invalid. Review the configuration object and ensure all required fields are set.',
+    [ErrorCode.PROVIDER_NOT_CONFIGURED]:
+        'No provider is configured. Initialize RWAClient with a network configuration or provider.',
+    [ErrorCode.SIGNER_REQUIRED]:
+        'A signer is required for this operation. Provide a private key or signer in the client configuration.',
+    [ErrorCode.UNKNOWN]:
+        'An unknown error occurred. Check the error details for more information.',
+};
+
+/**
+ * Base error class for RWA SDK errors
+ */
+export class RWAError extends Error {
+    readonly code: ErrorCode;
+    readonly suggestion: string;
+    readonly details?: Record<string, unknown>;
+
+    constructor(
+        code: ErrorCode,
+        message: string,
+        details?: Record<string, unknown>
+    ) {
+        super(message);
+        this.name = 'RWAError';
+        this.code = code;
+        this.suggestion = ERROR_SUGGESTIONS[code] || ERROR_SUGGESTIONS[ErrorCode.UNKNOWN];
+        this.details = details;
+
+        // Maintains proper stack trace for where error was thrown
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, RWAError);
+        }
+    }
+
+    /**
+     * Get a formatted error message including suggestion
+     */
+    toFormattedString(): string {
+        let result = `[${this.code}] ${this.message}`;
+        result += `\n\nSuggested fix: ${this.suggestion}`;
+        if (this.details) {
+            result += `\n\nDetails: ${JSON.stringify(this.details, null, 2)}`;
+        }
+        return result;
+    }
+}
+
+/**
+ * Error class for contract-related errors
+ */
+export class ContractError extends RWAError {
+    readonly contractAddress: string;
+    readonly functionName: string;
+    readonly revertReason?: string;
+
+    constructor(
+        code: ErrorCode,
+        message: string,
+        contractAddress: string,
+        functionName: string,
+        revertReason?: string,
+        details?: Record<string, unknown>
+    ) {
+        super(code, message, details);
+        this.name = 'ContractError';
+        this.contractAddress = contractAddress;
+        this.functionName = functionName;
+        this.revertReason = revertReason;
+    }
+}
+
+/**
+ * Error class for network-related errors
+ */
+export class NetworkError extends RWAError {
+    readonly chainId?: number;
+    readonly rpcUrl?: string;
+    readonly retryable: boolean;
+
+    constructor(
+        code: ErrorCode,
+        message: string,
+        retryable: boolean,
+        chainId?: number,
+        rpcUrl?: string,
+        details?: Record<string, unknown>
+    ) {
+        super(code, message, details);
+        this.name = 'NetworkError';
+        this.chainId = chainId;
+        this.rpcUrl = rpcUrl;
+        this.retryable = retryable;
+    }
+}
+
+/**
+ * Error class for validation errors
+ */
+export class ValidationError extends RWAError {
+    readonly field: string;
+    readonly constraint: string;
+    readonly value: unknown;
+
+    constructor(
+        code: ErrorCode,
+        message: string,
+        field: string,
+        constraint: string,
+        value: unknown,
+        details?: Record<string, unknown>
+    ) {
+        super(code, message, details);
+        this.name = 'ValidationError';
+        this.field = field;
+        this.constraint = constraint;
+        this.value = value;
+    }
+}
+
+/**
+ * Parse a contract revert reason and return the appropriate error
+ */
+export function parseContractError(
+    error: unknown,
+    contractAddress: string,
+    functionName: string
+): ContractError {
+    const errorObj = error as { reason?: string; message?: string; data?: string };
+    const reason = errorObj.reason || errorObj.message || 'Unknown contract error';
+
+    // Map common revert reasons to error codes
+    let code = ErrorCode.UNKNOWN;
+    if (reason.includes('NotVerified') || reason.includes('not verified')) {
+        code = ErrorCode.NOT_VERIFIED;
+    } else if (reason.includes('KYCExpired') || reason.includes('expired')) {
+        code = ErrorCode.KYC_EXPIRED;
+    } else if (reason.includes('TransferRestricted') || reason.includes('restricted')) {
+        code = ErrorCode.TRANSFER_RESTRICTED;
+    } else if (reason.includes('Paused') || reason.includes('paused')) {
+        code = ErrorCode.TOKENS_PAUSED;
+    } else if (reason.includes('AccessControl') || reason.includes('unauthorized') || reason.includes('Ownable')) {
+        code = ErrorCode.UNAUTHORIZED;
+    } else if (reason.includes('insufficient') || reason.includes('balance')) {
+        code = ErrorCode.INSUFFICIENT_BALANCE;
+    } else if (reason.includes('ClaimWindowExpired')) {
+        code = ErrorCode.CLAIM_WINDOW_EXPIRED;
+    } else if (reason.includes('AlreadyClaimed')) {
+        code = ErrorCode.ALREADY_CLAIMED;
+    } else if (reason.includes('ReentrancyGuard')) {
+        code = ErrorCode.REENTRANCY;
+    }
+
+    return new ContractError(
+        code,
+        `Contract call failed: ${reason}`,
+        contractAddress,
+        functionName,
+        reason,
+        { originalError: errorObj.message }
+    );
+}
+
+/**
+ * Parse a network error and return the appropriate error
+ */
+export function parseNetworkError(
+    error: unknown,
+    chainId?: number,
+    rpcUrl?: string
+): NetworkError {
+    const errorObj = error as { code?: string; message?: string };
+    const message = errorObj.message || 'Unknown network error';
+
+    let code = ErrorCode.RPC_ERROR;
+    let retryable = true;
+
+    if (message.includes('nonce') && message.includes('low')) {
+        code = ErrorCode.NONCE_TOO_LOW;
+        retryable = true;
+    } else if (message.includes('timeout') || message.includes('ETIMEDOUT')) {
+        code = ErrorCode.TIMEOUT;
+        retryable = true;
+    } else if (message.includes('insufficient funds')) {
+        code = ErrorCode.INSUFFICIENT_FUNDS;
+        retryable = false;
+    } else if (message.includes('gas')) {
+        code = ErrorCode.GAS_ESTIMATION_FAILED;
+        retryable = false;
+    }
+
+    return new NetworkError(
+        code,
+        `Network error: ${message}`,
+        retryable,
+        chainId,
+        rpcUrl,
+        { originalError: message }
+    );
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+/**
+ * @mantle-rwa/sdk
+ * TypeScript SDK for Real-World Asset tokenization on Mantle Network
+ */
+
+// Core client
+export { RWAClient } from './client';
+export type { RWAClientConfig } from './client';
+
+// Modules
+export {
+    TokenModule,
+    TokenInstance,
+    KYCModule,
+    KYCRegistryInstance,
+    YieldModule,
+    YieldDistributorInstance,
+    ComplianceModule,
+} from './modules';
+export type { KYCProvider } from './modules';
+
+// Types
+export * from './types';
+
+// Errors
+export * from './errors';
+
+// Constants
+export * from './constants';
+
+// Utilities
+export {
+    isValidAddress,
+    normalizeAddress,
+    parseAmount,
+    formatAmount,
+    hashIdentityData,
+    timestampToDate,
+    dateToTimestamp,
+    isExpired,
+    calculatePercentage,
+} from './utils';

package/src/modules/compliance.ts

@@ -0,0 +1,252 @@
+/**
+ * ComplianceModule - Handles transfer eligibility and compliance reporting
+ */
+
+import { ethers, type Provider, type Signer } from 'ethers';
+import type {
+    TransferEligibility,
+    TransferCheck,
+    ComplianceReport,
+    FilingData,
+} from '../types';
+import { RWA_TOKEN_ABI, KYC_REGISTRY_ABI } from '../constants';
+import { RWAError, ErrorCode } from '../errors';
+import { isValidAddress, normalizeAddress, parseAmount } from '../utils';
+
+/**
+ * Module for compliance operations
+ */
+export class ComplianceModule {
+    private readonly _provider: Provider;
+
+    constructor(provider: Provider, _signer: Signer | null) {
+        this._provider = provider;
+    }
+
+    /**
+     * Check if a transfer is eligible
+     */
+    async checkTransferEligibility(
+        tokenAddress: string,
+        from: string,
+        to: string,
+        amount: string
+    ): Promise<TransferEligibility> {
+        if (!isValidAddress(tokenAddress)) {
+            throw new RWAError(ErrorCode.INVALID_ADDRESS, `Invalid token address: ${tokenAddress}`);
+        }
+        if (!isValidAddress(from)) {
+            throw new RWAError(ErrorCode.INVALID_ADDRESS, `Invalid from address: ${from}`);
+        }
+        if (!isValidAddress(to)) {
+            throw new RWAError(ErrorCode.INVALID_ADDRESS, `Invalid to address: ${to}`);
+        }
+
+        const token = new ethers.Contract(tokenAddress, RWA_TOKEN_ABI, this._provider);
+        const checks: TransferCheck[] = [];
+
+        // Check 1: Token not paused
+        try {
+            const paused = await token.paused();
+            checks.push({
+                name: 'Token Active',
+                passed: !paused,
+                details: paused ? 'Token transfers are currently paused' : 'Token is active',
+            });
+        } catch {
+            checks.push({
+                name: 'Token Active',
+                passed: false,
+                details: 'Unable to check pause status',
+            });
+        }
+
+        // Check 2: Sender has sufficient balance
+        try {
+            const balance = await token.balanceOf(normalizeAddress(from));
+            const amountWei = parseAmount(amount);
+            const hasBalance = balance >= amountWei;
+            checks.push({
+                name: 'Sufficient Balance',
+                passed: hasBalance,
+                details: hasBalance
+                    ? `Balance: ${balance.toString()}`
+                    : `Insufficient balance. Has: ${balance.toString()}, Needs: ${amountWei.toString()}`,
+            });
+        } catch {
+            checks.push({
+                name: 'Sufficient Balance',
+                passed: false,
+                details: 'Unable to check balance',
+            });
+        }
+
+        // Check 3: KYC verification for sender and recipient
+        try {
+            const kycRegistryAddress = await token.kycRegistry();
+            if (kycRegistryAddress !== ethers.ZeroAddress) {
+                const kycRegistry = new ethers.Contract(
+                    kycRegistryAddress,
+                    KYC_REGISTRY_ABI,
+                    this._provider
+                );
+
+                // Check sender (skip for minting from zero address)
+                if (from !== ethers.ZeroAddress) {
+                    const senderVerified = await kycRegistry.isVerified(normalizeAddress(from));
+                    checks.push({
+                        name: 'Sender KYC Verified',
+                        passed: senderVerified,
+                        details: senderVerified
+                            ? 'Sender is KYC verified'
+                            : 'Sender is not KYC verified or verification has expired',
+                    });
+                }
+
+                // Check recipient
+                const recipientVerified = await kycRegistry.isVerified(normalizeAddress(to));
+                checks.push({
+                    name: 'Recipient KYC Verified',
+                    passed: recipientVerified,
+                    details: recipientVerified
+                        ? 'Recipient is KYC verified'
+                        : 'Recipient is not KYC verified or verification has expired',
+                });
+            }
+        } catch {
+            checks.push({
+                name: 'KYC Verification',
+                passed: false,
+                details: 'Unable to check KYC status',
+            });
+        }
+
+        // Check 4: Compliance modules
+        try {
+            const [allowed, reason] = await token.isTransferAllowed(
+                normalizeAddress(from),
+                normalizeAddress(to),
+                parseAmount(amount)
+            );
+            checks.push({
+                name: 'Compliance Modules',
+                passed: allowed,
+                details: allowed ? 'All compliance checks passed' : reason,
+            });
+        } catch {
+            checks.push({
+                name: 'Compliance Modules',
+                passed: false,
+                details: 'Unable to check compliance modules',
+            });
+        }
+
+        // Determine overall eligibility
+        const allPassed = checks.every((c) => c.passed);
+        const failedCheck = checks.find((c) => !c.passed);
+
+        return {
+            eligible: allPassed,
+            reason: allPassed ? undefined : failedCheck?.details,
+            checks,
+        };
+    }
+
+    /**
+     * Generate a compliance report for a token
+     */
+    async generateComplianceReport(tokenAddress: string): Promise<ComplianceReport> {
+        if (!isValidAddress(tokenAddress)) {
+            throw new RWAError(ErrorCode.INVALID_ADDRESS, `Invalid token address: ${tokenAddress}`);
+        }
+
+        const token = new ethers.Contract(tokenAddress, RWA_TOKEN_ABI, this._provider);
+
+        // Get KYC registry - verify it exists
+        try {
+            await token.kycRegistry();
+        } catch {
+            throw new RWAError(
+                ErrorCode.INVALID_CONFIGURATION,
+                'Unable to get KYC registry from token contract'
+            );
+        }
+
+        // Note: In a production implementation, this would require an indexer
+        // to track all token holders and their KYC status. This is a simplified
+        // version that returns placeholder data.
+        const report: ComplianceReport = {
+            generatedAt: new Date(),
+            tokenAddress: normalizeAddress(tokenAddress),
+            totalHolders: 0, // Would need indexer
+            verifiedHolders: 0, // Would need indexer
+            accreditedHolders: 0, // Would need indexer
+            transfersBlocked: 0, // Would need event indexing
+            complianceScore: 100, // Placeholder
+        };
+
+        return report;
+    }
+
+    /**
+     * Export a compliance report in various formats
+     */
+    async exportReport(
+        report: ComplianceReport,
+        format: 'json' | 'csv' | 'pdf'
+    ): Promise<Buffer> {
+        switch (format) {
+            case 'json':
+                return Buffer.from(JSON.stringify(report, null, 2));
+
+            case 'csv': {
+                const headers = Object.keys(report).join(',');
+                const values = Object.values(report)
+                    .map((v) => (v instanceof Date ? v.toISOString() : String(v)))
+                    .join(',');
+                return Buffer.from(`${headers}\n${values}`);
+            }
+
+            case 'pdf':
+                // PDF generation would require a library like pdfkit
+                throw new RWAError(
+                    ErrorCode.INVALID_CONFIGURATION,
+                    'PDF export requires additional dependencies. Use JSON or CSV format.'
+                );
+
+            default:
+                throw new RWAError(
+                    ErrorCode.INVALID_CONFIGURATION,
+                    `Unsupported export format: ${format}`
+                );
+        }
+    }
+
+    /**
+     * Prepare filing data for regulatory submissions
+     */
+    async prepareFilingData(
+        tokenAddress: string,
+        filingType: string,
+        startDate?: Date,
+        endDate?: Date
+    ): Promise<FilingData> {
+        const report = await this.generateComplianceReport(tokenAddress);
+
+        return {
+            filingType,
+            tokenAddress: normalizeAddress(tokenAddress),
+            reportingPeriod: {
+                start: startDate || new Date(Date.now() - 30 * 24 * 60 * 60 * 1000), // Default: 30 days ago
+                end: endDate || new Date(),
+            },
+            data: {
+                totalHolders: report.totalHolders,
+                verifiedHolders: report.verifiedHolders,
+                accreditedHolders: report.accreditedHolders,
+                complianceScore: report.complianceScore,
+                generatedAt: report.generatedAt.toISOString(),
+            },
+        };
+    }
+}

package/src/modules/index.ts

@@ -0,0 +1,8 @@
+/**
+ * SDK Modules
+ */
+
+export { TokenModule, TokenInstance } from './token';
+export { KYCModule, KYCRegistryInstance, type KYCProvider } from './kyc';
+export { YieldModule, YieldDistributorInstance } from './yield';
+export { ComplianceModule } from './compliance';