diff --git a/cartesi-rollups_versioned_docs/version-2.0/back-end-api.png b/cartesi-rollups_versioned_docs/version-2.0/back-end-api.png new file mode 100644 index 00000000..cf73b3af Binary files /dev/null and b/cartesi-rollups_versioned_docs/version-2.0/back-end-api.png differ diff --git a/cartesi-rollups_versioned_docs/version-2.0/core-components.png b/cartesi-rollups_versioned_docs/version-2.0/core-components.png new file mode 100644 index 00000000..c350efbb Binary files /dev/null and b/cartesi-rollups_versioned_docs/version-2.0/core-components.png differ diff --git a/cartesi-rollups_versioned_docs/version-2.0/core-concepts/architecture.md b/cartesi-rollups_versioned_docs/version-2.0/core-concepts/architecture.md new file mode 100644 index 00000000..19918611 --- /dev/null +++ b/cartesi-rollups_versioned_docs/version-2.0/core-concepts/architecture.md @@ -0,0 +1,162 @@ +--- +id: architecture +title: Architecture +resources: + - url: https://cartesi.io/blog/grokking-cartesi-virtual-machine/ + title: Grokking the Cartesi Machine + - url: https://cartesi.io/blog/understanding-cartesi-rollups-pt2/ + title: Understanding Cartesi Rollups + - url: https://cartesi.io/blog/grokking-cartesi-nodes/ + title: Grokking Cartesi Nodes + - url: https://youtu.be/uUzn_vdWyDM?si=J2or_Nfym5pabkjNz3z8Gw + title: Cartesi Machine DeepDive + - url: https://github.com/cartesi/dave + 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: + +- Cartesi Rollups: A set of _on-chain(rollups contracts)_ and _off-chain(rollups node)_ components that implement an Optimistic Rollup solution, providing the general framework for building dApps. + +- Cartesi Machine: A virtual machine (VM) that runs a complete Linux operating system, serving as the environment for executing the dApp's backend. + +- Backend: The application's state and verifiable logic run inside the Cartesi Machine as a standard Linux application. + +- Frontend: The application’s user-facing interface, typically implemented as a web application or a command-line interface tool. + + +![img](../../../static/img/v1.5/architecture-overview.jpg) + +## Cartesi Machine + +The Cartesi Machine forms the core of Cartesi's off-chain computation capabilities. It is a virtual machine based on the [RISC-V](https://riscv.org/) instruction set architecture (ISA), designed to provide a deterministic and isolated execution environment. + +Key features of the Cartesi Machine include: + +- Full Linux OS support: This allows developers to use familiar tools and libraries for backend development. You have flexibility in the choice of programming languages and all open-source libraries available on Linux. + +- Isolation and reproducibility: The machine operates independently, ensuring consistent behavior across executions. + +- Scalability: By leveraging significant off-chain computing power, the Cartesi Machine enables complex computations while maintaining blockchain-level security. + +- The Cartesi machine is self-contained and can't make an external request. It runs in isolation from any external influence on the computation to achieve reproducibility. + +The Cartesi Machine achieves its unique balance of scalability and security by performing computations off-chain but providing mechanisms to verify these computations on-chain when necessary. + + +## On-chain components + +The on-chain part of Cartesi Rollups consists of [several smart contracts](../rollups-apis/json-rpc/overview.md) deployed on the base layer. + +Here is an overview of the major contracts, with each serving a specific role in the dApp ecosystem: + +### InputBox +The [InputBox](../rollups-apis/json-rpc/input-box.md) contract is the entry point for user interactions with the off-chain layer. All inputs destined for a Cartesi dApp are first submitted to this contract, which then emits events that the off-chain components can process. + +### CartesiDApp +Each Cartesi dApp is associated with a unique instance of the [CartesiDApp](../rollups-apis/json-rpc/application.md) contract. This contract acts as the on-chain representation of the dApp and can hold ownership of digital assets on the base layer, including Ether, ERC-20 tokens, and NFTs. + +### CartesiDAppFactory +The [CartesiDAppFactory](../rollups-apis/json-rpc/application-factory.md) contract simplifies the deployment process for CartesiDApp contracts. It allows developers to deploy new CartesiDApp instances with a single function call, enhancing convenience and security. This factory approach ensures the deployed contract bytecode remains unaltered, assuring users and validators. + +### Portals + +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)](../rollups-apis/json-rpc/portals/EtherPortal.md) +- [ERC-20 (Fungible tokens)](../rollups-apis/json-rpc/portals/ERC20Portal.md) +- [ERC-721 (Non-fungible tokens)](../rollups-apis/json-rpc/portals/ERC721Portal.md) +- [ERC-1155 Single transfers](../rollups-apis/json-rpc/portals/ERC1155SinglePortal.md) +- [ERC-1155 Batch transfers](../rollups-apis/json-rpc/portals/ERC1155BatchPortal.md) + +These Portal contracts implement the logic to "teleport" assets safely between layers, maintaining their integrity and ownership throughout the transfer process. + +## Off-chain layer +The off-chain execution layer is centered around the Cartesi Rollups Node, the crucial middleware between the on-chain contracts and the Cartesi Machine. The node is responsible for: + +1. Processing inputs: It reads inputs from the base layer and forwards them to the Cartesi Machine for processing. + +2. State management: The node manages the state of the dApp, ensuring consistency between on-chain and off-chain representations. + +3. Validation: It can act as a validator, generating claims at the end of each epoch to be submitted on-chain. + +4. Inspection: The node handles requests to inspect the dApp state, facilitating queries without altering the state. + +5. Output management: It operates a GraphQL server that allows clients to query the outputs produced by the dApp. + +The Cartesi Rollups Node can operate in two primary modes: + +**1. Validator Nodes**: These nodes have full responsibilities, including processing inputs, generating claims, and ensuring the validity of on-chain state updates. They can operate in secure, isolated environments as they don't need to expose endpoints for external state queries. + +**2. Reader Nodes (In Development)**: These nodes focus on advancing the off-chain state and making it publicly available. They consume information from the blockchain but do not participate in the validation process. + +:::caution important +All Cartesi Nodes function as Validator Nodes, with Reader Node functionality under active development. +::: + + +## Data Flow and Processes + +The Cartesi architecture facilitates several key processes that enable the functioning of dApps. These processes include: + +### Advance state + +![img](../../../static/img/v1.5/node-advance.jpg) + +The `advance-state` process changes the application state, and it involves the following steps: + +- The application frontend submits an advance-state input to the `InputBox` smart contract on the base layer. + +- The node monitors events from the `InputBox` contract and retrieves the input data. + +- The node sends the input to the application backend inside the Cartesi Machine. + +- The Cartesi Machine processes the input and generates verifiable outputs ([vouchers](../rollups-apis/backend/vouchers.md), [notices](../rollups-apis/backend/notices.md), and [reports](../rollups-apis/backend/reports.md)). + +- The application frontend can query these outputs using the node's [GraphQL API](../rollups-apis/graphql/basics.md). + +### Inspect state + +![img](../../../static/img/v1.5/node-inspect.jpg) + +The `inspect-state` process allows for querying the application backend without altering its state: + +- The application frontend sends an inspect-state input directly to the Cartesi Node. + +- The node forwards this input to the Cartesi Machine. + +- The Cartesi Machine processes the input and generates a [report](../rollups-apis/backend/reports.md). + +- The node returns this report to the frontend via a [REST API](../rollups-apis/backend/introduction.md/#advance-and-inspect). + +:::note Inspect requests +It's important to note that `inspect-state` inputs do not produce vouchers or notices, and the current implementation processes inputs sequentially, which may impact scalability for applications heavily reliant on inspect-state functionality. +::: + +### Validation + +![img](../../../static/img/v1.5/node-validate.jpg) + +The validation process ensures the integrity of the off-chain computations: + +- The Cartesi Node bundles multiple `advance-state` inputs into an epoch. + +- At the end of an epoch, the node computes a claim summarizing the epoch's state changes. + +- The node submits this claim to the Cartesi Rollups smart contracts on the base layer. + +- The application frontend can fetch proofs for specific outputs within a closed epoch. + +- These proofs can validate outputs on-chain, such as validating notices or executing vouchers. + +## Introducing Dave — an interactive fraud-proof system + +[Dave](https://github.com/cartesi/dave) is Cartesi's dispute resolution algorithm designed to address shortcomings in existing fraud-proof protocols. Traditional fraud-proof systems often face challenges such as delay attacks and vulnerability to Sybil attacks, where malicious nodes can disrupt operations by continuously challenging transactions or overwhelming honest validators. + +Dave introduces an approach where the resources required to defend against disputes grow logarithmically with the number of opponents. This means that defending against challenges remains affordable for a single honest node, even in the face of multiple attackers. + +With Dave, a single honest participant can effectively defend their claims on-chain, ensuring the integrity of transactions without relying on trust in validators. Based on the [Permissionless Refereed Tournaments algorithm](https://arxiv.org/abs/2212.12439), this protocol empowers anyone to validate rollups and uphold correct states on-chain, enhancing transaction security and reliability. + +Similar to how a consensus algorithm is crucial for achieving agreement on a single state of the blockchain among all nodes in a base-layer chain, Dave plays a fundamental role in ensuring the integrity and trustworthiness of state transitions within Cartesi Rollups. 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 new file mode 100644 index 00000000..72140ca2 --- /dev/null +++ b/cartesi-rollups_versioned_docs/version-2.0/core-concepts/cartesi-machine.md @@ -0,0 +1,25 @@ +--- +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: + +- Code execution: Code is executed based on specific inputs to perform computations, process data, or run custom logic, depending on the requirements of the task at hand. + +- Abstraction of infrastructure: The underlying infrastructure is abstracted away, allowing you to focus on writing code without worrying about managing servers, hardware, or networking resources. + +- Flexibility in programming languages and libraries: You have flexibility in the choice of programming languages and all open-source libraries available on Linux. + + +The Cartesi Machine is a state machine that remains idle until a new request arises. The concept of state, in this case, is tied to both the input requests that the Cartesi Machine receives and the execution of the RISC-V instructions that the machine follows in processing those requests. The Cartesi Machine handles: + +- Discrete states: RISC-V instructions are executed step-by-step, transitioning from one state to another. + +- State transitions: State transitions happen deterministically as the emulator processes these RISC-V instructions, changing the system's state to a new discrete state. + +- Determinism: Given the same initial state and input, the Cartesi Machine will always produce the same output and final state to ensure that off-chain computations can be verified and agreed upon. + +- The Cartesi machine is self-contained and can't make an external request. To achieve reproducibility,it runs in isolation from any external influence on the computation. diff --git a/cartesi-rollups_versioned_docs/version-2.0/core-concepts/mainnet.md b/cartesi-rollups_versioned_docs/version-2.0/core-concepts/mainnet.md new file mode 100644 index 00000000..2a5801d9 --- /dev/null +++ b/cartesi-rollups_versioned_docs/version-2.0/core-concepts/mainnet.md @@ -0,0 +1,38 @@ +--- +id: mainnet-considerations +title: Mainnet considerations +resources: + - url: https://honeypot.cartesi.io/ + 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 + +Now that Cartesi has reached a Mainnet Ready stage, developers can build dApps with Cartesi Rollups and deploy on Ethereum, Optimism, and Arbitrum Mainnets! + +At this first stage, the validation remains permissive, with no support for disputes; however, progress in implementing this is already underway. + +## Undiscovered Bugs + +The codebase may contain some undiscovered vulnerabilities that might put user funds at risk. + +Developers and users should factor this risk into their decision to use Cartesi Rollups and decide how much of their value to entrust to the system. + +## Security + + +The Cartesi Rollups infrastructure is being built based on careful design decisions and a robust code review process that aligns with the mainstream dogma of blockchain technology. + +When it comes to dApp safety, developers must also implement the same level of concern in their process. A culture of code reviews, auditing, and extensively testing their code is paramount to avoid hacks or bugs that could lead to user funds being lost. + +**The Honeypot** is a dApp designed to demonstrate Cartesi Rollups’ security capabilities. + +As the Honeypot is tested and fortified, users and developers will have increased confidence in the security of Cartesi Rollups. Want to help test the security of Cartesi Rollups? [Try your hand at cracking the Honeypot](https://honeypot.cartesi.io/). + + +## Scams +Like Ethereum, Cartesi Rollups are permissionless—anybody can deploy any smart contract code. You can interact with contracts on Cartesi Rollups precisely as you do with Ethereum, but only if you’ve independently verified that the application is secure. + + diff --git a/cartesi-rollups_versioned_docs/version-2.0/core-concepts/optimistic-rollups.md b/cartesi-rollups_versioned_docs/version-2.0/core-concepts/optimistic-rollups.md new file mode 100644 index 00000000..a83a7034 --- /dev/null +++ b/cartesi-rollups_versioned_docs/version-2.0/core-concepts/optimistic-rollups.md @@ -0,0 +1,70 @@ +--- +id: optimistic-rollups +title: Optimistic Rollups +resources: + - url: https://ethereum.org/en/developers/docs/scaling/optimistic-rollups/ + title: Optimistic Rollups + - url: https://www.paradigm.xyz/2021/01/almost-everything-you-need-to-know-about-optimistic-rollup + title: Everything you need to know about Optimistic Rollups + - url: https://cartesi.io/blog/grokking-dave/ + title: Fraud-proof protocols | Grokking Dave +--- + +Cartesi implements a rollup design known as Optimistic Rollups. + +The combination of an Optimistic Rollups framework and the Cartesi Machine Emulator enables the development of dApps using any package or library available for Linux. + +## What is a Blockchain Rollup? + +A rollup is a blockchain scalability solution that offloads complex computations "off-chain," meaning they run on a separate computing environment (execution layer) outside the base layer, such as Ethereum. + +When employing rollups, the blockchain receives and logs transactions. In rare instances of an active attack or the involvement of a malicious agent, parties may disagree with a computation’s outcomes, and the blockchain will resolve these disputes. However, it's important to note that disagreements are not expected to occur under normal circumstances. + + +Users interact with a rollup through transactions on the base layer. They send messages (inputs) to the rollup on-chain smart contracts to define a computation to be processed and, as such, advance the state of the computing environment on the execution layer. Interested parties run an off-chain component (a node on the execution layer) that watches the blockchain for inputs, understanding, and executing the state updates. + +Once in a while, the state is checkpointed on the chain; at this point, it is considered finalized and can thus be accepted by any smart contract on the base layer. + +Ensuring this operation is secure is vital, meaning that the execution layer node must somehow prove the new state to the base layer. + +Consider this question: _"How does Ethereum know that the data posted by an off-chain L2 node is valid and was not submitted maliciously?"_ + +The answer depends on the rollup implementation, which falls within one of two categories according to the type of proof used: + +1. **Zero-knowledge Rollups (ZK Rollups)**, which use validity proofs. + +2. **Optimistic Rollups (ORs)**, which use fraud proofs. + +### Zero-knowledge Rollups (ZK Rollups) + +In ZK rollups, which use validity proof schemes, every state update is accompanied by a cryptographic proof created off-chain, attesting to its validity. The update is only taken if the proof successfully passes verification on-chain. Validity proofs(ZK Rollups) bring the enormous benefit of instant finality—as soon as a state update appears on-chain, it can be fully trusted and acted upon. + +The choice, however, also brings less than ideal properties: generating ZK proofs for general-purpose computations is, when possible, immensely expensive, and each on-chain state update must pay the extra gas fee for including and verifying a validity proof. + +### Optimistic Rollups (ORs) + +Optimistic Rollups, which use fraud-proof schemes, work by a different paradigm. State updates come unaccompanied by proofs; they’re proposed and, if not challenged, confirmed on-chain. Challenging a state update proposal using fraud proofs has two categories: **non-interactive** and **interactive**. + +Non-interactive refers to the fact that the challengers can prove that a state update is invalid in one step. With interactive fraud proofs, the claimer and challenger must, mediated by the blockchain, partake in something similar to a verification game. + +The assumption that state updates will likely be honest often gives solutions like this the name of Optimistic Rollups. + +This optimism is reinforced by financial incentives that reward honest behavior. Furthermore, any proposed false state will only be accepted if it remains undisputed for a prolonged period. + + +The main advantage of Optimistic Rollups is that they are much cheaper than ZK Rollups. Posting a state update on-chain is minimal, and challenging a state update is also low. + +The main disadvantage is that state updates take time to finalize and are not entirely accepted immediately. During this period, they are considered "optimistic" and can be challenged. + + +## Cartesi Rollups + +Cartesi's Optimistic Rollups adopt interactive fraud proofs to handle disputes. + +The base layer isn't burdened with executing all computations, allowing for more extensive computational tasks. + +Transactions and computations occur off-chain, leading to more intricate logic within transactions; hence, applications leverage powerful virtual machines (VMs) on the execution layer for complex computations. + +Cartesi's architecture specializes in app-specific rollups(appchains). Each dApp has its dedicated rollup for off-chain computation, enhancing scalability and performance. + + diff --git a/cartesi-rollups_versioned_docs/version-2.0/dapp-arch.png b/cartesi-rollups_versioned_docs/version-2.0/dapp-arch.png new file mode 100644 index 00000000..c350efbb Binary files /dev/null and b/cartesi-rollups_versioned_docs/version-2.0/dapp-arch.png differ diff --git a/cartesi-rollups_versioned_docs/version-2.0/deployment/introduction.md b/cartesi-rollups_versioned_docs/version-2.0/deployment/introduction.md new file mode 100644 index 00000000..2e1b63be --- /dev/null +++ b/cartesi-rollups_versioned_docs/version-2.0/deployment/introduction.md @@ -0,0 +1,53 @@ +--- +id: introduction +title: Introduction +resources: + - url: https://github.com/cartesi/rollups-contracts/tree/v1.4.0/onchain/rollups/deployments + title: Supported networks + +--- + +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. + +To facilitate the instantiation of such nodes, Cartesi provides an infrastructure for quickly getting them running in the cloud so the node can be run 24/7. This server will expose a single port to the internet so client applications can communicate with the node. + +The Cartesi rollups node is distributed as a Docker image. Any popular cloud provider, like AWS, GCP, Azure, Digital Ocean, or Linode, can run docker containers and hence can be used to host the rollups node. + +## Deployment process + +The deployment of an application involves building a Cartesi machine and deploying a smart contract to a supported network. + +The `cartesi build` command produces the Cartesi genesis machine, which contains a hash representing the application and its initial state. + +After deployment, any changes to the application code will generate a different hash and, hence, require another deployment. + +The smart contract that represents the application on the base layer can be deployed using the [`CartesiDAppFactory`](../rollups-apis/json-rpc/application-factory.md) smart contract. + +There are two methods to deploy an application: + +1. [Self-hosted deployment](../deployment/self-hosted.md): Deploy the application node using your infrastructure. + +2. Third-party service provider: Outsource running the application node to a service provider. + +:::caution important +Deployment with a third-party service provider is under development and will be available in a future release. +::: + +## 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. + +The table below shows the list of all [networks that are currently supported](https://github.com/cartesi/rollups-contracts/tree/v1.4.0/onchain/rollups/deployments) in the latest release: + +| Network Name | Chain ID | +| ---------------- | -------- | +| Ethereum Mainnet | 1 | +| Sepolia | 11155111 | +| Optimism | 10 | +| Optimism Sepolia | 11155420 | +| Arbitrum | 42161 | +| Arbitrum Sepolia | 421614 | +| Base | 8453 | +| Base Sepolia | 84532 | diff --git a/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted.md b/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted.md new file mode 100644 index 00000000..d4ce4914 --- /dev/null +++ b/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted.md @@ -0,0 +1,171 @@ +--- +id: self-hosted +title: Self-hosted deployment +resources: + - url: https://www.codecademy.com/article/installing-and-using-postgresql-locally + title: Installing and Using PostgreSQL Locally + - url: https://docs.digitalocean.com/products/databases/postgresql/how-to/create/ + title: How to Create PostgreSQL Database Clusters + - url: https://www.amazonaws.cn/en/getting-started/tutorials/deploy-docker-containers/ + title: How to Deploy Docker Container - AWS + - url: https://www.digitalocean.com/solutions/docker-hosting + title: Deploy Docker Containers on Digital Ocean + - url: https://docs.docker.com/reference/cli/docker/image/tag/ + title: Docker Tag +--- + +The self-hosted deployment involves running your infrastructure locally or on a remote cloud server to host your application node. + +Here are the requirements: + +- Wallet with sufficient funds on the chosen network. +- A cloud server +- A PostgreSQL database +- A web3 provider for interacting with the selected network + +## Initiating deployment + +1. Compile your application into RISC-V architecture and consequently build a Cartesi machine by running: + + ```shell + cartesi build + ``` + +2. Run the command below to start the deployment process. + + ```shell + cartesi deploy --hosting self-hosted --webapp https://sunodo.io/deploy + ``` + + The command generates a Docker image containing the rollups node and machine. You will be redirected to a web application to deploy the necessary smart contracts. + + ![img](../../../static/img/v1.3/deploy.png) + +## Deploying the contracts + +On the deploy web interface, the hash of the Cartesi machine will be automatically configured. + +1. Connect your wallet to set the application chain’s base layer and deployer account. + +2. Create a wallet specifically for Cartesi rollups node transactions. The Cartesi rollups node will use this wallet to submit transactions to the base layer. Paste the public address of this wallet. + + :::note create a wallet + You can use [Cast](https://book.getfoundry.sh/reference/cast/cast-wallet-new-mnemonic) to create a new wallet by running `cast wallet new-mnemonic --words 24`. For increased security, you can use a wallet managed by [AWS KMS](https://aws.amazon.com/blogs/database/part1-use-aws-kms-to-securely-manage-ethereum-accounts/). + ::: + +3. After successful deployment, the node’s configuration is presented in a `.env` file and a `.toml` format. This config file includes the addresses of the deployed smart contracts and information on the base layer chain. + + You will need the `.env` when [hosting the node on the cloud provider](./self-hosted.md/#hosting-on-a-cloud-provider) and the `.toml` file when [hosting on Fly.io](./self-hosted.md/#hosting-on-flyio). + + + + +## Hosting the node + +You’ll need a server to host the application node and keep it operational 24/7. This server will expose a single port for client access to the rollups node APIs through GraphQL or Inspect requests. + + +The server requirements depend on your application's expected usage and the specifications of the Cartesi machine you're using, such as its RAM size and total capacity. Consider a minimum of 8GB of RAM, and adjust as needed. + + +The Cartesi rollups node is distributed as a Docker image. Any popular cloud provider, like AWS, GCP, Azure, Digital Ocean, or Linode, can run docker containers and hence can be used to host the rollups node. + +Alternatively, you can use a service like [Fly.io](https://fly.io/) to deploy your application node. + +### Hosting on a cloud provider + +1. Download the `.env` configuration file into the root directory of your application. + +1. Obtain HTTP and WebSocket URLs from a web3 provider for the `CARTESI_BLOCKCHAIN_HTTP_ENDPOINT` and `CARTESI_BLOCKCHAIN_WS_ENDPOINT` variables. + + Here is an example from [Alchemy](https://dashboard.alchemy.com/): + + ![img](../../../static/img/v1.3/alchemy.png) + + :::caution important + The web3 provider URLs and wallet mnemonic are sensitive information that can compromise your application and funds. You should keep it **secure** and **private** at all times. + ::: + +1. Create a PostgreSQL database and configure the connection string in the `.env` file. + + The connection string for a PostgreSQL database must be configured at the `CARTESI_POSTGRES_ENDPOINT` variable. + + You can use any PostgreSQL database, whether managed by a cloud provider or set up on your local infrastructure. The key configuration required is the connection string, encompassing the database URL, username, password, and name. The node necessitates a PostgreSQL database to store the application state, which is accessible via the [GraphQL API](../rollups-apis/graphql/basics.md). + +1. With all the config variables set, here is how you can run the node on your local machine: + + ``` + docker run --env-file -p 10000:10000 + ``` + + Replace `` and `` with the `.env` file name and `sha256` hash of your Cartesi machine. + + The image can be tagged using [docker tag](https://docs.docker.com/reference/cli/docker/image/tag/). + + You can deploy your node with a cloud provider or use any managed container solution, like Kubernetes. + +### Hosting on fly.io + +Fly.io is a platform where you can conveniently deploy applications packaged as Docker containers. + +:::caution important +If deploying to Fly.io from macOS with Apple Silicon, create a Docker image for `linux/amd64` with: `cartesi deploy build --platform linux/amd64` +::: + +1. [Install the flyctl CLI](https://fly.io/docs/hands-on/install-flyctl/) + +1. [Create an account](https://fly.io/docs/hands-on/sign-up-sign-in/) + +1. Create an application: + + ```shell + $ fly app create + New app created: + ``` + +1. Create a Postgres database application: + + ```shell + fly postgres create --initial-cluster-size 1 --name -database --vm-size shared-cpu-1x --volume-size 1 + ``` + + Save the connection string provided by the command output. + +1. Attach database to the node application: + + ```shell + fly postgres attach -database -a + ``` + +1. Download `fly.toml` file from deploying the contracts and move it to your application directory: + + ![deploy self-hosted config](../../../static/img/v1.3/fly.png) + +1. Edit the `fly.toml` file to change all occurrences of `` to the name of your application + +1. Create secrets for sensitive configuration with the actual values: + + ```shell + fly secrets set -a CARTESI_BLOCKCHAIN_HTTP_ENDPOINT= + fly secrets set -a CARTESI_BLOCKCHAIN_WS_ENDPOINT= + fly secrets set -a CARTESI_AUTH_MNEMONIC=`` + fly secrets set -a CARTESI_POSTGRES_ENDPOINT= + ``` + + Set value of the `connection_string` as provided by step 4. + +1. Deploy the node: + + Tag the image produced at the beginning of the process and push it to the Fly.io registry: + + ```shell + flyctl auth docker + docker image tag registry.fly.io/ + docker image push registry.fly.io/ + fly deploy -a + ``` + + 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 new file mode 100644 index 00000000..0e6b004e --- /dev/null +++ b/cartesi-rollups_versioned_docs/version-2.0/development/asset-handling.md @@ -0,0 +1,69 @@ +--- +id: asset-handling +title: Asset handling +resources: + - url: https://www.udemy.com/course/cartesi-masterclass/ + 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 dApp that wants to manipulate assets needs a secure way of "teleporting" the assets from the base layer to the execution layer and then a way to "teleport" them back to the base layer. + +Currently, Cartesi Rollups support the following types of assets: + +- [Ether (ETH)](../rollups-apis/json-rpc/portals/) +- [ERC-20](../rollups-apis/json-rpc/portals/ERC20Portal.md) +- [ERC-721](../rollups-apis/json-rpc/portals/ERC721Portal.md) +- [ERC-1155 Single](../rollups-apis/json-rpc/portals/ERC1155SinglePortal.md) +- [ERC-1155 Batch](../rollups-apis/json-rpc/portals/ERC1155BatchPortal.md) + +![img](../../../static/img/v1.3/assets.jpg) + +## Deposits + +Portals enable the safe transfer of assets from the base layer to the execution layer. Users authorize portals to deduct assets from their accounts and initiate transfers to dApps. + +When an asset is deposited, it is on the base layer but gains a representation in the execution layer. The corresponding Portal contract sends an input via the `InputBox` contract describing the type of asset, amount, and some data the depositor might want the dApp to read. The off-chain machine will then interpret and validate the input payload. + +Deposit input payloads are always specified as packed ABI-encoded parameters, as detailed below. + +![img](../../..//static/img/v1.3/abi.jpg) + +### ABI encoding for deposits + + +| Asset | Packed ABI-encoded payload fields | Standard ABI-encoded payload fields | +| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------- | +| Ether |
  • `address sender`,
  • `uint256 value`,
  • `bytes execLayerData`
