docs: add leverage lp module specs

x/leveragelp/spec/01_concepts.md

@@ -0,0 +1,7 @@
+<!--
+order: 1
+-->
+
+# Concepts
+
+The `leveragelp` module in the Elys Network facilitates leveraged liquidity provision in AMM pools. It allows users to open and manage leveraged positions using collateral, enhancing their potential returns from liquidity provisioning. The module manages parameters such as leverage limits, pool thresholds, and positions, and includes mechanisms for liquidation and health checks to ensure the safety and stability of the leveraged positions.

x/leveragelp/spec/02_mechanism.md

@@ -0,0 +1,52 @@
+<!--
+order: 2
+-->
+
+# Mechanism
+
+The LeverageLP module enables participants to leverage their liquidity position in the AMM pool by borrowing USDC tokens bonded in the StableStake module. This interaction results in a leveraged position that is tracked and managed within the LeverageLP module.
+
+## Dependencies
+
+The LeverageLP module depends on two other modules:
+
+1. **StableStake**: Manages the bonding of USDC tokens by participants.
+2. **AMM**: Facilitates liquidity provision and trading.
+
+## Overview
+
+Participants in the system engage with the modules as follows:
+
+1. **Bonding USDC to StableStake**:
+
+   - Participants bond their USDC tokens to the StableStake module.
+   - These bonded tokens become available for borrowing by other participants.
+
+2. **Leveraging Liquidity with LeverageLP**:
+   - Participants borrow USDC tokens from the StableStake module using the LeverageLP module.
+   - The borrowed tokens are used to enhance their liquidity position in the AMM pool.
+   - This results in a debt recorded within the StableStake module.
+
+## Key Equations
+
+To maintain the stability and health of the pool, the following equations are used:
+
+1. **Pool Health**:
+
+   $\text{Pool Health} = \frac{\text{Total Shares} - \text{Leveraged LP Amount}}{\text{Total Shares}}$
+
+   - **Total Shares**: The total number of shares in the pool.
+   - **Leveraged LP Amount**: The amount of liquidity added to the pool through leveraged positions.
+
+   The Pool Health metric is monitored to ensure it does not fall below the Safety Factor threshold, which is set at 10%. Lower Pool Health indicates higher risk of leveraged positions being liquidated.
+
+2. **Position Health and Liquidation Mechanism**:
+
+   $\text{Position Health} = \frac{\text{Position Value}}{\text{Borrowed Amount} + \text{Interest Staked} + \text{Interest Paid}}$
+
+   - **Position Value**: The current value of the leveraged position.
+   - **Borrowed Amount**: The total amount of USDC borrowed from the StableStake module.
+   - **Interest Staked**: The amount of interest accrued on the borrowed amount.
+   - **Interest Paid**: The amount of interest paid by the participant.
+
+   If Position Health falls below the Safety Factor threshold (10%), the leveraged LP position is automatically liquidated to protect the underlying liquidity pool.

x/leveragelp/spec/03_usage.md

@@ -0,0 +1,56 @@
+<!--
+order: 3
+-->
+
+# Usage
+
+## Commands
+
+### Querying Parameters
+
+```bash
+elysd query leveragelp params
+```
+
+### Querying Pools
+
+```bash
+elysd query leveragelp pools
+elysd query leveragelp pool <pool_id>
+```
+
+### Querying Positions
+
+```bash
+elysd query leveragelp positions
+elysd query leveragelp position <address> <id>
+elysd query leveragelp positions-by-pool <pool_id>
+elysd query leveragelp positions-for-address <address>
+```
+
+### Querying Status and Whitelist
+
+```bash
+elysd query leveragelp status
+elysd query leveragelp whitelist
+elysd query leveragelp is-whitelisted <address>
+```
+
+### Opening a Leveraged Position
+
+```bash
+elysd tx leveragelp open --from <address> --collateral-asset <asset> --collateral-amount <amount> --amm-pool-id <pool_id> --leverage <leverage> --stop-loss-price <price> --chain-id <chain_id> --yes
+```
+
+### Closing a Leveraged Position
+
+```bash
+elysd tx leveragelp close --from <address> --id <position_id> --lp-amount <amount> --chain-id <chain_id> --yes
+```
+
+### Whitelisting and Dewhitelisting Addresses
+
+```bash
+elysd tx leveragelp whitelist --from <authority_address> --whitelisted-address <address> --chain-id <chain_id> --yes
+elysd tx leveragelp dewhitelist --from <authority_address> --whitelisted-address <address> --chain-id <chain_id> --yes
+```

x/leveragelp/spec/04_keeper.md

@@ -0,0 +1,39 @@
+<!--
+order: 4
+-->
+
+# Keeper
+
+## Position Management
+
+The `leveragelp` module's keeper handles the opening, updating, and closing of leveraged positions. It ensures that positions are correctly managed, leverage limits are respected, and health checks are performed to avoid liquidation risks.
+
+### Opening a Position
+
+The `Open` function allows a user to open a leveraged position by providing collateral and specifying leverage and a stop-loss price.
+
+```go
+func (k Keeper) Open(ctx sdk.Context, msg *types.MsgOpen) (*types.MsgOpenResponse, error) {
+    // logic to open a leveraged position
+}
+```
+
+### Closing a Position
+
+The `Close` function allows a user to close a leveraged position, either partially or fully, by specifying the amount of LP tokens to withdraw.
+
+```go
+func (k Keeper) Close(ctx sdk.Context, msg *types.MsgClose) (*types.MsgCloseResponse, error) {
+    // logic to close a leveraged position
+}
+```
+
+### Liquidation and Health Checks
+
+The `BeginBlocker` function performs regular health checks on all positions and liquidates unhealthy positions if necessary.
+
+```go
+func (k Keeper) BeginBlocker(ctx sdk.Context) {
+    // logic for regular health checks and liquidation
+}
+```