Quick Start

This article explains how to build and interact with a minimalistic Cartesi Rollups application.

By the end of this tutorial, you will learn how to run a simple existing dApp written in Python, called Echo-Python.

note

You can inspect the full code of the Echo Python dApp in Cartesi's public Github repository.

Overview

The Echo-Python dApp simply copies (or "echoes") each input received as a corresponding output notice. The dApp's back-end is written in Python, and its front-end is a simple console application written in Typescript that can be executed from a terminal.

The Quick Start guide consists of 5 main steps:

1. Installing
2. Building
3. Running
4. Interacting
5. Deploying

Installing

Follow the manual setup to make sure you have installed all the necessary requirements locally.

Building

To build the echo-python example:

1. Clone the cartesi/rollups-examples Github repository, and cd into it:

git clone https://github.com/cartesi/rollups-examples.git
cd rollups-examples

2. Navigate to the dApp example directory by running the following command:

cd echo-python

3. Check if your Docker supports the RISCV platform by running:

docker buildx ls

If you do not see linux/riscv64 in the platforms list, install QEMU by running:

apt install qemu-user-static

QEMU is a generic and open source machine emulator and virtualizer that will be used by Docker to emulate RISCV instructions to build a Cartesi Machine for your dApp.

After installing QEMU, the platform linux/riscv64 should appear in the platforms list.

4. Build the Echo dApp:

docker buildx bake --load

Running

To run the application, you can start an environment that includes a local blockchain with the Cartesi smart contracts deployed, as well as a Cartesi L2 node executing the dApp's back-end logic.

docker compose -f ../docker-compose.yml -f ./docker-compose.override.yml up

After you see the expected logs below, you can go to the Interacting Step.

Expected logs

Allow some time for the infrastructure to be ready. How much will depend on your system, but eventually the container logs will only show the continuous production of empty blocks in the local blockchain, as displayed below:

rollups-examples-hardhat-1                      | Mined empty block range #32 to #33
rollups-examples-hardhat-1                      | Mined empty block range #32 to #34
rollups-examples-hardhat-1                      | Mined empty block range #32 to #35
rollups-examples-hardhat-1                      | Mined empty block range #32 to #36

How to shutdown the environment

You can shutdown the environment by running:

docker compose -f ../docker-compose.yml -f ./docker-compose.override.yml down -v

note

Every time you stop the docker compose ... up command with ctrl+c, you need to run the docker compose ... down -v command to remove the volumes and containers. Ignoring this will preserve outdated information in those volumes, causing unexpected behaviors, such as failure to reset the hardhat localchain.

Interacting with the dApp

There are two ways to interact with the dApp:

• Locally
• Remotely

Frontend-console application

With the infrastructure in place, you can use our frontend-console application to interact with the Echo dApp.

Every Rollups dApp gets an address on the base layer when it's deployed. The following is needed to send inputs to a dApp:

• Gateway URL to the intended chain
• Cartesi Rollups InputBox contract address
• Appropriate account with sufficient funds for submitting transactions to the network

Interacting locally with the dApp

With the infrastructure in place, you can use our frontend-console application to interact with the Echo dApp by following the steps:

1. Open a separate terminal window
2. From the rollups-examples base directory, navigate to the frontend-console one:

cd frontend-console

3. Build the frontend console application:

yarn
yarn build

4. Send an input to the current locally deployed dApp:

yarn start input send --payload "Hello, Cartesi."

5. Verify the outputs (notices) generated by your input:

yarn start notice list

After completing all the steps above, you should get a response with the payload of the notice:

"Hello, Cartesi."

tip

You can run the Cartesi Rollups environment locally in host mode. Please follow the guide on how to run dApp back-ends in Host Mode, but before that make sure to shutdown the current running environment.

note

For more information about the frontend-console application and its options, please check the frontend-console documentation.

Interacting with remotely deployed dApps

The Echo dApp example is already deployed on a public blockchain test network called Goerli, which is an Ethereum testnet.

You can use the same frontend-console application to interact with it, as described below.

note

Please refer to the frontend-console documentation for details on how to use it to send inputs, list notices and deposit ERC-20 tokens.

The following steps describe how to send an input to the Echo dApp instance that is already deployed on Goerli:

1. Open a separate terminal window
2. Navigate to the frontend-console directory:

cd frontend-console

3. Build the project:

yarn
yarn build

4. You can follow this tutorial to create an Ethereum account using Metamask. Make sure to save the Secret Backup Phrase (MNEMONIC user sequence of twelve words)
5. Get testnet funds/tokens on Goerli to be able to submit transactions on that network. There are several faucets available, you may try https://goerlifaucet.com/, https://goerli-faucet.slock.it/ or https://faucet.chainstack.com/goerli-faucet
6. Create an Alchemy account to obtain an API key for reliable access to the Goerli network. Alternatively, you can use other options such as Infura or Chainstack
7. Configure your account on Goerli by running the commands below, which specify the network and MNEMONIC (Secret Backup Phrase) to use. The MNEMONIC is always specified as a string sequence of twelve words. In this example, use the MNEMONIC that you received when creating the Ethereum account using Metamask as described in step 4.

export NETWORK=goerli
export MNEMONIC="word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12"

8. Configure your Alchemy RPC gateway URL for Goerli:

export RPC_URL=https://eth-goerli.alchemyapi.io/v2/<Replace_This_With_Your_Alchemy_API_key>

9. Send an input:

yarn start input send --payload "Hello, Cartesi." --dapp echo-python

10. Query the L2 Cartesi Node for notices produced by the dApp:

yarn start notice list --url https://echo-python.goerli.rollups.staging.cartesi.io/graphql

11. You should get a response with the payload of the notice: "Hello, Cartesi."

tip

As shown in the last step (number 10), to query the L2 Cartesi Node for dApp outputs, you will need to specify the URL of its GraphQL endpoint. You can find other existing examples endpoints in the dApp table below.

Explore our dApps

You can find several Cartesi dApp examples on GitHub, such as the following:

dApp Name	dApp Deployment Status on Goerli Testnet	GraphQL endpoint URL
Echo Python	Yes	https://echo-python.goerli.rollups.staging.cartesi.io/graphql
Echo C++	Yes	https://echo-cpp.goerli.rollups.staging.cartesi.io/graphql
Echo Rust	No	-
Echo Lua	Yes	https://echo-lua.goerli.rollups.staging.cartesi.io/graphql
Echo JS dApp	Yes	https://echo-js.goerli.rollups.staging.cartesi.io/graphql
Echo Low-Level	Yes	https://echo-low-level.goerli.rollups.staging.cartesi.io/graphql
Converter	No	-
Calculator	No	_
SQLite	Yes	https://sqlite.goerli.rollups.staging.cartesi.io/graphql
k-NN	Yes	https://knn.goerli.rollups.staging.cartesi.io/graphql
m2cgen	No	-
ERC-20	No	-
Auction	No	-