Migrate a Ponder app to Portal

Replace the stock package instead of installing both packages side by side.

Replace the dependency

npm uninstall ponder
npm install --save-exact @subsquid/ponder@latest

This resolves npm’s current latest tag and saves that exact fork version. Commit the lockfile with the migration.

Update package imports

Import package APIs from @subsquid/ponder in ponder.config.ts, ponder.schema.ts, and API files:

import { createConfig, factory } from "@subsquid/ponder";
import { onchainTable } from "@subsquid/ponder";
import { client, graphql } from "@subsquid/ponder";

Keep Ponder virtual-module imports unchanged:

import { ponder } from "ponder:registry";
import { db } from "ponder:api";
import schema from "ponder:schema";

Add a Portal dataset per chain

Add a portal dataset URL beside each chain’s existing rpc URL:

chains: {
  mainnet: {
    id: 1,
    rpc: process.env.PONDER_RPC_URL_1,
    portal: "https://portal.sqd.dev/datasets/ethereum-mainnet",
  },
}

Keep the RPC configured for realtime indexing, chain setup, and contract reads.

Validate a bounded range

Set a bounded startBlock and endBlock, then run the migrated app:

npm run dev

Compare the resulting rows or application-level aggregates with the stock RPC path before widening the range. The repository’s migration guide includes compatibility checks and tooling that compares the two paths row by row.

Roll back

To return to stock Ponder, replace @subsquid/ponder with ponder, restore package imports, and remove the portal fields. Your handlers, schema, and virtual-module imports do not need to change. Check Benchmarks and validation for the currently tested versions, sources, and datasets. Because the integration tracks active Ponder development, repeat the bounded comparison when upgrading either package line.

Run the Ponder and Portal example

Ponder and Portal examples

⌘I

​Roll back

Roll back