updates with review comments from lyno

Author: riseandshaheen

fraud-proofs/fraud-proof-basics/epochs.md

@@ -18,8 +18,8 @@ Epochs serve several critical roles in Cartesi's fraud proof system:
 
 The system maintains the following epoch states at all times:
 
-1. **Settled Epochs**: Fully finalized state. Their outputs (e.g., vouchers) are executable.
-2. **Sealed Epoch**: The inputs for this epoch are fixed (sealed). This epoch is currently under dispute, if needed. It can take at least one week for a sealed epoch to be verified by the fraud-proof system.
+1. **Settled Epochs**: Fully finalized state. The outputs generated during these epochs can be validated on-chain.
+2. **Sealed Epoch**: The inputs for this epoch are fixed (sealed). This epoch is opened for state claims to be submitted, and if needed, trigger disputes. It takes at least one week for a sealed epoch to be settled by the fraud-proof system to allow anyone to also validate and submit claims.
 3. **Accumulating Epoch**: Actively collecting new inputs.
 
 ![Epoch States](../images/epochs-lifecycle.png)

fraud-proofs/fraud-proof-basics/introduction.md

@@ -4,9 +4,9 @@ This page provides a beginner-friendly introduction to fraud proof systems and t
 
 ## What is a Fraud Proof System?
 
-In [Cartesi rollups](../../../get-started/optimistic-rollups), users submit their input transactions to the base layer, the off-chain validator nodes process the inputs and submit _claims_ back to the blockchain. These claims are treated as correct by default - _optimistically_ - but they don’t finalize immediately rather, they remain open to challenge for a certain period. In case of conflicting claims, a fraud-proof system kicks in.
+In [Cartesi rollups](../../../get-started/optimistic-rollups), users submit their input transactions to the base layer, the off-chain validator nodes process the inputs and submit _claims_ of the resulting state back to the blockchain. These claims are treated as correct by default - _optimistically_ - but they aren't considered final immediately rather, they remain open to be challenged for a certain period. In case of conflicting claims, a fraud-proof system kicks in.
 
-A **fraud-proof system** is a mechanism that enables the blockchain to adjudicate disputes between participants and identify the valid claim, while requiring only minimal on-chain computation.
+A **fraud-proof system** enables the blockchain to adjudicate disputes between conflicting claims of the rollup's state, and identify the valid claim, while requiring only minimal on-chain computation.
 
 Note that the base layer (_here Ethereum_) acts as the data provider of inputs and also the on-chain verifier to resolve the disputes. Because of this, Cartesi rollups inherit Ethereum’s security: as long as at least one honest participant monitors the rollup and submits a valid claim when needed, the system can’t be corrupted.
 

fraud-proofs/fraud-proof-basics/state-transition-function.md

@@ -17,17 +17,15 @@ Understanding the Cartesi STF would require us to know a few concepts of the Car
 ### State of the Cartesi Machine
 In the context of Cartesi, the state typically refers to the state of the Cartesi Machine. A Cartesi Machine state is a complete snapshot of the machine’s execution environment at a given point in time. This includes the full address space - contents of physical memory (RAM), all register values, internal cycle counter and input/output flash drive states. 
 
-The **state hash** is a Merkle root representing this snapshot. The machine exposes its entire 64-bit physical address space as a flat array over which a Merkle tree is constructed. Each leaf of the tree corresponds to a 32-bytes memory word, and the root hash serves as a unique and verifiable fingerprint of the machine state. 
+The **state hash** is a Merkle root representing this snapshot. The machine exposes its entire 64-bit physical address space as a flat array over which a Merkle tree is constructed. Each leaf of the tree corresponds to a 32-bytes memory word, and the root hash serves as a unique and verifiable fingerprint of the machine state. This snapshot representation of the machine ensures that flipping even a single bit in the state produces a different hash, making it straightforward to verify whether two states are equivalent.
 
 A computation on the Cartesi Machine is therefore defined by a transition between two such state hashes. The **initial state hash** encodes all the information necessary to begin execution, while the **final state hash** summarizes the result after the computation has been performed. This structure enables efficient and trustless verification of state transitions on-chain, where only Merkle proofs need to be submitted rather than the full state. 
 
-The machine also supports generation and validation of **access logs** - cryptographic proofs of transition between two state commitments - which are central to enabling interactive dispute resolution protocols.
-
 ## Computation Hash
 The computation hash is a cryptographic commitment to the entire history of a computation, not just its final state. It is constructed as a Merkle tree, where each leaf node represents a state hash corresponding to a 
 _step_ in the computation - from the initial state (implicitly agreed upon) to the final state.
 
