docs: CLOB challenges #108

bguiz · 2025-09-19T04:43:50Z

Summary by CodeRabbit

Documentation
- Added Order Book documentation introducing on-chain CLOB concepts, Injective’s chain-level design, Frequent Batch Auctions, and industry comparisons.
- Added “Challenges & Debates” page covering performance vs decentralization, gas economics, MEV, liquidity fragmentation, economic alignment, and implementation complexity with cross-references.
- Updated table of contents: moved Token Standards (INJ coin, Token Factory, CW20) from Trading to DeFi Wallet.

Signed-off-by: Brendan Graetz <[email protected]>

coderabbitai · 2025-09-19T04:44:00Z

Walkthrough

Relocates the “Token Standards” section in the GitBook TOC from Trading to DeFi Wallet. Adds a new Order Book documentation section with two pages: an overview (CLOB concepts and Injective’s architecture) and a challenges page outlining key debates and issues for on-chain CLOBs.

Changes

Cohort / File(s)	Summary of Edits
TOC relocation (Token Standards) `./.gitbook/SUMMARY.md`	Moved “Token Standards” (INJ coin, Token Factory, CW20 Standard) from under Trading (iAssets) to DeFi Wallet.
New Order Book docs `.gitbook/defi/order-book/README.md`, `.gitbook/defi/order-book/challenges.md`	Added CLOB overview and a challenges/debates page covering performance, gas, MEV, liquidity, alignment, fairness, and implementation complexity.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I thump my paws on docs so bright,
Hopped Token Standards left to right;
New books of orders, clean and clear,
Batch by batch, the facts draw near.
In lettuce-green margins I annotate—
On-chain trails where traders congregate.
Carrots up; we iterate! 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title "docs: CLOB challenges" is concise, uses the docs: prefix, and directly describes the primary addition in the changeset—the new CLOB challenges documentation (challenges.md). It is specific and clear enough for a reviewer scanning PR history. Although the PR also adds an order-book README and moves a Token Standards TOC entry, the title correctly highlights the main topic and is not misleading.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch docs/order-book-challenges

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Please see the documentation for more information.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

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.}

coderabbitai

Actionable comments posted: 1

🧹 Nitpick comments (11)

.gitbook/SUMMARY.md (1)
9-9: Nit: title case consistency (“INJ coin” → “INJ Coin”)

Minor copy/style tweak to match common title casing used elsewhere.

Optional diff:
-      * [INJ coin](defi/tokens/inj-coin.md)
+      * [INJ Coin](defi/tokens/inj-coin.md)
.gitbook/defi/order-book/challenges.md (5)
41-41: Fix heading level consistency (use H2, not H1).

Section depth jumps back to H1. Make it ## Implementation Complexity & Technical Debt to keep a single H1 per page.
-# Implementation Complexity & Technical Debt
+## Implementation Complexity & Technical Debt
9-9: Replace italic “Addressed in:” lines with headings or callouts (MD036).

Italicized emphasis is being used as a heading; markdownlint flags this. Prefer a subheading or a callout with links.
-*Addressed in: Performance Metrics & Comparisons*
+### Addressed in
+- [Performance Metrics & Comparisons](./performance-metrics.md)

-*Addressed in: Gas Economics & Cost Efficiency*
+### Addressed in
+- [Gas Economics & Cost Efficiency](./gas-economics.md)

-*Addressed in: Frequent Batch Auctions: MEV Resistance Through Native Design*
+### Addressed in
+- [Frequent Batch Auctions: MEV Resistance Through Native Design](./frequent-batch-auctions.md)

-*Addressed in: Shared Liquidity Infrastructure*
+### Addressed in
+- [Shared Liquidity Infrastructure](./shared-liquidity.md)

-*Addressed in: Economic Alignment & Network Value Accrual*
+### Addressed in
+- [Economic Alignment & Network Value Accrual](./economic-alignment.md)

-*Addressed in: Frequent Batch Auctions: MEV Resistance Through Native Design*
+### Addressed in
+- [Frequent Batch Auctions: MEV Resistance Through Native Design](./frequent-batch-auctions.md)

-*Addressed in: Developer Experience & Composability*
+### Addressed in
+- [Developer Experience & Composability](./devex-and-composability.md)
If those targets don’t exist yet, keep the structure and add TODOs or convert to intra‑page anchors.

Also applies to: 15-15, 21-21, 27-27, 33-33, 39-39, 45-45

7-8: Qualify latency claims or add citations.

“sub‑10 ms” vs “100+ ms” is assertive; either cite representative sources or soften to ranges (“on the order of tens of ms vs ~100 ms+”).

Would you like me to add footnote-style references or convert to hedged language?

17-21: Add explicit cross-link to the FBA section.

Since you reference Frequent Batch Auctions as a mitigation, link to the section/file that explains it.
- Proposed solutions include encrypted mempools, trusted execution environments, and various batching mechanisms, but these often require significant infrastructure modifications or introduce new trust assumptions.
+ Proposed solutions include encrypted mempools, trusted execution environments, and various batching mechanisms (see [Frequent Batch Auctions](./frequent-batch-auctions.md)), but these often require significant infrastructure modifications or introduce new trust assumptions.
1-46: Standardize "order book" (two words) across the repo. Mixed usage found in .gitbook (examples: .gitbook/defi/auction.md, .gitbook/defi/open-liquidity-program/introduction.md, .gitbook/defi/order-book/README.md, .gitbook/developers-native/injective/exchange/03_state.md). Replace all occurrences of "orderbook" with "order book" for consistency.
.gitbook/defi/order-book/README.md (5)
14-14: Use “page” instead of “paper.”

Minor tone/style tweak for docs.
-This paper provides a comprehensive examination of Injective's on-chain CLOB infrastructure,
+This page provides a comprehensive examination of Injective's on-chain CLOB infrastructure,
8-9: Soften blanket claims about VM-based CLOB constraints.

Rephrase to avoid overgeneralization and keep a neutral tone.
-Most CLOB-based projects emerging on the scene face fundamental constraints, as they are built within virtual machine (VM) environments. These solutions, whether on Ethereum, Solana, Aptos, Sui, or other execution environments, suffer from gas economics, computational overhead, and architectural boundaries.
+Many CLOB implementations built within virtual machine (VM) environments encounter constraints such as gas costs, computational overhead, and architectural boundaries, though the specifics vary by chain and design.
7-7: Time-bounded claim check (“seven years”).

As of September 2025, 2018 → 2025 is seven years; keep this synced if the page is reused later (consider “since 2018”).
-For seven years, Injective has been quietly solving the technical challenges
+Since 2018, Injective has been solving the technical challenges
1-15: Cross-link to the new Challenges page.

Improve navigation by linking the companion page.
+## See also
+- [The Current CLOB Discourse: Key Challenges & Debates](./challenges.md)
1-15: Standardize “order book” vs “orderbook” across the repo. Mixed usage detected across multiple .gitbook files; pick one style (recommend "order book") and apply a repo-wide replace.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6d73a7e and 962c421.

📒 Files selected for processing (3)

.gitbook/SUMMARY.md (1 hunks)
.gitbook/defi/order-book/README.md (1 hunks)
.gitbook/defi/order-book/challenges.md (1 hunks)

🧰 Additional context used

🪛 markdownlint-cli2 (0.17.2)

.gitbook/defi/order-book/challenges.md

9-9: Emphasis used instead of a heading