Skip to content

Commit b96ab6e

Browse files
hxrtshxrts
authored
docs: add Mars Lending library documentation (#373)
1 parent d4815f9 commit b96ab6e

File tree

2 files changed

+103
-0
lines changed

2 files changed

+103
-0
lines changed

‎docs/src/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@
5252
- [Drop Liquid Unstaker](./libraries/cosmwasm/drop_liquid_unstaker.md)
5353
- [ICA CCTP Transfer](./libraries/cosmwasm/ica_cctp_transfer.md)
5454
- [ICA IBC Transfer](./libraries/cosmwasm/ica_ibc_transfer.md)
55+
- [Mars Lending](./libraries/cosmwasm/mars_lending.md)
5556
- [EVM](./libraries/evm/_overview.md)
5657
- [Forwarder](./libraries/evm/forwarder.md)
5758
- [CCTP Transfer](./libraries/evm/cctp_transfer.md)

‎docs/src/libraries/cosmwasm/mars_lending.md

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Valence Mars Lending library
2+
3+
The Valence Mars Lending library facilitates lending operations on the [Mars Protocol](https://marsprotocol.io/) from an input account and manages withdrawal of lent assets to an output account. The library creates and manages a Mars credit account that is owned by the input account, enabling simple lending and withdrawal operations. This library enables Valence Programs to earn yield on deposited assets through Mars Protocol's lending markets while maintaining full control over the lending positions through Mars credit accounts.
4+
5+
## High-level Flow
6+
7+
```mermaid
8+
---
9+
title: Mars Lending Library
10+
---
11+
graph LR
12+
IA((Input
13+
Account))
14+
OA((Output
15+
Account))
16+
P[Processor]
17+
S[Mars Lending
18+
Library]
19+
MC[Mars Credit
20+
Manager]
21+
CA[Mars Credit
22+
Account]
23+
P -- 1/Lend or Withdraw --> S
24+
S -- 2/Query balances --> IA
25+
S -- 3/Execute Create Credit Account
26+
(if needed) --> IA
27+
IA -- 4/Create Credit Account --> MC
28+
MC -.-> |4'/Create| CA
29+
S -- 5/Execute Lending --> IA
30+
IA -- 6/Deposit & Lend --> CA
31+
S -- 7/Execute Withdrawal --> IA
32+
IA -- 8/Reclaim & Withdraw --> CA
33+
IA -- 9/Transfer Tokens --> OA
34+
```
35+
36+
## Functions
37+
38+
| Function | Parameters | Description |
39+
|----------|------------|-------------|
40+
| **Lend** | - | Creates a Mars credit account (if one doesn't exist) and lends the entire balance of the specified denom from the input account to the Mars Protocol through the credit account. |
41+
| **Withdraw** | `amount: Option<Uint128>` | Withdraws lent assets from the Mars credit account to the output account. If no amount is specified, withdraws the entire position. |
42+
43+
## Configuration
44+
45+
The library is configured on instantiation via the `LibraryConfig` type.
46+
47+
```rust
48+
pub struct LibraryConfig {
49+
// Address of the input account that will own the credit account
50+
pub input_addr: LibraryAccountType,
51+
/// Address of the output account that will receive withdrawn funds
52+
pub output_addr: LibraryAccountType,
53+
// Address of the Mars credit manager contract
54+
pub credit_manager_addr: String,
55+
// Denom of the asset we are going to lend
56+
pub denom: String,
57+
}
58+
```
59+
60+
## Implementation Details
61+
62+
### Credit Account Management
63+
64+
The library automatically handles Mars credit account lifecycle:
65+
66+
- **Account Creation**: When lending is first initiated, the library checks if a credit account exists for the input address. If not, it creates one through the Mars Credit Manager.
67+
- **Account Ownership**: The credit account is owned by the input account, ensuring proper access control and security.
68+
- **Single Account**: Each input account maintains exactly one credit account through this library.
69+
70+
### Lending Process
71+
72+
1. **Balance Check**: Queries the input account balance for the specified denom
73+
2. **Credit Account Resolution**: Either uses existing credit account or creates a new one
74+
3. **Deposit & Lend**: Deposits the tokens into the credit account and immediately lends them to Mars Protocol
75+
4. **Reply Handling**: Uses CosmWasm reply mechanism to handle the two-step process of account creation followed by lending
76+
77+
### Withdrawal Process
78+
79+
1. **Credit Account Query**: Retrieves the existing credit account for the input address
80+
2. **Amount Calculation**: Uses exact amount if specified, otherwise withdraws the entire balance
81+
3. **Reclaim & Withdraw**: Executes two Mars actions:
82+
- `Reclaim`: Withdraws the lent position back to the credit account
83+
- `WithdrawToWallet`: Transfers the tokens from credit account to the output account
84+
85+
### Error Handling
86+
87+
- **No Funds**: Returns error if attempting to lend with zero balance
88+
- **No Credit Account**: Returns error if attempting to withdraw without an existing credit account
89+
- **Mars Integration**: Propagates Mars Protocol errors for lending/withdrawal operations
90+
91+
## Mars Protocol Integration
92+
93+
This library integrates with Mars Protocol's credit account system, which provides:
94+
95+
- **Isolated Lending**: Each credit account operates independently
96+
- **Flexible Actions**: Support for multiple DeFi actions through a single account
97+
- **Risk Management**: Mars Protocol's built-in risk management and liquidation mechanisms
98+
- **Composability**: Credit accounts can be used for complex DeFi strategies beyond simple lending
99+
100+
## Thanks
101+
102+
Thank you to Stana and the [Hydro](https://hydro.cosmos.network/) team for contributing this library upstream.

0 commit comments

Comments
 (0)