Add anvil fork mode to cartesi run by tuler · Pull Request #421 · cartesi/cli

tuler · 2026-02-11T20:21:20Z

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 · 2026-02-11T20:21:27Z

🦋 Changeset detected

Latest commit: 35b34cc

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 · 2026-02-11T20:24:56Z

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 · 2026-02-12T05:09:36Z

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

Package	Supply Chain Security	Quality	Maintenance
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	⁺²²	⁺²⁸	⁺⁹

View full report

tuler · 2026-02-12T05:38:05Z

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 · 2026-02-17T11:00:18Z

...
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.

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>

tuler · 2026-02-18T21:16:52Z

I think it's safer to remove the default fork url and require the user to provide one.

Removed DEFAULT_FORK_URL constant (line 31)
Removed the --fork option — the standalone flag that enabled fork mode with a default URL
Updated configureFork — removed the fork parameter; fork mode is now triggered only when --fork-url is provided (no default fallback)

Users who want to fork must now explicitly pass --fork-url <url>.

brunomenezes · 2026-02-19T10:02:53Z

I think it's safer to remove the default fork url and require the user to provide one.

Removed DEFAULT_FORK_URL constant (line 31)

Removed the --fork option — the standalone flag that enabled fork mode with a default URL

Updated configureFork — removed the fork parameter; fork mode is now triggered only when --fork-url is provided (no default fallback)

Users who want to fork must now explicitly pass --fork-url <url>.

What was the motivation was because of rate limiting, because it goes straight to Ethereum-mainnet or a combination of both? Just picking your brain here. nonetheless I think that is better as a more deliberate decision.

brunomenezes · 2026-02-19T10:18:01Z

apps/cli/src/base.ts

