NumPy Matrix Multiplication — Cartesi App

A Cartesi application that performs matrix multiplication using NumPy. Send any two matrices as input and receive the result as an on-chain notice.

How it works

The application receives a JSON payload containing two matrices, multiplies them using numpy.matmul, and emits the result as a rollup notice.

• Advance (state-changing): result is emitted as a notice
• Inspect (read-only): result is emitted as a report

Requirements

• Cartesi CLI
• Docker with QEMU support (for riscv64 emulation)

Building

Because the Cartesi machine runs on linux/riscv64, NumPy must be compiled for that architecture. A helper script handles this by building a pre-compiled wheel using Docker + QEMU emulation.

Step 1 — Build the NumPy wheel (once):

./build-wheels.sh

This compiles NumPy for linux/riscv64 and saves the wheel to wheels/. Only needs to be re-run if you change the NumPy version in requirements.txt.

Step 2 — Build the Cartesi machine:

cartesi build

Running

Start the local Cartesi node:

cartesi run

Sending an input

Use the Cartesi CLI to send an advance-state input. The payload must be a JSON object with matrix_a and matrix_b keys, each containing a 2D array:

cartesi send generic

When prompted for the hex payload, encode the following JSON:

{"matrix_a": [[1, 2], [3, 4]], "matrix_b": [[5, 6], [7, 8]]}

Example result

$$ \begin{bmatrix}1&2\\3&4\end{bmatrix} \times \begin{bmatrix}5&6\\7&8\end{bmatrix} = \begin{bmatrix}19&22\\43&50\end{bmatrix} $$

The application emits a notice with:

{"result": [[19.0, 22.0], [43.0, 50.0]]}

Constraints

• The number of columns in matrix_a must equal the number of rows in matrix_b
• Matrices can be any valid shape, not just square
• On invalid input the application rejects the input and emits an error report

Project structure

dapp.py            # App logic — decodes input, runs matmul, emits notice
requirements.txt   # Python dependencies (requests, numpy)
Dockerfile         # Cartesi machine image definition
build-wheels.sh    # Builds the riscv64 NumPy wheel using Docker + QEMU
wheels/            # Pre-built riscv64 wheels (generated by build-wheels.sh)

Notes on NumPy and riscv64

PyPI does not distribute pre-built NumPy wheels for linux/riscv64, so pip would normally compile it from source — requiring a full build toolchain inside the Docker image. The build-wheels.sh script solves this by building the wheel once on your host using QEMU emulation and committing it to the wheels/ folder. The Dockerfile then installs from that local wheel with no compilation required at build time.

NumPy is built without OpenBLAS (NPY_BLAS_ORDER="") to produce a self-contained wheel with no external shared library dependencies, which is required for the slim Cartesi base image.