@apibara/starknet 2.0.0-beta.9 → 2.1.0-beta.2

package/src/event.ts

@@ -0,0 +1,204 @@
+import type { Abi } from "abi-wan-kanabi";
+import type {
+  AbiEventMember,
+  EventToPrimitiveType,
+  ExtractAbiEventNames,
+} from "abi-wan-kanabi/kanabi";
+import {
+  PrimitiveTypeParsers,
+  getArrayElementType,
+  getEventSelector,
+  getOptionType,
+  getSpanType,
+  isArrayType,
+  isEmptyType,
+  isOptionType,
+  isPrimitiveType,
+  isSpanType,
+} from "./abi";
+import type { Event } from "./block";
+import {
+  ParseError,
+  type Parser,
+  parseArray,
+  parseEmpty,
+  parseOption,
+  parseSpan,
+  parseStruct,
+} from "./parser";
+
+export class DecodeEventError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DecodeEventError";
+  }
+}
+
+export type DecodeEventArgs<
+  TAbi extends Abi = Abi,
+  TEventName extends ExtractAbiEventNames<TAbi> = ExtractAbiEventNames<TAbi>,
+  TStrict extends boolean = true,
+> = {
+  abi: TAbi;
+  eventName: TEventName;
+  event: Event;
+  strict?: TStrict;
+};
+
+export type DecodedEvent<
+  TAbi extends Abi = Abi,
+  TEventName extends ExtractAbiEventNames<TAbi> = ExtractAbiEventNames<TAbi>,
+> = Event & {
+  eventName: TEventName;
+  args: EventToPrimitiveType<TAbi, TEventName>;
+};
+
+export type DecodeEventReturn<
+  TAbi extends Abi = Abi,
+  TEventName extends ExtractAbiEventNames<TAbi> = ExtractAbiEventNames<TAbi>,
+  TStrict extends boolean = true,
+> = TStrict extends true
+  ? DecodedEvent<TAbi, TEventName>
+  : DecodedEvent<TAbi, TEventName> | null;
+
+/** Decodes a single event.
+ *
+ * If `strict: true`, this function throws on failure. Otherwise, returns null.
+ */
+export function decodeEvent<
+  TAbi extends Abi = Abi,
+  TEventName extends ExtractAbiEventNames<TAbi> = ExtractAbiEventNames<TAbi>,
+  TStrict extends boolean = true,
+>(
+  args: DecodeEventArgs<TAbi, TEventName, TStrict>,
+): DecodeEventReturn<TAbi, TEventName, TStrict> {
+  const { abi, event, eventName, strict = true } = args;
+
+  const eventAbi = abi.find(
+    (item) => item.name === eventName && item.type === "event",
+  );
+
+  if (!eventAbi || eventAbi.type !== "event") {
+    if (strict) {
+      throw new DecodeEventError(`Event ${eventName} not found in ABI`);
+    }
+
+    return null as DecodeEventReturn<TAbi, TEventName, TStrict>;
+  }
+
+  if (eventAbi.kind === "enum") {
+    throw new DecodeEventError("enum: not implemented");
+  }
+
+  const selector = BigInt(getEventSelector(eventName));
+  if ((event.keys && selector !== BigInt(event.keys[0])) || !event.keys) {
+    if (strict) {
+      throw new DecodeEventError(
+        `Selector mismatch. Expected ${selector}, got ${event.keys?.[0]}`,
+      );
+    }
+
+    return null as DecodeEventReturn<TAbi, TEventName, TStrict>;
+  }
+
+  const keysAbi = eventAbi.members.filter((m) => m.kind === "key");
+  const dataAbi = eventAbi.members.filter((m) => m.kind === "data");
+
+  try {
+    const keysParser = compileEventMembers(abi, keysAbi);
+    const dataParser = compileEventMembers(abi, dataAbi);
+
+    const keysWithoutSelector = event.keys?.slice(1) ?? [];
+    const { out: decodedKeys } = keysParser(keysWithoutSelector, 0);
+    const { out: decodedData } = dataParser(event.data ?? [], 0);
+
+    const decoded = {
+      ...decodedKeys,
+      ...decodedData,
+    } as EventToPrimitiveType<TAbi, TEventName>;
+
+    return {
+      ...event,
+      eventName,
+      args: decoded,
+    } as DecodedEvent<TAbi, TEventName>;
+  } catch (error) {
+    if (error instanceof DecodeEventError && !strict) {
+      return null as DecodeEventReturn<TAbi, TEventName, TStrict>;
+    }
+
+    if (error instanceof ParseError && !strict) {
+      return null as DecodeEventReturn<TAbi, TEventName, TStrict>;
+    }
+
+    throw error;
+  }
+}
+
+function compileEventMembers<T extends Record<string, unknown>>(
+  abi: Abi,
+  members: AbiEventMember[],
+): Parser<T> {
+  return compileStructParser(abi, members) as Parser<T>;
+}
+
+function compileTypeParser(abi: Abi, type: string): Parser<unknown> {
+  if (isPrimitiveType(type)) {
+    return PrimitiveTypeParsers[type as keyof typeof PrimitiveTypeParsers];
+  }
+
+  if (isArrayType(type)) {
+    const elementType = getArrayElementType(type);
+    return parseArray(compileTypeParser(abi, elementType));
+  }
+
+  if (isSpanType(type)) {
+    const elementType = getSpanType(type);
+    return parseSpan(compileTypeParser(abi, elementType));
+  }
+
+  if (isOptionType(type)) {
+    const elementType = getOptionType(type);
+    return parseOption(compileTypeParser(abi, elementType));
+  }
+
+  if (isEmptyType(type)) {
+    return parseEmpty;
+  }
+
+  // Not a well-known type. Look it up in the ABI.
+  const typeAbi = abi.find((item) => item.name === type);
+  if (!typeAbi) {
+    throw new DecodeEventError(`Type ${type} not found in ABI`);
+  }
+
+  switch (typeAbi.type) {
+    case "struct": {
+      return compileStructParser(abi, typeAbi.members);
+    }
+    case "enum":
+      throw new DecodeEventError("enum: not implemented");
+    default:
+      throw new DecodeEventError(`Invalid type ${typeAbi.type}`);
+  }
+}
+
+type AbiMember = {
+  name: string;
+  type: string;
+};
+
+function compileStructParser(
+  abi: Abi,
+  members: readonly AbiMember[],
+): Parser<unknown> {
+  const parsers: Record<string, { index: number; parser: Parser<unknown> }> =
+    {};
+  for (const [index, member] of members.entries()) {
+    parsers[member.name] = {
+      index,
+      parser: compileTypeParser(abi, member.type),
+    };
+  }
+  return parseStruct(parsers);
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 import { StreamConfig } from "@apibara/protocol";
+export type { Abi } from "abi-wan-kanabi";
 import { BlockFromBytes } from "./block";
 import { FilterFromBytes, mergeFilter } from "./filter";
 
@@ -9,6 +10,16 @@ export * from "./filter";
 export * from "./block";
 
 export * from "./access";
+export * from "./event";
+export { getBigIntSelector, getEventSelector, getSelector } from "./abi";
+
+declare module "abi-wan-kanabi" {
+  interface Config {
+    FeltType: bigint;
+    BigIntType: bigint;
+    U256Type: bigint;
+  }
+}
 
 export const StarknetStream = new StreamConfig(
   FilterFromBytes,

package/src/parser.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  ParseError,
+  parseArray,
+  parseAsHex,
+  parseBool,
+  parseFelt252,
+  parseOption,
+  parseStruct,
+  parseTuple,
+  parseU8,
+  parseU16,
+  parseU32,
+  parseU64,
+  parseU128,
+  parseU256,
+} from "./parser";
+
+describe("Primitive types parser", () => {
+  it("can parse a bool", () => {
+    const data = ["0x1", "0x0"] as const;
+    const { out, offset } = parseBool(data, 0);
+    expect(out).toBe(true);
+    expect(offset).toBe(1);
+  });
+
+  it("can parse a u8", () => {
+    const data = ["0xf", "0x0"] as const;
+    const { out, offset } = parseU8(data, 0);
+    expect(out).toBe(15n);
+    expect(offset).toBe(1);
+  });
+
+  it("can parse a u16", () => {
+    const data = ["0x1234", "0x0"] as const;
+    const { out, offset } = parseU16(data, 0);
+    expect(out).toBe(4660n);
+    expect(offset).toBe(1);
+  });
+
+  it("can parse a u32", () => {
+    const data = ["0x12345678", "0x0"] as const;
+    const { out, offset } = parseU32(data, 0);
+    expect(out).toBe(305419896n);
+    expect(offset).toBe(1);
+  });
+
+  it("can parse a u64", () => {
+    const data = ["0x1234567890abcdef", "0x0"] as const;
+    const { out, offset } = parseU64(data, 0);
+    expect(out).toBe(1311768467294899695n);
+    expect(offset).toBe(1);
+  });
+
+  it("can parse a u128", () => {
+    const data = ["0x1234567890abcdef1234567890abcdef", "0x0"] as const;
+    const { out, offset } = parseU128(data, 0);
+    expect(out).toBe(24197857200151252728969465429440056815n);
+    expect(offset).toBe(1);
+  });
+
+  it("can parse a u256", () => {
+    const data = ["0x1234567890abcdef1234567890abcdef", "0x0"] as const;
+    const { out, offset } = parseU256(data, 0);
+    expect(out).toBe(24197857200151252728969465429440056815n);
+    expect(offset).toBe(2);
+  });
+
+  it("can parse an address", () => {
+    const data = ["0x1234567890abcdef1234567890abcdef", "0x0"] as const;
+    const { out, offset } = parseAsHex(data, 0);
+    expect(out).toBe("0x1234567890abcdef1234567890abcdef");
+    expect(offset).toBe(1);
+  });
+
+  it("can parse a felt252", () => {
+    const data = ["0x1234567890abcdef1234567890abcdef", "0x0"] as const;
+    const { out, offset } = parseFelt252(data, 0);
+    expect(out).toBe(24197857200151252728969465429440056815n);
+    expect(offset).toBe(1);
+  });
+});
+
+describe("Array parser", () => {
+  it("can parse an array", () => {
+    const data = ["0x3", "0x1", "0x2", "0x3"] as const;
+    const { out, offset } = parseArray(parseU8)(data, 0);
+    expect(out).toEqual([1n, 2n, 3n]);
+    expect(offset).toBe(4);
+  });
+
+  it("throws an error if there is not enough data", () => {
+    const data = ["0x3", "0x1", "0x2"] as const;
+    expect(() => parseArray(parseU8)(data, 0)).toThrow(ParseError);
+  });
+});
+
+describe("Option parser", () => {
+  it("can parse an option", () => {
+    const data = ["0x1", "0x2"] as const;
+    const { out, offset } = parseOption(parseU8)(data, 0);
+    expect(out).toBe(2n);
+    expect(offset).toBe(2);
+  });
+
+  it("returns null if the option is not present", () => {
+    const data = ["0x0"] as const;
+    const { out, offset } = parseOption(parseU8)(data, 0);
+    expect(out).toBeNull();
+    expect(offset).toBe(1);
+  });
+});
+
+describe("Struct parser", () => {
+  it("can parse a struct with primitive types", () => {
+    const data = ["0x1", "0x2", "0x3"] as const;
+    const { out, offset } = parseStruct({
+      a: { index: 0, parser: parseU8 },
+      b: { index: 1, parser: parseU8 },
+      c: { index: 2, parser: parseU8 },
+    })(data, 0);
+    expect(out).toEqual({ a: 1n, b: 2n, c: 3n });
+    expect(offset).toBe(3);
+  });
+
+  it("can parse a struct with an option", () => {
+    const data = ["0x1", "0x1", "0x3"] as const;
+    const { out, offset } = parseStruct({
+      a: { index: 0, parser: parseU8 },
+      b: { index: 1, parser: parseOption(parseU8) },
+    })(data, 0);
+    expect(out).toEqual({ a: 1n, b: 3n });
+    expect(offset).toBe(3);
+  });
+
+  it("can parse a nested struct", () => {
+    const data = ["0x1", "0x2"] as const;
+    const { out, offset } = parseStruct({
+      a: { index: 0, parser: parseU8 },
+      b: {
+        index: 1,
+        parser: parseStruct({ c: { index: 0, parser: parseU8 } }),
+      },
+    })(data, 0);
+    expect(out).toEqual({ a: 1n, b: { c: 2n } });
+    expect(offset).toBe(2);
+  });
+});
+
+describe("Tuple parser", () => {
+  it("can parse a tuple", () => {
+    const data = ["0x1", "0x2", "0x0"] as const;
+    const { out, offset } = parseTuple(parseU8, parseAsHex, parseBool)(data, 0);
+    expect(out).toEqual([1n, "0x2", false]);
+    expect(offset).toBe(3);
+  });
+
+  it("can parse a nested tuple", () => {
+    const data = ["0x1", "0x2", "0x3", "0x0"] as const;
+    const { out, offset } = parseTuple(
+      parseU8,
+      parseTuple(parseU8, parseU8),
+      parseBool,
+    )(data, 0);
+    expect(out).toEqual([1n, [2n, 3n], false]);
+    expect(offset).toBe(4);
+  });
+});

package/src/parser.ts

@@ -0,0 +1,170 @@
+/*
+ * Calldata combinatorial parsers.
+ *
+ * Based on the Ekubo's event parser.
+ *
+ * MIT License
+ *
+ * Copyright (c) 2023 Ekubo, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import type { FieldElement } from "./common";
+
+export type Parser<TOut> = (
+  data: readonly FieldElement[],
+  offset: number,
+) => { out: TOut; offset: number };
+
+export class ParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ParseError";
+  }
+}
+
+// Primitive types.
+
+function assertInBounds(data: readonly FieldElement[], offset: number) {
+  if (offset >= data.length) {
+    throw new ParseError(
+      `Offset out of bounds. Data length ${data.length}, offset ${offset}`,
+    );
+  }
+}
+
+export function parseBool(data: readonly FieldElement[], offset: number) {
+  assertInBounds(data, offset);
+  return { out: BigInt(data[offset]) > 0n, offset: offset + 1 };
+}
+
+export function parseAsBigInt(data: readonly FieldElement[], offset: number) {
+  assertInBounds(data, offset);
+  return { out: BigInt(data[offset]), offset: offset + 1 };
+}
+
+export const parseU8 = parseAsBigInt;
+export const parseU16 = parseAsBigInt;
+export const parseU32 = parseAsBigInt;
+export const parseU64 = parseAsBigInt;
+export const parseU128 = parseAsBigInt;
+export const parseUsize = parseAsBigInt;
+
+export function parseU256(data: readonly FieldElement[], offset: number) {
+  assertInBounds(data, offset + 1);
+  return {
+    out: BigInt(data[offset]) + (BigInt(data[offset + 1]) << 128n),
+    offset: offset + 2,
+  };
+}
+
+export function parseAsHex(data: readonly FieldElement[], offset: number) {
+  assertInBounds(data, offset);
+  return {
+    out: String(data[offset]),
+    offset: offset + 1,
+  };
+}
+
+export const parseContractAddress = parseAsHex;
+export const parseEthAddress = parseAsHex;
+export const parseStorageAddress = parseAsHex;
+export const parseClassHash = parseAsHex;
+export const parseBytes31 = parseAsHex;
+
+export function parseFelt252(data: readonly FieldElement[], offset: number) {
+  assertInBounds(data, offset);
+  return {
+    out: BigInt(data[offset]),
+    offset: offset + 1,
+  };
+}
+
+export function parseEmpty(data: readonly FieldElement[], offset: number) {
+  return { out: null, offset };
+}
+
+// Higher-level types.
+
+export function parseArray<T>(type: Parser<T>): Parser<T[]> {
+  return (data: readonly FieldElement[], startingOffset: number) => {
+    let offset = startingOffset;
+    const length = BigInt(data[offset]);
+
+    offset++;
+
+    const out: T[] = [];
+    for (let i = 0; i < length; i++) {
+      const { out: item, offset: newOffset } = type(data, offset);
+      out.push(item);
+      offset = newOffset;
+    }
+
+    return { out, offset };
+  };
+}
+
+export const parseSpan = parseArray;
+
+export function parseOption<T>(type: Parser<T>) {
+  return (data: readonly FieldElement[], offset: number) => {
+    const hasValue = BigInt(data[offset]) === 1n;
+    if (hasValue) {
+      return type(data, offset + 1);
+    }
+    return { out: null, offset: offset + 1 };
+  };
+}
+
+export function parseStruct<T extends { [key: string]: unknown }>(
+  parsers: { [K in keyof T]: { index: number; parser: Parser<T[K]> } },
+) {
+  const sortedParsers = Object.entries(parsers).sort(
+    (a, b) => a[1].index - b[1].index,
+  );
+  return (data: readonly FieldElement[], startingOffset: number) => {
+    let offset = startingOffset;
+    const out: Record<string, unknown> = {};
+    for (const [key, { parser }] of sortedParsers) {
+      const { out: value, offset: newOffset } = parser(data, offset);
+      out[key] = value;
+      offset = newOffset;
+    }
+    return { out, offset };
+  };
+}
+
+export function parseTuple<T extends Parser<unknown>[]>(
+  ...parsers: T
+): Parser<UnwrapParsers<T>> {
+  return (data: readonly FieldElement[], startingOffset: number) => {
+    let offset = startingOffset;
+    const out = [];
+    for (const parser of parsers) {
+      const { out: value, offset: newOffset } = parser(data, offset);
+      out.push(value);
+      offset = newOffset;
+    }
+    return { out, offset } as { out: UnwrapParsers<T>; offset: number };
+  };
+}
+
+type UnwrapParsers<TP> = {
+  [Index in keyof TP]: TP[Index] extends Parser<infer U> ? U : never;
+};