docs(precompiles): add oracle README and top-level overview by giwaov · Pull Request #311 · KiiChain/kiichain

giwaov · 2026-04-02T10:07:00Z

Summary

Adds README documentation for the oracle precompile and a top-level precompiles overview, as requested in #62. The staking precompile already has a README (added via PR #107).

Changes

New: `precompiles/README.md`

Overview table of all precompiles with addresses and descriptions
Architecture pattern explanation (interface, ABI, Go implementation, handlers, type parsers)
Utilities section documenting common/ and scripts/
Security notes and external links

New: `precompiles/oracle/README.md`

Full API reference for all three query methods:
- getExchangeRate(string denom) — single denomination rate
- getExchangeRates() — all active rates (capped at 1000 results)
- getTwaps(uint256 lookbackSeconds) — TWAP over a lookback window
Parameter tables and return value documentation
Solidity usage example with a complete contract
Security considerations (denom length validation, result limits, gas metering)
File structure reference

Modified: `CHANGELOG.md`

Added entry under ## Unreleased / ### Added

Note

This addresses the oracle precompile portion of #62. The staking precompile was already documented in PR #107. If other precompiles are added in the future, they can follow the same README pattern.

Partial fix for #62

Add documentation for the oracle precompile covering all three query methods (getExchangeRate, getExchangeRates, getTwaps), their parameters, return values, Solidity usage examples, and security considerations. Also add a top-level precompiles README with an overview table, architecture description, and links to each precompile's documentation. Partial fix for KiiChain#62

coderabbitai · 2026-04-02T10:07:10Z

Warning

Rate limit exceeded

@giwaov has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 3 minutes and 49 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 3 minutes and 49 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 654be629-9323-4fff-9b5e-0836ab526c08

📥 Commits

Reviewing files that changed from the base of the PR and between 5c894a6 and caa8561.

📒 Files selected for processing (3)

CHANGELOG.md
precompiles/README.md
precompiles/oracle/README.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Copilot

Pull request overview

Adds new documentation for KiiChain EVM precompiles: a top-level precompiles overview and an oracle precompile README/API reference, plus a changelog entry documenting the addition.

Changes:

Add precompiles/README.md with an overview, architecture notes, utilities, and security notes.
Add precompiles/oracle/README.md with oracle precompile API docs and Solidity usage example.
Update CHANGELOG.md under ## Unreleased to mention the new docs.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
`precompiles/README.md`	Introduces a top-level precompiles overview (table, architecture, utilities, security).
`precompiles/oracle/README.md`	Documents the oracle precompile address, functions, return values, and usage example.
`CHANGELOG.md`	Adds an Unreleased “Added” entry for the new precompile documentation.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-02T10:12:31Z

+## Available Precompiles
+
+| Precompile | Address | Description |
+|------------|---------|-------------|
+| [Oracle](./oracle/) | `0x0000000000000000000000000000000000001003` | Query exchange rates, TWAP prices from the oracle module |
+| [Staking](./staking/) | `0x0000000000000000000000000000000000000800` | Delegate, undelegate, and query delegation amounts |
+


The "Available Precompiles" table is presented as the full list, but the chain enables additional static precompiles beyond Oracle/Staking (e.g., tests/e2e/genesis.go includes 0x...0100, 0x...0400, 0x...0801–0x...0806). Please either expand the table to cover all enabled precompiles (with addresses/descriptions) or explicitly scope this README to only the precompiles documented/implemented under precompiles/ (and link to where the upstream Cosmos EVM precompiles are documented).

Copilot · 2026-04-02T10:12:32Z

+| Precompile | Address | Description |
+|------------|---------|-------------|
+| [Oracle](./oracle/) | `0x0000000000000000000000000000000000001003` | Query exchange rates, TWAP prices from the oracle module |
+| [Staking](./staking/) | `0x0000000000000000000000000000000000000800` | Delegate, undelegate, and query delegation amounts |


Markdown table syntax here starts with || ..., which renders as an extra empty column in many renderers. Use a single leading | for each row (consistent 3-column table) so the overview table displays correctly on GitHub.

Copilot · 2026-04-02T10:12:32Z

+## Architecture
+
+Each precompile follows the same pattern:
+
+1. **Solidity Interface** (`I<Name>.sol`) — defines the EVM-callable functions
+2. **ABI** (`abi.json`) — the compiled ABI used to decode calls at runtime
+3. **Go Implementation** (`<name>.go`) — implements `vm.PrecompiledContract`, routing method IDs to handler functions
+4. **Query/Tx Handlers** (`query.go` / `tx.go`) — execute the underlying Cosmos SDK keeper calls
+5. **Type Parsers** (`types.go`) — parse and validate ABI-decoded arguments
+


