@apibara/indexer 0.1.1 → 0.2.0

package/src/config.test-d.ts

@@ -0,0 +1,55 @@
+import { assertType, describe, test } from "vitest";
+
+import { Config } from "./config";
+
+describe("Config", () => {
+  test("without any network or sink type", () => {
+    assertType<Config>({
+      network: "test-network",
+      filter: {},
+      sinkType: "test-sink",
+      sinkOptions: {},
+    });
+  });
+
+  test("with restrictions on network and sink", () => {
+    type Network = {
+      network: "test-network";
+      filter: { a: number };
+    };
+
+    type Sink = {
+      sinkType: "test-sink";
+      sinkOptions: {
+        b: string;
+      };
+    };
+
+    assertType<Config<Network, Sink>>({
+      network: "test-network",
+      filter: {
+        a: 1,
+      },
+      sinkType: "test-sink",
+      sinkOptions: {
+        b: "test",
+      },
+    });
+  });
+
+  test("network options are required", () => {
+    // @ts-expect-error - missing network options
+    assertType<Config>({
+      sinkType: "test-sink",
+      sinkOptions: {},
+    });
+  });
+
+  test("sink options are required", () => {
+    // @ts-expect-error - missing sink options
+    assertType<Config>({
+      network: "test-network",
+      filter: {},
+    });
+  });
+});

package/src/config.ts

@@ -0,0 +1,47 @@
+/** Sink-related options. */
+export type SinkOptions = {
+  /** Sink type. */
+  sinkType: string;
+  /** Sink options. */
+  sinkOptions: object;
+};
+
+/** Network-specific options. */
+export type NetworkOptions = {
+  /** Network name. */
+  network: string;
+  /** Data filter. */
+  filter: object;
+};
+
+/** Data finality. */
+export type Finality =
+  | "DATA_STATUS_FINALIZED"
+  | "DATA_STATUS_ACCEPTED"
+  | "DATA_STATUS_PENDING";
+
+/** Stream-related options. */
+export type StreamOptions = {
+  /** The Apibara DNA stream url, e.g. `mainnet.starknet.a5a.ch`. */
+  streamUrl?: string;
+  /** Maximum message size, e.g. `50Mb` */
+  maxMessageSize?: string;
+  /** Additional metadata to send when connecting to the stream, in `key: value` form. */
+  metadata?: string[];
+  /** The Apibara DNA stream auth token. */
+  authToken?: string;
+};
+
+export type Config<
+  TNetworkOptions extends NetworkOptions = NetworkOptions,
+  TSink extends SinkOptions = SinkOptions,
+> = TSink &
+  TNetworkOptions &
+  StreamOptions & {
+    /** How many historical blocks to process in a single batch. */
+    batchSize?: number;
+    /** Finality of the data to process. */
+    finality?: Finality;
+    /** Start streaming data from this block. */
+    startingBlock?: number;
+  };

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./config";

package/src/sink/console.test-d.ts

@@ -0,0 +1,14 @@
+import { assertType, describe, test } from "vitest";
+
+import { Console } from "./console";
+
+describe("Console", () => {
+  test("accepts any option", () => {
+    assertType<Console>({
+      sinkType: "console",
+      sinkOptions: {
+        hello: "world",
+      },
+    });
+  });
+});

package/src/sink/console.ts

@@ -0,0 +1,11 @@
+/** Console sink type. */
+export type Console = {
+  sinkType: "console";
+
+  /** Accept any options.
+   *
+   * @remarks We do this so that users can quickly switch to the console sink to debug,
+   * without having to remove the options from the config file.
+   */
+  sinkOptions: object;
+};

package/src/sink/mongo.ts

@@ -0,0 +1,14 @@
+/** MongoDB sink options */
+export type Mongo = {
+  sinkType: "mongo";
+  sinkOptions: {
+    /** MongoDB connection string. */
+    connectionString?: string;
+    /** Target database name. */
+    database?: string;
+    /** Target collection name. */
+    collectionName?: string;
+    /** Enable entity mode. */
+    entityMode?: boolean;
+  };
+};

