From 67f827ac8457e01a25b58a8a8a2eeb517713913a Mon Sep 17 00:00:00 2001 From: Datt Goswami Date: Thu, 20 Jun 2024 13:00:07 -0600 Subject: [PATCH] adding documentation for the programs --- documentation/overview.md | 69 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 documentation/overview.md diff --git a/documentation/overview.md b/documentation/overview.md new file mode 100644 index 000000000..2fc783e7d --- /dev/null +++ b/documentation/overview.md @@ -0,0 +1,69 @@ +# High-Level Overview of the OpenBook-v2 Program + +A high-level overview of the program, its key components, and what is happening in various parts of the codebase. + +## Key Components + +1. **Accounts:** + - **Market Account:** Holds information about the market, including order books, fees, and market metadata. + - **OpenOrdersAccount:** Represents a user’s open orders in a market. Contains details about the user’s active orders, positions, and balances. + - **EventHeap:** Stores events such as order placements, cancellations, and trades. It acts as a log of all activities within the market. + - **Bids and Asks:** Separate accounts for storing the order books for buy (bid) and sell (ask) orders. + +2. **Instructions:** + - **Initialize Market:** Sets up a new market with all the necessary parameters and accounts. + - **Place Order:** Places a new order in the order book, either as a bid or an ask. + - **Cancel Order:** Cancels an existing order. + - **Match Orders:** Matches buy and sell orders to execute trades. + - **Settle Funds:** Settles the funds after a trade, updating the balances of the involved parties. + - **Consume Events:** Processes events from the event heap to finalize trades and update states. + +3. **Events and Logging:** + - **Event Heap:** Used to store and manage events related to trades, cancellations, and other market activities. + - **Logging Functions:** Emit events for various activities to provide transparency and facilitate debugging. + +## Directory Structure + +1. **`accounts/`:** Contains definitions for the various accounts used in the program. + - **`market.rs`:** Defines the structure and methods for the market account. + - **`open_orders.rs`:** Defines the structure and methods for the OpenOrdersAccount. + - **`event_heap.rs`:** Defines the structure and methods for the event heap. + - **`order_book.rs`:** Defines the structure and methods for managing the order books (bids and asks). + +2. **`instructions/`:** Contains the implementations of the program's instructions. + - **`initialize_market.rs`:** Logic for initializing a new market. + - **`place_order.rs`:** Logic for placing a new order. + - **`cancel_order.rs`:** Logic for cancelling an existing order. + - **`match_orders.rs`:** Logic for matching buy and sell orders. + - **`settle_funds.rs`:** Logic for settling funds after trades. + - **`consume_events.rs`:** Logic for consuming events from the event heap. + +3. **`state/`:** Contains state-related logic and helper functions. + - **`order.rs`:** Defines the structure and methods for orders. + - **`position.rs`:** Defines the structure and methods for managing positions. + - **`fees.rs`:** Defines the structure and methods for managing fees. + - **`market_metadata.rs`:** Defines metadata related to the market. + +4. **`error.rs`:** Defines custom errors used throughout the program. + +5. **`lib.rs`:** The main entry point for the program, where the modules are declared and the program logic is initialized. + +## High-Level Flow of Operations + +1. **Market Initialization:** + - The `initialize_market` instruction is called to create a new market. This sets up the market account, event heap, and order books (bids and asks). + +2. **Placing Orders:** + - Users place orders through the `place_order` instruction. Depending on whether it is a buy or sell order, it is added to the bids or asks order book. + +3. **Matching Orders:** + - The `match_orders` instruction is invoked to match existing buy and sell orders. This involves updating the order books, creating trade events, and updating user balances. + +4. **Consuming Events:** + - The `consume_events` instruction processes events in the event heap, finalizing trades, updating states, and emitting relevant logs. + +5. **Cancelling Orders:** + - Users can cancel their orders using the `cancel_order` instruction. This removes the order from the order book and updates the user's position and balance. + +6. **Settling Funds:** + - After trades are matched, the `settle_funds` instruction is used to settle the funds between the involved parties, ensuring that the correct balances are reflected in their accounts.