Feat/adds optional constant funding per grant in retrofunding (#56)

* fix: toaster errors

* feat: adds constant amount for each grant on retrofunding distribute component

* chore: added a new story to simulate GG23 Distributions

* added changeset

Author: nijoe1

.changeset/soft-carpets-allow.md

@@ -0,0 +1,5 @@
+---
+"@gitcoin/ui": patch
+---
+
+Adds optional constant funding per grantee in retrofunding Distribute component

packages/ui/src/components/Toaster/Toaster.tsx

@@ -57,6 +57,7 @@ export const Toaster = () => {
               .otherwise(() => <Icon type={IconType.SOLID_X} className="size-5 rounded-full" />);
             return (
               <Toast
+                key={toast.id}
                 toast={{
                   ...toast,
                   icon: ToastIcon ?? IconType.SOLID_X,

packages/ui/src/features/retrofunding/components/Distribute/Distribute.stories.tsx

@@ -1,6 +1,6 @@
 import { action } from "@storybook/addon-actions";
 import { StoryObj, Meta } from "@storybook/react";
-import { parseUnits } from "viem";
+import { formatUnits, parseUnits } from "viem";
 
 import { PoolStatus } from "@/types";
 import { ApplicationPayout, PoolConfig } from "@/types/distribute";
@@ -19,11 +19,12 @@ const TOKEN_DECIMALS = 18;
 
 const POOL_CONFIG: PoolConfig = {
   tokenTicker: "ETH",
-  amountOfTokensInPool: parseUnits("10", TOKEN_DECIMALS).toString(),
+  amountOfTokensInPool: parseUnits("100", TOKEN_DECIMALS).toString(),
   amountOfTokensToDistribute: 100,
   tokenDecimals: TOKEN_DECIMALS,
   poolStatus: PoolStatus.FundingPending,
   chainId: 11155111,
+  constantAmountPerGrant: 0,
 };
 
 const MOCK_APPLICATIONS: ApplicationPayout[] = [
@@ -32,28 +33,28 @@ const MOCK_APPLICATIONS: ApplicationPayout[] = [
     title: "Project Alpha",
     imageUrl: "https://picsum.photos/100",
     payoutAddress: "0x4614291bb169905074Da4aFaA39784D175162f79",
-    payoutPercentage: 23,
+    payoutPercentage: 10.4,
   },
   {
     id: "2",
     title: "Long Project Title That Might Need Truncation",
     imageUrl: "https://picsum.photos/101",
     payoutAddress: "0x4614291bb169905074Da4aFaA39784D175162f79",
-    payoutPercentage: 23,
+    payoutPercentage: 14.6,
   },
   {
     id: "3",
     title: "Project Beta",
     imageUrl: "https://picsum.photos/102",
     payoutAddress: "0x4614291bb169905074Da4aFaA39784D175162f79",
-    payoutPercentage: 23,
+    payoutPercentage: 23.7,
   },
   {
     id: "4",
     title: "Project Gamma",
     imageUrl: "https://picsum.photos/103",
     payoutAddress: "0x4614291bb169905074Da4aFaA39784D175162f79",
-    payoutPercentage: 23,
+    payoutPercentage: 22.3,
   },
   {
     id: "5",
@@ -77,14 +78,14 @@ const MOCK_APPLICATIONS: ApplicationPayout[] = [
     title: "Project Zeta",
     imageUrl: "https://picsum.photos/106",
     payoutAddress: "0x4614291bb169905074Da4aFaA39784D175162f79",
-    payoutPercentage: 2,
+    payoutPercentage: 13.4,
   },
   {
     id: "8",
     title: "Project Epsilon",
     imageUrl: "https://picsum.photos/107",
     payoutAddress: "0x4614291bb169905074Da4aFaA39784D175162f79",
-    payoutPercentage: 2,
+    payoutPercentage: 11.6,
   },
 ];
 
@@ -93,7 +94,17 @@ const args = {
   poolConfig: { ...POOL_CONFIG, amountOfTokensInPool: parseUnits("96", TOKEN_DECIMALS).toString() },
   canResetEdit: true,
   onFundRound: async (values: any) => onFundRound(values),
-  onDistribute: async (values: any) => onDistribute(values),
+  onDistribute: async (values: any) => {
+    const finalAmount = values.reduce((acc: any, curr: any) => {
+      acc += curr.amount;
+      return acc;
+    }, 0n);
+    onDistribute(
+      "Amount to distribute: ",
+      formatUnits(finalAmount, POOL_CONFIG.tokenDecimals),
+      values,
+    );
+  },
   onEditPayouts: async (values: any) => onEditPayouts(values),
   onResetEdit: async () => onResetEdit(),
   className: "w-full",
@@ -153,6 +164,23 @@ export const NoFinalizedProjects: StoryObj<typeof Distribute> = {
   },
 };
 
+export const NoFinalizedProjectsWithConstantAmountPerGrant: StoryObj<typeof Distribute> = {
+  args: {
+    ...args,
+    applications: MOCK_APPLICATIONS.map((application) => ({
+      ...application,
+      payoutTransactionHash: undefined,
+    })),
+    poolConfig: {
+      ...POOL_CONFIG,
+      constantAmountPerGrant: 10000,
+      amountOfTokensInPool: parseUnits("300000", POOL_CONFIG.tokenDecimals).toString(),
+      amountOfTokensToDistribute: 300000,
+      tokenTicker: "USDC",
+    },
+  },
+};
+
 export const NotFundingPhase: StoryObj<typeof Distribute> = {
   args: {
     ...args,

packages/ui/src/features/retrofunding/components/Distribute/Distribute.tsx

@@ -7,7 +7,7 @@ import { ApplicationPayout, PoolConfig } from "@/types/distribute";
 import { FundRoundSection, ActionButtons } from "./components";
 import { DistributeTabs } from "./components/DistributeTabs";
 import { useRound } from "./hooks/useRound";
-import { formatAmountFromPercentage } from "./utils";
+import { formatAmountFromPercentageWithConstant, getAvailableTokensToDistribute } from "./utils";
 
 interface DistributeProps {
   applications: ApplicationPayout[];
@@ -42,6 +42,11 @@ export const Distribute = ({
     [applications],
   );
 
+  const availableTokensToDistribute = getAvailableTokensToDistribute(
+    applications.length,
+    poolConfig,
+  );
+
   const canEdit = finalizedApplications.length === 0 && pendingApplications.length > 0;
   const hasPendingApplications = pendingApplications.length > 0;
   const distributionCompleted =
@@ -53,10 +58,11 @@ export const Distribute = ({
         .filter((p) => selectedApplications.includes(p.id))
         .map((p) => ({
           applicationId: p.id,
-          amount: formatAmountFromPercentage(
-            poolConfig.amountOfTokensToDistribute,
+          amount: formatAmountFromPercentageWithConstant(
+            availableTokensToDistribute,
             p.payoutPercentage,
             poolConfig.tokenDecimals,
+            poolConfig.constantAmountPerGrant,
           ),
         })),
     );
@@ -65,10 +71,11 @@ export const Distribute = ({
   const totalPaid = finalizedApplications.reduce(
     (acc, curr) =>
       acc +
-      formatAmountFromPercentage(
-        poolConfig.amountOfTokensToDistribute,
+      formatAmountFromPercentageWithConstant(
+        availableTokensToDistribute,
         curr.payoutPercentage,
         poolConfig.tokenDecimals,
+        poolConfig.constantAmountPerGrant,
       ),
     0n,
   );

packages/ui/src/features/retrofunding/components/Distribute/components/DistributeTable/ProjectTableRow.tsx

@@ -4,10 +4,13 @@ import { NumericFormat } from "react-number-format";
 import { getTransactionUrl } from "@/lib/explorer/getTransactionUrl";
 import { cn } from "@/lib/utils";
 import { Button, Checkbox } from "@/primitives";
-import { ApplicationPayout, PoolConfig } from "@/types/distribute";
 import { TableRow, TableCell } from "@/primitives/Table";
+import { ApplicationPayout, PoolConfig } from "@/types/distribute";
 
-import { formatAmountFromPercentage } from "../../utils";
+import {
+  formatAmountFromPercentageWithConstant,
+  getAvailableTokensToDistribute,
+} from "../../utils";
 
 interface ApplicationTableRowProps {
   application: ApplicationPayout;
@@ -61,6 +64,10 @@ export const ProjectTableRow = ({
     return () => input?.removeEventListener("wheel", handleWheel);
   }, [handleWheel, inputRef.current]);
 
+  const availableTokensToDistribute = getAvailableTokensToDistribute(
+    allApplications.length,
+    poolConfig,
+  );
   const handleSafeChange = useCallback(
     (newValue: number) => {
       const otherApplicationsTotal = editedApplications
@@ -73,7 +80,8 @@ export const ProjectTableRow = ({
   );
 
   const formatPayoutAmount = (percentage: number): number => {
-    const amount = (percentage / 100) * poolConfig.amountOfTokensToDistribute;
+    const amount =
+      (percentage / 100) * availableTokensToDistribute + poolConfig.constantAmountPerGrant;
     return Number(amount.toFixed(4));
   };
 
@@ -169,10 +177,11 @@ export const ProjectTableRow = ({
               onDistribute([
                 {
                   applicationId: application.id,
-                  amount: formatAmountFromPercentage(
+                  amount: formatAmountFromPercentageWithConstant(
                     poolConfig.amountOfTokensToDistribute,
                     application.payoutPercentage,
                     poolConfig.tokenDecimals,
+                    poolConfig.constantAmountPerGrant,
                   ),
                 },
               ])

packages/ui/src/features/retrofunding/components/Distribute/components/FundRoundSection.tsx

@@ -64,6 +64,21 @@ export const FundRoundSection = ({
           <span className="font-ui-mono text-sm font-bold">
             {poolConfig.amountOfTokensToDistribute} {poolConfig.tokenTicker}
           </span>
+          {!!poolConfig.constantAmountPerGrant && (
+            <div className="flex items-center gap-1 pl-5">
+              <Icon
+                className="size-5 rounded-full text-yellow-500"
+                type={IconType.INFORMATION_CIRCLE}
+              />
+              <span className="font-ui-sans text-sm font-normal">
+                This round has a constant distribution amount per application of
+              </span>
+
+              <span className="font-ui-mono text-sm font-bold">
+                {poolConfig.constantAmountPerGrant} {poolConfig.tokenTicker}
+              </span>
+            </div>
+          )}
         </div>
       )}
     </div>

packages/ui/src/features/retrofunding/components/Distribute/utils.ts

@@ -1,5 +1,7 @@
 import { formatUnits, parseUnits } from "viem";
 
+import { PoolConfig } from "@/types/distribute";
+
 /**
  * Calculates a percentage of a token amount and converts it to the token's smallest unit (wei/gwei/etc)
  * @param amountOfTokens - The total amount of tokens in human readable format (e.g., 100 for 100 tokens)
@@ -15,6 +17,26 @@ export const formatAmountFromPercentage = (
   return safeParseUnits(((amountOfTokens * percentage) / 100) * 10 ** 9, tokenDecimals) / 10n ** 9n;
 };
 
+/**
+ * Formats a token amount from a percentage and a constant amount per grant
+ * @param amountOfTokens - The total amount of tokens in human readable format (e.g., 100 for 100 tokens)
+ * @param percentage - The percentage to calculate (e.g., 50 for 50%)
+ * @param tokenDecimals - The number of decimal places for the token (e.g., 18 for ETH)
+ * @param constantAmountPerGrant - The constant amount per grant in human readable format (e.g., 100 for 100 tokens)
+ * @returns The formatted amount in the token's smallest unit as a bigint
+ */
+export const formatAmountFromPercentageWithConstant = (
+  amountOfTokens: number,
+  percentage: number,
+  tokenDecimals: number,
+  constantAmountPerGrant: number,
+) => {
+  return (
+    formatAmountFromPercentage(amountOfTokens, percentage, tokenDecimals) +
+    safeParseUnits(constantAmountPerGrant.toString(), tokenDecimals)
+  );
+};
+
 /**
  * Safely parses token amounts by converting scientific notation (e.g., 1e18) to decimal format.
  * Resolves common parseUnits errors when dealing with scientific notation inputs.
@@ -83,3 +105,22 @@ export const formatAmount = (amount: bigint, decimals: number, maxDecimals?: num
     maximumSignificantDigits: decimals,
   });
 };
+
+export const getAvailableTokensToDistribute = (
+  numberOfApplications: number,
+  poolConfig: PoolConfig,
+) => {
+  const constantDistributeAmount = (
+    numberOfApplications * poolConfig.constantAmountPerGrant
+  ).toLocaleString("fullwide", {
+    useGrouping: false,
+    maximumSignificantDigits: 9,
+  });
+
+  const totalConstantDistributeAmount = Number(safeParseUnits(constantDistributeAmount, 9)) / 1e9;
+
+  const availableTokensToDistribute =
+    poolConfig.amountOfTokensToDistribute - totalConstantDistributeAmount;
+
+  return availableTokensToDistribute;
+};

packages/ui/src/types/distribute.ts

@@ -11,6 +11,7 @@ export interface ApplicationPayout {
 
 export interface PoolConfig {
   tokenTicker: string;
+  constantAmountPerGrant: number;
   amountOfTokensInPool: bigint | string;
   amountOfTokensToDistribute: number;
   tokenDecimals: number;