CDPRegistry overview

doc/dev/CDPRegistry.md

@@ -0,0 +1,52 @@
+# CDPRegistry Smart Contract Overview
+
+The `CDPRegistry` smart contract is part of the Unit Protocol, a decentralized finance (DeFi) system. It tracks Collateralized Debt Positions (CDPs) and interfaces with other protocol components like the Vault and the Collateral Registry.
+
+The protocol tracks CDPs for several important reasons:
+
+1. **Risk Management**: Tracking CDPs allows the protocol to monitor the overall health and risk exposure of its system. By keeping tabs on the amount of debt and collateral in each CDP, the protocol can assess the risk of undercollateralization, which is crucial for maintaining stability and solvency.
+
+1. **Liquidation Processes**: CDPs need to be closely monitored for liquidation purposes. If the value of the collateral falls below a certain threshold relative to the debt, the CDP becomes vulnerable to liquidation. Tracking CDPs ensures that these positions can be identified and dealt with promptly to minimize financial loss and maintain system integrity.
+
+1. **Governance and Auditing**: For governance purposes, it's important to have a clear and transparent view of all active CDPs. This data can inform decisions about protocol parameters (like stability fees or collateralization ratios) and facilitate external audits and verifications.
+
+1. **User Insights and Service Improvement**: Tracking CDPs provides valuable insights into how users interact with the protocol. This data can be used to improve user experience, develop new features, or adjust existing ones to better meet user needs.
+
+1. **Security and Fraud Detection**: Monitoring CDPs can help in identifying suspicious activities or potential exploits. Early detection of anomalies in CDP behavior can trigger security protocols to prevent fraud or hacking attempts.
+
+1. **Financial Analysis and Reporting**: For both users and protocol managers, having detailed information about CDPs aids in financial analysis and reporting. This includes understanding the distribution of debt, collateral types used, and overall protocol utilization.
+
+## Key Components and Features
+
+### 1. Data Structures
+- **CDP**: A struct representing a CDP with asset and owner addresses.
+
+### 2. State Variables
+- **cdpList**: Mapping from asset addresses to arrays of owner addresses.
+- **cdpIndex**: Nested mapping for storing indices of CDPs in the `cdpList`.
+- **vault**: Reference to the IVault interface.
+- **cr**: Reference to the ICollateralRegistry interface.
+
+### 3. Events
+- **Added**: Emitted when a CDP is added to the registry.
+- **Removed**: Emitted when a CDP is removed from the registry.
+
+### 4. Constructor
+- Initializes the contract with the Vault and Collateral Registry addresses.
+
+### 5. Main Functionalities
+- **checkpoint**: Updates the CDP list based on the current status (active/inactive).
+- **batchCheckpointForAsset**: Processes multiple CDPs for a specified asset.
+- **batchCheckpoint**: Handles multiple CDPs for multiple assets.
+- **isAlive**: Checks if a CDP is active based on its associated debt.
+- **isListed**: Determines if a CDP is listed in the registry.
+- **_removeCdp** and **_addCdp**: Internal functions for CDP management.
+
+### 6. CDP Queries
+- **getCdpsByCollateral**: Retrieves all CDPs for a given collateral.
+- **getCdpsByOwner**: Fetches all CDPs owned by a specific address.
+- **getAllCdps**: Obtains all CDPs in the registry.
+- **getCdpsCount**: Provides the total count of CDPs.
+- **getCdpsCountForCollateral**: Counts CDPs for a specific collateral.
+
+The `CDPRegistry` is vital for the Unit Protocol's infrastructure, serving as a centralized reference for CDP tracking. It efficiently manages the CDPs in conjunction with the Vault and Collateral Registry, ensuring cohesive and reliable operation within the protocol. Its functionalities include maintaining an updated list of active CDPs and facilitating easy querying and management of these positions.