+        daveAppFactoryAddress[
+            forkChainId as keyof typeof daveAppFactoryAddress
+        ];
+    if (!chainDaveAppFactoryAddress) {


@tuler, should you do this kind of validation also on compose/anvil.ts and compose/node.ts? As this getAddressBook would only run when a address-book command is issued to the CLI.

The validation is about whether the chain ID of the fork is supported or not, right?

Good catch, added check as well to node.ts

tuler · 2026-02-19T14:56:35Z

What was the motivation was because of rate limiting

It was not working properly, the node was being disconnected often and dying.

add supported fork to run

Improved behavior of address-book. Now it prints a different set of contracts weather it’s a running fork or a running devnet. Test tokens are only present at devnet. ERC-4377 are currently only present at fork (not devnet).

tuler · 2026-02-20T03:09:14Z

Improved behavior of address-book.
Now it prints a different set of contracts weather it’s a running fork or a running devnet.

Test tokens are only present at devnet.
ERC-4377 are currently only present at fork (not devnet).

endersonmaia · 2026-02-20T16:54:24Z

When using an invalid URL it fails, I suggest catching the error and printing a nice message

cartesi run --dry-run --fork-url=https://url.com
WARNING: default block is set to 'latest', production configuration will likely use 'finalized'
i2 [HttpRequestError]: HTTP request failed.

URL: https://url.com/
Request body: {"method":"eth_blockNumber"}

Details: Unexpected token '<', "<!DOCTYPE "... is not valid JSON
Version: viem@2.46.1
    at Object.request (file:///home/endersonmaia/Work/cartesi/cli/apps/cli/dist/index.js:288:28678)
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
    ... 3 lines matching cause stack trace ...
    at async X (file:///home/endersonmaia/Work/cartesi/cli/apps/cli/dist/index.js:288:3946) {
  details: `Unexpected token '<', "<!DOCTYPE "... is not valid JSON`,
  docsPath: undefined,
  metaMessages: [
    'URL: https://url.com/',
    'Request body: {"method":"eth_blockNumber"}'
  ],
  shortMessage: 'HTTP request failed.',
  version: '2.46.1',
  body: { method: 'eth_blockNumber', params: undefined },
  headers: undefined,
  status: undefined,
  url: 'https://url.com/',
  [cause]: SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON
      at JSON.parse (<anonymous>)
      at Object.request (file:///home/endersonmaia/Work/cartesi/cli/apps/cli/dist/index.js:288:28441)
      at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
      at async T (file:///home/endersonmaia/Work/cartesi/cli/apps/cli/dist/index.js:291:17428)
      at async request (file:///home/endersonmaia/Work/cartesi/cli/apps/cli/dist/index.js:291:17476)
      at async M3.delay.count (file:///home/endersonmaia/Work/cartesi/cli/apps/cli/dist/index.js:288:25384)
      at async X (file:///home/endersonmaia/Work/cartesi/cli/apps/cli/dist/index.js:288:3946)
}

endersonmaia · 2026-02-20T16:54:36Z

I'm not sure how careful we should be with this kind or URL being accepted via CLI argument, since they may probably have some secret/token init that should be carefully handled. If we do not provide getting this from ENV we should at least show a disclaimer about rotating/revoking the token after using it.

tuler · 2026-02-20T17:06:54Z

I'm not sure how careful we should be with this kind or URL being accepted via CLI argument, since they may probably have some secret/token init that should be carefully handled. If we do not provide getting this from ENV we should at least show a disclaimer about rotating/revoking the token after using it.

The CLI is for dev environment, to run on the developer machine. I don't see a big risk here.

tuler changed the title ~~feat(cli): add anvil fork mode to cartesi run~~ Add anvil fork mode to cartesi run Feb 11, 2026

tuler changed the base branch from main to prerelease/v2-alpha February 11, 2026 20:22

tuler force-pushed the feature/anvil-fork branch from 39e4df4 to 2c2d626 Compare February 11, 2026 20:23

tuler requested a review from endersonmaia February 11, 2026 21:35

tuler force-pushed the feature/anvil-fork branch from a7da1d3 to 71d8c01 Compare February 12, 2026 05:08

tuler force-pushed the feature/anvil-fork branch from 71d8c01 to 4982e0f Compare February 12, 2026 05:31

tuler changed the base branch from prerelease/v2-alpha to feature/devnet-live-networks February 12, 2026 16:40

tuler changed the base branch from feature/devnet-live-networks to feature/sdk-bump-devnet February 12, 2026 16:44

tuler force-pushed the feature/sdk-bump-devnet branch from 70df749 to feb831d Compare February 12, 2026 18:32

tuler force-pushed the feature/anvil-fork branch from f39a101 to e580d99 Compare February 12, 2026 18:33

Base automatically changed from feature/sdk-bump-devnet to prerelease/v2-alpha February 16, 2026 16:57

tuler force-pushed the feature/anvil-fork branch 2 times, most recently from 8224b62 to d559b36 Compare February 16, 2026 17:13

tuler marked this pull request as ready for review February 16, 2026 18:00

tuler requested a review from brunomenezes February 16, 2026 18:00

brunomenezes approved these changes Feb 17, 2026

View reviewed changes

tuler and others added 2 commits February 18, 2026 16:11

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

dc9039c

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>

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

8f41216

tuler force-pushed the feature/anvil-fork branch from d559b36 to 8f41216 Compare February 18, 2026 21:15

brunomenezes reviewed Feb 19, 2026

View reviewed changes

tuler added 2 commits February 19, 2026 22:07

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

357516e

add supported fork to run

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

35b34cc

Improved behavior of address-book. Now it prints a different set of contracts weather it’s a running fork or a running devnet. Test tokens are only present at devnet. ERC-4377 are currently only present at fork (not devnet).

Conversation

tuler commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

changeset-bot bot commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

socket-security bot commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tuler commented Feb 12, 2026

Uh oh!

brunomenezes commented Feb 17, 2026

Uh oh!

brunomenezes left a comment

Choose a reason for hiding this comment

Uh oh!

tuler commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

brunomenezes commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

brunomenezes Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tuler Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

tuler commented Feb 19, 2026

Uh oh!

tuler commented Feb 20, 2026

Uh oh!

endersonmaia commented Feb 20, 2026

Uh oh!

endersonmaia commented Feb 20, 2026

Uh oh!

tuler commented Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

tuler commented Feb 11, 2026 •

edited

Loading

changeset-bot bot commented Feb 11, 2026 •

edited

Loading

github-actions bot commented Feb 11, 2026 •

edited

Loading

socket-security bot commented Feb 12, 2026 •

edited

Loading

tuler commented Feb 18, 2026 •

edited

Loading

brunomenezes commented Feb 19, 2026 •

edited

Loading

brunomenezes Feb 19, 2026 •

edited

Loading