feat(cli): add anvil fork mode to cartesi run

Allow forking from a live chain instead of using pre-baked devnet state.
Adds --fork, --fork-url, and --fork-block-number options.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: tuler

.changeset/shaggy-months-lose.md

@@ -0,0 +1,5 @@
+---
+"@cartesi/cli": patch
+---
+
+add anvil fork mode to `cartesi run`

apps/cli/biome.json

@@ -1,5 +1,5 @@
 {
-    "$schema": "https://biomejs.dev/schemas/2.3.14/schema.json",
+    "$schema": "https://biomejs.dev/schemas/2.3.15/schema.json",
     "root": false,
     "extends": "//",
     "linter": {

apps/cli/package.json

@@ -41,8 +41,9 @@
         "yaml": "^2.8.2"
     },
     "devDependencies": {
-        "@cartesi/devnet": "2.0.0-alpha.9",
+        "@cartesi/devnet": "2.0.0-alpha.10",
         "@cartesi/rollups": "2.1.1",
+        "@sunodo/wagmi-plugin-hardhat-deploy": "^0.4.0",
         "@types/bun": "^1.3.6",
         "@types/bytes": "^3.1.5",
         "@types/fs-extra": "^11.0.4",

apps/cli/src/base.ts

@@ -26,7 +26,7 @@ import {
     testNftAddress,
     testTokenAddress,
 } from "./contracts.js";
-import { getApplicationAddress } from "./exec/rollups.js";
+import { getApplicationAddress, getForkChainId } from "./exec/rollups.js";
 import type { PsResponse } from "./types/docker.js";
 
 export const getContextPath = (...paths: string[]): string => {
@@ -67,13 +67,22 @@ export type AddressBook = Record<string, Address>;
 export const getAddressBook = async (options: {
     projectName?: string;
 }): Promise<AddressBook> => {
+    const forkChainId = (await getForkChainId(options)) ?? 31337;
     const applicationAddress = await getApplicationAddress(options);
 
+    const chainDaveAppFactoryAddress =
+        daveAppFactoryAddress[
+            forkChainId as keyof typeof daveAppFactoryAddress
+        ];
+    if (!chainDaveAppFactoryAddress) {
+        throw new Error(`Unsupported fork chain ${forkChainId}`);
+    }
+
     // build rollups contracts address book
     const contracts: AddressBook = {
         ApplicationFactory: applicationFactoryAddress,
         AuthorityFactory: authorityFactoryAddress,
-        DaveAppFactory: daveAppFactoryAddress,
+        DaveAppFactory: chainDaveAppFactoryAddress,
         EntryPointV06: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
         EntryPointV07: "0x0000000071727De22E5E9d8BAf0edAc6f37da032",
         ERC1155BatchPortal: erc1155BatchPortalAddress,

apps/cli/src/commands/run.ts

@@ -8,20 +8,34 @@ import chalk from "chalk";
 import { ExecaError } from "execa";
 import getPort, { portNumbers } from "get-port";
 import ora from "ora";
-import { type Address, type Hex, numberToHex } from "viem";
+import {
+    type Address,
+    createPublicClient,
+    type Hex,
+    http,
+    numberToHex,
+} from "viem";
 import { getMachineHash, getProjectName } from "../base.js";
 import { DEFAULT_SDK_VERSION, PREFERRED_PORT } from "../config.js";
 import {
     AVAILABLE_SERVICES,
-    type RollupsDeployment,
     deployApplication,
     removeApplication,
+    type RollupsDeployment,
     startEnvironment,
     stopEnvironment,
     waitHealthyEnvironment,
 } from "../exec/rollups.js";
 import { keySelect } from "../prompts.js";
 
+const DEFAULT_FORK_URL = "https://ethereum.reth.rs/rpc";
+
+export type ForkConfig = {
+    blockNumber?: bigint;
+    chainId: number;
+    url: string;
+};
+
 const commaSeparatedList = (value: string) => value.split(",");
 
 const shell = async (options: {
@@ -165,6 +179,37 @@ const deploy = async (options: {
     return application;
 };
 
+const configureFork = async (options: {
+    fork?: true | undefined;
+    forkUrl?: string;
+    forkBlockNumber?: number;
+}): Promise<ForkConfig | undefined> => {
+    // determine fork mode: explicit --fork flag or --fork-url provided
+    const isFork = options.fork || options.forkUrl !== undefined;
+
+    if (!isFork) {
+        return undefined;
+    }
+
+    // assign default fork url
+    const url = options.forkUrl ?? DEFAULT_FORK_URL;
+
+    // create a client to upstream so we can query it
+    const client = createPublicClient({
+        transport: http(url),
+    });
+
+    // use explicit fork-block-number or query from upstream
+    const blockNumber = options.forkBlockNumber
+        ? BigInt(options.forkBlockNumber)
+        : await client.getBlockNumber();
+
+    // need to query fork chainId if forkUrl is specified
+    const chainId = await client.getChainId();
+
+    return { blockNumber, chainId, url };
+};
+
 export const createRunCommand = () => {
     return new Command("run")
         .description("Run a local cartesi node for the application.")
@@ -197,6 +242,17 @@ export const createRunCommand = () => {
                 .default("latest"),
         )
         .option("--dry-run", "show the docker compose configuration", false)
+        .option(
+            "--fork",
+            "fork from a live chain instead of using devnet state",
+        )
+        .option("--fork-url <url>", "RPC URL to fork from (implies --fork)")
+        .addOption(
+            new Option(
+                "--fork-block-number <number>",
+                "block number to fork from",
+            ).argParser(Number),
+        )
         .addOption(
             new Option(
                 "--memory <number>",
@@ -265,12 +321,16 @@ export const createRunCommand = () => {
                     port: portNumbers(PREFERRED_PORT, PREFERRED_PORT + 10),
                 }));
 
+            // configure optional anvil fork
+            const forkConfig = await configureFork(options);
+
             // run compose environment (detached)
             const { address, config } = await startEnvironment({
                 blockTime,
                 cpus,
                 defaultBlock,
                 dryRun,
+                forkConfig,
                 memory,
                 port,
                 projectName,

apps/cli/src/compose/anvil.ts

@@ -1,22 +1,46 @@
+import type { ForkConfig } from "../commands/run.js";
 import type { ComposeFile, Config, Service } from "../types/compose.js";
 import { DEFAULT_HEALTHCHECK } from "./common.js";
 
 type ServiceOptions = {
     imageTag?: string;
     blockTime?: number;
+    forkConfig?: ForkConfig;
 };
 
 // Anvil service
 const service = (options?: ServiceOptions): Service => {
     const blockTime = options?.blockTime ?? 2;
     const imageTag = options?.imageTag ?? "latest";
+    const forkConfig = options?.forkConfig;
+
+    // command for fork and command for load-state local (non-fork)
+    const command = forkConfig
+        ? [
+              "anvil",
+              "--chain-id",
+              "31337",
+              "--block-time",
+              blockTime.toString(),
+              "--fork-url",
+              forkConfig.url,
+              ...(forkConfig.blockNumber !== undefined
+                  ? ["--fork-block-number", forkConfig.blockNumber.toString()]
+                  : []),
+          ]
+        : ["devnet", "--block-time", blockTime.toString()];
+
+    // in case of forked network service is ready only when it responds with target block number
+    const test = forkConfig?.blockNumber
+        ? ["CMD", "eth_isready", forkConfig.blockNumber?.toString()]
+        : ["CMD", "eth_isready"];
 
     return {
         image: `cartesi/sdk:${imageTag}`,
-        command: ["devnet", "--block-time", blockTime.toString()],
+        command,
         healthcheck: {
             ...DEFAULT_HEALTHCHECK,
-            test: ["CMD", "eth_isready"],
+            test,
         },
         environment: {
             ANVIL_IP_ADDR: "0.0.0.0",

apps/cli/src/compose/node.ts

@@ -8,11 +8,12 @@ import type { ComposeFile, Config, Service } from "../types/compose.js";
 import { DEFAULT_HEALTHCHECK } from "./common.js";
 
 type ServiceOptions = {
+    cpus?: number;
     databaseHost?: string;
     databasePort?: number;
     databasePassword: string;
     defaultBlock?: "latest" | "safe" | "pending" | "finalized";
-    cpus?: number;
+    forkChainId?: number;
     logLevel?: "info" | "debug" | "warn" | "error" | "fatal";
     memory?: number;
     mnemonic?: string;
@@ -30,6 +31,10 @@ const service = (options: ServiceOptions): Service => {
     const mnemonic =
         options.mnemonic ??
         "test test test test test test test test test test test junk";
+    const chainId = (options.forkChainId ??
+        31337) as keyof typeof daveAppFactoryAddress;
+
+    const chainDaveAppFactoryAddress = daveAppFactoryAddress[chainId];
 
     return {
         image: `cartesi/rollups-runtime:${imageTag}`,
@@ -63,7 +68,8 @@ const service = (options: ServiceOptions): Service => {
             CARTESI_BLOCKCHAIN_HTTP_ENDPOINT: "http://anvil:8545",
             CARTESI_BLOCKCHAIN_ID: anvil.id.toString(),
             CARTESI_BLOCKCHAIN_WS_ENDPOINT: "ws://anvil:8545",
-            CARTESI_CONTRACTS_DAVE_APP_FACTORY_ADDRESS: daveAppFactoryAddress,
+            CARTESI_CONTRACTS_DAVE_APP_FACTORY_ADDRESS:
+                chainDaveAppFactoryAddress,
             CARTESI_CONTRACTS_INPUT_BOX_ADDRESS: inputBoxAddress,
             CARTESI_CONTRACTS_SELF_HOSTED_APPLICATION_FACTORY_ADDRESS:
                 selfHostedApplicationFactoryAddress,

apps/cli/src/exec/rollups.ts

@@ -6,8 +6,10 @@ import {
     type Address,
     type Hash,
     type Hex,
+    createPublicClient,
     getAddress,
     hexToNumber,
+    http,
 } from "viem";
 import { stringify } from "yaml";
 import {
@@ -16,6 +18,7 @@ import {
     getProjectName,
     getServiceHealth,
 } from "../base.js";
+import type { ForkConfig } from "../commands/run.js";
 import anvil from "../compose/anvil.js";
 import { concat } from "../compose/builder.js";
 import bundler from "../compose/bundler.js";
@@ -100,6 +103,25 @@ export const getApplicationAddress = async (options: {
     return deployment?.address;
 };
 
+/**
+ * Get anvil node configuration and query the chainId of its fork
+ * @param options projectName
+ * @returns chainId of anvil fork
+ */
+export const getForkChainId = async (options: {
+    projectName?: string;
+}): Promise<number | undefined> => {
+    const projectName = getProjectName(options ?? {});
+    const nodeInfo = await getAnvilNodeInfo({ projectName });
+    const forkUrl = nodeInfo?.forkConfig?.forkUrl;
+    if (forkUrl) {
+        // if anvil is configured with a forkUrl, connect to it and query the chainId
+        const client = createPublicClient({ transport: http(forkUrl) });
+        return client.getChainId();
+    }
+    return undefined;
+};
+
 type Service = {
     name: string; // name of the service
     healthySemaphore?: string; // service to check if the service is healthy
@@ -216,6 +238,7 @@ export const startEnvironment = async (options: {
     cpus?: number;
     defaultBlock: "latest" | "safe" | "pending" | "finalized";
     dryRun: boolean;
+    forkConfig?: ForkConfig;
     memory?: number;
     port: number;
     projectName: string;
@@ -228,6 +251,7 @@ export const startEnvironment = async (options: {
         cpus,
         defaultBlock,
         dryRun,
+        forkConfig,
         memory,
         port,
         projectName,
@@ -246,12 +270,17 @@ export const startEnvironment = async (options: {
     };
 
     const files = [
-        anvil({ blockTime, imageTag: runtimeVersion }),
+        anvil({
+            blockTime,
+            forkConfig,
+            imageTag: runtimeVersion,
+        }),
         database({ imageTag: runtimeVersion, password: "password" }),
         node({
             cpus,
             databasePassword: "password",
             defaultBlock,
+            forkChainId: forkConfig?.chainId,
             imageTag: runtimeVersion,
             logLevel: verbose ? "debug" : "info",
             memory,
@@ -546,3 +575,23 @@ export const getProjectPort = async (options: { projectName: string }) => {
     ]);
     return stdout;
 };
+
+/**
+ * Get anvil node info returned by RPC method anvil_nodeInfo
+ * @param options
+ * @returns anvil node info
+ */
+export const getAnvilNodeInfo = async (options: { projectName: string }) => {
+    const { projectName } = options;
+    const { stdout } = await execa("docker", [
+        "compose",
+        "--project-name",
+        projectName,
+        "exec",
+        "anvil",
+        "cast",
+        "rpc",
+        "anvil_nodeInfo",
+    ]);
+    return JSON.parse(stdout);
+};