# Cartesi Documentation > Cartesi rollups is a modular blockchain framework that enables developers to build decentralized applications using the Linux operating system and any programming language, with support for fraud proofs, application-specific rollups, and a full Cartesi Machine emulator. ## Instructions for AI Agents Use this file to discover and navigate Cartesi's documentation. Each link below points directly to the raw Markdown source for that page. A complete machine-readable copy of all docs concatenated is available at [https://docs.cartesi.io/llms-full.txt](https://docs.cartesi.io/llms-full.txt). An agent skill definition (operating guidance for AI assistants) is at [https://docs.cartesi.io/skill.md](https://docs.cartesi.io/skill.md). A Cartesi MCP server (HTTP transport, no auth) is available at `https://server.mcp.mugen.builders/mcp` — discovery file at [https://docs.cartesi.io/.well-known/mcp](https://docs.cartesi.io/.well-known/mcp). Additional agent skills are at [https://skills.mugen.builders/](https://skills.mugen.builders/). ### Version priority **Always default to Cartesi Rollups v2.0** (`/cartesi-rollups/2.0/`) when answering any question about building, deploying, or interacting with Cartesi applications. v2.0 is the current production version. v1.5 is deprecated and included at the bottom of this index for reference only — do not surface v1.5 content unless the user explicitly asks about v1.5, since its APIs, CLI commands, deployment model, and node architecture differ significantly from v2.0. ### Documentation map - **New to Cartesi** — conceptual introductions; start here for newcomers. - **Get Started** — quickstart guide, overview of core products (Rollups, Cartesi Machine, Fraud Proofs). - **Cartesi Machine** — the off-chain RISC-V Linux VM; covers host CLI, Lua scripting, blockchain integration, and the verification game. - **Cartesi Rollups v2.0** — the current application framework. Sub-sections: - *Getting Started* — architecture, concepts, installation. - *Development* — building, running, sending inputs, querying outputs, asset handling. - *API Reference* — HTTP backend API, inspect API, contract ABI, JSON-RPC node API. - *Deployment* — self-hosted node, public snapshot. - *Tutorials* — end-to-end worked examples (Counter, Calculator, Marketplace, wallets, React frontend). - **Fraud Proofs** — the PRT (Permissionless Refereed Tournament) dispute system; a distinct sub-system, not part of the Rollups application framework. - **Cartesi Compute (Legacy)** — a deprecated predecessor SDK (`/compute/`). Only reference this when a user explicitly asks about Cartesi Compute or the legacy SDK. - **Legacy Tutorials** — Cartesi Compute SDK tutorials (`/tutorials/`). These target the legacy SDK; do not apply them to Rollups v2.0 development. - **Earn CTSI** — staking, running a node, and managing staking pools; unrelated to application development. ### Key differences between v2.0 and v1.5 (do not mix) | Topic | v1.5 | v2.0 | |---|---|---| | Backend HTTP API | `/rollup/finish`, `/rollup/voucher` etc. on port 5004 | Same paths, but served by the new Rollups node | | Frontend / GraphQL API | GraphQL on the Rollups node | Replaced by JSON-RPC node API | | CLI | `cartesi` CLI v1.x | `cartesi` CLI v2.x — different commands and flags | | Deployment | Docker Compose + sunodo | `cartesi deploy` command, new node architecture | | Consensus | Authority contract v1 | Authority / Quorum contracts v2 with new claim flow | If a user's code or question references the old GraphQL API, `sunodo`, or v1.x CLI flags, note that they are on v1.5 and point them to the v2.0 migration guide at `/cartesi-rollups/2.0/resources/migration-guide.md`. ## Overview - [Home](https://docs.cartesi.io/): Cartesi documentation home ## New to Cartesi - [New to Cartesi](https://docs.cartesi.io/new-to-cartesi/): Section index for newcomers to Cartesi - [New to Cartesi](https://docs.cartesi.io/new-to-cartesi/overview.md): What Cartesi is and an introduction for newcomers - [Scalability](https://docs.cartesi.io/new-to-cartesi/scalability.md): How Cartesi addresses blockchain scalability - [Choose your Onboarding Path](https://docs.cartesi.io/new-to-cartesi/onboarding.md): Guided onboarding paths for different profiles ## Get Started - [Get Started](https://docs.cartesi.io/get-started.md): Entry point for all Cartesi products - [Quickstart](https://docs.cartesi.io/get-started/quickstart.md): Build and run your first Cartesi application - [Optimistic Rollups](https://docs.cartesi.io/get-started/optimistic-rollups.md): How optimistic rollups work - [Appchains](https://docs.cartesi.io/get-started/app-chains.md): Application-specific rollup chains - [Cartesi Machine](https://docs.cartesi.io/get-started/cartesi-machine.md): Introduction to the Cartesi Machine - [CLI commands](https://docs.cartesi.io/get-started/cli-commands.md): Cartesi CLI reference - [Fraud-proof system](https://docs.cartesi.io/get-started/fraud-proofs.md): Overview of Cartesi fraud proofs ## Cartesi Machine - [Introduction](https://docs.cartesi.io/cartesi-machine.md): Cartesi Machine overview - [Blockchain - Introduction](https://docs.cartesi.io/cartesi-machine/blockchain.md): Machine in the blockchain context - [Hash view of state](https://docs.cartesi.io/cartesi-machine/blockchain/hash.md): Merkle-tree based state hashing - [Verification game](https://docs.cartesi.io/cartesi-machine/blockchain/vg.md): On-chain dispute resolution - [Host - Overview](https://docs.cartesi.io/cartesi-machine/host.md): Running the machine from the host - [Command-line interface](https://docs.cartesi.io/cartesi-machine/host/cmdline.md): cartesi-machine CLI reference - [Lua interface](https://docs.cartesi.io/cartesi-machine/host/lua.md): Scripting the machine with Lua - [Target - Overview](https://docs.cartesi.io/cartesi-machine/target.md): Software running inside the machine - [System architecture](https://docs.cartesi.io/cartesi-machine/target/architecture.md): RISC-V ISA and hardware model - [Linux environment](https://docs.cartesi.io/cartesi-machine/target/linux.md): Linux OS inside the Cartesi Machine ## Cartesi Rollups v2.0 — Getting Started - [Cartesi Rollups v2.0](https://docs.cartesi.io/cartesi-rollups/2.0/): Section root for Cartesi Rollups v2.0 - [Overview](https://docs.cartesi.io/cartesi-rollups/overview.md): Cartesi Rollups v2.0 introduction - [Architecture](https://docs.cartesi.io/cartesi-rollups/2.0/getting-started/architecture.md): On-chain and off-chain components - [Concepts](https://docs.cartesi.io/cartesi-rollups/2.0/getting-started/concepts.md): Key concepts and terminology - [Installation](https://docs.cartesi.io/cartesi-rollups/2.0/getting-started/Installation.md): Install Cartesi CLI and dependencies - [Cartesi Machine](https://docs.cartesi.io/cartesi-rollups/2.0/core-concepts/cartesi-machine.md): Cartesi Machine in the rollups context ## Cartesi Rollups v2.0 — Development - [Installation](https://docs.cartesi.io/cartesi-rollups/2.0/development/installation.md): Install development tools - [Creating an Application](https://docs.cartesi.io/cartesi-rollups/2.0/development/creating-an-application.md): Bootstrap a new Cartesi dApp - [Building an application](https://docs.cartesi.io/cartesi-rollups/2.0/development/building-an-application.md): Build your application for the Cartesi Machine - [Running an application](https://docs.cartesi.io/cartesi-rollups/2.0/development/running-an-application.md): Run and test locally - [Sending inputs and assets](https://docs.cartesi.io/cartesi-rollups/2.0/development/send-inputs-and-assets.md): How to send inputs and assets to your dApp - [Query outputs](https://docs.cartesi.io/cartesi-rollups/2.0/development/query-outputs.md): Vouchers, notices and reports - [Asset handling](https://docs.cartesi.io/cartesi-rollups/2.0/development/asset-handling.md): Deposits and withdrawals ## Cartesi Rollups v2.0 — Development Snippets - [Request handling (C++)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/request_handling_cpp.md): C++ advance/inspect handler snippet - [Request handling (Go)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/request_handling_go.md): Go advance/inspect handler snippet - [Request handling (JavaScript)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/request_handling_js.md): JavaScript handler snippet - [Request handling (Python)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/request_handling_py.md): Python handler snippet - [Request handling (Rust)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/request_handling_rs.md): Rust handler snippet - [Implementing outputs (C++)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/implementing_outputs_cpp.md): C++ outputs snippet - [Implementing outputs (Go)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/implementing_outputs_go.md): Go outputs snippet - [Implementing outputs (JavaScript)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/implementing_outputs_js.md): JavaScript outputs snippet - [Implementing outputs (Python)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/implementing_outputs_py.md): Python outputs snippet - [Implementing outputs (Rust)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/implementing_outputs_rs.md): Rust outputs snippet - [Sending notice (C++)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/sending_notice_cpp.md): C++ notice snippet - [Sending notice (Go)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/sending_notice_go.md): Go notice snippet - [Sending report (C++)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/sending_report_cpp.md): C++ report snippet - [Sending report (Go)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/sending_report_go.md): Go report snippet - [Decode ERC-20 (C++)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/asset_decode_erc20_cpp.md): C++ ERC-20 decode snippet - [Decode ERC-20 (Go)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/asset_decode_erc20_go.md): Go ERC-20 decode snippet - [Decode ERC-20 (JavaScript)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/asset_decode_erc20_js.md): JavaScript ERC-20 decode snippet - [Decode ERC-20 (Python)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/asset_decode_erc20_py.md): Python ERC-20 decode snippet - [Decode ERC-20 (Rust)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/asset_decode_erc20_rs.md): Rust ERC-20 decode snippet - [Withdraw ERC-20 (C++)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/asset_withdraw_erc20_cpp.md): C++ ERC-20 withdraw snippet - [Withdraw ERC-20 (Go)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/asset_withdraw_erc20_go.md): Go ERC-20 withdraw snippet - [Withdraw ERC-20 (JavaScript)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/asset_withdraw_erc20_js.md): JavaScript ERC-20 withdraw snippet - [Withdraw ERC-20 (Python)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/asset_withdraw_erc20_py.md): Python ERC-20 withdraw snippet - [Withdraw ERC-20 (Rust)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/asset_withdraw_erc20_rs.md): Rust ERC-20 withdraw snippet - [Withdraw Ether (C++)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/asset_withdraw_ether_cpp.md): C++ Ether withdraw snippet - [Withdraw Ether (Go)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/asset_withdraw_ether_go.md): Go Ether withdraw snippet - [Withdraw Ether (JavaScript)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/asset_withdraw_ether_js.md): JavaScript Ether withdraw snippet - [Withdraw Ether (Python)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/asset_withdraw_ether_py.md): Python Ether withdraw snippet - [Withdraw Ether (Rust)](https://docs.cartesi.io/cartesi-rollups/2.0/development/snippets/asset_withdraw_ether_rs.md): Rust Ether withdraw snippet ## Cartesi Rollups v2.0 — API Reference - [API Reference Overview](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference.md): HTTP API overview - [Rollup HTTP API](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/rollup/cartesi-rollup-http-api.md): Backend HTTP API specification - [Add Voucher](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/rollup/add-voucher.md): Emit a voucher from the backend - [Add Notice](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/rollup/add-notice.md): Emit a notice from the backend - [Add Report](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/rollup/add-report.md): Emit a report from the backend - [Register Exception](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/rollup/register-exception.md): Register an exception - [Finish](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/rollup/finish.md): Complete input processing - [Inspect State (spec)](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/inspect/inspect-state-http-api-for-cartesi-rollups.md): Inspect HTTP API specification - [Inspect](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/inspect/inspect.md): Query application state ## Cartesi Rollups v2.0 — Backend API - [Introduction](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/backend/introduction.md): Communication between Cartesi Machine and node - [Notices](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/backend/notices.md): Informational statements - [Vouchers](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/backend/vouchers.md): Executable actions on base layer - [Reports](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/backend/reports.md): Application logs - [Exception](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/backend/exception.md): Register exceptions - [Finish](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/backend/finish.md): Complete request processing ## Cartesi Rollups v2.0 — Contracts API - [Contracts Overview](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/overview.md): All smart contracts in the framework - [InputBox](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/input-box.md): Entry point for user inputs - [Application](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/application.md): Per-dApp contract holding assets - [ApplicationFactory](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/application-factory.md): Deploy Application contracts - [EtherPortal](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/portals/EtherPortal.md): ETH deposits - [ERC20Portal](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/portals/ERC20Portal.md): ERC-20 token deposits - [ERC721Portal](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/portals/ERC721Portal.md): NFT deposits - [ERC1155SinglePortal](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/portals/ERC1155SinglePortal.md): ERC-1155 single token deposits - [ERC1155BatchPortal](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/portals/ERC1155BatchPortal.md): ERC-1155 batch deposits - [Consensus Overview](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/consensus/overview.md): Validates claims from validators - [AbstractConsensus](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/consensus/abstract-consensus.md): Base consensus contract - [IConsensus](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/consensus/iconsensus.md): Consensus interface - [IOutputsMerkleRootValidator](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/consensus/ioutputs-merkle-root-validator.md): Outputs Merkle root validator interface - [Authority](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/consensus/authority.md): Single-owner consensus - [AuthorityFactory](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/consensus/authority/authority-factory.md): Deploy Authority contracts - [IAuthority](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/consensus/authority/iauthority.md): Authority interface - [IAuthorityFactory](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/consensus/authority/iauthority-factory.md): Authority factory interface - [Quorum](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/consensus/quorum.md): Multi-validator consensus - [QuorumFactory](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/consensus/quorum/quorum-factory.md): Deploy Quorum contracts - [IQuorum](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/consensus/quorum/iquorum.md): Quorum interface - [IQuorumFactory](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/contracts/consensus/quorum/iquorum-factory.md): Quorum factory interface ## Cartesi Rollups v2.0 — JSON-RPC API - [JSON-RPC Overview](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/overview.md): Node management API overview - [Methods](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/methods.md): All JSON-RPC methods - [Types](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/types.md): JSON-RPC type definitions - [List Applications](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/methods/applications/applications-list.md): List all applications - [Get Application](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/methods/applications/applications-get.md): Get a specific application - [List Epochs](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/methods/epochs/epochs-list.md): List all epochs - [Get Epoch](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/methods/epochs/epochs-get.md): Get a specific epoch - [Get Last Accepted Epoch Index](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/methods/epochs/jsonrpc-epochs-last-accepted.md): Get last accepted epoch - [List Inputs](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/methods/inputs/inputs-list.md): List all inputs - [Get Input](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/methods/inputs/inputs-get.md): Get a specific input - [Get Processed Input Count](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/methods/inputs/jsonrpc-inputs-processed-count.md): Get processed input count - [List Outputs](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/methods/outputs/outputs-list.md): List all outputs - [Get Output](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/methods/outputs/outputs-get.md): Get a specific output - [List Reports](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/methods/reports/reports-list.md): List all reports - [Get Report](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/methods/reports/reports-get.md): Get a specific report - [Get Chain ID](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/methods/node/node-chain-id.md): Get node chain ID - [Get Node Version](https://docs.cartesi.io/cartesi-rollups/2.0/api-reference/jsonrpc/methods/node/node-version.md): Get node version ## Cartesi Rollups v2.0 — Deployment - [Introduction](https://docs.cartesi.io/cartesi-rollups/2.0/deployment/introduction.md): Overview of deployment options - [Self-hosted deployment](https://docs.cartesi.io/cartesi-rollups/2.0/deployment/self-hosted.md): Run your own node - [Public snapshot](https://docs.cartesi.io/cartesi-rollups/2.0/deployment/snapshot.md): Machine state management ## Cartesi Rollups v2.0 — Tutorials - [Counter](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/counter.md): Build a counter application - [Calculator](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/calculator.md): Build a calculator application - [Marketplace](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/marketplace.md): Build a marketplace application - [Ether Wallet](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/ether-wallet.md): Integrating Ether wallet functionality - [ERC-20 Wallet](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/erc-20-token-wallet.md): Integrating ERC20 token wallet functionality - [ERC-721 Wallet](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/erc-721-token-wallet.md): Integrating ERC721 token wallet functionality - [React Frontend](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/react-frontend-application.md): Build a React frontend for Cartesi apps - [CLI Account Abstraction](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/cli-account-abstraction-feauture.md): Sponsored transactions via CLI account abstraction - [Utilizing test tokens](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/utilizing-the-cli-test-tokens.md): Utilizing test tokens in dev environment ## Cartesi Rollups v2.0 — Tutorial Snippets - [Counter (C++)](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/snippets/counter-cpp.md): Counter application C++ snippet - [Counter (Go)](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/snippets/counter-go.md): Counter application Go snippet - [Counter (JavaScript)](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/snippets/counter-js.md): Counter application JavaScript snippet - [Counter (Python)](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/snippets/counter-py.md): Counter application Python snippet - [Counter (Rust)](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/snippets/counter-rs.md): Counter application Rust snippet - [Calculator (C++)](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/snippets/calculator-cpp.md): Calculator application C++ snippet - [Calculator (Go)](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/snippets/calculator-go.md): Calculator application Go snippet - [Calculator (JavaScript)](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/snippets/calculator-js.md): Calculator application JavaScript snippet - [Calculator (Python)](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/snippets/calculator-py.md): Calculator application Python snippet - [Calculator (Rust)](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/snippets/calculator-rs.md): Calculator application Rust snippet - [Marketplace (C++)](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/snippets/marketplace-cpp.md): Marketplace application C++ snippet - [Marketplace (Go)](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/snippets/marketplace-go.md): Marketplace application Go snippet - [Marketplace (JavaScript)](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/snippets/marketplace-js.md): Marketplace application JavaScript snippet - [Marketplace (Python)](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/snippets/marketplace-py.md): Marketplace application Python snippet - [Marketplace (Rust)](https://docs.cartesi.io/cartesi-rollups/2.0/tutorials/snippets/marketplace-rs.md): Marketplace application Rust snippet ## Cartesi Rollups v2.0 — Resources - [Community tools](https://docs.cartesi.io/cartesi-rollups/2.0/resources/community-tools.md): Third-party tools and integrations - [Integrations guide](https://docs.cartesi.io/cartesi-rollups/2.0/resources/integration-guides.md): Integration examples - [Migration Guide](https://docs.cartesi.io/cartesi-rollups/2.0/resources/migration-guide.md): Migrate from v1.x to v2.0 - [Mainnet considerations](https://docs.cartesi.io/cartesi-rollups/2.0/resources/mainnet-considerations.md): Production deployment considerations ## Fraud Proofs - [Overview](https://docs.cartesi.io/fraud-proofs.md): Fraud proof system overview and PRT introduction - [Introduction](https://docs.cartesi.io/fraud-proofs/fraud-proof-basics/introduction.md): Beginner-friendly fraud proof introduction - [Bonds](https://docs.cartesi.io/fraud-proofs/fraud-proof-basics/bonds.md): Bond mechanism in the fraud-proof system - [Epoch Lifecycle](https://docs.cartesi.io/fraud-proofs/fraud-proof-basics/epochs.md): Epoch boundaries and lifecycle - [State Transition Function](https://docs.cartesi.io/fraud-proofs/fraud-proof-basics/state-transition-function.md): State transition function explained - [PRT Introduction](https://docs.cartesi.io/fraud-proofs/prt/prt-introduction.md): Permissionless Refereed Tournament overview - [PRT Algorithm](https://docs.cartesi.io/fraud-proofs/prt/prt-algorithm.md): PRT algorithm details - [PRT Architecture](https://docs.cartesi.io/fraud-proofs/prt/prt-architecture.md): PRT system architecture - [Honeypot Introduction](https://docs.cartesi.io/fraud-proofs/honeypot/introduction.md): Honeypot application overview - [Honeypot Application Logic](https://docs.cartesi.io/fraud-proofs/honeypot/application-logic.md): Honeypot implementation details - [Honeypot with PRT](https://docs.cartesi.io/fraud-proofs/honeypot/prt-integration.md): Honeypot PRT integration - [DaveConsensus API Reference](https://docs.cartesi.io/fraud-proofs/references/daveconsensus.md): DaveConsensus contract reference - [Deployments](https://docs.cartesi.io/fraud-proofs/references/deployments.md): PRT and Honeypot deployed contracts - [PRT v1 Deployments](https://docs.cartesi.io/fraud-proofs/references/prt-v1-deployments.md): PRT v1 deployed contracts - [PRT Core Contracts](https://docs.cartesi.io/fraud-proofs/references/tournament.md): Tournament contract reference ## Cartesi Compute (Legacy) - [Cartesi Compute](https://docs.cartesi.io/cartesi-compute/): Cartesi Compute legacy section (redirects to compute/) - [Cartesi Compute SDK](https://docs.cartesi.io/compute.md): Cartesi Compute SDK overview - [Overview](https://docs.cartesi.io/compute/overview.md): Overview of Cartesi Compute - [How it works](https://docs.cartesi.io/compute/how.md): How Cartesi Compute works - [Architecture](https://docs.cartesi.io/compute/architecture.md): Cartesi Compute architecture - [Drives](https://docs.cartesi.io/compute/drives.md): Input and output drives - [Instantiate](https://docs.cartesi.io/compute/instantiate.md): Instantiate a computation - [Integer Drive](https://docs.cartesi.io/compute/integer_drive.md): Integer drive type - [Logger drives](https://docs.cartesi.io/compute/logger_drive.md): Logger drive type - [Machines off-chain](https://docs.cartesi.io/compute/machine-offchain.md): Off-chain machine management - [Machines on-chain](https://docs.cartesi.io/compute/machine-onchain.md): On-chain machine management - [The off-chain API](https://docs.cartesi.io/compute/off-chain-api.md): Off-chain API reference - [Provider drives](https://docs.cartesi.io/compute/provider.md): Provider drive type - [Platform services](https://docs.cartesi.io/compute/services.md): Platform services - [Supported networks](https://docs.cartesi.io/compute/supported-networks.md): Supported blockchain networks - [Execution timeline](https://docs.cartesi.io/compute/timeline.md): Computation execution timeline - [Topologies](https://docs.cartesi.io/compute/topologies.md): Network topologies - [Wallets](https://docs.cartesi.io/compute/wallet.md): Wallet integration - [Putting Things Together](https://docs.cartesi.io/compute/workflow.md): End-to-end workflow - [On-chain API](https://docs.cartesi.io/compute/api.md): On-chain API reference - [References](https://docs.cartesi.io/compute/references/): Reference documentation - [Tutorials](https://docs.cartesi.io/compute/tutorials/): Cartesi Compute tutorial index - [Hello World tutorial](https://docs.cartesi.io/compute/tutorials/helloworld/): Hello World Cartesi Compute tutorial - [Calculator tutorial](https://docs.cartesi.io/compute/tutorials/calculator/): Calculator Cartesi Compute tutorial - [Dogecoin Hash tutorial](https://docs.cartesi.io/compute/tutorials/dogecoin-hash/): Dogecoin Hash Cartesi Compute tutorial - [Generic Script tutorial](https://docs.cartesi.io/compute/tutorials/generic-script/): Generic Script Cartesi Compute tutorial - [GPG Verify tutorial](https://docs.cartesi.io/compute/tutorials/gpg-verify/): GPG Verify Cartesi Compute tutorial ## Legacy Tutorials (Cartesi Compute SDK) - [Introduction](https://docs.cartesi.io/tutorials/introduction.md): Introduction to the Cartesi Compute SDK tutorials - [General requirements](https://docs.cartesi.io/tutorials/requirements.md): Environment and tooling requirements - [Cartesi Compute SDK Environment](https://docs.cartesi.io/tutorials/compute-env.md): Setting up the Cartesi Compute SDK environment ### Hello World Tutorial - [Hello World machine](https://docs.cartesi.io/tutorials/helloworld/cartesi-machine.md): Build the Hello World Cartesi Machine - [Creating basic dApp](https://docs.cartesi.io/tutorials/helloworld/create-project.md): Create the Hello World dApp project - [Instantiating computation](https://docs.cartesi.io/tutorials/helloworld/instantiate.md): Instantiate the Hello World computation - [Deploying and running](https://docs.cartesi.io/tutorials/helloworld/deploy-run.md): Deploy and run the Hello World dApp - [Retrieving result](https://docs.cartesi.io/tutorials/helloworld/getresult.md): Retrieve the Hello World computation result ### Calculator Tutorial - [Calculator machine](https://docs.cartesi.io/tutorials/calculator/cartesi-machine.md): Build the Calculator Cartesi Machine - [Calculator project](https://docs.cartesi.io/tutorials/calculator/create-project.md): Create the Calculator dApp project - [Full Calculator dApp](https://docs.cartesi.io/tutorials/calculator/full-dapp.md): Complete Calculator dApp implementation ### Dogecoin Hash Tutorial - [Dogecoin Hash machine](https://docs.cartesi.io/tutorials/dogecoin-hash/cartesi-machine.md): Build the Dogecoin Hash Cartesi Machine - [Dogecoin Hash project](https://docs.cartesi.io/tutorials/dogecoin-hash/create-project.md): Create the Dogecoin Hash dApp project - [Computing scrypt using C](https://docs.cartesi.io/tutorials/dogecoin-hash/scrypt-c.md): Implement scrypt computation in C - [Full Dogecoin Hash dApp](https://docs.cartesi.io/tutorials/dogecoin-hash/full-dapp.md): Complete Dogecoin Hash dApp implementation ### Generic Script Tutorial - [Generic Script machine](https://docs.cartesi.io/tutorials/generic-script/cartesi-machine.md): Build the Generic Script Cartesi Machine - [Generic Script project](https://docs.cartesi.io/tutorials/generic-script/create-project.md): Create the Generic Script dApp project - [Custom root file-system](https://docs.cartesi.io/tutorials/generic-script/custom-rootfs.md): Build a custom root filesystem - [Full Generic Script dApp](https://docs.cartesi.io/tutorials/generic-script/full-dapp.md): Complete Generic Script dApp implementation ### GPG Verify Tutorial - [GPG Verify machine](https://docs.cartesi.io/tutorials/gpg-verify/cartesi-machine.md): Build the GPG Verify Cartesi Machine - [GPG Verify project](https://docs.cartesi.io/tutorials/gpg-verify/create-project.md): Create the GPG Verify dApp project - [Using ext2 files and GPG](https://docs.cartesi.io/tutorials/gpg-verify/ext2-gpg.md): Work with ext2 files and GPG in the machine - [Full GPG Verify dApp](https://docs.cartesi.io/tutorials/gpg-verify/full-dapp.md): Complete GPG Verify dApp implementation - [Processing larger files](https://docs.cartesi.io/tutorials/gpg-verify/larger-files.md): Handle larger file inputs ## Earn CTSI - [Earn CTSI](https://docs.cartesi.io/earn-ctsi/): Section index for staking and earning CTSI - [Staking overview](https://docs.cartesi.io/earn-ctsi/staking.md): Staking and earning CTSI overview - [Create a public pool](https://docs.cartesi.io/earn-ctsi/public-pool.md): Create and manage a staking pool - [Run a private node](https://docs.cartesi.io/earn-ctsi/run-node.md): Run a Cartesi node privately - [FAQs](https://docs.cartesi.io/earn-ctsi/staking-faq.md): Staking frequently asked questions ## Cartesi Rollups v1.5 (Deprecated) > **Deprecated.** Cartesi Rollups v1.5 is superseded by v2.0. APIs, CLI commands, deployment model, and node architecture differ significantly from v2.0. Always prefer v2.0 documentation unless the user explicitly asks about v1.5. ### v1.5 — Getting Started - [Overview](https://docs.cartesi.io/cartesi-rollups/1.5/): Cartesi Rollups v1.5 section root - [Quickstart](https://docs.cartesi.io/cartesi-rollups/1.5/quickstart.md): Build and run your first Cartesi Rollups v1.5 application - [Schema Documentation](https://docs.cartesi.io/cartesi-rollups/1.5/api/graphql/): Full GraphQL schema reference (auto-generated) ### v1.5 — Core Concepts - [Architecture](https://docs.cartesi.io/cartesi-rollups/1.5/core-concepts/architecture.md): On-chain and off-chain components - [Cartesi Machine](https://docs.cartesi.io/cartesi-rollups/1.5/core-concepts/cartesi-machine.md): Cartesi Machine in the v1.5 rollups context - [Mainnet considerations](https://docs.cartesi.io/cartesi-rollups/1.5/core-concepts/mainnet-considerations.md): Production deployment considerations - [Optimistic Rollups](https://docs.cartesi.io/cartesi-rollups/1.5/core-concepts/optimistic-rollups.md): How optimistic rollups work ### v1.5 — Development - [Installation](https://docs.cartesi.io/cartesi-rollups/1.5/development/installation.md): Install v1.5 development tools - [Creating an application](https://docs.cartesi.io/cartesi-rollups/1.5/development/creating-application.md): Bootstrap a new v1.5 Cartesi dApp - [Building the application](https://docs.cartesi.io/cartesi-rollups/1.5/development/building-the-application.md): Build your application for v1.5 - [Running the application](https://docs.cartesi.io/cartesi-rollups/1.5/development/running-the-application.md): Run and test locally with v1.5 - [Send requests](https://docs.cartesi.io/cartesi-rollups/1.5/development/send-requests.md): Send inputs to your v1.5 dApp - [Retrieve outputs](https://docs.cartesi.io/cartesi-rollups/1.5/development/retrieve-outputs.md): Query outputs from your v1.5 dApp - [Asset handling](https://docs.cartesi.io/cartesi-rollups/1.5/development/asset-handling.md): Deposits and withdrawals in v1.5 - [CLI commands](https://docs.cartesi.io/cartesi-rollups/1.5/development/cli-commands.md): Cartesi CLI v1.x reference - [Migration guide](https://docs.cartesi.io/cartesi-rollups/1.5/development/migration.md): Migrate from older versions to v1.5 ### v1.5 — Deployment - [Introduction](https://docs.cartesi.io/cartesi-rollups/1.5/deployment/introduction.md): Overview of v1.5 deployment options - [Self-hosted deployment](https://docs.cartesi.io/cartesi-rollups/1.5/deployment/self-hosted.md): Run your own v1.5 node ### v1.5 — External Resources - [Community tools](https://docs.cartesi.io/cartesi-rollups/1.5/external-resources/community-tools.md): Third-party tools and integrations for v1.5 - [Integration guides](https://docs.cartesi.io/cartesi-rollups/1.5/external-resources/integration-guides.md): Integration examples for v1.5 ### v1.5 — APIs Overview - [Rollups APIs](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/): API overview for Cartesi Rollups v1.5 ### v1.5 — Backend API - [Introduction](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/backend/introduction.md): Backend HTTP API overview - [Notices](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/backend/notices.md): Informational statements - [Vouchers](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/backend/vouchers.md): Executable actions on base layer - [Reports](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/backend/reports.md): Application logs ### v1.5 — Rollup HTTP API - [Cartesi Rollup HTTP API](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/rollup/cartesi-rollup-http-api/): HTTP API specification (auto-generated) - [Add Voucher](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/rollup/add-voucher/): Emit a voucher from the backend - [Add Notice](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/rollup/add-notice/): Emit a notice from the backend - [Add Report](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/rollup/add-report/): Emit a report from the backend - [Finish](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/rollup/finish/): Complete input processing - [Register Exception](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/rollup/register-exception/): Register an exception ### v1.5 — Inspect API - [Inspect State (spec)](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/inspect/inspect-state-http-api-for-cartesi-rollups/): Inspect HTTP API specification (auto-generated) - [Inspect](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/inspect/inspect/): Query application state ### v1.5 — GraphQL API - [Overview](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/overview.md): GraphQL API overview - [InputFilter](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/inputs/input-filter.md): Input filter type - [CompletionStatus](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/objects/completion-status.md): Completion status enum - [InputConnection](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/objects/input-connection.md): Input pagination connection - [InputEdge](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/objects/input-edge.md): Input connection edge - [Input](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/objects/input.md): Input object type - [NoticeConnection](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/objects/notice-connection.md): Notice pagination connection - [NoticeEdge](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/objects/notice-edge.md): Notice connection edge - [Notice](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/objects/notice.md): Notice object type - [OutputValidityProof](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/objects/output-validity-proof.md): Output validity proof type - [PageInfo](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/objects/page-info.md): Pagination info type - [Proof](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/objects/proof.md): Proof object type - [ReportConnection](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/objects/report-connection.md): Report pagination connection - [ReportEdge](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/objects/report-edge.md): Report connection edge - [Report](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/objects/report.md): Report object type - [VoucherConnection](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/objects/voucher-connection.md): Voucher pagination connection - [VoucherEdge](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/objects/voucher-edge.md): Voucher connection edge - [Voucher](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/objects/voucher.md): Voucher object type - [Inputs query](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/queries/inputs.md): Query inputs via GraphQL - [Notices query](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/queries/notices.md): Query notices via GraphQL - [Reports query](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/queries/reports.md): Query reports via GraphQL - [Vouchers query](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/queries/vouchers.md): Query vouchers via GraphQL - [BigInt](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/scalars/big-int.md): BigInt scalar type - [Boolean](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/scalars/boolean.md): Boolean scalar type - [DateTime](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/scalars/date-time.md): DateTime scalar type - [Int](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/scalars/int.md): Int scalar type - [String](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/scalars/string.md): String scalar type ### v1.5 — GraphQL Directives - [deprecated](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/directives/deprecated/): Deprecated directive - [include](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/directives/include/): Include directive - [skip](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/directives/skip/): Skip directive - [specifiedBy](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/graphql/directives/specified-by/): SpecifiedBy directive ### v1.5 — JSON-RPC API - [JSON-RPC Overview](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/json-rpc/overview.md): Contract API overview - [CartesiDApp](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/json-rpc/application.md): Per-dApp contract ABI - [CartesiDAppFactory](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/json-rpc/application-factory.md): Deploy CartesiDApp contracts - [InputBox](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/json-rpc/input-box.md): Entry point for user inputs - [EtherPortal](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/json-rpc/portals/EtherPortal.md): ETH deposits - [ERC20Portal](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/json-rpc/portals/ERC20Portal.md): ERC-20 token deposits - [ERC721Portal](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/json-rpc/portals/ERC721Portal.md): NFT deposits - [ERC1155SinglePortal](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/json-rpc/portals/ERC1155SinglePortal.md): ERC-1155 single token deposits - [ERC1155BatchPortal](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/json-rpc/portals/ERC1155BatchPortal.md): ERC-1155 batch deposits - [DAppAddressRelay](https://docs.cartesi.io/cartesi-rollups/1.5/rollups-apis/json-rpc/relays/): Relay contract ABI ### v1.5 — Tutorials - [Counter](https://docs.cartesi.io/cartesi-rollups/1.5/tutorials/counter.md): Build a counter application - [Calculator](https://docs.cartesi.io/cartesi-rollups/1.5/tutorials/calculator.md): Build a calculator application - [Ether Wallet](https://docs.cartesi.io/cartesi-rollups/1.5/tutorials/ether-wallet.md): Integrating Ether wallet functionality - [ERC-20 Wallet](https://docs.cartesi.io/cartesi-rollups/1.5/tutorials/erc-20-token-wallet.md): Integrating ERC20 token wallet functionality - [ERC-721 Wallet](https://docs.cartesi.io/cartesi-rollups/1.5/tutorials/erc-721-token-wallet.md): Integrating ERC721 token wallet functionality - [Marketplace](https://docs.cartesi.io/cartesi-rollups/1.5/tutorials/marketplace.md): Build a marketplace application - [React Frontend](https://docs.cartesi.io/cartesi-rollups/1.5/tutorials/react-frontend-application.md): Build a React frontend for Cartesi v1.5 apps - [CLI Account Abstraction](https://docs.cartesi.io/cartesi-rollups/1.5/tutorials/cli-account-abstraction-feauture.md): Sponsored transactions via CLI account abstraction ### v1.5 — Tutorial Snippets - [Counter (JavaScript)](https://docs.cartesi.io/cartesi-rollups/1.5/tutorials/snippets/counter-js.md): Counter application JavaScript snippet - [Counter (Python)](https://docs.cartesi.io/cartesi-rollups/1.5/tutorials/snippets/counter-py.md): Counter application Python snippet - [Counter (Rust)](https://docs.cartesi.io/cartesi-rollups/1.5/tutorials/snippets/counter-rs.md): Counter application Rust snippet - [Marketplace (JavaScript)](https://docs.cartesi.io/cartesi-rollups/1.5/tutorials/snippets/marketplace-js.md): Marketplace application JavaScript snippet - [Marketplace (Python)](https://docs.cartesi.io/cartesi-rollups/1.5/tutorials/snippets/marketplace-py.md): Marketplace application Python snippet - [Marketplace (Rust)](https://docs.cartesi.io/cartesi-rollups/1.5/tutorials/snippets/marketplace-rs.md): Marketplace application Rust snippet --- --- title: Introduction id: intro --- The Cartesi Machine is Cartesi's solution for verifiable computation. It was designed to bring mainstream scalability to dApps and mainstream productivity to dApp developers. ## Scalability dApps running exclusively on smart contracts face severe constraints on the amount of data they can manipulate and on the complexity of computations they can perform. These limitations manifest themselves as exorbitant transaction costs and, even if such costs could somehow be overcome, as extremely long computation times. In comparison, dApps running inside Cartesi Machines can process relatively unlimited amounts of data, and at a pace over 4 orders of magnitude faster. This is possible because Cartesi Machines run off-chain, free of the overhead imposed by the consensus mechanisms used by blockchains. In a typical scenario, one of the parties involved in a dApp will execute the Cartesi Machine off-chain and report its results to the blockchain. Different parties do not need to trust each other because the Cartesi platform includes an automatic dispute mechanism for Cartesi Machines. All interested parties repeat the computation off-chain and, if their results do not agree, they enter into a dispute, which the mechanism guarantees to be always won by an honest party against any dishonest party. To enable this dispute mechanism, Cartesi Machines are executed inside a special emulator that has three unique properties: - Cartesi Machines are _self contained_ — They run in isolation from any external influence on the computation; - Cartesi Machines are _reproducible_ — Two parties performing the same computation always obtain exactly the same results; - Cartesi Machines are _transparent_ — They expose their entire state for external inspection. From the point of view of the blockchain, the disputes require only a tiny fraction of the amount of computation performed by the Cartesi Machine. Dispute resolution thus becomes an ordinary task and dishonest parties are generally expected to be exposed, which discourages the posting of incorrect results and further increases the efficiency of the platform. Cartesi Machines allow dApps to take advantage of vastly increased computing capabilities off-chain, while enjoying the same security guarantees offered by code that runs natively as smart contracts. This is what Cartesi means by scalability. ## Productivity Scalability is not the only impediment to widespread blockchain adoption. Another serious limiting factor is the reduced developer productivity. Modern software development involves the combination of dozens of off-the-shelf software components. Creating these components took the concerted effort of an active worldwide community over the course of several decades. They have all been developed and tested using well-established toolchains (programming languages, compilers, linkers, profilers, debuggers, etc.), and rely on multiple services provided by modern operating systems (memory management, multi-tasking, file systems, networking, etc.). Smart contracts are developed using ad-hoc toolchains, and run directly on top of custom virtual machines, without the support of an underlying operating system. This arrangement deprives developers of the tools of their trade, severely reduces their expressive power, and consequently decimates their productivity. In contrast, Cartesi Machines are based on a proven platform: [RISC-V](https://riscv.org/). RISC-V was born of research in academia at UC Berkeley. It is now maintained by its own independent foundation. Unlike many of its academic counterparts, it is important to keep in mind that RISC-V is not a toy architecture. It is suitable for direct native hardware implementation, which is indeed currently commercialized by a large (and ever-increasing) number of [vendors](https://en.wikipedia.org/wiki/RISC-V#Implementations). This means that, in the future, Cartesi will not be limited to emulation or binary translation off-chain. The RISC-V platform is supported by a vibrant community of developers. Their efforts have produced an extensive software infrastructure, most notably ports of the Linux Operating System and the GNU toolchain. By moving key parts of their dApp logic to run inside Cartesi Machines, but on top of the Linux Operating System, developers are isolated not only from the limitations and idiosyncrasies of specific blockchains, but also from irrelevant details of the Cartesi Machine architecture itself. They regain access to all the tools they have come to rely on when writing applications. This is Cartesi's contribution to empowering dApp developers to express their creativity unimpeded, and to boost their productivity. ## What's in a machine All the components needed to create and run Cartesi Machines are distributed in the [Emulator SDK](http://www.github.com/cartesi/machine-emulator-sdk). Cartesi Machines are separated into a processor and a board. The processor performs the computations, executing the traditional fetch-execute loop while maintaining a variety of registers. The board defines the surrounding environment with an assortment of memories (ROM, RAM, flash drives, memory ranges) and a number of devices. Memories and devices are mapped to the 64-bit physical address space of the Cartesi Machine. The amount of RAM, as well as the number, length, and position of the flash drives and memory ranges in the address space can be chosen according to the needs of each particular application. The Cartesi Machine emulator is a program that carefully implements the Cartesi Machine architecture so that its executions are reproducible. It can be built in the `/emulator` directory of the Emulator SDK. The initialization of a Cartesi Machine loads a ROM image, a RAM image, and a root file-system (as a flash drive) from regular files in the host file-system. Execution starts from the ROM image, which contains a simple program that creates a description of the machine organization for the Linux kernel. The ROM image `rom.bin` can be built in the `rom/` directory in the Emulator SDK. The Linux kernel itself resides in the RAM image `linux.bin`, built in the `kernel/` directory in the Emulator SDK. After it is done with its own initialization, the Linux kernel cedes control to the `/sbin/init` program in the root file-system. The root file-system `rootfs.ext2` contains all the data files and programs that make up an embedded Linux distribution. It can be built in the `fs/` directory in the Emulator SDK. The components of the target application can reside in the root file-system itself, or in their own, separate file-systems. The emulator can be instructed to execute whatever command is necessary to start the target application. For a complete description of the Cartesi Machine architecture and the boot process, see the documentation for [the target perspective](./target/index.md). There are two distinct modes of operation. In the first mode, a Cartesi Machine is initialized and tasked to run a target application until the machine _halts_. Inputs for the target application can be provided as additional flash drives. Likewise, outputs can be sent to their own flash drives. (These drives can contain entire file-systems or can contain raw data.) Outputs are only available to the host after the machine halts. Once it halts, the machine cannot perform any additional computations. In the second mode of operation, the target application runs in a loop. In each iteration, it obtains a request carrying an input, performs any necessary computations to service the request, and produces a number of responses. After producing each response, the target application asks the machine to _yield_ control back to the host. The host extracts the response and _resumes_ the machine. When done with a given input, the target application once again asks the machine to yield control back to the host. The host then prepares the input for the next request, and _resumes_ the machine so the target application can service the next request in a new iteration of its loop. Inputs and responses are transferred in special memory ranges (_rollup_ memory ranges). Whatever state changes happen during the processing of a request will remain in effect when the next request is processed. Indeed, this is much like a server in which the target application can interact with the outside world. We say that a Cartesi Machine operating in this mode is a _Rolling Cartesi Machine_. ### Rolling Cartesi Machines and Cartesi Rollups The stringent demands of reproducibility prevent a Cartesi Machine from communicating _directly_ with the outside world. Indeed, if two parties were to run the same Cartesi Machine and then disagree on the data each instance independently obtained from a network connection, there would be no way to settle their dispute. Instead, Rolling Cartesi Machines communicate with the outside world under controlled conditions, through _Cartesi Rollups_. In a nutshell, Cartesi Rollups uses the blockchain to maintain a public record of requests made to advance the state of a Rolling Cartesi Machine. Both the order and the inputs carried by these requests are recorded and made available in an indisputable fashion. Since Cartesi Machines are deterministic, and since the inputs are agreed upon, the state of a Rolling Cartesi Machine can be advanced in a well-defined way, always producing the same set of responses, no matter who runs it. Advancing the state of a Rolling Cartesi Machine can produce four types of response: _vouchers_, _notices_, _reports_, and _exceptions_. Vouchers allow a Rolling Cartesi Machine to interact back with the blockchain. A voucher issued by the target application may, for example, grant a user the right to withdraw tokens locked into a custodial smart contract. Notices are used to register noteworthy changes to the state of the target application. A notice may be issued, for example, announcing the demise of a character in a game. Disputes over the fact that a voucher or notice has been generated while advancing the state of a Rolling Cartesi Machine can be settled by Cartesi Rollups. Reports, in contrast, are used to output any data that is irrelevant to the blockchain. A report may, for example, provide diagnostic information on the reasons why an input has been rejected. Finally, an exception is used to signal an irrecoverable error encountered by the target application. It is also possible to inspect the state of a local Rolling Cartesi Machine, without modifying it. State inspection produces only reports and exceptions. ## Documentation Cartesi Machines can be seen from 3 different perspectives: - _The host perspective_ — This is the environment right outside the Cartesi Machine emulator. It is most relevant to developers setting up Cartesi Machines, running them, or manipulating their contents. It includes the emulator's API in all its flavors: C, C++, Lua, gRPC, and the command-line interface; - _The target perspective _ — This is the environment inside the Cartesi Machine. It encompasses Cartesi's particular flavor of the RISC-V architecture, as well as the organization of the embedded Linux Operating System that runs on top of it. It is most relevant to programmers responsible for the dApp components that run off-chain but must be verifiable. The cross-compiling toolchain, and the tools used to build the Linux kernel and the embedded Linux root file-systems are also important from this perspective, even though they are used in the host; - _The blockchain perspective_ — This is the view smart contracts have of Cartesi Machines. It consists almost exclusively of the manipulation of cryptographic hashes of the state of Cartesi Machines and parts thereof. In particular, using only hash operations, the blockchain can verify assertions concerning the contents of the state, and can obtain the state hash that results from modifications to the state (including the execution of RISC-V instructions). As with every computer, the level of knowledge required to interact with Cartesi Machines depends on the nature of the application being created. Simple applications will require target developers to code a few scripts invoking pre-installed software components, require host developers to simply fill out a configuration file specifying the location of the components needed to build a Cartesi Machine, and require blockchain developers to simply instantiate one of the high-level contracts provided by Cartesi. At the other extreme are the developers working inside Cartesi, who regularly write, build, and deploy custom software components to run in the target, or even change the Linux kernel to support Cartesi-specific devices. Additionally, these developers programmatically control the creation and execution of Cartesi Machines in the host, and must also understand and use the hash-based state manipulation primitives the blockchain needs. Although Cartesi's goal is to shield platform users from as much complexity as possible, there is value in making information available to the greatest feasible extent. To that end, this documentation of Cartesi Machines aims to provide enough information to cover all 3 perspectives, at all depths of understanding. --- --- title: Introduction --- This section describes the Cartesi Machine from the perspective of the blockchain. Using the Cartesi platform, smart contracts gain a new ability. They can get their users to agree on the results of computations that cannot be performed natively as smart contracts: computations that either involve too much data, are too computationally demanding, or require a sophisticated software infrastructure that is simply not available for use on-chain. Users that have a stake in a given computation are represented off-chain by Cartesi Nodes under their control. Cartesi Nodes react to Cartesi-enabled smart contracts and instantiate Cartesi Machines to perform the required computations and post the result back to the blockchain. Since Cartesi Machines are self-contained and reproducible, the results of off-chain computations performed by honest users will agree. The smart contract can then make decisions of consequence that depend on these results. When the Cartesi Node representing an honest user identifies an incorrect result posted by a dishonest user, it disputes the result. The opposing Cartesi Nodes then engage in an automatic dispute resolution protocol presided by the blockchain, which results in the dishonest user being proven wrong. The smart contract that commanded the computation can then punish the dishonest user and reward the honest one. The Cartesi Machine emulator is one of a kind. It doesn't simply emulate the RISC-V ISA to the extent that it can boot a performant operating system based on Linux. It does so in a way that allows smart contracts to specify computations, replace their inputs, inspect their outputs, and direct the dispute resolution protocol. --- --- title: Hash view of state --- One of the key goals of moving computations off-chain is to allow them to manipulate vast amounts of data: so much data that it becomes economically prohibitive to explicitly store them in the blockchain. Nevertheless, for smart contracts to delegate computations off-chain, they must be able to specify the computations, their inputs, and then reason over their outputs. The key to solving these seemingly contradictory goals is the clever use of cryptographic hashes. Cartesi Machines are transparent in the sense that their entire state is exposed for external inspection. This includes the ROM, the RAM, all flash drives, general purpose registers, control and status registers, and even the internal state of all devices. In fact, the entire machine state is mapped into the 64-bit physical memory address space of the Cartesi Machine. (The exact mapping is given in the [system architecture](../target/architecture.md) section of the target perspective.) This means that, right before a machine is executed, a cryptographic hash of its entire state can be generated. A cryptographic hash of the state of a Cartesi Machine “completely” specifies the computation it is about to perform. This is because a given state always evolve in exactly the same way (because Cartesi Machines are self-contained and reproducible) and it is infeasible to find a different machine state that produces the same cryptographic state hash. By the same token, once the machine is done, the state hash “completely” specifies the result of the computation, wherever it may reside within the address space. :::info The scare quotes around “completely” are pedantic. It is true that there are a multitude of machine states that produce the same state hash. After all, the Keccak-256 state hashes fit in 256-bits, whereas machine states can take gigabytes. There are therefore many more possible machine states than possible state hashes. By the pigeonhole principle, there must be multiple machines with the same hash (i.e., hash collisions). However, given only the state hash, finding a Cartesi Machine with that state hash should be virtually impossible. Given a Cartesi Machine and its state hash, finding a *second* (distinct) Cartesi Machine with the same state hash should also be virtually impossible. Even finding two different Cartesi Machines that have the same state hash (any hash) should be virtually impossible. Cryptographic hash functions, such as Keccak-256, were designed *specifically* to have these properties. ::: The state hash of a Cartesi Machine is the root hash of a Merkle tree. Merkle trees are binary trees where a leaf node is labeled with the hash of a data block (In the case of Cartesi Machines, a block is simply one of the 261 64-bit words in the machine's physical memory address space.) and an inner node is labeled with the hash of the concatenated labels of its two child nodes. The root hash can be obtained from the `machine:get_root_hash()` method. In the command-line, the options `--initial-hash` and `--final-hash` of the `cartesi-machine` utility cause it to output the root hash of the Merkle tree as it is before the emulator starts running and after it is done running, respectively. The `cartesi.keccak()` function of the `cartesi` Lua module returns the hash of a 64-bit ``. The `cartesi.keccak(, )` overload returns the hash of the concatenation of `` and ``. In theory, the Merkle tree of the entire machine state could be built from these primitives and [external state access](../host/lua.md#external-state-access) to the machine instance. In practice, most of the state is unused and implicitly filled with zeros, and this allows the Merkle tree computation to skip large swaths of the state by using precomputed pristine hashes of all power-of-2 sizes. The computation is also smart enough to only update the parts of the tree that changed between invocations. Tree hashes are used instead of a linear hashes because they support a variety of operations that are unavailable from linear hashes. ## Merkle tree operations In the Merkle tree of a Cartesi Machine state, the labels of each the 2D nodes at a depth *D* can be seen as the root hashes for Merkle *subtrees* corresponding to adjacent intervals of *2L* bytes in the address space, where *L=64-D*. Each of these nodes can be identified by an address *A* and the log *L* of the length of the interval it spans, where *A* is aligned to a *2L* boundary. Consider a scenario in which a smart contract knows *only* the state hash *M* for a certain Cartesi Machine. Using Merkle trees makes the following key operations possible: 1. *Slicing* — A user with access to the Merkle tree of *M* can provide data the blockchain can use to prove that the word at a given address has a given value. More generally, the user can provide data the blockchain can use to prove that a node with a given address and length in the tree has a given label; 1. *Splicing* — A user with access to the Merkle tree of *M* can provide data the blockchain can use to prove that writing a given word at a given address results in a Cartesi Machine with a given state hash *M'*. More generally, the user can provide data the blockchain can use to prove that replacing a node of given length at a given address with another node of equal length and a given label results in a Cartesi Machine with a given state hash *M'*. To understand how the slicing proof works, notice that the path from the Merkle tree node at depth *D>0* (i.e., with log length *L=64-D*) and address *A* goes through *D* nodes: *nD*, *nD-1*, …, *n1* until it reaches the root *n0*. The labels associated to all these nodes can be produced as follows. If *nD* is a leaf node, the word value must be provided and the label is the hash of the word value. Otherwise, if it is a general node, its label must be provided. The label of *nD-1* can then be obtained by hashing together the label of node *nD* and the label of its sibling. The order between these two siblings is available from the *D*th most significant bit in address *A*. If it is clear, *nD*'s label comes first, otherwise, its sibling's label comes first. It should be obvious that, when labels for *all siblings* in the path from the target node to the root are provided, this process can be repeated until the label of *n0* itself is obtained. This must match the value *M* known to the smart contract. In fact, due to the properties of cryptographic hashes, it is infeasible for the label so obtained to match *M* *unless all the data provided is true*. The data needed for the proofs can be produced by the `machine:get_proof(
, )` method of a Cartesi Machine instance. The contents of the proof returned are described in the [host perspective](../host/lua.md#state-value-proofs). The same section gives the source-code for a simple function, `roll_hash_up(, )`, that implements the process described above. Here, `` is the structure returned by the `machine:get_proof()` method. The source-code is repeated below for convenience. ```lua title="cartesi/proof.lua (excerpt)" local cartesi = require"cartesi" local _M = {} function _M.roll_hash_up_tree(proof, target_hash) local hash = target_hash for log2_size = proof.log2_target_size, proof.log2_root_size-1 do local bit = (proof.target_address & (1 << log2_size)) ~= 0 local first, second local i = proof.log2_root_size-log2_size if bit then first, second = proof.sibling_hashes[i], hash else first, second = hash, proof.sibling_hashes[i] end hash = cartesi.keccak(first, second) end return hash end function _M.slice_assert(root_hash, proof) assert(root_hash == proof.root_hash, "proof root_hash mismatch") assert(_M.roll_hash_up_tree(proof, proof.target_hash) == root_hash, "node not in tree") end function _M.word_slice_assert(root_hash, proof, word) assert(proof.log2_target_size == 3, "not a word proof") assert(root_hash == proof.root_hash, "proof root_hash mismatch") assert(cartesi.keccak(word) == proof.target_hash, "proof target_hash mismatch") assert(_M.roll_hash_up_tree(proof, proof.target_hash) == root_hash, "node not in tree") end function _M.splice_assert(root_hash, proof, new_target_hash, new_root_hash) _M.slice_assert(root_hash, proof) assert(_M.roll_hash_up_tree(proof, new_target_hash) == new_root_hash, "new root hash mismatch") end function _M.word_splice_assert(root_hash, proof, old_word, new_word, new_root_hash) _M.word_slice_assert(root_hash, proof, old_word) assert(_M.roll_hash_up_tree(proof, cartesi.keccak(new_word)) == new_root_hash, "new root hash mismatch") end return _M ``` To verify a slicing operation, the code first checks the root hash *M* against the one found in the proof. Then, it uses `roll_hash_up_tree` to recompute the root hash from the path between the target node and root. Any mismatch triggers an assertion. Verifying a splicing operation is just as easy. First, the code verifies that the slicing operation is valid This ensures that the sibling hashes are correct. Then, it uses `roll_hash_up_tree` to compute the root hash from the path between the target node and root. Only this time it starts from the new target node hash. The resulting root hash is the hash of a tree with the old node replaced by the new. ### Template instantiation The most important use for the splicing operation is template instantiation. From the blockchain perspective, a [Cartesi Machine template](../host/cmdline.md#cartesi-machine-templates) is simply a state hash *M*. Instantiating the Cartesi Machine with a given input is simply the process of obtaining the state hash *M'* that results from replacing one or more of its input flash drives. Each replacement is the result of a splicing operation as described above. The splicing operation is particularly convenient if the flash drive length is a power of 2, and its start is aligned according to its length. This is why, by default, the `cartesi-machine` command-line utility positions flash drives a multiples of very large powers of 2. ### Result extraction The most important use for the slicing operation is retrieving computation results. In a typical scenario, a user posts the final state hash of an instantiated Cartesi Machine that has been run until it halted. When the other users agree with this final state hash, slicing operations can be used to convince the blockchain of the contents of the halted Cartesi Machine's state. This can be the value of a single word in a raw output flash drive, or it can be the hash for an entire flash drive. --- --- title: Verification game --- :::danger EDITOR NOTE This section is still under construction. Meanwhile, for details on how the verification game works, please refer to our [technical paper](https://cartesi.io/cartesi_whitepaper.pdf). ::: --- --- title: Overview --- Cartesi's reference off-chain implementation of Cartesi Machines is based on software emulation. The emulator is written in C/C++ with POSIX dependencies restricted to the terminal, process, and memory-mapping facilities. The `emulator/` directory in the [Emulator SDK](https://github.com/cartesi/machine-emulator-sdk) can be used to build and install the Cartesi Machine emulator. It is written as a C++ class, but can be accessed in a variety of different ways. When linked to a C++ application, the emulator can be controlled directly via the interface of the `cartesi::machine` class. C applications can control the emulator in a similar way, by means of a matching C API. The emulator can also be accessed from the Lua programming language, via a `cartesi` module that exposes a `cartesi.machine` interface to Lua programs. Additionally, Cartesi provides a [gRPC](https://grpc.io) server that can run a Cartesi Machine instance that is controlled remotely. Finally, there is a command-line utility (written in Lua) that can configure and run Cartesi Machines for rapid prototyping. The C, C++, Lua APIs as well as the command-line utility can seamlessly instantiate local emulators or connect to remote gRPC servers. The documentation starts from the command-line utility, `cartesi-machine`. This utility is used for most prototyping tasks. The documentation then covers the Lua interface of `cartesi.machine`. The C/C++/gRPC interfaces are very similar, and are covered only within their reference manuals. ## Machine playground The setup of a new development environment is often a time-consuming task. This is particularly true in case of cross-development environments (i.e., when the development happens in a host platform but software runs in a different target platform). With this in mind, the Cartesi team provides the `cartesi/playground` Docker image for use while reading this documentation. The Docker image enables immediate experimentation with Cartesi Machines. It comes with a pre-built emulator and Lua interpreter accessible within the command-line, as well as a pre-built ROM image, RAM image, and root file-system. It also comes with the cross-compiler for the RISC-V architecture on which the Cartesi Machine is based. To enter the playground, open a terminal, download the Docker image from Cartesi's repository, and run it adequately mapping the current user and group information, as well as making the host's current directory available inside the container: ```bash docker pull cartesi/playground:0.5.0 ``` ```bash docker run -it --rm -h playground \ -e USER=$(id -u -n) \ -e GROUP=$(id -g -n) \ -e UID=$(id -u) \ -e GID=$(id -g) \ -v `pwd`:/home/$(id -u -n) \ -w /home/$(id -u -n) \ cartesi/playground:0.5.0 /bin/bash ``` Once inside, you can execute the `cartesi-machine` utility as follows: ``` cartesi-machine --help ``` ``` %machine.host.overview.help ``` A final check can also be performed to verify if the contents inside the container are as expected: ``` sha256sum /opt/cartesi/share/images/linux.bin ``` ``` %machine.host.overview.sha256-linux ``` ``` sha256sum /opt/cartesi/share/images/rom.bin ``` ``` %machine.host.overview.sha256-rom ``` ``` sha256sum /opt/cartesi/share/images/rootfs.ext2 ``` ``` %machine.host.overview.sha256-rootfs ``` Note that, if the hashes of the files you are using do not match the ones above, then when you attempt to replicate the examples in the documentation, you will obtain different hashes. Moreover, the cycle counts and outputs may also differ. --- --- title: Command-line interface --- In the simplest usage scenario, the `cartesi-machine` command-line utility can be used to define a Cartesi Machine and run it until it halts. The command-line utility, however, is very versatile. It was designed to simplify the most common prototyping tasks. ## Initialization The following command instructs `cartesi-machine` to build a Cartesi Machine. The machine uses `rom.bin` as the ROM image, has 64MiB of RAM, uses `linux.bin` as the RAM image, and uses `rootfs.ext2` as the root file-system. (The `rom.bin`, `linux.bin`, and `rootfs.ext2` files are generated by the [Emulator SDK](https://github.com/cartesi/machine-emulator-sdk), and sample files are available in the playground.) Once initialization is complete, the machine executes the command `ls /bin` and exits. ```bash cartesi-machine \ --rom-image="/opt/cartesi/share/images/rom.bin" \ --ram-length=64Mi \ --ram-image="/opt/cartesi/share/images/linux.bin" \ --flash-drive="label:root,filename:/opt/cartesi/share/images/rootfs.ext2" \ -- "ls /bin" ``` The `--rom-image`, `--ram-image`, `--ram-length`, and `--flash-drive` command-line options have the values in the example as default, so these options can be omitted. To remove these default settings, use the command-line options `--no-ram-image` and `--no-root-flash-drive`, respectively. (The machine needs a ROM image, and, if needed, you can simply specify a different one.) The simplified command-line is ```bash cartesi-machine -- "ls /bin" ``` The output is ``` %machine.host.cmdline.ls ``` It shows the Cartesi Machine splash screen, followed by the listing of directory `/bin/`. The listing was produced by the command that follows the `--` separator in the command line. The Linux kernel passes this unmodified to `/sbin/init`, and the Cartesi-provided `/sbin/init` script executes the command before gracefully halting the machine. :::note In many of the documentation examples, the utilities invoked from the command-line executed by a Cartesi Machine are in the default search path for executables. (This is setup by the Cartesi-provided `/sbin/init` script itself.) When in doubt, or when using your own executables installed in custom locations, make sure to invoke them by using their full paths (e.g., `/bin/ls` or `/bin/sh` instead of simply `ls` and `sh`.) ::: ## Interactive sessions By default, the `cartesi-machine` utility executes the Cartesi Machine in non-interactive mode. Verifiable computations must always be run in non-interactive sessions. User interaction with a Cartesi Machine via the console is, after all, not reproducible. Nevertheless, during development, it is often convenient to directly interact with the emulator, as if using a computer console. The command-line option `-i` (short for `--htif-console-getchar`) instructs the emulator to monitor the console for input, and to make this input available to the Linux kernel. Typically, this option will be used in conjunction with the `--` separator and the command `sh`, causing the Cartesi-provided `/sbin/init` script to drop into an interactive shell. Interaction with the shell enables the exploration of the embedded Linux distribution from the inside. Exiting the shell returns control back to `/sbin/init`, which then gracefully halts the machine. For example, if an interactive session is started with the following command ```bash cartesi-machine -i -- sh ``` it drops into the shell. Running the command `ls /bin` causes the listing of directory `/bin` to appear. The command `exit` causes the shell to exit. The output is ``` %machine.host.cmdline.interactive-ls ``` :::note When running in interactive mode, not even the final cycle count is reproducible. To avoid busy wait for new interactive input, the emulator sleeps from one Cartesi Machine timer interrupt to the next, skipping Cartesi Machine cycles forward so programs running inside to stay _roughly_ in sync with wall-clock time outside. This dynamic balancing act is sure to vary between executions and across different computers. ::: ## Flash drives The command-line option `--flash-drive=label: