docs(v2): Rollups 2.0 migration, community tools, and self-hosted updates by riseandshaheen · Pull Request #353 · cartesi/docs

riseandshaheen · 2026-08-19T10:09:30Z

Summary

v2 Alpha visibility: Make v2.0 as recommended version and visible in the versions list.
Migration Guide: Rewrite the v1.5 → v2.0 migration guide for backend, frontend, machine image, outputs, JSON-RPC, inspect, and TypeScript clients.
API Reference: Align contracts API with rollups-contracts v3.0.0-alpha.9
Community tools: keep Deroll, Python-Cartesi, and Cartesapp; add libcma; drop NoNodo, Cartesify, Tikua, Rollmelette, Crabrolls, Python-Wallet, TypeScript-SQLite, and CartDevKit.
Self-hosted Deployment: Document self-hosted Mugen compose as one process per container, HTTP polling only, and dedicated Postgres users for anything beyond the sample testnet stack.
Hide the integration guides page from the v2.0 Resources sidebar (page kept).
Point Creating an application at the remaining frameworks and remove the NoNodo note from Running an application.
Add a v2.0 review comment on documented pages so Docusaurus lastUpdated timestamps refresh on merge.

github-actions · 2026-08-19T10:13:11Z

📖 Docs preview is ready

Preview: https://cartesi.github.io/docs/pr-preview/pr-353/

Built from commit 281f88a and published to GitHub Pages. Updates on every push; removed automatically when this PR is closed.

…ted guides Align v2.0 docs with JSON-RPC, unified outputs, and the current community stack; refresh lastUpdated markers on reviewed pages.

Update Application, portals, consensus, and withdrawal docs for input-box DA, claim staging, MachineValidityProof, Erc portal renames, deposit refunds, and GitHub release artifacts; point contract links at alpha.9. Co-authored-by: Cursor <cursoragent@cursor.com>

Align Authority-first EW deploy, recovery caveats, and compose with the validated Sepolia flow, and drop alpha-specific intro noise and a stale migration note. Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

jplgarcia · 2026-08-25T14:38:45Z

