@passly/passly-sdk 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passly/passly-sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
    "type": "module",
   "description": "Official SDK for Passly identity protocol - social identity verification for Web3",
   "main": "src/index.js",

package/src/index.js

@@ -13,6 +13,7 @@ import { ethers } from 'ethers';
  * - Historical verification data access  
  * - Platform configuration queries
  * - Referral system integration
+ * - Leaderboard and ranking system
  */
 class PasslySDK {
   /**
@@ -22,6 +23,7 @@ class PasslySDK {
    * @param {string} [config.platformsAddress] - Override for the Platforms contract address
    * @param {string} [config.archivesAddress] - Override for the Archives contract address  
    * @param {string} [config.rewardsAddress] - Override for the Rewards contract address
+   * @param {string} [config.leaderboardAddress] - Override for the Leaderboard contract address
    * @param {ethers.providers.Provider} [config.provider] - Optional ethers provider
    * @param {ethers.Signer} [config.signer] - Optional ethers signer for write operations
    * @param {string} [config.network] - Network name for default addresses
@@ -50,7 +52,8 @@ class PasslySDK {
       passly: config.contractAddress || '0x9a1b12c6E794dE70b1Bd73a74f81eF5A41Fb7Cb3',
       platforms: config.platformsAddress || '0x0f1ff42F6f9C2d8D1C054aF7c03cf5e449f0Bc15',
       archives: config.archivesAddress || '0xa26A0eAE99A6ccD8f82dC6Cfbd35ccCeebf3BcFf',
-      rewards: config.rewardsAddress || '0x993d28480D5f9bf457FAb67D58D696e3c5655031'
+      rewards: config.rewardsAddress || '0x993d28480D5f9bf457FAb67D58D696e3c5655031',
+      leaderboard: config.leaderboardAddress || null // Add when deployed
     };
 
     // Contract ABIs
@@ -93,6 +96,24 @@ class PasslySDK {
         "function validateReferralCode(string calldata referralCode) external view returns (bool isValid, uint256 ownerPassportId)",
         "function getUserReferrals(uint256 passportId) external view returns (string[] memory)",
         "function getPointConfig() external view returns (uint256 dailyHolding, uint256 referral, uint256 referee)"
+      ],
+
+      leaderboard: [
+        // Global leaderboard functions
+        "function getTopEntries(uint256 count) external view returns (tuple(uint256 passportId, address owner, uint256 totalScore, uint256 holdingPoints, uint256 platformPoints, uint256 referralPoints, uint256 verificationCount, string category, uint256 lastUpdated, uint256 rank, uint256 previousRank)[] memory)",
+        "function getPassportEntry(uint256 passportId) external view returns (tuple(uint256 passportId, address owner, uint256 totalScore, uint256 holdingPoints, uint256 platformPoints, uint256 referralPoints, uint256 verificationCount, string category, uint256 lastUpdated, uint256 rank, uint256 previousRank))",
+        "function getPassportRank(uint256 passportId) external view returns (uint256)",
+        "function getPassportScore(uint256 passportId) external view returns (uint256)",
+        "function isPassportInLeaderboard(uint256 passportId) external view returns (bool)",
+        
+        // Category-specific functions
+        "function getTopEntriesByCategory(string calldata category, uint256 count) external view returns (tuple(uint256 passportId, address owner, uint256 totalScore, uint256 holdingPoints, uint256 platformPoints, uint256 referralPoints, uint256 verificationCount, string category, uint256 lastUpdated, uint256 rank, uint256 previousRank)[] memory)",
+        "function getPassportEntryByCategory(uint256 passportId, string calldata category) external view returns (tuple(uint256 passportId, address owner, uint256 totalScore, uint256 holdingPoints, uint256 platformPoints, uint256 referralPoints, uint256 verificationCount, string category, uint256 lastUpdated, uint256 rank, uint256 previousRank))",
+        "function getPassportRankByCategory(uint256 passportId, string calldata category) external view returns (uint256)",
+        
+        // Leaderboard statistics
+        "function getLeaderboardStats(string calldata category) external view returns (uint256 totalEntries, bool isActive, uint256 maxEntries)",
+        "function getSupportedCategories() external view returns (string[] memory)"
       ]
     };
 
@@ -113,6 +134,10 @@ class PasslySDK {
       this.contracts.rewards = new ethers.Contract(addresses.rewards, abis.rewards, contractProvider);
     }
 
+    if (addresses.leaderboard) {
+      this.contracts.leaderboard = new ethers.Contract(addresses.leaderboard, abis.leaderboard, contractProvider);
+    }
+
     this.config = { ...config, addresses };
     this.isConnected = true;
     return this;
@@ -149,6 +174,26 @@ class PasslySDK {
     throw new Error('Invalid address or passport ID');
   }
 
+  /**
+   * Helper to format leaderboard entry from contract response
+   * @private
+   */
+  _formatLeaderboardEntry(entry) {
+    return {
+      passportId: entry.passportId.toNumber(),
+      owner: entry.owner,
+      totalScore: entry.totalScore.toNumber(),
+      holdingPoints: entry.holdingPoints.toNumber(),
+      platformPoints: entry.platformPoints.toNumber(),
+      referralPoints: entry.referralPoints.toNumber(),
+      verificationCount: entry.verificationCount.toNumber(),
+      category: entry.category,
+      lastUpdated: new Date(entry.lastUpdated.toNumber() * 1000),
+      rank: entry.rank.toNumber(),
+      previousRank: entry.previousRank.toNumber()
+    };
+  }
+
   // =============================================================================
   // PASSPORT & IDENTITY FUNCTIONS
   // =============================================================================
@@ -422,6 +467,244 @@ class PasslySDK {
     }
   }
 
