docs: order book risk management #110
Conversation
Signed-off-by: Brendan Graetz <[email protected]>
…gement Signed-off-by: Brendan Graetz <[email protected]>
WalkthroughRelocates Token Standards from Trading to Wallet in the GitBook summary. Adds two new DeFi documents: an Order Book README detailing Injective’s native on-chain CLOB and a Risk Management guide covering margin, liquidation, insurance fund, and oracle integration. No code or API changes; documentation-only modifications. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Trader
participant Wallet
participant "Exchange Module\n(on-chain CLOB)" as CLOB
participant Oracle
participant "Matching Engine\n(FBA)" as Match
participant "Settlement" as Settle
note over CLOB,Match: New/Documented interactions: native module-level order flow
Trader->>Wallet: Create/Sign Order
Wallet->>CLOB: Submit order tx
CLOB->>Oracle: Read price feeds (for risk checks)
CLOB->>Match: Enqueue order for batch
rect rgb(232, 244, 253)
note right of Match: Frequent Batch Auction window
Match-->>CLOB: Batch match results
end
CLOB->>Settle: Update balances/positions
Settle-->>Trader: State updated (fills/cancels)
sequenceDiagram
autonumber
participant "Validator Set" as Validators
participant "Exchange Module" as CLOB
participant Oracle
participant "Liquidation Engine" as Liq
participant "Insurance Fund" as IF
note over Validators,CLOB: Per-block margin updates (deterministic)
Validators->>Oracle: Fetch latest prices
Oracle-->>CLOB: Prices
CLOB->>CLOB: Revalue positions & margin checks
alt Maintenance margin breached
CLOB->>Liq: Trigger liquidation (partial/full)
Liq->>CLOB: Execute orders/position reductions
opt Deficit after liquidation
CLOB->>IF: Cover loss
IF-->>CLOB: Payout (if available)
end
else
CLOB-->>Validators: No action
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate 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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (11)
.gitbook/SUMMARY.md (1)
9-9: Title case: “INJ Coin”.Use consistent title casing for proper nouns.
Apply this diff:
- * [INJ coin](defi/tokens/inj-coin.md) + * [INJ Coin](defi/tokens/inj-coin.md).gitbook/defi/order-book/README.md (3)
7-8: Avoid relative time; switch to absolute dates.“For seven years” will age poorly. Use explicit dates.
Apply this diff:
-For seven years, Injective has been quietly solving the technical challenges that the broader crypto community has only recently begun to grapple with. +Since 2018, Injective has been solving technical challenges that the broader crypto community has only recently begun to grapple with.
10-11: Neutral tone and fact-check external project details.Tone down marketing language and ensure accuracy about Hyperliquid’s architecture; add a citation or rephrase conservatively.
Apply this diff:
-To be fair, Injective is not the only project to recognize these architectural limitations. Hyperliquid, which launched in 2022 and has captured massive attention in the current CLOB narrative, has also built a custom L1 to avoid VM constraints. However, it employs a dual architecture, splitting state execution between HyperCore and HyperEVM, introducing development complexity and performance implications for applications hoping to leverage the CLOB. +To be fair, Injective is not the only project to recognize these architectural limitations. Hyperliquid has also built a custom L1 to avoid general‑purpose VM constraints. Public materials describe multiple execution components (e.g., HyperCore and HyperEVM). Please verify these specifics and cite an authoritative source, or rephrase without naming internal components if uncertain.
12-14: Link out and cross-reference adjacent docs.Add explicit links to the Exchange module docs and the new Risk Management page for discoverability.
Apply this diff:
-Injective's approach is fundamentally different: implementing orderbook functionality as a native blockchain module rather than an application layer. This enables permissionless plug-and-play access for any application built on Injective, eliminating cross-layer complexity while executing sophisticated financial operations without gas optimization constraints or architectural compromises. +Injective's approach is fundamentally different: implementing orderbook functionality as a native blockchain module rather than an application layer. This enables permissionless plug‑and‑play access for any application built on Injective, eliminating cross‑layer complexity while executing sophisticated financial operations without EVM‑style gas metering constraints or architectural compromises. See also: [Exchange module](/developers-native/injective/exchange/README.md). @@ -This paper provides a comprehensive examination of Injective's on-chain CLOB infrastructure, explaining both how it works and why its architectural approach offers inherent advantages over alternative implementations. We will explore the Exchange module's (Injective’s CLOB infrastructure) design, detail its key innovations such as the Frequent Batch Auction mechanism for front-running prevention, and analyze how chain-level implementation enables capabilities that remain difficult or impossible to achieve within virtual machine environments. By understanding Injective's technical architecture, we can better appreciate both its significance as the original on-chain CLOB implementation and its strategic positioning as the crypto industry rediscovers the power of decentralized orderbook infrastructure. +This paper provides a high‑level examination of Injective's on‑chain CLOB infrastructure, explaining both how it works and why the architectural approach offers advantages over alternative implementations. We outline the Exchange module design, highlight the Frequent Batch Auction mechanism for front‑running mitigation, and analyze how chain‑level implementation enables capabilities that are difficult within virtual machine environments. For risk and margin details, see [Risk Management](/defi/order-book/risk-management.md)..gitbook/defi/order-book/risk-management.md (7)
68-71: Reword “gas-free” to avoid overclaiming.Be precise: native modules aren’t constrained by EVM-style gas metering; users may still pay transaction fees.
Apply this diff:
-The native module approach provides several crucial advantages for risk management compared to smart contract implementations. First, all risk calculations and controls operate without gas cost constraints, enabling sophisticated algorithms and frequent updates that would be economically prohibitive in virtual machine environments. +The native module approach provides several crucial advantages for risk management compared to smart contract implementations. First, risk calculations and controls are not constrained by EVM‑style gas metering, enabling sophisticated algorithms and frequent updates that would be economically prohibitive in many virtual machine environments.
23-31: Liquidation details: add references to parameters and process.Link to the canonical docs describing maintenance margin, partial liquidation thresholds, and auction/order type used during liquidation.
Apply this diff:
-## Liquidation Engine +## Liquidation Engine + +See also: [Margin Trading](/defi/trading/margin.md) and [Liquidation](/defi/trading/margin-liquidation.md) for user‑level concepts and parameters.
32-39: Insurance Fund: link to module docs and user-facing guide.Add cross-links to improve credibility and navigation.
Apply this diff:
-## Insurance Fund Operations +## Insurance Fund Operations + +References: +- [Insurance Funds (Indexer Queries)](/developers-native/query-chain/insurance-funds.md) +- [Insurance Module (Native)](/developers-native/injective/insurance/README.md)
58-63: Oracle integration: link to Oracle module docs.Helps readers validate the data path.
Apply this diff:
-## Integration with Oracle Infrastructure +## Integration with Oracle Infrastructure + +References: +- [Oracle (Native Module)](/developers-native/injective/oracle/README.md) +- [Querying Oracle](/developers-native/query-chain/oracle.md)
1-76: Remove or convert HTML comments before publishing.There are several commented sections (Lines 17, 20, 28, 39, 44, 50, 52–57, 64, 72, 74). Consider moving these into a “Future Work” or “TBD” section to avoid shipping hidden content.
1-2: Add breadcrumb/back-links.Add a short “Back to Order Book” link to improve navigation.
Apply this diff:
-# Risk Management & Margin System in Injective CLOB +# Risk Management & Margin System in Injective CLOB +[_Back to Order Book_](/defi/order-book/README.md)
74-76: Add a See also section.Cross-link user and module docs to round out the topic.
Apply this diff:
-This consistency is crucial for maintaining trader confidence and system integrity during stressful market conditions. +This consistency is crucial for maintaining trader confidence and system integrity during stressful market conditions. + +See also: +- [Exchange module (Native)](/developers-native/injective/exchange/README.md) +- [Margin Trading](/defi/trading/margin.md) +- [Liquidation](/defi/trading/margin-liquidation.md) +- [Insurance Funds](/developers-native/query-chain/insurance-funds.md)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
.gitbook/SUMMARY.md(1 hunks).gitbook/defi/order-book/README.md(1 hunks).gitbook/defi/order-book/risk-management.md(1 hunks)
🔇 Additional comments (4)
.gitbook/SUMMARY.md (1)
8-12: Relocation verified — no stale "Token Standards" links remain under Trading.
Tokens pages exist at .gitbook/defi/tokens/; search returned no 'Token Standards' or 'tokens' matches in .gitbook/defi/trading..gitbook/defi/order-book/risk-management.md (2)
1-76: Cross-link check — all referenced pages present. All targets referenced from .gitbook/defi/order-book/risk-management.md were found in-repo.
7-12: Clarify cross‑margin scope: state subaccount‑level cross‑margin and per‑market limits.gitbook/defi/order-book/risk-management.md (lines 7–12): explicitly state that Injective manages margin at the subaccount level (a subaccount’s deposits/equity are pooled to cover both spot and derivative positions), and call out that per‑market initial/maintenance margin ratios and market‑level haircuts/limits restrict effective cross‑margining — reference Exchange state (subaccount balances), State transitions (margin/liquidation), and Trading/perpetuals (margin formulas).
.gitbook/defi/order-book/README.md (1)
14-15: Qualify or cite the “original” claim.File: .gitbook/defi/order-book/README.md (lines 14–15)
"Original on‑chain CLOB implementation" is contestable. Injective announced its CLOB whitepaper on Apr 29, 2020, ran Solstice testnet with live on‑chain trading in Dec 2020, and launched mainnet in Nov 2021; later posts (Nov 2022) call it the "first fully on‑chain orderbook." Either:
- Replace with a qualified phrase (e.g., "one of the earliest on‑chain CLOB implementations — announced Apr 29, 2020; testnet Dec 2020; mainnet Nov 8, 2021") and add citations (whitepaper Apr 29, 2020; Dec 2020 Solstice posts; GitHub/chain releases; Nov 2022 blog), or
- Keep "first" but explicitly state which sense you mean (e.g., "first chain‑level/native orderbook module") and cite sources proving that specific claim.
| * [Order Book](defi/order-book/README.md) | ||
| * [Trading](defi/trading/README.md) |
There was a problem hiding this comment.
Add missing child link to Risk Management under Order Book.
The new page .gitbook/defi/order-book/risk-management.md isn’t discoverable from the TOC. Please add it as a child of “Order Book.”
Apply this diff:
* [Order Book](defi/order-book/README.md)
+ * [Risk Management](defi/order-book/risk-management.md)
* [Trading](defi/trading/README.md)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| * [Order Book](defi/order-book/README.md) | |
| * [Trading](defi/trading/README.md) | |
| * [Order Book](defi/order-book/README.md) | |
| * [Risk Management](defi/order-book/risk-management.md) | |
| * [Trading](defi/trading/README.md) |
🤖 Prompt for AI Agents
In .gitbook/SUMMARY.md around lines 12 to 13, the new page
defi/order-book/risk-management.md is missing from the table of contents; add a
child entry under "Order Book" by inserting a new list item that links to
defi/order-book/risk-management.md directly beneath the existing Order Book line
so the Risk Management page is discoverable.
Summary by CodeRabbit