adding documentation for the programs

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.