[withdrawal.config] requires values a developer cannot reasonably compute

[tuler]

Problem

The [withdrawal.config] section recently added to cartesi.toml requires the developer to supply five values, all of them mandatory:

[withdrawal.config]
guardian = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
log2_leaves_per_account = 0
log2_max_num_of_accounts = 7
accounts_drive_start_index = 9895604649984
withdrawal_output_builder = "0x0745787835A019cd4dae8EDB541Fbc0647793d63"

parseWithdrawalConfig (apps/cli/src/config.ts:593) rejects the section unless all five are present, and the result is forwarded verbatim to cartesi-rollups-cli via --withdrawal-config (apps/cli/src/exec/rollups.ts:531).

The semantics of these fields come from the emergency withdrawal specification. None of them is a decision a developer makes while writing an application, and in a local development environment — the CLI's primary target — every one of them has a single correct answer that the CLI is already in a position to know:

• withdrawal_output_builder — the devnet already deploys TestUsdWithdrawalOutputBuilder, and the CLI already publishes its address in the address book (apps/cli/src/base.ts:121). The user is being asked to paste back a value the CLI just printed.
• guardian — on a local devnet this is one of the well-known Anvil accounts.
• log2_leaves_per_account — is 0 for applications that do not store more than one leaf per account, which is the common case.
• log2_max_num_of_accounts — is a function of the accounts drive size, derived from the spec (unless the drive is also used for other data). The developer has to do that arithmetic by hand and redo it whenever the drive size changes.
• accounts_drive_start_index — is not a choice at all. It is the address at which the emulator placed the accounts drive.

accounts_drive_start_index is the sharpest edge

The CLI deliberately does not pass start or length when it builds flash drive arguments (apps/cli/src/machine.ts:20, // don't specify start and length), so placement is decided entirely by the emulator: the first drive is placed past the RAM, and each remaining drive past the previous one (machine-emulator docs).

The value in the example above, 9895604649984, is 0x90000000000 — that is 0x80000000000 + 1 × 0x10000000000, i.e. "the second flash drive". To produce it, a developer has to know the emulator's base address, its stride, and the ordinal position of the accounts drive among the drives declared in cartesi.toml.

Worse, the value is silently coupled to unrelated edits. Declaring a new drive ahead of the accounts drive, or reordering the drives, shifts the address and invalidates the configuration. Nothing in build or run detects the mismatch — the machine still builds and the application still deploys, just with a withdrawal configuration pointing at the wrong drive.

Consequence

Enabling emergency withdrawal locally requires reading the specification, understanding the emulator's memory layout, and hand-computing values that the CLI could resolve itself. This is disproportionate for what should be a local development workflow, and the resulting configuration is fragile in a way that fails quietly.

What a good outcome looks like

Enabling emergency withdrawal on the local devnet should require little or no configuration, with explicit values still available as overrides for cases the defaults do not cover (notably fork/live chains, where guardian and withdrawal_output_builder have no sane default). The all-or-nothing parsing should become per-field optionality, and existing cartesi.toml files that spell out all five values must keep working unchanged.

For the values that depend on the machine layout, the resolved configuration is the source of truth, not the emulator's placement rule reimplemented in the CLI. cartesi build already stores a machine snapshot (--store=image, apps/cli/src/commands/build.ts:157), and that snapshot already carries a config.json with each flash drive's resolved start and length. Making that resolved configuration reachable — to the CLI itself and to the developer — is likely a prerequisite for anything else here, and is useful for debugging drive layout regardless of emergency withdrawal.

Open questions

1. How is the accounts drive identified? By naming convention, by a flag on the drive configuration, or by an explicit reference under [withdrawal]? Should enabling withdrawal create the drive when none is declared, and at what size?
2. What exactly is the formula for log2_max_num_of_accounts per the specification — leaf size, and whether it rounds down to fit the drive or must match it exactly?
3. Where does log2_leaves_per_account belong — in [withdrawal.config], on the accounts drive configuration, or both?
4. What is the opt-in signal for enabling emergency withdrawal at all, once the section can be empty?
5. Should build/run reject (or warn about) an explicitly configured accounts_drive_start_index that disagrees with the resolved machine layout? That is what would catch the "I added a drive and it silently broke" case described above.

[guidanoli]

How is the accounts drive identified?

Explicit reference under the [withdrawal] section.

Should enabling withdrawal create the drive when none is declared, and at what size?

No. The accounts drive should be declared explictly and referenced under [withdrawal].

What exactly is the formula for log2_max_num_of_accounts per the specification

Assuming the drive size is of the form 2^log2_drive_size and log2_drive_size >= 5:
log2_max_num_of_accounts = log2_drive_size - log2_leaves_per_account - 5.

Where does log2_leaves_per_account belong

Under the [withdrawal.config] section, with 0 being the default.

What is the opt-in signal for enabling emergency withdrawal

An accounts drive being referenced under [withdrawal].

Should build/run reject (or warn about) an explicitly configured accounts_drive_start_index that disagrees with the resolved machine layout? That is what would catch the "I added a drive and it silently broke" case described above.

Yes, it should reject a misconfigured accounts_drive_start_index.
(Why not remove this field altogether and let CLI derive it from the drive config?)

[tuler]

Another alternative is not have a [withdraw] config section, and configure the drive as being for withdraw, maybe with a special builder type, avoiding mistakes like using a ext2 drive for withdraw.

[guidanoli]

I thought that configuring EW-specific stuff in the drive section would complicate things for the CLI back-end, but if not, that is also a valid option.

[lynoferraz]

I agree. Although I don't think restricting to a builder is a good option, as one could have a customized drive/nvram for that. I think a extra tag like use_as_accounts_drive = "true" would be better. Also, I think we should keep the [withdraw] section to override any value.

[tuler]

customized drive/nvram for that

what do you mean by customized in this context?

[lynoferraz]

One example would be the accounts drive is a nvram shared with other applications data to serve as the application's state 'drive'. This drive may be already initialized, despite the accounts drive section being zeroed.

[tuler]

One example would be the accounts drive is a nvram shared with other applications data to serve as the application's state 'drive'. This drive may be already initialized, despite the accounts drive section being zeroed.

I'll keep that in mind.
But for sanity you can always have more than one nvram drive (up to 8), and keep one for each purpose. That is more organized and should be the recommendation.

Because if you have a drive (or nvram) that only a part of it is the accounts area, that defeats the purpose of the recommendations here (that the drive position can define the start index, and the size can define number of accounts).

I'd rather simplify the usage, than keep it mega-flexible. Unless there is a real reason not to use multiple drives.

[brunomenezes]

My 2 cents here is that this [withdrawal] section is a configuration passed down to the rollups-node, and at the moment it is all or nothing (When nothing is provided, it will be filled with its zero-equivalent defaults). I'm not sure I understand the idea of derivation from X or Y because there is no explicit connection in the config options to other sections. Without a clear specification of how that should work properly between the parts, trying to be "smart" about it is prone to maintenance problems, in my opinion.

[tuler]

I'm not sure I understand the idea of derivation from X or Y

What matters is whether you have a drive to be used for EW. Not if you have a [withdraw] config section or not.