Skip to content

docs: add repository structure section to README #313

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
giwaov wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: add repository structure section to README #313

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
edc690b
docs: add repository structure section to README
Apr 2, 2026
0f93889
docs: address review feedback on repository structure table
Apr 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
23 changes: 23 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,6 +263,29 @@ 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 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. |
| `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. |

Comment thread
coderabbitai[bot] marked this conversation as resolved.
## 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!
Expand Down
Loading