# zorp-corp/nockchain architecture

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

- Interactive diagram: https://gitdiagram.com/zorp-corp/nockchain
- Repository: https://github.com/zorp-corp/nockchain

## Overview

##### Project Type and Purpose
- Nockchain is an open‐source, Rust‐based lightweight blockchain node plus tooling suite, augmented by Hoon smart‐contract code and ZK-proof components. Its goal is on-chain verification of off-chain proofs, supporting verifiable computation and lightweight consensus.

##### File‐Structure Analysis
- Top‐level crates/ directory holds a federation of Rust packages:
- crates/nockchain           → core node logic (consensus, block processing)
- crates/nockchain-libp2p-io → P2P networking layer (libp2p abstractions, metrics)
- crates/nockchain-bitcoin-sync → Bitcoin‐block synchronization as an external data oracle
- crates/wallet              → CLI wallet for transaction creation and node interaction
- crates/nockapp             → Hoon runtime host, app bootstrap, driver plugins
- crates/sword & crates/zkvm-jetpack → Nock interpreter/JIT (“Sword”), ZK-VM kernels and jets
- crates/kernels, crates/equix-latency → performance kernels and measurement binaries
- hoon/ directory contains pure‐Hoon source: smart contracts, common libraries, proofs, test-jams.
- Key build scripts and toolchain files: Makefile orchestrates choo (Hoon compiler) → Rust code generation, Cargo.toml for each crate, nested-workspace.toml for Hoon→Rust integration.

##### README Insights
- Workflow:
a. Install choo to compile Hoon code → Rust lib crates under crates/nockapp and hoon/common, hoon/apps
b. Cargo build assembles all Rust crates
c. make run-nockchain-{leader,follower} launches node roles
d. Wallet CLI uses main.rs in crates/wallet to send RPCs to the node
- Off-chain proving: Sword and zkvm-jetpack perform private proofs; crown kernel in nockapp handles on-chain verification.

