Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions .github/workflows/deploy-staging.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
name: Deploy to GitHub Pages

on:
push:
branches:
- Staging
workflow_dispatch:

permissions:
pages: write
id-token: write
contents: write

jobs:
build:
name: Build and upload artifact
runs-on: ubuntu-latest
defaults:
run:
shell: bash
working-directory: ./docs
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 20

- name: Clone submodules
run: |
git submodule init
git submodule update --init --recursive
- name: Install dependencies
run: yarn
- name: Build website
run: yarn build
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: build

deploy:
name: Deploy to GitHub Pages
needs: build
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Overview

In order to query the state of a Cartesi Rollups instance, front-end clients can make use of a [GraphQL API](https://graphql.org/learn/) that is exposed by the [Cartesi Nodes](../../components.md#cartesi-nodes).
In order to query the state of a Cartesi Rollups instance, front-end clients can make use of a [GraphQL API](https://graphql.org/learn/) that is exposed by the [Cartesi Nodes](/cartesi-rollups/1.0/main-concepts/#cartesi-nodes).

Essentially, this API allows any client to retrieve outputs produced by a dApp's back-end, and to link those outputs to the corresponding inputs that triggered them. Outputs can generally come in the form of [vouchers](./objects/voucher.mdx), [notices](./objects/notice.mdx) and [reports](./objects/report.mdx), and allow clients to both receive dApp updates and enforce consequences on the base layer, such as asset transfers.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ In this example, the command will fetch and display the balance as shown below:

##### getNumberOfInputs

The following example is a cast command that shows how to get the number of inputs using the function [getNumberOfInputs](./sol-input.md#addInput):
The following example is a cast command that shows how to get the number of inputs using the function [getNumberOfInputs](/cartesi-rollups/1.0/api/json-rpc/sol-input/#getnumberofinputs):

```shell
cast call <INPUTBOX_ADDRESS> getNumberOfInputs(address) <DAPP_ADDRESS>
Expand All @@ -111,7 +111,7 @@ The result of this JSON-RPC call is the number of inputs for the dApp, returned

##### addInput

The following example is a cast command that shows how to send an input using the function [addInput](./sol-input.md#addInput) of the [`InputBox`](./sol-input.md) smart contract:
The following example is a cast command that shows how to send an input using the function [addInput](/cartesi-rollups/1.0/api/json-rpc/sol-input/#addinput) of the [`InputBox`](/cartesi-rollups/1.0/api/json-rpc/sol-input) smart contract:

```shell
cast send <INPUTBOX_ADDRESS> addInput(_dapp,_input) <DAPP_ADDRESS> <INPUT>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@ id: sol-output
title: CartesiDApp
---

The **CartesiDApp** contract acts as the base layer incarnation of a dApp running on the execution layer. The dApp is hereby able to interact with other smart contracts through the execution of [vouchers](../../components.md#vouchers)
and the validation of [notices](../../components.md#notices). These outputs are generated by the [dApp back-end](../../dapp-architecture.md#back-end) on the execution layer and can be proven in the base layer thanks to claims submitted by a consensus contract.
The **CartesiDApp** contract acts as the base layer incarnation of a dApp running on the execution layer. The dApp is hereby able to interact with other smart contracts through the execution of [vouchers](/cartesi-rollups/1.0/main-concepts/#vouchers)
and the validation of [notices](/cartesi-rollups/1.0/main-concepts/#notices). These outputs are generated by the [dApp back-end](/cartesi-rollups/1.0/dapp-architecture/#back-end) on the execution layer and can be proven in the base layer thanks to claims submitted by a consensus contract.

A **voucher** is a one-time message call to another contract. It can encode asset transfers, approvals,
or any other message call that doesn't require Ether to be sent along. A voucher will only be consumed
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ while True:
```

In production mode, if the dApp exits the Rollups initialization script will register a Rollup Exception.
See [/exception](#api-Default-registerException).
See [/exception](/cartesi-rollups/1.0/api/rollup/register-exception/).

In host mode, the Cartesi Rollups infrastructure is not able to detect that the dApp exited.
It is up to the dApp developer to re-launch the dApp.
Expand Down
8 changes: 4 additions & 4 deletions cartesi-rollups_versioned_docs/version-1.0/assets-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@ Assets exist on the base layer, which is where they have actual meaning and valu

Asset handling in Cartesi dApps involves the following procedures:

1. Locking assets on the base layer by calling deposit methods on special contracts called [Portals](./components.md#portals), which will effectively transfer asset ownership to the target dApp contract. There are specific portals for each kind of asset (Ether, ERC-20, ERC-721, ERC-1155).
1. Locking assets on the base layer by calling deposit methods on special contracts called [Portals](/cartesi-rollups/1.0/api/json-rpc/portals/), which will effectively transfer asset ownership to the target dApp contract. There are specific portals for each kind of asset (Ether, ERC-20, ERC-721, ERC-1155).
2. The Cartesi Rollups framework notifies the dApp back-end of the deposit by sending it a special input.
3. The dApp's back-end code needs to recognize and handle the special input, in order to process the deposit according to its own logic (e.g., by storing each user's balance in a hash table or database).
4. When appropriate (e.g., when a game ends and the winner wishes to withdraw their funds), the back-end generates a [voucher](./components.md#vouchers) that encodes a transfer of assets on the base layer, from the dApp to the target user. The actual withdrawal will take effect on the base layer when the voucher is executed. This is a secure process because it can only be done when the voucher has an associated validity proof ensuring that the validator nodes have reached consensus about its contents.
4. When appropriate (e.g., when a game ends and the winner wishes to withdraw their funds), the back-end generates a [voucher](/cartesi-rollups/1.0/main-concepts/#vouchers) that encodes a transfer of assets on the base layer, from the dApp to the target user. The actual withdrawal will take effect on the base layer when the voucher is executed. This is a secure process because it can only be done when the voucher has an associated validity proof ensuring that the validator nodes have reached consensus about its contents.

## Ethereum ABI encoding for asset operations

Expand Down Expand Up @@ -94,7 +94,7 @@ For the above example, we would have the following decoded values:

#### Encoding withdrawals

In the case of a withdrawal, the back-end code needs to create a [voucher](./components.md#vouchers) that encodes a transfer of assets from the dApp to the target recipient address. For ERC-20, this transfer can be performed by encoding a call to the [transfer(address,uint256)](https://eips.ethereum.org/EIPS/eip-20#transfer) method of the appropriate ERC-20 contract on the base layer.
In the case of a withdrawal, the back-end code needs to create a [voucher](/cartesi-rollups/1.0/main-concepts/#vouchers) that encodes a transfer of assets from the dApp to the target recipient address. For ERC-20, this transfer can be performed by encoding a call to the [transfer(address,uint256)](https://eips.ethereum.org/EIPS/eip-20#transfer) method of the appropriate ERC-20 contract on the base layer.

```python
TRANSFER_FUNCTION_SELECTOR = b'\xa9\x05\x9c\xbb'
Expand Down Expand Up @@ -170,7 +170,7 @@ For the above example, we would have the following decoded values:

#### Encoding withdrawals

Withdrawals for ERC-721 are again very similar to what is done for ERC-20. Once more, a [voucher](./components.md#vouchers) must be emitted that encodes a transfer of the intended asset from the dApp to a target recipient address.
Withdrawals for ERC-721 are again very similar to what is done for ERC-20. Once more, a [voucher](/cartesi-rollups/1.0/main-concepts/#vouchers) must be emitted that encodes a transfer of the intended asset from the dApp to a target recipient address.
In the case of ERC-721 tokens, the voucher should encode a call to the [safeTransferFrom(address,address,uint256)](https://eips.ethereum.org/EIPS/eip-721#specification) method on the base layer token contract.

```python
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ tags: [deploy, quickstart, dapps, developer]

Cartesi Rollups dApps are intended to be deployed to public blockchains, so that they can be accessed by users. This can be done by taking advantage of a cloud-based infrastructure provided by Cartesi.

As happens with any blockchain application, the act of "deploying a dApp" involves publishing its smart contract so that it is publicly available and usable by clients or [front-end applications](../dapp-architecture.md#front-end). In the context of a Cartesi dApp, the smart contract is represented by an arbitrary [back-end program](../dapp-architecture.md#back-end) that runs on Linux inside a [Cartesi Node](../components.md#cartesi-nodes). This means that deploying Cartesi dApps basically corresponds to first deploying a smart contract that represents your dApp on-chain and then instantiating Cartesi Nodes that run the intended back-end logic of the application.
As happens with any blockchain application, the act of "deploying a dApp" involves publishing its smart contract so that it is publicly available and usable by clients or [front-end applications](/cartesi-rollups/1.0/dapp-architecture/#front-end). In the context of a Cartesi dApp, the smart contract is represented by an arbitrary [back-end program](/cartesi-rollups/1.0/dapp-architecture/#back-end) that runs on Linux inside a [Cartesi Node](/cartesi-rollups/1.0/main-concepts/#cartesi-nodes). This means that deploying Cartesi dApps basically corresponds to first deploying a smart contract that represents your dApp on-chain and then instantiating Cartesi Nodes that run the intended back-end logic of the application.

In order to facilitate the instantiation of such nodes, Cartesi provides an infrastructure for easily getting them running in the cloud. Developers are thus invited to take advantage of this convenience service in order to jump-start bringing their applications to public blockchains.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,14 @@ This article explains common practices for developing dApps using the Cartesi Ro
Please, check the [dApp architecture](../dapp-architecture.md) article to explore more essential topics such as the [back-end](../dapp-architecture.md#back-end) and [front-end](../dapp-architecture.md#front-end) components, and the [communication](../dapp-architecture.md#communication) between them.
:::

Cartesi dApps communicate between the front-end and back-end using the Rollups framework via a [set of HTTP APIs](..//http-api.md). The Cartesi dApp back-end contains the application's business logic and executes within the Cartesi Rollups framework. The back-end produces outputs in the form of [vouchers](../main-concepts.md#vouchers), [notices](../main-concepts.md#notices), or [reports](../main-concepts.md#reports), which provide vital information about the application's status. The Cartesi dApp front-end is responsible for presenting information and collecting user inputs. The front-end communicates with the back-end via APIs, and Cartesi provides a range of APIs that you can use to interact with the Rollups framework.
Cartesi dApps communicate between the front-end and back-end using the Rollups framework via a [set of HTTP APIs](/cartesi-rollups/1.0/http-api/). The Cartesi dApp back-end contains the application's business logic and executes within the Cartesi Rollups framework. The back-end produces outputs in the form of [vouchers](/cartesi-rollups/1.0/main-concepts/#vouchers), [notices](/cartesi-rollups/1.0/main-concepts/#notices), or [reports](/cartesi-rollups/1.0/main-concepts/#reports), which provide vital information about the application's status. The Cartesi dApp front-end is responsible for presenting information and collecting user inputs. The front-end communicates with the back-end via APIs, and Cartesi provides a range of APIs that you can use to interact with the Rollups framework.

When it comes to dApp architecture and APIs, several points are important to highlight:

- The [Cartesi Machine](/machine/intro) serves as the back-end for the dApp, and it is managed by a [Cartesi Node](../components.md#cartesi-nodes), providing a secure and efficient environment for running the dApp
- The [Cartesi Machine](/get-started/cartesi-machine/) serves as the back-end for the dApp, and it is managed by a [Cartesi Node](/cartesi-rollups/1.0/main-concepts#cartesi-nodes), providing a secure and efficient environment for running the dApp
- All inputs are sent to the L1 smart contracts
- You can query the Rollups state using a [GraphQL API](../api/graphql/basics.md). This state includes the received inputs and the associated outputs produced in the form of notices, vouchers and reports
- You can retrieve arbitrary application state via the [Inspect HTTP API](../api/inspect/inspect.api.mdx). It allows you to implement a REST-like API on the back-end of your dApp to return arbitrary information about it, much like what web2 applications are used to
- You can query the Rollups state using a [GraphQL API](/cartesi-rollups/1.0/api/graphql/basics/). This state includes the received inputs and the associated outputs produced in the form of notices, vouchers and reports
- You can retrieve arbitrary application state via the [Inspect HTTP API](/cartesi-rollups/1.0/api/inspect/inspect/). It allows you to implement a REST-like API on the back-end of your dApp to return arbitrary information about it, much like what web2 applications are used to

## General recommendations

Expand All @@ -43,8 +43,8 @@ The Cartesi Machine is a deterministic RISC-V emulator that runs software in an

The dApp front-end clients have two ways of retrieving information:

- [Inspect HTTP API](../api/inspect/inspect.api.mdx)
- [GraphQL API](../api/graphql/basics.md)
- [Inspect HTTP API](/cartesi-rollups/1.0/api/inspect/inspect/)
- [GraphQL API](/cartesi-rollups/1.0/api/graphql/basics/)

The **Inspect API** provides enhanced flexibility and aligns better with the conventions of modern web2 applications. Enabling the implementation of a REST-like API on the back-end allows for the retrieval of a variety of information about the dApp.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ You can inspect the [full code of the Echo Python dApp](https://github.com/carte

## Overview

The Echo-Python dApp simply copies (or "echoes") each input received as a corresponding output [notice](../components.md#notices). The dApp's back-end is written in _Python_, and its front-end is a [simple console application](https://github.com/cartesi/rollups-examples/tree/main/frontend-console) written in _Typescript_ that can be executed from a terminal.
The Echo-Python dApp simply copies (or "echoes") each input received as a corresponding output [notice](/cartesi-rollups/1.0/main-concepts/#notices). The dApp's back-end is written in _Python_, and its front-end is a [simple console application](https://github.com/cartesi/rollups-examples/tree/main/frontend-console) written in _Typescript_ that can be executed from a terminal.

The **Quick Start** guide consists of 5 main steps:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Cartesi Rollups are shaped by the contributions and collaborative efforts of its
- [Disputes](#disputes)
- [Large data as input](#large-data-as-input)
- [Composability](#composability)
- [Convenience layer: Front-end](#convenience-layer-front-end)
- [Convenience layer: Front-end](#convenience-layers)
- [Design for upgradability](#design-for-upgradability)

## Transaction scalability
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Here, the black boxes represent the parts that the developer needs to implement

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 decentralized applications need this back-end logic to be verifiable and hence trustless. As such, it is executed inside the Cartesi Rollups framework.

The back-end stores and updates the application state as user input is received and produces corresponding outputs. These outputs can come in the form of [vouchers](./components.md#vouchers) (transactions that can be carried out on L1, such as a transfer of assets), [notices](./components.md#notices) (informational statements, such as the resulting score of a game), or [reports](./components.md#reports) (application logs and diagnostic information, such as error or warning messages).
The back-end stores and updates the application state as user input is received and produces corresponding outputs. These outputs can come in the form of [vouchers](/cartesi-rollups/1.0/main-concepts/#vouchers) (transactions that can be carried out on L1, such as a transfer of assets), [notices](/cartesi-rollups/1.0/main-concepts/#notices) (informational statements, such as the resulting score of a game), or [reports](/cartesi-rollups/1.0/main-concepts/#reports) (application logs and diagnostic information, such as error or warning messages).

In practical terms, a Cartesi dApp back-end can be seen as an advanced smart contract.

Expand All @@ -38,7 +38,7 @@ The sequence diagram below illustrates how all of this works:
![img](./sequence-diagram.png)

:::note
The Cartesi Rollups framework provides a set of APIs to specify how the dApp's front-end and back-end should communicate with it. These APIs are explained in detail in the [next section](./http-api.md).
The Cartesi Rollups framework provides a set of APIs to specify how the dApp's front-end and back-end should communicate with it. These APIs are explained in detail in the [next section](/cartesi-rollups/1.0/http-api/).
:::

## Other components
Expand Down
Loading