@mantle-rwa/sdk 0.1.0

package/src/types/index.ts

@@ -0,0 +1,326 @@
+/**
+ * Core type definitions for the Mantle RWA SDK
+ */
+
+import type { TransactionReceipt } from 'ethers';
+
+/*//////////////////////////////////////////////////////////////
+                        NETWORK TYPES
+//////////////////////////////////////////////////////////////*/
+
+/**
+ * Supported network names
+ */
+export type NetworkName = 'mantle' | 'mantle-sepolia';
+
+/**
+ * Custom network configuration
+ */
+export interface CustomNetwork {
+  rpcUrl: string;
+  chainId: number;
+  name?: string;
+  explorerUrl?: string;
+}
+
+/**
+ * Network configuration
+ */
+export interface NetworkConfig {
+  name: string;
+  chainId: number;
+  rpcUrl: string;
+  explorerUrl: string;
+  contracts?: {
+    factory?: string;
+  };
+}
+
+/*//////////////////////////////////////////////////////////////
+                    ACCREDITATION TYPES
+//////////////////////////////////////////////////////////////*/
+
+/**
+ * Accreditation tiers matching the smart contract enum
+ */
+export enum AccreditationTier {
+  None = 0,
+  Retail = 1,
+  Accredited = 2,
+  Institutional = 3,
+}
+
+/*//////////////////////////////////////////////////////////////
+                    TRANSACTION TYPES
+//////////////////////////////////////////////////////////////*/
+
+/**
+ * Parsed event from a transaction
+ */
+export interface ParsedEvent {
+  name: string;
+  args: Record<string, unknown>;
+  address: string;
+  blockNumber: number;
+  transactionHash: string;
+  logIndex: number;
+}
+
+/**
+ * Result of a transaction
+ */
+export interface TransactionResult {
+  hash: string;
+  blockNumber: number;
+  gasUsed: bigint;
+  status: 'success' | 'failed';
+  events: ParsedEvent[];
+  receipt: TransactionReceipt;
+}
+
+/**
+ * Options for transaction execution
+ */
+export interface TransactionOptions {
+  gasLimit?: bigint;
+  maxFeePerGas?: bigint;
+  maxPriorityFeePerGas?: bigint;
+  nonce?: number;
+  retries?: number;
+  retryDelay?: number;
+}
+
+/*//////////////////////////////////////////////////////////////
+                    COMPLIANCE TYPES
+//////////////////////////////////////////////////////////////*/
+
+/**
+ * Available compliance rule types
+ */
+export type ComplianceRule =
+  | 'accredited-investor'
+  | 'transfer-limit-24h'
+  | 'transfer-limit-30d'
+  | 'holding-period'
+  | 'max-investors'
+  | 'geographic-restriction';
+
+/**
+ * Transfer eligibility check result
+ */
+export interface TransferEligibility {
+  eligible: boolean;
+  reason?: string;
+  checks: TransferCheck[];
+}
+
+/**
+ * Individual transfer check result
+ */
+export interface TransferCheck {
+  name: string;
+  passed: boolean;
+  details?: string;
+}
+
+/*//////////////////////////////////////////////////////////////
+                    DEPLOYMENT TYPES
+//////////////////////////////////////////////////////////////*/
+
+/**
+ * Configuration for deploying a new RWA system
+ */
+export interface DeploymentConfig {
+  tokenName: string;
+  tokenSymbol: string;
+  initialSupply: string;
+  complianceModules?: string[];
+  yieldClaimWindowDays?: number;
+  vaultSigners: string[];
+  vaultThreshold: number;
+  vaultWithdrawalThreshold?: string;
+}
+
+/**
+ * Addresses of deployed contracts
+ */
+export interface DeployedContracts {
+  token: string;
+  vault: string;
+  yieldDistributor: string;
+  kycRegistry: string;
+}
+
+/*//////////////////////////////////////////////////////////////
+                    TOKEN TYPES
+//////////////////////////////////////////////////////////////*/
+
+/**
+ * Configuration for deploying a token
+ */
+export interface TokenDeployConfig {
+  name: string;
+  symbol: string;
+  totalSupply: string;
+  complianceRules?: ComplianceRule[];
+  kycRegistryAddress?: string;
+}
+
+/**
+ * Token information
+ */
+export interface TokenInfo {
+  address: string;
+  name: string;
+  symbol: string;
+  decimals: number;
+  totalSupply: bigint;
+  paused: boolean;
+}
+
+/*//////////////////////////////////////////////////////////////
+                    KYC TYPES
+//////////////////////////////////////////////////////////////*/
+
+/**
+ * Investor data from the KYC registry
+ */
+export interface InvestorData {
+  verified: boolean;
+  tier: AccreditationTier;
+  expiry: Date;
+  identityHash: string;
+}
+
+/**
+ * Verification session for KYC flow
+ */
+export interface VerificationSession {
+  sessionId: string;
+  provider: string;
+  status: 'pending' | 'in_progress' | 'completed' | 'failed';
+  redirectUrl?: string;
+}
+
+/**
+ * Result of a KYC verification
+ */
+export interface VerificationResult {
+  verified: boolean;
+  tier: AccreditationTier;
+  identityHash: string;
+  expiryDate: Date;
+  rawData?: unknown;
+}
+
+/*//////////////////////////////////////////////////////////////
+                    YIELD TYPES
+//////////////////////////////////////////////////////////////*/
+
+/**
+ * Configuration for creating a distribution
+ */
+export interface DistributionConfig {
+  tokenAddress: string;
+  paymentToken: string;
+  totalAmount: string;
+  snapshotDate?: Date;
+  claimWindowDays?: number;
+}
+
+/**
+ * Preview of a distribution
+ */
+export interface DistributionPreview {
+  totalHolders: number;
+  totalSupplyAtSnapshot: bigint;
+  distributions: HolderDistribution[];
+}
+
+/**
+ * Distribution amount for a single holder
+ */
+export interface HolderDistribution {
+  address: string;
+  balance: bigint;
+  yieldAmount: bigint;
+  percentage: number;
+}
+
+/**
+ * Distribution information
+ */
+export interface Distribution {
+  id: number;
+  paymentToken: string;
+  totalAmount: bigint;
+  snapshotId: bigint;
+  claimDeadline: Date;
+  claimedAmount: bigint;
+}
+
+/**
+ * Pending claim for an account
+ */
+export interface PendingClaim {
+  distributionId: number;
+  amount: bigint;
+  paymentToken: string;
+  deadline: Date;
+}
+
+/*//////////////////////////////////////////////////////////////
+                    VAULT TYPES
+//////////////////////////////////////////////////////////////*/
+
+/**
+ * Withdrawal proposal
+ */
+export interface WithdrawalProposal {
+  id: number;
+  token: string;
+  amount: bigint;
+  recipient: string;
+  approvalCount: number;
+  executed: boolean;
+  approvers: string[];
+}
+
+/**
+ * Vault status information
+ */
+export interface VaultStatus {
+  isEmergency: boolean;
+  collateralizationRatio: number;
+  backingVerified: boolean;
+}
+
+/*//////////////////////////////////////////////////////////////
+                    COMPLIANCE REPORT TYPES
+//////////////////////////////////////////////////////////////*/
+
+/**
+ * Compliance report for regulatory purposes
+ */
+export interface ComplianceReport {
+  generatedAt: Date;
+  tokenAddress: string;
+  totalHolders: number;
+  verifiedHolders: number;
+  accreditedHolders: number;
+  transfersBlocked: number;
+  complianceScore: number;
+}
+
+/**
+ * Filing data for regulatory submissions
+ */
+export interface FilingData {
+  filingType: string;
+  tokenAddress: string;
+  reportingPeriod: {
+    start: Date;
+    end: Date;
+  };
+  data: Record<string, unknown>;
+}

