Cartesify REST - HLF

Cartesify HLF

Bruno aka @sandhilt and I are focused on growing Cartesi’s adoption, especially among web2 developers. Our proposal introduces a REST abstraction layer to the current technology stack, aiming to simplify onboarding. By taking advantage of the familiarity developers have with RESTful architectures, we aim to facilitate the transition from web2 to web3 with minimal effort. This approach aligns with our goal of creating a more developer-friendly ecosystem and expanding Cartesi’s reach within the broader community.


The latest Stack Overflow survey shows that the majority of developers are web developers.

Some Advantages

  1. Low Learning Curve:

    • Web2 developers are already familiar with REST APIs, making it easier for them to transition into Cartesi Rollups without a steep learning curve.
    • Leveraging existing knowledge helps developers become productive more quickly.
  2. Widely Adopted:

    • REST is a widely adopted in the development community, ensuring compatibility with a broad range of programming languages and frameworks.
    • This increases the chances of widespread adoption and support within the developer community.
  3. Adapting Existing Systems:

    • Many web2 applications are built on RESTful architectures, and integrating Cartesi Rollups through REST would allow for migration with existing systems with low effort.
    • This enables developers to incorporate Cartesi technology into their current projects viable.
  4. Future evolution:

    • The basic HTTP calls will allow this HLF to start with RESTful APIs and later evolve to more complex communication protocols like GraphQL or gRPC.
  5. Community Adoption:

    • By providing a REST API for Cartesi Rollups, you can attract a larger audience, particularly developers who may not be familiar with blockchain or specialized technologies.
  6. Documentation and Tooling:

    • RESTful APIs come with established standards for documentation (e.g., OpenAPI) and tooling, making it easier for developers to understand, use, and integrate Cartesi Rollups.


Given this minimal backend code:

const express = require("express")

const app = express();
const port = 8383;
app.use(express.json());'/hit', (req, res) => {
    res.send({ amount: req.body.amount });

app.listen(port, () => {
    console.log(`[server]: Server is running at http://localhost:${port}`);

The frontend code to make an HTTP POST request to the backend using Cartesify will be:

const handleHit = async () => {
    const res = await"/hit", { amount: 1234 });

When triggered, the code above will print {"amount": 1234} in the console.

Tech details

All the REST verbs that make changes to the state (POST, PUT, PATCH, DELETE) will be signed by the private key, possibly using a wallet like MetaMask, and will be implemented using the advance command. The GET operation will be implemented using the inspect command.

As a web2 developer, we will achieve battle-proof authentication by adding the msg_sender to the request headers.

// express code'/hit', (req, res) => {
    const msgSender = req.get('x-msg_sender');
    res.send({ amount: req.body.amount });

Additionally, web2 developers will benefit from an atomic operation. If the endpoint returns an error, such as a 4xx or 5xx status code, we will send a reject that performs a rollback operation, thanks to the Cartesi technology as pointed out by @gabrielbarros.


We will set up a protected webhook by convention, pointing to /webhooks/deposits, which can be configurable.

    "success": true,
    "erc20": "0x4ed7c70F96B99c776995fB64377f0d4aB3B0e1C1",
    "depositor": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
    "amount": "100",

Hi @fabio.oshiro! Very cool approach, I’ve often thought about a nice way of encapsulating things the way you are envisioning. I’ve got a few questions:

  1. I’m not sure I understood how your back-end code works. You are running Express inside the machine on port 8383, and there is also a BackCartesify service running (in place of the HTTP API) that interacts with the rollup device and calls the Express server?
  2. How would you encode vouchers in the back-end? I think res.send({ ... }) in the back-end would emit a notice, right?
  3. How would you retrieve and execute vouchers in the front-end?
1 Like

It’s an idea for a future optimization. If the Cartesi REST concept evolves, we will develop a better solution called “BackCartesify” to access the rollups device directly.

The Rollups HTTP Server will still be there to send vouchers and notices. Currently, we are only generating reports, but it’s easy to change.

We’re thinking about it. In our initial work with Solana, we handled deposit and voucher execution, etc. We need to revisit this topic because the code is outdated.

1 Like

I love the idea of using express and flask for development. The one thing I keep asking myself is, if code 4xx and 5xx sends a reject, shouldn’t the res.send() with status 200 only send “accept” and not notices? (Not saying it should, just raising this point)

1 Like

Hey there!

I like this approach, especially in terms of Statistics. It makes a lot of sense to bring REST to the game; almost every API project I’ve worked on so far in web2 used REST.

This resonates with the masterclass students, where the majority were web developers, especially JavaScript users.

Just a question: If I understood well, this also changes how developers integrate their frontends with our cartesi backend, right?
Also, with this approach, can we expect that the time for the data workflow will increase, right?

1 Like

I loved the approach! I think leveraging people’s knowledge of RESTful and the ‘verbs’ to introduce people to the basic concepts of interaction with blockchain is an excellent idea.

If we search for it, we can find issues and limitations with this design, of course, but honestly, as a bridge, this is really good. As the idea of coding a ‘backend’ with such special properties starts to sink into the developer’s mind, they can slowly add more customizations to your framework or even leave it altogether.

1 Like

I believe that the time will increase slightly because we will need to perform serialization and deserialization using JSON, as well as the time it takes for the chosen framework to respond.

1 Like

We are sending a report at the end of the HTTP request. This report is to provide feedback to the frontend with the response from the backend running within the Cartesi Machine.
And yes!! Additionally, the 200 status code will trigger a accept POST request to the /finish endpoint of the rollups server.

Hi Fabio! Im a fundamental advocate of convenience as a roadblock remover for adoption! So whenever I read convenience I tend to give thumbs up :slight_smile:

Thanks for a very detailed proposal and your time on digging into that so important topic!

I have a few questions to learn more:

1 - As I understood this new API will sit on top of the existing HTTP API right?

2 - How that connect with the other HLF that has been developed taking into consideration the HTTP API?

3 - Is there any impact on Sunodo? Sunodo brings a template for builders to use, so I presume the Sunodo template should come with your HLF, right? My goal here is to ensure we have a cohesive experience for developers putting all our improvements aligned within the same developer journey

Yes, the existing HTTP API will remain the same.

We will maintain all other frameworks.

Good suggestion! We will take a look at the templates repository to add a REST template.


Hi guys! Take a look at our first example to get a preview of what we’ve been working on: cartesify-nodejs-rest-example.
Your insights and suggestions are really welcome as we continue to refine and improve our frameworks.

1 Like

Hi Guys, we developed an example using Tim’s rock paper scissor tutorial using Cartesify: GitHub - Calindra/cartesify-rock-paper-scissors: Tim's Rock Paper Scissors example using Cartesify. Also you can check a full template (backend and frontend) here: GitHub - Calindra/cartesify-template: Cartesify Template for Sunodo


We are using the Cartesi Store as our lab to give to dev community the best experience.
Clone the project, install the backend, and run pnpm run dev, we expect you to have a backend auto-reload when you edit the code, with nonodo running.
And, of course, an easy way to communicate between the frontend and backend through the Cartesify REST framework.