@glowlabs-org/utils 0.1.4 → 0.1.5

package/dist/esm/index.js

@@ -18769,25 +18769,21 @@ async function createWeeklyReportLegacy(args) {
             if (farm.carbonCreditsProduced > 0 &&
                 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");
             }
             if (farm.weeklyPayment > 0 &&
                 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");
             }
             if (farm.carbonCreditsProduced > 0 &&
                 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}`);
             }
             if (farm.weeklyPayment > 0 &&
                 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}`);
             }
             addValueToMapLegacy(rewardSplit.walletAddress, value, mapLegacy);
@@ -18896,30 +18892,85 @@ async function createWeeklyReportLegacy(args) {
 }
 async function createWeeklyReport({ week, gcaUrls, apiUrl, }) {
     const map = new Map();
+    // 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(`${HUB_URL}/api/audits?omitDocuments=true&weekNumber=${week}`),
     ]);
-    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();
+    // Set to track shortIds that have been assigned a credit from a valid audit to prevent duplicates.
+    const processedAuditShortIds = new Set();
+    // 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`);
-        const splitValue = new Decimal(adjustedCredit).div(activeShortIds.length);
+            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 = [];
+        const auditInactiveFarmSids = [];
+        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.`);
+        }
+        // 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}`);
+            throw new Error(`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`);
         }
@@ -18929,7 +18980,9 @@ async function createWeeklyReport({ week, gcaUrls, apiUrl, }) {
             console.log(`Farm: ${farm.shortId} has ${farm.carbonCreditsProduced} carbon credits produced`);
             throw new Error("Carbon credits produced is less than 0 for farm " + farm.shortId);
         }
+        // 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, r) => acc + r.glowSplitPercent, 0);
         const sumUSDG = farm.rewardSplits.reduce((acc, r) => acc + r.usdgSplitPercent, 0);
         const percentTolerance = 1e-12;
@@ -18937,57 +18990,76 @@ async function createWeeklyReport({ week, gcaUrls, apiUrl, }) {
             throw new Error(`Glow splits ≠1 for farm ${farm.shortId}`);
         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 }, map);
         }
     }
+    // --- Finalize Merkle Tree and Generate Report Data ---
+    // Convert the accumulated weights map into the final list of leaves for the tree.
     const finalizedLeaves = 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));
     const totalUSDGWeight = finalizedLeaves.reduce((acc, { usdgWeight }) => acc.add(usdgWeight), 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));
     if (!glowSumProofLoop.eq(totalGlowWeight)) {
         console.error("Glow Weight Sum Mismatch (Post-73):");
@@ -19002,43 +19074,55 @@ async function createWeeklyReport({ week, gcaUrls, apiUrl, }) {
         console.error("Sum from reduce:", totalUSDGWeight.toString());
         throw new Error("USDG sum mismatch");
     }
+    // Calculate the total expected credits based on the adjusted values used.
     const totalExpectedCredits = farms.reduce((acc, f) => {
         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));
-    if (greaterThanMaxDeviation(totalExpectedCredits.toNumber(), totalUSDGWeightHuman.toNumber(), 0.001)) {
+    // Check deviation between total adjusted credits used and the final sum of USDG weights.
+    if (greaterThanMaxDeviation(totalExpectedCredits.toNumber(), totalUSDGWeightHuman.toNumber(), 0.001 // 0.1% tolerance
+    )) {
         console.error("Deviation Check Failed (Post-73): Expected Credits vs USDG Weight");
         console.error("Total Expected Credits:", totalExpectedCredits.toNumber());
         console.error("Total USDG Weight:", totalUSDGWeightHuman.toNumber());
         console.error("Allowed Deviation:", 0.001);
         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, f) => acc + f.weeklyPayment, 0);
-    if (greaterThanMaxDeviation(totalGlowWeightHuman.toNumber(), totalProtocolFeePayments, 0.001)) {
+    // Check deviation between total glow weight and total protocol fees paid.
+    if (greaterThanMaxDeviation(totalGlowWeightHuman.toNumber(), totalProtocolFeePayments, 0.001 // 0.1% tolerance
+    )) {
         console.error("Deviation Check Failed (Post-73): Glow Weight vs Protocol Fees");
         console.error("Total Glow Weight:", totalGlowWeightHuman.toNumber());
         console.error("Total Protocol Fees:", totalProtocolFeePayments);
         console.error("Allowed Deviation:", 0.001);
         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,
         glowWeightDecimals: GLOW_WEIGHT_DECIMAL_PRECISION,
         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,
         adjustedCredit: fromBigInt(creditBigInt, USDG_WEIGHT_DECIMAL_PRECISION).toString(),
     }));
+    // Detailed comparison between originally reported credits and adjusted credits for each farm.
     const creditsDeviationList = farms.map((farm) => {
         const adj = shortIdToAdjustedCredit.get(String(farm.shortId)) ?? BigInt(0);
         const adjusted = fromBigInt(adj, USDG_WEIGHT_DECIMAL_PRECISION);
@@ -19046,6 +19130,7 @@ async function createWeeklyReport({ week, gcaUrls, apiUrl, }) {
         let deviation;
         let absDeviation;
         let deviationPercent;
+        // Handle division by zero if produced is zero.
         if (produced.isZero() && adjusted.isZero()) {
             deviation = new Decimal(0);
             absDeviation = new Decimal(0);
@@ -19055,7 +19140,7 @@ async function createWeeklyReport({ week, gcaUrls, apiUrl, }) {
             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 {
@@ -19067,14 +19152,15 @@ async function createWeeklyReport({ week, gcaUrls, apiUrl, }) {
             deviationPercent: deviationPercent.toNumber(),
         };
     });
+    // 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
     };
 }