# risc0/kailua architecture

> Architecture diagram of the GitHub repository risc0/kailua, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/risc0/kailua
- Repository: https://github.com/risc0/kailua

## Overview

##### Project Type and Purpose
- Kailua is a hybrid on-chain/off-chain rollup fault-proving system that uses RISC-Zero zkVM proofs to finalize or dismiss rollup outputs.
- The on-chain environment lives in `crates/contracts/foundry/src` and contains the Solidity contracts (the “Dispute Game” factory and game logic) that govern proposer/validator interactions, collateral, and proof verification.

##### Key On-Chain Components to Model
a. DisputeGameFactory
- Deploys new instances of KailuaGame.
- Holds global configuration (timeouts, collateral parameters).
- Tracks active game instances.
b. KailuaGame (Fault Proof Contract)
- Manages a single dispute:
- Proposer calls `propose()` to submit a new output.
- Challenger calls `challenge()` to lock collateral and start a dispute.
- Either party submits a zkVM proof via `submitProof()` (off-chain computed by RISC-Zero).
- `finalize()` or `dismiss()` is called based on proof validity.
- Enforces collateral lockup and slashing rules.
c. ERC-20 Collateral Token (if used; could be ETH/wrapped ETH)
- Abstract as a “Collateral Vault” component.
d. zkVM Verifier Library
- Imported or embedded in the game contract to verify proofs on-chain.

##### External Systems and Off-Chain Actors
- Proposer Agent (CLI in `bin/cli`)
- Watches OP Stack devnet.
- Calls factory/game contracts to propose outputs.
- Computes proofs when challenged.
- Validator Agent (CLI in `bin/cli` or `bin/host`)
- Detects disputes.
- Calls game contract to challenge and submit proofs.
- RISC-Zero zkVM
- Runs Kona VM execution traces.
- Generates SNARKs or proof artifacts.
- Interacts off-chain with contracts via JSON-RPC.

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef onchain fill:#cceeff,stroke:#333,stroke-width:2px;
    classDef db fill:#ffeb99,stroke:#333,stroke-width:2px;
    subgraph "Ethereum Network"
        direction TB
        DGF["DisputeGameFactory\n• deployGame()\n• setConfig()\n• events: GameDeployed"]:::onchain
        KG["KailuaGame\n• propose(outputData, collateral)\n• challenge(gameId, collateral)\n• submitProof(proofBlob)\n• finalize()\n• dismiss()\n• events: DisputeCreated, ProofSubmitted"]:::onchain
        CV["Collateral Vault\n• lockCollateral()\n• slashCollateral()\n• transfer()"]:::db
        VLIB["Verifier Library\n• verifyProof(proofBlob)"]:::onchain
    end

    DGF -->|"deployGame()"| KG
    KG -->|"lockCollateral() / slashCollateral()"| CV
    KG -->|"verifyProof()"| VLIB

    click DGF "https://github.com/risc0/kailua/blob/main/crates/contracts/foundry/src/DisputeGameFactory.sol"
    click KG "https://github.com/risc0/kailua/blob/main/crates/contracts/foundry/src/KailuaGame.sol"
    click CV "https://github.com/risc0/kailua/blob/main/crates/contracts/foundry/src/CollateralVault.sol"
    click VLIB "https://github.com/risc0/kailua/blob/main/crates/contracts/foundry/src/vendor/Verifier.sol"
```