package/src/utils/index.ts

@@ -0,0 +1,240 @@
+/**
+ * Utility functions for the Mantle RWA SDK
+ */
+
+import { ethers, type TransactionReceipt, type Interface } from 'ethers';
+import type { ParsedEvent, TransactionResult } from '../types';
+import { NetworkError, ErrorCode, parseNetworkError } from '../errors';
+import { DEFAULTS } from '../constants';
+
+/**
+ * Validate an Ethereum address
+ */
+export function isValidAddress(address: string): boolean {
+    try {
+        return ethers.isAddress(address);
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Validate and normalize an Ethereum address
+ */
+export function normalizeAddress(address: string): string {
+    if (!isValidAddress(address)) {
+        throw new Error(`Invalid address: ${address}`);
+    }
+    return ethers.getAddress(address);
+}
+
+/**
+ * Parse a string amount to bigint with decimals
+ */
+export function parseAmount(amount: string, decimals: number = 18): bigint {
+    return ethers.parseUnits(amount, decimals);
+}
+
+/**
+ * Format a bigint amount to string with decimals
+ */
+export function formatAmount(amount: bigint, decimals: number = 18): string {
+    return ethers.formatUnits(amount, decimals);
+}
+
+/**
+ * Parse events from a transaction receipt
+ */
+export function parseEvents(
+    receipt: TransactionReceipt,
+    contractInterface: Interface
+): ParsedEvent[] {
+    const events: ParsedEvent[] = [];
+
+    for (const log of receipt.logs) {
+        try {
+            const parsed = contractInterface.parseLog({
+                topics: log.topics as string[],
+                data: log.data,
+            });
+
+            if (parsed) {
+                const args: Record<string, unknown> = {};
+                for (const [key, value] of Object.entries(parsed.args)) {
+                    // Skip numeric indices
+                    if (!/^\d+$/.test(key)) {
+                        args[key] = value;
+                    }
+                }
+
+                events.push({
+                    name: parsed.name,
+                    args,
+                    address: log.address,
+                    blockNumber: log.blockNumber,
+                    transactionHash: log.transactionHash,
+                    logIndex: log.index,
+                });
+            }
+        } catch {
+            // Skip logs that don't match the interface
+        }
+    }
+
+    return events;
+}
+
+/**
+ * Create a transaction result from a receipt
+ */
+export function createTransactionResult(
+    receipt: TransactionReceipt,
+    events: ParsedEvent[]
+): TransactionResult {
+    return {
+        hash: receipt.hash,
+        blockNumber: receipt.blockNumber,
+        gasUsed: receipt.gasUsed,
+        status: receipt.status === 1 ? 'success' : 'failed',
+        events,
+        receipt,
+    };
+}
+
+/**
+ * Sleep for a specified duration
+ */
+export function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Retry a function with exponential backoff
+ */
+export async function retry<T>(
+    fn: () => Promise<T>,
+    options: {
+        retries?: number;
+        delay?: number;
+        onRetry?: (error: unknown, attempt: number) => void;
+    } = {}
+): Promise<T> {
+    const { retries = DEFAULTS.TRANSACTION_RETRIES, delay = DEFAULTS.RETRY_DELAY_MS, onRetry } = options;
+
+    let lastError: unknown;
+
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            return await fn();
+        } catch (error) {
+            lastError = error;
+
+            // Check if error is retryable
+            const networkError = parseNetworkError(error);
+            if (!networkError.retryable) {
+                throw error;
+            }
+
+            if (attempt < retries) {
+                onRetry?.(error, attempt + 1);
+                await sleep(delay * Math.pow(2, attempt)); // Exponential backoff
+            }
+        }
+    }
+
+    throw lastError;
+}
+
+/**
+ * Estimate gas with buffer
+ */
+export async function estimateGasWithBuffer(
+    estimateFn: () => Promise<bigint>,
+    bufferPercent: number = DEFAULTS.GAS_BUFFER_PERCENT
+): Promise<bigint> {
+    const estimate = await estimateFn();
+    const buffer = (estimate * BigInt(bufferPercent)) / 100n;
+    return estimate + buffer;
+}
+
+/**
+ * Generate a keccak256 hash of identity data
+ */
+export function hashIdentityData(data: {
+    firstName?: string;
+    lastName?: string;
+    dateOfBirth?: string;
+    documentNumber?: string;
+    country?: string;
+}): string {
+    const normalized = JSON.stringify({
+        firstName: data.firstName?.toLowerCase().trim(),
+        lastName: data.lastName?.toLowerCase().trim(),
+        dateOfBirth: data.dateOfBirth,
+        documentNumber: data.documentNumber?.toUpperCase().trim(),
+        country: data.country?.toUpperCase().trim(),
+    });
+    return ethers.keccak256(ethers.toUtf8Bytes(normalized));
+}
+
+/**
+ * Convert a timestamp to a Date object
+ */
+export function timestampToDate(timestamp: bigint | number): Date {
+    const ts = typeof timestamp === 'bigint' ? Number(timestamp) : timestamp;
+    return new Date(ts * 1000);
+}
+
+/**
+ * Convert a Date to a Unix timestamp
+ */
+export function dateToTimestamp(date: Date): number {
+    return Math.floor(date.getTime() / 1000);
+}
+
+/**
+ * Check if a timestamp is expired
+ */
+export function isExpired(timestamp: bigint | number): boolean {
+    const now = Math.floor(Date.now() / 1000);
+    const ts = typeof timestamp === 'bigint' ? Number(timestamp) : timestamp;
+    return ts < now;
+}
+
+/**
+ * Calculate percentage
+ */
+export function calculatePercentage(part: bigint, total: bigint): number {
+    if (total === 0n) return 0;
+    return Number((part * 10000n) / total) / 100;
+}
+
+/**
+ * Chunk an array into smaller arrays
+ */
+export function chunk<T>(array: T[], size: number): T[][] {
+    const chunks: T[][] = [];
+    for (let i = 0; i < array.length; i += size) {
+        chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+}
+
+/**
+ * Wait for a transaction to be mined
+ */
+export async function waitForTransaction(
+    provider: ethers.Provider,
+    hash: string,
+    confirmations: number = 1
+): Promise<TransactionReceipt> {
+    const receipt = await provider.waitForTransaction(hash, confirmations);
+    if (!receipt) {
+        throw new NetworkError(
+            ErrorCode.TIMEOUT,
+            `Transaction ${hash} was not mined`,
+            true
+        );
+    }
+    return receipt;
+}