AI agent documentation index: llms.txt. Raw markdown for any page is available by appending .md to the URL. Full content snapshot: llms-full.txt.
llms.txt — complete Cartesi documentation index. Append .md to any page URL for raw Markdown (e.g. /cartesi-rollups/2.0/development/building-an-application.md).
Skip to main content

Overview

When users deposit assets into a Cartesi Rollups application, those assets are held by the application contract on the base layer, and the application's off-chain state (an in-app ledger of who owns what) decides how they can be spent. In normal operation the operator runs a node that keeps this state moving and settles it on-chain. But what happens to those funds if the operator stops running the node?

Foreclosure and emergency withdrawal are the answer. They let a designated guardian freeze an application, after which any user can withdraw their in-app balance straight from the base-layer contracts by proving their account, with no running node required.

The feature is opt-in: an application only supports it if it was deployed with a WithdrawalConfig. Applications deployed without one behave exactly as before. In addition to that, the application is also expected to record the assets deposited into it using the CMA ledger library. This library keeps those balances inside the accounts drive in a recoverable, provable layout that matches the WithdrawalConfig. See the Asset Management Library section for more details about the CMA library.

The two parts​

Foreclosure freezes the application. A guardian address, set in the withdrawal config, calls foreclose(). From that moment the application is frozen at its last settled state, and it stays frozen forever. See FOR-005 for the guardian-only rule.

Emergency withdrawal is the recovery path that foreclosure unlocks, and it is built on the application's accounts drive.

The accounts drive is a dedicated drive, a region of the Cartesi Machine's memory, that the application uses as its balance ledger. It records how much each account owns, in a fixed layout described by the WithdrawalConfig. Like every drive, it sits at a known, fixed address in the machine's memory. The machine's whole memory is a single Merkle tree whose root, the machine state root hash, is finalized on-chain as part of the settled claim. Because the accounts drive occupies a known address, its own Merkle root is a fixed branch of that tree, so it can be proven up to the machine state root hash with a short list of sibling hashes. After foreclosure, anyone submits that proof once to anchor the accounts-drive root on-chain against the application's last settled machine state. The ledger is then fixed on-chain, and each user withdraws their own balance by proving their account against that anchored drive. Everything happens directly against the contracts, so it keeps working even if the operator and its node are gone.

When funds are recoverable​

All of the following must hold:

  1. the application was deployed with a valid WithdrawalConfig (a guardian, an accounts-drive layout, and a withdrawal output builder);
  2. the guest application actually maintains the accounts drive in the layout the config describes;
  3. the application has been foreclosed by its guardian; and
  4. the account's balance was part of the last settled state.

Where to go next​

On this page

AboutBlogGovernance & Grants
WhitepaperFoundation NoticeUsage Policy

© 2026 Cartesi Foundation Ltd. All rights reserved.

The Cartesi Project is commissioned by the Cartesi Foundation.

We use cookies to ensure that we give you the best experience on our website. By using the website, you agree to the use of cookies.
PRIVACY POLICY