feat: add handler for RF distribution updated

Author: thelostone-mc

packages/processors/src/processors/strategy/easyRetroFunding/easyRetroFunding.handler.ts

@@ -23,12 +23,12 @@ import {
     UnsupportedEventException,
 } from "../../../internal.js";
 import {
-    BaseDistributionUpdatedHandler,
     BaseFundsDistributedHandler,
     BaseRecipientStatusUpdatedHandler,
     BaseStrategyHandler,
 } from "../common/index.js";
 import {
+    ERFDistributionUpdatedHandler,
     ERFRegisteredHandler,
     ERFTimestampsUpdatedHandler,
     ERFUpdatedRegistrationHandler,
@@ -86,7 +86,7 @@ export class EasyRetroFundingStrategyHandler extends BaseStrategyHandler {
                     this.dependencies,
                 ).handle();
             case "DistributionUpdated":
-                return new BaseDistributionUpdatedHandler(
+                return new ERFDistributionUpdatedHandler(
                     event as ProcessorEvent<"Strategy", "DistributionUpdated">,
                     this.chainId,
                     this.dependencies,

packages/processors/src/processors/strategy/easyRetroFunding/handlers/distributionUpdated.handler.ts

@@ -0,0 +1,79 @@
+import { getAddress } from "viem";
+
+import { Changeset } from "@grants-stack-indexer/repository";
+import { ChainId, ProcessorEvent } from "@grants-stack-indexer/shared";
+
+import {
+    IEventHandler,
+    MetadataNotFound,
+    MetadataParsingFailed,
+    ProcessorDependencies,
+} from "../../../../internal.js";
+import {
+    SimpleMatchingDistribution,
+    SimpleMatchingDistributionSchema,
+} from "../../../../schemas/index.js";
+
+type Dependencies = Pick<ProcessorDependencies, "metadataProvider" | "logger">;
+
+/**
+ * ERFDistributionUpdatedHandler: Processes 'DistributionUpdated' events
+ *
+ * - Decodes the updated distribution metadata
+ * - Creates a changeset to update the round with the new distribution
+ *
+ * @dev:
+ * - Strategy handlers that want to handle the DistributionUpdated event should create an instance of this class corresponding to the event.
+ *
+ */
+
+export class ERFDistributionUpdatedHandler
+    implements IEventHandler<"Strategy", "DistributionUpdated">
+{
+    constructor(
+        readonly event: ProcessorEvent<"Strategy", "DistributionUpdated">,
+        private readonly chainId: ChainId,
+        private readonly dependencies: Dependencies,
+    ) {}
+
+    /* @inheritdoc */
+    async handle(): Promise<Changeset[]> {
+        const { logger, metadataProvider } = this.dependencies;
+        const [_, pointer] = this.event.params.metadata;
+
+        const strategyAddress = getAddress(this.event.srcAddress);
+        const rawDistribution = await metadataProvider.getMetadata<
+            SimpleMatchingDistribution | undefined
+        >(pointer);
+
+        if (!rawDistribution) {
+            logger.warn(`No matching distribution found for pointer: ${pointer}`);
+
+            throw new MetadataNotFound(`No matching distribution found for pointer: ${pointer}`);
+        }
+
+        const distribution = SimpleMatchingDistributionSchema.safeParse(rawDistribution);
+
+        if (!distribution.success) {
+            logger.warn(`Failed to parse matching distribution: ${distribution.error.message}`);
+
+            throw new MetadataParsingFailed(
+                `Failed to parse matching distribution: ${distribution.error.message}`,
+            );
+        }
+
+        return [
+            {
+                type: "UpdateRoundByStrategyAddress",
+                args: {
+                    chainId: this.chainId,
+                    strategyAddress,
+                    round: {
+                        readyForPayoutTransaction: this.event.transactionFields.hash,
+                        matchingDistribution: distribution.data,
+                    },
+                },
+            },
+        ];
+    }
+}

packages/processors/src/processors/strategy/easyRetroFunding/handlers/index.ts

@@ -1,3 +1,4 @@
 export * from "./registered.handler.js";
 export * from "./timestampsUpdated.handler.js";
 export * from "./updatedRegistration.handler.js";
+export * from "./distributionUpdated.handler.js";

packages/processors/src/schemas/matchingDistribution.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 export type MatchingDistribution = z.infer<typeof MatchingDistributionSchema>;
+export type SimpleMatchingDistribution = z.infer<typeof SimpleMatchingDistributionSchema>;
 
 const BigIntSchema = z.string().or(
     z.object({ type: z.literal("BigNumber"), hex: z.string() }).transform((val) => {
@@ -22,3 +23,12 @@ export const MatchingDistributionSchema = z.object({
         }),
     ),
 });
+
+export const SimpleMatchingDistributionSchema = z.array(
+    z.object({
+        anchorAddress: z.string(),
+        payoutAddress: z.string(),
+        amount: BigIntSchema.default("0"),
+        index: z.coerce.number(),
+    }),
+);

packages/processors/test/strategy/easyRetroFunding/handlers/distributionUpdated.handler.spec.ts

@@ -0,0 +1,136 @@
+import { getAddress } from "viem";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { IMetadataProvider } from "@grants-stack-indexer/metadata";
+import { PartialRound } from "@grants-stack-indexer/repository";
+import { Bytes32String, ChainId, Logger, ProcessorEvent } from "@grants-stack-indexer/shared";
+
+import { MetadataNotFound, MetadataParsingFailed } from "../../../../src/internal.js";
+import { ERFDistributionUpdatedHandler } from "../../../../src/processors/strategy/easyRetroFunding/index.js";
+import { createMockEvent } from "../../../mocks/index.js";
+
+describe("ERFDistributionUpdatedHandler", () => {
+    let handler: ERFDistributionUpdatedHandler;
+    let mockMetadataProvider: IMetadataProvider;
+    let mockLogger: Logger;
+    let mockEvent: ProcessorEvent<"Strategy", "DistributionUpdated">;
+    const chainId = 10 as ChainId;
+    const eventName = "DistributionUpdated";
+    const defaultParams = {
+        metadata: ["1", "ipfs://QmTestHash"] as [string, string],
+        merkleRoot: "0xroot" as Bytes32String,
+    };
+    const defaultStrategyId = "0x9fa6890423649187b1f0e8bf4265f0305ce99523c3d11aa36b35a54617bb0ec0";
+
+    beforeEach(() => {
+        mockMetadataProvider = {
+            getMetadata: vi.fn(),
+        } as unknown as IMetadataProvider;
+        mockLogger = {
+            warn: vi.fn(),
+            error: vi.fn(),
+            info: vi.fn(),
+            debug: vi.fn(),
+        } as unknown as Logger;
+    });
+
+    it("handles a valid distribution update event", async () => {
+        mockEvent = createMockEvent(eventName, defaultParams, defaultStrategyId);
+        const mockDistribution = [
+            {
+                anchorAddress: "anchorAddress",
+                payoutAddress: "payoutAddress",
+                amount: "10",
+                index: 0,
+            },
+        ];
+
+        vi.spyOn(mockMetadataProvider, "getMetadata").mockResolvedValue(mockDistribution);
+
+        handler = new ERFDistributionUpdatedHandler(mockEvent, chainId, {
+            metadataProvider: mockMetadataProvider,
+            logger: mockLogger,
+        });
+
+        const result = await handler.handle();
+
+        expect(result).toEqual([
+            {
+                type: "UpdateRoundByStrategyAddress",
+                args: {
+                    chainId,
+                    strategyAddress: getAddress(mockEvent.srcAddress),
+                    round: {
+                        readyForPayoutTransaction: mockEvent.transactionFields.hash,
+                        matchingDistribution: mockDistribution,
+                    },
+                },
+            },
+        ]);
+    });
+
+    it("throws MetadataNotFound if distribution metadata is not found", async () => {
+        mockEvent = createMockEvent(eventName, defaultParams, defaultStrategyId);
+        vi.spyOn(mockMetadataProvider, "getMetadata").mockResolvedValue(undefined);
+
+        handler = new ERFDistributionUpdatedHandler(mockEvent, chainId, {
+            metadataProvider: mockMetadataProvider,
+            logger: mockLogger,
+        });
+
+        await expect(handler.handle()).rejects.toThrow(MetadataNotFound);
+        expect(mockLogger.warn).toHaveBeenCalledWith(
+            expect.stringContaining("No matching distribution found for pointer:"),
+        );
+    });
+
+    it("throw MatchingDistributionParsingError if distribution format is invalid", async () => {
+        mockEvent = createMockEvent(eventName, defaultParams, defaultStrategyId);
+        const invalidDistribution = {
+            matchingDistribution: [
+                {
+                    amount: "not_a_number", // Invalid amount format
+                    applicationId: "app1",
+                    recipientAddress: "0x1234567890123456789012345678901234567890",
+                },
+            ],
+        };
+
+        vi.spyOn(mockMetadataProvider, "getMetadata").mockResolvedValue(invalidDistribution);
+
+        handler = new ERFDistributionUpdatedHandler(mockEvent, chainId, {
+            metadataProvider: mockMetadataProvider,
+            logger: mockLogger,
+        });
+
+        await expect(handler.handle()).rejects.toThrow(MetadataParsingFailed);
+        expect(mockLogger.warn).toHaveBeenCalledWith(
+            expect.stringContaining("Failed to parse matching distribution:"),
+        );
+    });
+
+    it("handles empty matching distribution array", async () => {
+        mockEvent = createMockEvent(eventName, defaultParams, defaultStrategyId);
+        const emptyDistribution = {
+            matchingDistribution: [],
+        };
+
+        vi.spyOn(mockMetadataProvider, "getMetadata").mockResolvedValue(emptyDistribution);
+
+        handler = new ERFDistributionUpdatedHandler(mockEvent, chainId, {
+            metadataProvider: mockMetadataProvider,
+            logger: mockLogger,
+        });
+
+        const result = await handler.handle();
+        expect(result).toHaveLength(1);
+
+        const changeset = result[0] as {
+            type: "UpdateRoundByStrategyAddress";
+            args: {
+                round: PartialRound;
+            };
+        };
+        expect(changeset.args.round.matchingDistribution).toEqual([]);
+    });
+});

packages/repository/src/db/connection.ts

@@ -15,10 +15,10 @@ import {
     ApplicationPayout,
     Attestation as AttestationTable,
     AttestationTxn as AttestationTxnTable,
+    Distribution,
     Donation as DonationTable,
     ProcessedEvent as EventRegistryTable,
     LegacyProject as LegacyProjectTable,
-    MatchingDistribution,
     Metadata as MetadataCacheTable,
     PendingProjectRole as PendingProjectRoleTable,
     PendingRoundRole as PendingRoundRoleTable,
@@ -55,9 +55,9 @@ type ApplicationTable = Omit<Application, "statusSnapshots"> & {
 
 type RoundTable = Omit<Round, "matchingDistribution"> & {
     matchingDistribution: ColumnType<
-        MatchingDistribution[] | null,
-        MatchingDistribution[] | string | null,
-        MatchingDistribution[] | string | null
+        Distribution[] | null,
+        Distribution[] | string | null,
+        Distribution[] | string | null
     >;
 };
 

packages/repository/src/types/round.types.ts

@@ -1,5 +1,7 @@
 import { Address, ChainId } from "@grants-stack-indexer/shared";
 
+export type Distribution = SimpleMatchingDistribution | MatchingDistribution;
+
 export type MatchingDistribution = {
     applicationId: string;
     projectPayoutAddress: string;
@@ -11,6 +13,13 @@ export type MatchingDistribution = {
     matchAmountInToken: string;
 };
 
+export type SimpleMatchingDistribution = {
+    anchorAddress: string;
+    payoutAddress: string;
+    amount: string;
+    index: number;
+};
+
 export type Round = {
     id: Address | string;
     chainId: ChainId;
@@ -40,7 +49,7 @@ export type Round = {
     strategyId: string;
     strategyName: string;
     readyForPayoutTransaction: string | null;
-    matchingDistribution: MatchingDistribution[] | null;
+    matchingDistribution: Distribution[] | null;
     projectId: string;
     tags: string[];
     timestamp: Date;