From 08cc5d5c2a845ad23977b9165a2d01c5e55ac8c9 Mon Sep 17 00:00:00 2001 From: Shaheen Date: Wed, 19 Aug 2026 15:39:17 +0530 Subject: [PATCH 1/4] docs(v2): update Rollups 2.0 migration, community tools, and self-hosted guides Align v2.0 docs with JSON-RPC, unified outputs, and the current community stack; refresh lastUpdated markers on reviewed pages. --- .../api-reference/backend/exception.md | 2 + .../api-reference/backend/finish.md | 2 + .../api-reference/backend/introduction.md | 2 + .../api-reference/backend/notices.md | 2 + .../api-reference/backend/reports.md | 2 + .../api-reference/backend/vouchers.md | 2 + .../contracts/application-factory.md | 2 + .../api-reference/contracts/application.md | 2 + .../contracts/consensus/abstract-consensus.md | 2 + .../consensus/authority/authority-factory.md | 2 + .../consensus/authority/authority.md | 2 + .../consensus/authority/iauthority-factory.md | 2 + .../consensus/authority/iauthority.md | 2 + .../contracts/consensus/iconsensus.md | 2 + .../ioutputs-merkle-root-validator.md | 2 + .../contracts/consensus/overview.md | 2 + .../consensus/quorum/iquorum-factory.md | 2 + .../contracts/consensus/quorum/iquorum.md | 2 + .../consensus/quorum/quorum-factory.md | 2 + .../contracts/consensus/quorum/quorum.md | 2 + .../api-reference/contracts/input-box.md | 2 + .../api-reference/contracts/overview.md | 2 + .../contracts/portals/ERC1155BatchPortal.md | 2 + .../contracts/portals/ERC1155SinglePortal.md | 2 + .../contracts/portals/ERC20Portal.md | 2 + .../contracts/portals/ERC721Portal.md | 2 + .../contracts/portals/EtherPortal.md | 2 + .../version-2.0/api-reference/index.md | 2 + ...tate-http-api-for-cartesi-rollups.info.mdx | 2 + .../api-reference/inspect/inspect.api.mdx | 2 + .../api-reference/jsonrpc/methods.md | 2 + .../jsonrpc/methods/applications/get.md | 2 + .../jsonrpc/methods/applications/list.md | 2 + .../jsonrpc/methods/epochs/get.md | 2 + .../jsonrpc/methods/epochs/last-accepted.md | 2 + .../jsonrpc/methods/epochs/list.md | 2 + .../jsonrpc/methods/inputs/get.md | 2 + .../jsonrpc/methods/inputs/list.md | 2 + .../jsonrpc/methods/inputs/processed-count.md | 2 + .../jsonrpc/methods/node/chain-id.md | 2 + .../jsonrpc/methods/node/version.md | 2 + .../jsonrpc/methods/outputs/get.md | 2 + .../jsonrpc/methods/outputs/list.md | 2 + .../jsonrpc/methods/reports/get.md | 2 + .../jsonrpc/methods/reports/list.md | 2 + .../api-reference/jsonrpc/overview.md | 2 + .../api-reference/jsonrpc/types.md | 2 + .../api-reference/rollup/add-notice.api.mdx | 2 + .../api-reference/rollup/add-report.api.mdx | 2 + .../api-reference/rollup/add-voucher.api.mdx | 2 + .../rollup/cartesi-rollup-http-api.info.mdx | 2 + .../api-reference/rollup/finish.api.mdx | 2 + .../rollup/register-exception.api.mdx | 2 + .../version-2.0/build-with-ai/mcp-server.mdx | 2 + .../version-2.0/build-with-ai/overview.md | 2 + .../version-2.0/build-with-ai/prompting.md | 2 + .../version-2.0/build-with-ai/skills.md | 2 + .../core-concepts/cartesi-machine.md | 2 + .../version-2.0/deployment/introduction.md | 2 + .../deployment/self-hosted/standard.md | 92 ++-- .../version-2.0/deployment/snapshot.md | 2 + .../development/advanced-configuration.md | 2 + .../version-2.0/development/asset-handling.md | 2 + .../development/building-an-application.md | 2 + .../development/creating-an-application.md | 7 +- .../version-2.0/development/installation.md | 2 + .../version-2.0/development/query-outputs.md | 2 + .../development/running-an-application.md | 6 +- .../development/send-inputs-and-assets.md | 2 + .../getting-started/architecture.md | 2 + .../version-2.0/getting-started/concepts.md | 2 + .../getting-started/installation.md | 2 + .../version-2.0/index.md | 2 + .../version-2.0/resources/community-tools.md | 184 ++----- .../resources/integration-guides.md | 2 + .../version-2.0/resources/mainnet.md | 2 + .../version-2.0/resources/migration-guide.md | 462 +++++++++++++++--- .../version-2.0/tutorials/calculator.md | 2 + .../version-2.0/tutorials/counter.md | 2 + .../tutorials/erc-1155-token-wallet.md | 2 + .../tutorials/erc-20-token-wallet.md | 2 + .../tutorials/erc-721-token-wallet.md | 2 + .../version-2.0/tutorials/ether-wallet.md | 2 + .../version-2.0/tutorials/marketplace.md | 2 + .../tutorials/react-frontend-application.md | 2 + ...unning-applications-on-a-forked-network.md | 2 + .../tutorials/utilizing-the-cli-AA-feature.md | 2 + .../utilizing-the-cli-test-tokens.md | 2 + .../version-2.0-sidebars.json | 3 +- 89 files changed, 655 insertions(+), 265 deletions(-) diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/exception.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/exception.md index 654fb4e8f..1d0435870 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/exception.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/exception.md @@ -3,6 +3,8 @@ id: exception title: Exception --- + + The `/exception` endpoint is used to register an exception when the dApp cannot proceed with request processing. This should be the last method called by the dApp backend while processing a request. When an exception occurs during request processing, the dApp backend should: diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/finish.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/finish.md index 9480501e3..04338dd63 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/finish.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/finish.md @@ -3,6 +3,8 @@ id: finish title: Finish --- + + The `/finish` endpoint is used to indicate that any previous processing has been completed and the backend is ready to handle the next request. The subsequent request is returned as the call's response. The dApp backend should call the `/finish` endpoint to start processing rollup requests. The Rollup HTTP Server returns the next rollup request in the response body. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/introduction.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/introduction.md index 6aae203b8..ed80346b2 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/introduction.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/introduction.md @@ -3,6 +3,8 @@ id: introduction title: Introduction --- + + The backend of a Cartesi dApp processes requests in the following manner: - **Finish** — Called via [`/finish`](./finish.md), indicates that any previous processing has been completed and the backend is ready to handle the next request. The subsequent request is returned as the call's response and can be of the following types: diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/notices.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/notices.md index 7a90900f2..27953794c 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/notices.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/notices.md @@ -3,6 +3,8 @@ id: notices title: Notices --- + + A notice is a verifiable data declaration that attests to off-chain events or conditions and is accompanied by proof. Notices provide a mechanism to communicate essential off-chain events from the execution layer to the base layer in a verifiable manner. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/reports.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/reports.md index 34faa1ad4..3a712ead2 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/reports.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/reports.md @@ -3,6 +3,8 @@ id: reports title: Reports --- + + Reports are stateless logs, offering a means to record read-only information without changing the state. Primarily used for logging and diagnostic purposes, reports provide valuable insights into the operation and performance of a dApp. Unlike notices, reports lack any association with proof and are therefore unsuitable for facilitating trustless interactions, such as on-chain processing or convincing independent third parties of dApp outcomes. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/vouchers.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/vouchers.md index 51409abfa..b273900a9 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/vouchers.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/vouchers.md @@ -6,6 +6,8 @@ resources: title: DELEGATECALL Opcode --- + + Vouchers serve as a mechanism for facilitating on-chain actions initiated in the execution layer. Imagine vouchers as digital authorization tickets that grant dApps the authority to execute specific actions directly on the base layer. These vouchers encapsulate the details of the desired on-chain action, such as a token swap request or asset transfer. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application-factory.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application-factory.md index 164950726..785de1272 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application-factory.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application-factory.md @@ -6,6 +6,8 @@ resources: title: Application Factory contract --- + + The **ApplicationFactory** contract is a tool for reliably deploying new instances of the [`Application`](../contracts/application.md) contract with or without a specified salt value for address derivation. Additionally, it provides a function to calculate the address of a potential new `CartesiDApp` contract based on input parameters. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application.md index 385821a0e..6049486ce 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application.md @@ -8,6 +8,8 @@ resources: title: OpenZeppelin Contracts --- + + The **Application** contract serves as the base layer representation of the application running on the execution layer. The application can interact with other smart contracts through the execution and validation of outputs. These outputs, generated by the application backend on the execution layer, can be proven in the base layer through claims submitted by a consensus contract. Every Application is subscribed to a consensus contract and governed by a single address (owner). The consensus has the authority to submit claims, which are then used to validate outputs. The owner has complete control over the Application and can replace the consensus at any time. Consequently, users of an Application must trust both the consensus and the application owner. Depending on centralization or ownership concerns, the ownership model can be modified. This process is managed by the consensus contract. For more information about different ownership and consensus models, refer to the [consensus contracts](./consensus/overview.md). diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/abstract-consensus.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/abstract-consensus.md index 7b586a402..23c31eb08 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/abstract-consensus.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/abstract-consensus.md @@ -6,6 +6,8 @@ resources: title: AbstractConsensus Contract --- + + The **AbstractConsensus** contract provides an abstract implementation of `IConsensus` with common consensus functionality. ## Functions diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/authority-factory.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/authority-factory.md index 48ec68eee..3e3eeb9d0 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/authority-factory.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/authority-factory.md @@ -6,6 +6,8 @@ resources: title: AuthorityFactory Contract --- + + The **AuthorityFactory** contract allows anyone to reliably deploy new `IAuthority` contracts. ## Functions diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/authority.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/authority.md index 48c604567..a29a840c8 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/authority.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/authority.md @@ -6,6 +6,8 @@ resources: title: Authority Contract --- + + The **Authority** contract implements a single-owner consensus mechanism where only the contract owner can submit and accept claims. ## Functions diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/iauthority-factory.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/iauthority-factory.md index c9c91f50d..00e4757da 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/iauthority-factory.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/iauthority-factory.md @@ -6,6 +6,8 @@ resources: title: IAuthorityFactory Interface --- + + The **IAuthorityFactory** interface defines the contract for deploying new `IAuthority` contracts. ## Events diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/iauthority.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/iauthority.md index 3e04fd366..bf0e47406 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/iauthority.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/iauthority.md @@ -6,6 +6,8 @@ resources: title: IAuthority Interface --- + + The `IAuthority` interface defines a consensus contract controlled by a single address, the owner. ## Description diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/iconsensus.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/iconsensus.md index 660022646..539aba313 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/iconsensus.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/iconsensus.md @@ -6,6 +6,8 @@ resources: title: IConsensus Interface --- + + The `IConsensus` interface defines the main consensus contract behavior for validating and accepting claims submitted by validators. ## Description diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/ioutputs-merkle-root-validator.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/ioutputs-merkle-root-validator.md index 50381952d..a0b941c4a 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/ioutputs-merkle-root-validator.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/ioutputs-merkle-root-validator.md @@ -6,6 +6,8 @@ resources: title: IOutputsMerkleRootValidator Interface --- + + The `IOutputsMerkleRootValidator` interface provides valid outputs Merkle roots for validation. ## Description diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/overview.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/overview.md index dff5dd066..4f445ca03 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/overview.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/overview.md @@ -6,6 +6,8 @@ resources: title: Consensus Smart Contracts --- + + The consensus mechanism in Cartesi Rollups is responsible for validating and accepting claims submitted by validators. These contracts ensure the integrity of the rollup by validating outputs Merkle roots. ## Consensus Contracts diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/iquorum-factory.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/iquorum-factory.md index 1cf78eb89..e91cc0bc8 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/iquorum-factory.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/iquorum-factory.md @@ -6,6 +6,8 @@ resources: title: IQuorumFactory Interface --- + + The **IQuorumFactory** interface defines the contract for deploying new `IQuorum` contracts. ## Events diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/iquorum.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/iquorum.md index a179662a0..c033a9485 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/iquorum.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/iquorum.md @@ -6,6 +6,8 @@ resources: title: IQuorum Interface --- + + The `IQuorum` interface defines a consensus model controlled by a small, immutable set of validators. ## Description diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/quorum-factory.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/quorum-factory.md index 176f177b1..6d80d5270 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/quorum-factory.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/quorum-factory.md @@ -6,6 +6,8 @@ resources: title: QuorumFactory Contract --- + + The **QuorumFactory** contract allows anyone to reliably deploy new `IQuorum` contracts. ## Functions diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/quorum.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/quorum.md index 629339719..82099cc62 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/quorum.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/quorum.md @@ -6,6 +6,8 @@ resources: title: Quorum Contract --- + + The **Quorum** contract implements a multi-validator consensus mechanism where claims are accepted when a majority of validators vote in favor. ## Functions diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/input-box.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/input-box.md index 2bffa0cb4..7fae34b8d 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/input-box.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/input-box.md @@ -6,6 +6,8 @@ resources: title: InputBox contract --- + + The **InputBox** is a trustless and permissionless contract that receives arbitrary data blobs (called "inputs") from any sender and adds a compound hash to an append-only list (the "input box"). The hash stored on-chain comprises the hash of the input blob, block number, timestamp, input sender address, and input index. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/overview.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/overview.md index 27f21b165..4435641b7 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/overview.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/overview.md @@ -6,6 +6,8 @@ resources: title: Smart Contracts for Cartesi Rollups --- + + The Cartesi Rollups framework consists of components on two layers: the base layer (the foundational blockchain where an application contract is deployed, such as Ethereum) and the execution layer (the Cartesi off-chain layer where the application runs its backend logic). The frontend interacts with base layer smart contracts to send inputs to the backend, deposit assets, and process outputs. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC1155BatchPortal.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC1155BatchPortal.md index b9445c683..916f2213b 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC1155BatchPortal.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC1155BatchPortal.md @@ -4,6 +4,8 @@ resources: title: ERC1155BatchPortal contract --- + + The **ERC1155BatchPortal** allows anyone to perform batch transfers of ERC-1155 tokens to a dApp while informing the off-chain machine. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC1155SinglePortal.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC1155SinglePortal.md index a85c7ee7b..ef5c47e5f 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC1155SinglePortal.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC1155SinglePortal.md @@ -4,6 +4,8 @@ resources: title: ERC1155SinglePortal contract --- + + The **ERC1155SinglePortal** allows anyone to perform single transfers of ERC-1155 tokens to a dApp while informing the off-chain machine. ### `depositSingleERC1155Token()` diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC20Portal.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC20Portal.md index 08261f225..5bc492c2b 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC20Portal.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC20Portal.md @@ -4,6 +4,8 @@ resources: title: ERC20Portal contract --- + + The **ERC20Portal** allows anyone to perform transfers of ERC-20 tokens to a dApp while informing the off-chain machine. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC721Portal.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC721Portal.md index 7719e399f..2c688250a 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC721Portal.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC721Portal.md @@ -4,6 +4,8 @@ resources: title: ERC721Portal contract --- + + The **ERC721Portal** allows anyone to perform transfers of ERC-721 tokens to a dApp while informing the off-chain machine. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/EtherPortal.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/EtherPortal.md index edf46329e..aca3f188a 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/EtherPortal.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/EtherPortal.md @@ -4,6 +4,8 @@ resources: title: EtherPortal contract --- + + The **EtherPortal** allows anyone to perform transfers of Ether to a dApp while informing the off-chain machine. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/index.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/index.md index 6c06cf7c0..c41d72c45 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/index.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/index.md @@ -10,6 +10,8 @@ resources: title: Smart Contracts for Cartesi Rollups --- + + In a Cartesi dApp, the frontend and backend components communicate through the Rollups framework using HTTP and JSON-RPC APIs. When designing the APIs for this communication framework, we aimed to ensure that developers could create their applications without excessive concern about the low-level components of Cartesi Rollups. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/inspect/inspect-state-http-api-for-cartesi-rollups.info.mdx b/cartesi-rollups_versioned_docs/version-2.0/api-reference/inspect/inspect-state-http-api-for-cartesi-rollups.info.mdx index f8b374352..5a0c07185 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/inspect/inspect-state-http-api-for-cartesi-rollups.info.mdx +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/inspect/inspect-state-http-api-for-cartesi-rollups.info.mdx @@ -8,6 +8,8 @@ hide_title: true custom_edit_url: null --- + + import ApiLogo from "@theme/ApiLogo"; import Heading from "@theme/Heading"; import SchemaTabs from "@theme/SchemaTabs"; diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/inspect/inspect.api.mdx b/cartesi-rollups_versioned_docs/version-2.0/api-reference/inspect/inspect.api.mdx index 2782999c4..e66bb8a22 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/inspect/inspect.api.mdx +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/inspect/inspect.api.mdx @@ -11,6 +11,8 @@ info_path: cartesi-rollups/_versioned_docs/version-2.0/rollups-apis/inspect/insp custom_edit_url: null --- + + import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods.md index a8e64b6e1..4c8a41b67 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods.md @@ -3,6 +3,8 @@ id: methods title: Methods --- + + # JSON-RPC API Methods This page provides a quick reference to all available JSON-RPC methods in the Cartesi Rollups Node API. For each method, you will find: diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/applications/get.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/applications/get.md index daff9086f..2e3e7ec03 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/applications/get.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/applications/get.md @@ -3,6 +3,8 @@ id: applications-get title: Get Application --- + + # Get Application ## Example Request diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/applications/list.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/applications/list.md index 55abab6ee..f7028d8b1 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/applications/list.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/applications/list.md @@ -3,6 +3,8 @@ id: applications-list title: List Applications --- + + # List Applications ## Example Request diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/epochs/get.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/epochs/get.md index 9fe4d1322..0a216f1a0 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/epochs/get.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/epochs/get.md @@ -3,6 +3,8 @@ id: epochs-get title: Get Epoch --- + + # Get Epoch ## Example Request diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/epochs/last-accepted.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/epochs/last-accepted.md index 1b56d9e03..4b15922ae 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/epochs/last-accepted.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/epochs/last-accepted.md @@ -3,6 +3,8 @@ id: jsonrpc-epochs-last-accepted title: Get Last Accepted Epoch Index --- + + # Get Last Accepted Epoch Index ## Example Request diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/epochs/list.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/epochs/list.md index 1808db3c6..a589d0d9d 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/epochs/list.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/epochs/list.md @@ -3,6 +3,8 @@ id: epochs-list title: List Epochs --- + + # List Epochs ## Example Request diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/inputs/get.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/inputs/get.md index abfd335cd..a25170ec8 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/inputs/get.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/inputs/get.md @@ -3,6 +3,8 @@ id: inputs-get title: Get Input --- + + # Get Input ## Example Request diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/inputs/list.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/inputs/list.md index b19f93d1c..3afdd921b 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/inputs/list.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/inputs/list.md @@ -3,6 +3,8 @@ id: inputs-list title: List Inputs --- + + # List Inputs ## Example Request diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/inputs/processed-count.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/inputs/processed-count.md index 22cc6d0c8..57ad1ffe2 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/inputs/processed-count.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/inputs/processed-count.md @@ -3,6 +3,8 @@ id: jsonrpc-inputs-processed-count title: Get Processed Input Count --- + + # Get Processed Input Count ## Example Request diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/node/chain-id.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/node/chain-id.md index 86db0d2e8..79166d723 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/node/chain-id.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/node/chain-id.md @@ -3,6 +3,8 @@ id: node-chain-id title: Get Chain ID --- + + # Get Chain ID ## Example Request diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/node/version.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/node/version.md index 26dc7b0f6..f44840a0f 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/node/version.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/node/version.md @@ -3,6 +3,8 @@ id: node-version title: Get Node Version --- + + # Get Node Version ## Example Request diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/outputs/get.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/outputs/get.md index 6440d64f9..416904fe9 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/outputs/get.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/outputs/get.md @@ -3,6 +3,8 @@ id: outputs-get title: Get Output --- + + # Get Output ## Example Request diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/outputs/list.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/outputs/list.md index e791300aa..44d0dec19 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/outputs/list.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/outputs/list.md @@ -3,6 +3,8 @@ id: outputs-list title: List Outputs --- + + # List Outputs ## Example Request diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/reports/get.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/reports/get.md index 427790c23..744edd48f 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/reports/get.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/reports/get.md @@ -3,6 +3,8 @@ id: reports-get title: Get Report --- + + # Get Report ## Example Request diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/reports/list.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/reports/list.md index 2f76c7c79..90218c3a7 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/reports/list.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/methods/reports/list.md @@ -3,6 +3,8 @@ id: reports-list title: List Reports --- + + # List Reports ## Example Request diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/overview.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/overview.md index a26d904fd..4812a6498 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/overview.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/overview.md @@ -3,6 +3,8 @@ id: overview title: Overview --- + + # JSON-RPC API Overview The Cartesi Rollups Node API provides a JSON-RPC interface for interacting with Cartesi Rollups applications. This API allows you to: diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/types.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/types.md index 83e13ed96..02f3d0bc7 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/types.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/jsonrpc/types.md @@ -3,6 +3,8 @@ id: types title: Types --- + + # JSON-RPC API Types This page documents the data types used in the Cartesi Rollups Node API. These types are used in both request parameters and response data. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/add-notice.api.mdx b/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/add-notice.api.mdx index f9b08d8a2..085b93b6f 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/add-notice.api.mdx +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/add-notice.api.mdx @@ -11,6 +11,8 @@ info_path: cartesi-rollups/_versioned_docs/version-2.0/api-reference/rollup/cart custom_edit_url: null --- + + import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/add-report.api.mdx b/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/add-report.api.mdx index c26919d19..161e94240 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/add-report.api.mdx +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/add-report.api.mdx @@ -11,6 +11,8 @@ info_path: cartesi-rollups/_versioned_docs/version-2.0/api-reference/rollup/cart custom_edit_url: null --- + + import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/add-voucher.api.mdx b/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/add-voucher.api.mdx index 30ee98781..d50786ce0 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/add-voucher.api.mdx +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/add-voucher.api.mdx @@ -11,6 +11,8 @@ info_path: cartesi-rollups/_versioned_docs/version-2.0/api-reference/rollup/cart custom_edit_url: null --- + + import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/cartesi-rollup-http-api.info.mdx b/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/cartesi-rollup-http-api.info.mdx index 977acdbb0..1de6b7f2f 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/cartesi-rollup-http-api.info.mdx +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/cartesi-rollup-http-api.info.mdx @@ -8,6 +8,8 @@ hide_title: true custom_edit_url: null --- + + import ApiLogo from "@theme/ApiLogo"; import Heading from "@theme/Heading"; import SchemaTabs from "@theme/SchemaTabs"; diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/finish.api.mdx b/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/finish.api.mdx index 008eaf191..3216409aa 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/finish.api.mdx +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/finish.api.mdx @@ -11,6 +11,8 @@ info_path: cartesi-rollups/_versioned_docs/version-2.0/api-reference/rollup/cart custom_edit_url: null --- + + import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/register-exception.api.mdx b/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/register-exception.api.mdx index 088e24374..b92a1dc12 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/register-exception.api.mdx +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/rollup/register-exception.api.mdx @@ -11,6 +11,8 @@ info_path: cartesi-rollups/_versioned_docs/version-2.0/api-reference/rollup/cart custom_edit_url: null --- + + import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; diff --git a/cartesi-rollups_versioned_docs/version-2.0/build-with-ai/mcp-server.mdx b/cartesi-rollups_versioned_docs/version-2.0/build-with-ai/mcp-server.mdx index 661b7dc8e..e603eb645 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/build-with-ai/mcp-server.mdx +++ b/cartesi-rollups_versioned_docs/version-2.0/build-with-ai/mcp-server.mdx @@ -5,6 +5,8 @@ resources: title: MCP Server Standard --- + + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; diff --git a/cartesi-rollups_versioned_docs/version-2.0/build-with-ai/overview.md b/cartesi-rollups_versioned_docs/version-2.0/build-with-ai/overview.md index 947d31a9c..a7ed28020 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/build-with-ai/overview.md +++ b/cartesi-rollups_versioned_docs/version-2.0/build-with-ai/overview.md @@ -2,6 +2,8 @@ title: Overview --- + + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; diff --git a/cartesi-rollups_versioned_docs/version-2.0/build-with-ai/prompting.md b/cartesi-rollups_versioned_docs/version-2.0/build-with-ai/prompting.md index 6818bda2a..0bc717b5d 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/build-with-ai/prompting.md +++ b/cartesi-rollups_versioned_docs/version-2.0/build-with-ai/prompting.md @@ -2,6 +2,8 @@ title: Prompting --- + + Effective prompting helps your AI assistant use Cartesi docs, skills, and the MCP server reliably. Clear prompts tell the assistant what to generate and which skill or doc source to follow. ## Anatomy of a strong prompt diff --git a/cartesi-rollups_versioned_docs/version-2.0/build-with-ai/skills.md b/cartesi-rollups_versioned_docs/version-2.0/build-with-ai/skills.md index a4a13c2f7..a0a8371e8 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/build-with-ai/skills.md +++ b/cartesi-rollups_versioned_docs/version-2.0/build-with-ai/skills.md @@ -9,6 +9,8 @@ resources: title: Cartesi skills setup walkthrough --- + + **Cartesi Skills** are lightweight, specialized instructions for AI agents. Each skill covers a focused task: scaffolding a new app, building backend logic, wiring a frontend, interacting with L1 contracts, or deploying to a self-hosted node. Cartesi Skills follow the open [Agent Skills](https://agentskills.io/home) format. For a similar pattern in the broader Ethereum ecosystem, see [eth-skills](https://www.ethskills.com/). diff --git a/cartesi-rollups_versioned_docs/version-2.0/core-concepts/cartesi-machine.md b/cartesi-rollups_versioned_docs/version-2.0/core-concepts/cartesi-machine.md index 72140ca2d..7ec8c59b2 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/core-concepts/cartesi-machine.md +++ b/cartesi-rollups_versioned_docs/version-2.0/core-concepts/cartesi-machine.md @@ -3,6 +3,8 @@ id: cartesi-machine title: Cartesi Machine --- + + The [Cartesi Machine](/cartesi-machine) is a virtual machine that runs an entire Linux OS, in which a dApp's backend is executed. The Cartesi Machine is based on the [RISC-V ISA](https://riscv.org/), a set of instructions for processors. It runs in isolation, meaning it operates independently and is reproducible. Central to Cartesi Rollups is the Cartesi Machine, a virtual machine designed to perform off-chain computations for blockchain applications. When examined from a high level of abstraction, the Cartesi Machine can be compared to an AWS Lambda function, with similarities that encompass: diff --git a/cartesi-rollups_versioned_docs/version-2.0/deployment/introduction.md b/cartesi-rollups_versioned_docs/version-2.0/deployment/introduction.md index 4460f0066..27a7039cc 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/deployment/introduction.md +++ b/cartesi-rollups_versioned_docs/version-2.0/deployment/introduction.md @@ -7,6 +7,8 @@ resources: --- + + Applications built on Cartesi Rollups are intended to be deployed to public blockchains so users can access them. This can be done by taking advantage of a cloud-based infrastructure. Deploying a Cartesi dApp involves two steps: deploying a smart contract that defines your dApp on-chain and then instantiating a node that runs the application's intended backend logic. diff --git a/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/standard.md b/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/standard.md index e1ebc58f8..e43d24974 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/standard.md +++ b/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/standard.md @@ -3,21 +3,41 @@ id: standard title: Self-hosted deployment (standard) --- -This guide explains how to run a Cartesi Rollups node locally on your machine for development and testing purposes on **testnet**. + + +This guide explains how to run a Cartesi Rollups node on your machine for **testnet** development and testing. :::warning Production Warning -**This self-hosted approach should NOT be used in _production_.** +**Do not use this compose file as a production deployment.** + +It is a testnet-oriented starting point. It does not include public snapshot verification, production-grade secrets, high availability, or hardened Postgres. +::: + +## Node topology + +The [Mugen-Builders compose file](https://github.com/Mugen-Builders/deployment-setup-v2.0) already runs **one process per container**, not a single combined node: + +| Service | Role | +| :-- | :-- | +| `database` | Postgres | +| `evm-reader` | Reads L1 inputs and related events | +| `advancer` | Runs the Cartesi Machine; serves inspect | +| `validator` | Computes epoch claims and proofs | +| `claimer` | Submits claims on-chain | +| `jsonrpc-api` | JSON-RPC query API | + +Keep that split. Do not collapse reader, advancer, validator, claimer, and JSON-RPC into one process except for short local experiments. -While this setup works with testnet environments, it's designed exclusively for development purposes. It lacks critical production requirements such as: +The sample compose shares one Postgres role (`postgres`) and one database (`rollupsdb`). That is acceptable only for this testnet compose. 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. -- Public snapshot verification -- Proper security hardening -- Production-grade infrastructure. - ::: +The EVM reader **polls HTTP**. `BLOCKCHAIN_HTTP_ENDPOINT` is required. A WebSocket endpoint is optional and is not required for reading blocks. + +Pin runtime and database image tags to the rollups-node release you intend to run. The compose file on GitHub may lag a newer node alpha. ## Prerequisites -Before starting, ensure you have the following installed: +- Cartesi CLI 2.0 (currently alpha) +- Docker Desktop 4.x (Compose and Buildx) - Cartesi CLI: An easy-to-use tool for developing and deploying your dApps. @@ -27,57 +47,49 @@ For more details about the installation process for each of these tools, please ## Configuration -Before running the node, you need to configure your `.env` file with the following environment variables: +Create a `.env` file in the project root: ```shell BLOCKCHAIN_ID= AUTH_KIND="private_key" CARTESI_AUTH_PRIVATE_KEY="" -BLOCKCHAIN_WS_ENDPOINT="" BLOCKCHAIN_HTTP_ENDPOINT="" CARTESI_BLOCKCHAIN_DEFAULT_BLOCK="" ``` -**Important notes:** - | Variable | Description | | ---------------------------------- | -------------------------------------------------------------------- | -| `BLOCKCHAIN_ID` | Replace `` with your blockchain network ID | -| `BLOCKCHAIN_WS_ENDPOINT` | Replace `` with your WebSocket endpoint | -| `BLOCKCHAIN_HTTP_ENDPOINT` | Replace `` with your HTTP endpoint | -| `AUTH_KIND` | Set to `private_key` for local development | -| `CARTESI_AUTH_PRIVATE_KEY` | Replace `` with a private key for selected chain | -| `CARTESI_BLOCKCHAIN_DEFAULT_BLOCK` | Set to either `latest` or `finalized` | +| `BLOCKCHAIN_ID` | Chain ID of the target network | +| `BLOCKCHAIN_HTTP_ENDPOINT` | HTTP JSON-RPC endpoint for the base layer | +| `AUTH_KIND` | `private_key` for local and testnet experiments | +| `CARTESI_AUTH_PRIVATE_KEY` | Funded private key for the selected chain | +| `CARTESI_BLOCKCHAIN_DEFAULT_BLOCK` | `latest` or `finalized` | :::danger Security -Ensure to follow best practices when handling private keys during local development and deployment to production. +Do not commit private keys. Use Docker secrets or a file-backed key in any environment that is not a throwaway testnet. ::: ## Setting up the local node -1. **Download the Cartesi Rollups Node docker compose file in your project root:** +1. **Download the compose file into the project root** (alongside `.cartesi/`): ```shell curl -L https://raw.githubusercontent.com/Mugen-Builders/deployment-setup-v2.0/main/compose.local.yaml -o compose.local.yaml ``` -2. **Build the application with the Cartesi CLI:** +2. **Build the application snapshot:** ```shell cartesi build ``` - This command compiles your application into RISC-V architecture and creates a Cartesi machine snapshot locally. - -3. **Run the Cartesi Rollups Node with the application's initial snapshot attached:** +3. **Start the stack:** ```shell docker compose -f compose.local.yaml --env-file .env up -d ``` - This starts the local node using the configuration from your `.env` file. - -4. **Deploy and register the application to the node:** +4. **Deploy and register the application:** ```shell docker compose --project-name cartesi-rollups-node \ @@ -87,19 +99,17 @@ Ensure to follow best practices when handling private keys during local developm --register ``` - Replace `` with your application name and `` with a unique identifier. The salt must be unique for each deployment and cannot be repeated. You can generate a unique salt using: + Replace `` with the application name. The salt must be unique. Generate one with: ```shell cast keccak256 "your-unique-string" ``` - After this process, you'll have your application deployed and registered to the node. - - If deployment fails during the automated process, fall back to manually deploying the authority and application contracts. + If deployment fails, fall back to deploying authority and application contracts separately. ### Manual deployment fallback - 1. Deploy an authority contract with `cast`. Replace each placeholder with the expected value, and grab the returned address from the command output (the final `sed` call normalizes the address). + 1. Deploy an authority with `cast`. Capture the returned address (the `sed` call normalizes it): ```shell cast send "newAuthority(address,uint256)" \ @@ -107,9 +117,9 @@ Ensure to follow best practices when handling private keys during local developm --json | jq -r '.logs[-1].data' | sed 's/^0x000000000000000000000000/0x/' ``` - You can find the AuthorityFactory, portals and inputbox addresses for your target chain in the **Deployed Contracts** section below; Replace `` with the appropriate address. + Factory, portal, and InputBox addresses for the target chain are listed under **Deployed contracts** below. - 2. Use the address you got above as the `` in the deploy command below. This command re-runs the snapshot registration using the specified authority and epoch values. + 2. Register the snapshot against that authority: ```shell docker compose --project-name cartesi-rollups-node \ @@ -119,11 +129,11 @@ Ensure to follow best practices when handling private keys during local developm --json ``` - On success this command deploys, registers and returns the address of the deployed application contract, this should be notted for further interaction with your applciation. + On success the command returns the application contract address. -## Deployed Contracts: +## Deployed contracts -Depending on your intended deployment chain, you can find the list of required contracts like the Inputbox, Portals, Authority Factory etc, below: +Rollups contract addresses for supported networks: - [Cannon Devnet](https://usecannon.com/packages/cartesi-rollups/2.2.0/13370-main/deployment/contracts) - [Ethereum Sepolia](https://usecannon.com/packages/cartesi-rollups/2.2.0/11155111-main/deployment/contracts) @@ -131,9 +141,9 @@ Depending on your intended deployment chain, you can find the list of required c - [OP Sepolia](https://usecannon.com/packages/cartesi-rollups/2.2.0/11155420-main/deployment/contracts) - [Base Sepolia](https://usecannon.com/packages/cartesi-rollups/2.2.0/84532-main/deployment/contracts) -## Accessing the node +Use the Cannon package version that matches the contract suite your node was built against. -Once running, your local Cartesi Rollups Node will be accessible through the standard APIs: +## Accessing the node -- Inspect endpoint: `http://localhost:10012/inspect/` -- JSON-RPC endpoint: `http://localhost:10011/rpc` +- Inspect: `http://localhost:10012/inspect/` +- JSON-RPC: `http://localhost:10011/rpc` diff --git a/cartesi-rollups_versioned_docs/version-2.0/deployment/snapshot.md b/cartesi-rollups_versioned_docs/version-2.0/deployment/snapshot.md index 2b79b0c08..237a7a40a 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/deployment/snapshot.md +++ b/cartesi-rollups_versioned_docs/version-2.0/deployment/snapshot.md @@ -3,6 +3,8 @@ id: snapshot title: Public snapshot --- + + A Cartesi snapshot is a compressed representation of your application's machine state that can be deployed to rollups nodes. This process involves: 1. Building your application with the Cartesi CLI diff --git a/cartesi-rollups_versioned_docs/version-2.0/development/advanced-configuration.md b/cartesi-rollups_versioned_docs/version-2.0/development/advanced-configuration.md index 47d208292..e8268c4f0 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/development/advanced-configuration.md +++ b/cartesi-rollups_versioned_docs/version-2.0/development/advanced-configuration.md @@ -4,6 +4,8 @@ title: Advanced configuration resources: --- + + When you build an application with the Cartesi CLI, the CLI needs to know how to set up your Cartesi Machine. Things like how much memory to allocate, what code to run, and what data to include. All of these choices live in a single file at the root of your project called `cartesi.toml`. If you have worked with configuration files like `docker-compose.yml` or `Cargo.toml`, the idea is the same. You describe what you want, and the CLI takes care of the rest. diff --git a/cartesi-rollups_versioned_docs/version-2.0/development/asset-handling.md b/cartesi-rollups_versioned_docs/version-2.0/development/asset-handling.md index 4bbf9ff24..f8c222c86 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/development/asset-handling.md +++ b/cartesi-rollups_versioned_docs/version-2.0/development/asset-handling.md @@ -6,6 +6,8 @@ resources: title: The Cartesi dApp Developer Free Course --- + + Assets exist on the base layer, where they have actual meaning and value. As with any execution layer solution, a Cartesi Application that wants to manipulate assets needs a secure way of "teleporting" the assets from the base layer to the execution layer and when necessary, back to the base layer. diff --git a/cartesi-rollups_versioned_docs/version-2.0/development/building-an-application.md b/cartesi-rollups_versioned_docs/version-2.0/development/building-an-application.md index 6f04bf241..37a9671f3 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/development/building-an-application.md +++ b/cartesi-rollups_versioned_docs/version-2.0/development/building-an-application.md @@ -3,6 +3,8 @@ id: building-an-application title: Building an application --- + + “Building” in this context compiles your application into RISC-V architecture and consequently builds a Cartesi machine containing your application. This architecture enables computation done by your application to be reproducible and verifiable. Ensure you have Docker engine running, then navigate the directory to your application and build by running: diff --git a/cartesi-rollups_versioned_docs/version-2.0/development/creating-an-application.md b/cartesi-rollups_versioned_docs/version-2.0/development/creating-an-application.md index 7322c317b..d287e2f43 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/development/creating-an-application.md +++ b/cartesi-rollups_versioned_docs/version-2.0/development/creating-an-application.md @@ -6,6 +6,8 @@ resources: title: CartesiScan --- + + Cartesi CLI simplifies creating applications on Cartesi. To create a new application, run: @@ -33,9 +35,8 @@ This command creates a `new-app` directory with essential files for your applica Cartesi CLI has templates for the following languages – `cpp`, `cpp-low-level`, `go`, `java`, `javascript`, `lua`, `python`, `ruby`, `rust`, and `typescript`. :::note Libraries for simplifying development -We have high-level framework and alternative templates that simplify development and enhances input management, providing a smoother and more efficient experience. -For Go use Rollmelette, for Rust use Crabrolls, for Python use python-Cartesi and for Typescript/Javascrips use Deroll. -Visit this [page](../resources/community-tools.md) to learn more about these and other available tools. +High-level frameworks can simplify routing, inputs, and testing. For TypeScript use Deroll; for Python use python-Cartesi or Cartesapp. +See [Community tools](../resources/community-tools.md). ::: ## Implementing your application Logic diff --git a/cartesi-rollups_versioned_docs/version-2.0/development/installation.md b/cartesi-rollups_versioned_docs/version-2.0/development/installation.md index 3749d327b..e70fd7b23 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/development/installation.md +++ b/cartesi-rollups_versioned_docs/version-2.0/development/installation.md @@ -12,6 +12,8 @@ resources: title: Install Ubuntu LTS --- + + The primary requirements for building on Cartesi are: - Cartesi CLI: An easy-to-use tool for developing and deploying your dApps. diff --git a/cartesi-rollups_versioned_docs/version-2.0/development/query-outputs.md b/cartesi-rollups_versioned_docs/version-2.0/development/query-outputs.md index df8db12b8..5e96b6663 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/development/query-outputs.md +++ b/cartesi-rollups_versioned_docs/version-2.0/development/query-outputs.md @@ -6,6 +6,8 @@ resources: title: The Cartesi dApp Developer Free Course --- + + In Cartesi Rollups, outputs are essential in interacting with the blockchain. The direct output types are notices, reports and vouchers. The JSON-RPC server unifies Notice and Vouchers into a single query, therefore a single request returns all Notices and Vouchers generated by the application. diff --git a/cartesi-rollups_versioned_docs/version-2.0/development/running-an-application.md b/cartesi-rollups_versioned_docs/version-2.0/development/running-an-application.md index d77a09085..7770ff6f8 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/development/running-an-application.md +++ b/cartesi-rollups_versioned_docs/version-2.0/development/running-an-application.md @@ -6,6 +6,8 @@ resources: title: CartesiScan --- + + Running your application creates a docker container containing all required services, and exposes your application node on port `6751`, then an anvil network specific to your application on port `6751/anvil`. The node also logs all outputs received by your backend. Here are the prerequisites to run the node: @@ -83,7 +85,3 @@ Each of these services runs independently and can be activated or deactivated at - **Paymaster**: An account abstraction implementation that works hand in hand with the bundler to sponsor gas fees for transactions handled by the bundler, available at `http://localhost:6751/paymaster`. - **Passkey**: Runs a local passkey server, that enables account generation and interaction with application without a traditional wallet, available at `http://localhost:6751/passkey` - -:::note Testing tools -[NoNodo](https://github.com/Calindra/nonodo) is a Cartesi Rollups testing tool that works with host machine applications, eliminating the need for Docker or RISC-V compilation. -::: diff --git a/cartesi-rollups_versioned_docs/version-2.0/development/send-inputs-and-assets.md b/cartesi-rollups_versioned_docs/version-2.0/development/send-inputs-and-assets.md index 5581ec822..6f8a6bb2d 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/development/send-inputs-and-assets.md +++ b/cartesi-rollups_versioned_docs/version-2.0/development/send-inputs-and-assets.md @@ -8,6 +8,8 @@ resources: title: Angular template --- + + You can send two requests to an application depending on whether you want to change or read the state. - **Advance**: In this request, any input data changes the state of the application. diff --git a/cartesi-rollups_versioned_docs/version-2.0/getting-started/architecture.md b/cartesi-rollups_versioned_docs/version-2.0/getting-started/architecture.md index deb74432f..a3d80ce66 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/getting-started/architecture.md +++ b/cartesi-rollups_versioned_docs/version-2.0/getting-started/architecture.md @@ -14,6 +14,8 @@ resources: title: Dave --- + + The Cartesi Rollups framework is designed to enable complex computations off-chain while maintaining the security guarantees of blockchain technology. It consists of two primary components: **the on-chain base layer** (such as Ethereum), where the dApp contract is deployed, and **the off-chain execution layer**, where the dApp's backend logic operates. A decentralized application (dApp) built on Cartesi incorporates several key elements: diff --git a/cartesi-rollups_versioned_docs/version-2.0/getting-started/concepts.md b/cartesi-rollups_versioned_docs/version-2.0/getting-started/concepts.md index cefcf22fc..34cf9e877 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/getting-started/concepts.md +++ b/cartesi-rollups_versioned_docs/version-2.0/getting-started/concepts.md @@ -8,6 +8,8 @@ resources: title: Dave --- + + Before diving deep into the architecture and mechanisms of rollups, it's important to understand the fundamental concepts behind these scalability solutions. Rollups play a crucial role in enhancing blockchain performance by moving computation off-chain while ensuring security through on-chain verification. This section covers the core principles of rollups, the different approaches to validating state updates, and how dispute resolution mechanisms function. These foundational ideas will help you better grasp the architecture and innovations introduced by Cartesi's rollup solutions, including the **Dave** fraud-proof system. ## What is a Blockchain Rollup? diff --git a/cartesi-rollups_versioned_docs/version-2.0/getting-started/installation.md b/cartesi-rollups_versioned_docs/version-2.0/getting-started/installation.md index eed732d03..4fed879e5 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/getting-started/installation.md +++ b/cartesi-rollups_versioned_docs/version-2.0/getting-started/installation.md @@ -3,4 +3,6 @@ id: Installation title: Installation --- + + TODO: This is blank diff --git a/cartesi-rollups_versioned_docs/version-2.0/index.md b/cartesi-rollups_versioned_docs/version-2.0/index.md index f3bd14c7e..768e0da8b 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/index.md +++ b/cartesi-rollups_versioned_docs/version-2.0/index.md @@ -8,6 +8,8 @@ resources: title: Application-Specific Rollups --- + + Welcome to Cartesi Rollups, where decentralized application development meets unprecedented flexibility. With a foundation built on the Linux operating system, Cartesi Rollups offers modular stacks that allow developers to tailor consensus, data availability, and settlement layers according to their project requirements. Utilizing the Cartesi Machine for transaction processing, developers can effortlessly implement sophisticated logic using their preferred programming language or tool. Explore the possibilities and streamline your decentralized application development journey with Cartesi Rollups. diff --git a/cartesi-rollups_versioned_docs/version-2.0/resources/community-tools.md b/cartesi-rollups_versioned_docs/version-2.0/resources/community-tools.md index c403a64ce..003671e61 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/resources/community-tools.md +++ b/cartesi-rollups_versioned_docs/version-2.0/resources/community-tools.md @@ -3,180 +3,58 @@ id: community-tools title: Community tools --- -Several tools created and maintained by the community streamline the dApp creation process on Cartesi Rollups. + -## Deroll - -Introducing Deroll, a powerful TypeScript framework designed to simplify the development of dApps on Cartesi. - -- **Features**: - - Simplifies dApp development with intuitive methods. - - Handles advance and inspect requests easily. - - Comprehensive wallet functionality for ERC20, ERC721 and ERC-1155 token standards. - - Integrated router for complex routing logic. - -- **Getting Started**: - - Create a new Deroll project by running: - ```bash - npm init @deroll/app - ``` - -- **Resources**: - - [Deroll Documentation](https://deroll.dev) - - [Deroll GitHub Repository](https://github.com/tuler/deroll) - ---- - -## NoNodo - -NoNodo is a cutting-edge development tool for Cartesi Rollups that allows applications to run directly on the host machine, bypassing Docker or RISC-V compilation. - -- **Features**: - - Run applications directly on the host machine for faster performance. - - No Docker or RISC-V Required. - -- **Getting Started**: - - Install NoNodo by running: - ```bash - npm install -g @nonodo/cli - ``` -- **Resources**: - - [NoNodo GitHub Repository](https://github.com/Calindra/nonodo) - ---- - -## Cartesify - -Cartesify is a robust Web3 client designed for seamless interaction with the Cartesi Machine. - -- **Features**: - - Send transactions to the Cartesi Machine. - - Query data efficiently. - - Engage with backend systems using a REST-like interface. - -- **Resources**: - - [Cartesify GitHub Repository](https://github.com/Calindra/cartesify) - ---- - -## Tikua +Community projects that help build Cartesi Rollups applications. These are maintained outside the core Cartesi repositories. Confirm compatibility with Rollups v2 (JSON-RPC node API, unified outputs) before adopting them. -Tikua is a versatile JS Cartesi package designed for seamless integration with any visual library, whether in browser or terminal environments. - -- **Features**: - - Integrates smoothly with any visual library on both Browser and Terminal. - - Supports any provider or network with extensive configurability. - - Handles multi-chain applications. - - Provides warnings for unsupported provider chains. - - Retrieve machine results. - -- **Resources**: - - - [Tikua GitHub Repository](https://github.com/doiim/tikua) - - ---- - -## Rollmelette - -Rollmelette is a high-level framework that simplifies building Cartesi applications using the Go programming language. - -- **Features**: - - Simplifies the development of Cartesi applications. - - Provides a high-level API for interacting with the Cartesi Machine. - - Simplifies sending inputs, retrieving outputs and asset handling - - Supports the Go programming language. - -- **Resources**: - - [Rollmelette GitHub Repository](https://github.com/rollmelette/rollmelette) - ---- - -## Crabrolls +## Deroll -Introducing Crabroll, a powerful Rust framework designed to simplify the development of rust applications on Cartesi. +TypeScript framework for Cartesi dApps. -- **Features**: - - Simplifies dApp development with intuitive methods. - - Handles advance and inspect requests easily. - - Comprehensive wallet functionality for ERC20, ERC721 and ERC-1155 token standards. +- Advance and inspect handlers +- Wallet helpers for ERC-20, ERC-721, and ERC-1155 +- Router for application methods -- **Getting Started**: - - Create a new crabrolls project by running: - ```bash - git clone git@github.com:crabrolls-cartesi/template.git - ``` +```bash +npm init @deroll/app +``` -- **Resources**: - - [Crabrolls Documentation](https://crabrolls-cartesi.github.io/crabrolls/) - - [Crabrolls GitHub Repository](https://github.com/crabrolls-cartesi/crabrolls) +- [Documentation](https://deroll.dev) +- [GitHub](https://github.com/tuler/deroll) --- -## Python-Cartesi +## libcma (Cartesi Machine Assets) -Python-Cartesi is a high-level framework that simplifies the development of Cartesi applications using Python. +C++ library for parsing portal deposits and managing an in-machine asset ledger (Ether, ERC-20, ERC-721, ERC-1155). It is the basis for proveable balances and contracts v3 emergency withdrawal. -- **Features**: - - Simplifies the development of Cartesi applications. - - Prioritizes testing, equipping developers with tools to write tests for DApps within a local Python environment. - - Allows full control over inputs and outputs for scenarios where high-level tools may be insufficient - - Supports the Python programming language. +- Core: [Mugen-Builders/machine-asset-tools](https://github.com/Mugen-Builders/machine-asset-tools) +- Rust bindings: [Mugen-Builders/cma-rust-parser](https://github.com/Mugen-Builders/cma-rust-parser) +- Node.js / TypeScript bindings: [riseandshaheen/libcma-binding-node](https://github.com/riseandshaheen/libcma-binding-node) -- **Getting Started**: - - Install Python-Cartesi by running: - ```bash - pip install python-cartesi - ``` -- **Resources**: - - [Python-Cartesi GitHub Repository](https://github.com/prototyp3-dev/python-cartesi) +Related: [libcmt bindings](https://github.com/Mugen-Builders/libcmt-bindings) expose the guest `libcmt` C API (rollup I/O, ABI, Merkle) without the HTTP rollup server. --- -## TypeScript-SQLite template - -A backend application built with TypeScript and SQLite, designed to complement a corresponding frontend project. - -- **Features**: - - TypeScript and SQLite for backend development. - - Integration with React for the frontend. - - Ethers.js for seamless blockchain interaction. - - Template designed for easy project initiation. - -- **Resources**: - - [TypeScript-SQLite GitHub Repository](https://github.com/doiim/cartesi-ts-sqlite) - - [Pre-deployed demo available on the Sepolia Network](https://doiim.github.io/cartesi-ts-react-sqlite/). - ---- +## Python-Cartesi -## Python-Wallet +Python framework with local testing helpers and control over inputs and outputs. -A Python-based wallet implementation for Cartesi dApps designed to handle various types of assets. +```bash +pip install python-cartesi +``` -- **Features**: - - Simplifies asset handling for Cartesi dApps. - - Deposit assets into the dApp. - - Transfer assets within the dApp. - - Withdraw assets from the dApp. +- [GitHub](https://github.com/prototyp3-dev/python-cartesi) -- **Resources**: - - [Python-Wallet GitHub Repository](https://github.com/jplgarcia/python-wallet/tree/main) - - [Full example](https://github.com/jplgarcia/python-wallet/blob/main/dapp.py) --- -## CartDevKit -CartDevKit is an all-in-one package for building on Cartesi. +## Cartesapp -- **Features**: - - CLI tool for easy project setup. - - Templates for backend, frontend and Cartesify. +Opinionated Python library and CLI for Cartesi Rollups apps: routed endpoints, host and machine tests, build/run/deploy, and auto-generated frontend libraries. -- **Getting Started**: - - Create a new project: - ```bash - npx cartdevkit@latest create mydapp - ``` +```bash +pip3 install cartesapp[dev]@git+https://github.com/prototyp3-dev/cartesapp@main +cartesapp create NAME +``` -- **Resources**: - - [CartDevKit GitHub Repository](https://github.com/gconnect/cartdev-kit) - - [CartDevKit Documentation](https://africlab.gitbook.io/cartdevkit) \ No newline at end of file +- [GitHub](https://github.com/prototyp3-dev/cartesapp) diff --git a/cartesi-rollups_versioned_docs/version-2.0/resources/integration-guides.md b/cartesi-rollups_versioned_docs/version-2.0/resources/integration-guides.md index 0229081b0..f70ab5915 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/resources/integration-guides.md +++ b/cartesi-rollups_versioned_docs/version-2.0/resources/integration-guides.md @@ -3,6 +3,8 @@ id: integration-guides title: Integrations guide --- + + Guides for integrating external protocols into your Cartesi application. Each integration offers a unique functionality to your application. ## Avail Integration diff --git a/cartesi-rollups_versioned_docs/version-2.0/resources/mainnet.md b/cartesi-rollups_versioned_docs/version-2.0/resources/mainnet.md index 2a5801d96..a7c8220b6 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/resources/mainnet.md +++ b/cartesi-rollups_versioned_docs/version-2.0/resources/mainnet.md @@ -6,6 +6,8 @@ resources: title: Honeypot dApp --- + + Cartesi Rollups are app-specific execution environments that can be deployed as L2, L3, or sovereign rollups. It's not your typical L1 blockchain, so the idea of a "Mainnet launch" is slightly different. What goes to mainnet are the dApps built using Cartesi! And with the launch of the Honeypot dApp, Cartesi Rollups is officially ready for mainnet! ## About Mainnet diff --git a/cartesi-rollups_versioned_docs/version-2.0/resources/migration-guide.md b/cartesi-rollups_versioned_docs/version-2.0/resources/migration-guide.md index fdb3ee4a6..c42c06d1b 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/resources/migration-guide.md +++ b/cartesi-rollups_versioned_docs/version-2.0/resources/migration-guide.md @@ -3,94 +3,432 @@ id: migration-guide title: Migration Guide --- + + ## Migrating from Cartesi Rollups v1.5.x to v2.0 -Rollups node v2.0 introduces some major changes in how the node works internally and how the application code interacts with it. Not all the breaking changes affect all applications. To identify which changes might affect your application, check if any of the following cases apply: +Rollups node v2.0 changes how the node works internally and how application code interacts with it. Not every breaking change affects every application. Use the checklist below, then follow the matching sections. -### My back-end... -- handles ERC-20 token deposit inputs. See the [ERC-20 token deposit inputs](#erc-20-token-deposit-inputs) section. -- handles application address relay inputs. See the Application address section. -- generates Ether withdrawal vouchers. See the Ether withdrawal vouchers section. +### If the application backend -### My front-end... -- validates notices. See the Outputs section. -- executes vouchers. See the Outputs section. -- listens to voucher execution events. See the Outputs section. -- checks if a voucher was executed. See the Outputs section. -- uses inspect calls. See the Inspect calls section. -- uses JSON-RPC queries. See the JSON queries section. +- Decodes ERC-20 deposit inputs. See [ERC-20 token deposit inputs](#erc-20-token-deposit-inputs). +- Handles `DAppAddressRelay` inputs. See [Application address](#application-address). +- Generates Ether withdrawal vouchers. See [Ether withdrawal vouchers](#ether-withdrawal-vouchers). +- Builds a Cartesi Machine image with `machine-emulator-tools`. See [Cartesi Machine image](#cartesi-machine-image). -:::note -If your application uses a high-level framework(ex. Deroll, Rollmelette etc.) for either backend or frontend, check if the framework has already implemented the changes described in this guide. +### If the application frontend + +- Queries the node GraphQL API. See [JSON-RPC queries](#json-rpc-queries). +- Validates notices. See [Outputs](#outputs). +- Executes vouchers. See [Outputs](#outputs). +- Listens to voucher execution events. See [Outputs](#execution-event). +- Checks if a voucher was executed. See [Outputs](#execution-check). +- Uses inspect `GET /inspect/`. See [Inspect calls](#inspect-calls). +- Uses `@cartesi/wagmi`, `@cartesi/viem`, or another TypeScript client. See [TypeScript applications](#typescript-applications). + +:::note High-level frameworks +If you use Deroll, python-cartesi, Cartesapp, or a similar framework, check whether it already implements these changes before rewriting backend or frontend code by hand. ::: -### ERC-20 token deposit inputs +--- + +## ERC-20 token deposit inputs In SDK v1, ERC-20 token deposit inputs start with a 1-byte Boolean field which indicates whether the transfer was successful or not: -#### 1. Define the environment variables +| Field | Type | Size | Description | +| :-------- | :-------- | :------- | :--------------------------------------- | +| `success` | `bool` | 1 byte | Whether the ERC-20 transfer succeeded | +| `token` | `address` | 20 bytes | Address of the ERC-20 token contract | +| `sender` | `address` | 20 bytes | Address of the depositor | +| `amount` | `uint256` | 32 bytes | Amount of tokens deposited | +| `data` | `bytes` | variable | Extra data passed by the depositor | + +In SDK v2, the ERC-20 portal only accepts successful transfers. Because `success` would always be `true`, it was removed. The deposit payload is: + +| Field | Type | Size | Description | +| :------- | :-------- | :------- | :----------------------------------- | +| `token` | `address` | 20 bytes | Address of the ERC-20 token contract | +| `sender` | `address` | 20 bytes | Address of the depositor | +| `amount` | `uint256` | 32 bytes | Amount of tokens deposited | +| `data` | `bytes` | variable | Extra data passed by the depositor | + +Update the back-end to stop reading or checking the leading `success` byte. See [asset handling](../development/asset-handling.md#abi-encoding-for-deposits). + +Sources: [rollups-contracts `InputEncoding`](https://github.com/cartesi/rollups-contracts/blob/main/contracts/common/InputEncoding.sol); [contracts.md](https://github.com/cartesi/rollups-contracts/blob/v2.0.1/docs/contracts.md). + +--- + +## Application address + +In SDK v1, the back-end had no direct way to know its own on-chain address. `DAppAddressRelay` relayed it as an input. The back-end detected inputs from that contract and stored the payload. That address was required to build Ether or ERC-721 withdrawal vouchers. + +```python +# v1 — detect and store the relayed application address +if msg_sender.lower() == dapp_relay_address.lower(): + rollup_address = payload +``` + +In SDK v2, `DAppAddressRelay` is removed. Every advance-state input includes the application address in metadata as `app_contract`: + +```javascript +// v2 — read the application address from input metadata +const dAppAddress = data["metadata"]["app_contract"]; +``` + +Remove any handling of `DAppAddressRelay` inputs. Use `data.metadata.app_contract` whenever a voucher needs the application contract address. + +--- + +## Ether withdrawal vouchers + +In SDK v1, withdrawing Ether was a two-step process: -- `SALT`: A random 32-byte value for the deterministic deployment functions. -- `RPC_URL`: The RPC endpoint to be used. -- `MNEMONIC`: The mnemonic phrase for the Authority owner's wallet (other wallet options may be used). -- `HISTORY_FACTORY_ADDRESS`: The address of a valid HistoryFactory instance. -- `AUTHORITY_ADDRESS`: The address of the Authority instance used by the application. +1. Relay the application address using `DAppAddressRelay`. +2. Emit a voucher that called `withdrawEther(address,uint256)` on the `CartesiDApp` contract, with destination set to the application itself. - :::note environment variables - A `HistoryFactory` is deployed at `0x1f158b5320BBf677FdA89F9a438df99BbE560A26` for all supported networks, including Ethereum, Optimism, Arbitrum, Base, and their respective Sepolia-based testnets. - ::: +```javascript +// v1 — Ether withdrawal voucher +const call = encodeFunctionData({ + abi: CartesiDAppAbi, + functionName: "withdrawEther", + args: [receiver, amount], +}); -#### 2. Instantiate a New _History_ +const voucher = { + destination: applicationAddress, + payload: call, +}; +``` + +In SDK v2, `withdrawEther` is gone. Ether withdrawal vouchers send wei directly: the application contract `safeCall`s `destination` with `value`. -This is a two-step process. First calculate the address of the new History. After that, the new instance of History may be created. +- Set `destination` to the recipient. +- Set `payload` to empty (`zeroHash` / `0x`). +- Set `value` to the Wei amount as a 32-byte big-endian hex string **without** the `0x` prefix. -- To calculate the address of a new _History_ contract call the `calculateHistoryAddress(address,bytes32)(address)` function with the help of Foundry's Cast: +```javascript +// v2 — Ether withdrawal voucher +import { numberToHex, parseEther, zeroHash } from "viem"; - ```shell - cast call \ - --trace --verbose \ - $HISTORY_FACTORY_ADDRESS \ - "calculateHistoryAddress(address,bytes32)(address)" \ - $AUTHORITY_ADDRESS \ - $SALT \ - --rpc-url "$RPC_URL" - ``` +const voucher = { + destination: receiver, + payload: zeroHash, + value: numberToHex(BigInt(parseEther("1"))).slice(2), +}; +``` - If the command executes successfully, it will display the address of the new History contract. Store this address in the environment variable `NEW_HISTORY_ADDRESS` for later use. +See [asset handling](../development/asset-handling.md#withdrawing-tokens) and the [ether wallet tutorial](../tutorials/ether-wallet.md). -- Create a new instance of _History_ may be created by calling function `newHistory(address,bytes32)`: +--- - ```shell - cast send \ - --json \ - --mnemonic "$MNEMONIC" \ - $HISTORY_FACTORY_ADDRESS \ - "newHistory(address,bytes32)(History)" \ - $AUTHORITY_ADDRESS \ - $SALT \ - --rpc-url "$RPC_URL" - ``` +## Cartesi Machine image - The `cast send` command will fail if Cast does not recognize the _History_ type during execution. In such cases, replace _History_ with `address` as the return type for `newHistory()` and execute the command again. +The application still runs inside a Cartesi Machine. The guest-tools package that provides the rollup HTTP loop was renamed and versioned independently of the node. -The `cast send` command may also fail due to gas estimation issues. To circumvent this, provide gas constraints with the `--gas-limit` parameter (e.g., `--gas-limit 7000000`). +| | v1.5 | v2.0-alpha | +| :-- | :-- | :-- | +| Guest tools | `machine-emulator-tools` (typically `0.14.1`) | `machine-guest-tools` (typically `0.17.2` with node `alpha.12`) | +| Typical base | Ubuntu Jammy RISC-V images | Ubuntu Noble RISC-V images | +| Node emulator (released) | Emulator SDK 0.17.x | Emulator `v0.20.0` ([rollups-node#720](https://github.com/cartesi/rollups-node/pull/720)) | -#### 3. Replace the _History_ +The machine snapshot (template hash) must match the hash registered with the application contract and the node. Rebuilding against a different emulator or guest-tools version produces a different hash. -Ensure the environment variables from the previous step are set, including `NEW_HISTORY_ADDRESS`, which should have the address of the new History. +### Building for SDK 2.0 -To replace the _History_ used by the _Authority_, run this command: +Do not retrofit a v1.5 Dockerfile. Start the application from scratch with **Cartesi CLI 2.0** (currently alpha) and the **prerelease application templates**. Those templates are the source of truth for the v2 image layout. ```shell -cast send \ - --json \ - --mnemonic "$MNEMONIC" \ - "$AUTHORITY_ADDRESS" \ - "setHistory(address)" \ - "$NEW_HISTORY_ADDRESS" \ - --rpc-url "$RPC_URL" +cartesi create my-dapp --template javascript --branch prerelease/sdk-12 +``` + +`--branch` selects a branch of [cartesi/application-templates](https://github.com/cartesi/application-templates/tree/prerelease/sdk-12). `prerelease/sdk-12` is the CLI 2.0 default. Then port application logic into the new project and run `cartesi build`. + +:::caution Next emulator line +[`rollups-node#791`](https://github.com/cartesi/rollups-node/pull/791) (merged, **not in a node release yet**) bumps the node to machine-emulator `v0.21.0` and machine-guest-tools `v0.18.0`. After that ships, rebuild the image with matching guest tools before registering it. +::: + +--- + +## Outputs + +In SDK v1, the only verifiable outputs were notices and vouchers. Each type lived in a separate buffer inside the machine and in a separate Merkle tree in the proof. Adding or changing output types cascaded through the whole SDK. + +In SDK v2, notices and vouchers share one buffer and one proof tree (**output unification**). An output is an arbitrary byte array encoded as a Solidity function call, so the type is the function selector. Any output can be validated, not only notices. A new executable type, the **DELEGATECALL voucher**, was added. + +The `Application` contract API changed accordingly. The following subsections match the [rollups-contracts v1→v2 wiki](https://github.com/cartesi/rollups-contracts/wiki/Migration-Guide-(v1%E2%86%92v2)#outputs). + +| Action | v1 | v2 | +| :----- | :-- | :-- | +| Validate | `validateNotice(bytes notice, Proof proof)` | `validateOutput(bytes output, OutputValidityProof proof)` | +| Execute | `executeVoucher(address destination, bytes payload, Proof proof)` | `executeOutput(bytes output, OutputValidityProof proof)` | +| Execution check | `wasVoucherExecuted(uint256 inputIndex, uint256 outputIndex)` | `wasOutputExecuted(uint256 outputIndex)` | +| Execution event | `VoucherExecuted(uint256 voucherId)` | `OutputExecuted(uint64 outputIndex, bytes output)` | + +On contracts v3, do not treat a voucher as executable until the epoch status is `CLAIM_ACCEPTED`. `CLAIM_SUBMITTED` and `CLAIM_STAGED` are not enough. See [`rollups-contracts#514`](https://github.com/cartesi/rollups-contracts/pull/514) and [`rollups-node#779`](https://github.com/cartesi/rollups-node/pull/779). + +### Encoding + +Outputs are ABI-encoded Solidity function calls. Supported signatures are on the [`Outputs` interface](https://github.com/cartesi/rollups-contracts/blob/v2.0.1/src/common/Outputs.sol). Decode them with any Ethereum ABI library (for example viem). Selectors: + +| Selector | Kind | Encoded as | +| :------------ | :---------- | :-- | +| `0xc258d6e5` | Notice | `Notice(bytes payload)` | +| `0x237a816f` | Voucher (`CALL`) | `Voucher(address destination, uint256 value, bytes payload)` | +| `0x10321e8b` | DelegateCall voucher | `DelegateCallVoucher(address destination, bytes payload)` | + +The JSON-RPC `raw_data` field is this encoded blob. Pass it as `output` to `validateOutput` and `executeOutput`. `decoded_data.type` on the node is the same selector. + +The `value` field on a `CALL` voucher is the Wei forwarded with the call. It is also how Ether withdrawals work, and it can fund payable functions. + +### Proofs + +The proof type changed. Application code should use the proof the node returns with the output, not construct one. + +SDK v1 used a nested `Proof` / `OutputValidityProof` with per-type epoch roots, input index within the epoch, and two sibling arrays: + +```solidity +struct Proof { + OutputValidityProof validity; + bytes context; +} + +struct OutputValidityProof { + uint64 inputIndexWithinEpoch; + uint64 outputIndexWithinInput; + bytes32 outputHashesRootHash; + bytes32 vouchersEpochRootHash; + bytes32 noticesEpochRootHash; + bytes32 machineStateHash; + bytes32[] outputHashInOutputHashesSiblings; + bytes32[] outputHashesInEpochSiblings; +} +``` + +SDK v2 uses a single, simpler structure. Outputs are identified by a global, ever-increasing `outputIndex` (they are not keyed by input index): + +```solidity +struct OutputValidityProof { + uint64 outputIndex; + bytes32[] outputHashesSiblings; +} +``` + +### Validation + +SDK v1 could validate only notices, and `validateNotice` returned `bool`: + +```solidity +function validateNotice( + bytes calldata notice, + Proof calldata proof +) external view returns (bool success); +``` + +SDK v2 validates any output. `output` is the Solidity-encoded function call. There is no Boolean return: the call succeeds or it reverts. + +```solidity +function validateOutput( + bytes calldata output, + OutputValidityProof calldata proof +) external view; +``` + +### Execution + +SDK v1 executed only `CALL` vouchers and returned `bool`: + +```solidity +function executeVoucher( + address destination, + bytes calldata payload, + Proof calldata proof +) external returns (bool success); ``` -In SDK v2, we modified the ERC-20 portal to only accept successful transactions. With this change, the success field would always be true, so it has been removed: +SDK v2 executes `CALL` and `DELEGATECALL` vouchers through one function. Again, `output` is the encoded function call, and the call reverts on failure instead of returning `false`. + +```solidity +function executeOutput( + bytes calldata output, + OutputValidityProof calldata proof +) external; +``` + +### Execution event + +SDK v1 emitted `VoucherExecuted` with an opaque `voucherId` (input index packed with output index within that input): + +```solidity +event VoucherExecuted(uint256 voucherId); +``` + +SDK v2 emits `OutputExecuted` with the global output index and the encoded output bytes: + +```solidity +event OutputExecuted(uint64 outputIndex, bytes output); +``` + +Update event listeners from `VoucherExecuted` to `OutputExecuted`. Index by `outputIndex`, not by `(inputIndex, outputIndexWithinInput)`. + +### Execution check + +SDK v1 required both the input index and the output index within that input: + +```solidity +function wasVoucherExecuted( + uint256 inputIndex, + uint256 outputIndexWithinInput +) external view returns (bool executed); +``` + +SDK v2 only needs the output index: + +```solidity +function wasOutputExecuted( + uint256 outputIndex +) external view returns (bool executed); +``` + +--- + +## JSON-RPC queries + +In SDK v1, notices, vouchers, and reports were queried through GraphQL at `/graphql`. + +```javascript +// v1 — query notices via GraphQL +const response = await fetch("http://localhost:8080/graphql", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + query: `{ notices { edges { node { index input { index } payload } } } }`, + }), +}); +``` + +In SDK v2, GraphQL is removed. POST JSON-RPC 2.0 to the node's **`/rpc`** path (not the node root). The host and port depend on how the node is exposed. + +```javascript +// v2 — list outputs (notices + vouchers) via JSON-RPC +const response = await fetch("http://localhost:10011/rpc", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + jsonrpc: "2.0", + method: "cartesi_listOutputs", + params: { application: "0xYourAppAddress", limit: 50, offset: 0 }, + id: 1, + }), +}); +const { result } = await response.json(); +``` + +```javascript +// v2 — get a specific output by index +await fetch("http://localhost:10011/rpc", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + jsonrpc: "2.0", + method: "cartesi_getOutput", + params: { application: "0xYourAppAddress", output_index: "0x0" }, + id: 1, + }), +}); +``` + +Each output has a `decoded_data.type` selector: + +| Type selector | Output kind | +| :------------ | :---------- | +| `0xc258d6e5` | Notice | +| `0x237a816f` | Voucher | +| `0x10321e8b` | DelegateCall Voucher | + +`raw_data` is the ABI-encoded bytes for `executeOutput()` / `validateOutput()`. + +Reports **are** on JSON-RPC (`cartesi_listReports`, `cartesi_getReport`). They are also returned inline on inspect responses. + +GraphQL → JSON-RPC map: + +| v1 GraphQL | v2 JSON-RPC | +| :-- | :-- | +| `notices` / `vouchers` | `cartesi_listOutputs` / `cartesi_getOutput` | +| `reports` | `cartesi_listReports` / `cartesi_getReport` | +| `inputs` | `cartesi_listInputs` / `cartesi_getInput` | +| — | `cartesi_listApplications` / `cartesi_getApplication` | +| — | `cartesi_listEpochs` / `cartesi_getEpoch` / `cartesi_getLastAcceptedEpochIndex` | +| — | `cartesi_getChainId` / `cartesi_getNodeVersion` | + +On node `v2.0.0-alpha.12` (contracts v3), also: + +| Method | Use | +| :-- | :-- | +| `cartesi_listWithdrawals` / `cartesi_getWithdrawal` | Emergency L1 withdrawals after foreclosure — **not** voucher withdrawals | +| `cartesi_listTournaments`, `cartesi_getTournament`, `cartesi_listMatches`, … | PRT / Dave data | + +`cartesi_getApplication` on contracts v3 returns `enabled` plus `status` (`OK`, `FAILED`, `INOPERABLE` / `DIVERGED` / `CORRUPTED`, `FORECLOSED`). Do not read a single `state: ENABLED` field from older examples. + +From [`rollups-node#789`](https://github.com/cartesi/rollups-node/pull/789) (merged after `alpha.12`): inputs are identified by `transaction_hash` + `log_index` (multiple `InputAdded` logs in one L1 transaction are distinct). `cartesi_listInputs` accepts `transaction_hash`. There is no `transaction_reference`. + +Unknown application errors use a dedicated JSON-RPC code ([`rollups-node#783`](https://github.com/cartesi/rollups-node/pull/783)). + +The node's EVM reader now **polls HTTP** for new blocks ([`rollups-node#781`](https://github.com/cartesi/rollups-node/pull/781)). A WebSocket blockchain endpoint is no longer required for the reader. + +:::caution Open JSON-RPC work +[`rollups-node#793`](https://github.com/cartesi/rollups-node/pull/793) (open) adds batch requests, index ranges, multi-status epoch filters, executed/pending output counts, `cartesi_getNodeInfo`, and renames `cartesi_getMatchAdvanced` → `cartesi_getMatchAdvance`. Do not treat those methods as released until that PR merges and a node alpha ships. +::: + +Full method list: [JSON-RPC methods](../api-reference/jsonrpc/methods.md). Spec source: [`internal/jsonrpc/jsonrpc-discover.json` on `next/2.0`](https://github.com/cartesi/rollups-node/blob/next/2.0/internal/jsonrpc/jsonrpc-discover.json). + +--- + +## Inspect calls + +In SDK v1, inspect was an HTTP GET with the payload in the URL path: + +```javascript +// v1 — inspect via GET +const response = await fetch( + `http://localhost:8080/inspect/${encodeURIComponent(payload)}` +); +``` + +In SDK v2, inspect is HTTP POST to `/inspect/` with the payload in the body. The application must be in the path because one node can host several apps. + +```javascript +// v2 — inspect via POST +const response = await fetch(`http://localhost:10012/inspect/0xYourAppAddress`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(payload), +}); +const result = await response.json(); +``` + +The OpenAPI spec also accepts `application/octet-stream` for a binary body ([`api/openapi/inspect.yaml` on `next/2.0`](https://github.com/cartesi/rollups-node/blob/next/2.0/api/openapi/inspect.yaml)). + +The response is still a list of reports with hex payloads, plus `status`, `exception_payload`, and `processed_input_count`. + +Inspect is served from a temporary machine fork and is synchronous. It returns **503** when the machine is not ready, inspect capacity is exhausted, or the application was **foreclosed** (`Application was foreclosed; machine unavailable`). Body size is limited ([`rollups-node#761`](https://github.com/cartesi/rollups-node/pull/761)). + +--- + +## TypeScript applications + +v1.5 frontends typically called GraphQL directly. v2 TypeScript clients should use the packages in [cartesi/rollups-ts](https://github.com/cartesi/rollups-ts/tree/prerelease/v2-alpha) (`prerelease/v2-alpha`). They wrap the JSON-RPC node API, InputBox, and output execution. + +| Role | Earlier v2-alpha name | Current package | +| :-- | :-- | :-- | +| JSON-RPC typed client | `@cartesi/rpc` | [`@cartesi/rpc`](https://github.com/cartesi/rollups-ts/tree/prerelease/v2-alpha/packages/rpc) | +| viem L1 / node helpers | `@cartesi/viem` | [`@cartesi/client`](https://github.com/cartesi/rollups-ts/tree/prerelease/v2-alpha/packages/client) | +| React / wagmi hooks | `@cartesi/wagmi` | [`@cartesi/react`](https://github.com/cartesi/rollups-ts/tree/prerelease/v2-alpha/packages/react) | +| Input/output codec | — | [`@cartesi/codec`](https://github.com/cartesi/rollups-ts/tree/prerelease/v2-alpha/packages/codec) | + +Replace `@cartesi/viem` imports with `@cartesi/client` and `@cartesi/wagmi` with `@cartesi/react`. Pin explicit alpha versions; the `@alpha` npm tag can resolve to an older prerelease. + +:::note +See [rollups-ts#123](https://github.com/cartesi/rollups-ts/pull/123) and [#124](https://github.com/cartesi/rollups-ts/pull/124) for RPC type updates against the node API. Component layout for a React app is in the [React frontend tutorial](../tutorials/react-frontend-application.md); that page may still show the earlier package names. +::: -When the Cartesi Rollups Node restarts, it processes all existing inputs, recalculates the epochs, and sends the claims to the new _History_ based on the updated configuration. diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/calculator.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/calculator.md index 6927dac7d..412987ab0 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/calculator.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/calculator.md @@ -6,6 +6,8 @@ resources: title: Source code for the Calculator App --- + + In this tutorial, we will build a simple Calculator application to illustrate how requests are sent and processed within Cartesi Rollups Infrastructure. We provide JavaScript, Python, Rust, Go, and C++ implementations so you can use your preferred backend language. diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/counter.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/counter.md index 1d7327e4b..b03386393 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/counter.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/counter.md @@ -6,6 +6,8 @@ resources: title: Source code for the Counter Application --- + + This tutorial aims to guide you through creating and interacting with a basic Cartesi application, it'll take you through setting up your dev environment, creating a project then finally running and interacting with your application locally. We provide Rust, JavaScript, Python, Go, and C++ implementations of the application, so you can choose whichever language you're more comfortable with. diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-1155-token-wallet.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-1155-token-wallet.md index db012be56..faf72a2ca 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-1155-token-wallet.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-1155-token-wallet.md @@ -3,6 +3,8 @@ id: erc-1155-token-wallet title: Integrating ERC1155 token wallet functionality --- + + This tutorial guides you through building an ERC-1155 token wallet for a Cartesi backend application using TypeScript. It covers **single** and **batch** deposits from the base layer, internal balance tracking, transfers, and withdrawals for both modes. ## Setting up the project diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-20-token-wallet.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-20-token-wallet.md index 7d6c1c84f..b21f4e91d 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-20-token-wallet.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-20-token-wallet.md @@ -3,6 +3,8 @@ id: erc-20-token-wallet title: Integrating ERC20 token wallet functionality --- + + This tutorial will guide you through creating a basic ERC20 token wallet for a Cartesi backend application using TypeScript. ## Setting up the project diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-721-token-wallet.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-721-token-wallet.md index 0c0c85308..0267195ba 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-721-token-wallet.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-721-token-wallet.md @@ -3,6 +3,8 @@ id: erc-721-token-wallet title: Integrating ERC721 token wallet functionality --- + + This tutorial will guide you through creating a basic ERC721(NFT) token wallet using TypeScript for a Cartesi backend application. ## Setting up the project diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/ether-wallet.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/ether-wallet.md index 6df01a44f..19bf0dff6 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/ether-wallet.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/ether-wallet.md @@ -3,6 +3,8 @@ id: ether-wallet title: Integrating Ether wallet functionality --- + + This tutorial will build a basic Ether wallet inside a Cartesi backend application using TypeScript. The goal is to have a backend application to track balances and receive, transfer, and withdraw Ether. diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/marketplace.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/marketplace.md index 7b08cfc9d..1e8e39ccd 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/marketplace.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/marketplace.md @@ -6,6 +6,8 @@ resources: title: Source code for the Marketplace Application --- + + In this tutorial we'll be building a simple NFT Marketplace application, where users are able to deposit a unique token to be sold at a fixed price, then other users are able to purchase and withdraw these purchased tokens to their wallet. This Tutorial is built using an Object oriented approach and aims to cover, application creation, Notice, Voucher and Report generation, we'll also be decoding and consuming the payload passed alongside advance and inspect requests. diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/react-frontend-application.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/react-frontend-application.md index 4d59c61e5..b1c978d79 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/react-frontend-application.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/react-frontend-application.md @@ -6,6 +6,8 @@ resources: title: Source code for the frontend application --- + + # Building a React Frontend for Cartesi Apps This is a comprehensive guide for building a React frontend that interacts with the deployed Cartesi applications using Cartesi TypeScript packages, wagmi hooks and viem library. diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/running-applications-on-a-forked-network.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/running-applications-on-a-forked-network.md index c942c6b74..0b5dc8b83 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/running-applications-on-a-forked-network.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/running-applications-on-a-forked-network.md @@ -4,6 +4,8 @@ title: Running applications on a forked network resources: --- + + ## Introduction When building Cartesi applications, it is often necessary to interact with contracts and services that are already deployed on a live blockchain network. While a local clean chain is useful during early development, it does not always reflect real world conditions. diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/utilizing-the-cli-AA-feature.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/utilizing-the-cli-AA-feature.md index 90add2236..7fb2e91ab 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/utilizing-the-cli-AA-feature.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/utilizing-the-cli-AA-feature.md @@ -9,6 +9,8 @@ resources: title: Account Abstraction Script demo --- + + This tutorial will guide you through utilizing the account abstraction (AA) feature of the CLI to interact with your application while testing locally. ## Introduction diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/utilizing-the-cli-test-tokens.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/utilizing-the-cli-test-tokens.md index a4be57d09..b360c8347 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/utilizing-the-cli-test-tokens.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/utilizing-the-cli-test-tokens.md @@ -4,6 +4,8 @@ title: Utilizing test tokens in dev environment resources: --- + + ## Introduction The **Cartesi CLI** is one of the most important tools for developing applications with Cartesi. It provides a wide range of functionalities that simplify and automate the process of setting up, deploying, and interacting with your applications. diff --git a/cartesi-rollups_versioned_sidebars/version-2.0-sidebars.json b/cartesi-rollups_versioned_sidebars/version-2.0-sidebars.json index 6d50904f8..a70320c08 100644 --- a/cartesi-rollups_versioned_sidebars/version-2.0-sidebars.json +++ b/cartesi-rollups_versioned_sidebars/version-2.0-sidebars.json @@ -248,8 +248,7 @@ "items": [ "resources/community-tools", "resources/mainnet-considerations", - "resources/migration-guide", - "resources/integration-guides" + "resources/migration-guide" ] }, { From f589a5e56f890c95f82754aa01637d3dfcd8cb67 Mon Sep 17 00:00:00 2001 From: Shaheen Date: Mon, 24 Aug 2026 14:05:17 +0530 Subject: [PATCH 2/4] docs(v2): align contracts API with rollups-contracts v3.0.0-alpha.9 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 --- .../backend/emergency-withdrawal.md | 2 +- .../api-reference/backend/vouchers.md | 4 +- .../contracts/application-factory.md | 68 +++- .../api-reference/contracts/application.md | 311 ++++++++---------- .../contracts/consensus/abstract-consensus.md | 42 +-- .../consensus/authority/authority-factory.md | 41 ++- .../consensus/authority/authority.md | 53 ++- .../consensus/authority/iauthority-factory.md | 89 +---- .../consensus/authority/iauthority.md | 4 +- .../contracts/consensus/iconsensus.md | 238 ++++++++++---- .../ioutputs-merkle-root-validator.md | 40 ++- .../contracts/consensus/overview.md | 21 +- .../consensus/quorum/iquorum-factory.md | 89 +---- .../contracts/consensus/quorum/iquorum.md | 10 +- .../consensus/quorum/quorum-factory.md | 45 ++- .../contracts/consensus/quorum/quorum.md | 139 ++------ .../api-reference/contracts/input-box.md | 2 +- .../api-reference/contracts/overview.md | 8 +- .../contracts/portals/ERC20Portal.md | 32 -- ...55BatchPortal.md => Erc1155BatchPortal.md} | 20 +- ...SinglePortal.md => Erc1155SinglePortal.md} | 19 +- .../contracts/portals/Erc20Portal.md | 49 +++ .../{ERC721Portal.md => Erc721Portal.md} | 18 +- .../contracts/portals/EtherPortal.md | 13 +- .../withdrawal/iwithdrawal-output-builder.md | 14 +- .../contracts/withdrawal/overview.md | 5 +- .../usd-withdrawal-output-builder-factory.md | 8 +- .../usd-withdrawal-output-builder.md | 18 +- .../contracts/withdrawal/withdrawal-config.md | 4 +- .../version-2.0/api-reference/index.md | 2 +- .../version-2.0/deployment/introduction.md | 9 +- .../deployment/self-hosted/standard.md | 16 +- .../version-2.0/development/asset-handling.md | 8 +- .../getting-started/architecture.md | 8 +- .../tutorials/erc-1155-token-wallet.md | 4 +- .../tutorials/erc-20-token-wallet.md | 16 +- .../tutorials/erc-721-token-wallet.md | 16 +- .../tutorials/snippets/marketplace-js.md | 4 +- .../tutorials/snippets/marketplace-py.md | 4 +- .../utilizing-the-cli-test-tokens.md | 34 +- .../version-2.0-sidebars.json | 8 +- 41 files changed, 741 insertions(+), 794 deletions(-) delete mode 100644 cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC20Portal.md rename cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/{ERC1155BatchPortal.md => Erc1155BatchPortal.md} (51%) rename cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/{ERC1155SinglePortal.md => Erc1155SinglePortal.md} (52%) create mode 100644 cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/Erc20Portal.md rename cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/{ERC721Portal.md => Erc721Portal.md} (51%) diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/emergency-withdrawal.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/emergency-withdrawal.md index 18f05ea24..518b38b27 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/emergency-withdrawal.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/emergency-withdrawal.md @@ -25,7 +25,7 @@ The [`WithdrawalConfig`](../contracts/withdrawal/withdrawal-config.md) describes - `log2MaxNumOfAccounts` sets how many accounts fit (the tree depth); - `log2LeavesPerAccount` sets each record's size, which is `2^(5 + log2LeavesPerAccount)` bytes. -For the single-token case (see [`UsdWithdrawalOutputBuilder`](../contracts/withdrawal/usd-withdrawal-output-builder.md)), each record is 32 bytes: an 8-byte little-endian balance, followed by the 20-byte owner address, followed by padding. +For the single-token case (see [`UsdWithdrawalOutputBuilder`](../contracts/withdrawal/usd-withdrawal-output-builder.md)), each record is exactly 32 bytes: a 12-byte little-endian `uint96` balance, followed by the 20-byte owner address (no tail padding). ## Creating the accounts drive diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/vouchers.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/vouchers.md index b273900a9..e1fac95a8 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/vouchers.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/vouchers.md @@ -311,7 +311,7 @@ const abi = [ "function safeTransfer(address,address,uint256)" ]; -async function emitSafeERC20Transfer(token, to, amount) { +async function emitSafeErc20Transfer(token, to, amount) { const call = encodeFunctionData({ abi, functionName: "safeTransfer", @@ -424,7 +424,7 @@ import ( "github.com/ethereum/go-ethereum/common" ) -func emitSafeERC20Transfer(token, to common.Address, amount *big.Int) error { +func emitSafeErc20Transfer(token, to common.Address, amount *big.Int) error { abiJSON := `[{ "type":"function", "name":"safeTransfer", diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application-factory.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application-factory.md index 785de1272..2edfb0e85 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application-factory.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application-factory.md @@ -2,20 +2,34 @@ id: application-factory title: ApplicationFactory resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/dapp/ApplicationFactory.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/dapp/ApplicationFactory.sol title: Application Factory contract + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/dapp/IApplicationFactory.sol + title: IApplicationFactory interface --- The **ApplicationFactory** contract is a tool for reliably deploying new instances of the [`Application`](../contracts/application.md) contract with or without a specified salt value for address derivation. -Additionally, it provides a function to calculate the address of a potential new `CartesiDApp` contract based on input parameters. +Additionally, it provides a function to calculate the address of a potential new `Application` contract based on input parameters. -This contract ensures efficient and secure deployment of `Application` contracts within the Cartesi Rollups framework. +The factory takes an [`IRefundOutputBuilder`](https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/refund/IRefundOutputBuilder.sol) in its constructor. That refund builder is a factory-wide immutable: every application deployed by this factory shares it, and it is not part of `WithdrawalConfig` or of `newApplication` parameters. ## Functions +### `constructor()` + +```solidity +constructor(IRefundOutputBuilder refundOutputBuilder) +``` + +**Parameters** + +| Name | Type | Description | +|------|------|-------------| +| `refundOutputBuilder` | `IRefundOutputBuilder` | Factory-wide builder used for deposit refunds after foreclosure | + ### `newApplication()` ```solidity @@ -23,7 +37,7 @@ function newApplication( IOutputsMerkleRootValidator outputsMerkleRootValidator, address appOwner, bytes32 templateHash, - bytes calldata dataAvailability, + IInputBox inputBox, WithdrawalConfig calldata withdrawalConfig ) external override returns (IApplication) ``` @@ -37,7 +51,7 @@ Deploys a new Application contract without a salt value for address derivation. | `outputsMerkleRootValidator` | `IOutputsMerkleRootValidator` | The initial outputs Merkle root validator contract | | `appOwner` | `address` | Address of the owner of the application | | `templateHash` | `bytes32` | Hash of the template for the application | -| `dataAvailability` | `bytes` | The data availability solution | +| `inputBox` | `IInputBox` | The input box contract | | `withdrawalConfig` | `WithdrawalConfig` | The withdrawal configuration (see [WithdrawalConfig](./withdrawal/withdrawal-config.md)). Pass a zero-valued config to deploy without emergency withdrawal | **Return Values** @@ -53,7 +67,7 @@ function newApplication( IOutputsMerkleRootValidator outputsMerkleRootValidator, address appOwner, bytes32 templateHash, - bytes calldata dataAvailability, + IInputBox inputBox, WithdrawalConfig calldata withdrawalConfig, bytes32 salt ) external override returns (IApplication) @@ -68,7 +82,7 @@ Deploys a new `Application` contract with a specified salt value for address der | `outputsMerkleRootValidator` | `IOutputsMerkleRootValidator` | The initial outputs Merkle root validator contract | | `appOwner` | `address` | Address of the owner of the application | | `templateHash` | `bytes32` | Hash of the template for the application | -| `dataAvailability` | `bytes` | The data availability solution | +| `inputBox` | `IInputBox` | The input box contract | | `withdrawalConfig` | `WithdrawalConfig` | The withdrawal configuration (see [WithdrawalConfig](./withdrawal/withdrawal-config.md)). Pass a zero-valued config to deploy without emergency withdrawal | | `salt` | `bytes32` | Salt value for address derivation | @@ -85,7 +99,7 @@ function calculateApplicationAddress( IOutputsMerkleRootValidator outputsMerkleRootValidator, address appOwner, bytes32 templateHash, - bytes calldata dataAvailability, + IInputBox inputBox, WithdrawalConfig calldata withdrawalConfig, bytes32 salt ) external view override returns (address) @@ -100,7 +114,7 @@ Calculates the address of a potential new Application contract based on input pa | `outputsMerkleRootValidator` | `IOutputsMerkleRootValidator` | The initial outputs Merkle root validator contract | | `appOwner` | `address` | Address of the owner of the application | | `templateHash` | `bytes32` | Hash of the template for the application | -| `dataAvailability` | `bytes` | The data availability solution | +| `inputBox` | `IInputBox` | The input box contract | | `withdrawalConfig` | `WithdrawalConfig` | The withdrawal configuration (see [WithdrawalConfig](./withdrawal/withdrawal-config.md)). Pass a zero-valued config to deploy without emergency withdrawal | | `salt` | `bytes32` | Salt value for address derivation | @@ -110,16 +124,24 @@ Calculates the address of a potential new Application contract based on input pa |------|------|-------------| | `[0]` | `address` | Address of the potential new Application contract | +### `version()` + +```solidity +function version() external view returns (string memory) +``` + +Return the rollups-contracts package version string. + ## Events ### `ApplicationCreated()` ```solidity event ApplicationCreated( - IOutputsMerkleRootValidator outputsMerkleRootValidator, + IOutputsMerkleRootValidator indexed outputsMerkleRootValidator, address appOwner, bytes32 templateHash, - bytes dataAvailability, + IInputBox inputBox, WithdrawalConfig withdrawalConfig, IApplication appContract ) @@ -134,8 +156,8 @@ A new Application contract was deployed. | `outputsMerkleRootValidator` | `IOutputsMerkleRootValidator` | The outputs Merkle root validator contract | | `appOwner` | `address` | The owner of the application | | `templateHash` | `bytes32` | The template hash | -| `dataAvailability` | `bytes` | The data availability solution | -| `withdrawalConfig` | `WithdrawalConfig` | The withdrawal configuration (see [WithdrawalConfig](./withdrawal/withdrawal-config.md)). Pass a zero-valued config to deploy without emergency withdrawal | +| `inputBox` | `IInputBox` | The input box contract | +| `withdrawalConfig` | `WithdrawalConfig` | The withdrawal configuration | | `appContract` | `IApplication` | The deployed Application contract | ## Errors @@ -148,8 +170,20 @@ error InvalidWithdrawalConfig(WithdrawalConfig withdrawalConfig) Raised at deployment when the provided [`WithdrawalConfig`](./withdrawal/withdrawal-config.md) is invalid, meaning its accounts-drive layout does not fit inside the machine memory (see [`LibWithdrawalConfig.isValid`](./withdrawal/withdrawal-config.md#validation)). Checking the config in the factory means users and the node do not have to check it themselves. -**Parameters** +## Self-hosted factory -| Name | Type | Description | -|------|------|-------------| -| `withdrawalConfig` | `WithdrawalConfig` | The invalid withdrawal configuration | +[`ISelfHostedApplicationFactory`](https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/dapp/ISelfHostedApplicationFactory.sol) deploys an Authority + Application pair in one transaction. + +```solidity +function deployContracts( + address authorityOwner, + uint256 epochLength, + uint256 claimStagingPeriod, + bytes32 templateHash, + IInputBox inputBox, + WithdrawalConfig calldata withdrawalConfig, + bytes32 salt +) external returns (IApplication, IAuthority); +``` + +There is no `appOwner` parameter: the factory deploys the application under its own ownership and immediately renounces it, so self-hosted applications are ownerless and cannot migrate to another outputs Merkle root validator after deployment. `calculateAddresses` takes the same arguments (without returning ownership control). diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application.md index 6049486ce..46e5a0dd4 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application.md @@ -2,8 +2,10 @@ id: application title: Application resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/dapp/Application.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/dapp/Application.sol title: Application contract + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/dapp/IApplication.sol + title: IApplication interface - url: https://docs.openzeppelin.com/contracts/5.x/ title: OpenZeppelin Contracts --- @@ -12,9 +14,11 @@ resources: The **Application** contract serves as the base layer representation of the application running on the execution layer. The application can interact with other smart contracts through the execution and validation of outputs. These outputs, generated by the application backend on the execution layer, can be proven in the base layer through claims submitted by a consensus contract. -Every Application is subscribed to a consensus contract and governed by a single address (owner). The consensus has the authority to submit claims, which are then used to validate outputs. The owner has complete control over the Application and can replace the consensus at any time. Consequently, users of an Application must trust both the consensus and the application owner. Depending on centralization or ownership concerns, the ownership model can be modified. This process is managed by the consensus contract. For more information about different ownership and consensus models, refer to the [consensus contracts](./consensus/overview.md). +Every Application is subscribed to a consensus contract (an outputs Merkle root validator) and may be governed by a single address (owner). The consensus has the authority to accept claims, which are then used to validate outputs. The owner can replace the outputs Merkle root validator, but only in the deployment block. Consequently, users of an Application must trust both the consensus and the application owner. Depending on centralization or ownership concerns, the ownership model can be modified. For more information about different ownership and consensus models, refer to the [consensus contracts](./consensus/overview.md). -An Application may optionally be deployed with a [`WithdrawalConfig`](./withdrawal/withdrawal-config.md) that turns on **foreclosure and emergency withdrawal**. A chosen **guardian** can foreclose the application. Once it is foreclosed, users can withdraw their in-app balances straight from this contract by proving their accounts against the last-finalized machine state, without a running node. See [Foreclosure & Emergency Withdrawal](../../development/emergency-withdrawal/overview.md) for the full flow. These functions are documented below under [Guardian & Foreclosure](#guardian--foreclosure) and [Emergency Withdrawal](#emergency-withdrawal). +An Application may optionally be deployed with a [`WithdrawalConfig`](./withdrawal/withdrawal-config.md) that turns on **foreclosure and emergency withdrawal**. A chosen **guardian** can foreclose the application. Once it is foreclosed, users can withdraw their in-app balances straight from this contract by proving their accounts against the last-finalized machine state, without a running node. After foreclosure, users can also **refund** unprocessed deposits through `issueRefund`. See [Foreclosure & Emergency Withdrawal](../../development/emergency-withdrawal/overview.md) for the full flow. + +All foreclosure, withdrawal, and refund APIs live on `IApplication` (there are no separate `IApplicationForeclosure` / `IApplicationWithdrawal` interfaces). ## Functions @@ -25,14 +29,15 @@ constructor( IOutputsMerkleRootValidator outputsMerkleRootValidator, address initialOwner, bytes32 templateHash, - bytes memory dataAvailability, + IInputBox inputBox, + IRefundOutputBuilder refundOutputBuilder, WithdrawalConfig memory withdrawalConfig ) Ownable(initialOwner) ``` Creates an Application contract. -*Reverts with `InvalidWithdrawalConfig` if `withdrawalConfig` is invalid (see [`WithdrawalConfig`](./withdrawal/withdrawal-config.md)). A zero-valued `withdrawalConfig` is valid and deploys an application without the foreclosure / emergency-withdrawal feature.* +*Reverts with `InvalidWithdrawalConfig` if `withdrawalConfig` is invalid (see [`WithdrawalConfig`](./withdrawal/withdrawal-config.md)). A zero-valued `withdrawalConfig` is valid and deploys an application without the foreclosure / emergency-withdrawal feature. When deploying through [`ApplicationFactory`](./application-factory.md), the refund output builder is a factory-wide immutable and is not passed to `newApplication`.* **Parameters** @@ -41,7 +46,8 @@ Creates an Application contract. | `outputsMerkleRootValidator` | `IOutputsMerkleRootValidator` | The initial outputs Merkle root validator contract | | `initialOwner` | `address` | The initial application owner | | `templateHash` | `bytes32` | The initial machine state hash | -| `dataAvailability` | `bytes` | The data availability solution | +| `inputBox` | `IInputBox` | The input box contract used by the application | +| `refundOutputBuilder` | `IRefundOutputBuilder` | Builds refund outputs for unprocessed deposits after foreclosure | | `withdrawalConfig` | `WithdrawalConfig` | The withdrawal configuration (guardian, accounts-drive layout, and output builder). See [`WithdrawalConfig`](./withdrawal/withdrawal-config.md) | ### `receive()` @@ -57,12 +63,12 @@ Accept Ether transfers. ### `executeOutput()` ```solidity -function executeOutput(bytes calldata output, OutputValidityProof calldata proof) external override nonReentrant +function executeOutput(bytes calldata output, OutputValidityProof calldata proof) external override ``` Execute an output. -*On a successful execution, emits an OutputExecuted event.* +*On a successful execution, emits an `OutputExecuted` event. Uses checks-effects-interactions (no reentrancy guard): `wasOutputExecuted` returns `true` and the event is emitted before the output is executed. Reverts with `TargetHasNoCode` when a voucher with a non-empty payload or a delegate-call voucher targets an account with no code.* **Parameters** @@ -79,7 +85,7 @@ function migrateToOutputsMerkleRootValidator(IOutputsMerkleRootValidator newOutp Migrate the application to a new outputs Merkle root validator. -*Can only be called by the application owner.* +*Can only be called by the application owner, and only in the block in which the application was deployed. Reverts with `NotDeploymentBlock` if called later, and with `Foreclosed` if the application has been foreclosed.* **Parameters** @@ -93,7 +99,7 @@ Migrate the application to a new outputs Merkle root validator. function wasOutputExecuted(uint256 outputIndex) external view override returns (bool) ``` -Check whether an output has been executed. +Check whether an output has been executed (or is currently being executed in the current transaction). **Parameters** @@ -115,7 +121,7 @@ function validateOutput(bytes calldata output, OutputValidityProof calldata proo Validate an output. -*May raise any of the errors raised by validateOutputHash.* +*May raise any of the errors raised by `validateOutputHash`.* **Parameters** @@ -132,7 +138,7 @@ function validateOutputHash(bytes32 outputHash, OutputValidityProof calldata pro Validate an output hash. -*May raise InvalidOutputHashesSiblingsArrayLength or InvalidOutputsMerkleRoot.* +*May raise `InvalidOutputHashesSiblingsArrayLength` or `InvalidOutputsMerkleRoot`.* **Parameters** @@ -149,12 +155,6 @@ function getTemplateHash() external view override returns (bytes32) Get the application's template hash. -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `bytes32` | The application's template hash | - ### `getOutputsMerkleRootValidator()` ```solidity @@ -163,25 +163,13 @@ function getOutputsMerkleRootValidator() external view override returns (IOutput Get the current outputs Merkle root validator. -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `IOutputsMerkleRootValidator` | The current outputs Merkle root validator | - -### `getDataAvailability()` +### `getInputBox()` ```solidity -function getDataAvailability() external view override returns (bytes memory) +function getInputBox() external view override returns (IInputBox) ``` -Get the data availability solution used by application. - -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `bytes` | Solidity ABI-encoded function call that describes the source of inputs that should be fed to the application. | +Get the input box contract used by the application. ### `getDeploymentBlockNumber()` @@ -189,67 +177,38 @@ Get the data availability solution used by application. function getDeploymentBlockNumber() external view override returns (uint256) ``` -Get number of block in which contract was deployed. - -**Return Values** +Get the number of the block in which the contract was deployed. -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `uint256` | The deployment block number | - -### `owner()` +### `getNumberOfExecutedOutputs()` ```solidity -function owner() public view override(IOwnable, Ownable) returns (address) +function getNumberOfExecutedOutputs() external view override returns (uint256) ``` -Returns the address of the current owner. - -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `address` | The address of the current owner | +Get the number of outputs executed by the application. -### `renounceOwnership()` +### `version()` ```solidity -function renounceOwnership() public override(IOwnable, Ownable) +function version() external view returns (string memory) ``` -Leaves the contract without owner. It will not be possible to call onlyOwner functions. Can only be called by the current owner. NOTE: Renouncing ownership will leave the contract without an owner, thereby disabling any functionality that is only available to the owner. +Return the rollups-contracts package version string. -### `transferOwnership()` +### `owner()` / `renounceOwnership()` / `transferOwnership()` -```solidity -function transferOwnership(address newOwner) public override(IOwnable, Ownable) -``` - -Transfers ownership of the contract to a new account (newOwner). Can only be called by the current owner. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `newOwner` | `address` | The new owner address | +Standard OpenZeppelin Ownable methods for reading and transferring ownership. ## Events ### `OutputExecuted()` ```solidity -event OutputExecuted(uint64 outputIndex, bytes output) +event OutputExecuted(uint64 indexed outputIndex, bytes output) ``` An output was executed from the Application. -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `outputIndex` | `uint64` | The index of the output | -| `output` | `bytes` | The output | - ### `OutputsMerkleRootValidatorChanged()` ```solidity @@ -258,15 +217,9 @@ event OutputsMerkleRootValidatorChanged(IOutputsMerkleRootValidator newOutputsMe The outputs Merkle root validator was changed. -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `newOutputsMerkleRootValidator` | `IOutputsMerkleRootValidator` | The new outputs Merkle root validator | - ## Guardian & Foreclosure -These members come from the [`IApplicationForeclosure`](https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/dapp/IApplicationForeclosure.sol) interface. They are only meaningful when the application was deployed with a non-empty [`WithdrawalConfig`](./withdrawal/withdrawal-config.md); the guardian is the address set in that configuration. +These members are only meaningful when the application was deployed with a non-empty [`WithdrawalConfig`](./withdrawal/withdrawal-config.md); the guardian is the address set in that configuration. ### `foreclose()` @@ -274,15 +227,16 @@ These members come from the [`IApplicationForeclosure`](https://github.com/carte function foreclose() external override onlyGuardian ``` -Forecloses the application, allowing users to withdraw their funds by providing Merkle proofs of their in-app accounts. +Forecloses the application, allowing users to withdraw their funds by providing Merkle proofs of their in-app accounts, and to refund unprocessed deposits. -*Can only be called by the application guardian. On success, emits a `Foreclosure` event. An application that has been foreclosed remains so.* +*Can only be called by the application guardian. On success, emits a `Foreclosure` event. Reverts with `Foreclosed` if the application has already been foreclosed (the event is emitted at most once).* **Errors** | Error | Condition | |-------|-----------| | `NotGuardian` | Called by an account other than the guardian | +| `Foreclosed` | The application has already been foreclosed | ### `getGuardian()` @@ -292,12 +246,6 @@ function getGuardian() external view override returns (address) Get the address of the guardian, which has the power to foreclose the application. -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `address` | The guardian address | - ### `isForeclosed()` ```solidity @@ -306,23 +254,97 @@ function isForeclosed() external view override returns (bool) Check whether the application has been foreclosed. An application that has been foreclosed will remain so. -**Return Values** +### `Foreclosure()` + +```solidity +event Foreclosure() +``` + +Triggered when the application is foreclosed. + +## Deposit Refunds + +After foreclosure, anyone can refund deposits that were never finalized. The application static-calls the factory-wide [`IRefundOutputBuilder`](https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/refund/IRefundOutputBuilder.sol) to build a transfer back to the original depositor for Ether, ERC-20, ERC-721, and ERC-1155 deposits made through the canonical portals. + +### `issueRefund()` + +```solidity +function issueRefund(uint256 inputIndex, bytes calldata input) external override +``` + +Issue a refund for an unprocessed input. + +*On success, marks the input as refunded, emits a `RefundIssued` event, and executes the refund output. A refund may fail if the depositor is a contract that does not accept the asset back (for example, no `receive` entrypoint or missing ERC-721/ERC-1155 receiver hooks).* + +**Parameters** | Name | Type | Description | |------|------|-------------| -| `[0]` | `bool` | Whether the application has been foreclosed | +| `inputIndex` | `uint256` | The index of the input in the application's input box | +| `input` | `bytes` | The input that was sent to the application | -### `Foreclosure()` +**Errors** + +| Error | Condition | +|-------|-----------| +| `CannotRefundFinalizedInput` | The input was already finalized | +| `RefundAlreadyIssued` | A refund was already issued for this input | +| `UnknownInputSender` | Non-deposit input or input from a non-canonical portal | +| Errors from `validateInput()` | The input fails validation | + +### `getRefundOutputBuilder()` ```solidity -event Foreclosure() +function getRefundOutputBuilder() external view override returns (IRefundOutputBuilder) ``` -Triggered when the application is foreclosed. +Get the refund output builder. + +### `getNumberOfIssuedRefunds()` + +```solidity +function getNumberOfIssuedRefunds() external view override returns (uint256) +``` + +Get the number of issued refunds (useful for fast-syncing `RefundIssued` events). + +### `wasRefundForInputIssued()` + +```solidity +function wasRefundForInputIssued(uint256 inputIndex) external view override returns (bool) +``` + +Check whether a refund has been issued for an input (or is currently being issued). + +### `validateInput()` + +```solidity +function validateInput(uint256 inputIndex, bytes calldata input) + external view override + returns (uint256 blockNumber, address inputSender, bytes memory inputPayload) +``` + +Validate an input against the application's input box and decode it. + +### `validateInputHash()` + +```solidity +function validateInputHash(uint256 inputIndex, bytes32 inputHash) external view override +``` + +Validate an input hash against the application's input box. + +### `RefundIssued()` + +```solidity +event RefundIssued(uint256 indexed inputIndex, bytes input, bytes output) +``` + +Triggered when a refund for an input is issued. ## Emergency Withdrawal -These members come from the [`IApplicationWithdrawal`](https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/dapp/IApplicationWithdrawal.sol) interface. After the application is foreclosed, its **accounts drive** (the in-app balance ledger) is proved on-chain once, and then each account's funds can be withdrawn permissionlessly. For the end-to-end procedure see the [recovery guide](../../development/emergency-withdrawal/recovery-guide.md); for the output-building contracts see the [Withdrawal](./withdrawal/overview.md) subsection. +After the application is foreclosed, its **accounts drive** (the in-app balance ledger) is proved on-chain once, and then each account's funds can be withdrawn permissionlessly. For the end-to-end procedure see the [recovery guide](../../development/emergency-withdrawal/recovery-guide.md); for the output-building contracts see the [Withdrawal](./withdrawal/overview.md) subsection. Withdrawal-related functions take an `AccountValidityProof`: @@ -342,17 +364,10 @@ function proveAccountsDriveMerkleRoot( ) external override ``` -Prove the accounts drive Merkle root against the last-finalized machine state provided by the application's outputs Merkle root validator. Callable by anyone after the application is foreclosed, so that accounts can be validated and their funds withdrawn. +Prove the accounts drive Merkle root against the last-finalized machine state provided by the application's outputs Merkle root validator. If that root is zero (no accepted claims yet), the application's template hash is used instead. Callable by anyone after the application is foreclosed. *On success, stores the proved accounts drive Merkle root and emits an `AccountsDriveMerkleRootProved` event.* -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `accountsDriveMerkleRoot` | `bytes32` | The accounts drive Merkle root | -| `proof` | `bytes32[]` | Siblings of the accounts drive Merkle root in the machine state tree | - **Errors** | Error | Condition | @@ -360,7 +375,7 @@ Prove the accounts drive Merkle root against the last-finalized machine state pr | `NotForeclosed` | The application has not been foreclosed | | `AccountsDriveMerkleRootAlreadyProved` | The root has already been proved | | `InvalidAccountsDriveMerkleRootProofSize` | The proof array length is wrong | -| `InvalidMachineMerkleRoot(bytes32)` | The computed machine root differs from the last-finalized one (argument is the computed root) | +| `InvalidMachineMerkleRoot(bytes32)` | The computed machine root differs from the expected one | ### `withdraw()` @@ -368,24 +383,17 @@ Prove the accounts drive Merkle root against the last-finalized machine state pr function withdraw(bytes calldata account, AccountValidityProof calldata proof) external override ``` -Withdraw the funds of an account from the foreclosed application. First the account is validated against the proved accounts drive Merkle root; then a withdrawal output is built from the account and executed. +Withdraw the funds of an account from the foreclosed application. -*On success, marks the account funds as withdrawn and emits a `Withdrawal` event.* - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `account` | `bytes` | The account, as encoded in the accounts drive | -| `proof` | `AccountValidityProof` | The proof used to validate the account | +*Uses checks-effects-interactions: `wereAccountFundsWithdrawn` returns `true` and the `Withdrawal` event is emitted before the output is executed.* **Errors** | Error | Condition | |-------|-----------| | `NotForeclosed` | The application has not been foreclosed | -| `AccountFundsAlreadyWithdrawn(uint64)` | The account's funds were already withdrawn (argument is the account index) | -| Errors from `validateAccount()` | The account fails validation (see [`validateAccount()`](#validateaccount)) | +| `AccountFundsAlreadyWithdrawn(uint64)` | The account's funds were already withdrawn | +| Errors from `validateAccount()` | The account fails validation | ### `getWithdrawalConfig()` @@ -405,13 +413,6 @@ function getAccountsDriveMerkleRoot() Check whether the accounts drive Merkle root was proved, and its value. -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `wasAccountsDriveMerkleRootProved` | `bool` | Whether the accounts drive Merkle root was proved | -| `accountsDriveMerkleRoot` | `bytes32` | The accounts drive Merkle root (if proved) | - ### `getNumberOfWithdrawals()` ```solidity @@ -426,37 +427,11 @@ Get the number of withdrawals. Useful for fast-syncing `Withdrawal` events. function wereAccountFundsWithdrawn(uint256 accountIndex) external view override returns (bool) ``` -Check whether an account had its funds withdrawn. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `accountIndex` | `uint256` | The index of the account in the accounts drive | - -### `getLog2LeavesPerAccount()` - -```solidity -function getLog2LeavesPerAccount() external view override returns (uint8) -``` - -Get the log (base 2) of the number of machine-state-tree leaves reserved for each account in the accounts drive. - -### `getLog2MaxNumOfAccounts()` - -```solidity -function getLog2MaxNumOfAccounts() external view override returns (uint8) -``` - -Get the log (base 2) of the maximum number of accounts the accounts drive can store (the depth of the accounts drive tree). +Check whether an account had its funds withdrawn (or is currently being withdrawn). -### `getAccountsDriveStartIndex()` +### `getLog2LeavesPerAccount()` / `getLog2MaxNumOfAccounts()` / `getAccountsDriveStartIndex()` -```solidity -function getAccountsDriveStartIndex() external view override returns (uint64) -``` - -Get the start-index factor of the accounts drive. With `a = getLog2LeavesPerAccount()`, `b = getLog2MaxNumOfAccounts()`, and `c = getAccountsDriveStartIndex()`, the accounts drive starts at memory address `c * 2^(a+b+5)` and is `2^(a+b+5)` bytes in size. +Views that describe the accounts-drive geometry. With `a = getLog2LeavesPerAccount()`, `b = getLog2MaxNumOfAccounts()`, and `c = getAccountsDriveStartIndex()`, the accounts drive starts at memory address `c * 2^(a+b+5)` and is `2^(a+b+5)` bytes in size. ### `getWithdrawalOutputBuilder()` @@ -466,32 +441,18 @@ function getWithdrawalOutputBuilder() external view override returns (IWithdrawa Get the [withdrawal output builder](./withdrawal/iwithdrawal-output-builder.md), which is static-called whenever an account's funds are to be withdrawn. -### `validateAccount()` +### `validateAccount()` / `validateAccountMerkleRoot()` -```solidity -function validateAccount(bytes calldata account, AccountValidityProof calldata proof) external view override -``` - -Validate the existence of an account at a given index in the accounts drive, against the accounts drive Merkle root proved through `proveAccountsDriveMerkleRoot()`. - -*May raise any error raised by [`validateAccountMerkleRoot()`](#validateaccountmerkleroot), as well as `DriveSmallerThanData` (if the provided account is too large).* - -### `validateAccountMerkleRoot()` - -```solidity -function validateAccountMerkleRoot(bytes32 accountMerkleRoot, AccountValidityProof calldata proof) external view override -``` +Validate an account (or account Merkle root) against the proved accounts drive Merkle root. -Validate the existence of an account root at a given index in the accounts drive. - -**Errors** +**Errors** for `validateAccountMerkleRoot` | Error | Condition | |-------|-----------| | `InvalidAccountRootSiblingsArrayLength` | The siblings array length is wrong | | `InvalidNodeIndex` | The account index is outside the accounts drive | | `AccountsDriveMerkleRootNotProved` | The accounts drive root has not been proved yet | -| `InvalidAccountsDriveMerkleRoot(bytes32)` | The computed accounts drive root differs from the proved one (argument is the computed root) | +| `InvalidAccountsDriveMerkleRoot(bytes32)` | The computed accounts drive root differs from the proved one | ### `AccountsDriveMerkleRootProved()` @@ -501,24 +462,10 @@ event AccountsDriveMerkleRootProved(bytes32 accountsDriveMerkleRoot) Triggered when the accounts drive Merkle root is proved. -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `accountsDriveMerkleRoot` | `bytes32` | The accounts drive Merkle root | - ### `Withdrawal()` ```solidity -event Withdrawal(uint64 accountIndex, bytes account, bytes output) +event Withdrawal(uint64 indexed accountIndex, bytes account, bytes output) ``` Triggered when the funds of an account are withdrawn. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `accountIndex` | `uint64` | The account index in the accounts drive | -| `account` | `bytes` | The account as encoded in the accounts drive | -| `output` | `bytes` | The withdrawal output | diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/abstract-consensus.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/abstract-consensus.md index 23c31eb08..47ba3186b 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/abstract-consensus.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/abstract-consensus.md @@ -2,13 +2,13 @@ id: abstract-consensus title: AbstractConsensus resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/consensus/AbstractConsensus.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/AbstractConsensus.sol title: AbstractConsensus Contract --- -The **AbstractConsensus** contract provides an abstract implementation of `IConsensus` with common consensus functionality. +The **AbstractConsensus** contract provides an abstract implementation of `IConsensus` with common consensus functionality, including claim staging/acceptance counters and `IOutputsMerkleRootValidator` helpers (`isOutputsMerkleRootValid`, `getLastFinalizedMachineMerkleRoot`, `wasInputFinalized`). ## Functions @@ -20,32 +20,18 @@ function isOutputsMerkleRootValid(address appContract, bytes32 outputsMerkleRoot Check whether an outputs Merkle root is valid. -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `appContract` | `address` | The application contract address | -| `outputsMerkleRoot` | `bytes32` | The outputs Merkle root | - -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `bool` | True if the outputs Merkle root is valid | - -### `getEpochLength()` +### `getEpochLength()` / `getClaimStagingPeriod()` ```solidity function getEpochLength() public view override returns (uint256) +function getClaimStagingPeriod() public view override returns (uint256) ``` -Get the epoch length. +Get the epoch length and claim staging period. -**Return Values** +### `wasInputFinalized()` / `getLastFinalizedMachineMerkleRoot()` -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `uint256` | The epoch length | +See [`IOutputsMerkleRootValidator`](./ioutputs-merkle-root-validator.md). ### `supportsInterface()` @@ -53,16 +39,4 @@ Get the epoch length. function supportsInterface(bytes4 interfaceId) public view virtual override(IERC165, ERC165) returns (bool) ``` -Check if the contract supports a specific interface. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `interfaceId` | `bytes4` | The interface identifier | - -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `bool` | True if the interface is supported | \ No newline at end of file +Check if the contract supports a specific interface (`IConsensus` / `IOutputsMerkleRootValidator`). \ No newline at end of file diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/authority-factory.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/authority-factory.md index 3e3eeb9d0..9949af80a 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/authority-factory.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/authority-factory.md @@ -2,8 +2,10 @@ id: authority-factory 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 title: AuthorityFactory Contract + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/authority/IAuthorityFactory.sol + title: IAuthorityFactory Interface --- @@ -15,7 +17,11 @@ The **AuthorityFactory** contract allows anyone to reliably deploy new `IAuthori ### `newAuthority()` ```solidity -function newAuthority(address authorityOwner, uint256 epochLength) external override returns (IAuthority) +function newAuthority( + address authorityOwner, + uint256 epochLength, + uint256 claimStagingPeriod +) external override returns (IAuthority) ``` Deploy a new authority contract. @@ -26,6 +32,7 @@ Deploy a new authority contract. |------|------|-------------| | `authorityOwner` | `address` | The initial authority owner | | `epochLength` | `uint256` | The epoch length | +| `claimStagingPeriod` | `uint256` | How many base-layer blocks must elapse before a staged claim can be accepted | **Return Values** @@ -36,7 +43,12 @@ Deploy a new authority contract. ### `newAuthority()` (with salt) ```solidity -function newAuthority(address authorityOwner, uint256 epochLength, bytes32 salt) external override returns (IAuthority) +function newAuthority( + address authorityOwner, + uint256 epochLength, + uint256 claimStagingPeriod, + bytes32 salt +) external override returns (IAuthority) ``` Deploy a new authority contract deterministically using CREATE2. @@ -47,6 +59,7 @@ Deploy a new authority contract deterministically using CREATE2. |------|------|-------------| | `authorityOwner` | `address` | The initial authority owner | | `epochLength` | `uint256` | The epoch length | +| `claimStagingPeriod` | `uint256` | How many base-layer blocks must elapse before a staged claim can be accepted | | `salt` | `bytes32` | The salt used to deterministically generate the authority address | **Return Values** @@ -61,6 +74,7 @@ Deploy a new authority contract deterministically using CREATE2. function calculateAuthorityAddress( address authorityOwner, uint256 epochLength, + uint256 claimStagingPeriod, bytes32 salt ) external view override returns (address) ``` @@ -73,10 +87,29 @@ Calculate the address of an authority to be deployed deterministically. |------|------|-------------| | `authorityOwner` | `address` | The initial authority owner | | `epochLength` | `uint256` | The epoch length | +| `claimStagingPeriod` | `uint256` | How many base-layer blocks must elapse before a staged claim can be accepted | | `salt` | `bytes32` | The salt used to deterministically generate the authority address | **Return Values** | Name | Type | Description | |------|------|-------------| -| `[0]` | `address` | The deterministic authority address | \ No newline at end of file +| `[0]` | `address` | The deterministic authority address | + +### `version()` + +```solidity +function version() external view returns (string memory) +``` + +Return the rollups-contracts package version string. + +## Events + +### `AuthorityCreated()` + +```solidity +event AuthorityCreated(IAuthority authority) +``` + +Emitted when a new authority is deployed. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/authority.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/authority.md index a29a840c8..49baf7888 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/authority.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/authority.md @@ -2,13 +2,13 @@ id: authority 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 title: Authority Contract --- -The **Authority** contract implements a single-owner consensus mechanism where only the contract owner can submit and accept claims. +The **Authority** contract implements a single-owner consensus mechanism where only the contract owner can submit claims. Staged claims can be accepted after the claim staging period elapses (see [`IConsensus`](../iconsensus.md)). ## Functions @@ -18,19 +18,26 @@ The **Authority** contract implements a single-owner consensus mechanism where o function submitClaim( address appContract, uint256 lastProcessedBlockNumber, - bytes32 outputsMerkleRoot + bytes32 machineMerkleRoot, + MachineValidityProof calldata proof ) external onlyOwner ``` Submit a claim to the consensus. Only the contract owner can call this function. -**Parameters** +See [`IConsensus.submitClaim`](../iconsensus.md#submitclaim) for parameters, events, and machine-validation requirements. -| Name | Type | Description | -|------|------|-------------| -| `appContract` | `address` | The application contract address | -| `lastProcessedBlockNumber` | `uint256` | The number of the last processed block | -| `outputsMerkleRoot` | `bytes32` | The outputs Merkle root | +### `acceptClaim()` + +```solidity +function acceptClaim( + address appContract, + uint256 lastProcessedBlockNumber, + bytes32 machineMerkleRoot +) external +``` + +Accept a staged claim whose staging period has elapsed. See [`IConsensus.acceptClaim`](../iconsensus.md#acceptclaim). ### `owner()` @@ -40,12 +47,6 @@ function owner() public view override(IOwnable, Ownable) returns (address) Returns the address of the current owner. -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `address` | The current owner address | - ### `renounceOwnership()` ```solidity @@ -62,28 +63,18 @@ function transferOwnership(address newOwner) public override(IOwnable, Ownable) Transfers ownership of the contract to a new account. -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `newOwner` | `address` | The new owner address | - ### `supportsInterface()` ```solidity function supportsInterface(bytes4 interfaceId) public view override(IERC165, AbstractConsensus) returns (bool) ``` -Check if the contract supports a specific interface. +Check if the contract supports a specific interface. Authority returns `true` for `IOutputsMerkleRootValidator` as well as `IConsensus`. -**Parameters** +### `version()` -| Name | Type | Description | -|------|------|-------------| -| `interfaceId` | `bytes4` | The interface identifier | - -**Return Values** +```solidity +function version() external view returns (string memory) +``` -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `bool` | True if the interface is supported | \ No newline at end of file +Return the rollups-contracts package version string. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/iauthority-factory.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/iauthority-factory.md index 00e4757da..ea870376a 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/iauthority-factory.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/iauthority-factory.md @@ -2,7 +2,7 @@ id: iauthority-factory 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 title: IAuthorityFactory Interface --- @@ -10,89 +10,4 @@ resources: The **IAuthorityFactory** interface defines the contract for deploying new `IAuthority` contracts. -## Events - -### `AuthorityCreated` - -```solidity -event AuthorityCreated(IAuthority authority) -``` - -A new authority was deployed. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `authority` | `IAuthority` | The authority | - -## Functions - -### `newAuthority()` - -```solidity -function newAuthority(address authorityOwner, uint256 epochLength) external returns (IAuthority) -``` - -Deploy a new authority. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `authorityOwner` | `address` | The initial authority owner | -| `epochLength` | `uint256` | The epoch length | - -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `IAuthority` | The authority | - -### `newAuthority()` (with salt) - -```solidity -function newAuthority(address authorityOwner, uint256 epochLength, bytes32 salt) external returns (IAuthority) -``` - -Deploy a new authority deterministically. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `authorityOwner` | `address` | The initial authority owner | -| `epochLength` | `uint256` | The epoch length | -| `salt` | `bytes32` | The salt used to deterministically generate the authority address | - -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `IAuthority` | The authority | - -### `calculateAuthorityAddress()` - -```solidity -function calculateAuthorityAddress( - address authorityOwner, - uint256 epochLength, - bytes32 salt -) external view returns (address) -``` - -Calculate the address of an authority to be deployed deterministically. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `authorityOwner` | `address` | The initial authority owner | -| `epochLength` | `uint256` | The epoch length | -| `salt` | `bytes32` | The salt used to deterministically generate the authority address | - -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `address` | The deterministic authority address | \ No newline at end of file +See [`AuthorityFactory`](./authority-factory.md) for the full API, including the `claimStagingPeriod` parameter on `newAuthority` and `calculateAuthorityAddress`. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/iauthority.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/iauthority.md index bf0e47406..6f4ba92e9 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/iauthority.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/authority/iauthority.md @@ -2,7 +2,7 @@ id: iauthority 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 title: IAuthority Interface --- @@ -18,4 +18,4 @@ A consensus contract controlled by a single address, the owner. This interface c - [`Authority`](./authority.md): Implementation of this interface - [`IConsensus`](../iconsensus.md): Base consensus interface -- [`IOwnable`](https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/access/IOwnable.sol): Ownership management interface \ No newline at end of file +- [`IOwnable`](https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/access/IOwnable.sol): Ownership management interface \ No newline at end of file diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/iconsensus.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/iconsensus.md index 539aba313..8ee405669 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/iconsensus.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/iconsensus.md @@ -2,29 +2,70 @@ id: iconsensus title: IConsensus resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/consensus/IConsensus.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/IConsensus.sol title: IConsensus Interface --- -The `IConsensus` interface defines the main consensus contract behavior for validating and accepting claims submitted by validators. +The `IConsensus` interface defines the main consensus contract behavior for submitting, staging, and accepting claims about Cartesi Rollups applications. ## Description -Each application has its own stream of inputs. When an input is fed to the application, it may yield several outputs. Since genesis, a Merkle tree of all outputs ever produced is maintained both inside and outside the Cartesi Machine. +Each application has its own stream of inputs, split into epochs. The epoch of an input is the integer division of the base-layer block number in which it was added by the epoch length (see `getEpochLength`). -The claim that validators may submit to the consensus contract is the root of this Merkle tree after processing all base layer blocks until some height. +After every epoch, each validator can submit a claim about the post-epoch machine state (a machine Merkle root), while proving the set of all outputs ever emitted (an outputs Merkle root stored at a known address in machine memory). Empty epochs can be skipped to save fees. -A validator should be able to save transaction fees by not submitting a claim if it was: -- Already submitted by the validator (see the `ClaimSubmitted` event) or -- Already accepted by the consensus (see the `ClaimAccepted` event) +If a claim meets the staging criteria of the consensus model, it is **staged**. Acceptance is delayed by the claim staging period (see `getClaimStagingPeriod`) so guardians have time to foreclose the application if a malicious claim appears. After the staging period elapses, anyone can call `acceptClaim` to finalize the claim. -The acceptance criteria for claims may depend on the type of consensus, and is not specified by this interface. For example, a claim may be accepted if it was: -- Submitted by an authority or -- Submitted by the majority of a quorum or -- Submitted and not proven wrong after some period of time or -- Submitted and proven correct through an on-chain tournament +The staging criteria may depend on the consensus type (for example authority owner, quorum majority, challenge window, or tournament). + +`IConsensus` inherits from `IOutputsMerkleRootValidator`, `IApplicationChecker`, `IVersionGetter`, and `MachineValidationErrors`. + +## Types + +### `ClaimStatus` + +```solidity +enum ClaimStatus { + UNSTAGED, + STAGED, + ACCEPTED +} +``` + +### `Claim` + +```solidity +struct Claim { + ClaimStatus status; + uint256 stagingBlockNumber; + bytes32 stagedOutputsMerkleRoot; +} +``` + +The `stagingBlockNumber` and `stagedOutputsMerkleRoot` fields are only meaningful when the claim was staged. + +### `MachineValidityProof` + +```solidity +struct MachineValidityProof { + LeafProof iflagsYProof; // proves the iflags_Y register + LeafProof htifTohostProof; // proves the HTIF tohost register + LeafProof txBufferProof; // proves the first data block of the CMIO tx buffer +} +``` + +Proves that the post-epoch machine is manually yielded with an `rx accepted` reason and that the outputs Merkle root is stored at the start of the tx buffer. + +### `LeafProof` + +```solidity +struct LeafProof { + bytes32 dataBlock; // 32-byte data block at a known offset + bytes32[] siblings; // bottom-up siblings of the leaf node +} +``` ## Functions @@ -34,23 +75,45 @@ The acceptance criteria for claims may depend on the type of consensus, and is n function submitClaim( address appContract, uint256 lastProcessedBlockNumber, - bytes32 outputsMerkleRoot + bytes32 machineMerkleRoot, + MachineValidityProof calldata proof ) external ``` Submit a claim to the consensus. +*Must fire a `ClaimSubmitted` event. May fire a `ClaimStaged` event if the staging criteria is met. The proof must show a valid post-epoch machine (yielded with `rx accepted`); otherwise machine-validation errors are raised.* + **Parameters** | Name | Type | Description | |------|------|-------------| | `appContract` | `address` | The application contract address | | `lastProcessedBlockNumber` | `uint256` | The number of the last processed block | -| `outputsMerkleRoot` | `bytes32` | The outputs Merkle root | +| `machineMerkleRoot` | `bytes32` | The machine Merkle root | +| `proof` | `MachineValidityProof` | Proof of machine validity and outputs Merkle root | + +### `acceptClaim()` + +```solidity +function acceptClaim( + address appContract, + uint256 lastProcessedBlockNumber, + bytes32 machineMerkleRoot +) external +``` -**Events:** -- `ClaimSubmitted`: Must be fired -- `ClaimAccepted`: MAY be fired, if the acceptance criteria is met +Accept a staged claim whose staging period has elapsed. + +*Must fire a `ClaimAccepted` event.* + +**Parameters** + +| Name | Type | Description | +|------|------|-------------| +| `appContract` | `address` | The application contract address | +| `lastProcessedBlockNumber` | `uint256` | The number of the last processed block | +| `machineMerkleRoot` | `bytes32` | The machine Merkle root | ### `getEpochLength()` @@ -58,15 +121,45 @@ Submit a claim to the consensus. function getEpochLength() external view returns (uint256) ``` -Get the epoch length, in number of base layer blocks. +Get the epoch length, in number of base-layer blocks. -**Return Values** +### `getClaimStagingPeriod()` -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `uint256` | The epoch length | +```solidity +function getClaimStagingPeriod() external view returns (uint256) +``` + +Get the number of base-layer blocks after which a staged claim can be accepted. + +### `getNumberOfAcceptedClaims()` / `getNumberOfStagedClaims()` / `getNumberOfSubmittedClaims()` + +```solidity +function getNumberOfAcceptedClaims(address appContract) external view returns (uint256) +function getNumberOfStagedClaims(address appContract) external view returns (uint256) +function getNumberOfSubmittedClaims(address appContract) external view returns (uint256) +``` + +Per-application counters for accepted, staged, and submitted claims. + +### `getClaim()` + +```solidity +function getClaim( + address appContract, + uint256 lastProcessedBlockNumber, + bytes32 machineMerkleRoot +) external view returns (Claim memory claim) +``` + +Get information about a claim. + +### `version()` + +```solidity +function version() external view returns (string memory) +``` -**Note:** The epoch number of a block is defined as the integer division of the block number by the epoch length. +Return the rollups-contracts package version string. ## Events @@ -77,20 +170,23 @@ event ClaimSubmitted( address indexed submitter, address indexed appContract, uint256 lastProcessedBlockNumber, - bytes32 outputsMerkleRoot + bytes32 outputsMerkleRoot, + bytes32 machineMerkleRoot ) ``` -Must trigger when a claim is submitted. +### `ClaimStaged()` -**Parameters** +```solidity +event ClaimStaged( + address indexed appContract, + uint256 lastProcessedBlockNumber, + bytes32 outputsMerkleRoot, + bytes32 machineMerkleRoot +) +``` -| Name | Type | Description | -|------|------|-------------| -| `submitter` | `address` | The submitter address | -| `appContract` | `address` | The application contract address | -| `lastProcessedBlockNumber` | `uint256` | The number of the last processed block | -| `outputsMerkleRoot` | `bytes32` | The outputs Merkle root | +*For each application and `lastProcessedBlockNumber`, there can be at most one staged claim.* ### `ClaimAccepted()` @@ -98,21 +194,12 @@ Must trigger when a claim is submitted. event ClaimAccepted( address indexed appContract, uint256 lastProcessedBlockNumber, - bytes32 outputsMerkleRoot + bytes32 outputsMerkleRoot, + bytes32 machineMerkleRoot ) ``` -Must trigger when a claim is accepted. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `appContract` | `address` | The application contract address | -| `lastProcessedBlockNumber` | `uint256` | The number of the last processed block | -| `outputsMerkleRoot` | `bytes32` | The outputs Merkle root | - -**Note:** For each application and lastProcessedBlockNumber, there can be at most one accepted claim. +*For each application and `lastProcessedBlockNumber`, there can be at most one accepted claim.* ## Errors @@ -122,14 +209,7 @@ Must trigger when a claim is accepted. error NotEpochFinalBlock(uint256 lastProcessedBlockNumber, uint256 epochLength) ``` -The claim contains the number of a block that is not at the end of an epoch (its modulo epoch length is not epoch length - 1). - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `lastProcessedBlockNumber` | `uint256` | The number of the last processed block | -| `epochLength` | `uint256` | The epoch length | +The claim's last processed block is not at the end of an epoch. ### `NotPastBlock()` @@ -137,14 +217,7 @@ The claim contains the number of a block that is not at the end of an epoch (its error NotPastBlock(uint256 lastProcessedBlockNumber, uint256 currentBlockNumber) ``` -The claim contains the number of a block in the future (it is greater or equal to the current block number). - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `lastProcessedBlockNumber` | `uint256` | The number of the last processed block | -| `currentBlockNumber` | `uint256` | The number of the current block | +The claim contains a block number in the future. ### `NotFirstClaim()` @@ -154,14 +227,47 @@ error NotFirstClaim(address appContract, uint256 lastProcessedBlockNumber) A claim for that application and epoch was already submitted by the validator. -**Parameters** +### `ClaimNotStaged()` -| Name | Type | Description | -|------|------|-------------| -| `appContract` | `address` | The application contract address | -| `lastProcessedBlockNumber` | `uint256` | The number of the last processed block | +```solidity +error ClaimNotStaged( + address appContract, + uint256 lastProcessedBlockNumber, + bytes32 machineMerkleRoot, + ClaimStatus claimStatus +) +``` + +Tried to accept an unstaged or already-accepted claim. + +### `ClaimStagingPeriodNotOverYet()` + +```solidity +error ClaimStagingPeriodNotOverYet( + address appContract, + uint256 lastProcessedBlockNumber, + bytes32 machineMerkleRoot, + uint256 numberOfBlocksAfterStaging, + uint256 claimStagingPeriod +) +``` + +Tried to accept a claim during its staging period. + +### Machine validation errors + +From `MachineValidationErrors`: + +| Error | Condition | +|-------|-----------| +| `InvalidSiblingsArrayLength` | A leaf-proof siblings array has the wrong length | +| `InvalidMachineMerkleProof` | A Merkle proof does not produce the stated machine Merkle root | +| `InvalidPostEpochMachineIflagsYRegister` | Post-epoch `iflags_Y` is unset | +| `InvalidPostEpochMachineHtifTohostRegister` | Post-epoch HTIF tohost does not signal `rx accepted` | + +A machine that fails the post-epoch checks may have reached an unrecoverable state; foreclosure and emergency withdrawal / deposit refunds are the recovery path. ## Related Contracts - [`AbstractConsensus`](./abstract-consensus.md): Abstract implementation of this interface -- [`IOutputsMerkleRootValidator`](./ioutputs-merkle-root-validator.md): Interface for validating outputs Merkle roots \ No newline at end of file +- [`IOutputsMerkleRootValidator`](./ioutputs-merkle-root-validator.md): Interface for validating outputs Merkle roots diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/ioutputs-merkle-root-validator.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/ioutputs-merkle-root-validator.md index a0b941c4a..bf5dc469d 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/ioutputs-merkle-root-validator.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/ioutputs-merkle-root-validator.md @@ -2,13 +2,13 @@ id: ioutputs-merkle-root-validator title: IOutputsMerkleRootValidator resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/consensus/IOutputsMerkleRootValidator.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/IOutputsMerkleRootValidator.sol title: IOutputsMerkleRootValidator Interface --- -The `IOutputsMerkleRootValidator` interface provides valid outputs Merkle roots for validation. +The `IOutputsMerkleRootValidator` interface provides valid outputs Merkle roots for validation, last-finalized machine Merkle roots, and input finalization checks. ## Description @@ -17,6 +17,7 @@ This interface provides functionality to check whether an outputs Merkle root is ## Functions ### `isOutputsMerkleRootValid` + ```solidity function isOutputsMerkleRootValid(address appContract, bytes32 outputsMerkleRoot) external view returns (bool) ``` @@ -30,7 +31,40 @@ Check whether an outputs Merkle root is valid. **Returns:** - (bool): True if the outputs Merkle root is valid +### `getLastFinalizedMachineMerkleRoot` + +```solidity +function getLastFinalizedMachineMerkleRoot(address appContract) external view returns (bytes32) +``` + +Get the last finalized machine Merkle root for an application. + +**Returns:** +- (bytes32): The last finalized machine Merkle root, or zero if none has been finalized yet + +### `wasInputFinalized` + +```solidity +function wasInputFinalized( + address appContract, + uint256 inputIndex, + uint256 blockNumber +) external view returns (bool) +``` + +Check whether an input was finalized. + +**Parameters:** +- `appContract` (address): The application contract address +- `inputIndex` (uint256): The index of the input in the application's input box +- `blockNumber` (uint256): The number of the base-layer block in which the input was added + +**Returns:** +- (bool): Whether the input was finalized + +*Assumes that an input with such an index exists and was added in that block. Foreclosed applications use this when issuing refunds for deposit inputs that were not finalized.* + ## Related Contracts - [`IConsensus`](./iconsensus.md): Interface that inherits from this interface -- [`AbstractConsensus`](./abstract-consensus.md): Abstract implementation that implements this interface \ No newline at end of file +- [`AbstractConsensus`](./abstract-consensus.md): Abstract implementation that implements this interface diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/overview.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/overview.md index 4f445ca03..3f9638079 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/overview.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/overview.md @@ -2,7 +2,7 @@ id: overview title: Overview resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/consensus + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus title: Consensus Smart Contracts --- @@ -25,17 +25,18 @@ The framework supports different consensus mechanisms: ## Consensus Mechanism -A claim consists of: +A claim submission consists of: -- Application Contract Address: The address of the dApp being validated -- Last Processed Block Number: The block number up to which inputs have been processed -- Outputs Merkle Root: The root hash of the Merkle tree containing all outputs produced by the application +- Application contract address +- Last processed block number +- Machine Merkle root (post-epoch machine state) +- Machine validity proof (proves `iflags_Y`, HTIF tohost / `rx accepted`, and the outputs Merkle root in the tx buffer) + +If the claim meets the consensus staging criteria, it is **staged**. After the claim staging period elapses, it can be **accepted**. Once accepted, the outputs Merkle root becomes valid and can be used to validate individual outputs in the application contract. The consensus contract validates that: + - The block number is at the end of an epoch (modulo epoch length equals epoch length - 1) - The block number is in the past (not future) -- No duplicate claim has been submitted for the same application and epoch - -Once a claim is accepted, the outputs Merkle root becomes valid and can be used to validate individual outputs in the application contract. - - +- No duplicate claim has been submitted for the same application and epoch by that validator +- The post-epoch machine is manually yielded with an `rx accepted` reason diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/iquorum-factory.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/iquorum-factory.md index e91cc0bc8..ac69b6a24 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/iquorum-factory.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/iquorum-factory.md @@ -2,7 +2,7 @@ id: iquorum-factory title: IQuorumFactory resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/consensus/quorum/IQuorumFactory.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/quorum/IQuorumFactory.sol title: IQuorumFactory Interface --- @@ -10,89 +10,4 @@ resources: The **IQuorumFactory** interface defines the contract for deploying new `IQuorum` contracts. -## Events - -### `QuorumCreated` - -```solidity -event QuorumCreated(IQuorum quorum) -``` - -A new quorum was deployed. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `quorum` | `IQuorum` | The quorum | - -## Functions - -### `newQuorum()` - -```solidity -function newQuorum(address[] calldata validators, uint256 epochLength) external returns (IQuorum) -``` - -Deploy a new quorum. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `validators` | `address[]` | The list of validators | -| `epochLength` | `uint256` | The epoch length | - -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `IQuorum` | The quorum | - -### `newQuorum()` (with salt) - -```solidity -function newQuorum(address[] calldata validators, uint256 epochLength, bytes32 salt) external returns (IQuorum) -``` - -Deploy a new quorum deterministically. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `validators` | `address[]` | The list of validators | -| `epochLength` | `uint256` | The epoch length | -| `salt` | `bytes32` | The salt used to deterministically generate the quorum address | - -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `IQuorum` | The quorum | - -### `calculateQuorumAddress()` - -```solidity -function calculateQuorumAddress( - address[] calldata validators, - uint256 epochLength, - bytes32 salt -) external view returns (address) -``` - -Calculate the address of a quorum to be deployed deterministically. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `validators` | `address[]` | The list of validators | -| `epochLength` | `uint256` | The epoch length | -| `salt` | `bytes32` | The salt used to deterministically generate the quorum address | - -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `address` | The deterministic quorum address | \ No newline at end of file +See [`QuorumFactory`](./quorum-factory.md) for the full API, including the `claimStagingPeriod` parameter on `newQuorum` and `calculateQuorumAddress`. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/iquorum.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/iquorum.md index c033a9485..515c73865 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/iquorum.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/iquorum.md @@ -2,7 +2,7 @@ id: iquorum title: IQuorum resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/consensus/quorum/IQuorum.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/quorum/IQuorum.sol title: IQuorum Interface --- @@ -99,7 +99,7 @@ Check whether a validator is in favor of any claim in a given epoch. function numOfValidatorsInFavorOf( address appContract, uint256 lastProcessedBlockNumber, - bytes32 outputsMerkleRoot + bytes32 machineMerkleRoot ) external view returns (uint256) ``` @@ -108,7 +108,7 @@ Get the number of validators in favor of a claim. **Parameters:** - `appContract` (address): The application contract address - `lastProcessedBlockNumber` (uint256): The number of the last processed block -- `outputsMerkleRoot` (bytes32): The outputs Merkle root +- `machineMerkleRoot` (bytes32): The machine Merkle root **Returns:** - (uint256): Number of validators in favor of claim @@ -118,7 +118,7 @@ Get the number of validators in favor of a claim. function isValidatorInFavorOf( address appContract, uint256 lastProcessedBlockNumber, - bytes32 outputsMerkleRoot, + bytes32 machineMerkleRoot, uint256 id ) external view returns (bool) ``` @@ -128,7 +128,7 @@ Check whether a validator is in favor of a claim. **Parameters:** - `appContract` (address): The application contract address - `lastProcessedBlockNumber` (uint256): The number of the last processed block -- `outputsMerkleRoot` (bytes32): The outputs Merkle root +- `machineMerkleRoot` (bytes32): The machine Merkle root - `id` (uint256): The ID of the validator **Returns:** diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/quorum-factory.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/quorum-factory.md index 6d80d5270..7cc014ad0 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/quorum-factory.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/quorum-factory.md @@ -2,8 +2,10 @@ id: quorum-factory title: QuorumFactory resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/consensus/quorum/QuorumFactory.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/quorum/QuorumFactory.sol title: QuorumFactory Contract + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/quorum/IQuorumFactory.sol + title: IQuorumFactory Interface --- @@ -15,7 +17,11 @@ The **QuorumFactory** contract allows anyone to reliably deploy new `IQuorum` co ### `newQuorum()` ```solidity -function newQuorum(address[] calldata validators, uint256 epochLength) external override returns (IQuorum) +function newQuorum( + address[] calldata validators, + uint256 epochLength, + uint256 claimStagingPeriod +) external override returns (IQuorum) ``` Deploy a new quorum contract. @@ -24,8 +30,9 @@ Deploy a new quorum contract. | Name | Type | Description | |------|------|-------------| -| `validators` | `address[]` | The list of validators | +| `validators` | `address[]` | The list of validators (duplicates are ignored) | | `epochLength` | `uint256` | The epoch length | +| `claimStagingPeriod` | `uint256` | How many base-layer blocks must elapse before a staged claim can be accepted | **Return Values** @@ -36,7 +43,12 @@ Deploy a new quorum contract. ### `newQuorum()` (with salt) ```solidity -function newQuorum(address[] calldata validators, uint256 epochLength, bytes32 salt) external override returns (IQuorum) +function newQuorum( + address[] calldata validators, + uint256 epochLength, + uint256 claimStagingPeriod, + bytes32 salt +) external override returns (IQuorum) ``` Deploy a new quorum contract deterministically using CREATE2. @@ -45,8 +57,9 @@ Deploy a new quorum contract deterministically using CREATE2. | Name | Type | Description | |------|------|-------------| -| `validators` | `address[]` | The list of validators | +| `validators` | `address[]` | The list of validators (duplicates are ignored) | | `epochLength` | `uint256` | The epoch length | +| `claimStagingPeriod` | `uint256` | How many base-layer blocks must elapse before a staged claim can be accepted | | `salt` | `bytes32` | The salt used to deterministically generate the quorum address | **Return Values** @@ -61,6 +74,7 @@ Deploy a new quorum contract deterministically using CREATE2. function calculateQuorumAddress( address[] calldata validators, uint256 epochLength, + uint256 claimStagingPeriod, bytes32 salt ) external view override returns (address) ``` @@ -73,10 +87,29 @@ Calculate the address of a quorum to be deployed deterministically. |------|------|-------------| | `validators` | `address[]` | The list of validators | | `epochLength` | `uint256` | The epoch length | +| `claimStagingPeriod` | `uint256` | How many base-layer blocks must elapse before a staged claim can be accepted | | `salt` | `bytes32` | The salt used to deterministically generate the quorum address | **Return Values** | Name | Type | Description | |------|------|-------------| -| `[0]` | `address` | The deterministic quorum address | \ No newline at end of file +| `[0]` | `address` | The deterministic quorum address | + +### `version()` + +```solidity +function version() external view returns (string memory) +``` + +Return the rollups-contracts package version string. + +## Events + +### `QuorumCreated()` + +```solidity +event QuorumCreated(IQuorum quorum) +``` + +Emitted when a new quorum is deployed. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/quorum.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/quorum.md index 82099cc62..45719ccc4 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/quorum.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/consensus/quorum/quorum.md @@ -2,13 +2,13 @@ id: quorum title: Quorum resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/consensus/quorum/Quorum.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/consensus/quorum/Quorum.sol title: Quorum Contract --- -The **Quorum** contract implements a multi-validator consensus mechanism where claims are accepted when a majority of validators vote in favor. +The **Quorum** contract implements a multi-validator consensus mechanism where claims are staged when a majority of validators vote in favor. Staged claims can be accepted after the claim staging period elapses (see [`IConsensus`](../iconsensus.md)). ## Functions @@ -18,19 +18,26 @@ The **Quorum** contract implements a multi-validator consensus mechanism where c function submitClaim( address appContract, uint256 lastProcessedBlockNumber, - bytes32 outputsMerkleRoot + bytes32 machineMerkleRoot, + MachineValidityProof calldata proof ) external override ``` Submit a claim to the consensus. Only validators can call this function. -**Parameters** +See [`IConsensus.submitClaim`](../iconsensus.md#submitclaim) for parameters, events, and machine-validation requirements. Reverts with `CallerIsNotValidator` if the caller is not a validator. -| Name | Type | Description | -|------|------|-------------| -| `appContract` | `address` | The application contract address | -| `lastProcessedBlockNumber` | `uint256` | The number of the last processed block | -| `outputsMerkleRoot` | `bytes32` | The outputs Merkle root | +### `acceptClaim()` + +```solidity +function acceptClaim( + address appContract, + uint256 lastProcessedBlockNumber, + bytes32 machineMerkleRoot +) external +``` + +Accept a staged claim whose staging period has elapsed. See [`IConsensus.acceptClaim`](../iconsensus.md#acceptclaim). ### `numOfValidators()` @@ -40,31 +47,13 @@ function numOfValidators() external view override returns (uint256) Get the number of validators. -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `uint256` | The total number of validators | - ### `validatorId()` ```solidity function validatorId(address validator) external view override returns (uint256) ``` -Get the ID of a validator. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `validator` | `address` | The validator address | - -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `uint256` | The validator ID (0 for non-validators, >0 for validators) | +Get the ID of a validator (0 for non-validators, 1..N for validators). ### `validatorById()` @@ -72,19 +61,7 @@ Get the ID of a validator. function validatorById(uint256 id) external view override returns (address) ``` -Get the address of a validator by its ID. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `id` | `uint256` | The validator ID | - -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `address` | The validator address (address(0) for invalid IDs) | +Get the address of a validator by its ID (`address(0)` for invalid IDs). ### `numOfValidatorsInFavorOfAnyClaimInEpoch()` @@ -97,19 +74,6 @@ function numOfValidatorsInFavorOfAnyClaimInEpoch( Get the number of validators in favor of any claim in a given epoch. -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `appContract` | `address` | The application contract address | -| `lastProcessedBlockNumber` | `uint256` | The number of the last processed block | - -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `uint256` | Number of validators in favor of any claim in the epoch | - ### `isValidatorInFavorOfAnyClaimInEpoch()` ```solidity @@ -122,45 +86,17 @@ function isValidatorInFavorOfAnyClaimInEpoch( Check whether a validator is in favor of any claim in a given epoch. -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `appContract` | `address` | The application contract address | -| `lastProcessedBlockNumber` | `uint256` | The number of the last processed block | -| `id` | `uint256` | The ID of the validator | - -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `bool` | Whether validator is in favor of any claim in the epoch | - ### `numOfValidatorsInFavorOf()` ```solidity function numOfValidatorsInFavorOf( address appContract, uint256 lastProcessedBlockNumber, - bytes32 outputsMerkleRoot + bytes32 machineMerkleRoot ) external view override returns (uint256) ``` -Get the number of validators in favor of a claim. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `appContract` | `address` | The application contract address | -| `lastProcessedBlockNumber` | `uint256` | The number of the last processed block | -| `outputsMerkleRoot` | `bytes32` | The outputs Merkle root | - -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `uint256` | Number of validators in favor of claim | +Get the number of validators in favor of a claim identified by its machine Merkle root. ### `isValidatorInFavorOf()` @@ -168,27 +104,12 @@ Get the number of validators in favor of a claim. function isValidatorInFavorOf( address appContract, uint256 lastProcessedBlockNumber, - bytes32 outputsMerkleRoot, + bytes32 machineMerkleRoot, uint256 id ) external view override returns (bool) ``` -Check whether a validator is in favor of a claim. - -**Parameters** - -| Name | Type | Description | -|------|------|-------------| -| `appContract` | `address` | The application contract address | -| `lastProcessedBlockNumber` | `uint256` | The number of the last processed block | -| `outputsMerkleRoot` | `bytes32` | The outputs Merkle root | -| `id` | `uint256` | The ID of the validator | - -**Return Values** - -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `bool` | Whether validator is in favor of claim | +Check whether a validator is in favor of a claim identified by its machine Merkle root. ### `supportsInterface()` @@ -196,16 +117,12 @@ Check whether a validator is in favor of a claim. function supportsInterface(bytes4 interfaceId) public view override(IERC165, AbstractConsensus) returns (bool) ``` -Check if the contract supports a specific interface. - -**Parameters** +Check if the contract supports a specific interface. Quorum returns `true` for `IOutputsMerkleRootValidator` as well as `IConsensus`. -| Name | Type | Description | -|------|------|-------------| -| `interfaceId` | `bytes4` | The interface identifier | +### `version()` -**Return Values** +```solidity +function version() external view returns (string memory) +``` -| Name | Type | Description | -|------|------|-------------| -| `[0]` | `bool` | True if the interface is supported | \ No newline at end of file +Return the rollups-contracts package version string. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/input-box.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/input-box.md index 7fae34b8d..41d724f2b 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/input-box.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/input-box.md @@ -2,7 +2,7 @@ id: input-box title: InputBox resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/inputs/InputBox.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/inputs/InputBox.sol title: InputBox contract --- diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/overview.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/overview.md index 4435641b7..4f4940b55 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/overview.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/overview.md @@ -2,7 +2,7 @@ id: overview title: Overview resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6 + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9 title: Smart Contracts for Cartesi Rollups --- @@ -20,6 +20,8 @@ Clients can interact with Ethereum-compatible nodes using the JSON-RPC API in tw - Changing state: The state is changed by submitting a transaction that incurs gas fees. The transaction must be cryptographically signed by an Ethereum account with sufficient funds in its wallet. +Contract sources and artifacts are published with each [rollups-contracts release](https://github.com/cartesi/rollups-contracts/releases) (Soldeer package and GitHub release assets). The npm `@cartesi/rollups` package and Cannon distribution have been discontinued. + ## Cartesi Rollups Smart Contracts - [`InputBox`](../contracts/input-box.md): This contract receives inputs from users who want to interact with the off-chain layer. All inputs to your application are processed through this contract. @@ -28,6 +30,6 @@ Clients can interact with Ethereum-compatible nodes using the JSON-RPC API in tw - [`ApplicationFactory`](../contracts/application-factory.md): This contract enables anyone to deploy [`Application`](../contracts/application.md) contracts with a simple function call. It provides greater convenience to the deployer and security to users and validators, as they can verify that the bytecode has not been maliciously altered. -- [`Portals`](../contracts/portals/): These contracts are used to safely transfer assets from the base layer to the execution environment of your application. Currently, Portal contracts are available for the following types of assets: [Ether (ETH)](../contracts/portals/EtherPortal.md), [ERC-20 (Fungible tokens)](../contracts/portals/ERC20Portal.md), [ERC-721 (Non-fungible tokens)](../contracts/portals/ERC721Portal.md), [ERC-1155 single transfer](../contracts/portals/ERC1155SinglePortal.md), and [ERC-1155 batch token transfers](../contracts/portals/ERC1155BatchPortal.md). +- [`Portals`](../contracts/portals/): These contracts are used to safely transfer assets from the base layer to the execution environment of your application. Currently, Portal contracts are available for the following types of assets: [Ether (ETH)](../contracts/portals/EtherPortal.md), [ERC-20 (Fungible tokens)](../contracts/portals/Erc20Portal.md), [ERC-721 (Non-fungible tokens)](../contracts/portals/Erc721Portal.md), [ERC-1155 single transfer](../contracts/portals/Erc1155SinglePortal.md), and [ERC-1155 batch token transfers](../contracts/portals/Erc1155BatchPortal.md). -- [`Consensus`](../contracts/consensus/overview.md): These contracts are crucial for the framework's security and integrity. They validate and accept claims submitted by validators, ensuring the rollup's integrity by validating outputs Merkle roots. The framework supports different consensus mechanisms including [Authority-based consensus](../contracts/consensus/authority/authority.md) for single-owner control and [Quorum-based consensus](../contracts/consensus/quorum/quorum.md) for multi-validator approval. \ No newline at end of file +- [`Consensus`](../contracts/consensus/overview.md): These contracts are crucial for the framework's security and integrity. They validate and accept claims submitted by validators, ensuring the rollup's integrity by validating outputs Merkle roots. The framework supports different consensus mechanisms including [Authority-based consensus](../contracts/consensus/authority/authority.md) for single-owner control and [Quorum-based consensus](../contracts/consensus/quorum/quorum.md) for multi-validator approval. diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC20Portal.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC20Portal.md deleted file mode 100644 index 5bc492c2b..000000000 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC20Portal.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/portals/ERC20Portal.sol - title: ERC20Portal contract ---- - - - -The **ERC20Portal** allows anyone to perform transfers of -ERC-20 tokens to a dApp while informing the off-chain machine. - -## `depositERC20Tokens()` - -```solidity -function depositERC20Tokens(IERC20 token, address appContract, uint256 value, bytes calldata execLayerData) external; -``` - -Transfer ERC-20 tokens to a dApp and add an input to -the dApp's input box to signal such operation. - -The caller must allow the portal to withdraw at least `_amount` tokens -from their account beforehand, by calling the `approve` function in the -token contract. - -#### Parameters - -| Name | Type | Description | -| ------------- | ------- | -------------------------------------------------------- | -| token | IERC20 | The ERC-20 token contract address | -| appContract | address | The address of the dApp | -| value | uint256 | The amount of tokens to be transferred | -| execLayerData | bytes | Additional data to be interpreted by the execution layer | diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC1155BatchPortal.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/Erc1155BatchPortal.md similarity index 51% rename from cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC1155BatchPortal.md rename to cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/Erc1155BatchPortal.md index 916f2213b..c93235bca 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC1155BatchPortal.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/Erc1155BatchPortal.md @@ -1,18 +1,22 @@ --- resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/portals/ERC1155BatchPortal.sol - title: ERC1155BatchPortal contract + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/portals/Erc1155BatchPortal.sol + title: Erc1155BatchPortal contract + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/portals/IErc1155BatchPortal.sol + title: IErc1155BatchPortal interface --- -The **ERC1155BatchPortal** allows anyone to perform batch transfers of +The **Erc1155BatchPortal** allows anyone to perform batch transfers of ERC-1155 tokens to a dApp while informing the off-chain machine. -## `depositBatchERC1155Token()` +Portals inherit `IPortal`, which extends `IApplicationChecker` and `IVersionGetter`. They do not hold an input box address; deposits are routed to the input box advertised by the application (`getInputBox()`). Deposits may revert with `ApplicationNotDeployed`, `ApplicationReverted`, `IllformedApplicationReturnData`, `InputBoxNotDeployed`, or `ApplicationForeclosed`. + +## `depositBatchErc1155Token()` ```solidity -function depositBatchERC1155Token( IERC1155 token, address appContract, uint256[] calldata tokenIds, uint256[] calldata values, bytes calldata baseLayerData, bytes calldata execLayerData) external; +function depositBatchErc1155Token(IERC1155 token, address appContract, uint256[] calldata tokenIds, uint256[] calldata values, bytes calldata baseLayerData, bytes calldata execLayerData) external; ``` Transfer a batch of ERC-1155 tokens to a dApp and add an input to @@ -21,7 +25,11 @@ the dApp's input box to signal such operation. The caller must enable approval for the portal to manage all of their tokens beforehand, by calling the `setApprovalForAll` function in the token contract. -_Please make sure `tokenIds` and `values` have the same length._ +*Please make sure `tokenIds` and `values` have the same length.* + +If the application is foreclosed and the deposit input is not processed, +the user can issue a refund. If the depositor is a smart contract, a refund +succeeds only if it implements the ERC-1155 receiver hooks. #### Parameters diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC1155SinglePortal.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/Erc1155SinglePortal.md similarity index 52% rename from cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC1155SinglePortal.md rename to cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/Erc1155SinglePortal.md index ef5c47e5f..1c354ba1b 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC1155SinglePortal.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/Erc1155SinglePortal.md @@ -1,18 +1,21 @@ --- resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/portals/ERC1155SinglePortal.sol - title: ERC1155SinglePortal contract + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/portals/Erc1155SinglePortal.sol + title: Erc1155SinglePortal contract + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/portals/IErc1155SinglePortal.sol + title: IErc1155SinglePortal interface --- -The **ERC1155SinglePortal** allows anyone to perform single transfers of ERC-1155 tokens to a dApp while informing the off-chain machine. +The **Erc1155SinglePortal** allows anyone to perform single transfers of ERC-1155 tokens to a dApp while informing the off-chain machine. -### `depositSingleERC1155Token()` +Portals inherit `IPortal`, which extends `IApplicationChecker` and `IVersionGetter`. They do not hold an input box address; deposits are routed to the input box advertised by the application (`getInputBox()`). Deposits may revert with `ApplicationNotDeployed`, `ApplicationReverted`, `IllformedApplicationReturnData`, `InputBoxNotDeployed`, or `ApplicationForeclosed`. -```solidity -function depositSingleERC1155Token( IERC1155 token, address appContract, uint256 tokenId, uint256 value, bytes calldata baseLayerData, bytes calldata execLayerData) external; +### `depositSingleErc1155Token()` +```solidity +function depositSingleErc1155Token(IERC1155 token, address appContract, uint256 tokenId, uint256 value, bytes calldata baseLayerData, bytes calldata execLayerData) external; ``` Transfer an ERC-1155 token to a dApp and add an input to @@ -21,6 +24,10 @@ the dApp's input box to signal such operation. The caller must enable approval for the portal to manage all of their tokens beforehand, by calling the `setApprovalForAll` function in the token contract. +If the application is foreclosed and the deposit input is not processed, +the user can issue a refund. If the depositor is a smart contract, a refund +succeeds only if it implements the ERC-1155 receiver hooks. + #### Parameters | Name | Type | Description | diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/Erc20Portal.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/Erc20Portal.md new file mode 100644 index 000000000..31d9695e3 --- /dev/null +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/Erc20Portal.md @@ -0,0 +1,49 @@ +--- +resources: + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/portals/Erc20Portal.sol + title: Erc20Portal contract + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/portals/IErc20Portal.sol + title: IErc20Portal interface +--- + + + +The **Erc20Portal** allows anyone to perform transfers of +ERC-20 tokens to a dApp while informing the off-chain machine. + +Portals inherit `IPortal`, which extends `IApplicationChecker` and `IVersionGetter`. They do not hold an input box address; deposits are routed to the input box advertised by the application (`getInputBox()`). Deposits may revert with `ApplicationNotDeployed`, `ApplicationReverted`, `IllformedApplicationReturnData`, `InputBoxNotDeployed`, or `ApplicationForeclosed`. + +## `depositErc20Tokens()` + +```solidity +function depositErc20Tokens(IERC20 token, address appContract, uint256 value, bytes calldata execLayerData) external; +``` + +Transfer ERC-20 tokens to a dApp and add an input to +the dApp's input box to signal such operation. + +The caller must allow the portal to withdraw at least `value` tokens +from their account beforehand, by calling the `approve` function in the +token contract. + +Only ERC-20 compliant tokens are supported. The portal rejects deposits +of fee-on-transfer ERC-20 tokens by comparing the application balance +before and after the transfer. Empty or ill-formed `transferFrom` return +values raise a low-level error. + +#### Parameters + +| Name | Type | Description | +| ------------- | ------- | -------------------------------------------------------- | +| token | IERC20 | The ERC-20 token contract address | +| appContract | address | The address of the dApp | +| value | uint256 | The amount of tokens to be transferred | +| execLayerData | bytes | Additional data to be interpreted by the execution layer | + +#### Errors + +| Error | Condition | +|-------|-----------| +| `Erc20TransferFailed` | Token transfer did not succeed | +| `Erc20TransferDecreasedApplicationBalance` | Application balance fell during the transfer | +| `Erc20TransferValueIsNotBalanceDelta` | Balance delta did not equal `value` (fee-on-transfer) | diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC721Portal.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/Erc721Portal.md similarity index 51% rename from cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC721Portal.md rename to cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/Erc721Portal.md index 2c688250a..a5ecf8110 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/ERC721Portal.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/Erc721Portal.md @@ -1,18 +1,22 @@ --- resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/portals/ERC721Portal.sol - title: ERC721Portal contract + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/portals/Erc721Portal.sol + title: Erc721Portal contract + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/portals/IErc721Portal.sol + title: IErc721Portal interface --- -The **ERC721Portal** allows anyone to perform transfers of +The **Erc721Portal** allows anyone to perform transfers of ERC-721 tokens to a dApp while informing the off-chain machine. -## `depositERC721Token()` +Portals inherit `IPortal`, which extends `IApplicationChecker` and `IVersionGetter`. They do not hold an input box address; deposits are routed to the input box advertised by the application (`getInputBox()`). Deposits may revert with `ApplicationNotDeployed`, `ApplicationReverted`, `IllformedApplicationReturnData`, `InputBoxNotDeployed`, or `ApplicationForeclosed`. + +## `depositErc721Token()` ```solidity -function depositERC721Token( IERC721 token, address appContract, uint256 tokenId, bytes baseLayerData, bytes execLayerData) external +function depositErc721Token(IERC721 token, address appContract, uint256 tokenId, bytes calldata baseLayerData, bytes calldata execLayerData) external ``` Transfer an ERC-721 token to a dApp and add an input to @@ -22,6 +26,10 @@ The caller must change the approved address for the ERC-721 token to the portal address beforehand, by calling the `approve` function in the token contract. +If the application is foreclosed and the deposit input is not processed, +the user can issue a refund. If the depositor is a smart contract, a refund +succeeds only if it accepts the NFT through `onERC721Received`. + #### Parameters | Name | Type | Description | diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/EtherPortal.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/EtherPortal.md index aca3f188a..09ee541b0 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/EtherPortal.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/portals/EtherPortal.md @@ -1,7 +1,9 @@ --- resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/portals/EtherPortal.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/portals/EtherPortal.sol title: EtherPortal contract + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/portals/IEtherPortal.sol + title: IEtherPortal interface --- @@ -9,16 +11,23 @@ resources: The **EtherPortal** allows anyone to perform transfers of Ether to a dApp while informing the off-chain machine. +Portals inherit `IPortal`, which extends `IApplicationChecker` and `IVersionGetter`. They do not hold an input box address; deposits are routed to the input box advertised by the application (`getInputBox()`). Deposits may revert with `ApplicationNotDeployed`, `ApplicationReverted`, `IllformedApplicationReturnData`, `InputBoxNotDeployed`, or `ApplicationForeclosed`. + ## `depositEther()` ```solidity -function depositEther(address appContract, bytes execLayerData) external payable +function depositEther(address appContract, bytes calldata execLayerData) external payable ``` Transfer Ether to a dApp and add an input to the dApp's input box to signal such operation. All the value sent through this function is forwarded to the dApp. +If the transfer fails, an `EtherTransferFailed` error is raised. + +If the application is foreclosed and the deposit input is not processed, +the user can issue a refund. If the depositor is a smart contract, a refund +succeeds only if it accepts Ether through a message call. #### Parameters diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/iwithdrawal-output-builder.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/iwithdrawal-output-builder.md index 40574ffaa..fadc1bb1e 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/iwithdrawal-output-builder.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/iwithdrawal-output-builder.md @@ -2,9 +2,9 @@ id: iwithdrawal-output-builder title: IWithdrawalOutputBuilder resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/withdrawal/IWithdrawalOutputBuilder.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/withdrawal/IWithdrawalOutputBuilder.sol title: IWithdrawalOutputBuilder interface - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/withdrawal/IWithdrawalOutputBuilderErrors.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/withdrawal/IWithdrawalOutputBuilderErrors.sol title: IWithdrawalOutputBuilderErrors --- @@ -42,17 +42,17 @@ Build an output that, when executed by the application contract, transfers the f ## Errors -### `AccountTooShort()` +### `InvalidAccountSize()` ```solidity -error AccountTooShort(uint64 attemptedAccountSize, uint64 minAccountSize) +error InvalidAccountSize(uint256 attemptedAccountSize, uint64 accountSize) ``` -Raised when the provided account is too short for the builder to decode on-chain. +Raised when the provided account does not match the exact size the builder expects for on-chain decoding. **Parameters** | Name | Type | Description | |------|------|-------------| -| `attemptedAccountSize` | `uint64` | The attempted account size, in bytes | -| `minAccountSize` | `uint64` | The minimum expected account size, in bytes | +| `attemptedAccountSize` | `uint256` | The attempted account size, in bytes | +| `accountSize` | `uint64` | The expected account size, in bytes | diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/overview.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/overview.md index ef0ac50f3..167941117 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/overview.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/overview.md @@ -11,10 +11,11 @@ The withdrawal machinery lives partly on the [`Application`](../application.md) | Piece | Where | Role | |-------|-------|------| -| Foreclosure + withdrawal logic | [`Application`](../application.md) (`IApplicationForeclosure`, `IApplicationWithdrawal`) | `foreclose`, `proveAccountsDriveMerkleRoot`, `withdraw`, and the account/getter views | +| Foreclosure + withdrawal logic | [`Application`](../application.md) (`IApplication`) | `foreclose`, `proveAccountsDriveMerkleRoot`, `withdraw`, and the account/getter views | +| Deposit refunds | [`Application`](../application.md) + `IRefundOutputBuilder` | `issueRefund` recovers unprocessed portal deposits after foreclosure | | [`WithdrawalConfig`](./withdrawal-config.md) | passed to the `Application` constructor | Guardian, accounts-drive geometry, and the output builder to use | | [`IWithdrawalOutputBuilder`](./iwithdrawal-output-builder.md) | referenced by the config | Turns an account into a withdrawal output (static-called during `withdraw`) | -| [`UsdWithdrawalOutputBuilder`](./usd-withdrawal-output-builder.md) (+ [factory](./usd-withdrawal-output-builder-factory.md)) | one per ERC-20 token | The single-ERC-20 builder; emits a `DelegateCallVoucher` to a shared `SafeERC20Transfer` | +| [`UsdWithdrawalOutputBuilder`](./usd-withdrawal-output-builder.md) (+ [factory](./usd-withdrawal-output-builder-factory.md)) | one per ERC-20 token | The single-ERC-20 builder; emits a `DelegateCallVoucher` to a shared `SafeErc20Transfer` | ## The withdrawal flow, on-chain diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/usd-withdrawal-output-builder-factory.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/usd-withdrawal-output-builder-factory.md index b0df75c82..30c14bb5c 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/usd-withdrawal-output-builder-factory.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/usd-withdrawal-output-builder-factory.md @@ -2,15 +2,15 @@ id: usd-withdrawal-output-builder-factory title: UsdWithdrawalOutputBuilderFactory resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/withdrawal/UsdWithdrawalOutputBuilderFactory.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/withdrawal/UsdWithdrawalOutputBuilderFactory.sol title: UsdWithdrawalOutputBuilderFactory contract - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/withdrawal/IUsdWithdrawalOutputBuilderFactory.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/withdrawal/IUsdWithdrawalOutputBuilderFactory.sol title: IUsdWithdrawalOutputBuilderFactory interface --- **`UsdWithdrawalOutputBuilderFactory`** lets anyone deploy a [`UsdWithdrawalOutputBuilder`](./usd-withdrawal-output-builder.md) for a given ERC-20 token at a predictable address. Because these builders are **stateless**, it does not matter whether you deploy one yourself or reuse an existing one for the same token. The address is derived deterministically from the token and salt (using `CREATE2`). -The factory is constructed with a shared `SafeERC20Transfer` contract, which it passes to every builder it deploys (used as the delegate-call voucher destination). +The factory is constructed with a shared `SafeErc20Transfer` contract, which it passes to every builder it deploys (used as the delegate-call voucher destination). ## Functions @@ -64,7 +64,7 @@ Compute the deterministic address a builder for `token`/`salt` would have, wheth ### `getSafeErc20Transfer()` ```solidity -function getSafeErc20Transfer() external view returns (ISafeERC20Transfer safeErc20Transfer) +function getSafeErc20Transfer() external view returns (ISafeErc20Transfer safeErc20Transfer) ``` Get the shared safe ERC-20 transfer contract passed down to the builders (used as the delegate-call voucher destination). diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/usd-withdrawal-output-builder.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/usd-withdrawal-output-builder.md index 3405ed945..b33d530e2 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/usd-withdrawal-output-builder.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/usd-withdrawal-output-builder.md @@ -2,29 +2,31 @@ id: usd-withdrawal-output-builder title: UsdWithdrawalOutputBuilder resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/withdrawal/UsdWithdrawalOutputBuilder.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/withdrawal/UsdWithdrawalOutputBuilder.sol title: UsdWithdrawalOutputBuilder contract - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/withdrawal/IUsdWithdrawalOutputBuilder.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/withdrawal/IUsdWithdrawalOutputBuilder.sol title: IUsdWithdrawalOutputBuilder interface --- **`UsdWithdrawalOutputBuilder`** is a concrete [`IWithdrawalOutputBuilder`](./iwithdrawal-output-builder.md) for applications whose accounts drive denominates a **single ERC-20 token**. It is a stateless contract fixed to one token at construction; deploy one per token with the [factory](./usd-withdrawal-output-builder-factory.md). -For each account it produces a **`DelegateCallVoucher`** that delegate-calls a shared `SafeERC20Transfer` contract to move `balance` of the token to the account owner. +For each account it produces a **`DelegateCallVoucher`** that delegate-calls a shared `SafeErc20Transfer` contract to move `balance` of the token to the account owner. + +USD accounts are **exactly 32 bytes**: a little-endian `uint96` balance in the first 12 bytes, and the owner address in the last 20 bytes (no tail padding). Account encodings must end with the owner address so nodes can serve owner-to-account-index lookups. ## Functions ### `constructor()` ```solidity -constructor(ISafeERC20Transfer safeErc20Transfer, IERC20 usd) +constructor(ISafeErc20Transfer safeErc20Transfer, IERC20 usd) ``` **Parameters** | Name | Type | Description | |------|------|-------------| -| `safeErc20Transfer` | `ISafeERC20Transfer` | The shared safe-transfer contract used as the delegate-call destination | +| `safeErc20Transfer` | `ISafeErc20Transfer` | The shared safe-transfer contract used as the delegate-call destination | | `usd` | `IERC20` | The ERC-20 token this builder denominates withdrawals in | ### `token()` @@ -51,7 +53,7 @@ function buildWithdrawalOutput(address, bytes calldata account) returns (bytes memory output) ``` -Decode `account` as `(address user, uint256 balance)` and return a `DelegateCallVoucher` that, when executed by the application, calls `SafeERC20Transfer.safeTransfer(token, user, balance)`. +Decode `account` as `(address user, uint96 balance)` and return a `DelegateCallVoucher` that, when executed by the application, calls `SafeErc20Transfer.safeTransfer(token, user, balance)`. **Parameters** @@ -63,6 +65,6 @@ Decode `account` as `(address user, uint256 balance)` and return a `DelegateCall | Name | Type | Description | |------|------|-------------| -| `output` | `bytes` | An ABI-encoded `DelegateCallVoucher(destination, payload)` where `destination` is the `SafeERC20Transfer` contract and `payload` is `safeTransfer(token, user, balance)` | +| `output` | `bytes` | An ABI-encoded `DelegateCallVoucher(destination, payload)` where `destination` is the `SafeErc20Transfer` contract and `payload` is `safeTransfer(token, user, balance)` | -*Raises [`AccountTooShort`](./iwithdrawal-output-builder.md#accounttooshort) if the account cannot be decoded.* +*Raises [`InvalidAccountSize`](./iwithdrawal-output-builder.md#invalidaccountsize) if the account is not exactly 32 bytes.* diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/withdrawal-config.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/withdrawal-config.md index 079421295..919c7aad3 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/withdrawal-config.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/withdrawal/withdrawal-config.md @@ -2,9 +2,9 @@ id: withdrawal-config title: WithdrawalConfig resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/common/WithdrawalConfig.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/common/WithdrawalConfig.sol title: WithdrawalConfig struct - - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/library/LibWithdrawalConfig.sol + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9/src/library/LibWithdrawalConfig.sol title: LibWithdrawalConfig library --- diff --git a/cartesi-rollups_versioned_docs/version-2.0/api-reference/index.md b/cartesi-rollups_versioned_docs/version-2.0/api-reference/index.md index c41d72c45..524f84d3e 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/api-reference/index.md +++ b/cartesi-rollups_versioned_docs/version-2.0/api-reference/index.md @@ -6,7 +6,7 @@ resources: title: Off-chain implementation of the Cartesi Machine - url: https://github.com/cartesi/rollups-node title: Reference implementation of the Rollups Node - - url: https://github.com/cartesi/rollups-contracts/tree/v1.4.0/onchain/rollups/contracts + - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.9 title: Smart Contracts for Cartesi Rollups --- diff --git a/cartesi-rollups_versioned_docs/version-2.0/deployment/introduction.md b/cartesi-rollups_versioned_docs/version-2.0/deployment/introduction.md index 27a7039cc..bcd6dca6b 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/deployment/introduction.md +++ b/cartesi-rollups_versioned_docs/version-2.0/deployment/introduction.md @@ -2,9 +2,8 @@ id: introduction title: Introduction resources: - - url: https://github.com/cartesi/rollups-contracts/tree/v1.4.0/onchain/rollups/deployments - title: Supported networks - + - url: https://github.com/cartesi/rollups-contracts/releases/tag/v3.0.0-alpha.9 + title: Supported networks (deployment addresses) --- @@ -40,9 +39,9 @@ Deployment with a third-party service provider is under development and will be ## Supported networks -As stated above, the first step in deploying a new Cartesi dApp to a blockchain requires creating a smart contract on that network that uses the Cartesi Rollups smart contracts. Cartesi has already deployed the Rollups smart contracts to several networks for convenience. +As stated above, the first step in deploying a new Cartesi dApp to a blockchain requires creating a smart contract on that network that uses the Cartesi Rollups smart contracts. Cartesi publishes core contract deployment addresses with each [rollups-contracts release](https://github.com/cartesi/rollups-contracts/releases) (see the `deployment-addresses` artifact). -The table below shows the list of all [networks that are currently supported](https://usecannon.com/packages/cartesi-rollups) in the latest release: +The table below shows networks covered in recent releases: | Network Name | Chain ID | | ---------------- | -------- | diff --git a/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/standard.md b/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/standard.md index e43d24974..93969e18a 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/standard.md +++ b/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/standard.md @@ -112,12 +112,12 @@ Do not commit private keys. Use Docker secrets or a file-backed key in any envir 1. Deploy an authority with `cast`. Capture the returned address (the `sed` call normalizes it): ```shell - cast send "newAuthority(address,uint256)" \ - 10 --private-key --rpc-url \ + cast send "newAuthority(address,uint256,uint256)" \ + 10 --private-key --rpc-url \ --json | jq -r '.logs[-1].data' | sed 's/^0x000000000000000000000000/0x/' ``` - Factory, portal, and InputBox addresses for the target chain are listed under **Deployed contracts** below. + `claimStagingPeriod` is the number of base-layer blocks that must elapse after a claim is staged before it can be accepted. Factory, portal, and InputBox addresses for the target chain are listed under **Deployed contracts** below. 2. Register the snapshot against that authority: @@ -133,15 +133,9 @@ Do not commit private keys. Use Docker secrets or a file-backed key in any envir ## Deployed contracts -Rollups contract addresses for supported networks: +Rollups contract deployment addresses are published with each [rollups-contracts release](https://github.com/cartesi/rollups-contracts/releases) as `cartesi-rollups-contracts--deployment-addresses.tar.gz` (plaintext `.txt` files per chain and contract; JSON artifacts are deprecated). Devnet addresses ship in the Anvil state dump artifact for that release. -- [Cannon Devnet](https://usecannon.com/packages/cartesi-rollups/2.2.0/13370-main/deployment/contracts) -- [Ethereum Sepolia](https://usecannon.com/packages/cartesi-rollups/2.2.0/11155111-main/deployment/contracts) -- [Arbitrum Sepolia](https://usecannon.com/packages/cartesi-rollups/2.2.0/421614-main/deployment/contracts) -- [OP Sepolia](https://usecannon.com/packages/cartesi-rollups/2.2.0/11155420-main/deployment/contracts) -- [Base Sepolia](https://usecannon.com/packages/cartesi-rollups/2.2.0/84532-main/deployment/contracts) - -Use the Cannon package version that matches the contract suite your node was built against. +Cannon distribution of `@cartesi/rollups` has been discontinued; use the GitHub release assets or the Soldeer package instead. ## Accessing the node diff --git a/cartesi-rollups_versioned_docs/version-2.0/development/asset-handling.md b/cartesi-rollups_versioned_docs/version-2.0/development/asset-handling.md index f8c222c86..a60e26d4d 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/development/asset-handling.md +++ b/cartesi-rollups_versioned_docs/version-2.0/development/asset-handling.md @@ -15,10 +15,10 @@ As with any execution layer solution, a Cartesi Application that wants to manipu Currently, Cartesi Rollups support the following types of assets: - [Ether (ETH)](../api-reference/contracts/portals/EtherPortal.md) -- [ERC-20](../api-reference/contracts/portals/ERC20Portal.md) -- [ERC-721](../api-reference/contracts/portals/ERC721Portal.md) -- [ERC-1155 Single](../api-reference/contracts/portals/ERC1155SinglePortal.md) -- [ERC-1155 Batch](../api-reference/contracts/portals/ERC1155BatchPortal.md) +- [ERC-20](../api-reference/contracts/portals/Erc20Portal.md) +- [ERC-721](../api-reference/contracts/portals/Erc721Portal.md) +- [ERC-1155 Single](../api-reference/contracts/portals/Erc1155SinglePortal.md) +- [ERC-1155 Batch](../api-reference/contracts/portals/Erc1155BatchPortal.md) ![img](../../..//static/img/v2.0/onchain-contracts.jpg) diff --git a/cartesi-rollups_versioned_docs/version-2.0/getting-started/architecture.md b/cartesi-rollups_versioned_docs/version-2.0/getting-started/architecture.md index a3d80ce66..1921d9cfb 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/getting-started/architecture.md +++ b/cartesi-rollups_versioned_docs/version-2.0/getting-started/architecture.md @@ -78,10 +78,10 @@ The [CartesiDAppFactory](../api-reference/contracts/application-factory.md) cont Portal contracts facilitate the secure transfer of assets between the base layer and the Cartesi execution environment. Currently, Cartesi supports the following types of asset transfers: - [Ether (ETH)](../api-reference/contracts/portals/EtherPortal.md) -- [ERC-20 (Fungible tokens)](../api-reference/contracts/portals/ERC20Portal.md) -- [ERC-721 (Non-fungible tokens)](../api-reference/contracts/portals/ERC721Portal.md) -- [ERC-1155 Single transfers](../api-reference/contracts/portals/ERC1155SinglePortal.md) -- [ERC-1155 Batch transfers](../api-reference/contracts/portals/ERC1155BatchPortal.md) +- [ERC-20 (Fungible tokens)](../api-reference/contracts/portals/Erc20Portal.md) +- [ERC-721 (Non-fungible tokens)](../api-reference/contracts/portals/Erc721Portal.md) +- [ERC-1155 Single transfers](../api-reference/contracts/portals/Erc1155SinglePortal.md) +- [ERC-1155 Batch transfers](../api-reference/contracts/portals/Erc1155BatchPortal.md) These Portal contracts implement the logic to "teleport" assets safely between layers, maintaining their integrity and ownership throughout the transfer process. diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-1155-token-wallet.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-1155-token-wallet.md index faf72a2ca..73bbdf887 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-1155-token-wallet.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-1155-token-wallet.md @@ -272,7 +272,7 @@ Tokens deposited through the portals are held by your on-chain `Application` con Create `src/index.ts` to wire deposits from both portals and user operations sent as JSON inputs. :::note Portal addresses -Run [`cartesi address-book`](../development/send-inputs-and-assets.md) and copy the `ERC1155SinglePortal` and `ERC1155BatchPortal` addresses into `index.ts`. Do not hardcode portal addresses—they differ by CLI version and chain. +Run [`cartesi address-book`](../development/send-inputs-and-assets.md) and copy the `Erc1155SinglePortal` and `Erc1155BatchPortal` addresses into `index.ts`. Do not hardcode portal addresses—they differ by CLI version and chain. ::: ```typescript @@ -525,7 +525,7 @@ cartesi run ### Deposits :::caution token approvals -ERC-1155 uses `setApprovalForAll` on the token contract for each portal operator. Approve **both** [`ERC1155SinglePortal`](../api-reference/contracts/portals/ERC1155SinglePortal.md) and [`ERC1155BatchPortal`](../api-reference/contracts/portals/ERC1155BatchPortal.md) before depositing through the corresponding portal. +ERC-1155 uses `setApprovalForAll` on the token contract for each portal operator. Approve **both** [`Erc1155SinglePortal`](../api-reference/contracts/portals/Erc1155SinglePortal.md) and [`Erc1155BatchPortal`](../api-reference/contracts/portals/Erc1155BatchPortal.md) before depositing through the corresponding portal. ::: **Single deposit** — interactively: diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-20-token-wallet.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-20-token-wallet.md index b21f4e91d..9e11f80fa 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-20-token-wallet.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-20-token-wallet.md @@ -251,10 +251,10 @@ The `withdrawErc20` method encodes `transferFrom(application, recipient, amount) Now, let's create a simple application at the entry point `src/index.ts` to test the wallet’s functionality. -The [`ERC20Portal`](../api-reference/contracts/portals/ERC20Portal.md) contract moves ERC-20 tokens from the base layer into your application. Deposits arrive as advances whose `metadata.msg_sender` is the portal address. +The [`Erc20Portal`](../api-reference/contracts/portals/Erc20Portal.md) contract moves ERC-20 tokens from the base layer into your application. Deposits arrive as advances whose `metadata.msg_sender` is the portal address. :::note ERC20Portal address -Run [`cartesi address-book`](../development/send-inputs-and-assets.md) and copy the `ERC20Portal` address for your network into `index.ts`. Do not hardcode portal addresses—they differ by CLI version and chain. +Run [`cartesi address-book`](../development/send-inputs-and-assets.md) and copy the `Erc20Portal` address for your network into `index.ts`. Do not hardcode portal addresses—they differ by CLI version and chain. ::: ```typescript @@ -278,7 +278,7 @@ export type Report = components["schemas"]["Report"]; export type Voucher = components["schemas"]["Voucher"]; const wallet = new Wallet(); -// Replace with the ERC20Portal address from `cartesi address-book` +// Replace with the Erc20Portal address from `cartesi address-book` const ERC20Portal = `0xYOUR_ERC20_PORTAL_ADDRESS`; const rollupServer = process.env.ROLLUP_HTTP_SERVER_URL; @@ -425,7 +425,7 @@ main().catch((e) => { Here is a breakdown of the wallet functionality: -- We handle deposits when the sender is the `ERC20Portal`. +- We handle deposits when the sender is the `Erc20Portal`. - We parse the payload for other senders to determine the operation (`transfer` or `withdraw`). @@ -452,13 +452,13 @@ cartesi run ### Deposits :::caution token approvals -An approval step is needed for the [**ERC20 token standard**](https://ethereum.org/en/developers/docs/standards/tokens/). This ensures you grant explicit permission for `ERC20Portal` to transfer tokens on your behalf. +An approval step is needed for the [**ERC20 token standard**](https://ethereum.org/en/developers/docs/standards/tokens/). This ensures you grant explicit permission for `Erc20Portal` to transfer tokens on your behalf. -Without this approval, the `ERC20Portal` cannot deposit your tokens to the Cartesi backend. +Without this approval, the `Erc20Portal` cannot deposit your tokens to the Cartesi backend. -You will encounter this error if you don't approve the `ERC20Portal` address before deposits: +You will encounter this error if you don't approve the `Erc20Portal` address before deposits: -`ContractFunctionExecutionError: The contract function "depositERC20Tokens" reverted with the following reason: ERC20: insufficient allowance` +`ContractFunctionExecutionError: The contract function "depositErc20Tokens" reverted with the following reason: ERC20: insufficient allowance` ::: To deposit ERC20 tokens interactively: diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-721-token-wallet.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-721-token-wallet.md index 0267195ba..c9b7f025f 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-721-token-wallet.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/erc-721-token-wallet.md @@ -229,10 +229,10 @@ The `withdrawErc721` method encodes `safeTransferFrom(application, recipient, to Now, let's create a simple application at the entry point `src/index.ts` to test the wallet’s functionality. -The [`ERC721Portal`](../api-reference/contracts/portals/ERC721Portal.md) contract moves ERC-721 tokens from the base layer into your application. Deposits arrive as advances whose `metadata.msg_sender` is the portal address. +The [`Erc721Portal`](../api-reference/contracts/portals/Erc721Portal.md) contract moves ERC-721 tokens from the base layer into your application. Deposits arrive as advances whose `metadata.msg_sender` is the portal address. :::note ERC721Portal address -Run [`cartesi address-book`](../development/send-inputs-and-assets.md) and copy the `ERC721Portal` address for your network into `index.ts`. Do not hardcode portal addresses—they differ by CLI version and chain. +Run [`cartesi address-book`](../development/send-inputs-and-assets.md) and copy the `Erc721Portal` address for your network into `index.ts`. Do not hardcode portal addresses—they differ by CLI version and chain. ::: ```typescript @@ -256,7 +256,7 @@ export type Report = components["schemas"]["Report"]; export type Voucher = components["schemas"]["Voucher"]; const wallet = new Wallet(); -// Replace with the ERC721Portal address from `cartesi address-book` +// Replace with the Erc721Portal address from `cartesi address-book` const ERC721Portal = `0xYOUR_ERC721_PORTAL_ADDRESS`; const rollupServer = process.env.ROLLUP_HTTP_SERVER_URL; @@ -396,7 +396,7 @@ main().catch((e) => { Here is a breakdown of the wallet functionality: -- We handle deposits when the sender is the `ERC721Portal`. +- We handle deposits when the sender is the `Erc721Portal`. - We parse the payload for other senders to determine the operation (`transfer` or `withdraw`). @@ -423,13 +423,13 @@ cartesi run ### Deposits :::caution token approvals -An approval step is needed for the [**ERC721 token standard**](https://ethereum.org/en/developers/docs/standards/tokens/). This ensures you grant explicit permission for `ERC721Portal` to transfer tokens on your behalf. +An approval step is needed for the [**ERC721 token standard**](https://ethereum.org/en/developers/docs/standards/tokens/). This ensures you grant explicit permission for `Erc721Portal` to transfer tokens on your behalf. -Without this approval, the `ERC721Portal` cannot deposit your tokens to the Cartesi backend. +Without this approval, the `Erc721Portal` cannot deposit your tokens to the Cartesi backend. -You will encounter this error if you don't approve the `ERC721Portal` address before deposits: +You will encounter this error if you don't approve the `Erc721Portal` address before deposits: -`ContractFunctionExecutionError: The contract function "depositERC721Tokens" reverted with the following reason: ERC721: insufficient allowance` +`ContractFunctionExecutionError: The contract function "depositErc721Tokens" reverted with the following reason: ERC721: insufficient allowance` ::: To deposit ERC721 tokens interactively: diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/snippets/marketplace-js.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/snippets/marketplace-js.md index 757f1b2a5..f42fac3c3 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/snippets/marketplace-js.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/snippets/marketplace-js.md @@ -78,7 +78,7 @@ class Storage { this.users_erc20_token_balance.set(addr, current - BigInt(amount)); } - depositERC721Token(userAddress, tokenId) { + depositErc721Token(userAddress, tokenId) { const addr = normAddr(userAddress); const tid = asBigInt(tokenId); this.erc721_id_to_owner_address.set(tid, addr); @@ -155,7 +155,7 @@ async function handleERC20Deposit(depositorAddress, amountDeposited, tokenAddres async function handleERC721Deposit(depositorAddress, tokenId, tokenAddress) { if (normAddr(tokenAddress) === normAddr(storage.erc721_token)) { try { - storage.depositERC721Token(depositorAddress, tokenId); + storage.depositErc721Token(depositorAddress, tokenId); storage.listTokenForSale(tokenId); console.log("Token deposit and Listing processed successfully"); emitNotice("Token ID: " + tokenId + " Deposited by User: " + depositorAddress) diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/snippets/marketplace-py.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/snippets/marketplace-py.md index 02c7e1d9f..4250c5ec0 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/snippets/marketplace-py.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/snippets/marketplace-py.md @@ -172,7 +172,7 @@ class Storage: self.users_erc20_token_balance[addr] = current - amt return True - def depositERC721Token(self, userAddress: str, tokenId): + def depositErc721Token(self, userAddress: str, tokenId): addr = norm_addr(userAddress) tid = as_int(tokenId) zero_addr = "0x" + "0" * 40; @@ -257,7 +257,7 @@ def handle_erc20_deposit(depositor_address: str, amount_deposited, token_address def handle_erc721_deposit(depositor_address: str, token_id, token_address: str): if norm_addr(token_address) == storage.erc721_token: try: - storage.depositERC721Token(depositor_address, as_int(token_id)) + storage.depositErc721Token(depositor_address, as_int(token_id)) storage.listTokenForSale(token_id) logger.info("Token Listed Successfully") emitNotice(f"Token ID: {token_id} Deposited by User: {depositor_address}") diff --git a/cartesi-rollups_versioned_docs/version-2.0/tutorials/utilizing-the-cli-test-tokens.md b/cartesi-rollups_versioned_docs/version-2.0/tutorials/utilizing-the-cli-test-tokens.md index b360c8347..daa5f2c5c 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/tutorials/utilizing-the-cli-test-tokens.md +++ b/cartesi-rollups_versioned_docs/version-2.0/tutorials/utilizing-the-cli-test-tokens.md @@ -123,9 +123,9 @@ For a successful deposit process you should show logs similar to this: #### Using Cast -It's also possible to use cast commands to deposit assets to your application, but this would require a more manual process of granting approval, then calling the deposit function in the ERC20Portal contract. Below is a step-by-step process to achieve this: +It's also possible to use cast commands to deposit assets to your application, but this would require a more manual process of granting approval, then calling the deposit function in the Erc20Portal contract. Below is a step-by-step process to achieve this: -- Call the `testToken` contract to approve the `ERC20Portal` an equivalent of the amount of tokens you intend to deposit, using the below command +- Call the `testToken` contract to approve the `Erc20Portal` an equivalent of the amount of tokens you intend to deposit, using the below command @@ -153,7 +153,7 @@ cast send 0xFBdB734EF6a23aD76863CbA6f10d0C5CBBD8342C "approve(address,uint256)" The snippet above is an example of how to deposit 300 units of the test tokens, `http://127.0.0.1:6751/anvil` is the anvil_rpc to the local devnet where the application contract is deployed, finally the private_key `0xac0974bec39a17...e784d7bf4f2ff80` is the private key of the default anvil address which is also the owner of the erc20 test contract. -- Call the `depositERC20Tokens` function in the `ERC20Portal` contract, passing in the address of your contract along with the token address and amount of tokens deposited +- Call the `depositErc20Tokens` function in the `Erc20Portal` contract, passing in the address of your contract along with the token address and amount of tokens deposited @@ -161,7 +161,7 @@ The snippet above is an example of how to deposit 300 units of the test tokens, 

 
 ```bash
-cast send  "depositERC20Tokens(address,address,uint256,bytes)"     --rpc-url  --private-key 
+cast send  "depositErc20Tokens(address,address,uint256,bytes)"     --rpc-url  --private-key 
 ```
