add upgrading documentation

docs/v2/getting-started/upgrading/index.mdx

@@ -0,0 +1,155 @@
+---
+title: Upgrading from v1
+description: "Learn how to upgrade your indexers to Apibara v2."
+diataxis: how-to
+updatedAt: 2024-12-04
+---
+
+# 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.
+
+## Main changes
+
+ - The underlying gRPC protocol and data types have changed. You can review all
+ the changes [on this page](/docs/v2/networks/starknet/upgrade-from-v1).
+ - 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](/docs/v2/getting-started/plugins).
+
+## Missing (but planned) features
+
+These features will be added before the final DNA v2 release:
+
+ - Support pending (mempool) data. 
+ - Add missing integrations like MongoDB.
+
+## Migration
+
+For this guide, we'll assume an indexer like the following:
+
+```ts [indexer.ts]
+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:
+
+```bash [Terminal]
+npm init -y
+```
+
+Create the `indexers/` folder where all the indexers will live:
+
+```bash [Terminal]
+mkdir indexers
+```
+
+Add the dependencies needed to run the indexer. If you're using any external
+dependencies, make sure to add them.
+
+:::cli-command
+
+```bash [Terminal]
+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. 
+
+```ts [apibara.config.ts]
+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](/docs/v2/networks/starknet/filter) 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
+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
+```

docs/v2/sidebar.json

@@ -18,6 +18,11 @@
           "name": "Plugins & Hooks",
           "type": "page",
           "path": "/getting-started/plugins"
+        },
+        {
+          "name": "Upgrading from v1",
+          "type": "page",
+          "path": "/getting-started/upgrading"
         }
       ]
     },