@explorins/pers-sdk 1.0.0-alpha.1 → 1.1.2

package/src/web3/services/web3-service.ts

@@ -0,0 +1,338 @@
+import { Web3ChainService } from '../../web3-chain';
+import { Web3Api } from '../api/web3-api';
+import { 
+  ERC20BalanceRequest, 
+  ERC1155CollectionRequest, 
+  ERC721CollectionRequest, 
+  ERC721CollectionResponse, 
+  NFTItem, 
+  Web3BalanceResponse, 
+  Web3TokenListResponse, 
+  Web3TokenResult,
+  SimpleCache
+} from '../models';
+
+export class Web3Service {
+  //temporary fix, remove when the backend supports custom gateways
+  private readonly defaultIpfsGatewayDomain = 'pers.mypinata.cloud';
+
+  // ✅ CACHE: Simple 10-second cache instance
+  private cache = new SimpleCache();
+  private cleanupInterval: NodeJS.Timeout | null = null;
+
+  constructor(
+    private web3Api: Web3Api,
+    private web3ChainService: Web3ChainService
+  ) {
+    this.cleanupInterval = setInterval(() => {
+      this.cache.cleanup();
+    }, 30 * 1000);
+  }
+
+  destroy(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.cache.clear();
+  }
+
+  async getERC20Balance(request: ERC20BalanceRequest): Promise<Web3BalanceResponse> {
+    
+    const cacheKey = `erc20_balance_${request.accountAddress}_${request.token.contractAddress}_${request.token.chainId}`;
+    
+    // ✅ CACHE CHECK: Try to get from cache first
+    const cached = this.cache.get<Web3BalanceResponse>(cacheKey);
+    if (cached) {
+      console.debug(`💾 [Web3Service] Using cached ERC20 balance for ${request.token.symbol}`);
+      return cached;
+    }
+
+    console.debug(`🔄 [Web3Service] Fetching fresh ERC20 balance for ${request.token.symbol}`);
+    
+    const rawBalance = await this.web3Api.getTokenBalance({
+      accountAddress: request.accountAddress,
+      contractAddress: request.token.contractAddress,
+      abi: request.token.abi,
+      tokenId: null, // Always null for ERC20
+      chainId: request.token.chainId
+    });
+
+    const decimals = request.token.decimals ?? 18;
+    const symbol = request.token.symbol ?? 'UNKNOWN';
+
+    const response: Web3BalanceResponse = {
+      rawBalance,
+      formattedBalance: this.formatBalance(rawBalance, decimals),
+      decimals,
+      symbol,
+      hasBalance: rawBalance > 0
+    };
+
+    // ✅ CACHE SET: Store result in cache
+    this.cache.set(cacheKey, response);
+    
+    return response;
+  }
+
+  async getERC1155Collection(request: ERC1155CollectionRequest): Promise<Web3TokenListResponse> {
+    
+        // ✅ CACHE KEY: Create unique cache key for collection request
+    const contractAddresses = request.tokens.map(t => t.contractAddress).sort().join(',');
+    const cacheKey = `erc1155_collection_${request.accountAddress}_${contractAddresses}`;
+    
+    // ✅ CACHE CHECK: Try to get from cache first
+    const cached = this.cache.get<Web3TokenListResponse>(cacheKey);
+    if (cached) {
+      console.debug(`💾 [Web3Service] Using cached ERC1155 collection for ${request.accountAddress}`);
+      return cached;
+    }
+
+    console.debug(`🔄 [Web3Service] Fetching fresh ERC1155 collection for ${request.accountAddress}`);
+    
+    const tokenResults = await Promise.all(
+      request.tokens.map(async (token) => {
+        // ✅ FIXED: Handle null metadata properly
+        const tokenIds: string[] = token.metadata?.map(m => 
+          m.tokenMetadataIncrementalId?.toString()
+        ).filter((id): id is string => id !== undefined) ?? [];
+        
+        // Check balance for each known tokenId
+        const balanceResults = await Promise.allSettled(
+          tokenIds.map(async (tokenId) => {
+            try {
+              const rawBalance = await this.web3Api.getTokenBalance({
+                accountAddress: request.accountAddress,
+                contractAddress: token.contractAddress,
+                abi: token.abi,
+                tokenId,
+                chainId: token.chainId
+              });
+
+              const decimals = token.decimals ?? 0; // ERC1155 usually no decimals
+              
+              return {
+                tokenId,
+                balance: rawBalance,
+                formattedBalance: this.formatBalance(rawBalance, decimals),
+                hasBalance: rawBalance > 0,
+                // ✅ FIXED: Convert null to undefined for findMetadata
+                metadata: this.findMetadata(token.metadata ?? undefined, tokenId)
+              };
+            } catch (error) {
+              console.warn(`Failed to get balance for token ${token.contractAddress}:${tokenId}`, error);
+              return null; // Skip failed tokens
+            }
+          })
+        );
+
+        // Filter successful results with balance > 0
+        const successfulResults: Web3TokenResult[] = [];
+        for (const result of balanceResults) {
+          if (result.status === 'fulfilled' && result.value !== null && result.value.hasBalance) {
+            successfulResults.push(result.value);
+          }
+        }
+
+        return {
+          token,
+          results: successfulResults
+        };
+      })
+    );
+
+    const response: Web3TokenListResponse = {
+      accountAddress: request.accountAddress,
+      tokens: tokenResults.filter(t => t.results.length > 0)
+    };
+
+    // ✅ CACHE SET: Store complete collection result
+    this.cache.set(cacheKey, response);
+    
+    return response;
+  }
+
+  async getERC721Collection(request: ERC721CollectionRequest): Promise<ERC721CollectionResponse> {
+    
+        // ✅ CACHE KEY: Create unique cache key for NFT collection
+    const contractAddresses = request.nftContracts.map(t => t.contractAddress).sort().join(',');
+    const maxNFTs = request.maxNFTsPerContract || 50;
+    const cacheKey = `erc721_collection_${request.accountAddress}_${contractAddresses}_${maxNFTs}`;
+    
+    // ✅ CACHE CHECK: Try to get from cache first
+    const cached = this.cache.get<ERC721CollectionResponse>(cacheKey);
+    if (cached) {
+      console.debug(`💾 [Web3Service] Using cached ERC721 collection for ${request.accountAddress}`);
+      return cached;
+    }
+
+    console.debug(`🔄 [Web3Service] Fetching fresh ERC721 collection for ${request.accountAddress}`);
+    
+    const startTime = Date.now();
+    
+    const contractResults = await Promise.all(
+      request.nftContracts.map(async (token) => {
+        try {
+          const totalBalance = await this.web3Api.getTokenBalance({
+            accountAddress: request.accountAddress,
+            contractAddress: token.contractAddress,
+            abi: token.abi,
+            tokenId: null,
+            chainId: token.chainId
+          });
+          
+          if (totalBalance === 0) {
+            return {
+              token,
+              totalNFTs: 0,
+              nfts: [],
+              hasMore: false
+            };
+          }
+
+          const nftsToLoad = Math.min(totalBalance, maxNFTs);
+          
+          const nftResults = await Promise.allSettled(
+            Array.from({ length: nftsToLoad }, async (_, index): Promise<NFTItem | null> => {
+              try {
+                const tokenId = await this.web3Api.getTokenOfOwnerByIndex({
+                  contractAddress: token.contractAddress,
+                  abi: token.abi,
+                  accountAddress: request.accountAddress,
+                  tokenIndex: index,
+                  chainId: token.chainId
+                });
+                
+                const tokenUri = await this.web3Api.getTokenUri({
+                  contractAddress: token.contractAddress,
+                  abi: token.abi,
+                  tokenId,
+                  chainId: token.chainId
+                });
+                
+                const metadata = await this.fetchMetadata(tokenUri, token.chainId);
+                
+                const nftItem: NFTItem = {
+                  tokenId,
+                  name: metadata?.name || `Token #${tokenId}`,
+                  description: metadata?.description || '',
+                  imageUrl: await this.resolveIPFSUrl(metadata?.image || '', token.chainId),
+                  rawBalance: 1,
+                  formattedBalance: '1',
+                  hasBalance: true,
+                  metadata,
+                  tokenIndex: index
+                };
+                
+                return nftItem;
+                
+              } catch (error) {
+                console.warn(`Failed to load NFT at index ${index} for ${token.symbol}:`, error);
+                return null;
+              }
+            })
+          );
+          
+          // ✅ FIXED: Usar tipo específico NFTItem
+          const successfulNFTs = nftResults
+            .filter((result): result is PromiseFulfilledResult<NFTItem | null> => 
+              result.status === 'fulfilled' && result.value !== null
+            )
+            .map(result => result.value as NFTItem);
+          
+          return {
+            token,
+            totalNFTs: totalBalance,
+            nfts: successfulNFTs,
+            hasMore: totalBalance > maxNFTs
+          };
+          
+        } catch (error) {
+          console.error(`Failed to load NFT collection for ${token.symbol}:`, error);
+          return {
+            token,
+            totalNFTs: 0,
+            nfts: [],
+            hasMore: false
+          };
+        }
+      })
+    );
+    
+    const totalNFTs = contractResults.reduce((sum, contract) => sum + contract.nfts.length, 0);
+    const loadingTime = Date.now() - startTime;
+    
+    const response: ERC721CollectionResponse = {
+      accountAddress: request.accountAddress,
+      contracts: contractResults,
+      summary: {
+        totalContracts: request.nftContracts.length,
+        totalNFTs,
+        loadingTime
+      }
+    };
+
+    // ✅ CACHE SET: Store complete collection response
+    this.cache.set(cacheKey, response);
+    
+    return response;
+  }
+
+  // ==========================================
+  // HELPER METHODS
+  // ==========================================
+
+  private formatBalance(rawBalance: number, decimals: number): string {
+    const balance = rawBalance / Math.pow(10, decimals);
+    
+    return balance.toLocaleString('en-US', {
+      minimumFractionDigits: 0,
+      maximumFractionDigits: decimals > 0 ? 2 : 0
+    });
+  }
+
+  // ✅ FIXED: Update method signature to handle null properly
+  private findMetadata(metadata: any[] | undefined, tokenId: string | null): any | null {
+    if (!metadata || tokenId === null) return null;
+    return metadata.find(m => 
+      m.tokenMetadataIncrementalId?.toString() === tokenId
+    ) || null;
+  }
+
+  private async fetchMetadata(uri: string, chainId: number): Promise<any> {
+    try {
+      const httpUrl = await this.resolveIPFSUrl(uri, chainId);
+      const response = await fetch(httpUrl); 
+      
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      
+      return await response.json();
+    } catch (error) {
+      console.warn('Failed to fetch NFT metadata:', error);
+      return null;
+    }
+  }
+
+  private async getIpfsGatewayDomain(chainId: number): Promise<string> {
+    try {
+      const chainData = await this.web3ChainService.getChainDataWithCache(chainId);
+      return chainData.ipfsGatewayDomain || this.defaultIpfsGatewayDomain;
+    } catch (error) {
+      console.warn(`Failed to get chain data for chainId ${chainId}, using default IPFS gateway:`, error);
+      return this.defaultIpfsGatewayDomain;
+    }
+  }
+
+  private async resolveIPFSUrl(url: string, chainId: number): Promise<string> {
+    if (!url) return '';
+    
+    if (url.startsWith('ipfs://')) {
+      const gatewayDomain = await this.getIpfsGatewayDomain(chainId);
+      return `https://${gatewayDomain}/ipfs/${url.slice(7)}`;
+    }
+    
+    return url;
+  }
+}