-  $SALT \
-  --rpc-url "$RPC_URL"
-  ```
+1. Relay the application address using `DAppAddressRelay`.


I think this was also true for other assets, right? ERC1155 and ERC721

jplgarcia · 2026-08-25T14:47:39Z


-:::warning Production Warning
-**This self-hosted approach should NOT be used in _production_.**
+This guide explains how to run a Cartesi Rollups node locally on your machine for development and testing on **testnet**.


I'm thinking if we should have an alternate section on how to deploy an application with step by step

calculateAddresses

newApplication

deployContracts
as alternatives

Do you think a section should be added here somewhere?

Restructured the standard deployment a little bit to add granular cast commands. It gets a little lengthier tho. Here's how it looks:

Setting up the local node - compose, build, start

Deploying the application

One-shot CLI as the default,

CLI two-step (alternative, in case above one-shot fails)

Direct factory calls - cast recipes

Authority and Application separately

calculateAuthorityAddress, newAuthority

calculateApplicationAddress, newApplication

Authority and Application together

calculateAddresses, deployContracts

Register a cast-deployed application

At some point, we should merge emergency withdrawal with the standard process and have cast commands on a separate page. That could be better.

jplgarcia · 2026-08-25T14:54:16Z

+
+### Use dedicated database roles
+
+The sample compose shares one Postgres role (`postgres`) and one database (`rollupsdb`). For any longer-lived deployment, create a dedicated database user per service, grant only the tables that service needs, and do not use the superuser in application containers. Give Postgres a named volume, and back it up. Inputs live in the InputBox on L1, so a node can be rebuilt from chain plus the **exact** snapshot that produced the registered template hash — keep that published snapshot, not only a local rebuild.


Worth adding a defense-in-depth note here: give each role a Postgres CONNECTION LIMIT (and run the public JSON-RPC/inspect API under a read-only role with a low limit) so external read traffic can't exhaust max_connections and starve the pipeline services. As a redundant client-side bound you can also cap the pool in the DSN with ?pool_max_conns=N on CARTESI_DATABASE_CONNECTION.

jplgarcia · 2026-08-25T14:57:06Z

+                    "type": "link",
+                    "label": "PRT",
+                    "href": "https://arxiv.org/abs/2212.12439"
+                }


https://cartesi.io/cartesi_whitepaper.pdf
Cartesi whitepaper could be added here too

jplgarcia · 2026-08-25T14:58:15Z

Great work!

Split node setup from deployment, document CLI and cast paths with tested Sepolia recipes, and add a dedicated cast registration section. Co-authored-by: Cursor <cursoragent@cursor.com>

Clarify v1 withdrawal wording, remove stale alpha/PR callouts, and add the Cartesi Whitepaper to Resources. Co-authored-by: Cursor <cursoragent@cursor.com>

Show 2.0 in the version dropdown, make it the default, and add alpha/unmaintained banners so readers can tell 2.0 from 1.5. Co-authored-by: Cursor <cursoragent@cursor.com>

Nonnyjoe · 2026-09-01T16:16:03Z

 title: Exception
 ---

+<!-- Reviewed for Cartesi Rollups v2.0 documentation. -->


I noticed a couple of pages have this addition.
It might need cleanup

Nonnyjoe · 2026-09-01T17:39:36Z

+| `CARTESI_AUTH_PRIVATE_KEY`         | Funded private key for the selected chain                            |
+| `CARTESI_BLOCKCHAIN_DEFAULT_BLOCK` | `latest` for testnet tip-tracking; `finalized` for reorg-safe reads  |
+
+The EVM reader polls HTTP only. Do **not** set `BLOCKCHAIN_WS_ENDPOINT` or `CARTESI_BLOCKCHAIN_WS_ENDPOINT` with alpha.12: a blank or missing WS value crashes `evm-reader`.


This line might be understood as a little contradictory to the first section of the sentence,
with alpha.12: a blank or missing WS value crashes evm-reader
My suggestion would be to take out the highlighted section.

Nonnyjoe · 2026-09-01T20:17:35Z

 - **starts** at machine memory address `c * 2^(a + b + 5)`;
 - holds up to `2^b` accounts, each occupying `2^(a + 5)` bytes.

 These same three values are returned on-chain by [`getLog2LeavesPerAccount()`](../application.md#getlog2leavesperaccount), [`getLog2MaxNumOfAccounts()`](../application.md#getlog2maxnumofaccounts), and [`getAccountsDriveStartIndex()`](../application.md#getaccountsdrivestartindex), and must match the layout the guest application actually writes.


The highlighted line, references sections of the application page that was modified (merged into one section), so all 3 should also be resolved accordingly.

lynoferraz

Minor version corrections. Also give a overall look on the addresses used

lynoferraz · 2026-09-01T14:00:19Z

 title: AuthorityFactory
 resources:
-  - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/consensus/authority/AuthorityFactory.sol
+  - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/authority/AuthorityFactory.sol


Will the alphas be the main?
In any case, I'm changing to the alpha 10 (more as my own bookmark)

Suggested change

- url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/authority/AuthorityFactory.sol

- url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.10/src/consensus/authority/AuthorityFactory.sol

lynoferraz · 2026-09-01T14:00:39Z

-  - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/consensus/authority/AuthorityFactory.sol
+  - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/authority/AuthorityFactory.sol
    title: AuthorityFactory Contract
+  - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/authority/IAuthorityFactory.sol


Suggested change

- url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/authority/IAuthorityFactory.sol

- url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.10/src/consensus/authority/IAuthorityFactory.sol

lynoferraz · 2026-09-01T19:46:31Z

 title: Authority
 resources:
-  - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/consensus/authority/Authority.sol
+  - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/authority/Authority.sol


Suggested change

- url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/authority/Authority.sol

- url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.10/src/consensus/authority/Authority.sol

lynoferraz · 2026-09-01T19:48:05Z

 title: IAuthorityFactory
 resources:
-  - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/consensus/authority/IAuthorityFactory.sol
+  - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/authority/IAuthorityFactory.sol


Suggested change

- url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/authority/IAuthorityFactory.sol

- url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.10/src/consensus/authority/IAuthorityFactory.sol

lynoferraz · 2026-09-01T19:48:22Z

 title: IAuthority
 resources:
-  - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/consensus/authority/IAuthority.sol
+  - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/authority/IAuthority.sol


Suggested change

- url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/authority/IAuthority.sol

- url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.10/src/consensus/authority/IAuthority.sol

lynoferraz · 2026-09-01T21:11:02Z

+| :-- | :-- | :-- |
+| Guest tools | `machine-emulator-tools` (typically `0.14.1`) | `machine-guest-tools` (typically `0.17.2`) |
+| Typical base | Ubuntu Jammy RISC-V images | Ubuntu Noble RISC-V images |
+| Node emulator | Emulator SDK 0.17.x | Emulator `v0.20.0` |


lynoferraz · 2026-09-01T21:13:33Z


 ```bash
