# piplabs/story architecture

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

- Interactive diagram: https://gitdiagram.com/piplabs/story
- Repository: https://github.com/piplabs/story

## Overview

##### Project Type and Purpose
- This is a Go-based blockchain client (“story”) implementing a consensus layer (Cosmos SDK + CometBFT) plus staking & minting modules, decoupled from the execution (EVM) client.
- The codebase includes:
- client/ – consensus client binary, ABCI++ adapter, Cosmos SDK modules (EVM engine, staking, mint)
- contracts/ – Solidity smart contracts and Foundry scripts
- lib/ – shared libraries (logging, crypto, network config, etc.)
- client/proto & client/server – Protobuf definitions and HTTP/gRPC API server

##### File Structure Analysis
- Top-level folders:
- client/ – main Go application (app, cmd, genutil, comet integration, x/* modules)
- contracts/ – smart contracts, bindings, tests, build config
- lib/ – utilities and common packages
- scripts/ – dev tooling (protoc, build, test, Docker)
- Key files:
- client/app – ABCI++ application wiring Cosmos SDK modules
- client/cmd – CLI commands (init, run, validator, status)
- client/x/evmengine, evmstaking, mint – Cosmos SDK modules
- client/proto & client/server – API definitions & HTTP/gRPC handlers
- Dockerfile, Makefile – build and release pipelines

##### README Insights
- Architecture: execution client ↔ consensus client via Engine ABI + ABCI++
- Technologies: Go 1.22+, Cosmos SDK, CometBFT, EVM (geth), Protobuf, gRPC, Foundry (contracts)
- Components: CLI, consensus engine, EVM engine adapter, P2P network, config & data dirs

1) Execution Client (“story-geth” / geth)
2) Consensus Client (“story” binary)
- CLI & config loader
- ABCI++ adapter (Engine ABI connector)
- Cosmos SDK modules:
- x/evmengine (EVM state & block execution)
- x/evmstaking (staking logic)
- x/mint (token minting)
- CometBFT consensus engine (integrated)
- Storage (levelDB/state DB, snapshots)
- API Server (HTTP/gRPC) – client/server package
3) P2P Network (CometBFT peers & seed nodes)
4) External Clients (wallets, explorers) via JSON-RPC & REST
5) Solidity Contracts & Deployment Scripts (external, off-chain toolchain)

- geth → (Engine API + JWT over HTTP) → ABCI++ adapter
- ABCI++ adapter ↔ x/evmengine module (EVM block & state queries)
- x/evmengine, evmstaking, mint modules → (write/read) → state DB
- cosmos-sdk modules → CometBFT core (consensus messages)
- CometBFT core ↔ peer nodes (P2P gossip)
- CLI commands → internal App (init, run, migrate upgrades)
- API Server → modules (serve REST/gRPC endpoints) → external clients

c. Architectural Patterns & Principles
- Layered separation: Execution layer vs. Consensus layer vs. Application modules
- Cosmos SDK modularity: each x/* folder is a pluggable module
- ABCI++ adapter: decouples EVM execution from CometBFT consensus
- Protobuf + gRPC: strong-typed API definitions
- CLI + config templating: reproducible network init & upgrades

d. Key Technologies & Frameworks
- Go (language), Go modules
- Cosmos SDK, CometBFT (Tendermint)
- EVM Engine Adapter (Engine ABI, ABCI++)
- Protobuf, gRPC, buf tooling (client/proto)
- Foundry, Slither, Mythril for smart contracts
- Docker, Makefile, GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    Geth["Execution Client (geth)"]:::external
    ExtClient["External Clients (wallets, explorers)"]:::external
    P2P["P2P Network (CometBFT peers)"]:::external
    Lib["Shared Libraries & Utilities"]:::external
    subgraph "Off-chain Toolchain"
        Scripts["Dev Scripts"]:::tooling
        Contracts["Smart Contracts & Foundry"]:::tooling
    end

    %% Consensus Client Components
    subgraph "Consensus Client (story)"
        CLI["CLI & Commands"]:::consensus
        Config["Config Loader & Templates"]:::consensus
        Adapter["ABCI++ Adapter (Engine ABI)"]:::consensus
        AppWiring["Core Application Wiring"]:::consensus
        subgraph "Cosmos SDK Modules"
            EVM["x/evmengine"]:::module
            Stake["x/evmstaking"]:::module
            Mint["x/mint"]:::module
        end
        Comet["CometBFT Engine"]:::consensus
        Storage["LevelDB / State DB"]:::storage
        APIServer["API Server (HTTP & gRPC)"]:::api
    end

    %% Connections
    Geth -->|"Engine API (HTTP+JWT)"| Adapter
    Adapter -->|"state & block queries"| EVM

    CLI -->|“runs”| AppWiring
    Config -->|“loads”| CLI

    AppWiring -->|“init modules”| EVM
    AppWiring -->|“init modules”| Stake
    AppWiring -->|“init modules”| Mint
    AppWiring -->|“starts”| Comet

    EVM -->|"read/write"| Storage
    Stake -->|"read/write"| Storage
    Mint -->|"read/write"| Storage

    EVM -->|"consensus msgs"| Comet
    Stake -->|"consensus msgs"| Comet
    Mint -->|"consensus msgs"| Comet

    Comet -->|"gossip"| P2P
    P2P -->|"gossip"| Comet

    APIServer -->|"serve endpoints"| EVM
    APIServer -->|"serve endpoints"| Stake
    APIServer -->|"serve endpoints"| Mint
    ExtClient -->|“REST/gRPC calls”| APIServer

    Lib -.-> AppWiring
    Lib -.-> EVM
    Lib -.-> Stake
    Lib -.-> Mint
    Lib -.-> Adapter

    Scripts --> Contracts
    Contracts -->|"deploy & ABI"| Geth

    %% Click Events
    click CLI "https://github.com/piplabs/story/tree/main/client/cmd"
    click Config "https://github.com/piplabs/story/tree/main/client/config"
    click Adapter "https://github.com/piplabs/story/blob/main/client/app/abci.go"
    click AppWiring "https://github.com/piplabs/story/blob/main/client/app/app.go"
    click Comet "https://github.com/piplabs/story/blob/main/client/comet/comet.go"
    click EVM "https://github.com/piplabs/story/tree/main/client/x/evmengine"
    click Stake "https://github.com/piplabs/story/tree/main/client/x/evmstaking"
    click Mint "https://github.com/piplabs/story/tree/main/client/x/mint"
    click APIServer "https://github.com/piplabs/story/tree/main/client/server"
    click Lib "https://github.com/piplabs/story/tree/main/lib/"
    click Contracts "https://github.com/piplabs/story/tree/main/contracts/"
    click Scripts "https://github.com/piplabs/story/tree/main/scripts/"

    %% Styling
    classDef external fill:#fde2e2,stroke:#b02a37,stroke-width:1px
    classDef consensus fill:#e0f7fa,stroke:#006064,stroke-width:1px
    classDef module fill:#e8f5e9,stroke:#2e7d32,stroke-width:1px
    classDef storage fill:#fff3e0,stroke:#ef6c00,stroke-width:1px
    classDef api fill:#f3e5f5,stroke:#6a1b9a,stroke-width:1px
    classDef tooling fill:#fbe9e7,stroke:#bf360c,stroke-width:1px
```
