In this section, we will explain how to run a simple Echo DApp example that shows how to build and interact with a minimalistic Cartesi Rollups application that 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.

Before getting started, make sure you have installed all the necessary requirements.

Building

To build the echo-python example, start by cloning the cartesi/rollups-examples Github repository as follows:

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

Then, switch to the appropriate directory and build it:

cd rollups-examples/echo-python
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

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

The environment can be shut down with the following command:

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

Interacting with the application

With the infrastructure in place, we can use the frontend-console application included in the repository to interact with the DApp.

First, go to a separate terminal window, switch to the frontend-console directory, and build it:

cd frontend-console
yarn
yarn build

Then, send an input as follows:

yarn start send --input "Hello there"

In order to verify the notices generated by your inputs, run the command:

yarn start notices

The response should be something like this:

[ { epoch: '0', input: '1', notice: '0', payload: 'Hello there' } ]

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

Running the back-end in host mode

When developing an application, it is often important to easily test and debug it. For that matter, it is possible to run the Cartesi Rollups environment in host mode, so that the DApp's back-end can be executed directly on the host machine, allowing it to be debugged using regular development tools such as an IDE.

The first step is to run the environment in host mode using the following command:

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

The next step is to run the application back-end in your machine. Its code is written in Python, so you need to have python3 installed.

In order to start the back-end, run the following commands in a dedicated terminal:

cd echo-python/
python3 -m venv .env
. .env/bin/activate
pip install -r requirements.txt
ROLLUP_HTTP_SERVER_URL="http://127.0.0.1:5004" python3 echo.py

The final command will effectively run the back-end and send corresponding outputs to port 5004. It can optionally be configured in an IDE to allow interactive debugging using features like breakpoints.

You can also use a tool like entr to restart the back-end automatically when the code changes. For example:

ls *.py | ROLLUP_HTTP_SERVER_URL="http://127.0.0.1:5004" entr -r python3 echo.py

After the back-end successfully starts, it should print an output like the following:

INFO:__main__:HTTP rollup_server url is http://127.0.0.1:5004
INFO:__main__:Sending finish

After that, you can interact with the application normally as explained above.

Finally, to stop the containers, removing any associated volumes, execute:

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