starknet: fix enum handling and types in event decoder (#185)

fixes an issue where event decoder `decodeEvent()` would throw error in
case of nested enums parsing. also overrides a `abi-wan-kanabi` type to
improve type safety for enum types and match with our own runtime
values.

Author: fracek

change/@apibara-starknet-2fb40364-ed44-45a8-b402-3a014057aa82.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "starknet: fix enum handling and types in eventDecoder",
+  "packageName": "@apibara/starknet",
+  "email": "jadejajaipal5@gmail.com",
+  "dependentChangeType": "patch"
+}

packages/starknet/src/abi-wan-helpers.ts

@@ -15,9 +15,10 @@ For more information, please refer to https://unlicense.org
 import type { Abi } from "abi-wan-kanabi";
 import type {
   AbiEventMember,
+  ExtractAbiEnum,
   ExtractAbiEvent,
   ExtractAbiEventNames,
-  StringToPrimitiveType,
+  StringToPrimitiveType as OriginalStringToPrimitiveType,
 } from "abi-wan-kanabi/kanabi";
 
 export type AbiEventStruct = {
@@ -39,10 +40,50 @@ export type AbiEventEnum = {
   variants: AbiEventMember[];
 };
 
+export type AbiParameter = {
+  name: string;
+  type: string;
+};
+
+export type AbiEnum = {
+  type: "enum";
+  name: string;
+  variants: readonly AbiParameter[];
+};
+
 export type AbiEvent = AbiEventStruct | AbiEventEnum;
 
 export type AbiItem = Abi[number];
 
+// Custom StringToPrimitiveType that overrides abi-wan-kanabi's enum handling.
+// The original StringToPrimitiveType from abi-wan-kanabi produces ObjectToUnion types
+// for enums, which don't include the `_tag` property that our runtime parser generates.
+// This custom version ensures TypeScript types match the actual runtime values.
+export type StringToPrimitiveType<
+  TAbi extends Abi,
+  T extends string,
+> = ExtractAbiEnum<TAbi, T> extends never
+  ? // Not an enum type, forward to original abi-wan-kanabi type
+    OriginalStringToPrimitiveType<TAbi, T>
+  : ExtractAbiEnum<TAbi, T> extends {
+        type: "enum";
+        variants: infer TVariants extends readonly AbiParameter[];
+      }
+    ? // It's an enum type, create tagged union with _tag property
+      {
+        [Variant in TVariants[number] as Variant["name"]]: Variant["type"] extends "()"
+          ? // Unit variant (no data): { _tag: "VariantName"; VariantName: null }
+            { _tag: Variant["name"] } & { [K in Variant["name"]]: null }
+          : // Variant with data: { _tag: "VariantName"; VariantName: StringToPrimitiveType }
+            { _tag: Variant["name"] } & {
+              [K in Variant["name"]]: StringToPrimitiveType<
+                TAbi,
+                Variant["type"]
+              >;
+            };
+      }[TVariants[number]["name"]]
+    : never;
+
 export type DecodeEventArgs<
   TAbi extends Abi = Abi,
   TEventName extends ExtractAbiEventNames<TAbi> = ExtractAbiEventNames<TAbi>,

packages/starknet/src/event.ts

@@ -17,6 +17,7 @@ import {
   isSpanType,
 } from "./abi";
 import {
+  type AbiEnum,
   type AbiEvent,
   type AbiEventEnum,
   type AbiEventStruct,
@@ -33,6 +34,7 @@ import {
   parseArray,
   parseByteArray,
   parseEmpty,
+  parseEnum,
   parseOption,
   parseSpan,
   parseStruct,
@@ -315,9 +317,7 @@ function compileTypeParser(abi: Abi, type: string): Parser<unknown> {
       return compileStructParser(abi, typeAbi.members);
     }
     case "enum": {
-      // This should never happen anyways as compileTypeParser is only called
-      // primitive types or to compile structs parsers.
-      throw new DecodeEventError(`Enum types are not supported: ${type}`);
+      return compileEnumParser(abi, typeAbi);
     }
     default:
       throw new DecodeEventError(`Invalid type ${typeAbi.type}`);
@@ -338,3 +338,15 @@ function compileStructParser(
   }
   return parseStruct(parsers);
 }
+
+function compileEnumParser(abi: Abi, enumAbi: AbiEnum): Parser<unknown> {
+  const parsers: Record<string, { index: number; parser: Parser<unknown> }> =
+    {};
+  for (const [index, variant] of enumAbi.variants.entries()) {
+    parsers[variant.name] = {
+      index,
+      parser: compileTypeParser(abi, variant.type),
+    };
+  }
+  return parseEnum(parsers);
+}

packages/starknet/src/parser.ts

@@ -153,6 +153,34 @@ export function parseStruct<T extends Record<string, unknown>>(
   return parser as Parser<{ [K in keyof T]: T[K] }>;
 }
 
+export function parseEnum<T extends Record<string, unknown>>(
+  parsers: {
+    [K in keyof T]: { index: number; parser: Parser<T[K]> };
+  },
+): Parser<T[keyof T]> {
+  return (data: readonly FieldElement[], startingOffset: number) => {
+    const selectorFelt = data[startingOffset];
+    const selector = Number(BigInt(selectorFelt));
+
+    // Find the parser by index
+    const parserEntry = Object.entries(parsers).find(
+      ([, { index }]) => index === selector,
+    );
+
+    if (!parserEntry) {
+      throw new ParseError(`Unknown enum variant selector: ${selector}`);
+    }
+
+    const [variantName, { parser }] = parserEntry;
+    const { out, offset: newOffset } = parser(data, startingOffset + 1);
+
+    return {
+      out: { _tag: variantName, [variantName]: out } as T[keyof T],
+      offset: newOffset,
+    };
+  };
+}
+
 export function parseTuple<T extends Parser<unknown>[]>(
   ...parsers: T
 ): Parser<UnwrapParsers<T>> {

packages/starknet/tests/event.test.ts

@@ -8,6 +8,7 @@ import { chainlinkAbi } from "./fixtures/chainlink-abi";
 import { ekuboAbi } from "./fixtures/ekubo-abi";
 import { golifeAbi } from "./fixtures/golife-abi";
 import { paymentAbi } from "./fixtures/payment-abi";
+import { registryAbi } from "./fixtures/registry-abi";
 
 describe("decodeEvent", () => {
   describe("non strict mode", () => {
@@ -668,5 +669,67 @@ describe("decodeEvent", () => {
 
       expect(decoded).toBeNull();
     });
+
+    it('can decode event with nested enum with null ["()" type] data', () => {
+      const abi = registryAbi;
+      const userRegisteredEventSelector = getEventSelector("UserRegistered");
+
+      const event = {
+        transactionHash:
+          "0x07c2ea2b2211421e1a74e25f9fe9ad36862c83d6b7189b91185496c41cd83fc9",
+        address:
+          "0x04319b2cdf8f484e965a7df709e75c4d5c89780d3601f5105e1bc26243dd45b6",
+        keys: [
+          userRegisteredEventSelector,
+          "0x348ed741a6cfdfa876b4bc233e8f769468a624ae66543d610235112943cc993",
+          "0x796f64613133",
+        ],
+        data: ["0x6877a1fd", "0x1"],
+        filterIds: [],
+        eventIndex: 0,
+        eventIndexInTransaction: 0,
+        transactionIndex: 0,
+        transactionStatus: "succeeded",
+      } as const satisfies Event;
+
+      const decoded = decodeEvent({
+        abi,
+        event,
+        eventName:
+          "opinion_competitions::utils::common::events::UserRegistered",
+        strict: true,
+      });
+
+      expect(decoded).toMatchInlineSnapshot(`
+        {
+          "address": "0x04319b2cdf8f484e965a7df709e75c4d5c89780d3601f5105e1bc26243dd45b6",
+          "args": {
+            "timestamp": 1752670717n,
+            "user": "0x348ed741a6cfdfa876b4bc233e8f769468a624ae66543d610235112943cc993",
+            "username": 133519332421939n,
+            "verification_level": {
+              "ORB": null,
+              "_tag": "ORB",
+            },
+          },
+          "data": [
+            "0x6877a1fd",
+            "0x1",
+          ],
+          "eventIndex": 0,
+          "eventIndexInTransaction": 0,
+          "eventName": "opinion_competitions::utils::common::events::UserRegistered",
+          "filterIds": [],
+          "keys": [
+            "0x015854d06e396351cf7ea2143ce9ba79f24588d0f1b1617f54e9acca7a6ac325",
+            "0x348ed741a6cfdfa876b4bc233e8f769468a624ae66543d610235112943cc993",
+            "0x796f64613133",
+          ],
+          "transactionHash": "0x07c2ea2b2211421e1a74e25f9fe9ad36862c83d6b7189b91185496c41cd83fc9",
+          "transactionIndex": 0,
+          "transactionStatus": "succeeded",
+        }
+      `);
+    });
   });
 });