@steerprotocol/sdk 1.27.0 → 1.28.0

package/src/base/SmartRewards.ts

@@ -0,0 +1,783 @@
+import { Campaign, createClient } from '@steerprotocol/api-sdk';
+import type { Address, Hash, PublicClient, WalletClient } from 'viem';
+import { formatUnits } from 'viem';
+import { SteerResponse } from '../types.js';
+import { getSubgraphUrlByChainId } from '../const/subgraph.js';
+
+/**
+ * Represents a node in the claim proof data structure
+ * @property chainId - The ID of the chain where the claim exists
+ * @property lastBlockUpdatedTo - The last block number this claim was updated to
+ * @property user - The address of the user who can claim
+ * @property campaignId - The ID of the campaign this claim belongs to
+ * @property amount - The claimable amount as a string (may include decimals)
+ * @property proof - The merkle proof array required for claiming
+ */
+export interface ClaimProofNode {
+  chainId: number;
+  lastBlockUpdatedTo: number;
+  user: string;
+  campaignId: number;
+  amount: string;
+  proof: readonly string[];
+}
+
+export interface ClaimProofEdge {
+  node: ClaimProofNode;
+  cursor: string;
+}
+
+/**
+ * Represents a historical claim reward record
+ * @property id - Unique identifier for the claim
+ * @property user - Address of the user who claimed
+ * @property amount - Amount that was claimed (may include decimals)
+ * @property campaign - Campaign identifier
+ * @property chainId - Chain ID where the claim occurred
+ * @property timestamp - Unix timestamp of when the claim occurred
+ */
+export interface ClaimRewardNode {
+  id: string;
+  user: string;
+  amount: string;
+  campaign: string;
+  chainId: number;
+  timestamp: number;
+}
+
+export interface ClaimRewardEdge {
+  cursor: string;
+  node: ClaimRewardNode;
+}
+
+/**
+ * Pagination information for paginated queries
+ * @property hasNextPage - Whether there are more results available
+ * @property endCursor - Cursor to use for fetching next page, if available
+ */
+export interface PageInfo {
+  hasNextPage: boolean;
+  endCursor: string | null | undefined;
+}
+
+/**
+ * Connection type for claim rewards, following the Relay specification
+ * @property edges - Array of claim reward records with cursors
+ * @property pageInfo - Pagination information
+ * @property totalCount - Total number of records available
+ */
+export interface ClaimRewardsConnection {
+  edges: readonly ClaimRewardEdge[];
+  pageInfo: PageInfo;
+  totalCount: number;
+}
+
+export interface ClaimProofsPageInfo {
+  hasNextPage: boolean;
+  endCursor?: string;
+}
+
+export interface ClaimProofsResponse {
+  totalCount: number;
+  edges: readonly ClaimProofEdge[];
+  pageInfo: ClaimProofsPageInfo;
+}
+
+export interface SmartRewarderContract {
+  chainId: number;
+  address: string;
+}
+
+/**
+ * Parameters required for claiming rewards
+ * @property users - Array of user addresses who are claiming
+ * @property campaignIds - Array of campaign IDs corresponding to each claim
+ * @property amounts - Array of amounts to claim
+ * @property proofs - Array of merkle proofs for verification
+ * @property rewarderAddress - Address of the smart rewarder contract
+ */
+export interface ClaimRewardParams {
+  users: readonly Address[];
+  campaignIds: readonly bigint[];
+  amounts: readonly bigint[];
+  proofs: readonly (readonly `0x${string}`[])[];
+  rewarderAddress: Address;
+}
+
+/**
+ * Represents a reward balance with both native and formatted values
+ * @property formatted - Human-readable string format with proper decimals
+ * @property native - Raw bigint value
+ */
+export interface RewardBalance {
+  formatted: string;
+  native: bigint;
+}
+
+/**
+ * Comprehensive summary of a user's reward status
+ * @property totalEarned - Total rewards earned (claimed + claimable)
+ * @property totalClaimed - Total rewards already claimed
+ * @property claimable - Rewards available to claim
+ */
+export interface RewardSummary {
+  totalEarned: RewardBalance;
+  totalClaimed: RewardBalance;
+  claimable: RewardBalance;
+}
+
+export abstract class SmartRewards {
+  protected readonly client: ReturnType<typeof createClient>;
+  protected readonly publicClient: PublicClient;
+  protected readonly walletClient: WalletClient;
+
+  constructor(
+    client: ReturnType<typeof createClient>,
+    publicClient: PublicClient,
+    walletClient: WalletClient
+  ) {
+    this.client = client;
+    this.publicClient = publicClient;
+    this.walletClient = walletClient;
+  }
+
+  public async getCampaigns(chainId: number): Promise<SteerResponse<Campaign[]>> {
+    const campaigns = await this.client.campaigns({
+      filter: {
+        chainId,
+      },
+    });
+
+    return {
+      data: (campaigns.data?.campaigns.edges.map((edge) => ({
+        ...edge.node,
+        vaults: edge.node.vaults?.map(vault => ({
+          ...vault,
+          beaconName: vault.beaconName || '',
+          name: vault.name || '',
+          protocol: vault.protocol || '',
+          protocolBaseType: vault.protocolBaseType || '',
+          targetProtocol: vault.targetProtocol || ''
+        })) || []
+      })) || []) as Campaign[],
+      status: campaigns.status,
+      success: true,
+    };
+  }
+
+  /**
+   * Retrieves campaigns associated with a specific pool address
+   * @param poolAddress - The address of the pool to get campaigns for
+   * @param chainId - Chain ID where the pool exists
+   * @returns Promise resolving to an array of campaigns associated with the pool
+   * 
+   * @example
+   * ```typescript
+   * // Get campaigns for a pool on a specific chain
+   * const campaigns = await smartRewards.campaignsByPool('0x...', 1);
+   * ```
+   */
+  public async campaignsByPool(
+    poolAddress: string,
+    chainId: number
+  ): Promise<SteerResponse<Campaign[]>> {
+    try {
+      const campaigns = await this.client.campaignsByPool({
+        pool: poolAddress,
+        chainId
+      });
+
+      return {
+        data: (campaigns.data?.campaignsByPool?.map(campaign => campaign ? {
+          ...campaign,
+          vaults: campaign.vaults?.map(vault => vault ? {
+            ...vault,
+            beaconName: vault.beaconName || '',
+            name: vault.name || '',
+            protocol: vault.protocol || '',
+            protocolBaseType: vault.protocolBaseType || '',
+            targetProtocol: vault.targetProtocol || ''
+          } : null).filter((v): v is NonNullable<typeof v> => v !== null) || []
+        } : null).filter((c): c is NonNullable<typeof c> => c !== null) || []) as Campaign[],
+        status: campaigns.status,
+        success: true
+      };
+    } catch (error) {
+      return {
+        data: null,
+        status: 500,
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error occurred'
+      };
+    }
+  }
+
+  /**
+   * Retrieves claim proofs for a user that can be used to claim rewards
+   * @param user - Address of the user to get proofs for
+   * @param chainId - Chain ID where the claims exist
+   * @param campaignId - Optional campaign ID to filter claims
+   * @returns Promise resolving to claim proof data with pagination support
+   */
+  public async getClaimProofs(
+    user: Address,
+    chainId: number,
+    campaignId?: number
+  ): Promise<SteerResponse<ClaimProofsResponse>> {
+    try {
+      const normalizedUser = user.toLowerCase() as Address;
+      const response = await this.client.claimProofs({
+        user: normalizedUser,
+        filter: {
+          chainId,
+          campaignId
+        }
+      });
+
+      if (!response.data?.claimProofs) {
+        return {
+          data: null,
+          status: response.status,
+          success: true
+        };
+      }
+
+      const transformedResponse: ClaimProofsResponse = {
+        totalCount: response.data.claimProofs.totalCount,
+        pageInfo: {
+          hasNextPage: response.data.claimProofs.pageInfo.hasNextPage,
+          endCursor: response.data.claimProofs.pageInfo.endCursor || undefined
+        },
+        edges: response.data.claimProofs.edges.map(edge => ({
+          cursor: edge.cursor,
+          node: {
+            ...edge.node,
+            proof: edge.node.proof?.filter((p): p is string => p !== null) || []
+          }
+        }))
+      };
+
+      return {
+        data: transformedResponse,
+        status: response.status,
+        success: true
+      };
+    } catch (error) {
+      return {
+        data: null,
+        status: 500,
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error occurred'
+      };
+    }
+  }
+
+  /**
+   * Retrieves historical claim data for a specific pool
+   * @param chainId - Chain ID where the pool exists
+   * @param pool - Address or identifier of the pool
+   * @param user - Optional user address to filter claims
+   * @returns Promise resolving to paginated claim history data
+   * 
+   * @example
+   * ```typescript
+   * // Get all claims for a pool
+   * const allClaims = await smartRewards.getClaimRewardsByPool(1, poolAddress);
+   * 
+   * // Get claims for a specific user in a pool
+   * const userClaims = await smartRewards.getClaimRewardsByPool(1, poolAddress, userAddress);
+   * ```
+   */
+  public async getClaimedRewardsByPool(
+    chainId: number,
+    pool: string,
+    user?: Address
+  ): Promise<SteerResponse<ClaimRewardsConnection>> {
+    try {
+      const normalizedPool = pool.toLowerCase();
+      const normalizedUser = user ? user.toLowerCase() as Address : undefined;
+      
+      const response = await this.client.claimRewards({
+        poolId: normalizedPool,
+        chainId,
+        filter: normalizedUser ? { user: normalizedUser } : undefined
+      });
+
+      if (!response.data?.claimRewards) {
+        return {
+          data: null,
+          status: response.status,
+          success: true
+        };
+      }
+
+      const transformedResponse: ClaimRewardsConnection = {
+        totalCount: response.data.claimRewards.totalCount,
+        pageInfo: {
+          hasNextPage: response.data.claimRewards.pageInfo.hasNextPage,
+          endCursor: response.data.claimRewards.pageInfo.endCursor
+        },
+        edges: response.data.claimRewards.edges.map(edge => ({
+          cursor: edge.cursor,
+          node: {
+            ...edge.node,
+            timestamp: Number(edge.node.timestamp)
+          }
+        }))
+      };
+
+      return {
+        data: transformedResponse,
+        status: response.status,
+        success: true
+      };
+    } catch (error) {
+      return {
+        data: null,
+        status: 500,
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error occurred'
+      };
+    }
+  }
+
+  
+
+  /**
+   * Gets a comprehensive summary of a user's reward status
+   * @param user - Address of the user
+   * @param chainId - Chain ID to check rewards on
+   * @param campaignId - Optional campaign ID to filter rewards
+   * @param decimals - Number of decimals for formatting (default: 18)
+   * @returns Promise resolving to reward summary with both native and formatted values
+   * 
+   * @example
+   * ```typescript
+   * const summary = await smartRewards.getRewardSummary(userAddress, chainId);
+   * console.log('Total earned:', summary.data.totalEarned.formatted);
+   * console.log('Available to claim:', summary.data.claimable.formatted);
+   * ```
+   */
+  public async getRewardSummary(
+    user: Address,
+    poolAddress: string,
+    chainId: number,
+    campaignId: number,
+    decimals: number = 18
+  ): Promise<SteerResponse<RewardSummary>> {
+    try {
+      // Lowercase addresses
+      const normalizedUser = user.toLowerCase() as Address;
+      const normalizedPoolAddress = poolAddress.toLowerCase();
+
+      // Get claimable rewards
+      const claimProofs = await this.getClaimProofs(normalizedUser, chainId, campaignId);
+
+      // Filter claim proofs by campaignId for additional safety
+      const filteredClaimProofs = claimProofs.data?.edges.filter(
+        edge => edge.node.campaignId === campaignId
+      ) || [];
+
+      const totalAmount = filteredClaimProofs.reduce(
+        (sum, edge) => sum + BigInt(edge.node.amount.split('.')[0]),
+        0n
+      ) || 0n;
+
+      // Get claimed rewards
+      const claimedRewards = await this.getClaimedRewardsByPool(chainId, normalizedPoolAddress, normalizedUser);
+
+      // Filter claimed rewards by campaign ID
+      const filteredClaimedRewards = claimedRewards.data?.edges.filter(
+        edge => Number(edge.node.campaign) === campaignId
+      ) || [];
+
+      const claimedAmount = filteredClaimedRewards.reduce(
+        (sum, edge) => sum + BigInt(edge.node.amount.split('.')[0]),
+        0n
+      ) || 0n;
+
+      // Calculate totals
+      const claimableAmount = totalAmount - claimedAmount;
+
+      const summary: RewardSummary = {
+        totalEarned: {
+          native: totalAmount,
+          formatted: formatUnits(totalAmount, decimals)
+        },
+        totalClaimed: {
+          native: claimedAmount,
+          formatted: formatUnits(claimedAmount, decimals)
+        },
+        claimable: {
+          native: claimableAmount,
+          formatted: formatUnits(claimableAmount, decimals)
+        }
+      };
+
+      return {
+        data: summary,
+        status: 200,
+        success: true
+      };
+    } catch (error) {
+      return {
+        data: null,
+        status: 500,
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error occurred'
+      };
+    }
+  }
+
+  public async getSmartRewarderContracts(): Promise<SteerResponse<readonly SmartRewarderContract[]>> {
+    try {
+      const response = await this.client.smartRewarderContracts();
+
+      return {
+        data: response.data?.smartRewarderContracts || [],
+        status: response.status,
+        success: true
+      };
+    } catch (error) {
+      return {
+        data: null,
+        status: 500,
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error occurred'
+      };
+    }
+  }
+
+  /**
+   * Claims rewards from the smart rewarder contract
+   * @param params - Parameters required for claiming rewards
+   * @returns Promise resolving to transaction hash if successful
+   * 
+   * @remarks
+   * This method handles the low-level interaction with the smart contract.
+   * For a higher-level interface, consider using {@link claimCampaignRewards} instead.
+   * 
+   * @example
+   * ```typescript
+   * // Get claim proofs
+   * const claimProofs = await smartRewards.getClaimProofs(userAddress, chainId, campaignId);
+   * 
+   * // Get smart rewarder contract
+   * const rewarders = await smartRewards.getSmartRewarderContracts();
+   * const rewarder = rewarders.data?.find(r => r.chainId === chainId);
+   * 
+   * if (claimProofs.data && rewarder) {
+   *   // Prepare claim data
+   *   const claimData = smartRewards.prepareClaimData(claimProofs.data);
+   *   claimData.rewarderAddress = rewarder.address as Address;
+   *   
+   *   // Claim rewards
+   *   const tx = await smartRewards.claimReward(claimData);
+   * }
+   * ```
+   * 
+   * @throws Will throw an error if no wallet account is found
+   * @throws Will throw an error if contract simulation fails
+   */
+  public async claimReward(params: ClaimRewardParams): Promise<SteerResponse<Hash>> {
+    try {
+      const account = await this.walletClient.getAddresses();
+      if (!account[0]) throw new Error('No account found');
+
+      // Normalize addresses
+      const normalizedParams = {
+        ...params,
+        users: params.users.map(user => user.toLowerCase() as Address),
+        rewarderAddress: params.rewarderAddress.toLowerCase() as Address
+      };
+
+      const { request } = await this.publicClient.simulateContract({
+        address: normalizedParams.rewarderAddress,
+        abi: [{
+          type: 'function',
+          inputs: [
+            { name: 'users', internalType: 'address[]', type: 'address[]' },
+            { name: 'campaignIds', internalType: 'uint256[]', type: 'uint256[]' },
+            { name: 'amounts', internalType: 'uint256[]', type: 'uint256[]' },
+            { name: 'proofs', internalType: 'bytes32[][]', type: 'bytes32[][]' }
+          ],
+          name: 'claim',
+          outputs: [],
+          stateMutability: 'nonpayable'
+        }],
+        functionName: 'claim',
+        args: [
+          normalizedParams.users,
+          normalizedParams.campaignIds,
+          normalizedParams.amounts,
+          normalizedParams.proofs
+        ],
+        account: account[0]
+      });
+
+      const hash = await this.walletClient.writeContract(request);
+
+      return {
+        data: hash,
+        status: 200,
+        success: true
+      };
+    } catch (error) {
+      return {
+        data: null,
+        status: 500,
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error occurred'
+      };
+    }
+  }
+
+  /**
+   * Helper function to prepare claim data from claim proofs
+   * @param proofs - The claim proofs response from getClaimProofs
+   * @returns ClaimRewardParams object ready for use with claimReward
+   * 
+   * @remarks
+   * This helper function transforms the claim proofs into the format required by the smart contract.
+   * Note that the returned object's rewarderAddress is empty and must be set before using with claimReward.
+   * 
+   * @example
+   * ```typescript
+   * // Get claim proofs and rewarder contract
+   * const proofs = await smartRewards.getClaimProofs(userAddress, chainId);
+   * const rewarders = await smartRewards.getSmartRewarderContracts();
+   * const rewarder = rewarders.data?.find(r => r.chainId === chainId);
+   * 
+   * if (proofs.data && rewarder) {
+   *   // Prepare the claim data
+   *   const claimData = smartRewards.prepareClaimData(proofs.data);
+   *   
+   *   // Set the rewarder address (required)
+   *   claimData.rewarderAddress = rewarder.address as Address;
+   *   
+   *   // Now the data is ready for claiming
+   *   const tx = await smartRewards.claimReward(claimData);
+   * }
+   * ```
+   */
+  public prepareClaimData(proofs: ClaimProofsResponse): ClaimRewardParams {
+    return {
+      users: proofs.edges.map(edge => edge.node.user.toLowerCase() as Address),
+      campaignIds: proofs.edges.map(edge => BigInt(edge.node.campaignId)),
+      amounts: proofs.edges.map(edge => BigInt(edge.node.amount.split('.')[0])),
+      proofs: proofs.edges.map(edge => edge.node.proof as readonly `0x${string}`[]),
+      rewarderAddress: '' as Address
+    };
+  }
+
+  /**
+   * Convenience function to handle the entire claim process
+   * @param userAddress The address of the user claiming rewards
+   * @param chainId The chain ID where the campaign exists
+   * @param campaignId Optional campaign ID to filter claims
+   * @returns Transaction hash if successful, or error details if failed
+   */
+  public async claimCampaignRewards(
+    userAddress: Address,
+    chainId: number,
+    campaignId?: number
+  ): Promise<SteerResponse<Hash>> {
+    try {
+      const normalizedUser = userAddress.toLowerCase() as Address;
+      
+      // Get claim proofs
+      const claimProofsResponse = await this.getClaimProofs(normalizedUser, chainId, campaignId);
+      if (!claimProofsResponse.data || claimProofsResponse.data.edges.length === 0) {
+        return {
+          data: null,
+          status: 400,
+          success: false,
+          error: 'No claim proofs found'
+        };
+      }
+
+      // Filter claim proofs by campaignId if specified
+      let filteredClaimProofs = claimProofsResponse.data;
+      if (campaignId !== undefined) {
+        filteredClaimProofs = {
+          ...claimProofsResponse.data,
+          edges: claimProofsResponse.data.edges.filter(edge => edge.node.campaignId === campaignId)
+        };
+        
+        // If no matching campaign proofs found after filtering
+        if (filteredClaimProofs.edges.length === 0) {
+          return {
+            data: null,
+            status: 400,
+            success: false,
+            error: `No claim proofs found for campaign ID ${campaignId}`
+          };
+        }
+      }
+
+      // Get smart rewarder contract
+      const rewarderResponse = await this.getSmartRewarderContracts();
+      const rewarder = rewarderResponse.data?.find(r => r.chainId === chainId);
+      if (!rewarder) {
+        return {
+          data: null,
+          status: 400,
+          success: false,
+          error: `No smart rewarder contract found for chain ${chainId}`
+        };
+      }
+
+      // Prepare claim data
+      const claimData = this.prepareClaimData(filteredClaimProofs);
+      claimData.rewarderAddress = rewarder.address as Address;
+
+      // Execute claim
+      return await this.claimReward(claimData);
+    } catch (error) {
+      return {
+        data: null,
+        status: 500,
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error occurred'
+      };
+    }
+  }
+
+  /**
+   * Prepares the claim rewards campaign object with all necessary data for contract interaction
+   * @param userAddress The address of the user claiming rewards
+   * @param chainId The chain ID where the campaign exists
+   * @param campaignId Optional campaign ID to filter claims
+   * @returns Promise resolving to an object containing all necessary data for claiming rewards
+   * 
+   * @example
+   * ```typescript
+   * // Get the prepared claim data
+   * const claimData = await smartRewards.prepareClaimRewardsCampaign(userAddress, chainId, campaignId);
+   * 
+   * if (claimData.success) {
+   *   // Use the data with your own contract interaction methods
+   *   const { address, abi, functionName, args } = claimData.data;
+   *   // Execute the contract call using your preferred method
+   * }
+   * ```
+   */
+  public async prepareClaimRewardsCampaign(
+    userAddress: Address,
+    chainId: number,
+    campaignId?: number
+  ): Promise<SteerResponse<{
+    address: Address;
+    abi: {
+      type: string;
+      inputs: {
+        name: string;
+        internalType: string;
+        type: string;
+      }[];
+      name: string;
+      outputs: never[];
+      stateMutability: string;
+    }[];
+    functionName: string;
+    args: readonly [
+      readonly Address[],
+      readonly bigint[],
+      readonly bigint[],
+      readonly (readonly `0x${string}`[])[]
+    ];
+  }>> {
+    try {
+      const normalizedUser = userAddress.toLowerCase() as Address;
+      
+      // Get claim proofs
+      const claimProofsResponse = await this.getClaimProofs(normalizedUser, chainId, campaignId);
+      if (!claimProofsResponse.data || claimProofsResponse.data.edges.length === 0) {
+        return {
+          data: null,
+          status: 400,
+          success: false,
+          error: 'No claim proofs found'
+        };
+      }
+
+      // Filter claim proofs by campaignId if specified
+      let filteredClaimProofs = claimProofsResponse.data;
+      if (campaignId !== undefined) {
+        filteredClaimProofs = {
+          ...claimProofsResponse.data,
+          edges: claimProofsResponse.data.edges.filter(edge => edge.node.campaignId === campaignId)
+        };
+        
+        // If no matching campaign proofs found after filtering
+        if (filteredClaimProofs.edges.length === 0) {
+          return {
+            data: null,
+            status: 400,
+            success: false,
+            error: `No claim proofs found for campaign ID ${campaignId}`
+          };
+        }
+      }
+
+      // Get smart rewarder contract
+      const rewarderResponse = await this.getSmartRewarderContracts();
+      const rewarder = rewarderResponse.data?.find(r => r.chainId === chainId);
+      if (!rewarder) {
+        return {
+          data: null,
+          status: 400,
+          success: false,
+          error: `No smart rewarder contract found for chain ${chainId}`
+        };
+      }
+
+      // Prepare claim data
+      const claimData = this.prepareClaimData(filteredClaimProofs);
+
+      // Prepare the complete contract interaction data
+      return {
+        data: {
+          address: rewarder.address as Address,
+          abi: [{
+            type: 'function',
+            inputs: [
+              { name: 'users', internalType: 'address[]', type: 'address[]' },
+              { name: 'campaignIds', internalType: 'uint256[]', type: 'uint256[]' },
+              { name: 'amounts', internalType: 'uint256[]', type: 'uint256[]' },
+              { name: 'proofs', internalType: 'bytes32[][]', type: 'bytes32[][]' }
+            ],
+            name: 'claim',
+            outputs: [],
+            stateMutability: 'nonpayable'
+          }],
+          functionName: 'claim',
+          args: [
+            claimData.users,
+            claimData.campaignIds,
+            claimData.amounts,
+            claimData.proofs
+          ] as const
+        },
+        status: 200,
+        success: true
+      };
+    } catch (error) {
+      return {
+        data: null,
+        status: 500,
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error occurred'
+      };
+    }
+  }
+
+  /**
+   * Checks if a chain is supported by checking if it has a subgraph URL
+   * @param chainId The chain ID to check
+   * @returns boolean indicating if the chain is supported
+   */
+  public supportsChain(chainId: number): boolean {
+    return getSubgraphUrlByChainId(chainId) !== undefined;
+  }
+}