Skip to content

Commit df7ee9b

Browse files
euler-mabeuler-mab
committed
feat: add detailed event documentation for EulerSwap and EulerSwapFactory contracts
1 parent 957d3b6 commit df7ee9b

File tree

1 file changed

+143
-0
lines changed

1 file changed

+143
-0
lines changed

‎docs/events.md

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Events
2+
3+
## Introduction
4+
5+
The EulerSwap smart contracts emit several key event types to notify off-chain systems (e.g., frontends, analytics tools) of important state changes. These events facilitate transparency, integration with external systems, and effective monitoring of the protocol's behavior.
6+
7+
Events such as EulerSwapCreated and PoolDeployed are particularly useful for solvers and aggregators. These tools can track new pool creations, allowing them to dynamically update their routing algorithms and ensure trades are optimally routed through EulerSwap pools, enhancing liquidity and trading efficiency.
8+
9+
### Summary
10+
11+
| **Event** | **Contract** | **Purpose** | **Use Case** |
12+
| ------------------ | ------------------ | ----------------------------------------------------- | ------------------------------------- |
13+
| `AddLiquidity` | `EulerSwap` | Emitted when liquidity is added to the pool | Track liquidity inflows |
14+
| `RemoveLiquidity` | `EulerSwap` | Emitted when liquidity is removed from the pool | Monitor liquidity outflows |
15+
| `Swap` | `EulerSwap` | Emitted during token swaps | Trading analytics and UIs |
16+
| `CollectFees` | `EulerSwap` | Emitted when trading fees are collected | Revenue and protocol fee management |
17+
| `StatusChanged` | `EulerSwap` | Signals a change in the contract's operational status | DApp integration and state management |
18+
| `DebtLimitUpdated` | `EulerSwap` | Emitted when debt limits for assets are modified | Risk management and protocol settings |
19+
| `ErrorOccurred` | `EulerSwap` | Captures errors and exceptions | Debugging and transaction monitoring |
20+
| `EulerSwapCreated` | `EulerSwapFactory` | Emitted when a new `EulerSwap` instance is created | Track creation of new liquidity pools |
21+
| `PoolDeployed` | `EulerSwapFactory` | Indicates when a new liquidity pool is deployed | Detecting and listing new pools |
22+
23+
## Details
24+
25+
### Events in `EulerSwap.sol`
26+
27+
#### Liquidity management events
28+
29+
##### `AddLiquidity`
30+
31+
```solidity
32+
event AddLiquidity(address indexed provider, uint256 amount0, uint256 amount1);
33+
```
34+
35+
- **Purpose:** Emitted when liquidity is added to the pool.
36+
- **Parameters:**
37+
- `provider`: Address adding liquidity.
38+
- `amount0`, `amount1`: Quantities of `asset0` and `asset1` added.
39+
- **Use Case:** Helps liquidity providers and analytics tools track liquidity inflows.
40+
41+
##### `RemoveLiquidity`
42+
43+
```solidity
44+
event RemoveLiquidity(address indexed provider, uint256 amount0, uint256 amount1);
45+
```
46+
47+
- **Purpose:** Indicates when liquidity is withdrawn from the pool.
48+
- **Parameters:**
49+
- `provider`: Address removing liquidity.
50+
- `amount0`, `amount1`: Quantities of `asset0` and `asset1` withdrawn.
51+
- **Use Case:** Updates frontends and liquidity dashboards with outflows.
52+
53+
#### Trading events
54+
55+
##### `Swap`
56+
57+
```solidity
58+
event Swap(address indexed trader, address indexed assetIn, address indexed assetOut, uint256 amountIn, uint256 amountOut);
59+
```
60+
61+
- **Purpose:** Emitted during token swaps.
62+
- **Parameters:**
63+
- `trader`: Address executing the swap.
64+
- `assetIn`, `assetOut`: Assets being swapped.
65+
- `amountIn`, `amountOut`: Amounts involved in the swap.
66+
- **Use Case:** Crucial for trade analytics, swap history, and integration with trading UIs.
67+
68+
#### Fee & accounting events
69+
70+
##### `CollectFees`
71+
72+
```solidity
73+
event CollectFees(address indexed collector, uint256 fees0, uint256 fees1);
74+
```
75+
76+
- **Purpose:** Tracks when trading fees are collected.
77+
- **Parameters:**
78+
- `collector`: Address receiving the fees.
79+
- `fees0`, `fees1`: Fees collected in `asset0` and `asset1`.
80+
- **Use Case:** Important for revenue tracking and protocol fee management.
81+
82+
#### Administrative & status events
83+
84+
##### `StatusChanged`
85+
86+
```solidity
87+
event StatusChanged(uint32 oldStatus, uint32 newStatus);
88+
```
89+
90+
- **Purpose:** Signals a change in the contract's operational status.
91+
- **Parameters:**
92+
- `oldStatus`, `newStatus`: Numerical representation of the contract status (e.g., `0 = unactivated`, `1 = unlocked`, `2 = locked`).
93+
- **Use Case:** Enables dApps to adjust their behavior based on the contract state.
94+
95+
##### `DebtLimitUpdated`
96+
97+
```solidity
98+
event DebtLimitUpdated(uint112 newDebtLimit0, uint112 newDebtLimit1);
99+
```
100+
101+
- **Purpose:** Notifies when the debt limits for the assets are updated.
102+
- **Parameters:**
103+
- `newDebtLimit0`, `newDebtLimit1`: New debt limits for `asset0` and `asset1`.
104+
- **Use Case:** Supports risk management and off-chain monitoring of protocol settings.
105+
106+
### Events in `EulerSwapFactory.sol`
107+
108+
##### `EulerSwapCreated`
109+
110+
```solidity
111+
event EulerSwapCreated(address indexed asset0, address indexed asset1);
112+
```
113+
114+
- **Purpose:** Emitted when a new `EulerSwap` instance is created.
115+
- **Parameters:**
116+
- `asset0`, `asset1`: Addresses of the tokens in the newly created trading pair.
117+
- **Use Case:** Useful for tracking the creation of new liquidity pools and integrating with factory-based analytics.
118+
119+
##### `PoolDeployed`
120+
121+
```solidity
122+
event PoolDeployed(address indexed pool, address indexed asset0, address indexed asset1);
123+
```
124+
125+
- **Purpose:** Indicates when a new liquidity pool is deployed by the `EulerSwapFactory`.
126+
- **Parameters:**
127+
- `pool`: Address of the newly deployed pool.
128+
- `asset0`, `asset1`: Addresses of the tokens in the pool.
129+
- **Use Case:** Essential for detecting new pool deployments, often used by front-end interfaces to list available pools dynamically.
130+
131+
### Error handling events
132+
133+
##### `ErrorOccurred`
134+
135+
```solidity
136+
event ErrorOccurred(address indexed account, string message);
137+
```
138+
139+
- **Purpose:** Emitted when an error or unexpected condition occurs.
140+
- **Parameters:**
141+
- `account`: Address involved in the error.
142+
- `message`: Description of the error.
143+
- **Use Case:** Useful for debugging and alerting systems about failed transactions or invalid operations.

0 commit comments

Comments
 (0)