-Unlike traditional models that only commit to the end result, this structure allows one to verify any intermediate step. To optimize storage and efficiency - especially for use in PRT (Permissionless Refereed Tournament) - the computation hash is designed to support multi-level hierarchies. This brings us to the next concept, _sparsity_.
+Unlike traditional models that only commit to the end result, this structure makes it possible to verify the entire sequence of steps leading to the final hash, thereby also validating all intermediate steps. To optimize storage and efficiency - especially for use in PRT (Permissionless Refereed Tournament) - the computation hash is designed to support multi-level hierarchies. This brings us to the next concept, _sparsity_.
 
 ![Computation Hash](../images/computation-hash-tree.jpg)
 

fraud-proofs/honeypot/application-logic.md

@@ -10,7 +10,7 @@ As a standard Cartesi application, the Honeypot exposes two functions to process
 
 ![ERC-20 Token Operations](../images/honeypot-operations.png)
 
-## Operations Handlers
+## Operations
 
 The application implements three primary operations with specific validation and processing logic:
 

fraud-proofs/honeypot/prt-integration.md

@@ -2,15 +2,16 @@
 
 ## Architecture Overview
 
-The Honeypot v2 is secured by Permissionless Refereed Tournament(PRT) as the fraud proof system. Its core on‐chain components include the Application contract (the Honeypot app itself) and a separate `DaveConsensus` contract that implements the PRT consensus logic.  In the v2 deployment (Mainnet), Cartesi explicitly uses a 3‑layer PRT consensus (“PRT‑3L”). 
+The Honeypot v2 is secured by Permissionless Refereed Tournament(PRT) as the fraud proof system. Its core on‐chain components include the _Application contract_ (the Honeypot app itself) and a separate _Rollups-PRT Consensus contract_ that orchestrates the PRT consensus logic.  In the v2 deployment on Ethereum Mainnet, a 3‑layer PRT consensus (also known as _PRT‑3L_) is used. 
 
-The Application contract holds all user deposits and executes outputs, but it delegates output validity checks to the `DaveConsensus` contract via the `IOutputsMerkleRootValidator` interface.  In practice, the Application simply calls `validateOutput(...)` on any proposed output; that call invokes the DaveConsensus logic to decide if the output’s Merkle root is valid.  This cleanly separates the application’s business logic (escrowing tokens, enforcing withdraw rules) from the fraud‐proof logic (verifying computation correctness).
+The Application contract holds all user deposits and executes outputs, but it delegates output validity checks to the `DaveConsensus` contract via the `IOutputsMerkleRootValidator` interface.  All applications' outputs can be effectively validated by a `validateOutput(...)` call on the application contract. This call invokes the DaveConsensus logic to decide if the output’s Merkle root is valid.  This cleanly separates the application’s business logic (escrowing tokens, enforcing withdraw rules) from the fraud‐proof logic (verifying computation correctness).
 
 ![Honeypot with PRT](../images/honeypot-prt-architecture.png)
 
 ## On-Chain Components
 
