Skip to content

Commit 66c491c

Browse files
dcb9dcb9
committed
add ULST doc
1 parent e904a39 commit 66c491c

9 files changed

Lines changed: 407 additions & 0 deletions

File tree

‎pages/lsaas/_meta.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ export default{
2121
architecture_cosmos_lsd:"Cosmos LSD",
2222
architecture_solana_lsd:"Solana LSD",
2323
architecture_ton_lsd:"Ton LSD",
24+
architecture_ulst:"Stablecoin LSD",
2425
"-- develop": {
2526
type: "separator",
2627
title: "Develop"
@@ -32,6 +33,7 @@ export default{
3233
develop_cosmos_lsd:"Cosmos LSD",
3334
develop_sol_lsd:"Solana LSD",
3435
develop_ton_lsd:"Ton LSD",
36+
develop_ulst:"Stablecoin LSD",
3537
modules:"Modules",
3638
hackathon:"Hackathon",
3739
"-- security": {

‎pages/lsaas/architecture_ulst.mdx‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: Stablecoin LST Architecture
3+
---
4+
5+
# ULST (USD Liquid Staking Token) Architecture
6+
7+
## Overview
8+
9+
The ULST (USD Liquid Staking Token) system is a multi-network liquid staking protocol that enables users to deposit stablecoins (USDC, PYUSD, etc) and receive liquid staking derivative tokens (LSD tokens) in return. The system generates yield by integrating with Ondo Finance's Real World Asset (RWA) protocols, where deposited stablecoins are used to subscribe to yield-bearing RWA tokens.
10+
11+
The ULST system uses an era-based state machine to batch operations, ensuring efficient multi-user processing and clear state boundaries. It supports multiple independent networks through a factory pattern, enabling isolated deployments with independent governance.
12+
13+
## System Architecture
14+
15+
The ULST system implements a multi-network liquid staking protocol where:
16+
17+
1. Users deposit stablecoins through the `StakeManager` and receive LSD tokens at the current exchange rate
18+
2. Funds are delegated to Ondo via the `StakePool`, which subscribes to RWA tokens
19+
3. Exchange rates update through `newEra` method to reflect accrued rewards
20+
4. Users can unstake to initiate withdrawal, subject to an unbonding period
21+
5. Multiple independent networks can be deployed using the `LsdNetworkFactory`
22+
23+
## User Flows
24+
25+
### Staking Flow
26+
27+
1. User deposits stablecoins to the StakeManager contract
28+
2. StakeManager calculates LSD amount based on current exchange rate:
29+
```
30+
lstAmount = stakingAmount * (1e18 / currentRate)
31+
```
32+
3. LSD tokens are minted to the user's address
33+
4. Stablecoins are transferred to StakePool for custody
34+
5. Funds are queued for delegation to Ondo RWA protocols
35+
36+
37+
### Unstaking Flow
38+
39+
1. User initiates unstake by calling unstake function with LSD amount
40+
2. LSD tokens are burned from user's balance
41+
3. Unstake request is queued in the unbonding system
42+
4. Request waits for unbonding period (configurable number of eras)
43+
5. After unbonding period, user can withdraw stablecoins
44+
45+
46+
### Withdrawal Flow
47+
48+
1. User calls withdraw after unbonding period expires
49+
2. System checks if sufficient stablecoins are available in pool
50+
3. If available: Stablecoins are transferred immediately to user
51+
4. If insufficient: RWA tokens are redeemed from Ondo to fulfill withdrawal
52+
53+
54+
## Era Management
55+
56+
The ULST system uses an era-based state machine for efficient batch processing:
57+
58+
### Era Progression
59+
60+
- Era Duration: Configurable time period (default: 1 day)
61+
- Era Progression: Triggered by `newEra()` function calls
62+
- Batch Operations: All pending operations are processed during era transitions
63+
64+
### Era Operations
65+
66+
During each era progression:
67+
68+
1. Process pending delegations - Convert queued stablecoins to RWA tokens
69+
2. Process pending undelegations - Convert RWA tokens back to stablecoins
70+
3. Update exchange rates - Calculate new rates based on RWA performance
71+
4. Distribute rewards - Allocate yield to users, protocol, and fees
72+
5. Process unbonding - Move eligible unstake requests to withdrawable state
73+
74+
## Ondo Protocol Integration
75+
76+
The ULST system integrates with Ondo Finance through well-defined interfaces:
77+
78+
### Critical External Calls
79+
80+
- `IOndoInstantManager.subscribe(stablecoin, amount, minimumDepositAmount)` - Convert stablecoin to RWA
81+
- `IOndoInstantManager.redeem(rwaToken, amount, minimumRedemptionAmount)` - Convert RWA to stablecoin
82+
- `IOndoOracle.getAssetPrice(asset)` - Get current RWA/USD price for rate calculations

‎pages/lsaas/develop_ulst/_meta.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
export default{
2+
getstarted:"Get Started",
3+
contract:"Contract",
4+
relay:"Relay",
5+
app:"Stake App",
6+
deploy:"Deploy",
7+
}

‎pages/lsaas/develop_ulst/app.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: Stake App
3+
---
4+
5+
TBD

‎pages/lsaas/develop_ulst/contract.mdx‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
title: Contract
3+
---
4+
5+
# Contract
6+
7+
The stack for ULST consists of four contracts: 1. LsdNetworkFactory, an utility contract which deploys project contracts by a single call; 2. LsdToken, an ERC20-compatible token which represents users' receipt of their staking; 3. StakePool, delegates stablecoin assets to Ondo Finance for RWA token subscription; 4. StakeManager, manages project internal and external states and interacts with users.
8+
9+
The ULST system integrates with Real World Assets (RWA) through Ondo Finance, enabling users to deposit stablecoins and receive liquid staking derivative tokens that generate yield through RWA investments.
10+
11+
## LsdNetworkFactory.sol
12+
13+
The `LsdNetworkFactory` is a utility contract that simplifies the deployment of new LSD networks. Instead of manually deploying multiple contracts, you can use the factory to create a complete LSD network with a single transaction.
14+
15+
Network Contracts Structure
16+
17+
```solidity
18+
struct NetworkContracts {
19+
address _stakeManager;
20+
address _stakePool;
21+
address _lsdToken;
22+
uint256 _block;
23+
}
24+
```
25+
26+
Events
27+
28+
```solidity
29+
event LsdNetwork(NetworkContracts contracts);
30+
```
31+
32+
### createLsdNetwork()
33+
34+
Creates a new LSD network with immediate admin control.
35+
36+
```solidity
37+
function createLsdNetwork(
38+
string memory _lsdTokenName,
39+
string memory _lsdTokenSymbol,
40+
address _govInstantManagerAddress,
41+
address _govOracleAddress,
42+
address[] memory _stablecoins
43+
) external
44+
```
45+
46+
**Parameters:**
47+
- `_lsdTokenName` - Name of the LSD token (e.g., "StaFi rULST")
48+
- `_lsdTokenSymbol` - Symbol of the LSD token (e.g., "rULST")
49+
- `_govInstantManagerAddress` - Ondo Instant Manager contract address for RWA operations
50+
- `_govOracleAddress` - Ondo Oracle contract address for RWA price feeds
51+
- `_stablecoins` - Array of supported stablecoin addresses (USDC, PYUSD, etc.)
52+
53+
### createLsdNetworkWithTimelock()
54+
55+
Creates a new LSD network with timelock governance for enhanced security.
56+
57+
```solidity
58+
function createLsdNetworkWithTimelock(
59+
string memory _lsdTokenName,
60+
string memory _lsdTokenSymbol,
61+
address _govInstantManagerAddress,
62+
address _govOracleAddress,
63+
address[] memory _stablecoins,
64+
uint256 minDelay,
65+
address[] memory proposers
66+
) external
67+
```
68+
69+
**Additional Parameters:**
70+
- `minDelay` - Minimum delay for timelock operations (in seconds)
71+
- `proposers` - Array of addresses who can submit timelock proposals
72+
73+
## StakeManager.sol
74+
75+
The `StakeManager` is the main orchestration contract that manages the entire staking lifecycle and coordinates between users and the underlying RWA protocols.
76+
77+
### Stakers methods
78+
79+
`stake`: Allows users to deposit stablecoins and receive LSD tokens.
80+
81+
- `stablecoin` - Address of the stablecoin to stake (USDC, PYUSD)
82+
- `amount` - Amount of stablecoin to stake
83+
84+
```solidity
85+
function stake(address _stablecoin, uint256 _amount)
86+
```
87+
88+
`unstake`: Allows users to initiate unstaking by burning LSD tokens.
89+
90+
- `_stablecoin` - Address of the stablecoin to unstake (USDC, PYUSD)
91+
- `_lsdTokenAmount` - Amount of LSD tokens to unstake
92+
93+
```solidity
94+
function unstake(address _stablecoin, uint256 _lsdTokenAmount)
95+
```
96+
97+
98+
`withdraw`: Allows users to withdraw stablecoins after the unbonding period.
99+
100+
```solidity
101+
function withdraw() external
102+
```
103+
104+
### Administrative methods
105+
106+
- `addStablecoin` - Add a new supported stablecoin to the system
107+
- `rmStablecoin` - Remove a stablecoin from the supported list
108+
- `setIsUnstakePaused` - Pause or resume unstaking operations
109+
- `addStakePool` - Add a new stake pool to the network
110+
- `withdrawProtocolFee` - Withdraw accumulated protocol fees
111+
112+
### Parameters adjustment methods
113+
114+
- `setProtocolFeeCommission` - Set the protocol fee rate for reward distribution
115+
- `setFactoryFeeCommission` - Set the factory fee rate for protocol fees
116+
- `setEraParams` - Configure era duration and timing parameters
117+
- `setRateChangeLimit` - Set maximum allowed exchange rate change per era
118+
- `setMinStakeAmount` - Set minimum stake amount threshold
119+
- `setUnbondingDuration` - Set unbonding period duration in eras
120+
- `setUnstakeFee` - Set fee rate for unstaking operations
121+
122+
123+
### Era Method
124+
125+
Triggers era progression and processes pending operations. This is a permissionless function that can be called by anyone once sufficient time has elapsed.
126+
127+
The `newEra()` function executes a multi-phase pipeline that processes all bonded pools in the network:
128+
129+
1. Era Validation: Calculates next era number and validates sufficient time has passed
130+
2. Delegation Processing: Delegates accumulated stablecoins to Ondo Finance for RWA token subscription
131+
3. Undelegation Processing: Redeems RWA tokens back to stablecoins for pending withdrawals
132+
4. Reward Calculation: Calculates rewards from RWA token appreciation
133+
5. Rate Updates: Updates exchange rates based on total RWA value vs LSD supply
134+
6. Protocol Fee Distribution: Distributes protocol fees from newly earned rewards
135+
136+
**Rate Calculation:**
137+
```
138+
if (totalLst == 0 || totalActive < totalLst):
139+
return 1e18
140+
else:
141+
calRate = (totalActive * 1e18) / totalLst
142+
```
143+
144+
**Events Emitted:**
145+
- `ExecuteNewEra(uint256 indexed era, uint256 rate)` - Era transition and new exchange rate
146+
- `NewReward(address poolAddress, uint256 newReward)` - Rewards earned by each pool
147+
- `GovRedeemFee(address pool, address stablecoin, uint256 amount)` - Ondo redemption fees

‎pages/lsaas/develop_ulst/deploy.mdx‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# How to deploy an ULST stack
2+
3+
This guide provides a step-by-step script to deploy an EVM LSD project, without deep understanding of contracts and services. Read the documentation for comprehensive understandings of these components.
4+
5+
## Step1. Deploy your LSD network contracts
6+
7+
61 Lab have made [StaFi LSaaS](https://stack-app.stafi.io/) for project parties to deploy their LSD network contracts. Click ULST icon to deploy your ULST network.
8+
9+
![](/image/ulst/stack-app-homepage.png "Stack App Homepage")
10+
11+
## Parameter Tips
12+
13+
Owner Address: sets the owner of the LSD network being created.
14+
15+
Owner Permissions:
16+
- Upgrade contracts
17+
- Adjust commission fee
18+
- Adjust duration of era
19+
- Pause or unpause unstake operation
20+
- Manage stablecoins
21+
22+
Stable Coins: Stablecoins the network will support. You can add or remove stablecoin via StakeManager contract later with Owner permission.
23+
24+
- USDC
25+
- PYUSD
26+
27+
## Rewards Distribution
28+
29+
Rewards distribution is crucial to project parties. Commission fee of users is set default as 10% and StaFi Stack fee is 10% of the project income. for example, if `100Token` rewards received from the chain, the distribution will be:
30+
31+
| Role | Amount(Token) | Formula |
32+
|---------------|--------|-------|
33+
| Users | 90 | 100*(1-0.1) |
34+
| Project | 9 | (100-90)*(1-0.1) |
35+
| StaFi Stack | 1 | 100-90-9 |
36+
37+
## Save all the information generated
38+
39+
The LSD network has a set of smart contracts, so you should save all the information which you will interact frequently with, such as LSD App, and Relay service.
40+
41+
- LSD Network Factory address
42+
- Owner address
43+
- LSD Token address
44+
- Stake Manager address
45+
- Stake Pool address
46+
47+
## Step2. Run relay service
48+
[Follow this doc to run relay service](./relay/)
49+
50+
## Step3. Deploy your own LSD App
51+
[Follow this doc to deploy your own LSD App](./app/)

‎pages/lsaas/develop_ulst/getstarted.mdx‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Get Started
3+
---
4+
5+
# Get Started
6+
7+
ULST (USD Liquid Staking Token) Stack is devoted to help developers building liquid staking projects that integrate with Real World Assets (RWA) through Ondo Finance, and designed to provide a comprehensive set of solutions related to stablecoin deposits, RWA yield generation, and user operations: stake, unstake, withdraw.
8+
9+
## Contracts
10+
11+
Through the contracts provided by StaFi, project parties can create their ULST network contracts. These contracts are not only essential for a ULST project that records all the states of the project, such as: exchange rates between LSD and stablecoins, RWA token balances, and protocol fees etc, but also the dependence of Relay service and ULST dApp.
12+
13+
## ULST Relay Service
14+
15+
After creating the contracts, you'll need to deploy the relay service. The relay service operates off-chain and requires these addresses to work properly.
16+
17+
It provides functionality to manage era progression and coordinate with Ondo Finance for RWA operations. It triggers the smart contract to handle new era process: delegate stablecoins to RWA tokens, undelegate RWA tokens to stablecoins, and update exchange rates based on RWA performance.
18+
19+
## ULST dApp
20+
21+
Once the ULST contracts created, you can deploy the ULST dApp for users to stake stablecoins, unstake LSD tokens, withdraw funds and get the latest information about the project and RWA performance.

0 commit comments

Comments
 (0)