Add anvil fork mode to cartesi run

[tuler]

Summary

• Add --fork flag to cartesi run to fork from a live chain instead of using pre-baked devnet state
• Add --fork-url <url> option to specify a custom RPC endpoint (implies --fork, defaults to https://ethereum.reth.rs/rpc)
• Add --fork-block-number <number> option to pin the fork to a specific block

In fork mode, Anvil runs directly with --fork-url and --chain-id 31337 instead of the devnet wrapper that loads anvil_state.json. All other services (node, explorer, bundler, paymaster) continue working unchanged since the chain ID remains 31337.

Test plan

• cartesi run --dry-run — verify normal devnet mode is unchanged (no regression)
• cartesi run --fork --dry-run — verify anvil command uses fork with default URL
• cartesi run --fork-url https://custom-rpc.example.com --dry-run — verify fork with custom URL (implies --fork)
• cartesi run --fork --fork-block-number 12345 --dry-run — verify fork at specific block number
• cartesi run --fork — verify full environment starts and is healthy against a forked chain

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: d559b36

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cartesi/cli	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🟢	Lines	92.96% (🎯 0%)	726 / 781
🔵	Statements	92.96%	726 / 781
🔵	Functions	92.54%	62 / 67
🔵	Branches	0%	0 / 0

📁 File Coverage (11 files)

File	Lines	Statements	Functions	Branches	Uncovered Lines
apps/cli/src/builder/directory.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/builder/docker.ts	🟢 88.68%	🟢 88.68%	🟡 75%	🔴 0%	83-85, 139-147
apps/cli/src/builder/empty.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/builder/none.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/builder/tar.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/config.ts	🟢 92.63%	🟢 92.63%	🟢 94.12%	🔴 0%	65-66, 217, 226, 235, 255, ...
apps/cli/src/exec/cartesi-machine.ts	🟡 75%	🟡 75%	🟡 66.67%	🔴 0%	10-12, 28-30
apps/cli/src/exec/genext2fs.ts	🟢 96.92%	🟢 96.92%	🟢 100%	🔴 0%	87-88
apps/cli/src/exec/index.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/exec/mksquashfs.ts	🟢 91.23%	🟢 91.23%	🟢 100%	🔴 0%	68-72
apps/cli/src/exec/util.ts	🟢 94.44%	🟢 94.44%	🟢 100%	🔴 0%	47-48

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​sunodo/​wagmi-plugin-hardhat-deploy@​0.4.0
	tmp@​0.2.5
	smol-toml@​1.6.0
	yaml@​2.8.2
	@​cartesi/​devnet@​2.0.0-alpha.9 ⏵ 2.0.0-alpha.10	+22		+28	+9

View full report

[tuler]

Depending on the chosen fork-url the deployed contracts can have different addresses.
ps: in fact only 1 contract from Cartesi framework currently have this "problem": DaveAppFactory.

So the CLI needs to use the correct address during application deployment, and also report the correct address in the address-book command.

So it should know not only the addresses on local deployment, but also the addresses on all supported live networks, which can potentially be forked.

So I had to modify the devnet package to also package the deployments from all networks, which is maintained at cannon registry.

So I changed to devnet packaging to call cannon inspect, and export the addresses from all networks. And changed the artifact format to follow the format supported by the wagmi-hardhat-plugin, because then it would be much easier to use.

When merged the devnet package will need to be released first, then SDK, then CLI.

[brunomenezes]

...
So I changed to devnet packaging to call cannon inspect, and export the addresses from all networks. And changed the artifact format to follow the format supported by the wagmi-hardhat-plugin, because then it would be much easier to use.

When merged the devnet package will need to be released first, then SDK, then CLI.

So, are these devnet changes in some other PR? Also, I tried building the CLI from this branch, but it fails on the devnet package. Building it in isolation, here are the logs I received. Is there a specific version that is expected? Currently, my system is using 1.5.0-stable.

@cartesi/devnet:build:
@cartesi/devnet:build: IPFS Availability Score(# of nodes):  Run IPFS Locally to get this score
@cartesi/devnet:build:
✖ Failed to parse anvil version. Is anvil installed?
@cartesi/devnet:build: ✔ Download dependencies
@cartesi/devnet:build: ✔ Anvil started (PID: 98596)
@cartesi/devnet:build: ✔ Contracts deployed
@cartesi/devnet:build: ✔ Local deployments written to deployments/anvil.json
@cartesi/devnet:build: ✔ Export cannon packages
@cartesi/devnet:build: ✔ Anvil stopped -> anvil_state.json
@cartesi/devnet:build: error: script "build:dump" exited with code 1
@cartesi/devnet:build: ERROR: "build:dump" exited with 1.
@cartesi/devnet:build: error: script "build" exited with code 1
@cartesi/devnet:build: ERROR: command finished with error: command (/Users/--x--/cartesi/public/cli/packages/devnet) /opt/homebrew/bin/bun run build exited (1)
@cartesi/devnet#build: command (/Users/--x--/cartesi/public/cli/packages/devnet) /opt/homebrew/bin/bun run build exited (1)

 Tasks:    0 successful, 1 total                     └───────────────────┘
Cached:    0 cached, 1 total
  Time:    7.866s
Failed:    @cartesi/devnet#build

[brunomenezes]

I made the dry-runs suggested and also create/build/run an dapp. No hiccups.