Update Docs to cover foreclosure and emergency withdrawal

cartesi-rollups_versioned_docs/version-2.0/api-reference/backend/emergency-withdrawal.md

@@ -0,0 +1,75 @@
+---
+id: emergency-withdrawal
+title: Emergency Withdrawal (guest requirements)
+---
+
+[Emergency withdrawal](../../development/emergency-withdrawal/overview.md) lets users recover their in-app balances directly from the base layer after an application is foreclosed. For that to work, the on-chain contracts need a way to read each account's balance from the settled machine state. This page describes what the **guest application** (the code running inside the Cartesi Machine) must do to support it.
+
+## The accounts drive
+
+The application keeps a dedicated region of machine memory called the **accounts drive**. It is the withdrawable-balance ledger: a list of account records, where each record holds an owner and that owner's balance. After foreclosure, the contracts prove this drive against the settled machine state and pay each account out from it.
+
+An application supports emergency withdrawal only if:
+
+1. It maintains an accounts drive, and
+2. The drive's layout matches the [`WithdrawalConfig`](../contracts/withdrawal/withdrawal-config.md) the application was deployed with.
+3. The WithdrawalOutputBuilder contract configured in the application can decode the account and build a valid output to withdraw the assets
+
+If the layout the guest writes and the config the contract was given disagree, proofs will not validate and funds cannot be withdrawn.
+
+## Matching the layout
+
+The [`WithdrawalConfig`](../contracts/withdrawal/withdrawal-config.md) describes the drive with three values, and the guest must write records that match them:
+
+- `accountsDriveStartIndex` positions the drive in machine memory;
+- `log2MaxNumOfAccounts` sets how many accounts fit (the tree depth);
+- `log2LeavesPerAccount` sets each record's size, which is `2^(5 + log2LeavesPerAccount)` bytes.
+
+For the single-token case (see [`UsdWithdrawalOutputBuilder`](../contracts/withdrawal/usd-withdrawal-output-builder.md)), each record is 32 bytes: an 8-byte little-endian balance, followed by the 20-byte owner address, followed by padding.
+
+## Creating the accounts drive
+
+The accounts drive is a standard Cartesi Machine drive, declared in your project's `cartesi.toml` alongside every other drive. The [Advanced configuration](../../development/advanced-configuration.md#drives) guide covers how drives are defined and built in general; the accounts drive is distinctive only in that it is left raw, so the guest can write balance records into it directly.
+
+Declare it next to the root drive as an empty, raw, unmounted flash drive, and set `final_hash = true` so the build produces the machine hash that on-chain deployment requires:
+
+```toml
+[machine]
+# ...your existing machine settings...
+final_hash = true
+
+# The application and OS, built from your Dockerfile.
+[drives.root]
+builder = "docker"
+dockerfile = "Dockerfile"
+format = "ext2"
+
+# The accounts drive: a raw, unformatted flash drive for the balance ledger.
+[drives.accounts]
+builder = "empty"
+format = "raw"
+size = 4194304   # size in bytes
+mount = false
+user = "dapp"
+```
+
+Leaving the drive raw and unmounted is deliberate. Rather than layering a filesystem on top, the guest opens the block device directly (for example `/dev/pmem1`) and writes fixed-size records at deterministic offsets. That predictable layout is precisely what allows the drive to be Merkle-proven against the machine state after foreclosure. The [Common drive options](../../development/advanced-configuration.md#common-drive-options) reference explains each field used above.
+
+Two properties of the drive must agree with the [`WithdrawalConfig`](../contracts/withdrawal/withdrawal-config.md):
+
+- **Size.** The drive must be large enough to hold the entire account tree, which spans `2^(5 + log2MaxNumOfAccounts + log2LeavesPerAccount)` bytes. A single-token ledger with `log2LeavesPerAccount = 0` and `log2MaxNumOfAccounts = 12`, for example, occupies `2^17` bytes (128 KiB), well within the drive declared above.
+- **Position.** `accountsDriveStartIndex` records where the drive begins in machine memory, expressed as its start address divided by that account-tree size. You do not compute it by hand: `cartesi build` places the drive, and you read the assigned position from `.cartesi/image/config.json`. That value is the `accountsDriveStartIndex` you supply in the [`WithdrawalConfig`](../contracts/withdrawal/withdrawal-config.md#drive-geometry) at deploy time.
+
+With the drive declared and sized, the guest fills it with balance records, as described next.
+
+## Keeping the balances
+
+You rarely need to write the drive by hand. A ledger library maintains the accounts drive for you: it credits deposits, debits withdrawals and transfers, and stores every balance in the drive so it stays provable from the machine state. See the [Asset Management Library](https://cartesi.github.io/docs/pr-preview/pr-303/cartesi-rollups/2.0/api-reference/asset-management/overview/) for how to store and manage balances this way.
+
+## The account encoding must round-trip
+
+The bytes the guest writes for an account must be the same bytes the on-chain [withdrawal output builder](../contracts/withdrawal/iwithdrawal-output-builder.md) decodes at withdrawal time. For the USD builder, that means the `(owner, balance)` encoding the guest produces must match what the builder reads back to build the transfer.
+
+:::note
+Emergency withdrawal relies on four descriptions of the accounts drive agreeing: the layout the **guest** writes, the **`WithdrawalConfig`** on-chain, the parameters used to **generate proofs** off-chain, and the account encoding the **output builder** decodes. Choose these together at deploy time. See [Withdrawal Contracts Overview](../contracts/withdrawal/overview.md#the-four-way-agreement).
+:::

cartesi-rollups_versioned_docs/version-2.0/api-reference/contracts/application-factory.md

@@ -2,7 +2,7 @@
 id: application-factory
 title: ApplicationFactory
 resources:
-  - url: https://github.com/cartesi/rollups-contracts/tree/v2.0.1/src/dapp/ApplicationFactory.sol
+  - url: https://github.com/cartesi/rollups-contracts/tree/v3.0.0-alpha.6/src/dapp/ApplicationFactory.sol
     title: Application Factory contract
 ---
 
@@ -21,7 +21,8 @@ function newApplication(
     IOutputsMerkleRootValidator outputsMerkleRootValidator,
     address appOwner,
     bytes32 templateHash,
-    bytes calldata dataAvailability
+    bytes calldata dataAvailability,
+    WithdrawalConfig calldata withdrawalConfig
 ) external override returns (IApplication)
 ```
 
@@ -35,6 +36,7 @@ Deploys a new Application contract without a salt value for address derivation.
 | `appOwner` | `address` | Address of the owner of the application |
 | `templateHash` | `bytes32` | Hash of the template for the application |
 | `dataAvailability` | `bytes` | The data availability solution |
+| `withdrawalConfig` | `WithdrawalConfig` | The withdrawal configuration (see [WithdrawalConfig](./withdrawal/withdrawal-config.md)). Pass a zero-valued config to deploy without emergency withdrawal |
 
 **Return Values**
 
@@ -50,6 +52,7 @@ function newApplication(
     address appOwner,
     bytes32 templateHash,
     bytes calldata dataAvailability,
+    WithdrawalConfig calldata withdrawalConfig,
     bytes32 salt
 ) external override returns (IApplication)
 ```
@@ -64,6 +67,7 @@ Deploys a new `Application` contract with a specified salt value for address der
 | `appOwner` | `address` | Address of the owner of the application |
 | `templateHash` | `bytes32` | Hash of the template for the application |
 | `dataAvailability` | `bytes` | The data availability solution |
+| `withdrawalConfig` | `WithdrawalConfig` | The withdrawal configuration (see [WithdrawalConfig](./withdrawal/withdrawal-config.md)). Pass a zero-valued config to deploy without emergency withdrawal |
 | `salt` | `bytes32` | Salt value for address derivation |
 
 **Return Values**
@@ -80,6 +84,7 @@ function calculateApplicationAddress(
     address appOwner,
     bytes32 templateHash,
     bytes calldata dataAvailability,
+    WithdrawalConfig calldata withdrawalConfig,
     bytes32 salt
 ) external view override returns (address)
 ```
@@ -94,6 +99,7 @@ Calculates the address of a potential new Application contract based on input pa
 | `appOwner` | `address` | Address of the owner of the application |
 | `templateHash` | `bytes32` | Hash of the template for the application |
 | `dataAvailability` | `bytes` | The data availability solution |
+| `withdrawalConfig` | `WithdrawalConfig` | The withdrawal configuration (see [WithdrawalConfig](./withdrawal/withdrawal-config.md)). Pass a zero-valued config to deploy without emergency withdrawal |
 | `salt` | `bytes32` | Salt value for address derivation |
 
 **Return Values**
@@ -112,6 +118,7 @@ event ApplicationCreated(
     address appOwner,
     bytes32 templateHash,
     bytes dataAvailability,
+    WithdrawalConfig withdrawalConfig,
     IApplication appContract
 )
 ```
@@ -126,4 +133,21 @@ A new Application contract was deployed.
 | `appOwner` | `address` | The owner of the application |
 | `templateHash` | `bytes32` | The template hash |
 | `dataAvailability` | `bytes` | The data availability solution |
+| `withdrawalConfig` | `WithdrawalConfig` | The withdrawal configuration (see [WithdrawalConfig](./withdrawal/withdrawal-config.md)). Pass a zero-valued config to deploy without emergency withdrawal |
 | `appContract` | `IApplication` | The deployed Application contract |
+
+## Errors
+
+### `InvalidWithdrawalConfig()`
+
+```solidity
+error InvalidWithdrawalConfig(WithdrawalConfig withdrawalConfig)
+```
+
+Raised at deployment when the provided [`WithdrawalConfig`](./withdrawal/withdrawal-config.md) is invalid, meaning its accounts-drive layout does not fit inside the machine memory (see [`LibWithdrawalConfig.isValid`](./withdrawal/withdrawal-config.md#validation)). Checking the config in the factory means users and the node do not have to check it themselves.
+
+**Parameters**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `withdrawalConfig` | `WithdrawalConfig` | The invalid withdrawal configuration |