+  // =============================================================================
+  // LEADERBOARD FUNCTIONS
+  // =============================================================================
+
+  /**
+   * Get top entries from global leaderboard
+   * @param {number} [count=10] - Number of entries to return
+   * @returns {Promise<Array|null>} - Top leaderboard entries or null if no leaderboard contract
+   */
+  async getTopEntries(count = 10) {
+    this._ensureConnected();
+    
+    if (!this.contracts.leaderboard) return null;
+    
+    try {
+      const entries = await this.contracts.leaderboard.getTopEntries(count);
+      return entries.map(entry => this._formatLeaderboardEntry(entry));
+    } catch (error) {
+      console.warn('Failed to get top entries:', error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Get leaderboard entry for a specific passport
+   * @param {string|number} addressOrPassportId - Wallet address or passport ID
+   * @returns {Promise<Object|null>} - Leaderboard entry or null if not found/no leaderboard contract
+   */
+  async getPassportLeaderboardEntry(addressOrPassportId) {
+    this._ensureConnected();
+    
+    if (!this.contracts.leaderboard) return null;
+    
+    try {
+      const passportId = await this._resolvePassportId(addressOrPassportId);
+      const entry = await this.contracts.leaderboard.getPassportEntry(passportId);
+      return this._formatLeaderboardEntry(entry);
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Get global rank for a passport
+   * @param {string|number} addressOrPassportId - Wallet address or passport ID
+   * @returns {Promise<number|null>} - Global rank (1 = first place, 0 = not ranked) or null if no leaderboard contract
+   */
+  async getGlobalRank(addressOrPassportId) {
+    this._ensureConnected();
+    
+    if (!this.contracts.leaderboard) return null;
+    
+    try {
+      const passportId = await this._resolvePassportId(addressOrPassportId);
+      const rank = await this.contracts.leaderboard.getPassportRank(passportId);
+      return rank.toNumber();
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Get current leaderboard score for a passport
+   * @param {string|number} addressOrPassportId - Wallet address or passport ID
+   * @returns {Promise<number|null>} - Current score or null if not found/no leaderboard contract
+   */
+  async getLeaderboardScore(addressOrPassportId) {
+    this._ensureConnected();
+    
+    if (!this.contracts.leaderboard) return null;
+    
+    try {
+      const passportId = await this._resolvePassportId(addressOrPassportId);
+      const score = await this.contracts.leaderboard.getPassportScore(passportId);
+      return score.toNumber();
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Check if passport is in the leaderboard
+   * @param {string|number} addressOrPassportId - Wallet address or passport ID
+   * @returns {Promise<boolean>} - Whether passport is ranked in leaderboard
+   */
+  async isInLeaderboard(addressOrPassportId) {
+    this._ensureConnected();
+    
+    if (!this.contracts.leaderboard) return false;
+    
+    try {
+      const passportId = await this._resolvePassportId(addressOrPassportId);
+      return await this.contracts.leaderboard.isPassportInLeaderboard(passportId);
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Get top entries from a specific category leaderboard
+   * @param {string} category - Category name (e.g., "creator", "developer") or "global"
+   * @param {number} [count=10] - Number of entries to return
+   * @returns {Promise<Array|null>} - Top entries for category or null if no leaderboard contract
+   */
+  async getTopEntriesByCategory(category, count = 10) {
+    this._ensureConnected();
+    
+    if (!this.contracts.leaderboard) return null;
+    
+    try {
+      const entries = await this.contracts.leaderboard.getTopEntriesByCategory(category, count);
+      return entries.map(entry => this._formatLeaderboardEntry(entry));
+    } catch (error) {
+      console.warn(`Failed to get top entries for category ${category}:`, error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Get passport's rank in a specific category
+   * @param {string|number} addressOrPassportId - Wallet address or passport ID
+   * @param {string} category - Category name
+   * @returns {Promise<number|null>} - Rank in category (1 = first place, 0 = not ranked) or null if no leaderboard contract
+   */
+  async getCategoryRank(addressOrPassportId, category) {
+    this._ensureConnected();
+    
+    if (!this.contracts.leaderboard) return null;
+    
+    try {
+      const passportId = await this._resolvePassportId(addressOrPassportId);
+      const rank = await this.contracts.leaderboard.getPassportRankByCategory(passportId, category);
+      return rank.toNumber();
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Get passport's entry in a specific category leaderboard
+   * @param {string|number} addressOrPassportId - Wallet address or passport ID
+   * @param {string} category - Category name
+   * @returns {Promise<Object|null>} - Category leaderboard entry or null if not found/no leaderboard contract
+   */
+  async getCategoryLeaderboardEntry(addressOrPassportId, category) {
+    this._ensureConnected();
+    
+    if (!this.contracts.leaderboard) return null;
+    
+    try {
+      const passportId = await this._resolvePassportId(addressOrPassportId);
+      const entry = await this.contracts.leaderboard.getPassportEntryByCategory(passportId, category);
+      return this._formatLeaderboardEntry(entry);
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Get statistics for a leaderboard category
+   * @param {string} category - Category name or "global"
+   * @returns {Promise<Object|null>} - Leaderboard statistics or null if no leaderboard contract
+   */
+  async getLeaderboardStats(category) {
+    this._ensureConnected();
+    
+    if (!this.contracts.leaderboard) return null;
+    
+    try {
+      const [totalEntries, isActive, maxEntries] = await this.contracts.leaderboard.getLeaderboardStats(category);
+      
+      return {
+        category,
+        totalEntries: totalEntries.toNumber(),
+        isActive,
+        maxEntries: maxEntries.toNumber()
+      };
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Get all supported leaderboard categories
+   * @returns {Promise<string[]>} - Array of supported category names
+   */
+  async getLeaderboardCategories() {
+    this._ensureConnected();
+    
+    if (!this.contracts.leaderboard) return [];
+    
+    try {
+      return await this.contracts.leaderboard.getSupportedCategories();
+    } catch (error) {
+      return [];
+    }
+  }
+
+  /**
+   * Get comprehensive leaderboard data for a passport
+   * @param {string|number} addressOrPassportId - Wallet address or passport ID
+   * @returns {Promise<Object|null>} - Complete leaderboard information or null if no leaderboard contract
+   */
+  async getCompleteLeaderboardData(addressOrPassportId) {
+    this._ensureConnected();
+    
+    if (!this.contracts.leaderboard) return null;
+    
+    try {
+      const passportId = await this._resolvePassportId(addressOrPassportId);
+      
+      // Get passport's category from passport data
+      const passportData = await this.getPassport(addressOrPassportId);
+      if (!passportData) return null;
+      
+      const category = passportData.category;
+      
+      // Gather all leaderboard data in parallel
+      const [globalEntry, categoryEntry, isInBoard, categories] = await Promise.all([
+        this.getPassportLeaderboardEntry(passportId).catch(() => null),
+        this.getCategoryLeaderboardEntry(passportId, category).catch(() => null),
+        this.isInLeaderboard(passportId).catch(() => false),
+        this.getLeaderboardCategories().catch(() => [])
+      ]);
+      
+      return {
+        passportId,
+        category,
+        isInLeaderboard: isInBoard,
+        global: globalEntry,
+        categorySpecific: categoryEntry,
+        availableCategories: categories
+      };
+    } catch (error) {
+      return null;
+    }
+  }
+
   // =============================================================================
   // HISTORICAL DATA FUNCTIONS
   // =============================================================================
@@ -530,7 +813,7 @@ class PasslySDK {
   }
 
   /**
-   * Get supported categories
+   * Get supported categories (from Passly contract)
    * @returns {Promise<string[]>} - List of supported categories
    */
   async getSupportedCategories() {
@@ -597,15 +880,17 @@ class PasslySDK {
     const passport = await this.getPassport(address);
     if (!passport) return null;
 
-    const [pointBreakdown, referralInfo] = await Promise.all([
+    const [pointBreakdown, referralInfo, leaderboardData] = await Promise.all([
       this.getPointBreakdown(address).catch(() => null),
-      this.getReferralInfo(address).catch(() => null)
+      this.getReferralInfo(address).catch(() => null),
+      this.getCompleteLeaderboardData(address).catch(() => null)
     ]);
 
     return {
       ...passport,
       points: pointBreakdown,
-      referrals: referralInfo
+      referrals: referralInfo,
+      leaderboard: leaderboardData
     };
   }
 
@@ -683,9 +968,10 @@ class PasslySDK {
   async getSystemConfig() {
     this._ensureConnected();
     
-    const [supportedPlatforms, supportedCategories] = await Promise.all([
+    const [supportedPlatforms, supportedCategories, leaderboardCategories] = await Promise.all([
       this.getSupportedPlatforms().catch(() => []),
-      this.getSupportedCategories().catch(() => [])
+      this.getSupportedCategories().catch(() => []),
+      this.getLeaderboardCategories().catch(() => [])
     ]);
 
     let pointConfig = null;
@@ -705,12 +991,14 @@ class PasslySDK {
     return {
       supportedPlatforms,
       supportedCategories,
+      leaderboardCategories,
       pointConfig,
       contracts: {
         passly: this.config.addresses.passly,
         platforms: this.config.addresses.platforms || null,
         archives: this.config.addresses.archives || null,
-        rewards: this.config.addresses.rewards || null
+        rewards: this.config.addresses.rewards || null,
+        leaderboard: this.config.addresses.leaderboard || null
       }
     };
   }