package/src/sink/parquet.ts

@@ -0,0 +1,9 @@
+export type Parquet = {
+  sinkType: "parquet";
+  sinkOptions: {
+    /** Target output directory. */
+    outputDir?: string;
+    /** How many blocks to include in each file. */
+    batchSize?: number;
+  };
+};

package/src/sink/postgres.ts

@@ -0,0 +1,10 @@
+/** PostgreSQL sink options. */
+export type Postgres = {
+  sinkType: "postgres";
+  sinkOptions: {
+    /** Postgres connection string. */
+    connectionString?: string;
+    /** Target table name. */
+    tableName?: string;
+  };
+};

package/src/sink/webhook.ts

@@ -0,0 +1,12 @@
+/** Webhook sink options */
+export type Webhook = {
+  sinkType: "webhook";
+  sinkOptions: {
+    /** Target URL. */
+    targetUrl?: string;
+    /** Additional headers to send with the request, `key: value` format. */
+    header?: string[];
+    /** Send the data returned from the transform function as the request body. */
+    raw?: boolean;
+  };
+};

package/src/starknet/block.ts

@@ -0,0 +1,181 @@
+import { FieldElement } from "./felt";
+
+export type Block = {
+  header?: BlockHeader;
+  transactions: TransactionWithReceipt[];
+  events: EventWithTransaction[];
+  l2ToL1Messages: L2ToL1MessageWithTransaction[];
+  stateUpdate: StateUpdate;
+};
+
+export type BlockHeader = {
+  blockHash: FieldElement;
+  parentBlockHash: FieldElement;
+  blockNumber: string;
+  sequencerAddress: FieldElement;
+  newRoot: FieldElement;
+  timestamp: string;
+};
+
+export type TransactionWithReceipt = {
+  transaction: Transaction;
+  receipt: TransactionReceipt;
+};
+
+export type EventWithTransaction = {
+  transaction: Transaction;
+  receipt: TransactionReceipt;
+  event: Event;
+};
+
+export type L2ToL1MessageWithTransaction = {
+  transaction: Transaction;
+  message: L2ToL1Message;
+};
+
+export type Transaction = {
+  meta: TransactionMeta;
+} & TransactionBody;
+
+export type TransactionBody =
+  | {
+      invokeV0: InvokeTransactionV0;
+    }
+  | {
+      invokeV1: InvokeTransactionV1;
+    }
+  | {
+      deploy: DeployTransaction;
+    }
+  | {
+      declare: DeclareTransaction;
+    }
+  | {
+      deployAccount: DeployAccountTransaction;
+    }
+  | {
+      l1Handler: L1HandlerTransaction;
+    };
+
+export type TransactionMeta = {
+  hash: FieldElement;
+  maxFee: FieldElement;
+  signature: FieldElement[];
+  nonce: FieldElement;
+  version: string;
+};
+
+export type InvokeTransactionV0 = {
+  contractAddress: FieldElement;
+  entryPointSelector: FieldElement;
+  calldata: FieldElement[];
+};
+
+export type InvokeTransactionV1 = {
+  contractAddress: FieldElement;
+  entryPointSelector: FieldElement;
+  calldata: FieldElement[];
+};
+
+export type DeployTransaction = {
+  constructorCalldata: FieldElement[];
+  contractAddressSalt: FieldElement;
+  classHash: FieldElement;
+};
+
+export type DeclareTransaction = {
+  classHash: FieldElement;
+  senderAddress: FieldElement;
+  compiledClassHash: FieldElement;
+};
+
+export type DeployAccountTransaction = {
+  constructorCalldata: FieldElement[];
+  contractAddressSalt: FieldElement;
+  classHash: FieldElement;
+};
+
+export type L1HandlerTransaction = {
+  contractAddress: FieldElement;
+  entryPointSelector: FieldElement;
+  calldata: FieldElement[];
+};
+
+export type TransactionReceipt = {
+  executionStatus: ExecutionStatus;
+  transactionHash: FieldElement;
+  transactionIndex: string;
+  actualFee: FieldElement;
+  contractAddress: FieldElement;
+  l2ToL1Messages: L2ToL1Message[];
+  events: Event[];
+  revertReason?: string;
+};
+
+export type ExecutionStatus =
+  | "EXECUTION_STATUS_UNSPECIFIED"
+  | "EXECUTION_STATUS_SUCCEEDED"
+  | "EXECUTION_STATUS_REVERTED";
+
+export type Event = {
+  index: number;
+  fromAddress: FieldElement;
+  keys: FieldElement[];
+  data: FieldElement[];
+};
+
+export type L2ToL1Message = {
+  index: number;
+  fromAddress: FieldElement;
+  toAddress: FieldElement;
+  payload: FieldElement[];
+};
+
+export type StateUpdate = {
+  newRoot: FieldElement;
+  oldRoot: FieldElement;
+  stateDiff: StateDiff;
+};
+
+export type StateDiff = {
+  storageDiffs: StorageDiff[];
+  declaredContracts: DeclaredContract[];
+  deployedContracts: DeployedContract[];
+  nonces: NonceUpdate[];
+  declaredClasses: DeclaredClass[];
+  replacedClasses: ReplacedClass[];
+};
+
+export type StorageDiff = {
+  contractAddress: FieldElement;
+  storageEntries: StorageEntry[];
+};
+
+export type StorageEntry = {
+  key: FieldElement;
+  value: FieldElement;
+};
+
+export type DeclaredContract = {
+  classHash: FieldElement;
+};
+
+export type DeclaredClass = {
+  classHash: FieldElement;
+  compiledClassHash: FieldElement;
+};
+
+export type ReplacedClass = {
+  contractAddress: FieldElement;
+  classHash: FieldElement;
+};
+
+export type DeployedContract = {
+  contractAddress: FieldElement;
+  classHash: FieldElement;
+};
+
+export type NonceUpdate = {
+  contractAddress: FieldElement;
+  nonce: FieldElement;
+};

