@apibara/starknet 2.0.0-beta.7 → 2.0.0-beta.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apibara/starknet",
-  "version": "2.0.0-beta.7",
+  "version": "2.0.0-beta.9",
   "type": "module",
   "files": [
     "dist",
@@ -36,7 +36,7 @@
     "vitest": "^1.6.0"
   },
   "dependencies": {
-    "@apibara/protocol": "2.0.0-beta.7",
+    "@apibara/protocol": "2.0.0-beta.9",
     "@effect/schema": "^0.67.15",
     "effect": "^3.2.6",
     "long": "^5.2.1",

package/src/block.ts

@@ -479,6 +479,103 @@ export const MessageToL1 = Schema.Struct({
 
 export type MessageToL1 = typeof MessageToL1.Type;
 
+/** An entry in the storage diff.
+ *
+ * @prop key The storage location.
+ * @prop value The new value at the storage location.
+ */
+export const StorageEntry = Schema.Struct({
+  key: Schema.optional(FieldElement),
+  value: Schema.optional(FieldElement),
+});
+
+export type StorageEntry = typeof StorageEntry.Type;
+
+/** Storage diff.
+ *
+ * @prop contractAddress The contract address.
+ * @prop storageEntries The entries that changed.
+ */
+export const StorageDiff = Schema.Struct({
+  filterIds: Schema.optional(Schema.Array(Schema.Number)),
+  contractAddress: Schema.optional(FieldElement),
+  storageEntries: Schema.optional(Schema.Array(StorageEntry)),
+});
+
+export type StorageDiff = typeof StorageDiff.Type;
+
+/** A new class declared.
+ *
+ * @prop classHash The class hash.
+ * @prop compiledClassHash The compiled class hash. If undefined, it's the result of a deprecated Cairo 0 declaration.
+ */
+export const DeclaredClass = Schema.Struct({
+  _tag: tag("declaredClass"),
+  declaredClass: Schema.Struct({
+    classHash: Schema.optional(FieldElement),
+    compiledClassHash: Schema.optional(FieldElement),
+  }),
+});
+
+export type DeclaredClass = typeof DeclaredClass.Type;
+
+/** A class replaced.
+ *
+ * @prop contractAddress The contract address.
+ * @prop classHash The class new hash.
+ */
+export const ReplacedClass = Schema.Struct({
+  _tag: tag("replacedClass"),
+  replacedClass: Schema.Struct({
+    contractAddress: Schema.optional(FieldElement),
+    classHash: Schema.optional(FieldElement),
+  }),
+});
+
+export type ReplacedClass = typeof ReplacedClass.Type;
+
+/** A contract deployed.
+ *
+ * @prop contractAddress The contract address.
+ * @prop classHash The class hash.
+ */
+export const DeployedContract = Schema.Struct({
+  _tag: tag("deployedContract"),
+  deployedContract: Schema.Struct({
+    contractAddress: Schema.optional(FieldElement),
+    classHash: Schema.optional(FieldElement),
+  }),
+});
+
+export type DeployedContract = typeof DeployedContract.Type;
+
+/** A contract change.
+ *
+ * @prop contractAddress The contract address.
+ * @prop change The change.
+ */
+export const ContractChange = Schema.Struct({
+  filterIds: Schema.optional(Schema.Array(Schema.Number)),
+  change: Schema.optional(
+    Schema.Union(DeclaredClass, ReplacedClass, DeployedContract),
+  ),
+});
+
+export type ContractChange = typeof ContractChange.Type;
+
+/** A nonce update.
+ *
+ * @prop contractAddress The contract address.
+ * @prop nonce The new nonce.
+ */
+export const NonceUpdate = Schema.Struct({
+  filterIds: Schema.optional(Schema.Array(Schema.Number)),
+  contractAddress: Schema.optional(FieldElement),
+  nonce: Schema.optional(FieldElement),
+});
+
+export type NonceUpdate = typeof NonceUpdate.Type;
+
 /** A block.
  *
  * @prop header The block header.
@@ -486,6 +583,8 @@ export type MessageToL1 = typeof MessageToL1.Type;
  * @prop receipts The receipts of the transactions.
  * @prop events The events emitted by the transactions.
  * @prop messages The messages sent to L1 by the transactions.
+ * @prop storageDiffs The changes to the storage.
+ * @prop contractChanges The changes to contracts and classes.
  */
 export const Block = Schema.Struct({
   header: Schema.optional(BlockHeader),
@@ -493,6 +592,9 @@ export const Block = Schema.Struct({
   receipts: Schema.Array(TransactionReceipt),
   events: Schema.Array(Event),
   messages: Schema.Array(MessageToL1),
+  storageDiffs: Schema.Array(StorageDiff),
+  contractChanges: Schema.Array(ContractChange),
+  nonceUpdates: Schema.Array(NonceUpdate),
 });
 
 export type Block = typeof Block.Type;

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";
 }