Update Docs to cover foreclosure and emergency withdrawal#343
Open
Nonnyjoe wants to merge 10 commits into
Open
Update Docs to cover foreclosure and emergency withdrawal#343Nonnyjoe wants to merge 10 commits into
Nonnyjoe wants to merge 10 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.
|
|
||
| **Inputs.** A user action (a deposit through a portal, or a message sent to the app) becomes an **input**, recorded on-chain in the [`InputBox`](../../api-reference/contracts/input-box.md). | ||
|
|
||
| **Epochs.** Inputs are not settled one at a time. They are grouped into **epochs**, where an epoch is a fixed range of blocks (set by the consensus `epochLength`). Every input is assigned to an epoch by the block it arrived in. |
Member
There was a problem hiding this comment.
this is true for Authority but not true for PRT. It would be better to rephrase in a way that would be true for both, without complicating too much the explanation or going too deep in the issue.
|
|
||
| **Epochs.** Inputs are not settled one at a time. They are grouped into **epochs**, where an epoch is a fixed range of blocks (set by the consensus `epochLength`). Every input is assigned to an epoch by the block it arrived in. | ||
|
|
||
| **Claims.** The application runs as a deterministic Cartesi Machine. Once an epoch's block range closes, the node feeds that epoch's inputs to the machine, which updates its state and produces outputs. The node then reduces the result to a single fingerprint, a **claim** (a Merkle root), and posts it on-chain so the consensus contract can trust the off-chain computation by checking one hash. |
Member
There was a problem hiding this comment.
there is a small issue here when it says "Once an epoch's block range closes, the node feeds that epoch's inputs to the machine". In fact it feeds every input right after they arrive, not when epoch closes.
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.