Update Docs to cover foreclosure and emergency withdrawal#343
Open
Nonnyjoe wants to merge 11 commits into
Open
Update Docs to cover foreclosure and emergency withdrawal#343Nonnyjoe wants to merge 11 commits into
Nonnyjoe wants to merge 11 commits into
Conversation
Contributor
📖 Docs preview is readyPreview: https://cartesi.github.io/docs/pr-preview/pr-343/ Built from commit |
Move the category from a top-level sidebar entry to inside the Development section, right after Advanced-configuration. Files stay in foreclosure/. `yarn build` passes.
…/withdrawal on Application - Bump all Base Layer Contracts source refs v2.0.1 -> v3.0.0-alpha.6 (21 pages); fix EtherPortal src path typo. - application.md: 5-param constructor (adds WithdrawalConfig), intro paragraph, and full "Guardian & Foreclosure" (IApplicationForeclosure) and "Emergency Withdrawal" (IApplicationWithdrawal) sections — functions, getters, events, errors, and the AccountValidityProof struct. `yarn build` passes.
Fill the Base Layer Contracts → Withdrawal subsection from v3.0.0-alpha.6 sources: overview (how the pieces compose + four-way accounts-drive agreement), WithdrawalConfig (struct, drive geometry, LibWithdrawalConfig.isValid), IWithdrawalOutputBuilder, UsdWithdrawalOutputBuilder, and its factory.
…reference - application-factory.md: add WithdrawalConfig to newApplication (x2), calculateApplicationAddress, and the ApplicationCreated event; document the InvalidWithdrawalConfig error. - JSON-RPC: fill cartesi_listWithdrawals and cartesi_getWithdrawal from the node model/handlers; add the Withdrawal interface + WithdrawalList/GetResult to types.
…hase 2) - overview: what foreclosure/emergency withdrawal are, the two parts, the operator trust model (protects against an operator who disappears, not one who lies), and when funds are recoverable. - lifecycle: inputs -> epochs -> claim -> submit/stage/accept, the epoch-status flow (with an ASCII state diagram), foreclosure effects, and prove+withdraw. - recovery-guide: step-by-step foreclose -> replay -> prove accounts-drive -> prove-drive-root -> withdraw -> verify, plus the public-chain 30M-gas caveat. Plain wording, no em-dashes. Build passes.
…ases 3-4) - backend/emergency-withdrawal: the guest requirement to maintain the accounts drive matching the WithdrawalConfig, record layout, and the four-way agreement. - deployment/self-hosted split: overview chooser (keeps old URL via slug), standard (existing content), and with-emergency-withdrawal (same compose + a machine-tool service, deploy with --withdrawal-config-file, recovery link). Plain wording, no em-dashes. Build passes.
…s caveat - with-emergency-withdrawal: remove the manual machine-tool compose step (it is already in the standard compose file); add Configuration and full "Setting up the local node" steps (download compose, build, run, deploy with --withdrawal-config-file), mirroring the standard flow. Recovery stays last. - Rename both overview pages' title to "Overview" (foreclosure + self-hosted), so the sidebar entries read "Overview" under their categories. - recovery-guide: remove the public-chain gas-limit section (being fixed for the next alpha). Build passes.
…W deploy - with-emergency-withdrawal: add a "Configure the machine and ledger" section covering the cartesi.toml accounts-drive block ([drives.accounts], raw/empty, final_hash) and the requirement that the app use a ledger library to write balances in a provable layout. - Link the Asset Management Library docs (temporarily via the PR-303 preview URL, since that page is not on this branch yet) from both the deploy guide and the backend guest-requirements page. Build passes. NOTE: the two Asset Management links use the pr-preview/pr-303 URL; swap them for the internal ../asset-management/overview.md once PR #303 merges to main.
Nonnyjoe
force-pushed
the
docs/emergency-withdrawal-v2
branch
from
5fd6acf to
5af94e1
Compare
…e image - Rename the Withdrawal contracts overview page title to Overview. - Remove the "What you are trusting" section from the Foreclosure overview. - Move the foreclosure pages into the development/ folder to match the sidebar nesting, updating the sidebar and all inbound/outbound links. - Replace the epoch-status ASCII diagram with the epoch-flow.png image.
Add the Foreclosure & Emergency Withdrawal guides (under Development), the Withdrawal contract pages, the backend accounts-drive page, the JSON-RPC withdrawals methods, and the self-hosted standard / with-emergency-withdrawal split. Update the Development documentation-map bullet.
tuler
reviewed
Jul 8, 2026
tuler
left a comment
tuler
left a comment
Member
There was a problem hiding this comment.
What I miss from the documentation is more information about how to create an account drive that can work with EW.
Member
Author
@tuler I initially added a section for this to the deployment page, however it seems to not be the best position for it so I've moved it to the "API-Reference/Backend-API/emergency-withdrawal" section, then reference to this section was added to the development and deployment section. We also have a page that covers in-dept the different configuration options for Cartesi.toml file, this can be found in "Development/Advance-configuration", would appreciate your review on that also. |
- Rename the concept section to "Emergency Withdrawal" and update all sidebar, cross-page, and llms.txt references. - Add a standalone recovery-tools install guide (Cartesi Machine emulator, cartesi-rollups-cli, machine tool) with per-tool Linux and macOS steps. - Add a tabbed CLI/cast recovery walkthrough covering foreclose, replay, accounts-drive proving, root anchoring, and withdrawal. - Document how the guest creates and sizes the accounts drive against its WithdrawalConfig, and point the deployment guide to it to avoid duplication. - Expand the claim and foreclosure lifecycle for accuracy across Authority, Quorum, and PRT, including epoch definition, input-processing timing, and the three-step prove-and-withdraw flow. - Add foreclosure and accounts-drive withdrawal sequence diagrams and refresh the epoch-flow diagram. - Clarify that CLAIM_REJECTED is a node-level status, not an on-chain outcome.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.