init
This commit is contained in:
268
README.md
268
README.md
@ -1,24 +1,270 @@
|
||||
# Uniswap V2
|
||||
# Uniswap V2 Core 核心合约
|
||||
|
||||
[](https://github.com/Uniswap/uniswap-v2-core/actions)
|
||||
[](https://www.npmjs.com/package/@uniswap/v2-core)
|
||||
|
||||
In-depth documentation on Uniswap V2 is available at [uniswap.org](https://uniswap.org/docs).
|
||||
## 📋 项目概述
|
||||
|
||||
The built contract artifacts can be browsed via [unpkg.com](https://unpkg.com/browse/@uniswap/v2-core@latest/).
|
||||
Uniswap V2 Core 是去中心化交易协议 Uniswap V2 的核心智能合约集合，实现了自动化做市商(AMM)机制。本项目包含了创建和管理流动性池、执行代币交换等核心功能的智能合约。
|
||||
|
||||
# Local Development
|
||||
### 🎯 核心特性
|
||||
|
||||
The following assumes the use of `node@>=10`.
|
||||
- **自动化做市商(AMM)**: 基于恒定乘积公式 `x * y = k` 的去中心化交易
|
||||
- **流动性挖矿**: 用户可以提供流动性获得手续费收入
|
||||
- **CREATE2 部署**: 使用确定性地址部署，便于前端集成
|
||||
- **EIP-712 支持**: 支持链下签名授权，提升用户体验
|
||||
- **时间加权平均价格(TWAP)**: 内置价格预言机功能
|
||||
|
||||
## Install Dependencies
|
||||
## 🏗️ 项目架构
|
||||
|
||||
`yarn`
|
||||
### 核心合约
|
||||
|
||||
## Compile Contracts
|
||||
```
|
||||
contracts/
|
||||
├── UniswapV2Factory.sol # 工厂合约，管理所有交易对的创建
|
||||
├── UniswapV2Pair.sol # 交易对合约，实现AMM核心逻辑
|
||||
├── UniswapV2ERC20.sol # 流动性代币，支持EIP-712
|
||||
├── interfaces/ # 接口定义
|
||||
│ ├── IUniswapV2Factory.sol
|
||||
│ ├── IUniswapV2Pair.sol
|
||||
│ ├── IUniswapV2ERC20.sol
|
||||
│ ├── IERC20.sol
|
||||
│ └── IUniswapV2Callee.sol
|
||||
├── libraries/ # 工具库
|
||||
│ ├── Math.sol # 数学运算库
|
||||
│ ├── SafeMath.sol # 安全数学运算
|
||||
│ └── UQ112x112.sol # 定点数运算
|
||||
└── test/ # 测试合约
|
||||
```
|
||||
|
||||
`yarn compile`
|
||||
### 合约关系图
|
||||
|
||||
## Run Tests
|
||||
```mermaid
|
||||
graph TB
|
||||
Factory[UniswapV2Factory<br/>工厂合约] --> Pair[UniswapV2Pair<br/>交易对合约]
|
||||
Pair --> ERC20[UniswapV2ERC20<br/>流动性代币]
|
||||
Pair --> SafeMath[SafeMath<br/>安全数学运算]
|
||||
Pair --> Math[Math<br/>数学库]
|
||||
Pair --> UQ112x112[UQ112x112<br/>定点数库]
|
||||
|
||||
User[用户] --> Factory
|
||||
User --> Pair
|
||||
LP[流动性提供者] --> Pair
|
||||
Trader[交易者] --> Pair
|
||||
```
|
||||
|
||||
`yarn test`
|
||||
## 🔧 核心概念
|
||||
|
||||
### 1. 自动化做市商(AMM)
|
||||
|
||||
Uniswap V2 使用恒定乘积公式实现自动化做市：
|
||||
|
||||
```
|
||||
x * y = k
|
||||
```
|
||||
|
||||
其中：
|
||||
- `x` 和 `y` 是池中两种代币的数量
|
||||
- `k` 是恒定值，只在添加/移除流动性时改变
|
||||
|
||||
### 2. 流动性提供
|
||||
|
||||
用户可以向交易对提供流动性，获得：
|
||||
- **流动性代币(LP Token)**: 代表在池中的份额
|
||||
- **交易手续费**: 每笔交易的0.3%手续费按比例分配
|
||||
|
||||
流动性计算公式：
|
||||
```solidity
|
||||
// 首次添加流动性
|
||||
liquidity = sqrt(amount0 * amount1) - MINIMUM_LIQUIDITY
|
||||
|
||||
// 后续添加流动性
|
||||
liquidity = min(amount0 * totalSupply / reserve0, amount1 * totalSupply / reserve1)
|
||||
```
|
||||
|
||||
### 3. 价格发现机制
|
||||
|
||||
交易价格由池中代币比例决定：
|
||||
```
|
||||
price = reserve1 / reserve0
|
||||
```
|
||||
|
||||
每次交易后，价格会自动调整以维持恒定乘积。
|
||||
|
||||
### 4. 时间加权平均价格(TWAP)
|
||||
|
||||
合约内置价格累积器，可以计算任意时间段的平均价格：
|
||||
```solidity
|
||||
price0CumulativeLast += (reserve1 / reserve0) * timeElapsed
|
||||
price1CumulativeLast += (reserve0 / reserve1) * timeElapsed
|
||||
```
|
||||
|
||||
## 💼 主要功能
|
||||
|
||||
### UniswapV2Factory (工厂合约)
|
||||
|
||||
**职责**: 创建和管理所有交易对
|
||||
|
||||
**核心函数**:
|
||||
- `createPair(address tokenA, address tokenB)`: 创建新的交易对
|
||||
- `getPair(address tokenA, address tokenB)`: 获取交易对地址
|
||||
- `allPairs(uint index)`: 按索引获取交易对
|
||||
- `setFeeTo(address feeTo)`: 设置协议费接收地址
|
||||
|
||||
**特点**:
|
||||
- 使用CREATE2确定性部署，地址可预测
|
||||
- 任何人都可以创建交易对
|
||||
- 自动排序代币地址确保唯一性
|
||||
|
||||
### UniswapV2Pair (交易对合约)
|
||||
|
||||
**职责**: 实现具体的AMM交易逻辑
|
||||
|
||||
**核心函数**:
|
||||
- `mint(address to)`: 铸造流动性代币
|
||||
- `burn(address to)`: 销毁流动性代币，取回资产
|
||||
- `swap(uint amount0Out, uint amount1Out, address to, bytes calldata data)`: 执行代币交换
|
||||
- `getReserves()`: 获取当前储备量和时间戳
|
||||
|
||||
**安全机制**:
|
||||
- 重入锁防止重入攻击
|
||||
- 最小流动性锁定防止攻击
|
||||
- 完整性检查确保K值不减少
|
||||
|
||||
### UniswapV2ERC20 (流动性代币)
|
||||
|
||||
**职责**: 标准ERC20流动性代币，支持高级功能
|
||||
|
||||
**核心功能**:
|
||||
- 标准ERC20功能 (转账、授权等)
|
||||
- EIP-712签名授权 (`permit`)
|
||||
- 域分隔符确保跨链安全
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 环境要求
|
||||
|
||||
- Node.js >= 10
|
||||
- Yarn 包管理器
|
||||
|
||||
### 安装依赖
|
||||
|
||||
```bash
|
||||
yarn install
|
||||
```
|
||||
|
||||
### 编译合约
|
||||
|
||||
```bash
|
||||
yarn compile
|
||||
```
|
||||
|
||||
### 运行测试
|
||||
|
||||
```bash
|
||||
yarn test
|
||||
```
|
||||
|
||||
### 代码检查
|
||||
|
||||
```bash
|
||||
yarn lint
|
||||
```
|
||||
|
||||
## 📖 使用示例
|
||||
|
||||
### 1. 部署工厂合约
|
||||
|
||||
```solidity
|
||||
// 部署工厂合约
|
||||
UniswapV2Factory factory = new UniswapV2Factory(msg.sender);
|
||||
```
|
||||
|
||||
### 2. 创建交易对
|
||||
|
||||
```solidity
|
||||
// 创建 WETH/USDC 交易对
|
||||
address pair = factory.createPair(WETH, USDC);
|
||||
```
|
||||
|
||||
### 3. 添加流动性
|
||||
|
||||
```solidity
|
||||
// 向交易对转入代币
|
||||
IERC20(WETH).transfer(pair, wethAmount);
|
||||
IERC20(USDC).transfer(pair, usdcAmount);
|
||||
|
||||
// 铸造流动性代币
|
||||
uint liquidity = IUniswapV2Pair(pair).mint(msg.sender);
|
||||
```
|
||||
|
||||
### 4. 执行交换
|
||||
|
||||
```solidity
|
||||
// 计算输出数量 (需要使用路由合约)
|
||||
uint amountOut = getAmountOut(amountIn, reserveIn, reserveOut);
|
||||
|
||||
// 转入代币
|
||||
IERC20(tokenIn).transfer(pair, amountIn);
|
||||
|
||||
// 执行交换
|
||||
IUniswapV2Pair(pair).swap(amount0Out, amount1Out, msg.sender, "");
|
||||
```
|
||||
|
||||
## 🔐 安全考虑
|
||||
|
||||
### 重入攻击防护
|
||||
- 所有状态修改函数都使用重入锁
|
||||
- 采用检查-生效-交互模式
|
||||
|
||||
### 整数溢出防护
|
||||
- 使用SafeMath库防止算术溢出
|
||||
- 严格的边界检查
|
||||
|
||||
### 经济安全
|
||||
- 最小流动性锁定(1000 wei)
|
||||
- K值单调性检查
|
||||
- 合理的手续费机制
|
||||
|
||||
### 前端安全
|
||||
- CREATE2确定性地址
|
||||
- 完整的事件日志
|
||||
- 标准化接口
|
||||
|
||||
## 📚 深入学习
|
||||
|
||||
### 相关资源
|
||||
|
||||
- [Uniswap V2 白皮书](https://uniswap.org/whitepaper.pdf)
|
||||
- [官方文档](https://uniswap.org/docs)
|
||||
- [Solidity 最佳实践](https://consensys.github.io/smart-contract-best-practices/)
|
||||
|
||||
### 构建工件
|
||||
|
||||
编译后的合约可通过 [unpkg.com](https://unpkg.com/browse/@uniswap/v2-core@latest/) 浏览。
|
||||
|
||||
## 🤝 贡献指南
|
||||
|
||||
欢迎提交 Issue 和 Pull Request！
|
||||
|
||||
### 开发流程
|
||||
|
||||
1. Fork 本仓库
|
||||
2. 创建功能分支
|
||||
3. 提交更改
|
||||
4. 运行测试
|
||||
5. 提交 Pull Request
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
本项目采用 [GPL-3.0-or-later](LICENSE) 许可证。
|
||||
|
||||
## 🙏 致谢
|
||||
|
||||
- Uniswap 团队的创新设计
|
||||
- DappHub 的 SafeMath 库
|
||||
- 以太坊社区的支持
|
||||
|
||||
---
|
||||
|
||||
**⚠️ 风险提示**: 本项目仅供学习和研究使用。在生产环境中使用前，请进行充分的安全审计。去中心化金融存在智能合约风险、无常损失等风险，请谨慎参与。
|
||||
|
||||
Reference in New Issue
Block a user