package/src/starknet/felt.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, test } from "vitest";
+
+import { FieldElement } from "./felt";
+
+describe("FieldElement", () => {
+  test("parse address", () => {
+    FieldElement.parse(
+      "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
+    );
+  });
+
+  test("parse value", () => {
+    FieldElement.parse("0x1");
+  });
+
+  test("parse invalid value", () => {
+    expect(() => FieldElement.parse("0x")).toThrowError();
+  });
+});

package/src/starknet/felt.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+
+export type FieldElement = `0x${string}`;
+
+export const FieldElement = z.string().transform((value, ctx) => {
+  const regex = /^0x[0-9a-fA-F]{1,64}$/;
+
+  if (!regex.test(value)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `FieldElement must be a hex string with a 0x prefix, got ${value}`,
+    });
+  }
+
+  return value as FieldElement;
+});

package/src/starknet/filter.test-d.ts

@@ -0,0 +1,197 @@
+import { assertType, describe, test } from "vitest";
+
+import { FieldElement } from "./felt";
+import {
+  EventFilter,
+  Filter,
+  L2ToL1MessageFilter,
+  StateUpdateFilter,
+  TransactionFilter,
+} from "./filter";
+
+const address =
+  "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
+const entryPointSelector =
+  "0x03943907ef0ef6f9d2e2408b05e520a66daaf74293dbf665e5a20b117676170e";
+const calldata = [FieldElement.parse("0x01"), FieldElement.parse("0x02")];
+
+describe("Filter", () => {
+  test("all optional", () => {
+    assertType<Filter>({});
+  });
+});
+
+describe("TransactionFilter", () => {
+  test("all optional", () => {
+    assertType<TransactionFilter>({});
+  });
+
+  test("includeReverted", () => {
+    assertType<TransactionFilter>({ includeReverted: true });
+  });
+
+  test("only one inner filter", () => {
+    // @ts-expect-error - multiple inner filters
+    assertType<TransactionFilter>({
+      invokeV0: {},
+      deployAccount: {},
+    });
+  });
+
+  test("filter invoke transaction v0", () => {
+    assertType<TransactionFilter>({
+      invokeV0: {
+        contractAddress: address,
+        entryPointSelector,
+        calldata,
+      },
+    });
+  });
+
+  test("filter invoke transaction v1", () => {
+    assertType<TransactionFilter>({
+      invokeV1: {
+        senderAddress: address,
+        calldata,
+      },
+    });
+  });
+
+  test("filter deploy transaction", () => {
+    assertType<TransactionFilter>({
+      deploy: {
+        contractAddressSalt: address,
+        classHash: address,
+        constructorCalldata: calldata,
+      },
+    });
+  });
+
+  test("filter declare transaction", () => {
+    assertType<TransactionFilter>({
+      declare: {
+        senderAddress: address,
+        classHash: address,
+      },
+    });
+  });
+
+  test("filter l1 handler transaction", () => {
+    assertType<TransactionFilter>({
+      l1Handler: {
+        contractAddress: address,
+        entryPointSelector,
+        calldata,
+      },
+    });
+  });
+
+  test("filter deploy account transaction", () => {
+    assertType<TransactionFilter>({
+      deployAccount: {
+        contractAddressSalt: address,
+        classHash: address,
+        constructorCalldata: calldata,
+      },
+    });
+  });
+});
+
+describe("EventFilter", () => {
+  test("all optional", () => {
+    assertType<EventFilter>({});
+  });
+
+  test("with properties", () => {
+    assertType<EventFilter>({
+      fromAddress: address,
+      keys: [entryPointSelector],
+      includeReverted: true,
+      data: calldata,
+    });
+  });
+});
+
+describe("L2ToL1MessageFilter", () => {
+  test("all optional", () => {
+    assertType<L2ToL1MessageFilter>({});
+  });
+
+  test("with properties", () => {
+    assertType<L2ToL1MessageFilter>({
+      toAddress: address,
+      includeReverted: true,
+      payload: calldata,
+    });
+  });
+});
+
+describe("StateUpdateFilter", () => {
+  test("all optional", () => {
+    assertType<StateUpdateFilter>({});
+  });
+
+  test("with storage diffs", () => {
+    assertType<StateUpdateFilter>({
+      storageDiffs: [
+        {
+          contractAddress: address,
+        },
+      ],
+    });
+  });
+
+  test("with declared contracts", () => {
+    assertType<StateUpdateFilter>({
+      declaredContracts: [
+        {
+          classHash: address,
+        },
+      ],
+    });
+  });
+
+  test("with deployed contracts", () => {
+    assertType<StateUpdateFilter>({
+      deployedContracts: [
+        {
+          classHash: address,
+          contractAddress: address,
+        },
+      ],
+    });
+  });
+
+  test("with nonces", () => {
+    assertType<StateUpdateFilter>({
+      nonces: [
+        {
+          contractAddress: address,
+          nonce: "0x1",
+        },
+      ],
+    });
+  });
+
+  test("with declared classes", () => {
+    assertType<StateUpdateFilter>({
+      declaredClasses: [
+        {
+          compiledClassHash: address,
+          classHash: address,
+        },
+      ],
+    });
+  });
+
+  test("with replaced classes", () => {
+    assertType<StateUpdateFilter>({
+      replacedClasses: [
+        {
+          contractAddress: address,
+          classHash: address,
+        },
+      ],
+    });
+  });
+});