flowchart TB
    subgraph External["External Systems"]
        BTC["Bitcoin Network"]
        GOAT["GOAT L2 Chain"]
        PB["Proof Builder RPC"]
    end

    subgraph Node["bitvm-noded"]
        subgraph Input["Input Layer"]
            EW["Event Watch Task"]
            P2P["P2P Swarm (libp2p)"]
            RPC["RPC Service (Axum)"]
        end

        subgraph Core["Core Processing"]
            MH["Message Handler"]
            DISP["Role Dispatcher"]
        end

        subgraph Tasks["Background Tasks"]
            GM["Graph Maintenance"]
            IM["Instance Maintenance"]
            NM["Node Maintenance"]
            SPV["SPV Maintenance"]
        end

        subgraph Storage["Persistence Layer"]
            DB[(SQLite Database)]
            GD[("graph_raw_data\n(Graph JSON)")]
            GM_TBL[("graph\n(Metadata)")]
        end
    end

    BTC --> EW
    GOAT --> EW
    EW --> MH
    P2P --> MH
    RPC --> MH
    MH --> DISP
    DISP --> GM
    DISP --> IM
    GM --> DB
    IM --> DB
    NM --> DB
    SPV --> DB
    GM --> GD
    GM --> GM_TBL
    GM --> PB

flowchart LR
    subgraph Actors["Actor Roles"]
        C["Committee"]
        O["Operator"]
        V["Verifier"]
        W["Watchtower"]
        R["Relayer\n(Committee + Flag)"]
    end

    subgraph Network["P2P Topics"]
        TC["/goat/topic/Committee"]
        TO["/goat/topic/Operator"]
        TV["/goat/topic/Verifier"]
        TW["/goat/topic/Watchtower"]
        TA["/goat/topic/All"]
    end

    C <--> TC
    O <--> TO
    V <--> TV
    W <--> TW
    C & O & V & W & R <--> TA
    R -.->|"SyncGraph"| TA

classDiagram
    class Actor {
        <<enumeration>>
        Committee
        Operator
        Verifier
        Watchtower
        All
    }

    class Committee {
        +generate_nonces()
        +presign_transactions()
        +endorse_graph()
        +confirm_pegin()
    }

    class Operator {
        +create_graph()
        +push_data_to_l2()
        +broadcast_kickoff()
        +send_take1_take2()
    }

    class Verifier {
        +monitor_timeouts()
        +submit_disprove()
    }

    class Watchtower {
        +monitor_block_headers()
        +submit_challenge()
        +ack_nack_response()
    }

    class Relayer {
        +respond_sync_request()
        +distribute_graph_data()
        +cache_all_graphs()
    }

    Actor <|-- Committee
    Actor <|-- Operator
    Actor <|-- Verifier
    Actor <|-- Watchtower
    Committee <|-- Relayer : ENABLE_RELAYER=true

sequenceDiagram
    autonumber
    participant User
    participant GOAT as GOAT L2
    participant EW as Event Watch
    participant Committee
    participant Operator
    participant BTC as Bitcoin
    participant DB as SQLite DB

    User->>GOAT: Initiate BridgeInRequest
    GOAT-->>EW: Trigger BridgeInRequest event
    EW->>Committee: PeginRequest message

    Committee->>Committee: Validate fees and availability
    Committee->>Operator: ConfirmInstance

    Operator->>Operator: Create SimplifiedbitvmGraph
    Operator->>DB: Store graph_raw_data (JSON)
    Operator->>Committee: CreateGraph (with graph data)

    loop Multi-sig rounds
        Committee->>Committee: NonceGeneration
        Committee->>Committee: CommitteePresign
    end

    Committee->>Operator: EndorseGraph (graph endorsement)
    Operator->>GOAT: PostGraphData
    Operator->>BTC: Broadcast PreKickoff transaction
    BTC-->>EW: PreKickoff confirmed

    Note over User,DB: Peg-in complete, user receives assets on L2

stateDiagram-v2
    [*] --> UserIniting: User initiates request
    UserIniting --> UserInited: Event detected
    UserInited --> CommitteesAnswered: Enough committee responses
    UserInited --> NoEnoughCommitteesAnswered: Window timeout
    UserInited --> UserDiscarded: UTXO spent

    CommitteesAnswered --> UserBroadcastPeginPrepare: User broadcasts
    UserBroadcastPeginPrepare --> Presigned: All committees signed
    UserBroadcastPeginPrepare --> PresignedFailed: Signing failed

    Presigned --> RelayerL1Broadcasted: Relayer broadcasts
    RelayerL1Broadcasted --> RelayerL2Minted: L2 minting success
    RelayerL1Broadcasted --> RelayerL2MintedFailed: L2 minting failed

    UserBroadcastPeginPrepare --> Timeout: Timeout
    Timeout --> UserCanceled: User cancels

    RelayerL2Minted --> [*]
    UserCanceled --> [*]