a. Main Components
- Wallet CLI (crates/wallet)
- Node Core (crates/nockchain)
- P2P Layer (crates/nockchain-libp2p-io)
- Bitcoin‐Sync Oracle (crates/nockchain-bitcoin-sync)
- Hoon Runtime Host (crates/nockapp → crown kernel + drivers)
- Nock Interpreter & ZK-VM (crates/sword, crates/zkvm-jetpack)
- Performance Kernels & Metrics (crates/kernels, crates/equix-latency)
- Persistent Storage (e.g., on-chain database)
- External Services: Bitcoin blockchain network, libp2p peers
b. Relationships & Data Flow
1. Wallet → HTTP/RPC → Node Core
2. Node Core ↔ P2P Layer ↔ Other Peers
3. Node Core → Storage (blocks, chain state)
4. Node Core → Bitcoin-Sync → Bitcoin network
5. Node Core → Hoon Runtime Host (load compiled Hoon smart contracts)
6. Hoon Runtime → Sword & ZK-VM (run/verify proofs)
7. Performance Kernels invoked by Node Core for benchmarking/metrics
c. Architectural Patterns
- Layered modular architecture: CLI, Node Core, Network, Runtime, VM
- Plugin/driver pattern in crown kernel (nockapp/crown/src/drivers)
- Code‐generation pipeline: Hoon → choo → Rust crates → Cargo build
- Off‐chain proving → on‐chain verification separation
d. Technologies & Frameworks
- Rust + Cargo
- libp2p for networking
- choo Hoon compiler
- Nock smart‐contract language (Hoon)
- ZK‐proof VM (zkvm-jetpack)
- Sword Nock interpreter
- Makefile orchestration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "CLI Layer"
        direction TB
        WalletCLI["Wallet CLI"]:::rust
    end

    subgraph "Node Core Layer"
        direction TB
        NodeCore["nockchain (Node Core)"]:::rust
        P2PLayer["nockchain-libp2p-io (P2P Layer)"]:::rust
        BitcoinSync["nockchain-bitcoin-sync (Bitcoin-Sync Oracle)"]:::rust
    end

    subgraph "Runtime & Hoon Layer"
        direction TB
        HoonRuntime["nockapp/crown (Hoon Runtime Host)"]:::hoon
        HoonApps["nockapp/apps/choo (Hoon Apps Pipeline)"]:::hoon
        HoonCommon["hoon/common & hoon/apps"]:::hoon
    end

    subgraph "VM Layer"
        direction TB
        Sword["sword (Nock Interpreter)"]:::zk
        ZKVM["zkvm-jetpack (ZK-VM Kernels)"]:::zk
    end

    subgraph "Performance Layer"
        direction TB
        Kernels["kernels (Performance Kernels)"]:::rust
        Latency["equix-latency (Benchmark Metrics)"]:::rust
    end

    subgraph "External & Storage"
        direction TB
        Storage["Block DB (Persistent Storage)"]:::storage
        BitcoinNet["Bitcoin Network"]:::external
        Libp2pPeers["libp2p Peers"]:::external
    end

    %% Data Flows
    WalletCLI -->|"HTTP/RPC"| NodeCore
    NodeCore -->|gossip| P2PLayer
    P2PLayer -->|gossip| Libp2pPeers
    NodeCore -->|sync| BitcoinSync
    BitcoinSync -->|blocks| BitcoinNet
    NodeCore -->|read/write| Storage
    NodeCore -->|load contracts| HoonRuntime
    HoonRuntime -->|invoke| Sword
    HoonRuntime -->|verify proofs| ZKVM
    NodeCore -->|benchmark| Kernels
    NodeCore -->|metrics| Latency

    %% Compile-time pipeline
    HoonCommon -.->|compile via choo| HoonApps

    %% Click Events
    click WalletCLI "https://github.com/zorp-corp/nockchain/blob/master/crates/wallet/src/main.rs"
    click NodeCore "https://github.com/zorp-corp/nockchain/blob/master/crates/nockchain/src/main.rs"
    click P2PLayer "https://github.com/zorp-corp/nockchain/blob/master/crates/nockchain-libp2p-io/src/lib.rs"
    click P2PLayer "https://github.com/zorp-corp/nockchain/blob/master/crates/nockchain-libp2p-io/src/p2p.rs"
    click BitcoinSync "https://github.com/zorp-corp/nockchain/blob/master/crates/nockchain-bitcoin-sync/src/main.rs"
    click HoonRuntime "https://github.com/zorp-corp/nockchain/blob/master/crates/nockapp/crown/src/lib.rs"
    click HoonRuntime "https://github.com/zorp-corp/nockchain/tree/master/crates/nockapp/crown/src/drivers/"
    click HoonApps "https://github.com/zorp-corp/nockchain/blob/master/crates/nockapp/apps/choo/bootstrap/kernel.hoon"
    click HoonApps "https://github.com/zorp-corp/nockchain/blob/master/crates/nockapp/apps/choo/src/main.rs"
    click Sword "https://github.com/zorp-corp/nockchain/blob/master/crates/sword/rust/sword/src/interpreter.rs"
    click ZKVM "https://github.com/zorp-corp/nockchain/blob/master/crates/zkvm-jetpack/src/lib.rs"
    click ZKVM "https://github.com/zorp-corp/nockchain/tree/master/crates/zkvm-jetpack/src/jets/"
    click Kernels "https://github.com/zorp-corp/nockchain/blob/master/crates/kernels/src/lib.rs"
    click Kernels "https://github.com/zorp-corp/nockchain/blob/master/crates/kernels/src/wallet.rs"
    click Latency "https://github.com/zorp-corp/nockchain/blob/master/crates/equix-latency/src/main.rs"
    click HoonCommon "https://github.com/zorp-corp/nockchain/tree/master/hoon/common/"
    click HoonCommon "https://github.com/zorp-corp/nockchain/tree/master/hoon/apps/"

    %% Styles
    classDef rust fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef hoon fill:#E6FFDD,stroke:#28a745,color:#28a745;
    classDef zk fill:#FFE8CC,stroke:#d73a49,color:#d73a49;
    classDef external fill:#F0F0F0,stroke:#6a737d,color:#6a737d;
    classDef storage fill:#FFF5B1,stroke:#735C0F,color:#735C0F;
```
