cheqd/cheqd-node

1. What this repository is

cheqd-node is the ledger/node implementation for the cheqd network, built on Go, Cosmos SDK, and CometBFT. Architecturally it is a blockchain application rather than a generic service: transactions enter through the node, are validated by ante/post handlers and module message servers, then committed to the chain state.

2. Top-level application boundary

The main application wiring lives in app/ and cmd/cheqd-noded/. cmd/cheqd-noded provides the binary entrypoint and CLI surface, while app/app.go, app/ante.go, app/post.go, app/genesis.go, and related files compose the full chain: module registration, store keys, keepers, genesis initialization, upgrade hooks, and runtime decorators.

3. Core on-chain modules

The repository’s domain logic is concentrated in three custom modules under x/:

- x/did: DID Documents and DID lifecycle

- x/resource: DID-linked resources

- x/oracle: price/oracle and fee-related mechanisms

Each module follows the Cosmos pattern: types, keeper, msg_server, query_server, module.go, client/cli, and tests. This makes each module a clear boundary between protobuf-defined interfaces and stateful keeper logic.

4. DID subsystem

x/did handles creation, update, deactivation, minting/burning, and querying of DID Documents. The types/ package defines DID document structures, messages, query requests, fees, params, and validation rules. The keeper/ layer implements state transitions and versioned DID document storage, while migrations/ and upgrades/ show that this module has evolved through chain upgrades. This is the primary identity layer of the chain.

5. Resource subsystem

x/resource manages on-ledger resources attached to DIDs, such as schemas or other metadata used by identity workflows. It supports create/query flows, metadata, collection queries, and IBC-facing behavior through ibc_module.go. Like DID, it has a clean split between protobuf types, keeper logic, CLI commands, and migration paths. The module is designed to work as a sibling to DID rather than a dependency inside it.

6. Oracle and pricing subsystem

x/oracle provides the economic side of the chain: price feeds, ballots/voting, rewards, slashing, historic prices, deviation thresholds, and proposal-driven configuration. It also exposes ABCI integration under x/oracle/abci, which indicates it contributes to validator vote extensions / end-block processing, not just ordinary transactions. This module is the pricing backbone that supports dynamic fees and other on-chain economic decisions.

7. Fee handling and transaction gating

The ante/ and post/ packages define the transaction pipeline around module execution. ante/ contains decorators and fee checks such as fee bypass logic, fee absorption/burning, global fee validation, and message filtering. post/ contains post-processing such as tax/burn behavior after successful execution. These layers are important because they affect whether a transaction is admitted at all and how fees are redistributed or burned across modules.

8. Runtime data flow

The main path is: external clients use CLI or gRPC → transactions are signed and submitted to the node → ante handlers validate fees and message constraints → the relevant module MsgServer mutates keeper state → post handlers apply additional fee accounting → state is committed by the Cosmos app. Queries follow the inverse path through module query servers and generated gRPC endpoints. This makes app/ the orchestration layer and x/*/keeper the state transition layer.

9. Interfaces exposed to clients

The repo includes generated protobuf and gRPC definitions under proto/ and api/, with generated Go code in api/cheqd/... and x/*/types/*.pb.go. app/client/docs contains Swagger assets for REST/OpenAPI-style access, and each module has client/cli handlers for the command-line interface. The architecture therefore exposes three client surfaces: Cosmos CLI, gRPC/REST APIs, and chain-level transaction/query protobufs.

10. Upgrade and migration story

The presence of app/upgrades/, x/*/migrations/, and network upgrade JSON files under networks/*/upgrades/ shows that schema/state evolution is a first-class concern. The app is designed to coordinate chain upgrades across multiple versions, with module-specific migrations and network-wide upgrade plans. This is a key architectural boundary for a blockchain system because state layout changes must be deterministic across validators.

11. Network and deployment artifacts

docker/ and installer/ support node deployment and local operator workflows. docker/localnet and docker/persistent-chains define reproducible multi-node environments, while installer/installer.py and its templates package OS-level service installation for validators. These are not part of consensus logic, but they define how the runtime is provisioned and operated in the real world.

12. Test architecture

Testing is organized at multiple layers: unit tests near each package, integration tests under tests/integration, module tests under x/*/tests, and upgrade tests under tests/upgrade. There are also scenario-specific test suites for fee absorption, IBC, DID docs, resources, oracle flows, and chain upgrades. This indicates the repository validates both isolated keeper behavior and end-to-end chain behavior with Docker-based networks.

13. Utility and shared code

util/ contains reusable helpers that cut across modules: byte/string helpers, decimal math, coin math, reward logic, metrics, simulation utilities, and generic code generators/checkers. These are support libraries rather than architectural owners, but they reduce duplication across the custom modules and testing code.

14. How to draw the architecture

A good diagram would center on the Cosmos application container in app/, with three primary module boxes (x/did, x/resource, x/oracle) connected to shared fee/ante/post processing and to protobuf/gRPC/CLI interfaces. Around that, show upgrade/migration flows from network plans into the app, and deployment/test tooling as outer operational layers. The most important internal boundary is between interface definitions in types/ and stateful execution in keeper/, because that is where the chain’s contract and persistence meet.