From 8a81e6177f88ab05fded75904ee6f7e899f8e060 Mon Sep 17 00:00:00 2001 From: Idogwu Chinonso Date: Sun, 22 Mar 2026 23:51:06 +0100 Subject: [PATCH] mod: updated v2.0 deployment guide --- .../version-2.0/deployment/self-hosted.md | 98 ++++++++++++------- 1 file changed, 64 insertions(+), 34 deletions(-) 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 index 4affc444..e904e6b9 100644 --- a/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted.md +++ b/cartesi-rollups_versioned_docs/version-2.0/deployment/self-hosted.md @@ -6,14 +6,14 @@ title: Self-hosted deployment This guide explains how to run a Cartesi Rollups node locally on your machine for development and testing purposes on **testnet**. :::warning Production Warning -**This self-hosted approach should NOT be used in *production*.** +**This self-hosted approach should NOT be used in _production_.** While this setup works with testnet environments, it's designed exclusively for development purposes. It lacks critical production requirements such as: - Public snapshot verification - Proper security hardening -- Production-grade infrastructure -::: +- Production-grade infrastructure. + ::: ## Prerequisites @@ -31,42 +31,37 @@ Before running the node, you need to configure your `.env` file with the followi ```shell BLOCKCHAIN_ID= -AUTH_KIND="private_key_file" -PRIVATE_KEY_FILE="/run/secrets/pk" +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 | -| `PRIVATE_KEY_FILE` | Points to the private key file created in [**step 2**](#setting-up-the-local-node) | -| `AUTH_KIND` | Set to `"private_key_file"` for local development | +| 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` | + +:::danger Security +Ensure to follow best practices when handling private keys during local development and deployment to production. +::: ## Setting up the local node 1. **Download the Cartesi Rollups Node docker compose file in your project root:** ```shell - curl -L https://raw.githubusercontent.com/cartesi/docs/refs/heads/docs/deployment/cartesi-rollups_versioned_docs/version-2.0/deployment/src/compose.local.yaml -o compose.local.yaml + curl -L https://raw.githubusercontent.com/Mugen-Builders/deployment-setup-v2.0/main/compose.local.yaml -o compose.local.yaml ``` -2. **Create a secret for private key storage:** - - ```shell - mkdir -p secrets - echo "YOUR_PRIVATE_KEY" > secrets/pk - ``` - - :::danger Security - Ensure the `secrets/` directory is in a secure location and has restricted permissions, different from the project root to avoid leaking your private key. - ::: - -3. **Build the application with the Cartesi CLI:** +2. **Build the application with the Cartesi CLI:** ```shell cartesi build @@ -74,7 +69,7 @@ BLOCKCHAIN_HTTP_ENDPOINT="" This command compiles your application into RISC-V architecture and creates a Cartesi machine snapshot locally. -4. **Run the Cartesi Rollups Node with the application's initial snapshot attached:** +3. **Run the Cartesi Rollups Node with the application's initial snapshot attached:** ```shell docker compose -f compose.local.yaml --env-file .env up -d @@ -82,15 +77,14 @@ BLOCKCHAIN_HTTP_ENDPOINT="" This starts the local node using the configuration from your `.env` file. -5. **Deploy and register the application to the node:** +4. **Deploy and register the application to the node:** ```shell docker compose --project-name cartesi-rollups-node \ - exec advancer cartesi-rollups-cli deploy application /var/lib/cartesi-rollups-node/snapshot \ - --epoch-length 720 \ - --self-hosted \ - --salt \ - --json + exec advancer cartesi-rollups-cli deploy application /var/lib/cartesi-rollups-node/snapshot \ + --epoch-length 10 \ + --salt \ + --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: @@ -101,9 +95,45 @@ BLOCKCHAIN_HTTP_ENDPOINT="" 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. + + ### 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). + + ```shell + cast send "newAuthority(address,uint256)" \ + 10 --private-key --rpc-url \ + --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. + + 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. + + ```shell + docker compose --project-name cartesi-rollups-node \ + exec advancer cartesi-rollups-cli deploy application /var/lib/cartesi-rollups-node/snapshot \ + --epoch-length 10 \ + --consensus \ + --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. + +## Deployed Contracts: + +Depending on your intended deployment chain, you can find the list of required contracts like the Inputbox, Portals, Authority Factory etc, below: + +- [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) + ## Accessing the node Once running, your local Cartesi Rollups Node will be accessible through the standard APIs: -- Inspect endpoint: `http://localhost:10012` -- JSON-RPC endpoint: `http://localhost:10011` \ No newline at end of file +- Inspect endpoint: `http://localhost:10012/inspect/` +- JSON-RPC endpoint: `http://localhost:10011/rpc`