Repository navigation
CLOB Phase 0: market identity, typed units, price conversions, and event schema - #1095
Merged
IbrahimIjai merged 6 commits intoOct 21, 2026
Merged
Conversation
Derive MarketId from the unordered asset pair and a version, hashed over a domain separator, the version, and the XDR of the lower and higher addresses. Reversed pairs map to the same id, identical base and quote are rejected, and base/quote orientation stays in the market definition. Closes SO4-Markets#880
Introduce newtypes for base and quote atoms (i128, non-negative), base and quote lots, ticks, and sequence numbers (u64). No From impls exist between units, arithmetic is checked, and conversions between atoms and lots are explicit. Document the width and overflow analysis, including the 18-decimal cap, and cover max values and one-unit dust cases. Closes SO4-Markets#881
Price a tick as tick * tick_size in quote atoms per base atom, scaled by 10^8. Expose scaled_price, quote_for_base_atoms, and quote_for_lots. Every division takes an explicit Rounding: Up for amounts the trader pays in, Down for amounts the protocol pays out. Lot-to-atom conversion is exact, so rounding happens only at the price step. No floating point is used, and all arithmetic is checked. Closes SO4-Markets#882
Define the market event schema: deposit, withdrawal, order accepted, rested, reduced, canceled, expired, fill, fee accrued, fee withdrawn, market status changed, and config changed. Every record carries its MarketId and a strictly increasing, gap-free EventIndex, and orders are identified by the SequenceNumber assigned at acceptance. Topic names are stable. Tests cover topic stability, field values, index ordering, and rebuilding order lifecycle from events alone. Closes SO4-Markets#885
…ents Document the market id preimage, unit widths and overflow rules, the tick-to-quote price model with rounding policy, and the event topic catalogue, so SDK and indexer code can reproduce the consensus-critical definitions.
|
@victor-olamide Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits. You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀 |
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements the four Phase 0 foundation issues assigned to me in one branch:
MarketIdissha256(domain || version || xdr(lo) || xdr(hi))over the unordered asset pair. Reversed pairs derive the same id, andbase == quoteis rejected. Base/quote orientation stays in the market definition. (libs/clob_settlement_core/src/market_id.rs)i128, non-negative), base/quote lots, ticks and sequence numbers (u64). NoFromimpls between units, checked arithmetic only, and explicit atoms-to-lots conversions with dust handling. The module documents the width and overflow analysis, including an 18-decimal cap. (libs/clob_settlement_core/src/units.rs)scaled_price = tick * tick_size(exact), thenquote = base * scaled_price / 10^8. Every division takes an explicitRounding(Upfor trader payments in,Downfor protocol payments out). No floating point. (libs/clob_settlement_core/src/conversion.rs)MarketIdand a gap-free per-marketEventIndex. Orders are identified by their acceptanceSequenceNumber. Topic names are stable. (libs/clob_settlement_core/src/events.rs)docs/clob-foundations-spec.mddocuments the id preimage, unit rules, price model, rounding policy and event catalogue, so SDK and indexer code can reproduce them.One commit per issue, plus the spec commit. Each commit is linked to its issue.
Verification
cargo, ornpmcommand. The repo has noCargo.toml, and theAGENTS.mdverification gate that the issues reference is not in this repository. The unit tests are written but have not been run.soroban-sdk28 APIs used here (Address: Ord,ToXdr,Crypto::sha256,Bytes::from_slice/from_array,BytesN::to_array,register_stellar_asset_contract_v2) by reading the crate source in the local cargo registry.u64::MAXlot boundaries, one-unit dust on both sides of a lot, rounding bracket checks over a small grid, overflow toNone, topic stability, and rebuilding an order's lifecycle from events alone.Notes for reviewers
lib.rsalready hasuse soroban_sdk::{Address, Env, i128};and usesVecwithout importing it. Those lines predate this PR and I left them alone. They may need fixing before the crate compiles.MarketStatus(Open,Paused,Closed) andConfigField(TickSize,LotSize,FeeRate).Closes #880
Closes #881
Closes #882
Closes #885