atfi 1.0.0 → 1.1.1

package/README.md

@@ -1,6 +1,18 @@
 # ATFi SDK
 
-TypeScript SDK for interacting with ATFi commitment vaults on Base.
+TypeScript SDK for interacting with ATFi commitment vaults on Base. Stake tokens, verify attendance, earn rewards.
+
+[![npm version](https://img.shields.io/npm/v/atfi.svg)](https://www.npmjs.com/package/atfi)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Simulation-first** - Know results before wallet popup
+- **Transaction callbacks** - Loading states for UX
+- **Read-only mode** - Show data before wallet connection
+- **User-centric queries** - Dashboard, registered events, claimable rewards
+- **Real-time watching** - Subscribe to live vault events
+- **TypeScript** - Full type safety
 
 ## Installation
 

package/dist/index.d.mts

@@ -1,47 +1,58 @@
 import { Address, Hash, PublicClient, WalletClient } from 'viem';
 
-declare const CHAIN_ID = 8453;
+type Network = 'mainnet' | 'testnet';
+interface NetworkConfig {
+    chainId: number;
+    name: string;
+    factory: Address;
+    morphoVault: Address | null;
+    supportsYield: boolean;
+    tokens: {
+        USDC: TokenConfig;
+        IDRX?: TokenConfig;
+    };
+}
+interface TokenConfig {
+    address: Address;
+    decimals: number;
+    symbol: string;
+    supportsYield: boolean;
+}
+/**
+ * Network configurations for Base Mainnet and Sepolia Testnet
+ */
+declare const NETWORKS: Record<Network, NetworkConfig>;
+declare const CHAIN_ID: number;
 declare const CONTRACTS: {
-    readonly FACTORY: Address;
-    readonly MORPHO_VAULT: Address;
+    readonly FACTORY: `0x${string}`;
+    readonly MORPHO_VAULT: `0x${string}` | null;
 };
 declare const TOKENS: {
-    readonly USDC: {
-        readonly address: Address;
-        readonly decimals: 6;
-        readonly symbol: "USDC";
-        readonly supportsYield: true;
-    };
-    readonly IDRX: {
-        readonly address: Address;
-        readonly decimals: 2;
-        readonly symbol: "IDRX";
-        readonly supportsYield: false;
-    };
+    readonly USDC: TokenConfig;
+    readonly IDRX: TokenConfig;
 };
 type TokenSymbol = keyof typeof TOKENS;
+/**
+ * Get network configuration by network name or chain ID
+ */
+declare function getNetworkConfig(networkOrChainId: Network | number): NetworkConfig | null;
+/**
+ * Get token config by address (searches all networks)
+ */
 declare const getTokenByAddress: (address: Address) => {
     symbol: TokenSymbol;
     address: Address;
-    decimals: 6;
-    supportsYield: true;
-} | {
-    symbol: TokenSymbol;
-    address: Address;
-    decimals: 2;
-    supportsYield: false;
+    decimals: number;
+    supportsYield: boolean;
 } | null;
-declare const getTokenBySymbol: (symbol: TokenSymbol) => {
-    readonly address: Address;
-    readonly decimals: 6;
-    readonly symbol: "USDC";
-    readonly supportsYield: true;
-} | {
-    readonly address: Address;
-    readonly decimals: 2;
-    readonly symbol: "IDRX";
-    readonly supportsYield: false;
-};
+/**
+ * Get token config by symbol
+ */
+declare const getTokenBySymbol: (symbol: TokenSymbol) => TokenConfig;
+/**
+ * Check if yield is available on a network
+ */
+declare function isYieldSupported(networkOrChainId: Network | number): boolean;
 
 declare enum ParticipantStatus {
     NOT_STAKED = 0,
@@ -186,6 +197,8 @@ interface EventSummary {
     maxParticipants: number;
     currentParticipants: number;
     status: EventStatus;
+    tokenSymbol: string;
+    tokenDecimals: number;
 }
 interface ATFiSDKConfig {
     /** Custom factory address (optional, defaults to mainnet) */
@@ -344,6 +357,26 @@ interface VaultWatchCallbacks {
 /** Function to stop watching events */
 type UnwatchFn = () => void;
 
+/**
+ * Flexible public client type - accepts any viem-compatible client
+ * This allows SDK to work with different viem versions (e.g., from wagmi)
+ */
+type CompatiblePublicClient = PublicClient | {
+    readContract: any;
+    simulateContract: any;
+    waitForTransactionReceipt: any;
+    watchContractEvent: any;
+    estimateContractGas: any;
+};
+/**
+ * Flexible wallet client type - accepts any viem-compatible wallet
+ */
+type CompatibleWalletClient = WalletClient | {
+    account?: {
+        address: Address;
+    };
+    writeContract: any;
+} | null;
 /**
  * ATFi SDK - TypeScript SDK for interacting with ATFi Protocol
  *
@@ -357,7 +390,7 @@ type UnwatchFn = () => void;
  *
  * @example
  * ```ts
- * // Full mode (with wallet)
+ * // Full mode (with wallet) - works with wagmi clients directly!
  * const sdk = new ATFiSDK(publicClient, walletClient);
  *
  * // Read-only mode (no wallet needed)
@@ -378,7 +411,13 @@ declare class ATFiSDK {
     private walletClient;
     private factoryAddress;
     private _isReadOnly;
-    constructor(publicClient: PublicClient, walletClient?: WalletClient | null, config?: ATFiSDKConfig);
+    /**
+     * Create a new ATFi SDK instance
+     * @param publicClient - viem PublicClient (or wagmi's usePublicClient result)
+     * @param walletClient - viem WalletClient (or wagmi's useWalletClient result), optional for read-only
+     * @param config - Optional SDK configuration
+     */
+    constructor(publicClient: CompatiblePublicClient, walletClient?: CompatibleWalletClient, config?: ATFiSDKConfig);
     /**
      * Create a read-only SDK instance (no wallet required)
      * Use this to show event data before user connects wallet
@@ -390,7 +429,7 @@ declare class ATFiSDK {
      * const info = await sdk.getEventInfo(vaultAddress);
      * ```
      */
-    static readOnly(publicClient: PublicClient, config?: ATFiSDKConfig): ATFiSDK;
+    static readOnly(publicClient: CompatiblePublicClient, config?: ATFiSDKConfig): ATFiSDK;
     /** Check if SDK is in read-only mode */
     get isReadOnly(): boolean;
     /** Get connected wallet address (null if read-only) */
@@ -592,6 +631,136 @@ declare class ATFiError extends Error {
  */
 declare function parseContractError(error: unknown): ATFiError;
 
+/**
+ * Shorten an address for display
+ * @param address Full address
+ * @param chars Number of characters to show on each side (default 4)
+ * @returns Shortened address like "0x1234...5678"
+ *
+ * @example
+ * shortenAddress('0x1234567890abcdef1234567890abcdef12345678')
+ * // => "0x1234...5678"
+ */
+declare function shortenAddress(address: Address | string, chars?: number): string;
+/**
+ * Format amount for USD display
+ * @param amount Amount string or number
+ * @param decimals Decimal places (default 2)
+ * @returns Formatted string like "$10.50"
+ *
+ * @example
+ * formatUSD('1234.5')
+ * // => "$1,234.50"
+ */
+declare function formatUSD(amount: string | number, decimals?: number): string;
+/**
+ * Format token amount with symbol
+ * @param amount Amount string or number
+ * @param symbol Token symbol
+ * @param decimals Decimal places (default 2)
+ * @returns Formatted string like "10.50 USDC"
+ *
+ * @example
+ * formatTokenAmount('1234.567', 'USDC')
+ * // => "1,234.57 USDC"
+ */
+declare function formatTokenAmount(amount: string | number, symbol: string, decimals?: number): string;
+/**
+ * Format large numbers with abbreviations
+ * @param amount Amount to format
+ * @returns Abbreviated string like "1.2K", "3.4M"
+ *
+ * @example
+ * formatCompact(1234567)
+ * // => "1.2M"
+ */
+declare function formatCompact(amount: string | number): string;
+/**
+ * Format percentage
+ * @param value Value to format (e.g., 0.15 for 15%)
+ * @param decimals Decimal places (default 2)
+ * @returns Formatted percentage like "15.00%"
+ *
+ * @example
+ * formatPercent(0.1567)
+ * // => "15.67%"
+ */
+declare function formatPercent(value: number, decimals?: number): string;
+
+/**
+ * Hook to create ATFi SDK from wagmi clients
+ *
+ * @example
+ * ```tsx
+ * import { usePublicClient, useWalletClient } from 'wagmi';
+ * import { useATFiSDK } from 'atfi/react';
+ *
+ * function MyComponent() {
+ *   const publicClient = usePublicClient();
+ *   const { data: walletClient } = useWalletClient();
+ *   const { sdk, isReadOnly } = useATFiSDK(publicClient, walletClient);
+ *
+ *   // Use sdk...
+ * }
+ * ```
+ */
+declare function useATFiSDK(publicClient: any, walletClient?: any, config?: ATFiSDKConfig): {
+    sdk: ATFiSDK | null;
+    isReadOnly: boolean;
+};
+
+interface UseEventInfoResult {
+    data: EventInfo | null;
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+/**
+ * Hook to fetch and cache event info
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, error, refetch } = useEventInfo(sdk, vaultAddress);
+ *
+ * if (isLoading) return <Spinner />;
+ * if (error) return <Error message={error.message} />;
+ *
+ * return <EventCard event={data} />;
+ * ```
+ */
+declare function useEventInfo(sdk: ATFiSDK | null, vaultAddress: Address | string | undefined): UseEventInfoResult;
+
+interface WatchState {
+    participantCount: number;
+    verifiedCount: number;
+    isSettled: boolean;
+    lastClaim: {
+        participant: Address;
+        amount: string;
+    } | null;
+}
+interface UseWatchVaultResult extends WatchState {
+    isWatching: boolean;
+}
+/**
+ * Hook to watch vault events in real-time
+ * Automatically cleans up subscriptions on unmount
+ *
+ * @example
+ * ```tsx
+ * const { participantCount, verifiedCount, isSettled, isWatching } = useWatchVault(sdk, vaultAddress);
+ *
+ * return (
+ *   <div>
+ *     <p>Participants: {participantCount}</p>
+ *     <p>Verified: {verifiedCount}</p>
+ *     {isSettled && <ClaimButton />}
+ *   </div>
+ * );
+ * ```
+ */
+declare function useWatchVault(sdk: ATFiSDK | null, vaultAddress: Address | string | undefined): UseWatchVaultResult;
+
 declare const FactoryATFiABI: readonly [{
     readonly inputs: readonly [{
         readonly internalType: "address";
@@ -1754,4 +1923,4 @@ declare const ERC20ABI: readonly [{
     readonly stateMutability: "view";
 }];
 
-export { ATFiError, ATFiErrorCode, ATFiSDK, type ATFiSDKConfig, type ActionResult, CHAIN_ID, CONTRACTS, type ClaimAction, type ClaimParams, type ClaimResult, type CreateEventAction, type CreateEventParams, type CreateEventResult, ERC20ABI, type EventInfo, EventStatus, type EventSummary, FactoryATFiABI, type ParticipantInfo, ParticipantStatus, type RegisterAction, type RegisterParams, type RegisterResult, type SettleAction, type SettleEventParams, type SettleEventResult, type SimulateClaimResult, type SimulateCreateEventResult, type SimulateRegisterResult, type SimulateSettleResult, type SimulateStartEventResult, type SimulateVerifyResult, type SimulationBase, type StartEventAction, type StartEventParams, type StartEventResult, TOKENS, type TokenSymbol, type TransactionCallbacks, type UnwatchFn, type UserEventInfo, VaultATFiABI, type VaultWatchCallbacks, type VerifyAction, type VerifyParticipantParams, type VerifyParticipantResult, formatAmount, fromTokenUnits, getTokenByAddress, getTokenBySymbol, parseContractError, toTokenUnits };
+export { ATFiError, ATFiErrorCode, ATFiSDK, type ATFiSDKConfig, type ActionResult, CHAIN_ID, CONTRACTS, type ClaimAction, type ClaimParams, type ClaimResult, type CreateEventAction, type CreateEventParams, type CreateEventResult, ERC20ABI, type EventInfo, EventStatus, type EventSummary, FactoryATFiABI, NETWORKS, type Network, type NetworkConfig, type ParticipantInfo, ParticipantStatus, type RegisterAction, type RegisterParams, type RegisterResult, type SettleAction, type SettleEventParams, type SettleEventResult, type SimulateClaimResult, type SimulateCreateEventResult, type SimulateRegisterResult, type SimulateSettleResult, type SimulateStartEventResult, type SimulateVerifyResult, type SimulationBase, type StartEventAction, type StartEventParams, type StartEventResult, TOKENS, type TokenConfig, type TokenSymbol, type TransactionCallbacks, type UnwatchFn, type UserEventInfo, VaultATFiABI, type VaultWatchCallbacks, type VerifyAction, type VerifyParticipantParams, type VerifyParticipantResult, formatAmount, formatCompact, formatPercent, formatTokenAmount, formatUSD, fromTokenUnits, getNetworkConfig, getTokenByAddress, getTokenBySymbol, isYieldSupported, parseContractError, shortenAddress, toTokenUnits, useATFiSDK, useEventInfo, useWatchVault };

package/dist/index.d.ts

@@ -1,47 +1,58 @@
 import { Address, Hash, PublicClient, WalletClient } from 'viem';
 
-declare const CHAIN_ID = 8453;
+type Network = 'mainnet' | 'testnet';
+interface NetworkConfig {
+    chainId: number;
+    name: string;
+    factory: Address;
+    morphoVault: Address | null;
+    supportsYield: boolean;
+    tokens: {
+        USDC: TokenConfig;
+        IDRX?: TokenConfig;
+    };
+}
+interface TokenConfig {
+    address: Address;
+    decimals: number;
+    symbol: string;
+    supportsYield: boolean;
+}
+/**
+ * Network configurations for Base Mainnet and Sepolia Testnet
+ */
+declare const NETWORKS: Record<Network, NetworkConfig>;
+declare const CHAIN_ID: number;
 declare const CONTRACTS: {
-    readonly FACTORY: Address;
-    readonly MORPHO_VAULT: Address;
+    readonly FACTORY: `0x${string}`;
+    readonly MORPHO_VAULT: `0x${string}` | null;
 };
 declare const TOKENS: {
-    readonly USDC: {
-        readonly address: Address;
-        readonly decimals: 6;
-        readonly symbol: "USDC";
-        readonly supportsYield: true;
-    };
-    readonly IDRX: {
-        readonly address: Address;
-        readonly decimals: 2;
-        readonly symbol: "IDRX";
-        readonly supportsYield: false;
-    };
+    readonly USDC: TokenConfig;
+    readonly IDRX: TokenConfig;
 };
 type TokenSymbol = keyof typeof TOKENS;
+/**
+ * Get network configuration by network name or chain ID
+ */
+declare function getNetworkConfig(networkOrChainId: Network | number): NetworkConfig | null;
+/**
+ * Get token config by address (searches all networks)
+ */
 declare const getTokenByAddress: (address: Address) => {
     symbol: TokenSymbol;
     address: Address;
-    decimals: 6;
-    supportsYield: true;
-} | {
-    symbol: TokenSymbol;
-    address: Address;
-    decimals: 2;
-    supportsYield: false;
+    decimals: number;
+    supportsYield: boolean;
 } | null;
-declare const getTokenBySymbol: (symbol: TokenSymbol) => {
-    readonly address: Address;
-    readonly decimals: 6;
-    readonly symbol: "USDC";
-    readonly supportsYield: true;
-} | {
-    readonly address: Address;
-    readonly decimals: 2;
-    readonly symbol: "IDRX";
-    readonly supportsYield: false;
-};
+/**
+ * Get token config by symbol
+ */
+declare const getTokenBySymbol: (symbol: TokenSymbol) => TokenConfig;
+/**
+ * Check if yield is available on a network
+ */
+declare function isYieldSupported(networkOrChainId: Network | number): boolean;
 
 declare enum ParticipantStatus {
     NOT_STAKED = 0,
@@ -186,6 +197,8 @@ interface EventSummary {
     maxParticipants: number;
     currentParticipants: number;
     status: EventStatus;
+    tokenSymbol: string;
+    tokenDecimals: number;
 }
 interface ATFiSDKConfig {
     /** Custom factory address (optional, defaults to mainnet) */
@@ -344,6 +357,26 @@ interface VaultWatchCallbacks {
 /** Function to stop watching events */
 type UnwatchFn = () => void;
 
+/**
+ * Flexible public client type - accepts any viem-compatible client
+ * This allows SDK to work with different viem versions (e.g., from wagmi)
+ */
+type CompatiblePublicClient = PublicClient | {
+    readContract: any;
+    simulateContract: any;
+    waitForTransactionReceipt: any;
+    watchContractEvent: any;
+    estimateContractGas: any;
+};
+/**
+ * Flexible wallet client type - accepts any viem-compatible wallet
+ */
+type CompatibleWalletClient = WalletClient | {
+    account?: {
+        address: Address;
+    };
+    writeContract: any;
+} | null;
 /**
  * ATFi SDK - TypeScript SDK for interacting with ATFi Protocol
  *
@@ -357,7 +390,7 @@ type UnwatchFn = () => void;
  *
  * @example
  * ```ts
- * // Full mode (with wallet)
+ * // Full mode (with wallet) - works with wagmi clients directly!
  * const sdk = new ATFiSDK(publicClient, walletClient);
  *
  * // Read-only mode (no wallet needed)
@@ -378,7 +411,13 @@ declare class ATFiSDK {
     private walletClient;
     private factoryAddress;
     private _isReadOnly;
-    constructor(publicClient: PublicClient, walletClient?: WalletClient | null, config?: ATFiSDKConfig);
+    /**
+     * Create a new ATFi SDK instance
+     * @param publicClient - viem PublicClient (or wagmi's usePublicClient result)
+     * @param walletClient - viem WalletClient (or wagmi's useWalletClient result), optional for read-only
+     * @param config - Optional SDK configuration
+     */
+    constructor(publicClient: CompatiblePublicClient, walletClient?: CompatibleWalletClient, config?: ATFiSDKConfig);
     /**
      * Create a read-only SDK instance (no wallet required)
      * Use this to show event data before user connects wallet
@@ -390,7 +429,7 @@ declare class ATFiSDK {
      * const info = await sdk.getEventInfo(vaultAddress);
      * ```
      */
-    static readOnly(publicClient: PublicClient, config?: ATFiSDKConfig): ATFiSDK;
+    static readOnly(publicClient: CompatiblePublicClient, config?: ATFiSDKConfig): ATFiSDK;
     /** Check if SDK is in read-only mode */
     get isReadOnly(): boolean;
     /** Get connected wallet address (null if read-only) */
@@ -592,6 +631,136 @@ declare class ATFiError extends Error {
  */
 declare function parseContractError(error: unknown): ATFiError;
 
+/**
+ * Shorten an address for display
+ * @param address Full address
+ * @param chars Number of characters to show on each side (default 4)
+ * @returns Shortened address like "0x1234...5678"
+ *
+ * @example
+ * shortenAddress('0x1234567890abcdef1234567890abcdef12345678')
+ * // => "0x1234...5678"
+ */
+declare function shortenAddress(address: Address | string, chars?: number): string;
+/**
+ * Format amount for USD display
+ * @param amount Amount string or number
+ * @param decimals Decimal places (default 2)
+ * @returns Formatted string like "$10.50"
+ *
+ * @example
+ * formatUSD('1234.5')
+ * // => "$1,234.50"
+ */
+declare function formatUSD(amount: string | number, decimals?: number): string;
+/**
+ * Format token amount with symbol
+ * @param amount Amount string or number
+ * @param symbol Token symbol
+ * @param decimals Decimal places (default 2)
+ * @returns Formatted string like "10.50 USDC"
+ *
+ * @example
+ * formatTokenAmount('1234.567', 'USDC')
+ * // => "1,234.57 USDC"
+ */
+declare function formatTokenAmount(amount: string | number, symbol: string, decimals?: number): string;
+/**
+ * Format large numbers with abbreviations
+ * @param amount Amount to format
+ * @returns Abbreviated string like "1.2K", "3.4M"
+ *
+ * @example
+ * formatCompact(1234567)
+ * // => "1.2M"
+ */
+declare function formatCompact(amount: string | number): string;
+/**
+ * Format percentage
+ * @param value Value to format (e.g., 0.15 for 15%)
+ * @param decimals Decimal places (default 2)
+ * @returns Formatted percentage like "15.00%"
+ *
+ * @example
+ * formatPercent(0.1567)
+ * // => "15.67%"
+ */
+declare function formatPercent(value: number, decimals?: number): string;
+
+/**
+ * Hook to create ATFi SDK from wagmi clients
+ *
+ * @example
+ * ```tsx
+ * import { usePublicClient, useWalletClient } from 'wagmi';
+ * import { useATFiSDK } from 'atfi/react';
+ *
+ * function MyComponent() {
+ *   const publicClient = usePublicClient();
+ *   const { data: walletClient } = useWalletClient();
+ *   const { sdk, isReadOnly } = useATFiSDK(publicClient, walletClient);
+ *
+ *   // Use sdk...
+ * }
+ * ```
+ */
+declare function useATFiSDK(publicClient: any, walletClient?: any, config?: ATFiSDKConfig): {
+    sdk: ATFiSDK | null;
+    isReadOnly: boolean;
+};
+
+interface UseEventInfoResult {
+    data: EventInfo | null;
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+/**
+ * Hook to fetch and cache event info
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, error, refetch } = useEventInfo(sdk, vaultAddress);
+ *
+ * if (isLoading) return <Spinner />;
+ * if (error) return <Error message={error.message} />;
+ *
+ * return <EventCard event={data} />;
+ * ```
+ */
+declare function useEventInfo(sdk: ATFiSDK | null, vaultAddress: Address | string | undefined): UseEventInfoResult;
+
+interface WatchState {
+    participantCount: number;
+    verifiedCount: number;
+    isSettled: boolean;
+    lastClaim: {
+        participant: Address;
+        amount: string;
+    } | null;
+}
+interface UseWatchVaultResult extends WatchState {
+    isWatching: boolean;
+}
+/**
+ * Hook to watch vault events in real-time
+ * Automatically cleans up subscriptions on unmount
+ *
+ * @example
+ * ```tsx
+ * const { participantCount, verifiedCount, isSettled, isWatching } = useWatchVault(sdk, vaultAddress);
+ *
+ * return (
+ *   <div>
+ *     <p>Participants: {participantCount}</p>
+ *     <p>Verified: {verifiedCount}</p>
+ *     {isSettled && <ClaimButton />}
+ *   </div>
+ * );
+ * ```
+ */
+declare function useWatchVault(sdk: ATFiSDK | null, vaultAddress: Address | string | undefined): UseWatchVaultResult;
+
 declare const FactoryATFiABI: readonly [{
     readonly inputs: readonly [{
         readonly internalType: "address";
@@ -1754,4 +1923,4 @@ declare const ERC20ABI: readonly [{
     readonly stateMutability: "view";
 }];
 
-export { ATFiError, ATFiErrorCode, ATFiSDK, type ATFiSDKConfig, type ActionResult, CHAIN_ID, CONTRACTS, type ClaimAction, type ClaimParams, type ClaimResult, type CreateEventAction, type CreateEventParams, type CreateEventResult, ERC20ABI, type EventInfo, EventStatus, type EventSummary, FactoryATFiABI, type ParticipantInfo, ParticipantStatus, type RegisterAction, type RegisterParams, type RegisterResult, type SettleAction, type SettleEventParams, type SettleEventResult, type SimulateClaimResult, type SimulateCreateEventResult, type SimulateRegisterResult, type SimulateSettleResult, type SimulateStartEventResult, type SimulateVerifyResult, type SimulationBase, type StartEventAction, type StartEventParams, type StartEventResult, TOKENS, type TokenSymbol, type TransactionCallbacks, type UnwatchFn, type UserEventInfo, VaultATFiABI, type VaultWatchCallbacks, type VerifyAction, type VerifyParticipantParams, type VerifyParticipantResult, formatAmount, fromTokenUnits, getTokenByAddress, getTokenBySymbol, parseContractError, toTokenUnits };
+export { ATFiError, ATFiErrorCode, ATFiSDK, type ATFiSDKConfig, type ActionResult, CHAIN_ID, CONTRACTS, type ClaimAction, type ClaimParams, type ClaimResult, type CreateEventAction, type CreateEventParams, type CreateEventResult, ERC20ABI, type EventInfo, EventStatus, type EventSummary, FactoryATFiABI, NETWORKS, type Network, type NetworkConfig, type ParticipantInfo, ParticipantStatus, type RegisterAction, type RegisterParams, type RegisterResult, type SettleAction, type SettleEventParams, type SettleEventResult, type SimulateClaimResult, type SimulateCreateEventResult, type SimulateRegisterResult, type SimulateSettleResult, type SimulateStartEventResult, type SimulateVerifyResult, type SimulationBase, type StartEventAction, type StartEventParams, type StartEventResult, TOKENS, type TokenConfig, type TokenSymbol, type TransactionCallbacks, type UnwatchFn, type UserEventInfo, VaultATFiABI, type VaultWatchCallbacks, type VerifyAction, type VerifyParticipantParams, type VerifyParticipantResult, formatAmount, formatCompact, formatPercent, formatTokenAmount, formatUSD, fromTokenUnits, getNetworkConfig, getTokenByAddress, getTokenBySymbol, isYieldSupported, parseContractError, shortenAddress, toTokenUnits, useATFiSDK, useEventInfo, useWatchVault };

package/dist/index.js

@@ -28,15 +28,26 @@ __export(index_exports, {
   ERC20ABI: () => ERC20ABI,
   EventStatus: () => EventStatus,
   FactoryATFiABI: () => FactoryATFiABI,
+  NETWORKS: () => NETWORKS,
   ParticipantStatus: () => ParticipantStatus,
   TOKENS: () => TOKENS,
   VaultATFiABI: () => VaultATFiABI,
   formatAmount: () => formatAmount,
+  formatCompact: () => formatCompact,
+  formatPercent: () => formatPercent,
+  formatTokenAmount: () => formatTokenAmount,
+  formatUSD: () => formatUSD,
   fromTokenUnits: () => fromTokenUnits,
+  getNetworkConfig: () => getNetworkConfig,
   getTokenByAddress: () => getTokenByAddress,
   getTokenBySymbol: () => getTokenBySymbol,
+  isYieldSupported: () => isYieldSupported,
   parseContractError: () => parseContractError,
-  toTokenUnits: () => toTokenUnits
+  shortenAddress: () => shortenAddress,
+  toTokenUnits: () => toTokenUnits,
+  useATFiSDK: () => useATFiSDK,
+  useEventInfo: () => useEventInfo,
+  useWatchVault: () => useWatchVault
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -95,30 +106,74 @@ var ERC20ABI = [
 ];
 
 // src/constants/addresses.ts
-var CHAIN_ID = 8453;
+var NETWORKS = {
+  mainnet: {
+    chainId: 8453,
+    name: "Base",
+    factory: "0x0be05a5fa7116c1b33f2b0036eb0d9690db9075f",
+    morphoVault: "0x050cE30b927Da55177A4914EC73480238BAD56f0",
+    supportsYield: true,
+    tokens: {
+      USDC: {
+        address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        decimals: 6,
+        symbol: "USDC",
+        supportsYield: true
+      },
+      IDRX: {
+        address: "0x18Bc5bcC660cf2B9cE3cd51a404aFe1a0cBD3C22",
+        decimals: 2,
+        symbol: "IDRX",
+        supportsYield: false
+      }
+    }
+  },
+  testnet: {
+    chainId: 84532,
+    // Base Sepolia
+    name: "Base Sepolia",
+    factory: "0xf1EA206029549A8c4e2EB960F7ac43A98E922A49",
+    morphoVault: null,
+    // No Morpho on testnet
+    supportsYield: false,
+    tokens: {
+      USDC: {
+        address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+        // Base Sepolia USDC
+        decimals: 6,
+        symbol: "USDC",
+        supportsYield: false
+      }
+    }
+  }
+};
+var CHAIN_ID = NETWORKS.mainnet.chainId;
 var CONTRACTS = {
-  FACTORY: "0x0be05a5fa7116c1b33f2b0036eb0d9690db9075f",
-  MORPHO_VAULT: "0x050cE30b927Da55177A4914EC73480238BAD56f0"
+  FACTORY: NETWORKS.mainnet.factory,
+  MORPHO_VAULT: NETWORKS.mainnet.morphoVault
 };
 var TOKENS = {
-  USDC: {
-    address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
-    decimals: 6,
-    symbol: "USDC",
-    supportsYield: true
-  },
-  IDRX: {
-    address: "0x18Bc5bcC660cf2B9cE3cd51a404aFe1a0cBD3C22",
-    decimals: 2,
-    symbol: "IDRX",
-    supportsYield: false
-  }
+  USDC: NETWORKS.mainnet.tokens.USDC,
+  IDRX: NETWORKS.mainnet.tokens.IDRX
 };
+function getNetworkConfig(networkOrChainId) {
+  if (typeof networkOrChainId === "string") {
+    return NETWORKS[networkOrChainId] || null;
+  }
+  for (const config of Object.values(NETWORKS)) {
+    if (config.chainId === networkOrChainId) {
+      return config;
+    }
+  }
+  return null;
+}
 var getTokenByAddress = (address) => {
   const normalizedAddress = address.toLowerCase();
-  for (const [sym, token] of Object.entries(TOKENS)) {
-    if (token.address.toLowerCase() === normalizedAddress) {
-      return { ...token, symbol: sym };
+  for (const network of Object.values(NETWORKS)) {
+    for (const [sym, token] of Object.entries(network.tokens)) {
+      if (token.address.toLowerCase() === normalizedAddress) {
+        return { ...token, symbol: sym };
+      }
     }
   }
   return null;
@@ -126,6 +181,10 @@ var getTokenByAddress = (address) => {
 var getTokenBySymbol = (symbol) => {
   return TOKENS[symbol];
 };
+function isYieldSupported(networkOrChainId) {
+  const config = getNetworkConfig(networkOrChainId);
+  return config?.supportsYield ?? false;
+}
 
 // src/utils/decimals.ts
 var import_viem = require("viem");
@@ -241,6 +300,12 @@ var EventStatus = /* @__PURE__ */ ((EventStatus2) => {
 
 // src/ATFiSDK.ts
 var ATFiSDK = class _ATFiSDK {
+  /**
+   * Create a new ATFi SDK instance
+   * @param publicClient - viem PublicClient (or wagmi's usePublicClient result)
+   * @param walletClient - viem WalletClient (or wagmi's useWalletClient result), optional for read-only
+   * @param config - Optional SDK configuration
+   */
   constructor(publicClient, walletClient, config) {
     this.publicClient = publicClient;
     this.walletClient = walletClient ? walletClient : null;
@@ -822,7 +887,9 @@ var ATFiSDK = class _ATFiSDK {
         stakeAmount: info.stakeAmount,
         maxParticipants: info.maxParticipants,
         currentParticipants: info.currentParticipants,
-        status
+        status,
+        tokenSymbol: info.tokenSymbol,
+        tokenDecimals: info.tokenDecimals
       };
     });
   }
@@ -1388,6 +1455,150 @@ var ATFiSDK = class _ATFiSDK {
     return { txHash: hash, amountClaimed: fromTokenUnits(claimable, decimals) };
   }
 };
+
+// src/utils/formatting.ts
+function shortenAddress(address, chars = 4) {
+  if (!address) return "";
+  const start = address.slice(0, chars + 2);
+  const end = address.slice(-chars);
+  return `${start}...${end}`;
+}
+function formatUSD(amount, decimals = 2) {
+  const num = typeof amount === "string" ? parseFloat(amount) : amount;
+  if (isNaN(num)) return "$0.00";
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "USD",
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals
+  }).format(num);
+}
+function formatTokenAmount(amount, symbol, decimals = 2) {
+  const num = typeof amount === "string" ? parseFloat(amount) : amount;
+  if (isNaN(num)) return `0 ${symbol}`;
+  const formatted = new Intl.NumberFormat("en-US", {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals
+  }).format(num);
+  return `${formatted} ${symbol}`;
+}
+function formatCompact(amount) {
+  const num = typeof amount === "string" ? parseFloat(amount) : amount;
+  if (isNaN(num)) return "0";
+  return new Intl.NumberFormat("en-US", {
+    notation: "compact",
+    maximumFractionDigits: 1
+  }).format(num);
+}
+function formatPercent(value, decimals = 2) {
+  return `${(value * 100).toFixed(decimals)}%`;
+}
+
+// src/react/useATFiSDK.ts
+var import_react = require("react");
+function useATFiSDK(publicClient, walletClient, config) {
+  const sdk = (0, import_react.useMemo)(() => {
+    if (!publicClient) return null;
+    if (walletClient) {
+      return new ATFiSDK(publicClient, walletClient, config);
+    }
+    return ATFiSDK.readOnly(publicClient, config);
+  }, [publicClient, walletClient, config]);
+  return {
+    sdk,
+    isReadOnly: !walletClient
+  };
+}
+
+// src/react/useEventInfo.ts
+var import_react2 = require("react");
+function useEventInfo(sdk, vaultAddress) {
+  const [data, setData] = (0, import_react2.useState)(null);
+  const [isLoading, setIsLoading] = (0, import_react2.useState)(false);
+  const [error, setError] = (0, import_react2.useState)(null);
+  const fetchData = (0, import_react2.useCallback)(async () => {
+    if (!sdk || !vaultAddress) {
+      setData(null);
+      return;
+    }
+    setIsLoading(true);
+    setError(null);
+    try {
+      const info = await sdk.getEventInfo(vaultAddress);
+      setData(info);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error("Failed to fetch event info"));
+      setData(null);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [sdk, vaultAddress]);
+  (0, import_react2.useEffect)(() => {
+    fetchData();
+  }, [fetchData]);
+  return {
+    data,
+    isLoading,
+    error,
+    refetch: fetchData
+  };
+}
+
+// src/react/useWatchVault.ts
+var import_react3 = require("react");
+function useWatchVault(sdk, vaultAddress) {
+  const [state, setState] = (0, import_react3.useState)({
+    participantCount: 0,
+    verifiedCount: 0,
+    isSettled: false,
+    lastClaim: null
+  });
+  const [isWatching, setIsWatching] = (0, import_react3.useState)(false);
+  const unwatchRef = (0, import_react3.useRef)(null);
+  (0, import_react3.useEffect)(() => {
+    if (!sdk || !vaultAddress) {
+      setIsWatching(false);
+      return;
+    }
+    if (unwatchRef.current) {
+      unwatchRef.current();
+    }
+    try {
+      unwatchRef.current = sdk.watchVault(vaultAddress, {
+        onParticipantJoined: (_participant, totalParticipants) => {
+          setState((prev) => ({ ...prev, participantCount: totalParticipants }));
+        },
+        onParticipantVerified: (_participant, totalVerified) => {
+          setState((prev) => ({ ...prev, verifiedCount: totalVerified }));
+        },
+        onSettled: () => {
+          setState((prev) => ({ ...prev, isSettled: true }));
+        },
+        onClaimed: (participant, amount) => {
+          setState((prev) => ({ ...prev, lastClaim: { participant, amount } }));
+        },
+        onError: (error) => {
+          console.error("[useWatchVault]", error);
+        }
+      });
+      setIsWatching(true);
+    } catch (err) {
+      console.error("[useWatchVault] Failed to start watching:", err);
+      setIsWatching(false);
+    }
+    return () => {
+      if (unwatchRef.current) {
+        unwatchRef.current();
+        unwatchRef.current = null;
+      }
+      setIsWatching(false);
+    };
+  }, [sdk, vaultAddress]);
+  return {
+    ...state,
+    isWatching
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ATFiError,
@@ -1398,13 +1609,24 @@ var ATFiSDK = class _ATFiSDK {
   ERC20ABI,
   EventStatus,
   FactoryATFiABI,
+  NETWORKS,
   ParticipantStatus,
   TOKENS,
   VaultATFiABI,
   formatAmount,
+  formatCompact,
+  formatPercent,
+  formatTokenAmount,
+  formatUSD,
   fromTokenUnits,
+  getNetworkConfig,
   getTokenByAddress,
   getTokenBySymbol,
+  isYieldSupported,
   parseContractError,
-  toTokenUnits
+  shortenAddress,
+  toTokenUnits,
+  useATFiSDK,
+  useEventInfo,
+  useWatchVault
 });

package/dist/index.mjs

@@ -55,30 +55,74 @@ var ERC20ABI = [
 ];
 
 // src/constants/addresses.ts
-var CHAIN_ID = 8453;
+var NETWORKS = {
+  mainnet: {
+    chainId: 8453,
+    name: "Base",
+    factory: "0x0be05a5fa7116c1b33f2b0036eb0d9690db9075f",
+    morphoVault: "0x050cE30b927Da55177A4914EC73480238BAD56f0",
+    supportsYield: true,
+    tokens: {
+      USDC: {
+        address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        decimals: 6,
+        symbol: "USDC",
+        supportsYield: true
+      },
+      IDRX: {
+        address: "0x18Bc5bcC660cf2B9cE3cd51a404aFe1a0cBD3C22",
+        decimals: 2,
+        symbol: "IDRX",
+        supportsYield: false
+      }
+    }
+  },
+  testnet: {
+    chainId: 84532,
+    // Base Sepolia
+    name: "Base Sepolia",
+    factory: "0xf1EA206029549A8c4e2EB960F7ac43A98E922A49",
+    morphoVault: null,
+    // No Morpho on testnet
+    supportsYield: false,
+    tokens: {
+      USDC: {
+        address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+        // Base Sepolia USDC
+        decimals: 6,
+        symbol: "USDC",
+        supportsYield: false
+      }
+    }
+  }
+};
+var CHAIN_ID = NETWORKS.mainnet.chainId;
 var CONTRACTS = {
-  FACTORY: "0x0be05a5fa7116c1b33f2b0036eb0d9690db9075f",
-  MORPHO_VAULT: "0x050cE30b927Da55177A4914EC73480238BAD56f0"
+  FACTORY: NETWORKS.mainnet.factory,
+  MORPHO_VAULT: NETWORKS.mainnet.morphoVault
 };
 var TOKENS = {
-  USDC: {
-    address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
-    decimals: 6,
-    symbol: "USDC",
-    supportsYield: true
-  },
-  IDRX: {
-    address: "0x18Bc5bcC660cf2B9cE3cd51a404aFe1a0cBD3C22",
-    decimals: 2,
-    symbol: "IDRX",
-    supportsYield: false
-  }
+  USDC: NETWORKS.mainnet.tokens.USDC,
+  IDRX: NETWORKS.mainnet.tokens.IDRX
 };
+function getNetworkConfig(networkOrChainId) {
+  if (typeof networkOrChainId === "string") {
+    return NETWORKS[networkOrChainId] || null;
+  }
+  for (const config of Object.values(NETWORKS)) {
+    if (config.chainId === networkOrChainId) {
+      return config;
+    }
+  }
+  return null;
+}
 var getTokenByAddress = (address) => {
   const normalizedAddress = address.toLowerCase();
-  for (const [sym, token] of Object.entries(TOKENS)) {
-    if (token.address.toLowerCase() === normalizedAddress) {
-      return { ...token, symbol: sym };
+  for (const network of Object.values(NETWORKS)) {
+    for (const [sym, token] of Object.entries(network.tokens)) {
+      if (token.address.toLowerCase() === normalizedAddress) {
+        return { ...token, symbol: sym };
+      }
     }
   }
   return null;
@@ -86,6 +130,10 @@ var getTokenByAddress = (address) => {
 var getTokenBySymbol = (symbol) => {
   return TOKENS[symbol];
 };
+function isYieldSupported(networkOrChainId) {
+  const config = getNetworkConfig(networkOrChainId);
+  return config?.supportsYield ?? false;
+}
 
 // src/utils/decimals.ts
 import { parseUnits, formatUnits } from "viem";
@@ -201,6 +249,12 @@ var EventStatus = /* @__PURE__ */ ((EventStatus2) => {
 
 // src/ATFiSDK.ts
 var ATFiSDK = class _ATFiSDK {
+  /**
+   * Create a new ATFi SDK instance
+   * @param publicClient - viem PublicClient (or wagmi's usePublicClient result)
+   * @param walletClient - viem WalletClient (or wagmi's useWalletClient result), optional for read-only
+   * @param config - Optional SDK configuration
+   */
   constructor(publicClient, walletClient, config) {
     this.publicClient = publicClient;
     this.walletClient = walletClient ? walletClient : null;
@@ -782,7 +836,9 @@ var ATFiSDK = class _ATFiSDK {
         stakeAmount: info.stakeAmount,
         maxParticipants: info.maxParticipants,
         currentParticipants: info.currentParticipants,
-        status
+        status,
+        tokenSymbol: info.tokenSymbol,
+        tokenDecimals: info.tokenDecimals
       };
     });
   }
@@ -1348,6 +1404,150 @@ var ATFiSDK = class _ATFiSDK {
     return { txHash: hash, amountClaimed: fromTokenUnits(claimable, decimals) };
   }
 };
+
+// src/utils/formatting.ts
+function shortenAddress(address, chars = 4) {
+  if (!address) return "";
+  const start = address.slice(0, chars + 2);
+  const end = address.slice(-chars);
+  return `${start}...${end}`;
+}
+function formatUSD(amount, decimals = 2) {
+  const num = typeof amount === "string" ? parseFloat(amount) : amount;
+  if (isNaN(num)) return "$0.00";
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "USD",
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals
+  }).format(num);
+}
+function formatTokenAmount(amount, symbol, decimals = 2) {
+  const num = typeof amount === "string" ? parseFloat(amount) : amount;
+  if (isNaN(num)) return `0 ${symbol}`;
+  const formatted = new Intl.NumberFormat("en-US", {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals
+  }).format(num);
+  return `${formatted} ${symbol}`;
+}
+function formatCompact(amount) {
+  const num = typeof amount === "string" ? parseFloat(amount) : amount;
+  if (isNaN(num)) return "0";
+  return new Intl.NumberFormat("en-US", {
+    notation: "compact",
+    maximumFractionDigits: 1
+  }).format(num);
+}
+function formatPercent(value, decimals = 2) {
+  return `${(value * 100).toFixed(decimals)}%`;
+}
+
+// src/react/useATFiSDK.ts
+import { useMemo } from "react";
+function useATFiSDK(publicClient, walletClient, config) {
+  const sdk = useMemo(() => {
+    if (!publicClient) return null;
+    if (walletClient) {
+      return new ATFiSDK(publicClient, walletClient, config);
+    }
+    return ATFiSDK.readOnly(publicClient, config);
+  }, [publicClient, walletClient, config]);
+  return {
+    sdk,
+    isReadOnly: !walletClient
+  };
+}
+
+// src/react/useEventInfo.ts
+import { useState, useEffect, useCallback } from "react";
+function useEventInfo(sdk, vaultAddress) {
+  const [data, setData] = useState(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const fetchData = useCallback(async () => {
+    if (!sdk || !vaultAddress) {
+      setData(null);
+      return;
+    }
+    setIsLoading(true);
+    setError(null);
+    try {
+      const info = await sdk.getEventInfo(vaultAddress);
+      setData(info);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error("Failed to fetch event info"));
+      setData(null);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [sdk, vaultAddress]);
+  useEffect(() => {
+    fetchData();
+  }, [fetchData]);
+  return {
+    data,
+    isLoading,
+    error,
+    refetch: fetchData
+  };
+}
+
+// src/react/useWatchVault.ts
+import { useState as useState2, useEffect as useEffect2, useRef } from "react";
+function useWatchVault(sdk, vaultAddress) {
+  const [state, setState] = useState2({
+    participantCount: 0,
+    verifiedCount: 0,
+    isSettled: false,
+    lastClaim: null
+  });
+  const [isWatching, setIsWatching] = useState2(false);
+  const unwatchRef = useRef(null);
+  useEffect2(() => {
+    if (!sdk || !vaultAddress) {
+      setIsWatching(false);
+      return;
+    }
+    if (unwatchRef.current) {
+      unwatchRef.current();
+    }
+    try {
+      unwatchRef.current = sdk.watchVault(vaultAddress, {
+        onParticipantJoined: (_participant, totalParticipants) => {
+          setState((prev) => ({ ...prev, participantCount: totalParticipants }));
+        },
+        onParticipantVerified: (_participant, totalVerified) => {
+          setState((prev) => ({ ...prev, verifiedCount: totalVerified }));
+        },
+        onSettled: () => {
+          setState((prev) => ({ ...prev, isSettled: true }));
+        },
+        onClaimed: (participant, amount) => {
+          setState((prev) => ({ ...prev, lastClaim: { participant, amount } }));
+        },
+        onError: (error) => {
+          console.error("[useWatchVault]", error);
+        }
+      });
+      setIsWatching(true);
+    } catch (err) {
+      console.error("[useWatchVault] Failed to start watching:", err);
+      setIsWatching(false);
+    }
+    return () => {
+      if (unwatchRef.current) {
+        unwatchRef.current();
+        unwatchRef.current = null;
+      }
+      setIsWatching(false);
+    };
+  }, [sdk, vaultAddress]);
+  return {
+    ...state,
+    isWatching
+  };
+}
 export {
   ATFiError,
   ATFiErrorCode,
@@ -1357,13 +1557,24 @@ export {
   ERC20ABI,
   EventStatus,
   FactoryATFiABI,
+  NETWORKS,
   ParticipantStatus,
   TOKENS,
   VaultATFiABI,
   formatAmount,
+  formatCompact,
+  formatPercent,
+  formatTokenAmount,
+  formatUSD,
   fromTokenUnits,
+  getNetworkConfig,
   getTokenByAddress,
   getTokenBySymbol,
+  isYieldSupported,
   parseContractError,
-  toTokenUnits
+  shortenAddress,
+  toTokenUnits,
+  useATFiSDK,
+  useEventInfo,
+  useWatchVault
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atfi",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "TypeScript SDK for ATFi commitment vaults on Base",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -18,8 +18,17 @@
   "dependencies": {
     "viem": "^2.21.0"
   },
+  "peerDependencies": {
+    "react": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
     "vitest": "^1.0.0"