Upgrading from v1

This guide explains how to upgrade your Starknet indexers from the old Apibara CLI experience to the new Apibara v2 experience.

At the time of writing (December 2024), Apibara v2 is still in beta. This means that it's ready for developers to start testing it, but you should not use it in production yet.

• The underlying gRPC protocol and data types have changed. You can review all the changes on this page.
• The old CLI has been replaced by a pure Typescript library. This means you can now leverage the full Node ecosystem (including Bun and Deno).
• You can now extend indexers with plugins and hooks.

These features will be added before the final DNA v2 release:

• Support pending (mempool) data.
• Add missing integrations like MongoDB.

For this guide, we'll assume an indexer like the following:

export const config = {
  streamUrl: "https://mainnet.starknet.a5a.ch",
  startingBlock: 800_000,
  network: "starknet",
  finality: "DATA_STATUS_ACCEPTED",
  filter: {
    header: {},
  },
  sinkType: "console",
  sinkOptions: {},
};

export default function transform(block) {
  return block;
}

Step 1: initialize the Node project

Initialize the project to contain a package.json file:

npm init -y

Create the indexers/ folder where all the indexers will live:

mkdir indexers

Add the dependencies needed to run the indexer. If you're using any external dependencies, make sure to add them.

npm add --save apibara@next @apibara/protocol@next @apibara/indexer@next @apibara/starknet@next

added 325 packages, and audited 327 packages in 11s

73 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

Step 2: initialize the Apibara project

Create a new file called apibara.config.ts in the root of your project.

import { defineConfig } from "apibara/config";

export default defineConfig({});

Step 3: update the indexer

Now it's time to update the indexer.

• Move the indexer to the indexers/ folder, ensuring tha the file name ends with .indexer.ts.
• Wrap the indexer in a defineIndexer(StarknetStream)({ /* ... */ }) call. Notice that now the stream configuration and transform function live in the same configuration object.
• startingBlock is now startingCursor.orderKey.
• streamUrl is the same, but the URL is different while in beta.
• finality is now simpler to type.
• The filter object changed. Please refer to the filter documentation for more information.
• sinkType and sinkOptions are gone.
• The transform function now takes named arguments, with block containing the block data.

The following git diff shows the changes to the indexer at the beginning of the guide.

diff --git a/simple.ts b/indexers/simple.indexer.ts
index bb09fdc..701a494 100644
--- a/simple.ts
+++ b/indexers/simple.indexer.ts
@@ -1,15 +1,18 @@
-export const config = {
-    streamUrl: "https://mainnet.starknet.a5a.ch",
-    startingBlock: 800_000,
-    network: "starknet",
-    finality: "DATA_STATUS_ACCEPTED",
+import { StarknetStream } from "@apibara/starknet";
+import { defineIndexer } from "@apibara/indexer";
+import { useLogger } from "@apibara/indexer/plugins/logger";
+
+export default defineIndexer(StarknetStream)({
+    streamUrl: "https://starknet.preview.apibara.org",
+    startingCursor: {
+        orderKey: 800_000n,
+    },
+    finality: "accepted",
     filter: {
-        header: {},
+        header: "always",
     },
-    sinkType: "console",
-    sinkOptions: {},
-};
-
-export default function transform(block) {
-    return block;
-}
\ No newline at end of file
+    async transform({ block }) {
+        const logger = useLogger();
+        logger.info(block);
+    },
+});
\ No newline at end of file