feat: changes to support node alpha.12 by brunomenezes · Pull Request #489 · cartesi/cli

brunomenezes · 2026-06-15T16:53:58Z

📝 Summary

This PR improves the CLI run flow, node compose generation, and configuration parsing, alongside dependency upgrades, test suite expansions, and comprehensive validation for fork mode configurations.

🚀 Key Changes

CLI & run Command Enhancements
- Added a flag to list supported environment variables per service in JSON format.
- Added support for a claim staging period in the run/deploy flow.
- Added support for loading and passing withdrawal configurations via TOML files.
- Enabled passing direct configuration file paths to the run command.
- Added tty Docker option support in the fallback execution path (used by the shell command).
- Fixed a bug by removing the --no-rollup flag passed to the cartesi-machine binary, ensuring compatibility with newer versions.
- Integrated fork configuration assertions in run.ts before initiating a run session in fork mode.
Config System & Validation
- Verification of Required Settings on Fork Mode: Created a new validation module validations.ts with assertForkConfig to execute pre-flight assertions. This ensures required contracts are deployed on the target chain/block and validates that on-chain calls like getInputBox or getDeploymentBlockNumber succeed.
- Replaced getForkChainId with a more complete getForkConfig function inside rollups.ts to query the current Anvil service details and return a complete ForkConfig (containing chainId, url, and blockNumber).
- Integrated validations into base.ts to verify the deployment and contract state within getAddressBook().
- Introduced withdrawalConfig parsing and validation (including address and numeric validation).
- Added InvalidAddressValueError, ForkChainValidationError, and UnsupportedForkChainError to improve error context.
- Updated machine hash extraction to read from hash_tree.sht (root hash offset).
Rollups-Node Env Management & Proxy Updates
- Implemented a strict allow-list for CARTESI-prefixed environment variables. Host-provided values take precedence over defaults set in the code.
- Removed CARTESI_BLOCKCHAIN_WS_ENDPOINT from default node compose environments.
- Added CORS middleware (wildcard origins, methods, and headers) definition to the node proxy's inspect and RPC routers.
Dependencies & SDK
- Bumped default SDK to 0.12.0-alpha.41.
- Bumped the rollups-explorer image integration version from 2.0.0-alpha.2 to 2.0.0-alpha.3 in rollups.ts.
- Updated devnet dependencies and removed unused rollups dependencies.
- Updated address book entries for renamed token constants and integrated TestUsdWithdrawalOutputBuilder.

⚠️ Scope & Impact (Note for Reviewers)

Migration risk is low, but note the following behavioral changes:

