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 and test suite expansions.

 🚀 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.
Config System & Validation
- Introduced withdrawalConfig parsing and validation (including address and numeric validation).
- Added InvalidAddressValueError and improved error context for numeric validation.
- 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.
- 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:

Unsupported environment variables are now explicitly filtered out by the new allow-list.
The machine hash source has shifted to hash_tree.sht. (Don't forget to execute cartesi build on existing dapps)
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.

## 🧪 Testing & Validation

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: afe3049

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.71% (🎯 0%)	4581 / 4641
🔵	Statements	98.71%	4581 / 4641
🔵	Functions	95.33%	102 / 107
🔵	Branches	0%	0 / 0

📁 File Coverage (15 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`	🟢 97.01%	🟢 97.01%	🟢 100%	🔴 0%	105-108
`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%	-
`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

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.

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: changes to support node alpha.12#489

feat: changes to support node alpha.12#489
brunomenezes wants to merge 16 commits into
prerelease/v2-alphafrom
feat/cli-update-commands-deps

brunomenezes commented Jun 15, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jun 15, 2026 •

edited

Loading

Uh oh!

socket-security Bot commented Jun 15, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 18, 2026 •

edited

Loading

Uh oh!

brunomenezes commented Jun 19, 2026

Uh oh!

endersonmaia left a comment

Uh oh!

Uh oh!

brunomenezes commented Jun 22, 2026

Uh oh!

brunomenezes commented Jun 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

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)

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

brunomenezes commented Jun 15, 2026 •

edited

Loading

 🚀 Key Changes 

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