From 5535f2b6a33d13a1d7e2de88fe484a44f6c904e2 Mon Sep 17 00:00:00 2001 From: Joao Garcia Date: Tue, 8 Jul 2025 12:59:39 +0100 Subject: [PATCH 1/3] added deployment tutorial under docs --- README.md | 1 + docs/deployment.md | 157 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 158 insertions(+) create mode 100644 docs/deployment.md diff --git a/README.md b/README.md index e02b24adb..2d3b8e1c5 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,7 @@ cast call $(jq -r .address deployments/InputBox.json) 'getDeploymentBlockNumber( ## Documentation A more in-depth documentation on the contracts can be found [here](./docs/contracts.md). +A tutorial on how to deploy core and applcation specific contracts can be found [here](.docs/deployment.md). ## Use cases diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 000000000..a2054bf45 --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,157 @@ +# Cartesi Rollups Deployment Tutorial (v2.0) + +This tutorial provides a comprehensive guide for deploying a Cartesi Rollups Application. It covers the deployment of both the Cartesi Rollups core contracts and your application-specific contracts. The deployment process leverages key tools like [Cannon](https://usecannon.com/) for reproducible deployments, and *cast* from [Foundry](https://getfoundry.sh/) for interacting with smart contracts. Whether you’re deploying locally for development or targeting a public testnet or mainnet, this tutorial will help you understand and execute each step with confidence. + +--- + +## 1. Prerequisites + +Before beginning, ensure your environment is correctly set up. This includes having: + +* [Corepack](https://nodejs.org/api/corepack.html), which manages multiple Node.js package managers, +* [Foundry](https://book.getfoundry.sh/getting-started/installation) v1.1.0 or higher, a fast and modular toolkit for Ethereum application development. + +Next, clone the Cartesi Rollups contracts repository and install its dependencies. This repository contains both the core smart contracts and the application-specific ones: + +```bash +git clone https://github.com/cartesi/rollups-contracts.git +cd rollups-contracts +pnpm install +forge soldeer install +``` + +This setup provides you with all the components needed to work with the Cartesi Rollups contracts. + +--- + +## 2. Running a Local Devnet with Cannon + +To begin development or testing, you can simulate a full Cartesi devnet locally. This is useful for experimentation and validation before deploying to a live network. + +To do so, run: + +```bash +pnpm start +``` + +This command launches Cannon, which deploys the Cartesi Rollups core contracts.. These contracts will be deployed on a local Ethereum JSON-RPC instance at `127.0.0.1:8545`. + +Once running, you can interact with the contracts in one of two ways: + +* Pressing `i` in the terminal where Cannon is running, which provides a prompt interface. +* Using `cast` from a separate terminal session. + +--- + +## 3. Deploying to Testnet or Mainnet + +When ready to deploy on a live network, you must first identify the addresses of the already-deployed core contracts, which are required by your application. + +### Simulate Deployment First (Recommended) + +Before initiating a real deployment, it is strongly recommended to simulate the process to ensure correctness and identify potential issues early. This can be done using: + +```bash +pnpm cannon build --rpc-url $RPC_URL --dry-run --impersonate-all +``` + +Simulating with `--dry-run` prevents any real transactions from being broadcast, while `--impersonate-all` allows Cannon to simulate signatures for all accounts involved. + +--- + +### Deploying Core Contracts to a Real Network + +Once you are confident with the simulated results, proceed to deploy the Cartesi Rollups core contracts using: + +```bash +pnpm cannon build --rpc-url $RPC_URL --private-key $PRIVATE_KEY +``` + +After deployment, use the same `cannon inspect` command to confirm the contract addresses. These addresses will be required in the next stage when deploying your actual application. + +> [!NOTE] +> The deployment method is deterministic, this means the core contracts should always have the same address independently of the chain. This can be false for chains that do not support CREATE2. + +--- + +## 4. Deploying Your Application Using `ISelfHostedApplicationFactory` + +Cartesi Applications are deployed using the `ApplicationFactory`. This factory deploys your application contract, but for now, we can use the `SelfHostedApplicationFactory` which is an utility contract to communicate with both the `ApplicationFactory` and the `AuthorityFactory` which is an authoritary settlement module responsible to receive and provide claims. + +### Contract Functions + +The `SelfHostedApplicationFactory` interface provides two key functions: + +```solidity +function deployContracts(...) external returns (IApplication, IAuthority); +function calculateAddresses(...) external view returns (address, address); +``` + +The `deployContracts` function performs the actual deployment, while `calculateAddresses` can be used to determine the final contract addresses prior to deployment using deterministic inputs. + +### Parameters Explained + +| Parameter | Description | +| ------------------ | ------------------------------------------------------------ | +| `authorityOwner` | The Ethereum address that will own the `Authority` contract. This account is expected to run a cartesi-rollups-node, which is responsible for validating your application and submitting claims to the Cartesi Rollups framework. | +| `epochLength` | Duration of each epoch (in seconds) | +| `appOwner` | The address authorized to update the application's outputs Merkle root validator, which defines the official state of the application's outputs and submits claims about them. | +| `templateHash` | Application template hash obtained using `cartesi hash` | +| `dataAvailability` | ABI-encoded configuration related to data availability | +| `salt` | A 32-byte salt used for deterministic `CREATE2` deployment | + +> [!TIP] +> A random salt can be generated with the following command: +> `head -c 32 /dev/urandom | xxd -p -c 32 | sed 's/^/0x/'` + +--- + +### a. Encode `dataAvailability` + +The `dataAvailability` parameter must be ABI-encoded. To do this, use the `cast calldata` command: + +```bash +cast calldata "FunctionSignature(type1,type2,...)" arg1 arg2 ... +``` + +#### For default InputBox usage: + +```bash +cast calldata "InputBox(address)" +``` + +#### For advanced configurations such as Espresso: + +```bash +cast calldata "InputBoxAndEspresso(address,uint256,uint32)" 1234 5678 +``` + +--- + +### b. Calculate Deterministic Addresses + +Before deploying, you can predict the addresses of your application and authority contracts using: + +```bash +cast call $SELF_HOSTED_APPLICATION_FACTORY_ADDRESS \ + "calculateAddresses(address,uint256,address,bytes32,bytes,bytes32)(address,address)" \ + $AUTHORITY_OWNER $EPOCH_LENGTH $APP_OWNER $TEMPLATE_HASH $DATA_AVAILABILITY $SALT \ + --rpc-url $RPC_URL +``` + +--- + +### c. Deploy the Application + Authority + +Finally, deploy your application using the `deployContracts` function. This will deploy both the `Application` and `Authority` contracts at the precomputed addresses: + +```bash +cast send $SELF_HOSTED_FACTORY_ADDRESS \ + "deployContracts(address,uint256,address,bytes32,bytes,bytes32)" \ + $AUTHORITY_OWNER $EPOCH_LENGTH $APP_OWNER $TEMPLATE_HASH $DATA_AVAILABILITY $SALT \ + --private-key $DEPLOYER_PK --rpc-url $RPC_URL +``` + +After this transaction is confirmed, your Cartesi Rollups Application will be live and ready to process inputs through the deployed core and application contracts. + +Now it's time to spin up the node! \ No newline at end of file From 644657407bf9984a63d85b880fd3f4fe1f010faf Mon Sep 17 00:00:00 2001 From: Joao Garcia Date: Wed, 9 Jul 2025 14:24:44 +0100 Subject: [PATCH 2/3] spilt the tutorial into two, updated requisites to reference getting started --- README.md | 5 +- docs/deploying.md | 61 +++++++++++++++++++++ docs/{deployment.md => interacting.md} | 75 +++----------------------- 3 files changed, 72 insertions(+), 69 deletions(-) create mode 100644 docs/deploying.md rename docs/{deployment.md => interacting.md} (52%) diff --git a/README.md b/README.md index 2d3b8e1c5..f6a0217d5 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,10 @@ cast call $(jq -r .address deployments/InputBox.json) 'getDeploymentBlockNumber( ## Documentation A more in-depth documentation on the contracts can be found [here](./docs/contracts.md). -A tutorial on how to deploy core and applcation specific contracts can be found [here](.docs/deployment.md). + +A tutorial on how to deploy core contracts can be found [here](.docs/deploying.md). + +A tutorial to interact with the core contracts and deploy applcation specific contracts can be found [here](.docs/interacting.md). ## Use cases diff --git a/docs/deploying.md b/docs/deploying.md new file mode 100644 index 000000000..3d18d5852 --- /dev/null +++ b/docs/deploying.md @@ -0,0 +1,61 @@ +# Cartesi Rollups Deployment Tutorial (v2.0) + +This tutorial provides a comprehensive guide for deploying a Cartesi Rollups Core Contracts. The deployment process uses [Cannon](https://usecannon.com/) tool for reproducible deployments. This tutorial works whether you’re deploying locally for development or targeting a public testnet or mainnet. + +--- + +## 1. Prerequisites + +First, please make sure to follow the steps described in the [Getting Started](./../README.md#getting-started) section. + +--- + +## 2. Running a Local Devnet with Cannon + +To begin development or testing, you can simulate a full Cartesi devnet locally. This is useful for experimentation and validation before deploying to a live network. + +To do so, run: + +```bash +pnpm start +``` + +This command launches Cannon, which deploys the Cartesi Rollups core contracts.. These contracts will be deployed on a local Ethereum JSON-RPC instance at `127.0.0.1:8545`. + +Once running, you can interact with the contracts in one of two ways: + +* Pressing `i` in the terminal where Cannon is running, which provides a prompt interface. +* Using `cast` from a separate terminal session. + +--- + +## 3. Deploying to Testnet or Mainnet + +When ready to deploy on a live network, you must first identify the addresses of the already-deployed core contracts, which are required by your application. + +### Simulate Deployment First (Recommended) + +Before initiating a real deployment, it is strongly recommended to simulate the process to ensure correctness and identify potential issues early. This can be done using: + +```bash +pnpm cannon build --rpc-url $RPC_URL --dry-run --impersonate-all +``` + +Simulating with `--dry-run` prevents any real transactions from being broadcast, while `--impersonate-all` allows Cannon to simulate signatures for all accounts involved. + +--- + +### Deploying Core Contracts to a Real Network + +Once you are confident with the simulated results, proceed to deploy the Cartesi Rollups core contracts using: + +```bash +pnpm cannon build --rpc-url $RPC_URL --private-key $PRIVATE_KEY +``` + +After deployment, use the same `cannon inspect` command to confirm the contract addresses. These addresses will be required in the next stage when deploying your actual application. + +> [!NOTE] +> The deployment method is deterministic, this means the core contracts should always have the same address independently of the chain. This can be false for chains that do not support CREATE2. + +Now you can also deploy your Application contracts to your preferred chain. \ No newline at end of file diff --git a/docs/deployment.md b/docs/interacting.md similarity index 52% rename from docs/deployment.md rename to docs/interacting.md index a2054bf45..aabb5999f 100644 --- a/docs/deployment.md +++ b/docs/interacting.md @@ -1,80 +1,16 @@ # Cartesi Rollups Deployment Tutorial (v2.0) -This tutorial provides a comprehensive guide for deploying a Cartesi Rollups Application. It covers the deployment of both the Cartesi Rollups core contracts and your application-specific contracts. The deployment process leverages key tools like [Cannon](https://usecannon.com/) for reproducible deployments, and *cast* from [Foundry](https://getfoundry.sh/) for interacting with smart contracts. Whether you’re deploying locally for development or targeting a public testnet or mainnet, this tutorial will help you understand and execute each step with confidence. +This tutorial provides a comprehensive guide for deploying a Cartesi Rollups Application. The deployment process described here uses *cast* from [Foundry](https://getfoundry.sh/) for interacting with smart contracts. --- ## 1. Prerequisites -Before beginning, ensure your environment is correctly set up. This includes having: +First, please make sure the core contracts are deployed to the network you are trying to deploy you application to. This is explained in this [tutorial](./deploying.md). -* [Corepack](https://nodejs.org/api/corepack.html), which manages multiple Node.js package managers, -* [Foundry](https://book.getfoundry.sh/getting-started/installation) v1.1.0 or higher, a fast and modular toolkit for Ethereum application development. +Also, ensure the following dependencies are installed as specified in the [Getting Started](./../README.md#getting-started) section. -Next, clone the Cartesi Rollups contracts repository and install its dependencies. This repository contains both the core smart contracts and the application-specific ones: - -```bash -git clone https://github.com/cartesi/rollups-contracts.git -cd rollups-contracts -pnpm install -forge soldeer install -``` - -This setup provides you with all the components needed to work with the Cartesi Rollups contracts. - ---- - -## 2. Running a Local Devnet with Cannon - -To begin development or testing, you can simulate a full Cartesi devnet locally. This is useful for experimentation and validation before deploying to a live network. - -To do so, run: - -```bash -pnpm start -``` - -This command launches Cannon, which deploys the Cartesi Rollups core contracts.. These contracts will be deployed on a local Ethereum JSON-RPC instance at `127.0.0.1:8545`. - -Once running, you can interact with the contracts in one of two ways: - -* Pressing `i` in the terminal where Cannon is running, which provides a prompt interface. -* Using `cast` from a separate terminal session. - ---- - -## 3. Deploying to Testnet or Mainnet - -When ready to deploy on a live network, you must first identify the addresses of the already-deployed core contracts, which are required by your application. - -### Simulate Deployment First (Recommended) - -Before initiating a real deployment, it is strongly recommended to simulate the process to ensure correctness and identify potential issues early. This can be done using: - -```bash -pnpm cannon build --rpc-url $RPC_URL --dry-run --impersonate-all -``` - -Simulating with `--dry-run` prevents any real transactions from being broadcast, while `--impersonate-all` allows Cannon to simulate signatures for all accounts involved. - ---- - -### Deploying Core Contracts to a Real Network - -Once you are confident with the simulated results, proceed to deploy the Cartesi Rollups core contracts using: - -```bash -pnpm cannon build --rpc-url $RPC_URL --private-key $PRIVATE_KEY -``` - -After deployment, use the same `cannon inspect` command to confirm the contract addresses. These addresses will be required in the next stage when deploying your actual application. - -> [!NOTE] -> The deployment method is deterministic, this means the core contracts should always have the same address independently of the chain. This can be false for chains that do not support CREATE2. - ---- - -## 4. Deploying Your Application Using `ISelfHostedApplicationFactory` +## 2. Deploying Your Application Using `ISelfHostedApplicationFactory` Cartesi Applications are deployed using the `ApplicationFactory`. This factory deploys your application contract, but for now, we can use the `SelfHostedApplicationFactory` which is an utility contract to communicate with both the `ApplicationFactory` and the `AuthorityFactory` which is an authoritary settlement module responsible to receive and provide claims. @@ -139,6 +75,9 @@ cast call $SELF_HOSTED_APPLICATION_FACTORY_ADDRESS \ --rpc-url $RPC_URL ``` +> [!TIP] Cannon includes an interactive CLI! +> As an alternative you can also use Cannon interactive CLI to inspect deployed contracts, call functions on them, view state and logs + --- ### c. Deploy the Application + Authority From 7f309ed5e5a7fc8ff7d403d96eb9c68eeaeafbd6 Mon Sep 17 00:00:00 2001 From: Joao Garcia Date: Wed, 9 Jul 2025 14:27:46 +0100 Subject: [PATCH 3/3] added link for Cannon on the tip on interacting tutorial since it does not mention it before --- docs/interacting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/interacting.md b/docs/interacting.md index aabb5999f..9588837df 100644 --- a/docs/interacting.md +++ b/docs/interacting.md @@ -75,7 +75,7 @@ cast call $SELF_HOSTED_APPLICATION_FACTORY_ADDRESS \ --rpc-url $RPC_URL ``` -> [!TIP] Cannon includes an interactive CLI! +> [!TIP] [Cannon](https://usecannon.com/) includes an interactive CLI! > As an alternative you can also use Cannon interactive CLI to inspect deployed contracts, call functions on them, view state and logs ---