fgc_betting DApp

fgc_betting is a customized DApp written in Python, which originally resembles the one provided by the sample Echo Python DApp. Contrary to that example, this DApp does not use shared resources from the rollups-examples main directory, and as such the commands for building, running and deploying it are slightly different.

The documentation below reflects the original application code, and should also be used as a basis for documenting any DApp created with this mechanism.

Requirements

Please refer to the rollups-examples requirements.

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 rollups-examples frontend-console application to interact with the DApp. Ensure that the application has already been built before using it.

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

The response should be something like this:

[ { epoch: '0', input: '1', notice: '0', payload: '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 back-end 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 Goerli testnet using an Alchemy RPC node, you could execute:

export NETWORK=goerli
export MNEMONIC=<user sequence of twelve words>
export RPC_URL=https://eth-goerli.alchemyapi.io/v2/<USER_KEY>

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

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

This will create a file at ./deployments/<network>/fgc_betting.address 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=fgc_betting 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 back-end 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) and the chain ID of the target network.

For example, for Goerli and Alchemy, you would set the following additional variables:

export WSS_URL=wss://eth-goerli.alchemyapi.io/v2/<USER_KEY>
export CHAIN_ID=5

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

DAPP_NAME=mydapp docker compose -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/fgc_betting/deployments/<network>/fgc_betting.address

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

yarn start notice list

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.

This DApp's back-end is written in Python, so to run it in your machine you need to have python3 installed.

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

python3 -m venv .env
. .env/bin/activate
pip install -r requirements.txt
ROLLUP_HTTP_SERVER_URL="http://127.0.0.1:5004" python3 fgc_betting.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 fgc_betting.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.