package/src/web3-chain/api/web3-chain-api.ts

@@ -0,0 +1,42 @@
+import { PersApiClient } from '../../core/pers-api-client';
+import { ChainData } from '../models';
+
+/**
+ * Platform-Agnostic Web3 Chain API Client
+ * 
+ * Handles blockchain chain operations using the PERS backend.
+ * Uses @explorins/web3-ts types for perfect framework compatibility.
+ */
+export class Web3ChainApi {
+  constructor(private apiClient: PersApiClient) {}
+
+  private basePath = '/chains';
+
+  // ==========================================
+  // PUBLIC OPERATIONS
+  // ==========================================
+
+  /**
+   * PUBLIC: Get chain data by chain ID
+   * ✅ Returns ChainData exactly as framework expects from @explorins/web3-ts
+   */
+  async getChainData(chainId: number): Promise<ChainData> {
+  try {
+
+    console.log('🔍 [Web3ChainApi] Fetching chain data for chainId:', chainId);
+    const response = await this.apiClient.get<ChainData>(`${this.basePath}/${chainId}`);
+
+    if (!response) {
+      throw new Error(`No chain data received for chainId: ${chainId}`);
+    }
+
+    return response;
+  } catch (error) {
+    console.error('❌ [Web3ChainApi] Failed to get chain data:', {
+      chainId,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    throw error;
+  }
+}
+}

package/src/web3-chain/index.ts

@@ -0,0 +1,27 @@
+import { PersApiClient } from '../core/pers-api-client';
+import { Web3ChainApi } from './api/web3-chain-api';
+import { Web3ProviderService } from './services/provider.service';
+
+import { Web3ChainService } from './services/web3-chain-service';
+
+export function createWeb3ChainSDK(apiClient: PersApiClient, providerService: Web3ProviderService) {
+  const web3ChainApi = new Web3ChainApi(apiClient);
+  const web3ChainService = new Web3ChainService(web3ChainApi, providerService); // ✅ DIRECT INJECTION
+  
+  return {
+    // ✅ REPLICA: Same methods as framework
+    getChainDataById: (chainId: number) => web3ChainService.getChainDataById(chainId),
+    getWeb3ByChainId: (chainId: number) => web3ChainService.getWeb3ByChainId(chainId),
+    
+    api: web3ChainApi,
+    service: web3ChainService
+  };
+}
+
+// ✅ EXPORT: All models and service
+export { Web3ChainApi } from './api/web3-chain-api';
+export { Web3ChainService } from './services/web3-chain-service';
+export { Web3ProviderService } from './services/provider.service';
+export * from './models';
+export type { ChainData } from './models';
+export * from '../shared/interfaces/pers-shared-lib.interfaces';

package/src/web3-chain/models/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Web3 Chain Domain Models
+ * 
+ * Minimal interface definitions matching framework usage exactly.
+ * Local ChainData interface to avoid external dependency issues.
+ */
+
+import type { Web3 } from "web3";
+
+// ✅ FIXED: Local ChainData interface instead of problematic external import
+export interface ChainData {
+    name: string;
+    shortName?: string;
+    chain?: string;
+    network?: string;
+    chainId?: number;
+    networkId?: number | null;
+    rpcUrl: string;
+    explorerUrl?: string;
+    authHeader?: string;
+    nativeCurrency?: any;
+    chainType: ChainType;
+    ipfsGatewayDomain?: string;
+}
+
+export type ChainType = typeof ChainTypes[keyof typeof ChainTypes];
+
+export const ChainTypes = {
+  PUBLIC: 'PUBLIC',
+  PRIVATE: 'PRIVATE'
+} as const;
+
+export interface CachedWeb3Instance {
+  instance: Web3;
+  createdAt: number;
+  chainId: number;
+}
+
+export interface CachedChainInstance {
+  web3Instance: Web3;
+  chainData: ChainData;
+  createdAt: number;
+  chainId: number;
+}
+

package/src/web3-chain/services/getWeb3FCD.service.ts

@@ -0,0 +1,47 @@
+
+//IMPORTANT//
+//This function is temporary so we install ethers just to make it work, once we delete this function we must uninstall Ethers
+
+import { ChainData } from "@explorins/web3-ts";
+import { FetchRequest, JsonRpcProvider } from "ethers";
+
+export const getWeb3ProviderFromChainData = (
+  chainData: ChainData,
+  timeout = 15000,
+  customUserAgentName = '',
+  tokenRefresher?: () => Promise<string>
+) => {
+
+  // Fixed ethers provider setup for authenticated requests
+  let ethersProvider: JsonRpcProvider;
+
+  if (chainData.authHeader) {
+    // For authenticated requests, create a custom FetchRequest
+    const fetchRequest = new FetchRequest(chainData.rpcUrl);
+    fetchRequest.timeout = timeout;
+    fetchRequest.setHeader('Authorization', chainData.authHeader);
+    fetchRequest.setHeader('Content-Type', 'application/json');
+
+    if (customUserAgentName) {
+      fetchRequest.setHeader('User-Agent', customUserAgentName);
+    }
+
+    // Create provider with the configured FetchRequest
+    ethersProvider = new JsonRpcProvider(fetchRequest, undefined, {
+      staticNetwork: false,
+      polling: false, // Disable polling for better Lambda performance
+    });
+  } else {
+    // For public chains, use simple URL-based provider
+    ethersProvider = new JsonRpcProvider(chainData.rpcUrl, undefined, {
+      staticNetwork: false,
+      polling: false,
+    });
+  }
+
+  return {
+    web3Provider: null,
+    ethersProvider: ethersProvider,
+    isAuthenticated: !!chainData.authHeader,
+  };
+};

package/src/web3-chain/services/provider.service.ts

@@ -0,0 +1,123 @@
+import Web3 from "web3";
+import { ChainData, ChainType, ChainTypes } from "@explorins/web3-ts";
+import { PublicHttpProviderService } from "./public-http-provider.service";
+import { getWeb3ProviderFromChainData } from "./getWeb3FCD.service";
+
+
+export class Web3ProviderService {
+  
+    private _web3: Web3 | null = null;
+    private _currentChainId: number | null = null;
+  
+    constructor(
+        private readonly publicHttpProviderService: PublicHttpProviderService,
+    ) {
+    }
+  
+    public async getWeb3(chainId: number, chainType: ChainType, privateChainData: ChainData | null = null) {
+        if (!this._web3 || this._currentChainId !== chainId) {
+              
+            if(!chainId) throw new Error('ChainId not found')
+  
+            try {
+                this._currentChainId = chainId;
+                const provider = await this.getWeb3ByChainId(chainId, chainType, privateChainData);
+                this._web3 = this.convertToWeb3(provider);
+            } catch (error) {  
+                console.error('Error getting web3 connection from chain id ' + chainId , error)
+                throw new Error('Error getting web3 connection from chain id ' + chainId)
+            }
+        }
+        return this._web3 as Web3;
+    }
+  
+    // Keep return type as 'any' to avoid TypeScript errors while still being adapted later
+    private getWeb3ByChainId(chainId: number, chainType: ChainType, privateChainData: ChainData | null = null): any {
+        // Rest of the method remains the same
+        if(chainType === ChainTypes.PRIVATE && privateChainData) {
+            //const privateProvider = this.privateChainProviderService.getProviderFromChainData(privateChainData)
+            const privateProvider = getWeb3ProviderFromChainData(privateChainData);
+            
+            if(!privateProvider || privateProvider instanceof Error) throw new Error('Error getting web3 provider');
+              
+            
+            return privateProvider;
+  
+        } else {
+            
+            const publicProvider = this.publicHttpProviderService.getProvider(chainId)
+            if(!publicProvider || publicProvider instanceof Error) throw new Error('Error getting web3 provider');
+              
+            return publicProvider;
+        }
+    }
+
+    private convertToWeb3(provider: unknown): Web3 {
+        if (provider instanceof Web3) {
+            return provider as Web3;
+        }
+
+        if (provider && typeof provider === 'object' && 'web3Provider' in provider) {
+            const providerObj = provider as { 
+                web3Provider?: unknown; 
+                ethersProvider?: any;
+                isAuthenticated?: boolean;
+            };
+            
+            // If we want to user the web3Provider directly:
+            /*if (providerObj.web3Provider) {
+                return new Web3(providerObj.web3Provider as never);
+            }*/
+            
+            if (providerObj.ethersProvider) {
+
+                const url = this.extractUrlFromEthersProvider(providerObj.ethersProvider);
+                const headers = this.extractHeadersFromEthersProvider(providerObj.ethersProvider);
+                
+                const web3 = new Web3(url);
+                const currentProvider = web3.currentProvider as unknown as Record<string, unknown>;
+
+                if (currentProvider) {
+                    currentProvider['url'] = url;
+                    
+                    if (headers && Object.keys(headers).length > 0) {
+                        currentProvider['request'] = async (payload: Record<string, unknown>): Promise<Record<string, unknown>> => {
+                            const response = await fetch(url, {
+                                method: 'POST',
+                                headers: {
+                                    'Content-Type': 'application/json',
+                                    ...headers
+                                },
+                                body: JSON.stringify(payload)
+                            });
+                            
+                            if (!response.ok) {
+                                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+                            }
+                            
+                            return await response.json() as Record<string, unknown>;
+                        };
+                    }
+                }
+
+                return web3;
+            }
+        }
+
+        return new Web3(provider as never);
+    }
+
+    
+    private extractUrlFromEthersProvider(ethersProvider: any): string {
+        return ethersProvider.connection?.url || 
+               ethersProvider._getConnection?.()?.url || 
+               ethersProvider.url || 
+               '';
+    }
+
+    private extractHeadersFromEthersProvider(ethersProvider: any): Record<string, string> {
+        return ethersProvider.connection?.headers || 
+               ethersProvider._getConnection?.()?.headers || 
+               {};
+    }
+}

package/src/web3-chain/services/public-http-provider.service.ts

@@ -0,0 +1,26 @@
+import type { PublicWeb3ProviderData } from "@explorins/web3/types";
+import type Web3 from "web3";
+
+import { adaptToWeb3, getPublicWeb3ConnectionFromChainId } from "@explorins/web3-ts";
+
+export class PublicHttpProviderService {
+    private $providerData: PublicWeb3ProviderData | null;
+
+    constructor(providerData: PublicWeb3ProviderData | null = null) {
+        this.$providerData = providerData;
+    }
+
+    public getProvider(chainId: number): Web3 {
+        const providerApiKey = this.$providerData ? this.$providerData?.apiKey || null : null;
+        if (!providerApiKey) throw new Error('Provider API key not found');
+        
+        try {
+            // Use the adapter function instead of unsafe type casting
+            const provider = getPublicWeb3ConnectionFromChainId(chainId, 'infuraHttp', providerApiKey);
+            return adaptToWeb3(provider);
+        } catch (error) {
+            console.error('Error getting web3 connection from chain id ' + chainId, error);
+            throw new Error('Error getting web3 connection from chain id ' + chainId);
+        }
+    }
+}