sequenceDiagram
    autonumber
    participant User
    participant GOAT as GOAT L2
    participant Operator
    participant BTC as Bitcoin

    User->>GOAT: InitWithdraw (withdrawal request)
    GOAT-->>Operator: Withdrawal event detected

    Operator->>BTC: Broadcast Kickoff transaction
    Note over Operator,BTC: Wait for Timelock expiry

    alt No challenge (Happy Path)
        Operator->>BTC: Broadcast Take1 transaction
        BTC->>User: BTC transferred to user address
    end

sequenceDiagram
    autonumber
    participant User
    participant GOAT as GOAT L2
    participant Operator
    participant Watchtower
    participant Verifier
    participant BTC as Bitcoin

    User->>GOAT: InitWithdraw
    Operator->>BTC: Kickoff transaction

    rect rgb(255, 240, 240)
        Note over Operator,Watchtower: Challenge Phase
        Operator->>BTC: WatchtowerChallengeInitTx

        loop For each Watchtower index
            Watchtower->>BTC: WatchtowerChallengeTx
            alt Operator accepts
                Operator->>BTC: ACK response
            else Operator rejects
                Operator->>BTC: NACK response
                Verifier->>BTC: DisproveTx
            end
        end

        Operator->>BTC: CommitBlockHashTx
        Operator->>BTC: AssertInitTx
        Operator->>BTC: AssertCommitTx
    end

    alt All challenges passed
        Operator->>BTC: Take2 transaction
        BTC->>User: BTC transferred to user address
    else Challenge failed
        Verifier->>BTC: DisproveTx
        Note over User,BTC: User funds safe, Operator penalized
    end

flowchart TB
    subgraph WTC["Watchtower Challenge Phase"]
        WTC1["OperatorInit"] --> WTC2{"Watchtower response?"}
        WTC2 -->|"Submit challenge"| WTC3["Challenge"]
        WTC2 -->|"Timeout"| WTC4["ChallengeTimeout"]
        WTC3 --> WTC5{"Operator response?"}
        WTC5 -->|"ACK"| WTC6["OperatorACK"]
        WTC5 -->|"NACK"| WTC7["OperatorNACK"]
        WTC5 -->|"Timeout"| WTC8["ACKTimeout"]
    end

    subgraph CBH["CommitBlockHash Phase"]
        CBH1["WatchtowerChallengeProcessed"]
        CBH2["OperatorCommit"]
        CBH3["OperatorCommitTimeout"]
        CBH1 --> CBH2
        CBH1 --> CBH3
    end

    subgraph AC["Assert Commit Phase"]
        AC1["OperatorInit"]
        AC2["OperatorCommit"]
        AC3["OperatorCommitTimeout"]
        AC1 --> AC2
        AC1 --> AC3
    end

    WTC6 --> CBH1
    CBH2 --> AC1
    AC2 --> TAKE2["Take2 Success"]

    WTC4 & WTC7 & WTC8 & CBH3 & AC3 --> DISP["Disprove"]

stateDiagram-v2
    [*] --> OperatorPresigned: Operator creates graph

    OperatorPresigned --> CommitteePresigned: Collected enough committee signatures
    OperatorPresigned --> Obsoleted: PreKickoff on-chain but data not posted

    CommitteePresigned --> OperatorDataPushed: Operator pushes L2 data
    CommitteePresigned --> Obsoleted: PreKickoff on-chain but data not posted

    OperatorDataPushed --> PreKickoff: PreKickoff tx confirmed
    OperatorDataPushed --> Obsoleted: Pegin not withdrawable and no withdrawal request

    PreKickoff --> OperatorKickOff: Kickoff tx broadcast
    PreKickoff --> Skipped: Guardian intervention or force skip

    Obsoleted --> OperatorKickOff: Kickoff tx observed on-chain after all
    Obsoleted --> Skipped: Guardian intervention or force skip

    OperatorKickOff --> OperatorTake1: Timelock expired without challenge
    OperatorKickOff --> Challenge: WatchtowerChallengeInit confirmed
    OperatorKickOff --> Disprove: Guardian disprove detected before any Challenge opened

    Challenge --> OperatorTake2: Take2 tx confirmed and no disprove detected
    Challenge --> Disprove: Guardian disprove, watchtower-flow disprove, verifier disprove, or unrecognized connector-D spend

    OperatorTake1 --> [*]: Happy Path complete
    OperatorTake2 --> [*]: Challenge Path complete
    Skipped --> [*]: Graph skipped
    Disprove --> [*]: Dispute resolved

