How piplabs/story works
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