Custom Python dApp

This is customized dApp written in Python, which uses the deprecated way of building Cartesi dApp.

Requirements

Docker Desktop is a must-have requirement that comes pre-configured with two necessary plugins for building dApps on Cartesi:

Docker Buildx and
Docker Compose.

Follow the instructions here to install Docker Desktop for your operating system.

Building

To build the application, run the following command:

docker buildx bake -f docker-bake.hcl -f docker-bake.override.hcl --load

Running

To start the application, execute the following command:

docker compose up

The application can afterwards be shut down with the following command:

docker compose down -v

Interacting with the application

We can use the frontend-console application to interact with the dApp.

From within the frontend-console directory, you can send an input as follows:

yarn start input send --payload "Hello there"

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

yarn start notice list

In the example above, the payload of the notice should be "Hello there".

Deploying to a testnet

Deploying the application to a blockchain requires creating a smart contract on that network, as well as running a validator node for the dApp.

The first step is to build the dApp's backend machine, which will produce a hash that serves as a unique identifier.

docker buildx bake -f docker-bake.hcl -f docker-bake.override.hcl machine --load

Once the machine docker image is ready, we can use it to deploy a corresponding Rollups smart contract. This requires you to define a few environment variables to specify which network you are deploying to, which account to use, and which RPC gateway to use when submitting the deploy transaction.

export NETWORK=<network>
export MNEMONIC=<user sequence of twelve words>
export RPC_URL=<https://your.rpc.gateway>

For example, to deploy to the Sepolia testnet using an Alchemy RPC node, you could execute:

export NETWORK=sepolia
export MNEMONIC=<user sequence of twelve words>
export RPC_URL=https://eth-sepolia.g.alchemy.com/v2/<USER_KEY>

With that in place, you can submit a deploy transaction to the CartesiDAppFactory contract on the target network by executing the following command:

DAPP_NAME=my-dapp docker compose -f ./deploy-testnet.yml up

This will create a file at ./deployments/<network>/my-dapp.json with the deployed contract's address. Once the command finishes, it is advisable to stop the docker compose and remove the volumes created when executing it.

DAPP_NAME=my-dapp docker compose -f ./deploy-testnet.yml down -v

After that, a corresponding Cartesi Validator Node must also be instantiated in order to interact with the deployed smart contract on the target network and handle the backend logic of the dApp.

Aside from the environment variables defined above, the node will also need a secure websocket endpoint for the RPC gateway (WSS URL).

For example, for Sepolia and Alchemy, you would set the following additional variable:

export WSS_URL=wss://eth-sepolia.g.alchemy.com/v2/<USER_KEY>

Then, the node itself can be started by running a docker compose as follows:

DAPP_NAME=my-dapp</dapp-name> docker compose --env-file ./env.<network> -f ./docker-compose-testnet.yml -f ./docker-compose.override.yml up

Which, in the case of Sepolia, would be:

DAPP_NAME=my-dapp</dapp-name> docker compose --env-file ./env.sepolia -f ./docker-compose-testnet.yml -f ./docker-compose.override.yml up

Interacting with the deployed application

With the node running, you can interact with the deployed dApp using the frontend-console, as described previously. This time, however, you need to specify the appropriate connectivity configurations.

First of all, in the separate terminal for the frontend-console, define the MNEMONIC and RPC_URL variables as before:

export MNEMONIC=<user sequence of twelve words>
export RPC_URL=<https://your.rpc.gateway>

Then, inputs can be sent by specifying the dApp contract's address, as follows:

yarn start input send --payload "Hello there" --addressFile path/to/my-dapp/deployments/<network>/my-dapp.json

Resulting notices can then be retrieved by querying the local Cartesi Node, as before:

yarn start notice list

Running the backend 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 backend can be executed directly on the host machine, allowing it to be debugged using regular development tools such as an IDE.

The host environment can be executed with the following command:

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

This dApp's backend is written in Python, so to run it in your machine you need to have python3 installed.

In order to start the backend, run the following commands in a dedicated terminal:

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
ROLLUP_HTTP_SERVER_URL="http://127.0.0.1:5004" python3 my-dapp.py

The final command will effectively run the backend 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 backend automatically when the code changes. For example:

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

After the backend 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.

masiedu4 / custom-python-dapp