flowchart TB
    subgraph Storage["SQLite Database"]
        GT[("graph table\n(Metadata, TxIDs, Status)")]
        GRD[("graph_raw_data table\n(Serialized JSON)")]
    end

    subgraph Operations["Graph Operations"]
        CREATE["store_graph()"]
        READ["get_graph()"]
        PARSE["parse_graph_raw_data()"]
        SERIALIZE["serialize_graph_raw_data()"]
    end

    subgraph P2P["P2P Synchronization"]
        REQ["SyncGraphRequest"]
        RESP["SyncGraph"]
        RELAY["Relayer Nodes"]
    end

    CREATE -->|"Atomic Transaction"| GT
    CREATE -->|"JSON Serialization"| GRD
    READ --> GT
    READ --> GRD
    PARSE -->|"spawn_blocking"| GRD
    SERIALIZE -->|"spawn_blocking"| GRD

    REQ -->|"Broadcast to All"| RELAY
    RELAY -->|"Lookup Local DB"| GRD
    RELAY -->|"Respond with Graph"| RESP

sequenceDiagram
    autonumber
    participant NodeA as Node A (Missing Graph)
    participant P2P as P2P Network
    participant Relayer as Relayer Node
    participant DB as Relayer DB

    NodeA->>NodeA: Check local DB for graph
    Note over NodeA: Graph NOT FOUND

    NodeA->>P2P: SyncGraphRequest(instance_id, graph_id)
    P2P->>Relayer: Broadcast to All topic

    Relayer->>Relayer: is_relayer() check
    Note over Relayer: ENABLE_RELAYER=true

    Relayer->>DB: Query graph_raw_data
    DB-->>Relayer: Return serialized graph

    Relayer->>P2P: SyncGraph(instance_id, graph_id, graph_data)
    P2P->>NodeA: Deliver response

    NodeA->>NodeA: Validate graph_id on GOAT chain
    NodeA->>NodeA: store_graph() locally
    Note over NodeA: Graph synchronized!

classDiagram
    class GOATMessage {
        +Actor actor
        +GOATMessageContent content
        +serialize_message() Vec~u8~
        +deserialize_message() GOATMessage
    }

    class GOATMessageContent {
        <<enumeration>>
        PeginRequest
        CreateGraph
        ConfirmInstance
        NonceGeneration
        CommitteePresign
        EndorseGraph
        GraphFinalize
        KickoffReady
        KickoffSent
        ChallengeSent
        DisproveReady
        DisproveSent
        Take1Sent
        Take2Sent
        SyncGraphRequest
        SyncGraph
        ...
    }

    class Actor {
        <<enumeration>>
        Committee
        Operator
        Verifier
        Watchtower
        All
    }

    GOATMessage --> Actor : target
    GOATMessage --> GOATMessageContent : payload

flowchart TB
    subgraph EventWatch["Event Watch Task (Continuous)"]
        EW1["fetch_and_handle_gateway_events"]
        EW2["fetch_and_handle_bridge_out_events"]
        EW1 --> MSG1["PeginRequest"]
        EW2 --> MSG2["InitWithdraw detection"]
    end

    subgraph GraphMaint["Graph Maintenance (20s interval)"]
        GM1["detect_init_withdraw_call"]
        GM2["detect_kickoff"]
        GM3["detect_take1_or_challenge"]
        GM4["process_graph_challenge"]

        GM1 -->|"KickoffReady"| GM2
        GM2 -->|"Status update"| GM3
        GM3 -->|"Challenge"| GM4
        GM3 -->|"Take1Ready"| T1["Take1 processing"]
        GM4 -->|"Take2Ready"| T2["Take2 processing"]
        GM4 -->|"DisproveReady"| DP["Disprove processing"]
    end

    subgraph InstMaint["Instance Maintenance (20s interval)"]
        IM1["instance_answers_monitor"]
        IM2["instance_window_expiration_monitor"]
        IM3["instance_btc_tx_monitor"]
        IM4["instance_bridge_out_monitor"]
        IM5["instance_committee_key_cleanup_monitor"]
    end

    subgraph Other["Other Tasks"]
        NM["Node Maintenance"]
        SPV["SPV Header Updates"]
    end

    EventWatch --> GraphMaint
    GraphMaint --> InstMaint