Cartesi DApps are here

5 steps to develop applications on the blockchain OS

Cartesi Foundation
Published in
11 min readDec 29, 2021



Let’s just face it: blockchain development is still hard and limited at its current stage. And while it is true that the blockchain community has committed enormous amounts of energy and effort to tackle some of these issues, a number of them have remained pretty much unaddressed so far.

For starters, given the inherent restrictions of current blockchain technologies, real-world decentralized applications or DApps are still quite limited in terms of complexity. Not being able to loop through an array many times, perform string operations, or simply use a database, are limitations that daunt any developer who dares to venture into the blockchain world. Moreover, when compared to what the mainstream software industry enjoys, the technology and tools available for building DApps are all relatively new and immature, even for the Ethereum ecosystem.

In practical terms, this all means that there’s a huge barrier of entry for the vast majority of developers out there, which severely hinders the growth and adoption of blockchain technology in general. At Cartesi, we believe that creating decentralized applications should not be too different from building desktop, web, or mobile apps. In this article, we show how Cartesi Rollups can fulfill this vision, giving developers access to a full operating system on the blockchain for the first time, along with the flexibility of using the software stacks and tools of their choosing.

Technological background

As originally described in Erick de Moura’s article “Cartesi Rollups — Scalable smart contracts built with mainstream software stacks”, Cartesi Rollups is a Layer-2 framework in which application logic can be developed on top of an actual operating system such as Linux, but still integrated with an underlying Layer-1 blockchain and secured by it.

Over the past year, we at Cartesi have worked hard to implement this framework. We have released several articles describing its parts, explaining the reasons for the design decisions we made and showing how everything works together. You can check those out to understand in detail how our on-chain smart contracts were implemented as well as how the off-chain Layer-2 nodes work, which leverage our RISC-V Cartesi Machine to allow verifiable computing to be executed on top of Linux.

Now, we are happy to announce that an alpha version of the entire solution is being publicly released and that we have reached the point in which our dream has come true: to enable anyone to develop decentralized applications of arbitrary complexity, using mainstream development tools and software stacks, and have all of it sit on top of established blockchain networks such as Ethereum, Polygon, Avalanche or Binance Smart Chain.

Architecture of a Cartesi DApp

Broadly speaking, from a developer’s point of view, a Cartesi DApp is composed of two main parts: a front-end and a back-end.

Borrowing from familiar mainstream terminology, the front-end corresponds to the user-facing interface, which will often provide a GUI (e.g., a web application) but may also be just a command-line interface (e.g., a Hardhat task using ethers.js, or a command-line tool written in Python).

On the other hand, the back-end of a Cartesi DApp contains the business logic of the application, similar to what traditional systems would run inside a server. The difference here — and the reason for using blockchain technology in general — is that for decentralized applications there is a need for this back-end logic to be verifiable and hence trustless. As such, it is executed inside Cartesi Rollups, which stores and updates the application state as user input is received, producing corresponding outputs. These outputs can come in the form of vouchers (transactions that can be carried out on Layer-1, such as a transfer of assets) and notices (informational statements, such as the resulting score of a game). In practical terms, a Cartesi DApp back-end can be seen as a smart contract, but on steroids.

Aside from these two main components, the DApp front-end can of course also make use of external resources such as 3rd-party services. Indeed, for more complex DApps it is expected that there will be other back-ends besides the one running inside Cartesi Rollups. These would be used whenever the application doesn’t really need a service to be decentralized and verifiable, such as providing fast and accessible data caches, helping users communicate with each other, or interfacing with other non-blockchain services.

When compared to traditional software development, the main difference of a Cartesi DApp is that the back-end is deployed to a decentralized network of Layer-2 nodes, who continuously verify the correctness of all processing results. As a consequence, the front-end and back-end do not communicate directly with each other. Rather, the front-end sends inputs to the Cartesi Rollups framework, who in turn makes them available to the back-end instances running inside each node. After the inputs are processed by the back-end logic, the corresponding outputs are then informed back to the Rollups framework, which enforces their correctness before making them available to the front-end and any other interested parties.

The diagram below illustrates how all of this works from the point of view of the developer:

