Skip to content

Latest commit

 

History

History
 
 

calculator

README.md

Calculator DApp

Calculator is a DApp written in Python that evaluates mathematical expressions with the help of the Python Mathematical Expression Evaluator (py-expression-eval).

The DApp receives mathematical expressions as inputs and generates notices with the result of the corresponding evaluations. For example, the following expression is a valid input:

$$3 + 2 + 5 - 9$$

Installing extra dependencies

As explained above, the Calculator DApp requires py-expression-eval to work. Such module is not available on the default Python installation that comes with the Cartesi Machine.

In order to install extra libraries, the DApp build configuration must be adapted before proceeding with the build process as usual.

Changing the build configuration

First of all, all modules required by the DApp must be appended to requirements.txt.

In order to install the modules during the DApp build process, we need to compile a customized version of Python for RISC-V. This can be done using the Docker image toolchain-python, as defined in ../docker/Dockerfile. To have this image built before the DApp, we should change the build configuration for target dapp by adjusting docker-bake.override.hcl so that the target toolchain-python (already defined in docker-bake.hcl) takes precedence over it. The resulting configuration should look like this:

target "dapp" {
  contexts = {
    toolchain-python = "target:toolchain-python"
  }
}
...

Finally, the DApp image definition must be changed to be based on toolchain-python, which will allow the modules defined in requirements.txt to be installed. This may be accomplished by updating the DApp's Dockerfile as follows:

# syntax=docker.io/docker/dockerfile:1.4
FROM toolchain-python

WORKDIR /opt/cartesi/dapp
COPY . .

RUN <<EOF
python3 -m crossenv $(which python3) .venv
. ./.venv/bin/activate
pip install -r requirements.txt
EOF

Note: This procedure works out-of-the-box for pure Python modules. Modules that depend on native libraries are out of the scope of these instructions.

Increasing file system size

The DApp file system size must be increased in order to accommodate the new modules.

This is accomplished by adjusting the DApp's own configuration file, dapp.json, as follows:

  • Include directory .venv, where the modules were installed, in the file system;
  • Overriding the default file system size, defined as fs.size at ../docker/default.json. Values are stated in bytes.

The resulting dapp.json file is listed below:

{
  "fs": {
    "files": [".venv", "calculator.py", "entrypoint.sh"],
    "size": 128000
  }
}

Changing runtime configuration

In order to make the installed modules available, PYTHONPATH must be defined in the DApp's entry point script as follows:

set -e
PYTHONPATH=/mnt/dapp/.venv/cross/lib/python3.10/site-packages python3 calculator.py

Interacting with the application

We can use the frontend-console application to interact with the DApp. Ensure that the application has already been built before using it.

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

cd frontend-console

Then, send an input as follows:

yarn start input send --payload "3 + 2 + 5 - 9"

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": "1" }]

Running the environment 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 calculator back-end, run the following commands in a dedicated terminal:

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

This will run the calculator back-end and send the corresponding notices 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 calculator.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.