Skip to content

Commit 5b8765a

Browse files
GitGuru7GitGuru7
committed
feat: add technical documentation of risk stewards
1 parent eb1828d commit 5b8765a

File tree

5 files changed

+619
-0
lines changed

5 files changed

+619
-0
lines changed

‎.gitbook/assets/riskSteward.png‎

755 KB
Loading

‎risk/risk-oracle-and-risk-stewards.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Risk Stewards & Risk Oracles
2+
3+
## Overview
4+
5+
Venus Protocol incorporates Risk Oracles and Risk Stewards to ensure risk parameters remain up-to-date, resilient, and aligned with real-time market conditions—all while preserving decentralized governance. Previously, Venus relied on manually created VIPs to apply risk updates based on Chaos Labs recommendations. With the introduction of the Risk Steward and its on-chain receiver, this process is now automated through a secure and permissioned mechanism. In the initial phase, only market cap-related parameters—specifically supply caps and borrow caps—will be updated automatically, improving responsiveness and operational efficiency.
6+
7+
---
8+
9+
## Chaos Labs Risk Oracle
10+
11+
The **Chaos Labs Risk Oracle** is a system designed to continuously analyze market conditions—such as price volatility, liquidity, asset utilization, and liquidation events—and generate risk parameter recommendations tailored to the Venus Protocol.
12+
13+
### Key Benefits:
14+
15+
- **Real-time updates** to key parameters like supply and borrow caps
16+
- **Automated adjustments** to ensure optimal lending and borrowing rates
17+
- **More responsive risk management** with lower latency
18+
- **Reduced operational overhead** for the Venus community
19+
20+
The Risk Oracle makes Venus more adaptable while ensuring parameters remain within safe and governance-approved limits.
21+
22+
---
23+
24+
## Risk Steward
25+
26+
A **Risk Steward** is an on-chain smart contract that executes risk parameter updates on behalf of the protocol, based on recommendations from the Risk Oracle. Venus has introduced this role to bridge off-chain risk intelligence with on-chain execution in a controlled, transparent way.
27+
28+
### Role of the Risk Steward:
29+
30+
- Reads values from the Risk Oracle during execution
31+
- Updates only pre-approved risk parameters (e.g., supply caps, borrow caps)
32+
- Operates within limits set by Venus governance
33+
- Cannot modify critical protocol settings such as interest rate models, market listings, or governance controls
34+
35+
This structure ensures **faster, automated adjustments** without compromising community control.
36+
37+
---
38+
39+
## How It Works
40+
41+
1. **Data Source**: Chaos Labs publishes updated recommendations via the Risk Oracle.
42+
2. **Keeper Role**: A Keeper bot observes changes and initiates transactions to update Venus Protocol’s parameters.
43+
3. **Validation**: During execution, Venus contracts read and apply new values **only if they are within predefined safety bounds**.
44+
4. **Challenge Window**: Critical updates, which will be introduced in an upcoming phase, will go through governance and can be **challenged or vetoed** during a defined challenge window before they take effect.
45+
46+
## Governance & Control
47+
48+
Importantly, this system does **not bypass protocol governance**. All automated updates happen within constraints defined and approved by the Venus community.
49+
50+
Any change made through the Risk Oracle follows an **optimistic governance model**:
51+
52+
This process **preserves decentralization** while enabling faster, safer protocol maintenance.
53+
54+
---
55+
56+
## What’s Next
57+
58+
Initially, the integration focuses on automating supply and borrow cap updates. Over time, additional parameters may be supported as part of a gradual rollout, always subject to DAO approval and governance-defined constraints.
59+
60+
---
61+
62+
## Learn More
63+
64+
- [Chaos Labs: Risk Oracles — Real-Time Risk Management for DeFi](https://chaoslabs.xyz/posts/risk-oracles-real-time-risk-management-for-defi)
65+
- [Venus Community Proposal: Integrate Chaos Labs Risk Oracle](https://community.venus.io/t/integrate-chaos-labs-risk-oracle-to-venus-protocol/4569)
66+

‎technical-reference/reference-governance/MarketCapsRiskSteward.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# MarketCapsRiskSteward
2+
Contract that can update supply and borrow caps received from RiskStewardReceiver. Requires that the update is within the max delta.
3+
Expects the new value to be an encoded uint256 value of un padded bytes.
4+
5+
# Solidity API
6+
7+
### maxDeltaBps
8+
9+
The max delta bps for the update relative to the current value
10+
11+
```solidity
12+
uint256 maxDeltaBps
13+
```
14+
15+
- - -
16+
17+
### CORE_POOL_COMPTROLLER
18+
19+
Address of the CorePoolComptroller used for selecting the correct comptroller abi
20+
21+
```solidity
22+
contract ICorePoolComptroller CORE_POOL_COMPTROLLER
23+
```
24+
25+
- - -
26+
27+
### RISK_STEWARD_RECEIVER
28+
29+
Address of the RiskStewardReceiver used to validate incoming updates
30+
31+
```solidity
32+
contract IRiskStewardReceiver RISK_STEWARD_RECEIVER
33+
```
34+
35+
- - -
36+
37+
### SUPPLY_CAP
38+
39+
The update type for supply caps
40+
41+
```solidity
42+
string SUPPLY_CAP
43+
```
44+
45+
- - -
46+
47+
### BORROW_CAP
48+
49+
The update type for borrow caps
50+
51+
```solidity
52+
string BORROW_CAP
53+
```
54+
55+
- - -
56+
57+
### setMaxDeltaBps
58+
59+
Sets the max delta bps
60+
61+
```solidity
62+
function setMaxDeltaBps(uint256 maxDeltaBps_) external
63+
```
64+
65+
#### Parameters
66+
| Name | Type | Description |
67+
| ---- | ---- | ----------- |
68+
| maxDeltaBps_ | uint256 | The new max delta bps |
69+
70+
#### 📅 Events
71+
* Emits MaxDeltaBpsUpdated with the old and new max delta bps
72+
73+
#### ⛔️ Access Requirements
74+
* Controlled by AccessControlManager
75+
76+
#### ❌ Errors
77+
* InvalidMaxDeltaBps if the max delta bps is 0 or greater than MAX_BPS
78+
79+
- - -
80+
81+
### processUpdate
82+
83+
Processes a market cap update from the RiskStewardReceiver.
84+
Validates that the update is within range and then directly update the market supply or borrow cap on the market's comptroller.
85+
RiskParameterUpdate shape is as follows:
86+
* newValue - encoded uint256 value of un padded bytes
87+
* previousValue - encoded uint256 value of un padded bytes
88+
* updateType - supplyCap | borrowCap
89+
* additionalData - encoded bytes of (address underlying, uint16 destChainId)
90+
91+
```solidity
92+
function processUpdate(struct RiskParameterUpdate update) external
93+
```
94+
95+
#### Parameters
96+
| Name | Type | Description |
97+
| ---- | ---- | ----------- |
98+
| update | struct RiskParameterUpdate | RiskParameterUpdate update to process. |
99+
100+
#### 📅 Events
101+
* Emits SupplyCapUpdated or BorrowCapUpdated depending on the update with the market and new cap
102+
103+
#### ⛔️ Access Requirements
104+
* Only callable by the RiskStewardReceiver
105+
106+
#### ❌ Errors
107+
* OnlyRiskStewardReceiver Thrown if the sender is not the RiskStewardReceiver
108+
* UnsupportedUpdateType Thrown if the update type is not supported
109+
* UpdateNotInRange Thrown if the update is not within the allowed range
110+
111+
- - -
112+

‎technical-reference/reference-governance/RiskStewardReceiver.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# RiskStewardReceiver
2+
Contract that can read updates from the Chaos Labs Risk Oracle, validate them, and push them to the correct RiskSteward.
3+
4+
# Solidity API
5+
6+
### riskParameterConfigs
7+
8+
Mapping of supported risk configurations and their validation parameters
9+
10+
```solidity
11+
mapping(string => struct RiskParamConfig) riskParameterConfigs
12+
```
13+
14+
- - -
15+
16+
### RISK_ORACLE
17+
18+
Whitelisted oracle address to receive updates from
19+
20+
```solidity
21+
contract IRiskOracle RISK_ORACLE
22+
```
23+
24+
- - -
25+
26+
### lastProcessedTime
27+
28+
Mapping of market and update type to last update timestamp. Used for debouncing updates.
29+
30+
```solidity
31+
mapping(bytes => uint256) lastProcessedTime
32+
```
33+
34+
- - -
35+
36+
### processedUpdates
37+
38+
Mapping of processed updates. Used to prevent re-execution
39+
40+
```solidity
41+
mapping(uint256 => bool) processedUpdates
42+
```
43+
44+
- - -
45+
46+
### UPDATE_EXPIRATION_TIME
47+
48+
Time before a submitted update is considered stale
49+
50+
```solidity
51+
uint256 UPDATE_EXPIRATION_TIME
52+
```
53+
54+
- - -
55+
56+
### initialize
57+
58+
Initializes the contract as ownable, pausable, and access controlled
59+
60+
```solidity
61+
function initialize(address accessControlManager_) external
62+
```
63+
64+
#### Parameters
65+
| Name | Type | Description |
66+
| ---- | ---- | ----------- |
67+
| accessControlManager_ | address | The address of the access control manager |
68+
69+
- - -
70+
71+
### pause
72+
73+
Pauses processing of updates
74+
75+
```solidity
76+
function pause() external
77+
```
78+
79+
#### ⛔️ Access Requirements
80+
* Controlled by AccessControlManager
81+
82+
- - -
83+
84+
### unpause
85+
86+
Unpauses processing of updates
87+
88+
```solidity
89+
function unpause() external
90+
```
91+
92+
#### ⛔️ Access Requirements
93+
* Controlled by AccessControlManager
94+
95+
- - -
96+
97+
### setRiskParameterConfig
98+
99+
Sets the risk parameter config for a given update type
100+
101+
```solidity
102+
function setRiskParameterConfig(string updateType, address riskSteward, uint256 debounce) external
103+
```
104+
105+
#### Parameters
106+
| Name | Type | Description |
107+
| ---- | ---- | ----------- |
108+
| updateType | string | The type of update to configure |
109+
| riskSteward | address | The address for the risk steward contract responsible for processing the update |
110+
| debounce | uint256 | The debounce period for the update |
111+
112+
#### 📅 Events
113+
* Emits RiskParameterConfigSet with the update type, previous risk steward, new risk steward, previous debounce,
114+
* new debounce, previous active status, and new active status
115+
116+
#### ⛔️ Access Requirements
117+
* Controlled by AccessControlManager
118+
119+
#### ❌ Errors
120+
* Throws UnsupportedUpdateType if the update type is an empty string
121+
* Throws InvalidDebounce if the debounce is 0
122+
* Throws ZeroAddressNotAllowed if the risk steward address is zero
123+
124+
- - -
125+
126+
### toggleConfigActive
127+
128+
Toggles the active status of a risk parameter config
129+
130+
```solidity
131+
function toggleConfigActive(string updateType) external
132+
```
133+
134+
#### Parameters
135+
| Name | Type | Description |
136+
| ---- | ---- | ----------- |
137+
| updateType | string | The type of update to toggle on or off |
138+
139+
#### 📅 Events
140+
* Emits ToggleConfigActive with the update type and the new active status
141+
142+
#### ⛔️ Access Requirements
143+
* Controlled by AccessControlManager
144+
145+
#### ❌ Errors
146+
* Throws UnsupportedUpdateType if the update type is not supported
147+
148+
- - -
149+
150+
### processUpdateById
151+
152+
Processes an update by its ID. Will validate that the update configuration is active, is not expired, unprocessed, and that the debounce period has passed.
153+
Validated updates will be processed by the associated risk steward contract which will perform update specific validations and apply validated updates.
154+
155+
```solidity
156+
function processUpdateById(uint256 updateId) external
157+
```
158+
159+
#### Parameters
160+
| Name | Type | Description |
161+
| ---- | ---- | ----------- |
162+
| updateId | uint256 | The ID of the update to process |
163+
164+
#### 📅 Events
165+
* Emits RiskParameterUpdated with the update ID
166+
167+
#### ❌ Errors
168+
* Throws ConfigNotActive if the config is not active
169+
* Throws UpdateIsExpired if the update is expired
170+
* Throws ConfigAlreadyProcessed if the update has already been processed
171+
* Throws UpdateTooFrequent if the update is too frequent
172+
173+
- - -
174+
175+
### processUpdateByParameterAndMarket
176+
177+
Processes the latest update for a given parameter and market. Will validate that the update configuration is active, is not expired,
178+
unprocessed, and that the debounce period has passed.
179+
Validated updates will be processed by the associated risk steward contract which will perform update specific validations and apply validated updates.
180+
181+
```solidity
182+
function processUpdateByParameterAndMarket(string updateType, address market) external
183+
```
184+
185+
#### Parameters
186+
| Name | Type | Description |
187+
| ---- | ---- | ----------- |
188+
| updateType | string | The type of update to process |
189+
| market | address | The market to process the update for |
190+
191+
#### 📅 Events
192+
* Emits RiskParameterUpdated with the update ID
193+
194+
#### ❌ Errors
195+
* Throws ConfigNotActive if the config is not active
196+
* Throws UpdateIsExpired if the update is expired
197+
* Throws ConfigAlreadyProcessed if the update has already been processed
198+
* Throws UpdateTooFrequent if the update is too frequent
199+
200+
- - -
201+

0 commit comments

Comments
 (0)