Here, the green boxes represent the parts that the developer needs to implement to build a DApp, while the parts in purple correspond to the general Rollups framework provided by Cartesi. This framework includes both the underlying Layer-1 blockchain, with Cartesi Rollups smart contracts deployed, and the Layer-2 off-chain nodes.


As illustrated by the architecture figure above, in a Cartesi DApp the front-end and back-end parts of the application communicate with each other through the Cartesi Rollups framework.

When designing the API for this communication with the framework, we wanted to ensure developers could create their applications without having to worry too much about the idiosyncrasies of blockchain technology or our rollups solution. In particular, we wanted to allow the back-end code to abstract away whether it was running inside a specific virtual machine or not.

With this in mind, we decided to offer an HTTP API as a convenience layer for this communication, leveraging a well-known and ubiquitous standard instead of having applications deal with any kernel-level or VM-specific devices, or having to understand how our rollups solution encodes and decodes data.

Back-end API

From the back-end component’s point of view, the API can be split into two parts, as illustrated by the figure below.

First, a couple of endpoints are expected to be implemented by the DApp’s back-end to receive requests from the Rollups framework, as shown in the list below:

  • AdvanceState — Provides input to the back-end, to be processed asynchronously to advance the application’s state.
  • InspectState — Submits a query about the current application state, to be answered synchronously.

As the back-end processes the inputs received via the AdvanceState endpoint, it can access a second set of HTTP endpoints provided by the Rollups framework itself, in order to inform it of the computed results and consequences, as shown below:

  • AddVoucher — Called to specify a collateral effect in the form of a transaction that can be carried out on layer-1 (e.g., a transfer of ERC-20 tokens).
  • AddNotice — Informs about a new relevant state of the application (e.g., updated player rankings).
  • AddReport — Provides diagnostics or logs associated with a received input.
  • Finish — Communicates that the asynchronous processing of an AdvanceState request has been completed.

Note that you can find the complete OpenAPI specification for these endpoints in Cartesi’s public Github repository.

Front-end API

The front-end part of the DApp needs to access the Cartesi Rollups framework to submit user inputs and retrieve the corresponding vouchers and notices produced by the back-end. The following figure and table detail how this communication is done:

  • AddInput — Submits input data to the Rollups smart contracts on layer-1 as a regular JSON-RPC blockchain transaction. When that transaction is mined and executed, an event is emitted containing the submitted input’s identifier, which the front-end can later use to query associated outputs. In the future, there will also be support for sending inputs via an aggregator service.
  • QueryOutputs — Submits a query to a layer-2 node to retrieve vouchers, notices and reports, as specified by the Cartesi Rollups GraphQL schema.
  • InspectState — Submits a query to a layer-2 node to retrieve arbitrary DApp-specific application state. Note that this endpoint is not yet available at the time of writing.
  • ExecuteVoucher — Submits a JSON-RPC blockchain transaction to request a given voucher to be executed by the Rollups smart contracts on layer-1. This is how a DApp’s results, such as a transfer of assets, can take effect on the underlying blockchain. It should be noted that the contracts will only actually execute the voucher if it has been finalized, meaning that its contents can no longer be disputed. Finalized vouchers are explained in more detail in the Rollups On-Chain article.

Development in practice: the DApp Life Cycle

Now that we have seen how the front-end and back-end communicate with the Cartesi Rollups framework, let’s step back a bit to discuss how a DApp can be implemented in practice.

As mentioned before, we at Cartesi wanted to provide a development experience that would feel as familiar as possible for mainstream developers. With that in mind, we defined a series of stages covering the entire life cycle of a Cartesi DApp’s development. The intention here is to allow developers to use their usual mainstream development environment for the larger part of their projects, and to make that possible Cartesi will provide the necessary tools and infrastructure.

Stage 1: Design

This would involve the overall conceptual design of the application, specifying the main scope of the front-end and back-end logic, as well as general technology requirements (e.g., whether it will use an SQL database, execute a trained AI model, etc.)

Stage 2: Proof of Concept

