Skip to content

Commit 21dce6b

Browse files
NonnyjoeNonnyjoe
committed
impl(tutorials): Added counter and marketplace tutorials
1 parent 2de5b56 commit 21dce6b

18 files changed

Lines changed: 4326 additions & 0 deletions

File tree

‎cartesi-rollups_versioned_docs/version-1.5/tutorials/counter.md‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
---
2+
id: counter
3+
title: Build a counter Application
4+
resources:
5+
- url: https://github.com/Mugen-Builders/Counter-X-Marketplace-apps
6+
title: Source code for the counter Application
7+
---
8+
9+
This tutorial aims to guide you through creating and interacting with a basic Cartesi application, it'll take you through setting up your dev environment, creating a project then finally running and interacting with your application locally.
10+
11+
We would also be providing the Rust, JavaScript, Python and Go implementation of the application, so you could choose whichever language you're more conversant with.
12+
13+
## Set up your environment
14+
15+
To build an application using Cartesi, it's necessary that you have the following tools installed:
16+
17+
- Cartesi CLI: A simple tool for building applications on Cartesi. [Install Cartesi CLI for your OS of choice](../development/installation.md).
18+
19+
- Docker Desktop 4.x: The tool you need to run the Cartesi Machine and its dependencies. [Install Docker for your OS of choice](https://www.docker.com/products/docker-desktop/).
20+
21+
## Create an application template using the Cartesi CLI
22+
23+
Creating an application template for your application is a generally simple process, to do this, we utilize the Cartesi CLI by running the below command:
24+
25+
import Tabs from '@theme/Tabs';
26+
import TabItem from '@theme/TabItem';
27+
28+
<Tabs>
29+
<TabItem value="JavaScript" label="JavaScript" default>
30+
<pre><code>
31+
32+
```shell
33+
cartesi create counter --template javascript
34+
```
35+
36+
</code></pre>
37+
</TabItem>
38+
39+
<TabItem value="Python" label="Python" default>
40+
<pre><code>
41+
42+
```shell
43+
cartesi create counter --template python
44+
```
45+
46+
</code></pre>
47+
</TabItem>
48+
49+
<TabItem value="Rust" label="Rust" default>
50+
<pre><code>
51+
52+
```shell
53+
cartesi create counter --template rust
54+
```
55+
56+
</code></pre>
57+
</TabItem>
58+
</Tabs>
59+
60+
This command creates a directory called `counter` and depending on your selected language this directory would contain the necessary entry point file to start your application, for Python developers this would be `dapp.py` while for Rust users it would be `src/main.rs`, then finally for JavaScript users, the entry point file would be `src/index.js`.
61+
62+
This entry point file contains the default template for interacting with the Cartesi Rollups HTTP Server, it also makes available, two function namely `handle_advance()` and `handle_inspect()` which process "advance / write" and "inspect / read" requests to the application. In the next section we would be updating these functions with the implementation for your application.
63+
64+
## Implement the Application Logic
65+
66+
We’ll build the counter with a simple object‑oriented design. It defines a Counter object with three methods: a constructor, `increment()` to increase the count, and `get()` to return the current count.
67+
68+
We also update `handle_advance()` to increment the counter whenever an advance (write) request arrives, ignoring the request payload. And we update `handle_inspect()` to log the current counter value when an inspect (read) request arrives.
69+
70+
Together, these handlers let you increment the counter and check its value.
71+
72+
To try it locally, copy the snippet for your language and replace the contents of the entry point file in your `counter/` directory.
73+
74+
import CounterJS from './snippets/counter-js.md';
75+
import CounterPY from './snippets/counter-py.md';
76+
import CounterRS from './snippets/counter-rs.md';
77+
78+
<Tabs>
79+
<TabItem value="JavaScript" label="JavaScript" default>
80+
<pre><code>
81+
82+
<CounterJS />
83+
84+
</code></pre>
85+
</TabItem>
86+
87+
<TabItem value="Python" label="Python" default>
88+
<pre><code>
89+
90+
<CounterPY />
91+
92+
</code></pre>
93+
</TabItem>
94+
95+
<TabItem value="Rust" label="Rust" default>
96+
<pre><code>
97+
98+
<CounterRS />
99+
100+
</code></pre>
101+
</TabItem>
102+
</Tabs>
103+
104+
## Build and Run your Application
105+
106+
Once you have your application logic written out, the next step is to build the application, this is done by running the below commands using the Cartesi CLI:
107+
108+
```shell
109+
cartesi build
110+
```
111+
112+
- Expected Logs:
113+
114+
```shell
115+
user@user-MacBook-Pro counter % cartesi build
116+
(node:4460) ExperimentalWarning: Importing JSON modules is an experimental feature and might change at any time
117+
(Use `node --trace-warnings ...` to show where the warning was created)
118+
✔ Build drives
119+
✔ Build drive root
120+
121+
.
122+
/ \
123+
/ \
124+
\---/---\ /----\
125+
\ X \
126+
\----/ \---/---\
127+
\ / CARTESI
128+
\ / MACHINE
129+
'
130+
131+
[INFO rollup_http_server] starting http dispatcher service...
132+
[INFO rollup_http_server::http_service] starting http dispatcher http service!
133+
[INFO actix_server::builder] starting 1 workers
134+
[INFO actix_server::server] Actix runtime found; starting in Actix runtime
135+
[INFO actix_server::server] starting service: "actix-web-service-127.0.0.1:5004", workers: 1, listening on: 127.0.0.1:5004
136+
[INFO rollup_http_server::dapp_process] starting dapp: python3 dapp.py
137+
INFO:__main__:HTTP rollup_server url is http://127.0.0.1:5004
138+
INFO:__main__:Sending finish
139+
140+
Manual yield rx-accepted (1) (0x000020 data)
141+
Cycles: 8108719633
142+
8108719633: 107174e04a294787e22b6864c61fedd845833e5c8bc9a244480f2996ddabb3c7
143+
Storing machine: please wait
144+
```
145+
146+
The build command compiles your application then builds a Cartesi machine that contains your application.
147+
148+
This recently built machine alongside other necessary service, like an Anvil network, inspect service, etc. wound next be started by running the command:
149+
150+
```bash
151+
cartesi run
152+
```
153+
154+
If the `run` command is successful, you should see logs similar to this:
155+
156+
```bash
157+
user@user-MacBook-Pro counter % cartesi run
158+
(node:5404) ExperimentalWarning: Importing JSON modules is an experimental feature and might change at any time
159+
(Use `node --trace-warnings ...` to show where the warning was created)
160+
WARNING: default block is set to 'latest', production configuration will likely use 'finalized'
161+
[+] Pulling 4/0
162+
✔ database Skipped - Image is already present locally
163+
✔ rollups-node Skipped - Image is already present locally
164+
✔ anvil Skipped - Image is already present locally
165+
✔ proxy Skipped - Image is already present locally
166+
✔ counter starting at http://127.0.0.1:6751
167+
✔ anvil service ready at http://127.0.0.1:6751/anvil
168+
✔ rpc service ready at http://127.0.0.1:6751/rpc
169+
✔ inspect service ready at http://127.0.0.1:6751/inspect/counter
170+
✔ counter machine hash is 0x107174e04a294787e22b6864c61fedd845833e5c8bc9a244480f2996ddabb3c7
171+
✔ counter contract deployed at 0x94b32605a405d690934eb4ecc91856febfa747cc
172+
(l) View logs (b) Build and redeploy (q) Quit
173+
```
174+
175+
## Interacting with your Counter Application
176+
177+
Interacting with your Counter application could be achieved either through initiating transactions on the local anvil network which was activated when you ran the `cartesi run` command or more easily through the Cartesi CLI, for this tutorial, we'll be using the Cartesi CLI to send an input to our application which would increase our counter variable.
178+
179+
### 1. Query current count value
180+
181+
We start by querying the current count value, this is done by making an inspect request to the counter application running locally, to achieve this we run the below command in a new terminal:
182+
183+
```bash
184+
curl -X POST http://127.0.0.1:6751/inspect/counter \
185+
-H "Content-Type: application/json" \
186+
-d '{""}'
187+
```
188+
189+
:::note Inspect endpoint
190+
Please note that if your application is running on a different port or your application is not named `counter` as in the guide, then you'll need to replace the inspect endpoint `http://127.0.0.1:6751/inspect/counter` with the endpoint provided after running the `cartesi run` command.
191+
:::
192+
193+
On success, we receive a confirmation response from the HTTP server, something similar to `{"status":"Accepted","reports":null,"processed_input_count":0}`, then on the terminal running our application when we press the `l` key to access our application logs we should get a log confirming that our application received the inspect call and should also contain a log of the current count value.
194+
195+
```bash
196+
[INFO rollup_http_server::http_service] received new request of type INSPECT
197+
inspect_request.payload_length: 4
198+
[INFO actix_web::middleware::logger] 127.0.0.1 "POST /finish HTTP/1.1" 200 64 "-" "python-requests/2.31.0" 0.020096
199+
INFO:__main__:Received finish status 200
200+
INFO:__main__:Received inspect request data {'payload': '0x7b22227d'}
201+
INFO:__main__:Current counter value: 0
202+
INFO:__main__:Sending finish
203+
2025-11-09T17:47:44.661 INF Request executed service=inspect status=Accepted application=counter
204+
```
205+
206+
As seen in the third to last line of our received log, we can see the `count value` returned to be `0`
207+
208+
### 2. Increase count value
209+
210+
Now that we've confirmed our count value to be zero (0), we would be sending an advance request using the CLI to increase the value of our counter by running the below command:
211+
212+
```bash
213+
cartesi send random_text
214+
```
215+
216+
The above command sends an advance request with the payload "random_text" to our application, which ignores this payload then proceeds to increase out count value by `one (1)`, if this command is successful and our application process this request graciously, we should get a log similar to what's presented below on the terminal running our application:
217+
218+
```bash
219+
INFO:__main__:Received advance request data {'metadata': {'chain_id': 13370, 'app_contract': '0x9d40cfc42bb386b531c5d4eb3ade360f4105c4a3', 'msg_sender': '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266', 'block_number': 630, 'block_timestamp': 1762711409, 'prev_randao': '0x63a2bb3993d9f9c371624f995a10a6f493e33c2535e62b32fee565f812b4c4ab', 'input_index': 0}, 'payload': '0x72616e646f6d5f74657874'}
220+
INFO:__main__:Counter increment requested, new count value: 1
221+
INFO:__main__:Sending finish
222+
```
223+
224+
The above logs prove that out application received the advance request, increased our count value, logs the updated count value then finishes that request successfully.
225+
226+
As seen in the second to last line of the log, our count value has been increased from 0 to 1. To confirm this increase, we can run an inspect request once more to verify the current count value, and on running the same inspect command as last time, we obtain the updated logs below.
227+
228+
```shell
229+
[INFO rollup_http_server::http_service] received new request of type INSPECT
230+
inspect_request.payload_length: 4
231+
[INFO actix_web::middleware::logger] 127.0.0.1 "POST /finish HTTP/1.1" 200 64 "-" "python-requests/2.31.0" 0.002048
232+
INFO:__main__:Received finish status 200
233+
INFO:__main__:Received inspect request data {'payload': '0x7b22227d'}
234+
INFO:__main__:Current counter value: 1
235+
INFO:__main__:Sending finish
236+
2025-11-09T18:22:45.142 INF Request executed service=inspect status=Accepted application=counter
237+
```
238+
239+
From the latest application logs, it's now clear that the application's count value has been increased from 0 to one, and subsequent advance calls would further increase the count value.
240+
241+
## Conclusion
242+
243+
Congratulations, you've successfully bootstrapped, implemented, ran and interacted with your first Cartesi Application.
244+
245+
For a more detailed version of this code, you can check the `counter` folder for your selected language in [this repository](https://github.com/Mugen-Builders/Counter-X-Marketplace-apps)

0 commit comments

Comments
 (0)