| none | +| ERC-20 |
  • `bool success`,
  • `address token`,
  • `address sender`,
  • `uint256 amount`,
  • `bytes execLayerData`
| none | +| ERC-721 |
  • `address token`,
  • `address sender`,
  • `uint256 tokenId`,
  • standard ABI-encoded fields...
|
  • `bytes baseLayerData`,
  • `bytes execLayerData`
| +| ERC-1155 (single) |
  • `address token`,
  • `address sender`,
  • `uint256 tokenId`,
  • `uint256 value`,
  • standard ABI-encoded fields...
|
  • `bytes baseLayerData`,
  • `bytes execLayerData`
| +| ERC-1155 (batch) |
  • `address token`,
  • `address sender`,
  • standard ABI-encoded fields...
|
  • `uint256[] tokenIds`,
  • `uint256[] values`,
  • `bytes baseLayerData`,
  • `bytes execLayerData`
| + + +## Withdrawing assets + +Users can deposit assets to a Cartesi dApp, but only the dApp can initiate withdrawals. When a withdrawal request is made, it’s processed and interpreted off-chain by the Cartesi Machine running the dApp’s code. Subsequently, the Cartesi Machine creates a voucher containing the necessary instructions for withdrawal, which is executable when an epoch has settled. + +Vouchers are crucial in allowing dApps in the execution layer to interact with contracts in the base layer through message calls. They are emitted by the off-chain machine and executed by any participant in the base layer. Each voucher includes a destination address and a payload, typically encoding a function call for Solidity contracts. + +The dApp’s off-chain layer often requires knowledge of its address to facilitate on-chain interactions for withdrawals, for example: `transferFrom(sender, recipient, amount)`. In this case, the sender is the dApp itself. + +By calling [`relayDAppAddress()`](../rollups-apis/json-rpc/relays/relays.md), function of the `DAppAddressRelay` contract, it adds the dApp’s address as a new input for the Cartesi dApp to process. Next, the off-chain machine uses this address to generate a voucher for execution at the [`executeVoucher()`](../rollups-apis/json-rpc/application.md/#executevoucher) function of the `CartesiDApp` contract. + +:::note epoch length +By default, Cartesi nodes close one epoch every 7200 blocks. You can [manually set the epoch length](./cli-commands.md/#run) to facilitate quicker asset-handling methods. +::: + +Here are the function signatures used by vouchers to withdraw the different types of assets: + +| Asset | Destination | Function signature | +| :------- | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------ | +| Ether | dApp contract | `withdrawEther(address,uint256)` [:page_facing_up:](../rollups-apis/json-rpc/application.md/#withdrawether) | +| ERC-20 | Token contract | `transfer(address,uint256)` [:page_facing_up:](https://eips.ethereum.org/EIPS/eip-20#methods) | +| ERC-20 | Token contract | `transferFrom(address,address,uint256)` [:page_facing_up:](https://eips.ethereum.org/EIPS/eip-20#methods) | +| ERC-721 | Token contract | `safeTransferFrom(address,address,uint256)` [:page_facing_up:](https://eips.ethereum.org/EIPS/eip-721#specification) | +| ERC-721 | Token contract | `safeTransferFrom(address,address,uint256,bytes)` [:page_facing_up:](https://eips.ethereum.org/EIPS/eip-721#specification) | +| ERC-1155 | Token contract | `safeTransferFrom(address,address,uint256,uint256,data)` [:page_facing_up:](https://eips.ethereum.org/EIPS/eip-1155#specification) | +| ERC-1155 | Token contract | `safeBatchTransferFrom(address,address,uint256[],uint256[],data)` [:page_facing_up:](https://eips.ethereum.org/EIPS/eip-1155#specification) | diff --git a/cartesi-rollups_versioned_docs/version-2.0/development/building-the-application.md b/cartesi-rollups_versioned_docs/version-2.0/development/building-the-application.md new file mode 100644 index 00000000..fbac5190 --- /dev/null +++ b/cartesi-rollups_versioned_docs/version-2.0/development/building-the-application.md @@ -0,0 +1,53 @@ +--- +id: building-the-application +title: Building the 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. + +With the Docker engine running, change the directory to your application and build by running: + +```shell +cartesi build +``` + +The successful execution of this step will log this in your terminal: + +```shell + . + / \ + / \ +\---/---\ /----\ + \ X \ + \----/ \---/---\ + \ / CARTESI + \ / MACHINE + ' + +[INFO rollup_http_server] starting http dispatcher service... +[INFO rollup_http_server::http_service] starting http dispatcher http service! +[INFO actix_server::builder] starting 1 workers +[INFO actix_server::server] Actix runtime found; starting in Actix runtime +[INFO rollup_http_server::dapp_process] starting dapp +INFO:__main__:HTTP rollup_server url is http://127.0.0.1:5004 +INFO:__main__:Sending finish + +Manual yield rx-accepted (0x100000000 data) +Cycles: 2767791744 +2767791744: b740d27cf75b6cb10b1ab18ebd96be445ca8011143d94d8573221342108822f5 +Storing machine: please wait +Successfully copied 288MB to /Users/michaelasiedu/Code/calculator/python/.cartesi/image +``` +## Memory + +To change the default memory size for the Cartesi Machine, you can personalize it by adding a specific label in your Dockerfile. + +The line below lets you define the memory size in megabytes (MB): + +```dockerfile +LABEL io.cartesi.rollups.ram_size=128Mi +``` + +:::note environment variables +You can create a `.cartesi.env` in the project's root and override any variable controlling the rollups-node. +::: \ No newline at end of file diff --git a/cartesi-rollups_versioned_docs/version-2.0/development/cli-commands.md b/cartesi-rollups_versioned_docs/version-2.0/development/cli-commands.md new file mode 100644 index 00000000..fe3f5a70 --- /dev/null +++ b/cartesi-rollups_versioned_docs/version-2.0/development/cli-commands.md @@ -0,0 +1,151 @@ +--- +id: cli-commands +title: CLI commands +--- + + +The Cartesi CLI provides essential tools for developing, deploying, and interacting with Cartesi applications. This page offers a quick reference to available commands and usage. + +## Basic Usage +To use any command, run: + +```bash +cartesi [COMMAND] +``` + +For detailed help on a specific command, use: + +```bash +cartesi help [COMMAND] +``` + +## Core Commands + +| Command | Description | +|---------|-------------| +| `create` | Create a new application | +| `build` | Build the application | +| `run` | Run the application node | +| `send` | Send input to the application | +| `deploy` | Deploy application to a live network | +| `address-book` | Prints addresses of deployed smart contracts | +| `clean` | Clean build artifacts of the application | +| `doctor` | Verify the minimal system requirements | +| `hash` | Print the image hash generated by the build command | +| `shell` | Start a shell in the Cartesi machine of the application | + + +--- +### `create` + +Create a new Cartesi application from a template. + +#### Usage: +```bash +cartesi create NAME --template [--branch ] +``` + +#### Flags: + +- `--template=