Checkpoint stage to implement a proof of concept ensuring the feasibility of executing the intended back-end logic and tech stacks inside a Cartesi Machine. This stage might involve cross-compiling a library to Cartesi’s RISC-V Linux OS and verifying that the performance of running the intended software in the Cartesi Machine is satisfactory.

Stage 3: Implementation

This is the stage where the front-end and back-end logic are actually implemented, representing the bulk of the work in the DApp’s development life cycle.

At this stage, the DApp developer will make use of a Cartesi Rollups Host Environment to implement the front-end and back-end modules of the DApp using common mainstream technologies and tools. This environment provides the very same HTTP API as the regular one, mimicking the behavior of the actual Layer-1 and Layer-2 components. This way, the front-end and back-end modules can be tested as any regular application, such as having a web application front-end in the browser and a native back-end running on localhost. This allows the developer to run and debug them using familiar tools, such as an IDE.

We expect this feature to be a game-changer in terms of DApp development productivity. The Cartesi Rollups Host Environment can be executed by simply running a Docker Compose file, and detailed instructions about using it can be found in our Rollups Github repository.

Stage 4: Packaging

In this stage, the back-end part is packaged to run inside a Cartesi Machine, to be executed by a real Layer-2 node (i.e., not a development version in which the back-end runs directly on the host). The feasibility of running it inside a Cartesi Machine should have already been accessed during Stage 2, and now we will just see if the full DApp implementation runs satisfactorily as well.

Since the back-end will keep using the very same HTTP API as before, it remains unchanged. The only difference is that this time around it will interact with a service running inside the Cartesi Machine itself, instead of directly communicating with the Rollups Host infrastructure as in Stage 3.

Stage 5: Deployment

With the full application working fine inside a Cartesi Machine, the final step is to deploy it. This can be tested on a local environment in which a Hardhat instance acts as a local blockchain, but the ultimate goal is of course to deploy it to a remote blockchain network.

This stage involves publishing the DApp back-end so that Cartesi Layer-2 nodes can execute its logic inside a Cartesi Machine. To that end, the DApp developer will use a deployment script that will register the DApp in the target blockchain and upload the back-end machine configuration so that it can be used by the target Cartesi nodes. Note that this deployment script is not yet available for use at the time of writing.

What now?

We are very excited to be making this solution available to everyone. For the first time, developers can use their favorite mainstream tools to create decentralized applications using virtually any software components, while leveraging a real-world operating system and still keeping the security guarantees of a Layer-1 blockchain like Ethereum.

It is already possible to start developing Cartesi DApps now. Once again, we encourage you to check out our main Rollups Github repository and explore. We are soon going to publish follow-ups with detailed code examples of Cartesi DApps, so stay tuned!

Aside from that, Cartesi is presently partnering with several mainstream software companies to develop a number of showcase applications, spanning areas as diverse as gaming, IoT, finance, and AI. In the following months, we will continuously collect feedback from partners and the community to iterate over the solution, increasing its maturity and convenience of use, and bringing it progressively closer to Mainnet availability.

In this way, Cartesi hopes to lower the barrier of entry for the ocean of mainstream developers eager to enter the blockchain space. We firmly believe that the widespread adoption of blockchain technologies can in turn lead to an unprecedented explosion of innovation and growth in the ecosystem, thus helping it finally realize its full potential.

About Cartesi: Home to what’s next

Cartesi is the first OS on the blockchain, and their Layer-2 solution integrates Linux and standard programming environments to blockchain. This allows developers to code scalable smart contracts with rich software tools, libraries, and services they are used to.

Cartesi bridges the gap between mainstream software and blockchain, welcoming millions of new startups and their developers to blockchain by bringing Linux to blockchain applications. Cartesi combines a groundbreaking virtual machine, optimistic rollups, and side-chains to revolutionize the way developers create blockchain applications.

Follow Cartesi across official channels:

Telegram Announcements | Telegram | Discord (Development Community)| Reddit | Twitter | Facebook| Instagram | Youtube | Github | Website

[Images in courtesy of Dave Xu and Miguel A. Padrian]



Cartesi Foundation

Cartesi is an application-specific rollup protocol with a Linux runtime.