Environment Filtering: Unsupported environment variables are now explicitly filtered out by the new allow-list.
Machine Hash Source: The machine hash source has shifted to hash_tree.sht. (Don't forget to execute cartesi build on existing dapps)
Flag Removal: The --no-rollup flag has been removed as it is not available as an option in cartesi-machine versions 0.20 and previous 0.19. This ensures the CLI works correctly with newer CM versions.
Fork Mode Safety: Fork-mode runs will now fail early if pre-flight assertions on contract bytecode or vital on-chain calls (like getInputBox) fail.

🧪 Testing & Validation

Unit Testing: Added comprehensive test cases for validations.ts that dynamically derive contract baseline call indices (avoiding fragile, hardcoded call-count assumptions) and explicitly assert contract checks.
Expanded unit tests covering node compose allow-lists, default build behaviors, and withdrawal config parsing.

changeset-bot · 2026-06-15T16:54:04Z

🦋 Changeset detected

Latest commit: a9dc071

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

socket-security · 2026-06-15T16:54:45Z

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

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@cartesi/devnet@2.0.0-alpha.11 ⏵ 2.0.0-alpha.14

View full report

…the IDE.

…si/rollups 2.2.0.

…devnet-contracts [address-book] * Replaced Fungible and Non Fungible token addresses to use the new ones exported by Devnet package. * Refactor deposit ERC-20 and ERC-721 to the new addresses as defaults.

…me and bump required-version for cartesi-machine tests.

github-actions · 2026-06-18T19:47:09Z

Coverage Report

Status	Category	Percentage	Covered / Total
🟢	Lines	98.79% (🎯 0%)	4819 / 4878
🔵	Statements	98.79%	4819 / 4878
🔵	Functions	96.21%	127 / 132
🔵	Branches	0%	0 / 0

📁 File Coverage (19 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/compose/builder.ts`	🟢 99.79%	🟢 99.79%	🟢 100%	🔴 0%	228
`apps/cli/src/compose/common.ts`	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
`apps/cli/src/compose/node.ts`	🟢 99.24%	🟢 99.24%	🟢 100%	🔴 0%	106
`apps/cli/src/config.ts`	🟢 93.69%	🟢 93.69%	🟢 94.87%	🔴 0%	75-76, 240, 249, 258, 307, ...
`apps/cli/src/contracts.ts`	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
`...rc/errors/ForkChainValidationError.ts`	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
`...c/errors/UnsupportedForkChainError.ts`	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
`...c/exec/cartesi-machine-stored-hash.ts`	🟢 92.86%	🟢 92.86%	🟢 100%	🔴 0%	36-37
`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.74%	🟢 94.74%	🟢 100%	🔴 0%	49-50
`apps/cli/src/validations.ts`	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-

brunomenezes · 2026-06-19T14:39:56Z

I am making that ready to review, but a release will also need to have an explorer ready

The PR is here: cartesi/rollups-explorer#464.

Once we have a tag and release for the explorer, I will just update the image tag for the service.

endersonmaia

I see there's --prt that enables prt mode and default is Authority, what about Quorum, will it be possible to use Quorum in dev mode?

brunomenezes · 2026-06-22T06:27:11Z

I see there's --prt that enables prt mode and default is Authority, what about Quorum, will it be possible to use Quorum in dev mode?

Not for this release.

brunomenezes · 2026-06-22T08:33:45Z

I did one extra commit to include a fix to the following bug

Fix: Non existing cartesi-machine option #476

* Add parse function related to the configuration * Add a few type check parsers for address and number.

…when using RUN command. - Add --claim-staging-period flag. default to 0 - Add --config flag. default to cartesi.toml

… property. - The application status and enabled has separate meanings. It can be in a FAILED state but still enabled.

… allow external access. - Allow specific methods, headers with max-age control of 24 hours and a vary-header to avoid intermittent CORS bug when tightening the domain list.

…CHAIN_WS_ENDPOINT.

- Fix "unable to open a TTY: No such device or address" error returned by cartesi-machine.

…ESI and pass it down to rollups-node. * There is a list of allowed environment variable configured for rollups-node. Only these are picked on from the big bag of possible variables.

…pported environment variables by service.

…he cartesi-machine.

* Solve lint blocker problems.

… mode.

tuler · 2026-06-24T06:21:13Z

+ * A number of environment variables are rule out to avoid confusion e.g. CORS, FEATURE Enablement, etc.
+ */
+export const nodeAllowedEnvironmentVariables = [
+    "CARTESI_AUTH_MNEMONIC",


is it really worth the burden of maintaining this list over time?

I did curate that because there are a dozen more; I just did not add them all because, looking at the node source code, it looks like they set reasonable defaults. I am not sure about going free and just plugging any CARTESI_* in the compose environment section of the rollups-node service declaration.

I think only advanced users will set CARTESI_ variables. And for those it's a minor issue if they break the behavior of the dev execution because they set some variable to some value that changes the behavior in an unpredictable way to the CLI.

IMO it's a big downside for maintenance to keep this list. The rollups node may change variables, as it happened several times in the past, and the CLI will always need to keep up.

I'd just iterate over all variables, filter all prefixed with CARTESI_ and forward all. It's simple, it works, and low-maintenance.

tuler · 2026-06-24T06:29:48Z

 export const getMachineHash = (): Hash | undefined => {
    // read hash of the cartesi machine snapshot, if one exists
-    const hashPath = getContextPath("image", "hash");
+    const hashPath = getContextPath("image", "hash_tree.sht");


I wouldn't read this file. Instead I'd rather call the cartesi-machine-stored-hash utility

Push the change here: 053f405

The change in the YAML was small, just the QEMU + Docker Buildx setup. ~~But for some reason, Biome was formatting the whole document.~~

* Add integration test cases. * Add test utility to create and build a cartesi-application on demand using CLI binary. A temporary folder is generated and a cleanup is applied after-all tests had finished

brunomenezes added this to Rollups SDK Jun 15, 2026

brunomenezes added cli v2 labels Jun 15, 2026

github-project-automation Bot moved this to Todo in Rollups SDK Jun 15, 2026

brunomenezes moved this from Todo to In progress in Rollups SDK Jun 15, 2026

brunomenezes force-pushed the chore/sdk-machine-emulator-bump branch from 0499c68 to c063bb0 Compare June 18, 2026 10:16

Base automatically changed from chore/sdk-machine-emulator-bump to prerelease/v2-alpha June 18, 2026 14:09

brunomenezes added 5 commits June 18, 2026 20:42

chore(cli): Add tsconfig.json to help TS recognize node/bun types in …

e27c1ab

…the IDE.

chore(cli): Bump @cartesi/devnet to alpha.14 and remove unused @carte…

2c044a8

…si/rollups 2.2.0.

feat(cli): Add the new TestUsdWithdrawalOutputBuilder address to the …

9994885

…devnet-contracts [address-book] * Replaced Fungible and Non Fungible token addresses to use the new ones exported by Devnet package. * Refactor deposit ERC-20 and ERC-721 to the new addresses as defaults.

refactor(cli): Update flash-drive option from filename to data_filena…

1c9388f

…me and bump required-version for cartesi-machine tests.

refactor(cli): Recover the machine-hash from the new hash_tree.sht file.

8af2c60

brunomenezes force-pushed the feat/cli-update-commands-deps branch from 2969b12 to 6cb5268 Compare June 18, 2026 19:46

brunomenezes changed the title ~~Feat/cli update commands deps~~ feat: change to support node alpha.12 Jun 18, 2026

This was linked to issues Jun 18, 2026

CLI: Bump SDK version v0.12.0-alpha.40 [next] #473

Open

CLI: Bump devnet version 2.0.0-alpha.14 [next] #474

Open

CLI: Update commands that user cartesi-rollups-cli #484

Open

brunomenezes force-pushed the feat/cli-update-commands-deps branch from f494f64 to 3ac391f Compare June 19, 2026 14:18

brunomenezes changed the title ~~feat: change to support node alpha.12~~ feat: changes to support node alpha.12 Jun 19, 2026

brunomenezes linked an issue Jun 19, 2026 that may be closed by this pull request

Forward host environment variables to the rollups node container #488

Open

5 tasks

brunomenezes requested review from endersonmaia, tuler and vfusco June 19, 2026 14:38

brunomenezes marked this pull request as ready for review June 19, 2026 14:38

endersonmaia requested changes Jun 19, 2026

View reviewed changes

Comment thread apps/cli/src/commands/run.ts

brunomenezes linked an issue Jun 22, 2026 that may be closed by this pull request

Fix: Non existing cartesi-machine option #476

Open

brunomenezes force-pushed the feat/cli-update-commands-deps branch 3 times, most recently from c3d1b2a to 791b9c7 Compare June 22, 2026 13:46

brunomenezes added 11 commits June 22, 2026 14:50

feat(cli): Add support to withdrawal-config through a toml file.

d5c0edc

* Add parse function related to the configuration * Add a few type check parsers for address and number.

feat(cli): Add support to claim-staging-period and withdrawal-config …

7c19db6

…when using RUN command. - Add --claim-staging-period flag. default to 0 - Add --config flag. default to cartesi.toml

feat(cli): Refactor state for status and make room to the new enabled…

80ac676

… property. - The application status and enabled has separate meanings. It can be in a FAILED state but still enabled.

feat(cli): Add CORS configuration to the node proxy docker compose to…

f01ff31

… allow external access. - Allow specific methods, headers with max-age control of 24 hours and a vary-header to avoid intermittent CORS bug when tightening the domain list.

feat(cli): Bump default sdk version to 0.12.0-alpha.41

dcf79de

refactor(cli): Remove node compose environment variable CARTESI_BLOCK…

4c193a2

…CHAIN_WS_ENDPOINT.

refactor(cli): Add tty docker-option when using shell command.

612b1b2

- Fix "unable to open a TTY: No such device or address" error returned by cartesi-machine.

feat(cli): Add support to load environment variables prefix with CART…

40e29d6

…ESI and pass it down to rollups-node. * There is a list of allowed environment variable configured for rollups-node. Only these are picked on from the big bag of possible variables.

feat(cli): Add new flag to RUN command to return information about su…

02bbb94

…pported environment variables by service.

fix(cli): Remove non-existing flag --no-rollup that is pass down to t…

dadcc2a

…he cartesi-machine.

chore(devnet): Use expected types.

afe3049

* Solve lint blocker problems.

brunomenezes force-pushed the feat/cli-update-commands-deps branch from 791b9c7 to afe3049 Compare June 22, 2026 13:51

brunomenezes requested a review from endersonmaia June 22, 2026 13:53

brunomenezes added 2 commits June 23, 2026 10:50

chore(cli): Bump rollups-explorer to version 2.0.0-alpha.3

8a081ba

refactor(cli):Update verification of required settings to run on fork…

ffb74ec

… mode.

brunomenezes moved this from In progress to Waiting review in Rollups SDK Jun 23, 2026

tuler reviewed Jun 24, 2026

View reviewed changes

brunomenezes force-pushed the feat/cli-update-commands-deps branch from d709be7 to 053f405 Compare June 24, 2026 15:46

refactor(cli): Use cartesi-machine-stored-hash to read the hash.

a9dc071

* Add integration test cases. * Add test utility to create and build a cartesi-application on demand using CLI binary. A temporary folder is generated and a cleanup is applied after-all tests had finished

brunomenezes force-pushed the feat/cli-update-commands-deps branch from 053f405 to a9dc071 Compare June 24, 2026 16:42

tuler approved these changes Jun 24, 2026

View reviewed changes

brunomenezes merged commit 281ff21 into prerelease/v2-alpha Jun 24, 2026
5 checks passed

brunomenezes deleted the feat/cli-update-commands-deps branch June 24, 2026 16:48

github-project-automation Bot moved this from Waiting review to Done in Rollups SDK Jun 24, 2026

Uh oh!

Conversation

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

Uh oh!

📝 Summary

🚀 Key Changes

⚠️ Scope & Impact (Note for Reviewers)

🧪 Testing & Validation

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

socket-security Bot commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

brunomenezes commented Jun 19, 2026

Uh oh!

endersonmaia left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

brunomenezes commented Jun 22, 2026

Uh oh!

brunomenezes commented Jun 22, 2026

Uh oh!

tuler Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

brunomenezes Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

tuler Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

tuler Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

brunomenezes Jun 24, 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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

brunomenezes commented Jun 15, 2026 •

edited

Loading

changeset-bot Bot commented Jun 15, 2026 •

edited

Loading

socket-security Bot commented Jun 15, 2026 •

edited

Loading

github-actions Bot commented Jun 18, 2026 •

edited

Loading

brunomenezes Jun 24, 2026 •

edited

Loading