-cast send 0xc700D6aDd016eECd59d989C028214Eaa0fCC0051 "depositERC20Tokens(address,address,uint256,bytes)" 0xFBdB734EF6a23aD76863CbA6f10d0C5CBBD8342C 0xba3347e79665924033beeb7362629ca7992897d9 202 0x --rpc-url http://127.0.0.1:6751/anvil --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
+cast send 0xc700D6aDd016eECd59d989C028214Eaa0fCC0051 "depositErc20Tokens(address,address,uint256,bytes)" 0xFBdB734EF6a23aD76863CbA6f10d0C5CBBD8342C 0xba3347e79665924033beeb7362629ca7992897d9 202 0x --rpc-url http://127.0.0.1:6751/anvil --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80


Review contracts alpha 10 portal address

lynoferraz · 2026-09-01T21:14:09Z


 ```bash
-cast send 0xc700d52F5290e978e9CAe7D1E092935263b60051 "depositERC721Token(address,address,uint256,bytes,bytes)" 0xBa46623aD94AB45850c4ecbA9555D26328917c3B 0xba3347e79665924033beeb7362629ca7992897d9 8 0x 0x --rpc-url http://127.0.0.1:6751/anvil --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
+cast send 0xc700d52F5290e978e9CAe7D1E092935263b60051 "depositErc721Token(address,address,uint256,bytes,bytes)" 0xBa46623aD94AB45850c4ecbA9555D26328917c3B 0xba3347e79665924033beeb7362629ca7992897d9 8 0x 0x --rpc-url http://127.0.0.1:6751/anvil --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80


Review contracts alpha 10 portal address

lynoferraz · 2026-09-01T21:14:17Z


 ```bash
-cast send 0xc700A261279aFC6F755A3a67D86ae43E2eBD0051 "depositSingleERC1155Token(address,address,uint256,uint256,bytes,bytes)" 0xDC6d64971B77a47fB3E3c6c409D4A05468C398D2 0x0c0fe740dcd46f0a6ddb8498d0bfdca93c5910e6 5 1 0x 0x --rpc-url http://127.0.0.1:6751/anvil --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
+cast send 0xc700A261279aFC6F755A3a67D86ae43E2eBD0051 "depositSingleErc1155Token(address,address,uint256,uint256,bytes,bytes)" 0xDC6d64971B77a47fB3E3c6c409D4A05468C398D2 0x0c0fe740dcd46f0a6ddb8498d0bfdca93c5910e6 5 1 0x 0x --rpc-url http://127.0.0.1:6751/anvil --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80


Review contracts alpha 10 portal address

lynoferraz · 2026-09-01T21:17:36Z


 <Tabs>

 <TabItem value="Structure" label="Structure" default>


Are there erc1155batch and ether tabs? Should it?

lynoferraz

Minor version corrections. Also give a overall look on the addresses used

github-actions Bot added a commit that referenced this pull request Aug 19, 2026

Deploy preview for PR #353 (5cb4f72)

f7a0031

riseandshaheen mentioned this pull request Aug 21, 2026

Update Docs to cover foreclosure and emergency withdrawal #343

Merged

