aiia-vault-sdk 1.0.2 → 1.1.1

package/dist/SeedRoundFundraiser.d.ts

@@ -34,6 +34,13 @@ export interface UserContribution {
     contributedToken: string;
     contributedAmount: number;
 }
+/**
+ * SDK for interacting with the SeedRoundFundraiser smart contract
+ *
+ * @remarks
+ * This SDK provides methods to interact with the SeedRoundFundraiser contract,
+ * including contributing tokens, managing rounds, and handling whitelisted tokens.
+ */
 export declare class SeedRoundFundraiserSDK {
     name: string;
     private contract;
@@ -43,14 +50,138 @@ export declare class SeedRoundFundraiserSDK {
     private PRICE_PRECISION;
     private whitelistedTokensArray;
     private networkName;
+    /**
+     * Creates a new instance of the SeedRoundFundraiserSDK
+     *
+     * @param rpcUrls - Single RPC URL or array of RPC URLs for blockchain connection
+     * @param contractAddress - Optional contract address. If not provided, will be resolved from contracts.json
+     *
+     * @throws Will throw if no valid RPC providers are available
+     */
     constructor(rpcUrls: string | string[], contractAddress?: string);
+    /**
+     * Gets the network name from the RPC URL
+     *
+     * @param rpcUrl - The RPC URL to parse
+     * @returns The network name (e.g., 'sepolia', 'mainnet', 'base-sepolia')
+     * @private
+     */
     private getNetworkNameFromRpc;
+    /**
+     * Imports whitelisted tokens from configuration file
+     *
+     * @private
+     */
     private importWhitelistedTokens;
+    /**
+     * Gets detailed information about a whitelisted token
+     *
+     * @param tokenAddress - The address of the token to query
+     * @returns Token information including price, symbol, and contribution limits, or null if not whitelisted
+     *
+     * @example
+     * ```typescript
+     * const tokenInfo = await sdk.getWhitelistedTokenInfo("0x...");
+     * if (tokenInfo) {
+     *   console.log(`Max contribution: ${tokenInfo.maxContribution} ${tokenInfo.symbol}`);
+     * }
+     * ```
+     */
     getWhitelistedTokenInfo(tokenAddress: string): Promise<WhitelistedTokenInfo | null>;
+    /**
+     * Gets information about all whitelisted tokens that are accepted for seed round participation.
+     *
+     * @remarks
+     * This function iterates through all whitelisted token addresses and fetches detailed information
+     * for each token that is actually whitelisted in the smart contract. The price and maxContribution
+     * values are calculated based on the current active round settings.
+     *
+     * @returns Promise<WhitelistedTokenInfo[]> Array of whitelisted token information with the following fields:
+     * - `address` (string): The token's contract address on the blockchain. For ETH, this will be the zero address (0x000...000)
+     * - `isWhitelisted` (boolean): Whether the token is currently whitelisted and accepted for contributions
+     * - `price` (number): Token price in USD with PRICE_PRECISION decimals (e.g., 1800.5 means 1 token = $1800.50)
+     * - `symbol` (string): Token symbol (e.g., "ETH", "USDC", "USDT")
+     * - `maxContribution` (number): Maximum amount of tokens a user can contribute in human-readable format,
+     *                              calculated as (maxFundPerAccount / tokenPrice)
+     * - `maxContributionRaw` (number): Maximum contribution amount adjusted with token decimals (maxContribution * 10^decimals),
+     *                                  ready for contract interaction
+     * - `decimals` (number): Number of decimal places the token uses (e.g., 18 for ETH, 6 for USDC)
+     *
+     * @example
+     * ```typescript
+     * const sdk = new SeedRoundFundraiserSDK(rpcUrl);
+     * const whitelistedTokens = await sdk.getAllWhitelistedTokensInfo();
+     *
+     * // Example response:
+     * [
+     *   {
+     *     address: "0x0000000000000000000000000000000000000000",
+     *     isWhitelisted: true,
+     *     price: 1800.5, // 1 ETH = $1800.50
+     *     symbol: "ETH",
+     *     maxContribution: 5.55, // Can contribute up to 5.55 ETH
+     *     maxContributionRaw: 5550000000000000000n, // 5.55 * 10^18
+     *     decimals: 18
+     *   },
+     *   {
+     *     address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+     *     isWhitelisted: true,
+     *     price: 1.0, // 1 USDC = $1.00
+     *     symbol: "USDC",
+     *     maxContribution: 10000, // Can contribute up to 10000 USDC
+     *     maxContributionRaw: 10000000000, // 10000 * 10^6
+     *     decimals: 6
+     *   }
+     * ]
+     * ```
+     *
+     * @notice
+     * - Token prices are in USD with PRICE_PRECISION (1e18) decimals
+     * - maxContribution is calculated based on the current round's maxFundPerAccount
+     * - For new rounds or if no active round exists, maxContribution will be 0
+     * - ETH is represented with the zero address and always has 18 decimals
+     *
+     * @see {@link getWhitelistedTokenInfo} For getting information about a single token
+     * @see {@link WhitelistedTokenInfo} For the interface definition
+     */
     getAllWhitelistedTokensInfo(): Promise<WhitelistedTokenInfo[]>;
+    /**
+     * Gets a random provider from the available providers
+     *
+     * @returns An ethers Provider instance
+     * @private
+     */
     private getRandomProvider;
+    /**
+     * Gets a contract instance with a random provider
+     *
+     * @returns Contract instance
+     * @private
+     */
     private getContractWithRandomProvider;
+    /**
+     * Bootstraps the SDK by checking RPC health and removing inactive providers
+     *
+     * @throws Will throw if no active RPC providers are available
+     */
     bootstrap(): Promise<void>;
+    /**
+     * Signs and sends a transaction to the blockchain
+     *
+     * @param tx - The transaction to send
+     * @param wallet - The wallet or transaction sender
+     * @param callbacks - Optional callbacks for transaction lifecycle events
+     * @returns Transaction result and status
+     *
+     * @example
+     * ```typescript
+     * const tx = await sdk.buildContributeTx(0, ethers.ZeroAddress, 1.5);
+     * const result = await sdk.signAndSendTransaction(tx, wallet, {
+     *   onSubmit: (txHash) => console.log(`Submitted: ${txHash}`),
+     *   onFinally: (status) => console.log(`Completed: ${status.status}`)
+     * });
+     * ```
+     */
     signAndSendTransaction(tx: ethers.ContractTransaction, wallet: ethers.Wallet | SendTransactionMutateAsync<Config, any>, callbacks?: {
         onSubmit?: (tx: string) => void | Promise<void>;
         onFinally?: (status: {
@@ -72,20 +203,154 @@ export declare class SeedRoundFundraiserSDK {
             attempts: number;
         };
     }>;
+    /**
+     * Builds a transaction to add a token to the whitelist
+     *
+     * @param token - The token address to whitelist
+     * @param price - The price of the token in USD (with PRICE_PRECISION decimals)
+     * @returns Populated transaction
+     *
+     * @example
+     * ```typescript
+     * const tx = await sdk.buildAddWhitelistedTokenTx("0x...", 1800.5);
+     * ```
+     */
     buildAddWhitelistedTokenTx(token: string, price: number): Promise<ethers.ContractTransaction>;
+    /**
+     * Builds a transaction to update a whitelisted token's price
+     *
+     * @param token - The token address
+     * @param newPrice - The new price in USD (with PRICE_PRECISION decimals)
+     * @returns Populated transaction
+     */
     buildUpdateTokenPriceTx(token: string, newPrice: number): Promise<ethers.ContractTransaction>;
+    /**
+     * Builds a transaction to remove a token from the whitelist
+     *
+     * @param token - The token address to remove
+     * @returns Populated transaction
+     */
     buildRemoveWhitelistedTokenTx(token: string): Promise<ethers.ContractTransaction>;
+    /**
+     * Builds a transaction to create a new fundraising round
+     *
+     * @param startTime - Round start time (Unix timestamp)
+     * @param endTime - Round end time (Unix timestamp)
+     * @param targetFund - Target funding amount in USD (with PRICE_PRECISION decimals)
+     * @param totalAllocation - Total tokens to allocate
+     * @param maxFundPerAccount - Maximum funding per account in USD
+     * @returns Populated transaction
+     *
+     * @example
+     * ```typescript
+     * const now = Math.floor(Date.now() / 1000);
+     * const tx = await sdk.buildCreateRoundTx(
+     *   now,
+     *   now + 86400, // 24 hours
+     *   1000000, // $1M target
+     *   1000000, // 1M tokens
+     *   10000 // $10k max per account
+     * );
+     * ```
+     */
     buildCreateRoundTx(startTime: number, endTime: number, targetFund: number, totalAllocation: number, maxFundPerAccount: number): Promise<ethers.ContractTransaction>;
+    /**
+     * Builds a transaction to update an existing round's parameters
+     *
+     * @param roundId - The ID of the round to update
+     * @param startTime - New start time
+     * @param endTime - New end time
+     * @param targetFund - New target fund amount
+     * @param totalAllocation - New total token allocation
+     * @param maxFundPerAccount - New maximum funding per account
+     * @returns Populated transaction
+     */
     buildUpdateRoundTx(roundId: number, startTime: number, endTime: number, targetFund: number, totalAllocation: number, maxFundPerAccount: number): Promise<ethers.ContractTransaction>;
+    /**
+     * Builds a transaction to end a round
+     *
+     * @param roundId - The ID of the round to end
+     * @returns Populated transaction
+     */
     buildEndRoundTx(roundId: number): Promise<ethers.ContractTransaction>;
+    /**
+     * Builds a transaction to enable/disable token claiming for a round
+     *
+     * @param roundId - The round ID
+     * @param enabled - Whether to enable or disable claiming
+     * @returns Populated transaction
+     */
     buildSetClaimingEnabledTx(roundId: number, enabled: boolean): Promise<ethers.ContractTransaction>;
+    /**
+     * Builds a transaction to enable/disable refunds for a round
+     *
+     * @param roundId - The round ID
+     * @param enabled - Whether to enable or disable refunds
+     * @returns Populated transaction
+     */
     buildSetRefundEnabledTx(roundId: number, enabled: boolean): Promise<ethers.ContractTransaction>;
+    /**
+     * Builds a transaction to contribute to a round
+     *
+     * @param roundId - The ID of the round to contribute to
+     * @param token - The token address (use ethers.ZeroAddress for ETH)
+     * @param amount - Amount to contribute in human-readable format
+     * @returns Populated transaction
+     *
+     * @example
+     * ```typescript
+     * // Contribute 1.5 ETH
+     * const tx = await sdk.buildContributeTx(0, ethers.ZeroAddress, 1.5);
+     *
+     * // Contribute 1000 USDC
+     * const tx = await sdk.buildContributeTx(0, "0x...", 1000);
+     * ```
+     *
+     * @notice For ERC20 tokens, ensure you have approved the contract first
+     */
     buildContributeTx(roundId: number, token: string, amount: number): Promise<ethers.ContractTransaction>;
+    /**
+     * Builds a transaction to claim allocated tokens
+     *
+     * @returns Populated transaction for claiming tokens from all eligible rounds
+     */
     buildClaimTokensTx(): Promise<ethers.ContractTransaction>;
+    /**
+     * Builds a transaction to request a refund
+     *
+     * @returns Populated transaction for requesting refund from eligible rounds
+     */
     buildRefundTx(): Promise<ethers.ContractTransaction>;
+    /**
+     * Builds a transaction to withdraw accumulated funds
+     *
+     * @param token - The token address to withdraw
+     * @param amount - Amount to withdraw in human-readable format
+     * @returns Populated transaction
+     *
+     * @notice Only callable by contract owner
+     */
     buildWithdrawFundsTx(token: string, amount: number): Promise<ethers.ContractTransaction>;
+    /**
+     * Builds a transaction to claim tokens from a specific round
+     *
+     * @param roundId - The round ID to claim tokens from
+     * @returns Populated transaction
+     */
     buildClaimTokensByRoundIdTx(roundId: number): Promise<ethers.ContractTransaction>;
+    /**
+     * Gets information about a whitelisted token
+     *
+     * @param token - The token address
+     * @returns Token whitelist status and price
+     */
     getWhitelistedToken(token: string): Promise<WhitelistedToken>;
+    /**
+     * Gets configuration of a specific round
+     *
+     * @param roundId - The round ID to query
+     * @returns Round configuration including times, targets, and status
+     */
     getRound(roundId: number): Promise<RoundConfig>;
     getUserContribution(roundId: number, user: string): Promise<UserContribution>;
     getRoundRaisedFunds(roundId: number): Promise<number>;
@@ -101,9 +366,63 @@ export declare class SeedRoundFundraiserSDK {
      */
     getLatestRoundId(): Promise<number>;
     /**
-     * Get comprehensive information about a specific round
-     * @param roundId The ID of the round to get information for
-     * @returns An object containing all information about the specified round
+     * Gets comprehensive information about a specific fundraising round
+     *
+     * @param roundId - The ID of the round to query (0-based index)
+     * @returns Detailed round information with the following fields:
+     * ```typescript
+     * {
+     *   roundId: number;    // The queried round ID
+     *   config: {           // Round configuration and current state
+     *     startTime: number;      // Unix timestamp when the round starts
+     *     endTime: number;        // Unix timestamp when the round ends
+     *     targetFund: number;     // Target funding amount in USD (with PRICE_PRECISION)
+     *     totalAllocation: number;// Total project tokens to be distributed in this round
+     *     maxFundPerAccount: number; // Maximum USD value one account can contribute
+     *     exists: boolean;        // Whether this round has been created
+     *     ended: boolean;         // Whether this round has been manually ended
+     *     claimingEnabled: boolean; // Whether participants can claim their tokens
+     *     refundEnabled: boolean;   // Whether refunds are enabled for this round
+     *   };
+     *   raisedFunds: number;    // Total USD value raised in this round
+     *   participants: number;    // Number of unique participants
+     *   isActive: boolean;      // Whether the round is currently active
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const roundInfo = await sdk.getRoundInfo(0);
+     *
+     * // Check if round is active and accepting contributions
+     * if (roundInfo.isActive) {
+     *   console.log(`Round 0 is active!`);
+     *   console.log(`Progress: $${roundInfo.raisedFunds}/$${roundInfo.config.targetFund}`);
+     *   console.log(`Participants: ${roundInfo.participants}`);
+     * }
+     *
+     * // Check if tokens can be claimed
+     * if (roundInfo.config.claimingEnabled) {
+     *   console.log('Token claiming is enabled for this round');
+     * }
+     * ```
+     *
+     * @notice
+     * - All USD values (targetFund, maxFundPerAccount, raisedFunds) use PRICE_PRECISION (1e18) decimals
+     * - totalAllocation is in project token's decimals (e.g., usually 18 decimals)
+     * - A round is considered active if:
+     *   1. It exists
+     *   2. Current time is between startTime and endTime
+     *   3. It hasn't been manually ended
+     * - Rounds are 0-indexed, so first round has ID 0
+     *
+     * @throws Will throw an error if:
+     * - roundId is negative
+     * - roundId is greater than or equal to total number of rounds
+     *
+     * @see {@link getRound} For getting just the round configuration
+     * @see {@link getRoundRaisedFunds} For getting just the raised funds
+     * @see {@link getRoundParticipants} For getting just the participant count
      */
     getRoundInfo(roundId: number): Promise<{
         roundId: number;
@@ -127,4 +446,72 @@ export declare class SeedRoundFundraiserSDK {
     getAllEvents(fromBlock: number, toBlock: number): Promise<ParsedSeedRoundFundraiserEventRaw[]>;
     streamEvents(fromBlock: number, onEvent: (event: ParsedSeedRoundFundraiserEvent) => Promise<void>, saveLatestBlock: (blockNumber: number) => Promise<void>, batchSize?: number, sleepTime?: number): Promise<void>;
     formatEventArgs: (event: ParsedSeedRoundFundraiserEventRaw) => ParsedSeedRoundFundraiserEvent;
+    /**
+     * Gets detailed information about a user's contribution in a specific round
+     *
+     * @param roundId - The ID of the round to query
+     * @param user - The user's address to check contribution
+     * @returns Detailed contribution information with the following fields:
+     * ```typescript
+     * {
+     *   contribution: {
+     *     fundAmount: number;      // Total USD value of contribution (with PRICE_PRECISION)
+     *     tokenAllocation: number; // Amount of project tokens allocated
+     *     claimed: boolean;        // Whether allocated tokens have been claimed
+     *     refunded: boolean;       // Whether contribution has been refunded
+     *     contributedToken: string;// Address of token used for contribution
+     *     contributedAmount: number;// Actual amount of tokens contributed
+     *   };
+     *   roundInfo: {
+     *     exists: boolean;         // Whether the round exists
+     *     isActive: boolean;       // Whether the round is currently active
+     *     claimingEnabled: boolean;// Whether token claiming is enabled
+     *     refundEnabled: boolean;  // Whether refunds are enabled
+     *   };
+     *   tokenInfo?: {              // Only present if contribution exists
+     *     symbol: string;          // Symbol of contributed token
+     *     decimals: number;        // Decimals of contributed token
+     *   };
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const userContrib = await sdk.getUserRoundContribution(0, "0x...");
+     *
+     * if (userContrib.contribution.fundAmount > 0) {
+     *   console.log(`Contributed: ${userContrib.contribution.contributedAmount} ${userContrib.tokenInfo?.symbol}`);
+     *   console.log(`Value: $${userContrib.contribution.fundAmount}`);
+     *   console.log(`Allocated: ${userContrib.contribution.tokenAllocation} tokens`);
+     *
+     *   if (userContrib.roundInfo.claimingEnabled && !userContrib.contribution.claimed) {
+     *     console.log('Tokens are ready to claim!');
+     *   }
+     * }
+     * ```
+     *
+     * @notice
+     * - All USD values use PRICE_PRECISION (1e18) decimals
+     * - Token amounts are in their native decimals (e.g., 18 for ETH, 6 for USDC)
+     * - For ETH contributions, contributedToken will be the zero address
+     * - tokenInfo will be undefined if user hasn't contributed to the round
+     *
+     * @throws Will throw if:
+     * - roundId is invalid
+     * - user address is invalid
+     * - Contract call fails
+     */
+    getUserRoundContribution(roundId: number, user: string): Promise<{
+        contribution: UserContribution;
+        roundInfo: {
+            exists: boolean;
+            isActive: boolean;
+            claimingEnabled: boolean;
+            refundEnabled: boolean;
+        };
+        tokenInfo?: {
+            symbol: string;
+            decimals: number;
+        };
+    }>;
 }