From edc690bf433a92de35f6bc5c7d1557b6a8d48ac4 Mon Sep 17 00:00:00 2001 From: Security Auditor Date: Thu, 2 Apr 2026 12:59:17 +0100 Subject: [PATCH 1/2] docs: add repository structure section to README Document all top-level directories and custom modules (oracle, feeabstraction, rewards, tokenfactory) with brief descriptions of their purpose and boundaries. Helps new contributors navigate the monorepo. Closes #60 --- CHANGELOG.md | 4 ++++ README.md | 22 ++++++++++++++++++++++ 2 files changed, 26 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 30468245..3b186876 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,10 @@ ## Unreleased +### Added + +- Add "Repository Structure" section to README documenting all top-level directories and custom modules ([#60](https://github.com/KiiChain/kiichain/issues/60)) + ### Fixed - Fix division-by-zero chain halt in `CalculateReward` caused by sub-second schedule durations; replace `Seconds()` truncation with `Nanoseconds()` precision and release full remaining reward when `EndTime <= LastReleaseTime` ([#267](https://github.com/KiiChain/kiichain/issues/267)) diff --git a/README.md b/README.md index 66922b22..cea3e0ee 100644 --- a/README.md +++ b/README.md @@ -263,6 +263,28 @@ export PATH="$HOME/go/bin:$PATH" sed -i.bak -e "/minimum-gas-prices =/ s^= .*^= \"1000000000akii\"^" ~/.kiichain/config/app.toml ``` +## Repository Structure + +An overview of the top-level directories and their purposes: + +| Directory | Description | +|---|---| +| `ante/` | Custom [AnteHandler](https://docs.cosmos.network/main/learn/beginner/tx-lifecycle#antehandler) decorators that run before every transaction — signature verification, fee deduction, EVM-specific checks, feeless transaction logic, and governance vote/expedited-proposal guards. | +| `app/` | Main application wiring. Defines `KiichainApp`, registers all modules, configures keepers, and implements `InitChainer`/`BeginBlocker`/`EndBlocker`. Also contains test helpers (`helpers/`, `apptesting/`), simulation config, and upgrade handlers. | +| `client/` | Client-side utilities and generated API documentation (Swagger/OpenAPI). | +| `cmd/` | Entry point for the `kiichaind` binary — node startup, CLI commands, and configuration. | +| `contrib/` | Developer tooling, scripts, and helper resources — local node setup, state-sync scripts, upgrade helpers, Docker test files, and sample contract artifacts. | +| `precompiles/` | EVM precompiled contracts that expose native Cosmos SDK functionality to Solidity. Includes the **Oracle** precompile (exchange rates, TWAPs) and **Staking** precompile (delegation, undelegation, redelegation), plus shared utilities. | +| `proto/` | Protobuf definitions for all custom modules. Used to generate Go types, gRPC services, and REST endpoints. | +| `tests/` | End-to-end (`e2e/`) and integration tests that exercise the full chain stack. | +| `wasmbinding/` | CosmWasm ↔ Cosmos SDK bindings — custom message and query plugins that let Wasm contracts interact with native modules (oracle price feeds, token factory, EVM, bech32 conversion). | +| `x/` | Custom Cosmos SDK modules: | +| | • `x/oracle/` — On-chain price feeds. Validators submit exchange rates that are aggregated into a canonical feed available to other modules and smart contracts. | +| | • `x/feeabstraction/` — Allows transaction fees to be paid in tokens other than the native `akii` (e.g., stablecoins), using oracle exchange rates for pricing. | +| | • `x/rewards/` — Community-pool reward distribution to validators on a configurable linear release schedule. | +| | • `x/tokenfactory/` — Permissionless token creation (`factory/{creator}/{subdenom}`), with admin-level mint, burn, and metadata controls. | +| | • `x/types/` — Shared types and constants used across custom modules. | + ## Contributing All contributions are very welcome! Remember, contribution is not only PRs and code, but any help with docs or helping other developers solve their issues are very appreciated! From 0f93889fdd5511ddecb4cb00647def32db611bf9 Mon Sep 17 00:00:00 2001 From: Security Auditor Date: Thu, 2 Apr 2026 13:08:42 +0100 Subject: [PATCH 2/2] docs: address review feedback on repository structure table - Reword intro to mention custom modules under x/ (Copilot) - Give each x/* module its own table row instead of bullets (Copilot) - Add missing assets/ directory (CodeRabbit) --- README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index cea3e0ee..a58a5233 100644 --- a/README.md +++ b/README.md @@ -265,12 +265,13 @@ sed -i.bak -e "/minimum-gas-prices =/ s^= .*^= \"1000000000akii\"^" ~/.kiichain/ ## Repository Structure -An overview of the top-level directories and their purposes: +An overview of the top-level directories and custom modules under `x/`: | Directory | Description | |---|---| | `ante/` | Custom [AnteHandler](https://docs.cosmos.network/main/learn/beginner/tx-lifecycle#antehandler) decorators that run before every transaction — signature verification, fee deduction, EVM-specific checks, feeless transaction logic, and governance vote/expedited-proposal guards. | | `app/` | Main application wiring. Defines `KiichainApp`, registers all modules, configures keepers, and implements `InitChainer`/`BeginBlocker`/`EndBlocker`. Also contains test helpers (`helpers/`, `apptesting/`), simulation config, and upgrade handlers. | +| `assets/` | Static assets such as images and logos used in documentation. | | `client/` | Client-side utilities and generated API documentation (Swagger/OpenAPI). | | `cmd/` | Entry point for the `kiichaind` binary — node startup, CLI commands, and configuration. | | `contrib/` | Developer tooling, scripts, and helper resources — local node setup, state-sync scripts, upgrade helpers, Docker test files, and sample contract artifacts. | @@ -278,12 +279,12 @@ An overview of the top-level directories and their purposes: | `proto/` | Protobuf definitions for all custom modules. Used to generate Go types, gRPC services, and REST endpoints. | | `tests/` | End-to-end (`e2e/`) and integration tests that exercise the full chain stack. | | `wasmbinding/` | CosmWasm ↔ Cosmos SDK bindings — custom message and query plugins that let Wasm contracts interact with native modules (oracle price feeds, token factory, EVM, bech32 conversion). | -| `x/` | Custom Cosmos SDK modules: | -| | • `x/oracle/` — On-chain price feeds. Validators submit exchange rates that are aggregated into a canonical feed available to other modules and smart contracts. | -| | • `x/feeabstraction/` — Allows transaction fees to be paid in tokens other than the native `akii` (e.g., stablecoins), using oracle exchange rates for pricing. | -| | • `x/rewards/` — Community-pool reward distribution to validators on a configurable linear release schedule. | -| | • `x/tokenfactory/` — Permissionless token creation (`factory/{creator}/{subdenom}`), with admin-level mint, burn, and metadata controls. | -| | • `x/types/` — Shared types and constants used across custom modules. | +| `x/` | Custom Cosmos SDK modules. | +| `x/oracle/` | On-chain price feeds. Validators submit exchange rates that are aggregated into a canonical feed available to other modules and smart contracts. | +| `x/feeabstraction/` | Allows transaction fees to be paid in tokens other than the native `akii` (e.g., stablecoins), using oracle exchange rates for pricing. | +| `x/rewards/` | Community-pool reward distribution to validators on a configurable linear release schedule. | +| `x/tokenfactory/` | Permissionless token creation (`factory/{creator}/{subdenom}`), with admin-level mint, burn, and metadata controls. | +| `x/types/` | Shared types and constants used across custom modules. | ## Contributing