@apibara/starknet 2.0.0-beta.4 → 2.0.0-beta.40

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/filter.test.ts

@@ -2,9 +2,12 @@ import { Schema } from "@effect/schema";
 import { describe, expect, it } from "vitest";
 
 import {
+  ContractChangeFilter,
   EventFilter,
   HeaderFilter,
   Key,
+  NonceUpdateFilter,
+  StorageDiffFilter,
   TransactionFilter,
   mergeFilter,
 } from "./filter";
@@ -14,7 +17,7 @@ describe("HeaderFilter", () => {
   const decode = Schema.decodeSync(HeaderFilter);
 
   it("should encode and decode", () => {
-    const always = { always: true };
+    const always = "always";
 
     const proto = encode(always);
     const decoded = decode(proto);
@@ -468,27 +471,168 @@ describe("TransactionFilter", () => {
   });
 });
 
+describe("StorageDiffFilter", () => {
+  const encode = Schema.encodeSync(StorageDiffFilter);
+  const decode = Schema.decodeSync(StorageDiffFilter);
+
+  it("should encode and decode storage diffs", () => {
+    const proto = encode({
+      contractAddress: "0xAABBCCDD",
+    });
+
+    expect(proto).toMatchInlineSnapshot(`
+      {
+        "contractAddress": {
+          "x0": 0n,
+          "x1": 0n,
+          "x2": 0n,
+          "x3": 2864434397n,
+        },
+      }
+    `);
+    const decoded = decode(proto);
+    expect(decoded).toMatchInlineSnapshot(`
+      {
+        "contractAddress": "0x00000000000000000000000000000000000000000000000000000000aabbccdd",
+      }
+    `);
+  });
+});
+
+describe("ContractChangeFilter", () => {
+  const encode = Schema.encodeSync(ContractChangeFilter);
+  const decode = Schema.decodeSync(ContractChangeFilter);
+
+  it("should encode and decode declared class changes", () => {
+    const proto = encode({
+      change: {
+        _tag: "declaredClass",
+        declaredClass: {},
+      },
+    });
+    expect(proto).toMatchInlineSnapshot(`
+      {
+        "change": {
+          "$case": "declaredClass",
+          "declaredClass": {},
+        },
+      }
+    `);
+    const decoded = decode(proto);
+    expect(decoded).toMatchInlineSnapshot(`
+      {
+        "change": {
+          "_tag": "declaredClass",
+          "declaredClass": {},
+        },
+      }
+    `);
+  });
+
+  it("should encode and decode replaced class changes", () => {
+    const proto = encode({
+      change: {
+        _tag: "replacedClass",
+        replacedClass: {},
+      },
+    });
+    expect(proto).toMatchInlineSnapshot(`
+      {
+        "change": {
+          "$case": "replacedClass",
+          "replacedClass": {},
+        },
+      }
+    `);
+    const decoded = decode(proto);
+    expect(decoded).toMatchInlineSnapshot(`
+      {
+        "change": {
+          "_tag": "replacedClass",
+          "replacedClass": {},
+        },
+      }
+    `);
+  });
+
+  it("should encode and decode deployed contract changes", () => {
+    const proto = encode({
+      change: {
+        _tag: "deployedContract",
+        deployedContract: {},
+      },
+    });
+    expect(proto).toMatchInlineSnapshot(`
+      {
+        "change": {
+          "$case": "deployedContract",
+          "deployedContract": {},
+        },
+      }
+    `);
+    const decoded = decode(proto);
+    expect(decoded).toMatchInlineSnapshot(`
+      {
+        "change": {
+          "_tag": "deployedContract",
+          "deployedContract": {},
+        },
+      }
+    `);
+  });
+});
+
+describe("NonceUpdateFilter", () => {
+  const encode = Schema.encodeSync(NonceUpdateFilter);
+  const decode = Schema.decodeSync(NonceUpdateFilter);
+
+  it("should encode and decode nonce updates", () => {
+    const proto = encode({
+      contractAddress: "0xAABBCCDD",
+    });
+
+    expect(proto).toMatchInlineSnapshot(`
+      {
+        "contractAddress": {
+          "x0": 0n,
+          "x1": 0n,
+          "x2": 0n,
+          "x3": 2864434397n,
+        },
+      }
+    `);
+    const decoded = decode(proto);
+    expect(decoded).toMatchInlineSnapshot(`
+      {
+        "contractAddress": "0x00000000000000000000000000000000000000000000000000000000aabbccdd",
+      }
+        `);
+  });
+});
+
 describe("mergeFilter", () => {
   it("returns header.always if any has it", () => {
-    const fa = mergeFilter({}, { header: { always: true } });
+    const fa = mergeFilter({}, { header: "always" });
     expect(fa).toMatchInlineSnapshot(`
       {
+        "contractChanges": [],
         "events": [],
-        "header": {
-          "always": true,
-        },
+        "header": "always",
         "messages": [],
+        "nonceUpdates": [],
+        "storageDiffs": [],
         "transactions": [],
       }
     `);
-    const fb = mergeFilter({ header: { always: true } }, {});
+    const fb = mergeFilter({ header: "always" }, {});
     expect(fb).toMatchInlineSnapshot(`
       {
+        "contractChanges": [],
         "events": [],
-        "header": {
-          "always": true,
-        },
+        "header": "always",
         "messages": [],
+        "nonceUpdates": [],
+        "storageDiffs": [],
         "transactions": [],
       }
     `);
@@ -498,9 +642,12 @@ describe("mergeFilter", () => {
     const f = mergeFilter({}, {});
     expect(f).toMatchInlineSnapshot(`
       {
+        "contractChanges": [],
         "events": [],
         "header": undefined,
         "messages": [],
+        "nonceUpdates": [],
+        "storageDiffs": [],
         "transactions": [],
       }
     `);
@@ -517,9 +664,12 @@ describe("mergeFilter", () => {
     );
     expect(f).toMatchInlineSnapshot(`
       {
+        "contractChanges": [],
         "events": [],
         "header": undefined,
         "messages": [],
+        "nonceUpdates": [],
+        "storageDiffs": [],
         "transactions": [
           {
             "transactionType": {
@@ -545,6 +695,7 @@ describe("mergeFilter", () => {
     );
     expect(f).toMatchInlineSnapshot(`
       {
+        "contractChanges": [],
         "events": [
           {
             "address": "0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
@@ -555,6 +706,8 @@ describe("mergeFilter", () => {
         ],
         "header": undefined,
         "messages": [],
+        "nonceUpdates": [],
+        "storageDiffs": [],
         "transactions": [],
       }
     `);
@@ -567,6 +720,7 @@ describe("mergeFilter", () => {
     );
     expect(f).toMatchInlineSnapshot(`
       {
+        "contractChanges": [],
         "events": [],
         "header": undefined,
         "messages": [
@@ -577,6 +731,100 @@ describe("mergeFilter", () => {
             "fromAddress": "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
           },
         ],
+        "nonceUpdates": [],
+        "storageDiffs": [],
+        "transactions": [],
+      }
+    `);
+  });
+
+  it("concatenates storage diffs", () => {
+    const f = mergeFilter(
+      { storageDiffs: [{ contractAddress: "0xAABBCCDD" }] },
+      { storageDiffs: [{ contractAddress: "0xBBBBCCDD" }] },
+    );
+
+    expect(f).toMatchInlineSnapshot(`
+      {
+        "contractChanges": [],
+        "events": [],
+        "header": undefined,
+        "messages": [],
+        "nonceUpdates": [],
+        "storageDiffs": [
+          {
+            "contractAddress": "0xAABBCCDD",
+          },
+          {
+            "contractAddress": "0xBBBBCCDD",
+          },
+        ],
+        "transactions": [],
+      }
+    `);
+  });
+
+  it("concatenates contract changes", () => {
+    const f = mergeFilter(
+      {
+        contractChanges: [
+          { change: { _tag: "declaredClass", declaredClass: {} } },
+        ],
+      },
+      {
+        contractChanges: [
+          { change: { _tag: "replacedClass", replacedClass: {} } },
+        ],
+      },
+    );
+
+    expect(f).toMatchInlineSnapshot(`
+      {
+        "contractChanges": [
+          {
+            "change": {
+              "_tag": "declaredClass",
+              "declaredClass": {},
+            },
+          },
+          {
+            "change": {
+              "_tag": "replacedClass",
+              "replacedClass": {},
+            },
+          },
+        ],
+        "events": [],
+        "header": undefined,
+        "messages": [],
+        "nonceUpdates": [],
+        "storageDiffs": [],
+        "transactions": [],
+      }
+    `);
+  });
+
+  it("concatenates nonce updates", () => {
+    const f = mergeFilter(
+      { nonceUpdates: [{ contractAddress: "0xAABBCCDD" }] },
+      { nonceUpdates: [{ contractAddress: "0xBBBBCCDD" }] },
+    );
+
+    expect(f).toMatchInlineSnapshot(`
+      {
+        "contractChanges": [],
+        "events": [],
+        "header": undefined,
+        "messages": [],
+        "nonceUpdates": [
+          {
+            "contractAddress": "0xAABBCCDD",
+          },
+          {
+            "contractAddress": "0xBBBBCCDD",
+          },
+        ],
+        "storageDiffs": [],
         "transactions": [],
       }
     `);

package/src/filter.ts

@@ -6,11 +6,39 @@ import * as proto from "./proto";
 
 /** Header options.
  *
- * Change `always` to `true` to receive headers even if no other data matches.
+ * - `always`: receive all block headers.
+ * - `on_data`: receive headers only if any other filter matches.
+ * - `on_data_or_on_new_block`: receive headers only if any other filter matches and for "live" blocks.
  */
-export const HeaderFilter = Schema.Struct({
-  always: Schema.optional(Schema.Boolean),
-});
+export const HeaderFilter = Schema.transform(
+  Schema.Enums(proto.filter.HeaderFilter),
+  Schema.Literal("always", "on_data", "on_data_or_on_new_block", "unknown"),
+  {
+    decode(value) {
+      const enumMap = {
+        [proto.filter.HeaderFilter.ALWAYS]: "always",
+        [proto.filter.HeaderFilter.ON_DATA]: "on_data",
+        [proto.filter.HeaderFilter.ON_DATA_OR_ON_NEW_BLOCK]:
+          "on_data_or_on_new_block",
+        [proto.filter.HeaderFilter.UNSPECIFIED]: "unknown",
+        [proto.filter.HeaderFilter.UNRECOGNIZED]: "unknown",
+      } as const;
+      return enumMap[value] ?? "unknown";
+    },
+    encode(value) {
+      switch (value) {
+        case "always":
+          return proto.filter.HeaderFilter.ALWAYS;
+        case "on_data":
+          return proto.filter.HeaderFilter.ON_DATA;
+        case "on_data_or_on_new_block":
+          return proto.filter.HeaderFilter.ON_DATA_OR_ON_NEW_BLOCK;
+        default:
+          return proto.filter.HeaderFilter.UNSPECIFIED;
+      }
+    },
+  },
+);
 
 export type HeaderFilter = typeof HeaderFilter.Type;
 
@@ -202,11 +230,68 @@ export const TransactionFilter = Schema.Struct({
 
 export type TransactionFilter = typeof TransactionFilter.Type;
 
+/** Filter storage diffs.
+ *
+ *  @prop contractAddress Filter by contract address.
+ */
+export const StorageDiffFilter = Schema.Struct({
+  id: Schema.optional(Schema.Number),
+  contractAddress: Schema.optional(FieldElement),
+});
+
+export type StorageDiffFilter = typeof StorageDiffFilter.Type;
+
+/** Filter declared classes. */
+export const DeclaredClassFilter = Schema.Struct({
+  _tag: tag("declaredClass"),
+  declaredClass: Schema.Struct({}),
+});
+
+export type DeclaredClassFilter = typeof DeclaredClassFilter.Type;
+
+export const ReplacedClassFilter = Schema.Struct({
+  _tag: tag("replacedClass"),
+  replacedClass: Schema.Struct({}),
+});
+
+export type ReplacedClassFilter = typeof ReplacedClassFilter.Type;
+
+export const DeployedContractFilter = Schema.Struct({
+  _tag: tag("deployedContract"),
+  deployedContract: Schema.Struct({}),
+});
+
+export type DeployedContractFilter = typeof DeployedContractFilter.Type;
+
+/** Filter contract changes. */
+export const ContractChangeFilter = Schema.Struct({
+  id: Schema.optional(Schema.Number),
+  change: Schema.optional(
+    Schema.Union(
+      DeclaredClassFilter,
+      ReplacedClassFilter,
+      DeployedContractFilter,
+    ),
+  ),
+});
+
+/** Filter updates to nonces.
+ *
+ * @prop contractAddress Filter by contract address.
+ */
+export const NonceUpdateFilter = Schema.Struct({
+  id: Schema.optional(Schema.Number),
+  contractAddress: Schema.optional(FieldElement),
+});
+
 export const Filter = Schema.Struct({
   header: Schema.optional(HeaderFilter),
   transactions: Schema.optional(Schema.Array(TransactionFilter)),
   events: Schema.optional(Schema.Array(EventFilter)),
   messages: Schema.optional(Schema.Array(MessageToL1Filter)),
+  storageDiffs: Schema.optional(Schema.Array(StorageDiffFilter)),
+  contractChanges: Schema.optional(Schema.Array(ContractChangeFilter)),
+  nonceUpdates: Schema.optional(Schema.Array(NonceUpdateFilter)),
 });
 
 export type Filter = typeof Filter.Type;
@@ -238,6 +323,12 @@ export function mergeFilter(a: Filter, b: Filter): Filter {
     transactions: [...(a.transactions ?? []), ...(b.transactions ?? [])],
     events: [...(a.events ?? []), ...(b.events ?? [])],
     messages: [...(a.messages ?? []), ...(b.messages ?? [])],
+    storageDiffs: [...(a.storageDiffs ?? []), ...(b.storageDiffs ?? [])],
+    contractChanges: [
+      ...(a.contractChanges ?? []),
+      ...(b.contractChanges ?? []),
+    ],
+    nonceUpdates: [...(a.nonceUpdates ?? []), ...(b.nonceUpdates ?? [])],
   };
 }
 
@@ -251,7 +342,14 @@ function mergeHeaderFilter(
   if (b === undefined) {
     return a;
   }
-  return {
-    always: a.always || b.always,
-  };
+
+  if (a === "always" || b === "always") {
+    return "always";
+  }
+
+  if (a === "on_data_or_on_new_block" || b === "on_data_or_on_new_block") {
+    return "on_data_or_on_new_block";
+  }
+
+  return "on_data";
 }

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,