The Architecture section describes files like I<Name>.sol, abi.json, <name>.go, and tx.go as if they exist for each precompile in this repo, but precompiles/staking/ only contains a README and most other enabled precompiles are imported from github.com/cosmos/evm/precompiles/*. Consider rewording to distinguish (a) locally-implemented precompiles (like oracle/) from (b) upstream Cosmos EVM precompiles, or link directly to the upstream structure for those.

Copilot · 2026-04-02T10:12:32Z

+## Security
+
+- All precompile inputs are validated (e.g., denom length capped at 128 bytes)
+- Query results are bounded to prevent unbounded memory allocation


Security section states "Query results are bounded" as a general guarantee, but the oracle getTwaps query path does not apply MaxQueryResults (the module's Twaps query returns the full computed list). Please soften this to reflect which queries are actually capped (e.g., getExchangeRates), or document any relevant upper bounds for TWAP results.

Suggested change

- Query results are bounded to prevent unbounded memory allocation

- Query results for some queries (for example, oracle `getExchangeRates`) are explicitly bounded to prevent unbounded memory allocation; other queries, such as TWAP price queries, may return all available results as provided by the underlying Cosmos SDK modules

Copilot · 2026-04-02T10:12:32Z

+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `denom` | `string` | The denomination to query (max 128 bytes) |
+
+**Returns:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `rate` | `string` | The current exchange rate |
+| `lastUpdate` | `string` | Block height of the last update |
+| `lastUpdateTimestamp` | `int64` | Unix timestamp of the last update |


The parameter/return tables use || at the start of each row, which can render as an extra empty column in GitHub Markdown. Switch to standard |-delimited tables so the API reference displays consistently.

Copilot · 2026-04-02T10:12:33Z

+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `lookbackSeconds` | `uint256` | Number of seconds to look back for the TWAP calculation |
+


getTwaps(lookbackSeconds) documentation doesn't mention the enforced bounds: the precompile rejects lookbackSeconds <= 0, and the oracle keeper validates lookbackSeconds must be <= Params.LookbackDuration (otherwise the query errors). Please document these constraints so callers can avoid unexpected reverts/errors.

Suggested change

> **Constraints:** `lookbackSeconds` must be greater than `0` (the precompile rejects `lookbackSeconds <= 0`) and must be less than or equal to the configured maximum lookback duration (`Params.LookbackDuration`), otherwise the oracle query will error.

giwaov · 2026-04-10T15:16:56Z

Hi @jhelison — friendly ping! This PR is ready for review whenever you have a moment. All CI checks are passing. Happy to address any feedback. Thanks!

giwaov · 2026-04-21T19:44:00Z

Hey @Thaleszh, would love to get your eyes on this when you have a moment. Thanks!

giwaov requested a review from jhelison as a code owner April 2, 2026 10:07

Copilot AI review requested due to automatic review settings April 2, 2026 10:07

Copilot started reviewing on behalf of giwaov April 2, 2026 10:07 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(precompiles): add oracle README and top-level overview#311

docs(precompiles): add oracle README and top-level overview#311
giwaov wants to merge 1 commit into
KiiChain:mainfrom
giwaov:docs/precompile-readmes

giwaov commented Apr 2, 2026

Uh oh!

coderabbitai Bot commented Apr 2, 2026

Rate limit exceeded

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

giwaov commented Apr 10, 2026

Uh oh!

giwaov commented Apr 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	- Query results are bounded to prevent unbounded memory allocation
	- Query results for some queries (for example, oracle `getExchangeRates`) are explicitly bounded to prevent unbounded memory allocation; other queries, such as TWAP price queries, may return all available results as provided by the underlying Cosmos SDK modules



	> Constraints: `lookbackSeconds` must be greater than `0` (the precompile rejects `lookbackSeconds <= 0`) and must be less than or equal to the configured maximum lookback duration (`Params.LookbackDuration`), otherwise the oracle query will error.

Conversation

giwaov commented Apr 2, 2026

Summary

Changes

New: precompiles/README.md

New: precompiles/oracle/README.md

Modified: CHANGELOG.md

Note

Uh oh!

coderabbitai Bot commented Apr 2, 2026

Rate limit exceeded

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

giwaov commented Apr 10, 2026

Uh oh!

giwaov commented Apr 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

New: `precompiles/README.md`

New: `precompiles/oracle/README.md`

Modified: `CHANGELOG.md`