docs(v2): update Rollups 2.0 migration, community tools, and self-hos…

08cc5d5

…ted guides Align v2.0 docs with JSON-RPC, unified outputs, and the current community stack; refresh lastUpdated markers on reviewed pages.

riseandshaheen force-pushed the docs/v2-rollups-docs-updates branch from 5cb4f72 to 08cc5d5 Compare August 21, 2026 08:41

github-actions Bot added a commit that referenced this pull request Aug 21, 2026

Deploy preview for PR #353 (08cc5d5)

be25263

github-actions Bot added a commit that referenced this pull request Aug 24, 2026

Deploy preview for PR #353 (f589a5e)

5a9c506

docs(v2): fix self-hosted and EW guides for working testnet deploy

7eb25da

Align Authority-first EW deploy, recovery caveats, and compose with the validated Sepolia flow, and drop alpha-specific intro noise and a stale migration note. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions Bot added a commit that referenced this pull request Aug 24, 2026

Deploy preview for PR #353 (7eb25da)

d3d889f

riseandshaheen requested review from Nonnyjoe, jplgarcia and lynoferraz August 24, 2026 12:48

riseandshaheen marked this pull request as ready for review August 24, 2026 12:49

docs(v2): add self-hosted good practices for longer-lived nodes

7f814f6

Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions Bot added a commit that referenced this pull request Aug 24, 2026

Deploy preview for PR #353 (7f814f6)

87c29d3

jplgarcia requested changes Aug 25, 2026

View reviewed changes

riseandshaheen and others added 2 commits August 28, 2026 20:35

docs(v2): restructure self-hosted standard deployment guide

75ee02d

Split node setup from deployment, document CLI and cast paths with tested Sepolia recipes, and add a dedicated cast registration section. Co-authored-by: Cursor <cursoragent@cursor.com>

docs(v2): polish migration guide and add whitepaper sidebar link

911b18f

Clarify v1 withdrawal wording, remove stale alpha/PR callouts, and add the Cartesi Whitepaper to Resources. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions Bot added a commit that referenced this pull request Aug 28, 2026

Deploy preview for PR #353 (911b18f)

e924ac9

docs(v2): unhide 2.0 alpha as the default Rollups version

281f88a

Show 2.0 in the version dropdown, make it the default, and add alpha/unmaintained banners so readers can tell 2.0 from 1.5. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions Bot added a commit that referenced this pull request Sep 1, 2026

Deploy preview for PR #353 (281f88a)

a5f47d3

Nonnyjoe reviewed Sep 1, 2026

View reviewed changes

lynoferraz reviewed Sep 1, 2026

View reviewed changes


		### Use dedicated database roles

		The sample compose shares one Postgres role (`postgres`) and one database (`rollupsdb`). For any longer-lived deployment, create a dedicated database user per service, grant only the tables that service needs, and do not use the superuser in application containers. Give Postgres a named volume, and back it up. Inputs live in the InputBox on L1, so a node can be rebuilt from chain plus the exact snapshot that produced the registered template hash — keep that published snapshot, not only a local rebuild.

	- url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/authority/AuthorityFactory.sol
	- url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.10/src/consensus/authority/AuthorityFactory.sol

	\| Node emulator \| Emulator SDK 0.17.x \| Emulator `v0.20.0` \|
	\| Node emulator \| Emulator SDK 0.17.x \| Emulator `v0.21.0` \|

Uh oh!

Conversation

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

Uh oh!

Summary

Uh oh!

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

Uh oh!

📖 Docs preview is ready

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jplgarcia commented Aug 25, 2026

Uh oh!

Nonnyjoe Sep 1, 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!

Nonnyjoe Sep 1, 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!

Nonnyjoe Sep 1, 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!

lynoferraz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lynoferraz left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

riseandshaheen commented Aug 19, 2026 •

edited

Loading

github-actions Bot commented Aug 19, 2026 •

edited

Loading

Nonnyjoe Sep 1, 2026 •

edited

Loading

Nonnyjoe Sep 1, 2026 •

edited

Loading

Nonnyjoe Sep 1, 2026 •

edited

Loading