Skip to main content

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

note

You can use online development environments such as Gitpod and CodeSandbox to open the rollups-exmaples directly in your browser with all required dependencies already installed. These services allow you to start experimenting immediately, but keep in mind that they are provided by third-parties and are subject to unavailability and policy changes. They may also require access to your GitHub account in order to work properly.

There are two different options to setup the prerequisites, you can choose one of the following:

  1. Using Gitpod as a fast option
  2. Using manual setup to install all the necessary requirements locally

Using Gitpod

Open in Gitpod

This is an easy and fast setup, you need to follow the steps:

  1. Navigate to Gitpod rollups-examples to automate your development setup
  2. When you click on the link above, it will forward you to login options.
  3. Login with your preferable option via GitLab, GitHub, or Bitbucket.
  4. Provide authorization to GitLab, GitHub, or Bitbucket.
  5. Congratulations, you have successfully setup your development environment
  6. Start Building our Echo DApp

Using manual setup

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

Building

To build the echo-python example:

tip

If you are running your environment using the Gitpod option explained above, then please start from step number 2 as you will not need to clone the Github repository.

  1. Clone the cartesi/rollups-examples Github repository by running the following command:
git clone https://github.com/cartesi/rollups-examples.git
  1. Navigate to the DApp example directory by running the following command:
cd rollups-examples/echo-python
  1. Build the Echo DApp by running the following command:
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 layer-2 node executing the DApp's back-end logic.

This can be done by running the following command:

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 after some time showing the error "concurrent call in session", eventually the container logs will repeatedly show the following:

server_manager_1      | Received GetVersion
server_manager_1 | Received GetStatus
server_manager_1 | default_rollups_id
server_manager_1 | Received GetSessionStatus for session default_rollups_id
server_manager_1 | 0
server_manager_1 | Received GetEpochStatus for session default_rollups_id epoch 0

Advancing time

When executing an example, it is possible to advance time to simulate the passing of epochs. To do that, run:

curl --data '{"id":1337,"jsonrpc":"2.0","method":"evm_increaseTime","params":[864010]}' http://localhost:8545

How to shutdown the environment

You can shutdown the environment by running the following command:

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

Interacting with the DApp

There are two ways to interact with the DApp:

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
  1. Build the frontend console application:
yarn
yarn build
  1. Send an input to the current locally deployed DApp:
yarn start input send --payload "Hello Blockchain OS!"
  1. Verify the outputs (notices) generated by your input, to display your DApp notices run the following command:
yarn start notice list

After completing all the steps above, you should get a response similar to the following:

[ { epoch: '0', input: '1', notice: '0', payload: 'Hello Blockchain OS!' } ]
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
  1. Build the project:
yarn
yarn build
  1. 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)
  2. 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/ or https://goerli-faucet.slock.it/
  3. 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 Moralis
  4. Configure your account on Goerli by running the commands below, which specify the network and MNEMONIC (Secret Backup Phrase) to use:
export NETWORK=goerli
export MNEMONIC=<paste here your user sequence of twelve words>
  1. Configure your Alchemy RPC gateway URL for Goerli by running the following command:
export RPC_URL=https://eth-goerli.alchemyapi.io/v2/<Replace_This_With_Your_Alchemy_API_key>
  1. Send an input by running the command:
yarn start input send --payload "my new message" --dapp echo-python
  1. Query the layer-2 Cartesi Node for notices produced by the DApp:
yarn start notice list --url https://echo-python.goerli.rollups.staging.cartesi.io/graphql
tip

As shown in the last step (number 10), to query the layer-2 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 NameDApp Deployment Status on Goerli TestnetGraphQL endpoint URL
Echo PythonYeshttps://echo-python.goerli.rollups.staging.cartesi.io/graphql
Echo C++Yeshttps://echo-cpp.goerli.rollups.staging.cartesi.io/graphql
Echo RustNo-
Echo LuaYeshttps://echo-lua.goerli.rollups.staging.cartesi.io/graphql
Echo JS DAppYeshttps://echo-js.goerli.rollups.staging.cartesi.io/graphql
Echo Low-LevelYeshttps://echo-low-level.goerli.rollups.staging.cartesi.io/graphql
ConverterNo-
CalculatorNo_
SQLiteYeshttps://sqlite.goerli.rollups.staging.cartesi.io/graphql
k-NNYeshttps://knn.goerli.rollups.staging.cartesi.io/graphql
m2cgenNo-
ERC-20No-
AuctionNo-

Deploying DApps to Cartesi's infrastructure

Cartesi Rollups DApps are intended to be deployed to public blockchains, so that they can be accessed by users. This can be done by taking advantage of a cloud-based infrastructure provided by Cartesi.

As happens with any blockchain application, the act of "deploying a DApp" involves publishing its smart contract so that it is publicly available and usable by clients or front-end applications. In the context of a Cartesi DApp, the smart contract is represented by an arbitrary back-end program that runs on Linux inside a Cartesi Node. This means that deploying Cartesi DApps basically corresponds to instantiating Cartesi Nodes that run the intended back-end logic of the application.

In order to facilitate the instantiation of such nodes, Cartesi provides an infrastructure for easily getting them running in the cloud. Developers are thus invited to take advantage of this convenience service in order to jump-start bringing their applications to public blockchains.

Additional resources

We use cookies to ensure that we give you the best experience on our website. By using the website, you agree to the use of cookies.