@glowlabs-org/utils 0.1.4 → 0.2.0

package/src/lib/create-weekly-report/index.ts

@@ -149,11 +149,6 @@ export async function createWeeklyReportLegacy(args: CreateWeeklyReportArgs) {
         usdgWeight <= 0 &&
         rewardSplit.usdgSplitPercent > 0
       ) {
-        console.log(
-          farm.carbonCreditsProduced,
-          usdgWeight,
-          rewardSplit.usdgSplitPercent
-        );
         throw new Error(
           "USDG weight is less than 0 and carbon credits produced is greater than 0"
         );
@@ -163,11 +158,6 @@ export async function createWeeklyReportLegacy(args: CreateWeeklyReportArgs) {
         glowWeight <= 0 &&
         rewardSplit.glowSplitPercent > 0
       ) {
-        console.log(
-          farm.weeklyPayment,
-          glowWeight,
-          rewardSplit.glowSplitPercent
-        );
         throw new Error(
           "Glow weight is less than 0 and weekly payment is greater than 0"
         );
@@ -178,11 +168,6 @@ export async function createWeeklyReportLegacy(args: CreateWeeklyReportArgs) {
         usdgWeight <= 0 &&
         rewardSplit.usdgSplitPercent > 0
       ) {
-        console.log(
-          farm.carbonCreditsProduced,
-          usdgWeight.toString(),
-          rewardSplit.usdgSplitPercent
-        );
         throw new Error(
           `USDG weight is less than or equal to 0 and carbon credits produced is greater than 0 for farm ${farm.shortId}`
         );
@@ -192,11 +177,6 @@ export async function createWeeklyReportLegacy(args: CreateWeeklyReportArgs) {
         glowWeight <= 0 &&
         rewardSplit.glowSplitPercent > 0
       ) {
-        console.log(
-          farm.weeklyPayment,
-          glowWeight.toString(),
-          rewardSplit.glowSplitPercent
-        );
         throw new Error(
           `Glow weight is less than or equal to 0 and weekly payment is greater than 0 for farm ${farm.shortId}`
         );
@@ -374,6 +354,7 @@ export async function createWeeklyReport({
 }: CreateWeeklyReportArgs) {
   const map = new Map<string, MerkleLeaf>();
 
+  // Fetch active farms for the week (source of truth) and audits for the week.
   const [apiResponse, auditsRes] = await Promise.all([
     fetchFarmsForWeek(week, gcaUrls, apiUrl),
     axios.get<Audit[]>(
@@ -381,38 +362,119 @@ export async function createWeeklyReport({
     ),
   ]);
 
-  const farms = apiResponse.filteredFarms;
-  const audits = auditsRes.data;
+  const farms = apiResponse.filteredFarms; // List of farms active this week.
+  const audits = auditsRes.data; // Audits potentially containing adjusted credits.
   const rawData = apiResponse.rawData;
 
+  // Map to store the final adjusted credit (as bigint) for each active farm shortId.
   const shortIdToAdjustedCredit = new Map<string, bigint>();
+  // Set to track shortIds that have been assigned a credit from a valid audit to prevent duplicates.
+  const processedAuditShortIds = new Set<string>();
+  // Set of shortIds from the active farms list for quick lookup.
+  const farmShortIds = new Set(farms.map((f) => String(f.shortId)));
 
+  // Process each audit to extract adjusted credit values for active farms.
   for (const audit of audits) {
     const activeShortIds = audit.activeShortIds ?? [];
     const adjustedCredit =
       audit.summary?.carbonFootprintAndProduction?.adjustedWeeklyCarbonCredit?.trim();
 
+    // Basic validation: Ensure the audit has a valid numeric credit and lists associated shortIds.
     if (!adjustedCredit || !NUMERIC_REGEX.test(adjustedCredit))
       throw new Error(
         `Invalid adjustedWeeklyCarbonCredit for audit ${audit.id}`
       );
     if (activeShortIds.length === 0)
-      throw new Error(`audit ${audit.id} has empty activeShortIds`);
+      throw new Error(`Audit ${audit.id} has empty activeShortIds`);
+
+    // Separate the shortIds listed in the audit into those that are active this week and those that are not.
+    const auditActiveFarmSids: string[] = [];
+    const auditInactiveFarmSids: string[] = [];
+    for (const sid of activeShortIds) {
+      const sidString = String(sid);
+      if (farmShortIds.has(sidString)) {
+        auditActiveFarmSids.push(sidString);
+      } else {
+        auditInactiveFarmSids.push(sidString);
+      }
+    }
+
+    // --- Audit Validity Checks ---
+
+    // Data Integrity Check: An audit for credit distribution should not mix active and inactive farms for the current week.
+    if (auditActiveFarmSids.length > 0 && auditInactiveFarmSids.length > 0) {
+      throw new Error(
+        `Audit ${
+          audit.id
+        } for week ${week} contains a mix of active farms (${auditActiveFarmSids.join(
+          ", "
+        )}) and inactive farms (${auditInactiveFarmSids.join(
+          ", "
+        )}). Audits should only contain active farms when distributing credits.`
+      );
+    }
 
-    const splitValue = new Decimal(adjustedCredit).div(activeShortIds.length);
+    // Skip Audit: If the audit only contains shortIds that are not active this week, it's irrelevant for this report.
+    if (auditActiveFarmSids.length === 0) {
+      continue; // Move to the next audit.
+    }
+
+    // --- Process Valid Audit for Active Farms ---
+
+    // Calculate the credit share per active farm within this audit.
+    const splitValue = new Decimal(adjustedCredit).div(
+      auditActiveFarmSids.length // Divide only by the count of *active* farms found in this audit.
+    );
+
+    // Sanity Check: Ensure the calculated split is not zero.
     if (splitValue.isZero())
       throw new Error(
-        `Zero adjustedWeeklyCarbonCredit split in audit ${audit.id}`
+        `Zero adjustedWeeklyCarbonCredit split for active farms in audit ${audit.id}`
       );
 
+    // Convert the decimal split value to a bigint using the defined precision.
     const splitBigInt = toBigInt(splitValue, USDG_WEIGHT_DECIMAL_PRECISION);
-    for (const sid of activeShortIds)
-      shortIdToAdjustedCredit.set(String(sid), splitBigInt);
+
+    // Dust Check: Ensure that the conversion to bigint didn't truncate the value to zero.
+    if (splitBigInt === BigInt(0)) {
+      throw new Error(
+        `Adjusted credit split for audit ${
+          audit.id
+        } resulted in zero BigInt after conversion for precision ${USDG_WEIGHT_DECIMAL_PRECISION}. Original split value: ${splitValue.toString()}. This might indicate dust loss.`
+      );
+    }
+
+    // Distribute the calculated split value to each active farm associated with this audit.
+    for (const sidString of auditActiveFarmSids) {
+      // Duplicate Check: Ensure this shortId hasn't already received credit from another valid audit this week.
+      if (processedAuditShortIds.has(sidString)) {
+        throw new Error(
+          `ShortId ${sidString} found in multiple valid audits for week ${week}`
+        );
+      }
+      processedAuditShortIds.add(sidString); // Mark this shortId as processed.
+
+      // Store the adjusted credit for this active farm.
+      shortIdToAdjustedCredit.set(sidString, splitBigInt);
+    }
+  } // End of loop through audits.
+
+  // Final Validation: Ensure every farm considered active for this week received an adjusted credit value from a valid audit.
+  for (const farmId of farmShortIds) {
+    if (!shortIdToAdjustedCredit.has(farmId)) {
+      throw new Error(
+        `Farm ${farmId} is active for week ${week} but has no corresponding adjusted credit found in any valid audit.`
+      );
+    }
   }
 
-  let totalCreditsProduced18dp = BigInt(0);
+  // --- Start Calculation of Merkle Tree Weights ---
+
+  let totalCreditsProduced18dp = BigInt(0); // Raw total from farm data, for reporting/comparison.
 
+  // Iterate through each active farm to calculate its contribution to the Merkle tree leaves.
   for (const farm of farms) {
+    // Basic checks for farm data consistency.
     if (farm.status === "Unassigned") {
       throw new Error(`farm ${farm.shortId} is unassigned`);
     }
@@ -429,11 +491,13 @@ export async function createWeeklyReport({
       );
     }
 
+    // Accumulate the reported carbon credits (18 decimal places).
     totalCreditsProduced18dp += parseUnits(
       customToFixed(farm.carbonCreditsProduced, 18),
       18
     );
 
+    // Validate reward split percentages add up to 1 (within tolerance).
     const sumGlow = farm.rewardSplits.reduce(
       (acc: number, r: any) => acc + r.glowSplitPercent,
       0
@@ -448,49 +512,62 @@ export async function createWeeklyReport({
     if (Math.abs(sumUSDG - 1) > percentTolerance)
       throw new Error(`USDG splits ≠1 for farm ${farm.shortId}`);
 
+    // Get the base GLOW payment for the farm, converted to bigint with appropriate precision.
     const glowBase = parseUnits(
       customToFixed(farm.weeklyPayment, GLOW_WEIGHT_DECIMAL_PRECISION),
       GLOW_WEIGHT_DECIMAL_PRECISION
     );
 
+    // Retrieve the pre-calculated adjusted credit for this farm. Should always exist due to prior checks.
     const adjustedCreditBigInt =
       shortIdToAdjustedCredit.get(String(farm.shortId)) ?? BigInt(0);
 
+    // Sanity check (likely redundant due to earlier checks, but safe).
     if (adjustedCreditBigInt <= BigInt(0))
       throw new Error(
         `Adjusted credit is less than or equal to 0 for farm ${farm.shortId}`
       );
 
+    // Process each reward split recipient for this farm.
     for (const split of farm.rewardSplits) {
+      // Calculate the GLOW weight for this recipient based on the farm's weekly payment and split percentage.
       const glowWeight = multiplyBigIntByDecimalPercentage(
         glowBase,
         GLOW_WEIGHT_DECIMAL_PRECISION,
         split.glowSplitPercent
       );
+      // Calculate the USDG weight for this recipient based on the farm's *adjusted* credit and split percentage.
       const usdgWeight = multiplyBigIntByDecimalPercentage(
         adjustedCreditBigInt,
         USDG_WEIGHT_DECIMAL_PRECISION,
         split.usdgSplitPercent
       );
 
+      // Dust Loss Checks: Ensure non-zero percentages didn't result in zero weight due to precision limits.
       if (
         split.usdgSplitPercent > 0 &&
         adjustedCreditBigInt > BigInt(0) &&
         usdgWeight === BigInt(0)
       )
-        throw new Error(`USDG dust lost for farm ${farm.shortId}`);
+        throw new Error(
+          `USDG dust lost for farm ${farm.shortId} wallet ${split.walletAddress}`
+        );
       if (
         split.glowSplitPercent > 0 &&
         glowBase > BigInt(0) &&
         glowWeight === BigInt(0)
       )
-        throw new Error(`Glow dust lost for farm ${farm.shortId}`);
+        throw new Error(
+          `Glow dust lost for farm ${farm.shortId} wallet ${split.walletAddress}`
+        );
 
+      // Overflow Check: Ensure individual leaf weights don't exceed the maximum allowed.
       if (glowWeight > MAX_WEIGHT || usdgWeight > MAX_WEIGHT)
         throw new Error(
           `Leaf weight overflow on wallet ${split.walletAddress}`
         );
 
+      // Accumulate the calculated weights into the map for the recipient wallet.
       accumulateLeafWeights(
         split.walletAddress,
         { wallet: split.walletAddress, glowWeight, usdgWeight },
@@ -499,27 +576,33 @@ export async function createWeeklyReport({
     }
   }
 
+  // --- Finalize Merkle Tree and Generate Report Data ---
+
+  // Convert the accumulated weights map into the final list of leaves for the tree.
   const finalizedLeaves: FinalizedLeaf[] = Array.from(map.values()).map(
     ({ wallet, glowWeight, usdgWeight }) => ({
       wallet,
-      glowWeight: glowWeight.toString(),
+      glowWeight: glowWeight.toString(), // Convert BigInts to strings for hashing/reporting.
       usdgWeight: usdgWeight.toString(),
     })
   );
 
+  // Hash each leaf according to the defined structure.
   const hashedLeaves = finalizedLeaves.map((leaf) =>
     hashLeaf({
       address: leaf.wallet,
       glowWeight: leaf.glowWeight,
-      usdcWeight: leaf.usdgWeight,
+      usdcWeight: leaf.usdgWeight, // Note: Parameter name inconsistency (usdc vs usdg)
     })
   );
 
+  // Build the Merkle tree.
   const merkleTree = new MerkleTree(hashedLeaves, ethers.utils.keccak256, {
-    sort: true,
+    sort: true, // Ensure consistent tree structure.
   });
-  const merkleRoot = merkleTree.getHexRoot();
+  const merkleRoot = merkleTree.getHexRoot(); // Get the root hash.
 
+  // Calculate the total weights across all finalized leaves.
   const totalGlowWeight = finalizedLeaves.reduce(
     (acc, { glowWeight }) => acc.add(glowWeight),
     ethers.BigNumber.from(0)
@@ -529,23 +612,29 @@ export async function createWeeklyReport({
     ethers.BigNumber.from(0)
   );
 
+  // Total Weight Overflow Checks: Ensure sums don't exceed maximum.
   if (totalGlowWeight.toBigInt() > MAX_WEIGHT)
     throw new Error("Total glow weight overflow");
   if (totalUSDGWeight.toBigInt() > MAX_WEIGHT)
     throw new Error("Total USDG weight overflow");
 
+  // Generate Merkle proofs for each leaf and verify them.
   const leavesWithProofs = finalizedLeaves.map((leaf) => {
     const hashed = hashLeaf({
       address: leaf.wallet,
       glowWeight: leaf.glowWeight,
-      usdcWeight: leaf.usdgWeight,
+      usdcWeight: leaf.usdgWeight, // Note: Parameter name inconsistency
     });
     const proof = merkleTree.getHexProof(hashed);
     if (!merkleTree.verify(proof, hashed, merkleRoot))
+      // Verify proof against the calculated root.
       throw new Error("Invalid proof for " + leaf.wallet);
     return { ...leaf, proof };
   });
 
+  // --- Sanity Checks on Final Weights ---
+
+  // Verify that summing weights from leavesWithProofs matches the earlier reduce calculation.
   const glowSumProofLoop = leavesWithProofs.reduce(
     (acc, l) => acc.add(l.glowWeight),
     ethers.BigNumber.from(0)
@@ -568,22 +657,25 @@ export async function createWeeklyReport({
     throw new Error("USDG sum mismatch");
   }
 
+  // Calculate the total expected credits based on the adjusted values used.
   const totalExpectedCredits = farms.reduce((acc: Decimal, f: any) => {
     const adj = shortIdToAdjustedCredit.get(String(f.shortId)) ?? BigInt(0);
     return acc.plus(fromBigInt(adj, USDG_WEIGHT_DECIMAL_PRECISION));
   }, new Decimal(0));
 
+  // Convert total USDG weight back to human-readable decimal for deviation check.
   const totalUSDGWeightHuman = new Decimal(
     formatUnits(
       BigInt(totalUSDGWeight.toString()),
       USDG_WEIGHT_DECIMAL_PRECISION
     )
   );
+  // Check deviation between total adjusted credits used and the final sum of USDG weights.
   if (
     greaterThanMaxDeviation(
       totalExpectedCredits.toNumber(),
       totalUSDGWeightHuman.toNumber(),
-      0.001
+      0.001 // 0.1% tolerance
     )
   ) {
     console.error(
@@ -595,21 +687,24 @@ export async function createWeeklyReport({
     throw new Error("totalExpectedCredits vs USDG weight deviation >0.1% ");
   }
 
+  // Convert total Glow weight back to human-readable decimal.
   const totalGlowWeightHuman = new Decimal(
     formatUnits(
       BigInt(totalGlowWeight.toString()),
       GLOW_WEIGHT_DECIMAL_PRECISION
     )
   );
+  // Sum the original weekly protocol fee payments from farm data.
   const totalProtocolFeePayments = farms.reduce(
     (acc: number, f: any) => acc + f.weeklyPayment,
     0
   );
+  // Check deviation between total glow weight and total protocol fees paid.
   if (
     greaterThanMaxDeviation(
       totalGlowWeightHuman.toNumber(),
       totalProtocolFeePayments,
-      0.001
+      0.001 // 0.1% tolerance
     )
   ) {
     console.error(
@@ -621,12 +716,15 @@ export async function createWeeklyReport({
     throw new Error("totalGlowWeight vs protocol fees deviation >0.1% ");
   }
 
+  // --- Prepare Output Data ---
+
+  // Key statistics for the report.
   const headlineStats = {
     weekNumber: week,
-    totalCreditsProduced: formatUnits(totalCreditsProduced18dp, 18),
+    totalCreditsProduced: formatUnits(totalCreditsProduced18dp, 18), // Original reported total
     totalCreditsProducedBN: totalCreditsProduced18dp.toString(),
-    totalGlowWeightInFinalized: totalGlowWeight.toString(),
-    totalGlowWeightHuman: totalGlowWeightHuman.toString(),
+    totalGlowWeightInFinalized: totalGlowWeight.toString(), // Total weight as BigNumber string
+    totalGlowWeightHuman: totalGlowWeightHuman.toString(), // Total weight as human-readable decimal
     totalUSDGWeightInFinalized: totalUSDGWeight.toString(),
     totalUSDGWeightHuman: totalUSDGWeightHuman.toString(),
     root: merkleRoot,
@@ -634,6 +732,7 @@ export async function createWeeklyReport({
     usdgWeightDecimals: USDG_WEIGHT_DECIMAL_PRECISION,
   };
 
+  // List of shortIds and their final adjusted credit value (human-readable).
   const shortIdAdjustedList = Array.from(shortIdToAdjustedCredit.entries()).map(
     ([shortId, creditBigInt]) => ({
       shortId,
@@ -644,6 +743,7 @@ export async function createWeeklyReport({
     })
   );
 
+  // Detailed comparison between originally reported credits and adjusted credits for each farm.
   const creditsDeviationList = farms.map((farm: any) => {
     const adj = shortIdToAdjustedCredit.get(String(farm.shortId)) ?? BigInt(0);
     const adjusted = fromBigInt(adj, USDG_WEIGHT_DECIMAL_PRECISION);
@@ -651,6 +751,7 @@ export async function createWeeklyReport({
     let deviation: Decimal;
     let absDeviation: Decimal;
     let deviationPercent: Decimal;
+    // Handle division by zero if produced is zero.
     if (produced.isZero() && adjusted.isZero()) {
       deviation = new Decimal(0);
       absDeviation = new Decimal(0);
@@ -659,7 +760,7 @@ export async function createWeeklyReport({
       deviation = produced.minus(adjusted);
       absDeviation = deviation.abs();
       deviationPercent = deviation
-        .div(produced.isZero() ? 1 : produced)
+        .div(produced.isZero() ? 1 : produced) // Avoid division by zero
         .mul(100);
     }
     return {
@@ -672,13 +773,14 @@ export async function createWeeklyReport({
     };
   });
 
+  // Return all calculated data.
   return {
     headlineStats,
-    finalizedLeaves,
-    leavesWithProofs,
-    farms,
-    rawData,
-    shortIdAdjustedList,
-    creditsDeviationList,
+    finalizedLeaves, // Leaves without proofs (for potential use cases)
+    leavesWithProofs, // Leaves with proofs (primary data for distribution)
+    farms, // Original filtered farm data
+    rawData, // Raw GCA responses
+    shortIdAdjustedList, // List of adjusted credits per farm
+    creditsDeviationList, // Detailed deviation report per farm
   };
 }