From bc851ac512e366cbe39741768c558475c016f1f3 Mon Sep 17 00:00:00 2001 From: Cosmic Vagabond <121588426+cosmic-vagabond@users.noreply.github.com> Date: Thu, 6 Jun 2024 11:41:57 +0200 Subject: [PATCH] docs: add mechanism section --- x/leveragelp/spec/02_mechanism.md | 52 +++++++++++++++++++ .../spec/{02_usage.md => 03_usage.md} | 2 +- .../spec/{03_keeper.md => 04_keeper.md} | 2 +- ...initions.md => 05_protobuf_definitions.md} | 2 +- .../spec/{05_functions.md => 06_functions.md} | 2 +- x/leveragelp/spec/README.md | 9 ++-- 6 files changed, 61 insertions(+), 8 deletions(-) create mode 100644 x/leveragelp/spec/02_mechanism.md rename x/leveragelp/spec/{02_usage.md => 03_usage.md} (99%) rename x/leveragelp/spec/{03_keeper.md => 04_keeper.md} (99%) rename x/leveragelp/spec/{04_protobuf_definitions.md => 05_protobuf_definitions.md} (99%) rename x/leveragelp/spec/{05_functions.md => 06_functions.md} (99%) diff --git a/x/leveragelp/spec/02_mechanism.md b/x/leveragelp/spec/02_mechanism.md new file mode 100644 index 000000000..1541bb38d --- /dev/null +++ b/x/leveragelp/spec/02_mechanism.md @@ -0,0 +1,52 @@ + + +# 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. diff --git a/x/leveragelp/spec/02_usage.md b/x/leveragelp/spec/03_usage.md similarity index 99% rename from x/leveragelp/spec/02_usage.md rename to x/leveragelp/spec/03_usage.md index f6373e249..f4e97b56e 100644 --- a/x/leveragelp/spec/02_usage.md +++ b/x/leveragelp/spec/03_usage.md @@ -1,5 +1,5 @@ # Usage diff --git a/x/leveragelp/spec/03_keeper.md b/x/leveragelp/spec/04_keeper.md similarity index 99% rename from x/leveragelp/spec/03_keeper.md rename to x/leveragelp/spec/04_keeper.md index e2d803e5c..2eead42c5 100644 --- a/x/leveragelp/spec/03_keeper.md +++ b/x/leveragelp/spec/04_keeper.md @@ -1,5 +1,5 @@ # Keeper diff --git a/x/leveragelp/spec/04_protobuf_definitions.md b/x/leveragelp/spec/05_protobuf_definitions.md similarity index 99% rename from x/leveragelp/spec/04_protobuf_definitions.md rename to x/leveragelp/spec/05_protobuf_definitions.md index 45248d4c8..1c9769985 100644 --- a/x/leveragelp/spec/04_protobuf_definitions.md +++ b/x/leveragelp/spec/05_protobuf_definitions.md @@ -1,5 +1,5 @@ # Types, Messages, Queries, and States diff --git a/x/leveragelp/spec/05_functions.md b/x/leveragelp/spec/06_functions.md similarity index 99% rename from x/leveragelp/spec/05_functions.md rename to x/leveragelp/spec/06_functions.md index 644eaaf2c..52a238536 100644 --- a/x/leveragelp/spec/05_functions.md +++ b/x/leveragelp/spec/06_functions.md @@ -1,5 +1,5 @@ # Functions diff --git a/x/leveragelp/spec/README.md b/x/leveragelp/spec/README.md index 0d501707b..236d26b7e 100644 --- a/x/leveragelp/spec/README.md +++ b/x/leveragelp/spec/README.md @@ -3,10 +3,11 @@ ## Contents 1. **[Concepts](01_concepts.md)** -2. **[Usage](02_usage.md)** -3. **[Keeper](03_keeper.md)** -4. **[Protobuf Definitions](04_protobuf_definitions.md)** -5. **[Functions](05_functions.md)** +2. **[Mechanism](02_mechanism.md)** +3. **[Usage](03_usage.md)** +4. **[Keeper](04_keeper.md)** +5. **[Protobuf Definitions](05_protobuf_definitions.md)** +6. **[Functions](06_functions.md)** ## References