# cheqd/cheqd-node architecture

> Architecture diagram of the GitHub repository cheqd/cheqd-node, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cheqd/cheqd-node
- Repository: https://github.com/cheqd/cheqd-node

## Overview

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.

Main entry points: [`app/app.go`](https://github.com/cheqd/cheqd-node/blob/main/app/app.go) (App wiring), [`x/resource/keeper/keeper.go`](https://github.com/cheqd/cheqd-node/blob/main/x/resource/keeper/keeper.go) (Resource keeper), [`x/did/client/cli/tx.go`](https://github.com/cheqd/cheqd-node/blob/main/x/did/client/cli/tx.go) (Module CLI), [`tests/integration/integration_suite_test.go`](https://github.com/cheqd/cheqd-node/blob/main/tests/integration/integration_suite_test.go) (Integration tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_cmd_entry["Node binary<br/>CLI entrypoint<br/>[main.go]"]
  node_cmd_root["Root CLI<br/>cobra commands<br/>[root.go]"]
  node_app_container["App wiring<br/>Cosmos app<br/>[app.go]"]
  node_app_ante["Ante stack<br/>tx pre-check<br/>[ante.go]"]
  node_post_handler["Post stack<br/>tx post-check<br/>[post.go]"]
  node_app_upgrade["Upgrades<br/>versioned migration<br/>[const.go]"]
end

subgraph group_modules["On-chain modules"]
  node_did_types["DID types<br/>proto contracts<br/>[tx.go]"]
  node_did_keeper["DID keeper<br/>state transitions<br/>[keeper.go]"]
  node_did_migrations["DID migrations<br/>schema migration<br/>[migrate.go]"]
  node_resource_types["Resource types<br/>proto contracts<br/>[tx.pb.go]"]
  node_resource_keeper["Resource keeper<br/>state transitions<br/>[keeper.go]"]
  node_resource_ibc["Resource IBC<br/>IBC module<br/>[ibc_module.go]"]
  node_resource_migrations["Resource migrations<br/>schema migration<br/>[migration.go]"]
  node_oracle_types["Oracle types<br/>proto contracts<br/>[tx.pb.go]"]
  node_oracle_keeper["Oracle keeper<br/>state transitions<br/>[keeper.go]"]
  node_oracle_abci["Oracle ABCI<br/>vote extension<br/>[voteextension.go]"]
end

subgraph group_interfaces["Client interfaces"]
  node_proto_api["Proto API<br/>gRPC/REST surface<br/>[tx.proto]"]
  node_module_cli["Module CLI<br/>command surface<br/>[tx.go]"]
  node_swagger_docs["API docs<br/>[swagger.yaml]"]
end

subgraph group_ops["Operations"]
  node_networks["Network plans<br/>upgrade config<br/>[genesis.json]"]
  node_docker_install["Deploy tools<br/>ops tooling"]
  node_tests_suite["Integration tests<br/>end-to-end tests"]
end

node_cmd_entry -->|"starts"| node_cmd_root
node_cmd_root -->|"configures"| node_app_container
node_app_container -->|"uses"| node_app_ante
node_app_container -->|"uses"| node_post_handler
node_app_container -->|"orchestrates"| node_app_upgrade
node_app_container -->|"wires"| node_did_keeper
node_app_container -->|"wires"| node_resource_keeper
node_app_container -->|"wires"| node_oracle_keeper
node_app_container -->|"binds"| node_did_types
node_app_container -->|"binds"| node_resource_types
node_app_container -->|"binds"| node_oracle_types
node_did_keeper -->|"implements"| node_did_types
node_did_keeper -->|"evolves"| node_did_migrations
node_resource_keeper -->|"implements"| node_resource_types
node_resource_keeper -->|"serves"| node_resource_ibc
node_resource_keeper -->|"evolves"| node_resource_migrations
node_oracle_keeper -->|"implements"| node_oracle_types
node_oracle_keeper -->|"feeds"| node_oracle_abci
node_proto_api -->|"generates"| node_module_cli
node_swagger_docs -->|"documents"| node_proto_api
node_module_cli -->|"targets"| node_did_types
node_module_cli -->|"targets"| node_resource_types
node_module_cli -->|"targets"| node_oracle_types
node_networks -->|"drives"| node_app_upgrade
node_docker_install -->|"runs"| node_cmd_entry
node_tests_suite -->|"exercises"| node_app_container
node_tests_suite -->|"covers"| node_resource_ibc
node_tests_suite -->|"covers"| node_oracle_abci

click node_cmd_entry "https://github.com/cheqd/cheqd-node/blob/main/cmd/cheqd-noded/main.go"
click node_cmd_root "https://github.com/cheqd/cheqd-node/blob/main/cmd/cheqd-noded/cmd/root.go"
click node_app_container "https://github.com/cheqd/cheqd-node/blob/main/app/app.go"
click node_app_ante "https://github.com/cheqd/cheqd-node/blob/main/app/ante.go"
click node_post_handler "https://github.com/cheqd/cheqd-node/blob/main/post/post.go"
click node_app_upgrade "https://github.com/cheqd/cheqd-node/blob/main/app/upgrades/v4/const.go"
click node_did_types "https://github.com/cheqd/cheqd-node/blob/main/x/did/types/tx.go"
click node_did_keeper "https://github.com/cheqd/cheqd-node/blob/main/x/did/keeper/keeper.go"
click node_did_migrations "https://github.com/cheqd/cheqd-node/blob/main/x/did/migrations/v6/migrate.go"
click node_resource_types "https://github.com/cheqd/cheqd-node/blob/main/x/resource/types/tx.pb.go"
click node_resource_keeper "https://github.com/cheqd/cheqd-node/blob/main/x/resource/keeper/keeper.go"
click node_resource_ibc "https://github.com/cheqd/cheqd-node/blob/main/x/resource/ibc_module.go"
click node_resource_migrations "https://github.com/cheqd/cheqd-node/blob/main/x/resource/migration/v5/migration.go"
click node_oracle_types "https://github.com/cheqd/cheqd-node/blob/main/x/oracle/types/tx.pb.go"
click node_oracle_keeper "https://github.com/cheqd/cheqd-node/blob/main/x/oracle/keeper/keeper.go"
click node_oracle_abci "https://github.com/cheqd/cheqd-node/blob/main/x/oracle/abci/voteextension.go"
click node_proto_api "https://github.com/cheqd/cheqd-node/blob/main/proto/cheqd/did/v2/tx.proto"
click node_module_cli "https://github.com/cheqd/cheqd-node/blob/main/x/did/client/cli/tx.go"
click node_swagger_docs "https://github.com/cheqd/cheqd-node/blob/main/app/client/docs/swagger.yaml"
click node_networks "https://github.com/cheqd/cheqd-node/blob/main/networks/mainnet/genesis.json"
click node_docker_install "https://github.com/cheqd/cheqd-node/tree/main/docker/Dockerfile"
click node_tests_suite "https://github.com/cheqd/cheqd-node/blob/main/tests/integration/integration_suite_test.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmd_entry,node_cmd_root,node_app_container,node_app_ante,node_post_handler,node_app_upgrade toneBlue
class node_did_types,node_did_keeper,node_did_migrations,node_resource_types,node_resource_keeper,node_resource_ibc,node_resource_migrations,node_oracle_types,node_oracle_keeper,node_oracle_abci toneAmber
class node_proto_api,node_module_cli,node_swagger_docs toneMint
class node_networks,node_docker_install,node_tests_suite toneRose
```

## Components

### Runtime

Chain application, entrypoint, and transaction pipeline

- [Node binary](https://github.com/cheqd/cheqd-node/blob/main/cmd/cheqd-noded/main.go): CLI entrypoint · Main command and startup wiring · `cmd/cheqd-noded/main.go`
- [Root CLI](https://github.com/cheqd/cheqd-node/blob/main/cmd/cheqd-noded/cmd/root.go): cobra commands · Command tree, init, debug, and runtime options · `cmd/cheqd-noded/cmd/root.go`
- [App wiring](https://github.com/cheqd/cheqd-node/blob/main/app/app.go): Cosmos app · Application assembly, keepers, stores, genesis, and module registration · `app/app.go`
- [Ante stack](https://github.com/cheqd/cheqd-node/blob/main/app/ante.go): tx pre-check · Fee validation, bypass, filters, and other admission logic · `app/ante.go`
- [Post stack](https://github.com/cheqd/cheqd-node/blob/main/post/post.go): tx post-check · Post-execution fee accounting and tax/burn behavior · `post/post.go`
- [Upgrades](https://github.com/cheqd/cheqd-node/blob/main/app/upgrades/v4/const.go): versioned migration · App-level upgrade handlers and module version coordination · `app/upgrades/v4/const.go`

### On-chain modules

Custom Cosmos modules and their stateful boundaries

- [DID types](https://github.com/cheqd/cheqd-node/blob/main/x/did/types/tx.go): proto contracts · DID documents, tx/query messages, params, and validation rules · `x/did/types/tx.go`
- [DID keeper](https://github.com/cheqd/cheqd-node/blob/main/x/did/keeper/keeper.go): state transitions · Create, update, deactivate, mint/burn, storage, and queries · `x/did/keeper/keeper.go`
- [DID migrations](https://github.com/cheqd/cheqd-node/blob/main/x/did/migrations/v6/migrate.go): schema migration · Module state evolution across chain upgrades · `x/did/migrations/v6/migrate.go`
- [Resource types](https://github.com/cheqd/cheqd-node/blob/main/x/resource/types/tx.pb.go): proto contracts · Resource and metadata messages, params, packet types, and validation · `x/resource/types/tx.pb.go`
- [Resource keeper](https://github.com/cheqd/cheqd-node/blob/main/x/resource/keeper/keeper.go): state transitions · Create, query, metadata, collection lookup, and IBC port handling · `x/resource/keeper/keeper.go`
- [Resource IBC](https://github.com/cheqd/cheqd-node/blob/main/x/resource/ibc_module.go): IBC module · IBC-facing integration boundary for resource behavior · `x/resource/ibc_module.go`
- [Resource migrations](https://github.com/cheqd/cheqd-node/blob/main/x/resource/migration/v5/migration.go): schema migration · Versioned state migrations for resource module · `x/resource/migration/v5/migration.go`
- [Oracle types](https://github.com/cheqd/cheqd-node/blob/main/x/oracle/types/tx.pb.go): proto contracts · Price feeds, ballots, proposals, params, rewards, and events · `x/oracle/types/tx.pb.go`
- [Oracle keeper](https://github.com/cheqd/cheqd-node/blob/main/x/oracle/keeper/keeper.go): state transitions · Ballots, pricing, historic prices, rewards, slashing, and params · `x/oracle/keeper/keeper.go`
- [Oracle ABCI](https://github.com/cheqd/cheqd-node/blob/main/x/oracle/abci/voteextension.go): vote extension · End-block and vote-extension integration with consensus · `x/oracle/abci/voteextension.go`

### Client interfaces

Protobuf, gRPC, CLI, and generated API surfaces

- [Proto API](https://github.com/cheqd/cheqd-node/blob/main/proto/cheqd/did/v2/tx.proto): gRPC/REST surface · Generated protobuf, gRPC, and gateway definitions for modules · `proto/cheqd/did/v2/tx.proto`
- [Module CLI](https://github.com/cheqd/cheqd-node/blob/main/x/did/client/cli/tx.go): command surface · Per-module tx/query commands for operators and integrators · `x/did/client/cli/tx.go`
- [API docs](https://github.com/cheqd/cheqd-node/blob/main/app/client/docs/swagger.yaml): OpenAPI docs · REST/OpenAPI documentation assets for client consumption · `app/client/docs/swagger.yaml`

### Operations

Upgrade, deployment, and test tooling

- [Network plans](https://github.com/cheqd/cheqd-node/blob/main/networks/mainnet/genesis.json): upgrade config · Mainnet and testnet genesis, seeds, and upgrade proposals · `networks/mainnet/genesis.json`
- [Deploy tools](https://github.com/cheqd/cheqd-node/tree/main/docker/Dockerfile): ops tooling · Docker, localnet, persistent chains, and installer packaging · `docker/Dockerfile`
- [Integration tests](https://github.com/cheqd/cheqd-node/blob/main/tests/integration/integration_suite_test.go): end-to-end tests · Chain, CLI, IBC, fee, oracle, and upgrade scenarios · `tests/integration/integration_suite_test.go`

## Connections

- Node binary → Root CLI: starts · Binary invokes the Cobra command tree
- Root CLI → App wiring: configures · CLI bootstraps the Cosmos application
- App wiring → Ante stack: uses · App installs transaction ante decorators
- App wiring → Post stack: uses · App installs post-execution processing
- App wiring → Upgrades: orchestrates · App coordinates upgrades and migrations
- App wiring → DID keeper: wires · Registers DID keeper and module services
- App wiring → Resource keeper: wires · Registers resource keeper and module services
- App wiring → Oracle keeper: wires · Registers oracle keeper and module services
- App wiring → DID types: binds · App consumes module message and query contracts
- App wiring → Resource types: binds · App consumes module message and query contracts
- App wiring → Oracle types: binds · App consumes module message and query contracts
- DID keeper → DID types: implements · Keeper realizes DID state machine defined by types
- DID keeper → DID migrations: evolves · Keeper state is updated through migrations
- Resource keeper → Resource types: implements · Keeper realizes resource state machine defined by types
- Resource keeper → Resource IBC: serves · Keeper is exposed through IBC module hooks
- Resource keeper → Resource migrations: evolves · Keeper state is updated through migrations
- Oracle keeper → Oracle types: implements · Keeper realizes oracle pricing and rewards rules
- Oracle keeper → Oracle ABCI: feeds · Keeper data contributes to consensus-side ABCI logic
- Proto API → Module CLI: generates · Protobuf contracts back both gRPC and CLI surfaces
- API docs → Proto API: documents · REST docs are generated from protobuf APIs
- Module CLI → DID types: targets · CLI issues DID transactions and queries
- Module CLI → Resource types: targets · CLI issues resource transactions and queries
- Module CLI → Oracle types: targets · CLI issues oracle transactions and queries
- Network plans → Upgrades: drives · Network upgrade files coordinate app version transitions
- Deploy tools → Node binary: runs · Deployment tooling starts the node binary
- Integration tests → App wiring: exercises · Integration suites run the full chain app
- Integration tests → Resource IBC: covers · Dedicated scenarios exercise IBC resource flows
- Integration tests → Oracle ABCI: covers · Upgrade and oracle scenarios cover consensus hooks