-**Application (Honeypot App) Contract:**  The main application contract (implementing `IApplication`) contains the Honeypot logic.  It inherits standard modules (Ownable, token holder guards, reentrancy guard) and **never embeds any tournament logic**.  Instead, it stores an `IOutputsMerkleRootValidator` instance (initialized in its constructor) to validate outputs. When an off‐chain computation produces an output (e.g. a Voucher or DelegateCallVoucher allowing a withdraw), the app contract’s `executeOutput(bytes output, OutputValidityProof proof)` function is invoked. This function **first calls** `validateOutput(output, proof)`, which in turn checks the Merkle proof against the current validator:
+#### **Honeypot Application Contract** 
+The main application contract (implementing `IApplication`) is the representation of the Honeypot application on-chain.  It inherits standard modules (Ownable, token holder guards, reentrancy guard) and never embeds any tournament logic.  Instead, it stores an `IOutputsMerkleRootValidator` instance (initialized in its constructor) to validate outputs. When an off‐chain computation produces an output (e.g. a Voucher or DelegateCallVoucher allowing a withdraw), the app contract’s `executeOutput(bytes output, OutputValidityProof proof)` function is invoked. This function **first calls** `validateOutput(output, proof)`, which in turn checks the Merkle proof against the current validator:
 
 ```javascript
 function validateOutput(bytes calldata output, OutputValidityProof calldata proof)
@@ -23,33 +24,23 @@ function validateOutput(bytes calldata output, OutputValidityProof calldata proo
 
 Thus, outputs are only accepted if DaveConsensus has marked the corresponding root as valid. Only after validation does the contract perform the application logic (calling voucher/delegate calls, which in practice transfer the ERC‑20 tokens). All application‐level “withdraw” rules (e.g. only a pre‐configured account can receive tokens) are enforced in the off‐chain logic and then honored on‐chain via these voucher calls.
 
-**PRT Consensus (DaveConsensus):**  The DaveConsensus contract implements Cartesi’s PRT protocol for a single application. It keeps track of “epochs” (intervals of inputs) and manages the tournament for each epoch. Importantly, it implements both `IDataProvider` and `IOutputsMerkleRootValidator`. Application outputs are considered valid if and only if DaveConsensus has stored that output-root as acceptable. In DaveConsensus, the function `isOutputsMerkleRootValid(address app, bytes32 root)` simply checks a mapping set during settlement. This value is set to true only when a **tournament has been settled successfully** for that epoch and the outputsMerkleRoot has been verified via on-chain computations.
+#### **PRT-Rollups Consensus (DaveConsensus)** 
+The DaveConsensus contract implements Cartesi’s PRT protocol for a single application. It keeps track of “epochs” (intervals of inputs) and manages the tournament for each epoch. Importantly, it implements both `IDataProvider` and `IOutputsMerkleRootValidator`. Application outputs are considered valid if and only if DaveConsensus has stored that output-root as acceptable. In DaveConsensus, the function `isOutputsMerkleRootValid(address app, bytes32 root)` simply checks a mapping set during settlement. This value is set to true only when a **tournament has been settled successfully** for that epoch and the outputsMerkleRoot has been verified via on-chain computations.
 
-**PRT Tournament Contracts:**  Under the hood, DaveConsensus uses a `ITournamentFactory` (typically the Cartesi *MultiLevelTournamentFactory*) to spawn a new **TopTournament** at the start of each epoch. Each dispute is handled by a multi‐stage “tournament” on-chain: the TopTournament coordinates bisection of a disputed computation trace, while BottomTournament contracts handle the final step-by-step verification by calling the on-chain Cartesi machine verifier (CartesiStateTransition) for a single contested instruction. All these PRT contracts (TopTournament, BottomTournament, factory) are part of Cartesi’s `prt-contracts` library and are invoked indirectly via DaveConsensus. The Application itself never needs to know about these; it only interacts with the DaveConsensus contract.
+#### **PRT Tournament Contracts**  
+Under the hood, DaveConsensus uses a `ITournamentFactory` (typically the Cartesi *MultiLevelTournamentFactory*) to spawn a new **TopTournament** at the start of each epoch. Each dispute is handled by a multi‐stage “tournament” on-chain: the TopTournament coordinates bisection of a disputed computation trace, while BottomTournament contracts handle the final step-by-step verification by calling the on-chain Cartesi machine verifier (CartesiStateTransition) for a single contested instruction. All these PRT contracts (TopTournament, BottomTournament, factory) are part of Cartesi’s `prt-contracts` library and are invoked indirectly via DaveConsensus. The Application itself never needs to know about these; it only interacts with the DaveConsensus contract.
 
 ## Off-Chain Components
 
-The Honeypot uses Cartesi’s Rollups node software with PRT support. This includes:
+The Honeypot uses Cartesi’s Rollups node with PRT support. This includes:
 
-* **PRT Node (Dave) Software:** Anyone can run a node that executes the Honeypot machine (with the provided `honeypot.cpp`) and participates in PRT. The node listens for new inputs from the InputBox on L1, advances the Cartesi machine to compute outputs, and either submits a `settle` call or joins disputes. The Cartesi blog emphasizes that “any node can challenge correctness of computations” and that “honest users inherently help guarantee integrity… anyone can run their own node to validate the PRT Honeypot”.
-* **Output and Input Bridges:** Off-chain, the Honeypot node also communicates with L1 by adding inputs (via the InputBox) and generating outputs (via Voucher calls). The ERC-20 Portal (for CTSI) is used to actually move tokens on L1 when a Voucher output is executed. These portal contracts are standard Cartesi components, used here to deposit CTSI into the Application contract and later withdraw it to a target address.
+#### **Honeypot PRT Node** 
+The Honeypot-PRT node executes the Honeypot Cartesi Machine (with the provided `honeypot.cpp`) and participates in the PRT fraud proof system. The node listens for new inputs from the _InputBox_ contract on L1, advances the Cartesi machine to compute outputs, and either submits a `settle` call or joins disputes. Running the Honeypot node is permissionless and any node can challenge correctness of computations to guarantee the integrity of the rollup.
 
-Behind the scenes, the off-chain node uses a service (the PRT tournament logic) to monitor the on-chain tournament state. It uses `cartesi-rollups-prt-node` or similar that integrates the `cartesi/dave` libraries. This service automatically triggers tournament moves when disputes arise. These off-chain components are separate processes from the Application logic (the latter being purely EVM code). Thus **application logic (the honeypot rules)** lives entirely in the off-chain machine and Application contract, while **fraud-proof logic** lives in the PRT consensus code and off-chain PRT engines.
+:::note Run a Honeypot Node
+Checkout the Honeypot wiki to learn how to run a node that participates in PRT [here](https://github.com/cartesi/honeypot/wiki).
+:::
 
-## Triggering Claims and Disputes
-
-**Submitting Claims (Outputs):** In Cartesi Rollups, outputs are proposed by rollup nodes whenever an epoch is sealed. A node will call `settle(epoch, outputsMerkleRoot, proof)` on DaveConsensus (as shown in) once it believes an epoch’s execution is complete. If the tournament for that epoch has finished (meaning someone won any dispute), `settle` will perform a Merkle‐proof check against the final machine state, then **mark the outputs root as valid** and start the next tournament. Importantly, once DaveConsensus has accepted an outputsMerkleRoot, the Application contract will honor any outputs (vouchers) under that root.
-
-**Dispute Resolution Workflow:** If any validator disagrees with the proposed output for an epoch, they participate in the PRT tournament. That process is largely *off-chain and decentralized*: anyone running a PRT-aware Cartesi node can join the tournament by fetching the current TopTournament contract from DaveConsensus. They then exchange “claims” by making specific function calls on the TopTournament contract (bisecting the execution trace). Each round eliminates half of the false claims. Eventually, the dispute narrows to a single instruction, and a BottomTournament is spawned to resolve that instruction on-chain. We see this in DaveConsensus’s use of `ITournament` and the events emitted at epoch seal. After resolution, any honest validator (or even anyone) can call `settle` on DaveConsensus to finalize the epoch.
-
-## Key Abstractions & Patterns
-
-The integration decouples the fraud-proof system from app logic: the Honeypot Application contract doesn’t import or call any PRT-specific code directly. Instead:
-
-* **Validator Interface:** The use of `IOutputsMerkleRootValidator` is a key abstraction. The Application only depends on this interface, not on DaveConsensus specifically. This means the app logic doesn’t need to know how consensus works, only that outputs will be checked. The owner of the app contract can even replace the validator (with `migrateToOutputsMerkleRootValidator`) if needed.
-* **Modular Fraud-Proof Contracts:** All tournament and proof logic lives in separate contracts (DaveConsensus, ITournamentFactory, Top/Bottom Tournaments, CartesiStateTransition, etc.). The application simply observes their results. Likewise, Merkle and proof utilities are factored into libraries (`LibOutputValidityProof`, `LibMerkle32`, etc.) for reuse.
-* **Epoch-Based Coordination:** DaveConsensus defines clear epoch boundaries and emits an `EpochSealed` event. This event-driven design lets off-chain services (and even users) know exactly when to start a new challenge or accept the results. It cleanly separates “accumulate inputs for epoch” from “finalize epoch” stages.
-* **Standardized Output Formats:** The Honeypot app uses Cartesi’s standard Vouchers (`Outputs.Voucher` and `DelegateCallVoucher`) to drive actions. Because these are part of the Cartesi SDK, the PRT system already understands how to verify them via Merkle proofs.
-
-Together, these patterns ensure the Honeypot’s core logic remains fully isolated from the PRT framework.  The app simply promises to honor any output that DaveConsensus agrees is valid, while DaveConsensus handles all disputes by spawning tournaments and consulting the ultimate on-chain verifier.
+When an epoch is sealed and the node detects that no tournaments remain unresolved, it will call `settle(epoch, outputsMerkleRoot, proof)` on DaveConsensus. This settle call verifies the Merkle proof of the final machine state, records the outputs root as valid, and opens the next epoch to receive inputs. Once DaveConsensus has accepted a root in this way, the Honeypot Application contract will honor any vouchers contained within it, such as withdrawals of deposited tokens.
 
+Under the hood, the Honeypot-PRT node listens to the events emitted by the PRT contracts, and tracks tournament state. When disputes arise, it reacts to those events by issuing the required tournament moves.