@@ -171,7 +171,7 @@ cast send "depositERC20Tokens(address,address,uint256,byte 

 
 ```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
 ```
@@ -179,7 +179,7 @@ cast send 0xc700D6aDd016eECd59d989C028214Eaa0fCC0051 "depositERC20Tokens(address -The above command interacts with the ERC20Portal which utilizes the allowance issued in the previous function to call the `transferFrom` function in the `testToken` contract. This operation transfers the amount of tokens listed to the application contract, and calls the input box to send an input to your application. +The above command interacts with the Erc20Portal which utilizes the allowance issued in the previous function to call the `transferFrom` function in the `testToken` contract. This operation transfers the amount of tokens listed to the application contract, and calls the input box to send an input to your application. The next section covers implementations on your application to handle deposits. @@ -688,9 +688,9 @@ For a successful deposit process you should get a log similar to this below: #### Using Cast -It's also possible to deposit the ERC721 test tokens to your application using Cast, this process, requires a more manual approach and happens in 2 phases, one is granting approval to the ERC721Portal then the second is calling the `depositERC721Token` function in the ERC721Portal contract. Below is a step-by-step process for this: +It's also possible to deposit the ERC721 test tokens to your application using Cast, this process, requires a more manual approach and happens in 2 phases, one is granting approval to the Erc721Portal then the second is calling the `depositErc721Token` function in the Erc721Portal contract. Below is a step-by-step process for this: -- Grant the `ERC721Portal` contract approval +- Grant the `Erc721Portal` contract approval @@ -716,9 +716,9 @@ cast send 0xBa46623aD94AB45850c4ecbA9555D26328917c3B "setApprovalForAll(address, -The above command calls the `testNFT` contract `0xBa46...8917c3B` to approve the `ERC721Portal` `0xc700d5...0051` to withdraw tokens to be deposited to your application, the arguments listed above should be the same if you intend to deposit the `testNFT` token, for other ERC721 tokens, then you could change the token address to match the tokens you intend to transfer. +The above command calls the `testNFT` contract `0xBa46...8917c3B` to approve the `Erc721Portal` `0xc700d5...0051` to withdraw tokens to be deposited to your application, the arguments listed above should be the same if you intend to deposit the `testNFT` token, for other ERC721 tokens, then you could change the token address to match the tokens you intend to transfer. -- Call the `depositERC721Token` function in the ERC721Portal contract +- Call the `depositErc721Token` function in the Erc721Portal contract @@ -726,7 +726,7 @@ The above command calls the `testNFT` contract `0xBa46...8917c3B` to approve the 

 
 ```bash
-cast send  "depositERC721Token(address,address,uint256,bytes,bytes)"        --rpc-url  --private-key 
+cast send  "depositErc721Token(address,address,uint256,bytes,bytes)"        --rpc-url  --private-key 
 ```
@@ -736,7 +736,7 @@ cast send "depositERC721Token(address,address,uint256,byt 

 
 ```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
 ```
@@ -744,7 +744,7 @@ cast send 0xc700d52F5290e978e9CAe7D1E092935263b60051 "depositERC721Token(address -From the above command we call the `depositERC721Token` function in the `ERC721Portal` contract `0xc700...60051`, passing the `testNFT` contract `0xBa46...8917c3B`, the `Application contract address` `0x23eff...560fc`, the token_id `4` and finally the optional baseLayer and executionLayer data `0x` and `0x`. For this implementation it's expected that the token_id passed to the function should already be minted and owned by the wallet whose private key is used to sign the transaction. +From the above command we call the `depositErc721Token` function in the `Erc721Portal` contract `0xc700...60051`, passing the `testNFT` contract `0xBa46...8917c3B`, the `Application contract address` `0x23eff...560fc`, the token_id `4` and finally the optional baseLayer and executionLayer data `0x` and `0x`. For this implementation it's expected that the token_id passed to the function should already be minted and owned by the wallet whose private key is used to sign the transaction. #### Handling Deposited ERC721 tokens @@ -1234,7 +1234,7 @@ cartesi deposit #### Using Cast -- Grant the `ERC1155SinglePortal` contract approval +- Grant the `Erc1155SinglePortal` contract approval @@ -1260,7 +1260,7 @@ cast send 0xDC6d64971B77a47fB3E3c6c409D4A05468C398D2 "setApprovalForAll(address, -- Call the `depositSingleERC1155Token` function in the ERC1155SinglePortal contract +- Call the `depositSingleErc1155Token` function in the Erc1155SinglePortal contract @@ -1268,7 +1268,7 @@ cast send 0xDC6d64971B77a47fB3E3c6c409D4A05468C398D2 "setApprovalForAll(address, 

 
 ```bash
-cast send  "depositSingleERC1155Token(address,address,uint256,uint256,bytes,bytes)"         ---rpc-url  --private-key 
+cast send  "depositSingleErc1155Token(address,address,uint256,uint256,bytes,bytes)"         ---rpc-url  --private-key 
 ```
@@ -1278,7 +1278,7 @@ cast send "depositSingleERC1155Token(addr 

 
 ```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
 ```
diff --git a/cartesi-rollups_versioned_sidebars/version-2.0-sidebars.json b/cartesi-rollups_versioned_sidebars/version-2.0-sidebars.json index a70320c08..ae9f4de83 100644 --- a/cartesi-rollups_versioned_sidebars/version-2.0-sidebars.json +++ b/cartesi-rollups_versioned_sidebars/version-2.0-sidebars.json @@ -30,10 +30,10 @@ "collapsed": true, "items": [ "api-reference/contracts/portals/EtherPortal", - "api-reference/contracts/portals/ERC20Portal", - "api-reference/contracts/portals/ERC721Portal", - "api-reference/contracts/portals/ERC1155SinglePortal", - "api-reference/contracts/portals/ERC1155BatchPortal" + "api-reference/contracts/portals/Erc20Portal", + "api-reference/contracts/portals/Erc721Portal", + "api-reference/contracts/portals/Erc1155SinglePortal", + "api-reference/contracts/portals/Erc1155BatchPortal" ] }, { From 7eb25daba37edb14dd4ba1b3ccf73a38094f0582 Mon Sep 17 00:00:00 2001 From: Shaheen Date: Mon, 24 Aug 2026 16:23:40 +0530 Subject: [PATCH 3/4] docs(v2): fix self-hosted and EW guides for working testnet deploy 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 --- .../version-2.0/deployment/introduction.md | 2 + .../deployment/self-hosted/standard.md | 117 +++++++++++------- .../self-hosted/with-emergency-withdrawal.md | 82 +++++++----- .../deployment/src/compose.local.yaml | 44 +++---- .../emergency-withdrawal/lifecycle.md | 8 +- .../emergency-withdrawal/overview.md | 4 +- .../emergency-withdrawal/recovery-guide.md | 47 ++++--- .../version-2.0/resources/migration-guide.md | 4 - .../version-2.0-sidebars.json | 12 +- 9 files changed, 192 insertions(+), 128 deletions(-) diff --git a/cartesi-rollups_versioned_docs/version-2.0/deployment/introduction.md b/cartesi-rollups_versioned_docs/version-2.0/deployment/introduction.md index bcd6dca6b..92a1f2beb 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/deployment/introduction.md +++ b/cartesi-rollups_versioned_docs/version-2.0/deployment/introduction.md @@ -33,6 +33,8 @@ There are two methods to deploy an application: 1. [Self-hosted deployment](./self-hosted/overview.md): Deploy the application node using your infrastructure 2. Third-party service provider: Outsource running the application node to a service provider +Applications that custody assets should follow [Deployment with emergency withdrawal](./self-hosted/with-emergency-withdrawal.md) so a guardian can foreclose and users can recover funds without a live operator. + :::caution important Deployment with a third-party service provider is under development and will be available soon. ::: diff --git a/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/standard.md b/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/standard.md index 93969e18a..02a62d40b 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/standard.md +++ b/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/standard.md @@ -5,7 +5,7 @@ title: Self-hosted deployment (standard) -This guide explains how to run a Cartesi Rollups node on your machine for **testnet** development and testing. +This guide explains how to run a Cartesi Rollups node locally on your machine for development and testing on **testnet**. :::warning Production Warning **Do not use this compose file as a production deployment.** @@ -13,37 +13,12 @@ This guide explains how to run a Cartesi Rollups node on your machine for **test It is a testnet-oriented starting point. It does not include public snapshot verification, production-grade secrets, high availability, or hardened Postgres. ::: -## Node topology - -The [Mugen-Builders compose file](https://github.com/Mugen-Builders/deployment-setup-v2.0) already runs **one process per container**, not a single combined node: - -| Service | Role | -| :-- | :-- | -| `database` | Postgres | -| `evm-reader` | Reads L1 inputs and related events | -| `advancer` | Runs the Cartesi Machine; serves inspect | -| `validator` | Computes epoch claims and proofs | -| `claimer` | Submits claims on-chain | -| `jsonrpc-api` | JSON-RPC query API | - -Keep that split. Do not collapse reader, advancer, validator, claimer, and JSON-RPC into one process except for short local experiments. - -The sample compose shares one Postgres role (`postgres`) and one database (`rollupsdb`). That is acceptable only for this testnet compose. 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. - -The EVM reader **polls HTTP**. `BLOCKCHAIN_HTTP_ENDPOINT` is required. A WebSocket endpoint is optional and is not required for reading blocks. - -Pin runtime and database image tags to the rollups-node release you intend to run. The compose file on GitHub may lag a newer node alpha. - ## Prerequisites -- Cartesi CLI 2.0 (currently alpha) +- Cartesi CLI 2.0 - Docker Desktop 4.x (Compose and Buildx) -- Cartesi CLI: An easy-to-use tool for developing and deploying your dApps. - -- Docker Desktop 4.x: The required tool to distribute the Cartesi Rollups framework and its dependencies. - -For more details about the installation process for each of these tools, please refer to the [this section](../../development/installation.md). +See [installation](../../development/installation.md). ## Configuration @@ -51,10 +26,10 @@ Create a `.env` file in the project root: ```shell BLOCKCHAIN_ID= -AUTH_KIND="private_key" -CARTESI_AUTH_PRIVATE_KEY="" -BLOCKCHAIN_HTTP_ENDPOINT="" -CARTESI_BLOCKCHAIN_DEFAULT_BLOCK="" +AUTH_KIND=private_key +CARTESI_AUTH_PRIVATE_KEY= +BLOCKCHAIN_HTTP_ENDPOINT= +CARTESI_BLOCKCHAIN_DEFAULT_BLOCK=latest ``` | Variable | Description | @@ -63,7 +38,11 @@ CARTESI_BLOCKCHAIN_DEFAULT_BLOCK="" | `BLOCKCHAIN_HTTP_ENDPOINT` | HTTP JSON-RPC endpoint for the base layer | | `AUTH_KIND` | `private_key` for local and testnet experiments | | `CARTESI_AUTH_PRIVATE_KEY` | Funded private key for the selected chain | -| `CARTESI_BLOCKCHAIN_DEFAULT_BLOCK` | `latest` or `finalized` | +| `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`. + +Factory addresses default to cartesi-rollups 3.0.0-alpha.6 in the compose file. Override them in `.env` only if you are not using that suite. :::danger Security Do not commit private keys. Use Docker secrets or a file-backed key in any environment that is not a throwaway testnet. @@ -81,63 +60,105 @@ Do not commit private keys. Use Docker secrets or a file-backed key in any envir ```shell cartesi build + cartesi hash ``` + `cartesi build` writes the machine to `.cartesi/image/`. `cartesi hash` prints the template hash (`0x…`). Current CLI snapshots do not write `.cartesi/image/hash`, which `cartesi-rollups-cli` still reads by default, so pass `--template-hash` in the deploy step. + 3. **Start the stack:** ```shell docker compose -f compose.local.yaml --env-file .env up -d + docker compose -f compose.local.yaml exec advancer cartesi-rollups-node --version ``` + Expect `cartesi-rollups-node version 2.0.0-alpha.12`. All six services should be running. + 4. **Deploy and register the application:** ```shell - docker compose --project-name cartesi-rollups-node \ - exec advancer cartesi-rollups-cli deploy application /var/lib/cartesi-rollups-node/snapshot \ + docker compose -f compose.local.yaml exec advancer \ + cartesi-rollups-cli deploy application /var/lib/cartesi-rollups-node/snapshot \ --epoch-length 10 \ --salt \ + --template-hash \ --register ``` - Replace `` with the application name. The salt must be unique. Generate one with: + Replace `` with the application name and `` with the value from `cartesi hash`. The salt must be unique. Generate one with: ```shell cast keccak256 "your-unique-string" ``` - If deployment fails, fall back to deploying authority and application contracts separately. + On success the command prints the application contract address and registers the app on the node. + + If the combined self-hosted factory deploy fails with `execution reverted`, fall back to deploying authority and application separately (see below). Emergency-withdrawal apps should use that two-step path from the start; see [Deployment with emergency withdrawal](./with-emergency-withdrawal.md). ### Manual deployment fallback - 1. Deploy an authority with `cast`. Capture the returned address (the `sed` call normalizes it): + 1. Deploy an authority with the CLI (preferred) or with `cast`. With the CLI: + + ```shell + docker compose -f compose.local.yaml exec advancer \ + cartesi-rollups-cli deploy authority --claim-staging-period + ``` + + Or with `cast` (capture the returned address; the `sed` call normalizes it): ```shell cast send "newAuthority(address,uint256,uint256)" \ - 10 --private-key --rpc-url \ + 10 --private-key --rpc-url \ --json | jq -r '.logs[-1].data' | sed 's/^0x000000000000000000000000/0x/' ``` - `claimStagingPeriod` is the number of base-layer blocks that must elapse after a claim is staged before it can be accepted. Factory, portal, and InputBox addresses for the target chain are listed under **Deployed contracts** below. + `claimStagingPeriod` is the number of base-layer blocks that must elapse after a claim is staged before it can be accepted. Factory addresses are listed under **Deployed contracts** below. - 2. Register the snapshot against that authority: + 2. Deploy the application against that authority: ```shell - docker compose --project-name cartesi-rollups-node \ - exec advancer cartesi-rollups-cli deploy application /var/lib/cartesi-rollups-node/snapshot \ + docker compose -f compose.local.yaml exec advancer \ + cartesi-rollups-cli deploy application /var/lib/cartesi-rollups-node/snapshot \ --epoch-length 10 \ --consensus \ - --json + --salt \ + --template-hash \ + --register ``` On success the command returns the application contract address. ## Deployed contracts -Rollups contract deployment addresses are published with each [rollups-contracts release](https://github.com/cartesi/rollups-contracts/releases) as `cartesi-rollups-contracts--deployment-addresses.tar.gz` (plaintext `.txt` files per chain and contract; JSON artifacts are deprecated). Devnet addresses ship in the Anvil state dump artifact for that release. +This node version uses **cartesi-rollups 3.0.0-alpha.6**. Infrastructure addresses are identical on Ethereum, Optimism, Arbitrum, and Base (mainnet and Sepolia). Only `BLOCKCHAIN_ID` and the HTTP RPC URL change per chain. -Cannon distribution of `@cartesi/rollups` has been discontinued; use the GitHub release assets or the Soldeer package instead. +| Contract | Address | +| :-- | :-- | +| InputBox | `0x346B3df038FE9f8380071eC6514D5a83aD143939` | +| AuthorityFactory | `0x3C1FE01c542a88A523FF6847eD1E26176c8C4ED0` | +| ApplicationFactory | `0xC549F89cF1ca43eDDECC64Ac2208F4b283B1c483` | +| SelfHostedApplicationFactory | `0x6145C5996a71a379E030aEb0440df79D60833418` | +| QuorumFactory | `0x1f94009389F408B8D0ADfFcF8BBDCe5552BaCa5F` | +| ERC20Portal | `0x22E57511C30CcE6CDaa742E13CE3b774fDC663b1` | + +Rollups contract deployment addresses are also published with each [rollups-contracts release](https://github.com/cartesi/rollups-contracts/releases) as `cartesi-rollups-contracts--deployment-addresses.tar.gz`. Use the suite that matches the node you run; API reference pages may track a newer contracts alpha than this compose pin. ## Accessing the node -- Inspect: `http://localhost:10012/inspect/` -- JSON-RPC: `http://localhost:10011/rpc` +Once running, your local Cartesi Rollups Node will be accessible through the standard APIs: + +- Inspect endpoint: `http://localhost:10012/inspect/` + +```shell +curl -s -X POST "http://localhost:10012/inspect/" \ + -H "Content-Type: application/json" \ + -d '{"payload":"0x"}' +``` + +- JSON-RPC is `http://localhost:10011/rpc`: + +```shell +curl -s -X POST http://localhost:10011/rpc \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"cartesi_listInputs","params":[""],"id":1}' +``` diff --git a/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/with-emergency-withdrawal.md b/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/with-emergency-withdrawal.md index 46eb6d9ad..871941ed3 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/with-emergency-withdrawal.md +++ b/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/with-emergency-withdrawal.md @@ -3,6 +3,8 @@ id: with-emergency-withdrawal title: Self-hosted with Emergency Withdrawal --- + + This guide runs a self-hosted node and deploys an application that supports [emergency withdrawal](../../development/emergency-withdrawal/overview.md): a guardian can foreclose it, and users can then recover their funds directly from the contracts. It follows the same flow as the [standard deployment](./standard.md), with a few additions. Read the [Foreclosure & Emergency Withdrawal overview](../../development/emergency-withdrawal/overview.md) first for the concept. :::warning Production Warning @@ -15,7 +17,7 @@ In addition to the [standard prerequisites](./standard.md#prerequisites) (Cartes - A **guardian** address. This account, and only this account, can foreclose the application. - A **withdrawal output builder** for your token. For a single ERC-20, deploy one with the [`UsdWithdrawalOutputBuilderFactory`](../../api-reference/contracts/withdrawal/usd-withdrawal-output-builder-factory.md), or reuse an existing one for the same token. Note its address. -- An application whose guest maintains an **accounts drive** in a known layout. See [Emergency Withdrawal (guest requirements)](../../api-reference/backend/emergency-withdrawal.md). +- An application whose guest maintains an **accounts drive** in a known layout. A generic echo application cannot be withdrawal-enabled. See [Emergency Withdrawal (guest requirements)](../../api-reference/backend/emergency-withdrawal.md). ## Configure the machine and ledger (`cartesi.toml`) @@ -23,86 +25,102 @@ For an application to support emergency withdrawal, its Cartesi Machine must inc Because those choices (the drive declaration, its size and position, and the record layout) belong to the guest application, they are documented once, in full, on the guest-requirements page. Set the drive up as described in [Creating the accounts drive](../../api-reference/backend/emergency-withdrawal.md#creating-the-accounts-drive) before continuing, and see [Keeping the balances](../../api-reference/backend/emergency-withdrawal.md#keeping-the-balances) for the ledger library. +Build the machine against the portal and token you will deposit on that chain. A template compiled for a different portal will reject deposits. + ## Configuration -Configure your `.env` file exactly as in the standard flow: +Configure your `.env` file exactly as in the [standard flow](./standard.md#configuration). Do **not** set a WebSocket endpoint with node alpha.12: ```shell BLOCKCHAIN_ID= -AUTH_KIND="private_key" -CARTESI_AUTH_PRIVATE_KEY="" -BLOCKCHAIN_WS_ENDPOINT="" -BLOCKCHAIN_HTTP_ENDPOINT="" -CARTESI_BLOCKCHAIN_DEFAULT_BLOCK="" +AUTH_KIND=private_key +CARTESI_AUTH_PRIVATE_KEY= +BLOCKCHAIN_HTTP_ENDPOINT= +CARTESI_BLOCKCHAIN_DEFAULT_BLOCK=latest ``` -| Variable | Description | -| ---------------------------------- | -------------------------------------------------------------------- | -| `BLOCKCHAIN_ID` | Your blockchain network ID | -| `BLOCKCHAIN_WS_ENDPOINT` | Your WebSocket endpoint | -| `BLOCKCHAIN_HTTP_ENDPOINT` | Your HTTP endpoint | -| `AUTH_KIND` | Set to `private_key` for local development | -| `CARTESI_AUTH_PRIVATE_KEY` | A funded private key for the selected chain | -| `CARTESI_BLOCKCHAIN_DEFAULT_BLOCK` | Set to either `latest` or `finalized` | - :::danger Security -Follow best practices when handling private keys during local development and deployment. +Do not commit private keys. The guardian key used later for foreclosure can differ from `CARTESI_AUTH_PRIVATE_KEY`; keep both out of source control. ::: ## Prepare the withdrawal config -Create a `withdrawal.json` describing the guardian and the accounts-drive layout. These values must match what your guest application actually writes (see [WithdrawalConfig](../../api-reference/contracts/withdrawal/withdrawal-config.md#drive-geometry)): +Create a `withdrawal.json` describing the guardian and the accounts-drive layout. All fields are required when withdrawal config is supplied. These values must match what your guest application actually writes (see [WithdrawalConfig](../../api-reference/contracts/withdrawal/withdrawal-config.md#drive-geometry)): ```json { "guardian": "", "log2_leaves_per_account": 0, - "log2_max_num_of_accounts": 12, - "accounts_drive_start_index": 309237645312, + "log2_max_num_of_accounts": 17, + "accounts_drive_start_index": 0, "withdrawal_output_builder": "" } ``` +Derive `accounts_drive_start_index` from the stored machine. For a 4 MiB accounts drive: + +```shell +jq -r '.config.flash_drive[] | select(.length == 4194304) | (.start / 4194304 | floor)' \ + .cartesi/image/config.json +``` + +Do not leave the index as a placeholder `0` unless that is the real value from `config.json`. + ## Setting up the local node -1. **Download the Cartesi Rollups Node docker compose file in your project root:** +1. **Download the compose file into the project root** (alongside `.cartesi/`): ```shell curl -L https://raw.githubusercontent.com/Mugen-Builders/deployment-setup-v2.0/main/compose.local.yaml -o compose.local.yaml ``` - This is the same compose file used by the standard flow. It already includes the machine-tool service used later for recovery, so there is nothing extra to add. + This is the same compose file used by the standard flow. There is no separate machine-tool service: `cartesi-rollups-machine-tool` ships inside `cartesi/rollups-runtime` and is invoked with `docker compose … exec advancer` during recovery. -2. **Build the application with the Cartesi CLI:** +2. **Build the application snapshot:** ```shell cartesi build + cartesi hash ``` - This compiles your application into RISC-V and creates a Cartesi machine snapshot locally. Make sure your application maintains its accounts drive in the layout described by `withdrawal.json`. + Make sure your application maintains its accounts drive in the layout described by `withdrawal.json`. Pass the printed template hash to deploy. -3. **Run the Cartesi Rollups Node with the application's initial snapshot attached:** +3. **Start the stack:** ```shell docker compose -f compose.local.yaml --env-file .env up -d ``` -4. **Deploy and register the application with its withdrawal config:** +4. **Deploy authority, then the application with its withdrawal config:** - Make the config file readable inside the `advancer` container, then deploy with `--withdrawal-config-file`: + The combined self-hosted factory call (`deploy application` with no `--consensus`) currently reverts on alpha.12, with or without withdrawal config. Deploy the authority first, then the application against that consensus. + + Copy the config into the `advancer` container, then deploy: ```shell - docker compose --project-name cartesi-rollups-node cp withdrawal.json advancer:/tmp/withdrawal.json + docker compose -f compose.local.yaml cp withdrawal.json advancer:/tmp/withdrawal.json + + docker compose -f compose.local.yaml exec advancer \ + cartesi-rollups-cli deploy authority --claim-staging-period - docker compose --project-name cartesi-rollups-node \ - exec advancer cartesi-rollups-cli deploy application /var/lib/cartesi-rollups-node/snapshot \ + docker compose -f compose.local.yaml exec advancer \ + cartesi-rollups-cli deploy application /var/lib/cartesi-rollups-node/snapshot \ + --consensus \ --epoch-length 10 \ - --withdrawal-config-file /tmp/withdrawal.json \ --salt \ + --template-hash \ + --withdrawal-config-file /tmp/withdrawal.json \ --register ``` - Replace `` with your application name and `` with a unique identifier (generate one with `cast keccak256 "your-unique-string"`). The deployment is rejected if the config is invalid, meaning its accounts-drive layout does not fit the machine memory. A zero-valued config would deploy an application without emergency withdrawal, which is the standard case. + Replace `` with your application name, `` with the address from `deploy authority`, `` with the value from `cartesi hash`, and `` with a unique identifier (generate one with `cast keccak256 "your-unique-string"`). The deployment is rejected if the config is invalid, meaning its accounts-drive layout does not fit the machine memory. Omit `--withdrawal-config-file` entirely to deploy without emergency withdrawal. + +5. **Commit the accounts-drive root every epoch:** + + ```shell + docker compose -f compose.local.yaml exec advancer \ + cartesi-rollups-cli app execution-parameters set snapshot_policy EVERY_EPOCH + ``` After this, your application is deployed and registered, and a guardian can foreclose it when needed. diff --git a/cartesi-rollups_versioned_docs/version-2.0/deployment/src/compose.local.yaml b/cartesi-rollups_versioned_docs/version-2.0/deployment/src/compose.local.yaml index ded253eae..f022776a4 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/deployment/src/compose.local.yaml +++ b/cartesi-rollups_versioned_docs/version-2.0/deployment/src/compose.local.yaml @@ -1,26 +1,30 @@ +# Cartesi Rollups Node 2.0.0-alpha.12 (images 0.12.0-alpha.41). +# Testnet-oriented compose. The EVM reader polls HTTP only; do not set +# CARTESI_BLOCKCHAIN_WS_ENDPOINT (unsupported in alpha.12). +# Factory defaults are cartesi-rollups 3.0.0-alpha.6 (identical CREATE2 +# addresses on Ethereum / Optimism / Arbitrum / Base mainnet and Sepolia). +# Wipe the database volume when upgrading from 0.12.0-alpha.39 (node alpha.11). name: cartesi-rollups-node x-env: &env CARTESI_LOG_LEVEL: info CARTESI_AUTH_KIND: ${AUTH_KIND} CARTESI_BLOCKCHAIN_ID: ${BLOCKCHAIN_ID} - CARTESI_AUTH_PRIVATE_KEY_FILE: ${PRIVATE_KEY_FILE} - CARTESI_BLOCKCHAIN_WS_ENDPOINT: ${BLOCKCHAIN_WS_ENDPOINT} + CARTESI_AUTH_PRIVATE_KEY: ${CARTESI_AUTH_PRIVATE_KEY} CARTESI_BLOCKCHAIN_HTTP_ENDPOINT: ${BLOCKCHAIN_HTTP_ENDPOINT} CARTESI_SNAPSHOTS_DIR: "/var/lib/cartesi-rollups-node/snapshot" - CARTESI_CONTRACTS_INPUT_BOX_ADDRESS: 0xc70074BDD26d8cF983Ca6A5b89b8db52D5850051 - CARTESI_CONTRACTS_AUTHORITY_FACTORY_ADDRESS: 0xC7003566dD09Aa0fC0Ce201aC2769aFAe3BF0051 - CARTESI_CONTRACTS_APPLICATION_FACTORY_ADDRESS: 0xc7006f70875BaDe89032001262A846D3Ee160051 - CARTESI_CONTRACTS_SELF_HOSTED_APPLICATION_FACTORY_ADDRESS: 0xc700285Ab555eeB5201BC00CFD4b2CC8DED90051 + CARTESI_CONTRACTS_INPUT_BOX_ADDRESS: ${CARTESI_CONTRACTS_INPUT_BOX_ADDRESS:-0x346B3df038FE9f8380071eC6514D5a83aD143939} + CARTESI_CONTRACTS_AUTHORITY_FACTORY_ADDRESS: ${CARTESI_CONTRACTS_AUTHORITY_FACTORY_ADDRESS:-0x3C1FE01c542a88A523FF6847eD1E26176c8C4ED0} + CARTESI_CONTRACTS_APPLICATION_FACTORY_ADDRESS: ${CARTESI_CONTRACTS_APPLICATION_FACTORY_ADDRESS:-0xC549F89cF1ca43eDDECC64Ac2208F4b283B1c483} + CARTESI_CONTRACTS_SELF_HOSTED_APPLICATION_FACTORY_ADDRESS: ${CARTESI_CONTRACTS_SELF_HOSTED_APPLICATION_FACTORY_ADDRESS:-0x6145C5996a71a379E030aEb0440df79D60833418} + CARTESI_CONTRACTS_QUORUM_FACTORY_ADDRESS: ${CARTESI_CONTRACTS_QUORUM_FACTORY_ADDRESS:-0x1f94009389F408B8D0ADfFcF8BBDCe5552BaCa5F} CARTESI_DATABASE_CONNECTION: postgres://postgres:password@database:5432/rollupsdb?sslmode=disable - -secrets: - pk: - file: ./secrets/pk # TODO: change to the path of the your private key file + CARTESI_EPOCH_LENGTH: 1 + CARTESI_BLOCKCHAIN_DEFAULT_BLOCK: ${CARTESI_BLOCKCHAIN_DEFAULT_BLOCK:-latest} services: database: container_name: database - image: cartesi/rollups-database:0.12.0-alpha.20 + image: cartesi/rollups-database:0.12.0-alpha.41 environment: POSTGRES_PASSWORD: password networks: @@ -37,8 +41,8 @@ services: evm-reader: container_name: evm-reader - image: cartesi/rollups-runtime:0.12.0-alpha.20 - command: cartesi-rollups-evm-reader + image: cartesi/rollups-runtime:0.12.0-alpha.41 + command: cartesi-rollups-evm-reader --default-block ${CARTESI_BLOCKCHAIN_DEFAULT_BLOCK:-latest} depends_on: database: condition: service_healthy @@ -51,7 +55,7 @@ services: advancer: container_name: advancer - image: cartesi/rollups-runtime:0.12.0-alpha.20 + image: cartesi/rollups-runtime:0.12.0-alpha.41 command: cartesi-rollups-advancer depends_on: database: @@ -66,12 +70,10 @@ services: - "10012:10012" environment: <<: *env - secrets: - - pk validator: container_name: validator - image: cartesi/rollups-runtime:0.12.0-alpha.20 + image: cartesi/rollups-runtime:0.12.0-alpha.41 command: cartesi-rollups-validator depends_on: database: @@ -85,7 +87,7 @@ services: claimer: container_name: claimer - image: cartesi/rollups-runtime:0.12.0-alpha.20 + image: cartesi/rollups-runtime:0.12.0-alpha.41 command: cartesi-rollups-claimer depends_on: database: @@ -96,12 +98,10 @@ services: - "10004:10004" environment: <<: *env - secrets: - - pk jsonrpc-api: container_name: jsonrpc-api - image: cartesi/rollups-runtime:0.12.0-alpha.20 + image: cartesi/rollups-runtime:0.12.0-alpha.41 command: cartesi-rollups-jsonrpc-api depends_on: database: @@ -115,4 +115,4 @@ services: <<: *env volumes: - data: \ No newline at end of file + data: diff --git a/cartesi-rollups_versioned_docs/version-2.0/development/emergency-withdrawal/lifecycle.md b/cartesi-rollups_versioned_docs/version-2.0/development/emergency-withdrawal/lifecycle.md index 2ed0d5676..0c333233d 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/development/emergency-withdrawal/lifecycle.md +++ b/cartesi-rollups_versioned_docs/version-2.0/development/emergency-withdrawal/lifecycle.md @@ -43,14 +43,14 @@ Everything above assumes the operator keeps running the node and the application The claim staging period is the guardian's window to act: foreclosing before such a claim is accepted terminalizes it as `CLAIM_FORECLOSED` and freezes the application on the last state it still trusts, so users withdraw against that state and not the bad one. It's important to note that, Foreclosure does not reverse a claim that has already been accepted; once a state is accepted it is what emergency withdrawals pay out from, which is why the guardian's protection depends on acting within the staging window. -To forclose an application, the **guardian**, a single address fixed in the withdrawal config, calls [`foreclose()`](../../api-reference/contracts/application.md#foreclose) on the application contract. [`isForeclosed()`](../../api-reference/contracts/application.md#isforeclosed) becomes `true` and this permanently freezes the application: +To foreclose an application, the **guardian**, a single address fixed in the withdrawal config, calls [`foreclose()`](../../api-reference/contracts/application.md#foreclose) on the application contract. [`isForeclosed()`](../../api-reference/contracts/application.md#isforeclosed) becomes `true` and this permanently freezes the application: **A foreclosed application can no longer process inputs.** Once frozen it takes on no new inputs and settles no new state. The one procedure it can still run is [emergency withdrawal](./recovery-guide.md): returning the assets users already deposited back to them, directly from the contracts. Foreclosure is a property of the **application contract** and of the **node**. It takes both to make the freeze permanent: - **The contract** holds the on-chain truth. `foreclose()` can only be called by the guardian and sets `isForeclosed()`, after which the normal `submitClaim` and `acceptClaim` paths revert. The contract also gates emergency withdrawal so that path only opens once the application is foreclosed. -- **The node** observes that truth and acts on it. Its EVM Reader detects the on-chain `Foreclosure` event, records it in the node database, and stops claiming new inputs for that application, however it still keeps watching the base layer so as to index subsequent emergency withdrawals. The node also generates the accounts-drive proofs users need to withdraw. +- **The node** observes that truth and acts on it. Its EVM Reader detects the on-chain `Foreclosure` event, records it in the node database, and stops claiming new inputs for that application, however it still keeps watching the base layer so as to index subsequent emergency withdrawals. Users generate accounts-drive proofs with `cartesi-rollups-machine-tool` (replay needs the node database or an equivalent input archive). ![Foreclosure sequence: the guardian calls foreclose() on the application contract; the node's EVM Reader observes isForeclosed(), records the foreclosure in its database, then continues its scanners to drain pre-foreclosure inputs and index post-foreclosure events](../../foreclosure-sequence.png) @@ -64,8 +64,8 @@ Foreclosure has three effects on claims: Once frozen, the accounts drive (the in-app balance ledger inside the machine state) at the last accepted epoch is the source of truth for balances. Turning that into on-chain payouts takes three steps, one off-chain and two on-chain: -1. **Generate the proofs.** Off-chain, anyone runs the **machine tool** (`cartesi-rollups-machine-tool`) to replay the settled machine state and then `prove accounts-drive`. Replay is deterministic, so anyone can reproduce the last accepted state independently, with no running node. This writes two proof files: `drive-root-proof.json` (the accounts-drive root and its proof against the machine state, used once in step 2) and `account-proof.json` (the per-account Merkle proofs, used in step 3). -2. **Anchor the ledger.** Anyone calls [`proveAccountsDriveMerkleRoot()`](../../api-reference/contracts/application.md#proveaccountsdrivemerkleroot) once, passing the root and proof from `drive-root-proof.json`. The contract checks it against the settled machine state and stores it. This is permissionless and happens once per application. +1. **Generate the proofs.** Off-chain, anyone with the accepted inputs runs the **machine tool** (`cartesi-rollups-machine-tool`) to replay the settled machine state and then `prove accounts-drive`. Replay is deterministic for the same inputs; on a self-hosted node those inputs come from the node database (see the [recovery guide](./recovery-guide.md)). This writes two proof files: `drive-root-proof.json` (the accounts-drive root and its proof against the machine state, used once in step 2) and `account-proof.json` (the per-account Merkle proofs, used in step 3). +2. **Anchor the ledger.** Anyone calls [`proveAccountsDriveMerkleRoot()`](../../api-reference/contracts/application.md#proveaccountsdrivemerkleroot) once, passing the root and proof from `drive-root-proof.json`. The contract checks it against the settled machine state and stores it. This is permissionless and happens once per application. Wait for the transaction to mine before withdrawing. 3. **Withdraw per account.** Each account is withdrawn with [`withdraw()`](../../api-reference/contracts/application.md#withdraw), passing the account and its Merkle proof from `account-proof.json`. The contract validates the account against the anchored root, builds a transfer output, runs it, and marks the account as withdrawn so it cannot be withdrawn twice. The gas payer can differ from the recipient. As each on-chain step lands, the node's EVM Reader indexes it: it records the `AccountsDriveMerkleRootProved` event when the ledger is anchored, and stores each `Withdrawal` event (keyed by application and account index) so clients can read withdrawals over JSON-RPC and the CLI. diff --git a/cartesi-rollups_versioned_docs/version-2.0/development/emergency-withdrawal/overview.md b/cartesi-rollups_versioned_docs/version-2.0/development/emergency-withdrawal/overview.md index 29463b85f..cdcbbe697 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/development/emergency-withdrawal/overview.md +++ b/cartesi-rollups_versioned_docs/version-2.0/development/emergency-withdrawal/overview.md @@ -5,13 +5,13 @@ title: Overview When users deposit assets into a Cartesi Rollups application, those assets are held by the application contract on the base layer, and the application's off-chain state (an in-app ledger of who owns what) decides how they can be spent. In normal operation the operator runs a node that keeps this state moving and settles it on-chain. But what happens to those funds if the operator stops running the node? -**Foreclosure and emergency withdrawal** are the answer. They let a designated **guardian** freeze an application, after which any user can withdraw their in-app balance straight from the base-layer contracts by proving their account, with **no running node required**. +**Foreclosure and emergency withdrawal** are the answer. They let a designated **guardian** freeze an application, after which any user can withdraw their in-app balance straight from the base-layer contracts by proving their account. After foreclosure, payouts do not depend on the operator continuing to advance the application; generating the proofs still needs the accepted inputs (typically from the node database or an equivalent archive). See the [recovery guide](./recovery-guide.md). The feature is opt-in: an application only supports it if it was deployed with a [`WithdrawalConfig`](../../api-reference/contracts/withdrawal/withdrawal-config.md). Applications deployed without one behave exactly as before. In addition to that, the application is also expected to record the assets deposited into it using the CMA ledger library. This library keeps those balances inside the accounts drive in a recoverable, provable layout that matches the `WithdrawalConfig`. See the [Asset Management Library](https://cartesi.github.io/docs/pr-preview/pr-303/cartesi-rollups/2.0/api-reference/asset-management/overview/) section for more details about the CMA library. ## The two parts -**Foreclosure** freezes the application. A guardian address, set in the withdrawal config, calls [`foreclose()`](../../api-reference/contracts/application.md#foreclose). From that moment the application is frozen at its last settled state, and it stays frozen forever. See [FOR-005](../../api-reference/contracts/application.md#foreclose) for the guardian-only rule. +**Foreclosure** freezes the application. A guardian address, set in the withdrawal config, calls [`foreclose()`](../../api-reference/contracts/application.md#foreclose). From that moment the application is frozen at its last settled state, and it stays frozen forever. Only the configured guardian can call `foreclose()`; any other signer reverts with `NotGuardian`. **Emergency withdrawal** is the recovery path that foreclosure unlocks, and it is built on the application's **accounts drive**. diff --git a/cartesi-rollups_versioned_docs/version-2.0/development/emergency-withdrawal/recovery-guide.md b/cartesi-rollups_versioned_docs/version-2.0/development/emergency-withdrawal/recovery-guide.md index 7dbe95953..921164f75 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/development/emergency-withdrawal/recovery-guide.md +++ b/cartesi-rollups_versioned_docs/version-2.0/development/emergency-withdrawal/recovery-guide.md @@ -12,26 +12,39 @@ This guide walks through foreclosing an application and withdrawing an account's You need: -- An application that was deployed with a [`WithdrawalConfig`](../../api-reference/contracts/withdrawal/withdrawal-config.md), and that has reached at least one accepted epoch; +- An application that was deployed with a [`WithdrawalConfig`](../../api-reference/contracts/withdrawal/withdrawal-config.md), and that has reached at least one accepted epoch (`CLAIM_ACCEPTED`); - The **guardian** key (only the guardian can foreclose); - The **machine tool** (`cartesi-rollups-machine-tool`), which reproduces the settled machine state and generates the proofs; - To send the on-chain transactions, either the **`cartesi-rollups-cli`** (see [Installing the required tools](./installation-guide.md)) or, if you prefer, **Foundry's `cast`** with `jq`; - The application's **accounts-drive parameters** from its withdrawal config: `accountsDriveStartIndex`, `log2MaxNumOfAccounts`, and `log2LeavesPerAccount`. These must match the values the application was deployed with. -- This should be done in the same environment of the node, with access to the database (and configuration variables) +- Access to the **node database** (and configuration variables) for `machine-tool replay`. On the self-hosted stack, run the CLI and machine tool inside the `advancer` container, which already has DB and snapshot access: + +```sh +docker compose -f compose.local.yaml exec advancer +``` This guide assumes the application already maintains its accounts drive in the layout its `WithdrawalConfig` describes. For how that drive is created, sized, and kept, see [Emergency Withdrawal (guest requirements)](../../api-reference/backend/emergency-withdrawal.md), and in particular [Creating the accounts drive](../../api-reference/backend/emergency-withdrawal.md#creating-the-accounts-drive). -The on-chain steps (1, 4, 5, and 6) can be run with either tool. Choose a tab in each step, and it applies to the others. Steps 2 and 3 use the machine tool either way. In the `cast` tabs, `` is the application contract address, `` is your node RPC endpoint, and the private key is the guardian's (step 1) or your own (steps 4 and 5). +The on-chain steps (1, 4, 5, and 6) can be run with either tool. Choose a tab in each step, and it applies to the others. Steps 2 and 3 use the machine tool either way. In the `cast` tabs, `` is the application contract address, `` is your base-layer RPC endpoint, and the private key is the guardian's (step 1) or your own (steps 4 and 5). + +Find the last accepted epoch before foreclosure proofs: + +```sh +cartesi-rollups-cli read epochs --status CLAIM_ACCEPTED --limit 1 --descending +``` + +`--to-epoch` for replay is a **decimal** integer. Convert the hex `index` from `read epochs` (for example `0x1197ca` → `1152970`). ## Step 1: Foreclose the application -Signed by the guardian, freeze the application: +Signed by the guardian, freeze the application. The CLI signer is `CARTESI_AUTH_*`. If the guardian is not the node's default signer, override the key for this call (or set `CARTESI_AUTH_MNEMONIC_ACCOUNT_INDEX` when using a mnemonic): ```sh -cartesi-rollups-cli foreclose +CARTESI_AUTH_PRIVATE_KEY= \ + cartesi-rollups-cli foreclose --yes ``` @@ -45,21 +58,23 @@ cast send 'foreclose()' \ -After this, `isForeclosed()` returns `true` and the application is frozen at its last accepted epoch. +After this, `isForeclosed()` returns `true` and the application is frozen at its last accepted epoch. The node indexes foreclosure asynchronously. Wait until `foreclose_block` is non-zero in `cartesi-rollups-cli app list` before proving the drive root. ## Step 2: Reproduce the settled machine state -Find the last accepted epoch, then replay the node database into a machine snapshot up to that epoch: +Replay accepted inputs from the node database into a machine snapshot up to that epoch. `--store` must be a path that does **not** already exist; `cartesi-machine` refuses to overwrite it. ```sh cartesi-rollups-machine-tool replay \ --template \ --application \ - --to-epoch \ - --store replay-snapshot + --to-epoch \ + --store ``` -Replay is deterministic: running it again produces the same machine state, so anyone can reproduce this snapshot independently. +On the self-hosted stack, `` is typically `/var/lib/cartesi-rollups-node/snapshot`. If replay fails writing reports under `/tmp` (`Permission denied`), run the tool as root inside the container (`docker compose exec -u root advancer …`) and ensure `/tmp` is world-writable. + +Replay is deterministic for the same inputs: running it again with the same database contents produces the same machine state. It still needs those inputs (from the node database or an equivalent archive), not only the on-chain claim hash. ## Step 3: Generate the proofs @@ -67,7 +82,7 @@ From that snapshot, generate the accounts-drive-root proof and the per-account p ```sh cartesi-rollups-machine-tool prove accounts-drive \ - --snapshot replay-snapshot \ + --snapshot \ --accounts-drive-start-index \ --log2-max-num-of-accounts \ --log2-leaves-per-account \ @@ -87,7 +102,7 @@ Record the accounts-drive root against the settled machine state. This is permis ```sh cartesi-rollups-cli prove-drive-root \ - --proof-file drive-root-proof.json + --proof-file drive-root-proof.json --yes ``` @@ -106,6 +121,8 @@ cast send 'proveAccountsDriveMerkleRoot(bytes32,bytes32[])' "$ROOT On success the contract stores the root and emits `AccountsDriveMerkleRootProved`. Anchoring a root from the wrong epoch, or from a different application, is rejected. +Wait until that transaction is mined (and `accounts_drive_proved_block` is set on the app, if you are watching the node) before withdrawing. Calling `withdraw` too early reverts with `AccountsDriveMerkleRootNotProved()`. + ## Step 5: Withdraw the account's funds With the root anchored, withdraw the account: @@ -115,7 +132,7 @@ With the root anchored, withdraw the account: ```sh cartesi-rollups-cli withdraw \ - --proof-file account-proof.json + --proof-file account-proof.json --yes ``` @@ -133,7 +150,7 @@ cast send 'withdraw(bytes,(uint64,bytes32[]))' "$ACCT" "($IDX,[$SI -The contract validates the account against the anchored root, builds and runs the transfer, marks the account as withdrawn, and emits a `Withdrawal` event. Withdrawing the same account again is rejected. +The contract validates the account against the anchored root, builds and runs the transfer, marks the account as withdrawn, and emits a `Withdrawal` event. Withdrawing the same account again is rejected. The gas payer does not need to be the withdrawal recipient; the recipient is encoded in the account proof according to the app's `withdrawal_output_builder`. ## Step 6: Verify @@ -157,4 +174,4 @@ cast call 'wereAccountFundsWithdrawn(uint256)(bool)' -Either way, [`wereAccountFundsWithdrawn(accountIndex)`](../../api-reference/contracts/application.md#wereaccountfundswithdrawn) returns `true`, and the token balance has moved from the application contract to the account owner. +Either way, [`wereAccountFundsWithdrawn(accountIndex)`](../../api-reference/contracts/application.md#wereaccountfundswithdrawn) returns `true`, and the token balance has moved from the application contract to the account owner. The same indexed data is available through JSON-RPC with `cartesi_listWithdrawals` and `cartesi_getWithdrawal`. diff --git a/cartesi-rollups_versioned_docs/version-2.0/resources/migration-guide.md b/cartesi-rollups_versioned_docs/version-2.0/resources/migration-guide.md index c42c06d1b..b9cd53273 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/resources/migration-guide.md +++ b/cartesi-rollups_versioned_docs/version-2.0/resources/migration-guide.md @@ -428,7 +428,3 @@ v1.5 frontends typically called GraphQL directly. v2 TypeScript clients should u Replace `@cartesi/viem` imports with `@cartesi/client` and `@cartesi/wagmi` with `@cartesi/react`. Pin explicit alpha versions; the `@alpha` npm tag can resolve to an older prerelease. -:::note -See [rollups-ts#123](https://github.com/cartesi/rollups-ts/pull/123) and [#124](https://github.com/cartesi/rollups-ts/pull/124) for RPC type updates against the node API. Component layout for a React app is in the [React frontend tutorial](../tutorials/react-frontend-application.md); that page may still show the earlier package names. -::: - diff --git a/cartesi-rollups_versioned_sidebars/version-2.0-sidebars.json b/cartesi-rollups_versioned_sidebars/version-2.0-sidebars.json index ae9f4de83..4a1cb30fc 100644 --- a/cartesi-rollups_versioned_sidebars/version-2.0-sidebars.json +++ b/cartesi-rollups_versioned_sidebars/version-2.0-sidebars.json @@ -248,7 +248,17 @@ "items": [ "resources/community-tools", "resources/mainnet-considerations", - "resources/migration-guide" + "resources/migration-guide", + { + "type": "link", + "label": "Dave", + "href": "https://arxiv.org/abs/2411.05463" + }, + { + "type": "link", + "label": "PRT", + "href": "https://arxiv.org/abs/2212.12439" + } ] }, { From 7f814f62b5e9ba08f0b30c05140f3a8406032ed0 Mon Sep 17 00:00:00 2001 From: Shaheen Date: Mon, 24 Aug 2026 18:30:26 +0530 Subject: [PATCH 4/4] docs(v2): add self-hosted good practices for longer-lived nodes Co-authored-by: Cursor --- .../deployment/self-hosted/standard.md | 44 ++++++++++++++++++- .../self-hosted/with-emergency-withdrawal.md | 2 +- 2 files changed, 44 insertions(+), 2 deletions(-) diff --git a/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/standard.md b/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/standard.md index 02a62d40b..aeadb7a88 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/standard.md +++ b/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/standard.md @@ -10,7 +10,7 @@ This guide explains how to run a Cartesi Rollups node locally on your machine fo :::warning Production Warning **Do not use this compose file as a production deployment.** -It is a testnet-oriented starting point. It does not include public snapshot verification, production-grade secrets, high availability, or hardened Postgres. +It is a testnet-oriented starting point. It does not include public snapshot verification, proper security hardening, or production-grade infrastructure. See [Good practices](#good-practices) before running a longer-lived node. ::: ## Prerequisites @@ -162,3 +162,45 @@ curl -s -X POST http://localhost:10011/rpc \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"cartesi_listInputs","params":[""],"id":1}' ``` + +## Good practices + +The walkthrough above is enough to get a testnet node running. Apply the following before the stack stays up, holds a funded key, or exposes APIs beyond localhost. + +### Keep one process per container + +Do not collapse reader, advancer, validator, claimer, and JSON-RPC into one process except for short local experiments. They have different trust boundaries and failure modes. + +### Scope the signing key + +The sample compose puts `CARTESI_AUTH_PRIVATE_KEY` in the shared environment, so every service receives the funded key. Only `claimer` and the one-off `deploy` CLI need to sign. Give the key to those processes only, preferably as a file-backed Docker secret (`CARTESI_AUTH_PRIVATE_KEY_FILE`), not an environment variable. Env vars are readable via `docker inspect` and often appear in crash dumps. + +`deploy application` derives both the application owner and the authority owner from the auth key unless you pass `--application-owner` / `--authority-owner`. Use a separate cold owner key from the hot claiming key. + +### 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. + +### Limit what is published on the network + +The compose publishes telemetry on ports `10001`–`10005` as well as inspect (`10012`) and JSON-RPC (`10011`). Bind telemetry to `127.0.0.1` or keep it on an internal network. Put inspect and JSON-RPC behind a reverse proxy with TLS, rate limiting, and a body-size cap. + +Inspect runs on a temporary machine fork. An open inspect endpoint is an easy way to exhaust the host. The node logs `HTTP service bound to all interfaces; restrict access via firewall or reverse proxy` when it starts. + +Drop hardcoded `container_name` values if you intend to run more than one application on the same host; otherwise Compose cannot start a second stack. + +### Choose a default block and cap RPC ranges + +Use `CARTESI_BLOCKCHAIN_DEFAULT_BLOCK=finalized` whenever the node submits claims of value. `latest` is for fast local iteration; a reorg can orphan inputs the node already processed. Hosted RPC providers cap `eth_getLogs` ranges. Set a maximum block range on the EVM reader (for example `--max-block-range`) so a resync from an old InputBox deployment block does not fail against Infura or Alchemy. + +### Pin images and verify the snapshot + +Pin `cartesi/rollups-runtime` and `cartesi/rollups-database` by digest (`image@sha256:…`), not only a mutable tag. Before `--register`, compare `cartesi hash` with the hash of the [public snapshot](../snapshot.md) you intend to run. Registering a local rebuild that does not match the published artifact means other validators cannot reproduce your machine. + +### Restart, monitor, and rotate logs + +Give every service a restart policy. Watch `evm-reader` specifically: it can exit while the other containers stay up, and the node then accepts no inputs. Alert on reader block lag, claim submission failures, and the gas balance of the claimer key. Configure log rotation. The advancer logs application stdout, so input payloads can end up in logs. + +### Set a withdrawal guardian for apps that custody assets + +A zero-address guardian means no foreclosure path. If the application holds funds, pass a valid `--withdrawal-config-file` at deploy time so a guardian can foreclose if claims go wrong. See [Deployment with emergency withdrawal](./with-emergency-withdrawal.md). diff --git a/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/with-emergency-withdrawal.md b/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/with-emergency-withdrawal.md index 871941ed3..532722b04 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/with-emergency-withdrawal.md +++ b/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted/with-emergency-withdrawal.md @@ -8,7 +8,7 @@ title: Self-hosted with Emergency Withdrawal This guide runs a self-hosted node and deploys an application that supports [emergency withdrawal](../../development/emergency-withdrawal/overview.md): a guardian can foreclose it, and users can then recover their funds directly from the contracts. It follows the same flow as the [standard deployment](./standard.md), with a few additions. Read the [Foreclosure & Emergency Withdrawal overview](../../development/emergency-withdrawal/overview.md) first for the concept. :::warning Production Warning -Like the standard setup, this is for development and testing on **testnet**, not production. +Like the standard setup, this is for development and testing on **testnet**, not production. Follow the [good practices](./standard.md#good-practices) in the standard deployment guide before the stack stays up, holds a funded key, or exposes APIs beyond localhost. ::: ## Prerequisites