How ggezlabs/ggezchain works
Project Type & Purpose
• This is a full-stack blockchain application built with the Cosmos SDK (Go) and Tendermint, aiming to tokenize real-world assets for ReFi.
• Core features include on-chain modules (ACL, Trade, IBC, bank, gov, staking, wasm), a custom application binary (ggezchaind), Protobuf/gRPC APIs, CLI, tests, docs, and CI/CD.
Main Components
a. Node & Application Layer
• Tendermint Consensus Engine (ABCI server)
• Cosmos SDK-based application (app/app.go, app/ante.go, modules under x/…)
• Modules: ACL, Trade, IBC, WASM, plus standard Cosmos modules (bank, distribution, gov, staking, slashing, evidence, vesting)
• State Store: BoltDB/LevelDB KV stores managed by each module
b. API Layer
• gRPC services auto-generated from proto/ definitions (query, tx)
• gRPC Gateway / REST endpoints (OpenAPI spec under docs/static/openapi.yml)
• CLI (cmd/ggezchaind) invoking gRPC/RPC methods
c. Protobuf Definitions & Codegen
• proto/ directory with .proto files for each module
• Codegen config via Buf (buf.yaml, buf.gen.*.yaml) producing Go, Pulsar, Swagger, TypeScript clients
• api/ggezchain contains Pulsar-generated code
d. Client Tools & Scripts
• Dockerfile & Makefile for build/release (.github/workflows/release.yml, goreleaser.yaml)
• Helper scripts (scripts/) for linting, mock generation
e. Testing
• Unit/integration tests in x/…/keeper, tests/integrations, tests/e2e
• Simulation tests in app/sim_… and module simulation code under x/…/simulation
Relationships & Data Flow
• Consensus <→ Application: Tendermint delivers transactions via ABCI to the app.
• CLI/API → Node:
• CLI invokes gRPC/RPC endpoints on ggezchaind.
• REST calls via gRPC-Gateway translate to gRPC methods.
• Module Interactions:
• AnteHandler (fee checks, auth) → each module’s handler → state updates
• IBC module handles cross-chain packets → other modules may respond
• State Persistence: Each module has its own KV store namespace, all stored in a single underlying DB.
• Protobuf Codegen: .proto → generated Go/Pulsar/TS code → used by CLI, API, modules.
Architectural Patterns & Design Principles
• Modular Architecture: Each feature isolated in its own Cosmos SDK module under x/…, promoting separation of concerns, pluggability, and testability.
• Layered Design:
• Network/Consensus (Tendermint)
• Application (ABCI + SDK modules)
• API/CLI (gRPC, REST, Pulsar pub/sub)
• Codegen-Driven: Centralized Protobuf definitions ensure consistency across client/server and reduce manual wiring.
• Plugin Pattern: Modules register message handlers, query services, simulation hooks at app initialization (app/module.go, x/…/module.go).
• CI/CD Pipeline: Automated release (GitHub Actions + GoReleaser), linting, mockgen in scripts.