# Monad 区块链开发助手

`区块链` `智能合约` `Monad` `DeFi` `Foundry` `AI辅助开发`

# Monad Wingman

一款以 Agent Skill 形式构建的 Monad 区块链开发全能导师与指南。涵盖使用 Foundry + Scaffold-Monad 工具链进行智能合约开发、DeFi 协议集成，以及针对 Monad 并行执行 EVM 兼容 L1 的安全最佳实践。

## 快速开始

**在 AI 辅助下从零构建 Monad dApp：**

```bash
# 1. 创建新项目目录
mkdir my-monad-project
cd my-monad-project

# 2. 安装 Monad Wingman skill
npx skills add monad-wingman

# 3. 用 Cursor（或其他支持 AI 的编辑器）打开
cursor .
```

**然后直接告诉 AI 你想构建什么：**

> "帮我在 Monad 上构建一个质押合约"

> "创建一个带买卖功能的代币"

> "构建一个 NFT 系列并部署到 Monad 测试网"

Monad Wingman 将会：
- 搭建 Foundry 或 Scaffold-Monad 项目
- 为 Monad 进行配置（prague EVM、--legacy 标志、正确的链 ID）
- 提醒你关键的注意事项（gas 上限计费、代币精度、重入攻击等）
- 指导安全最佳实践
- 附带正确的验证步骤将合约部署到 Monad 测试网

---

## 什么是 Monad Wingman？

Monad Wingman 是一套知识库与提示词系统，帮助 AI 代理协助开发者在 Monad 上进行开发。内容涵盖：

- **智能合约挑战**：12 个学习模块（NFT、质押、DEX、借贷、预言机等）
- **Foundry 工具链**：以 forge 脚本、Anvil 测试、Monad 部署为核心的主要工作流
- **Scaffold-Monad**：含 React/Next.js 前端的全栈 dApp 脚手架
- **DeFi 协议**：Monad 上的 Uniswap V3、Euler、Morpho、Kuru、Fastlane、Pyth 使用模式
- **ERC 标准**：ERC-20、721、1155、4626 的完整指南
- **Monad 架构**：并行执行、MonadBFT、gas 上限计费、储备余额
- **安全性**：关键注意事项（通用 + Monad 专属）、历史漏洞案例、上线前检查清单

## 安装

### 通过 skills.sh 安装（推荐）
```bash
npx skills add monad-wingman
```

兼容 Cursor、Claude Code、Codex、OpenCode 及其他 AI 编程助手。

### 手动安装

**Cursor：**
将 `.cursorrules` 复制到项目根目录，或添加到 Cursor 全局规则中。

**Claude Code：**
在项目说明中引用 `CLAUDE.md` 文件。

## 目录结构

```
monad-wingman/
├── skills/
│   └── monad-wingman/       # skills.sh 兼容包
│       ├── SKILL.md          # 含 frontmatter 的 Skill 定义
│       ├── AGENTS.md         # 完整编译后的指令
│       ├── metadata.json     # Skill 元数据
│       ├── README.md         # Skill 文档
│       ├── scripts/          # 辅助脚本
│       │   ├── init-project.sh
│       │   └── check-gotchas.sh
│       └── references/       # 核心知识文件
├── knowledge/
│   ├── challenges/      # 12 个智能合约挑战模块
│   ├── protocols/       # DeFi 协议文档（Uniswap、Euler、Morpho、Kuru 等）
│   ├── standards/       # ERC 标准
│   ├── foundations/     # Monad 基础、Solidity、预言机、生态系统
│   └── gotchas/         # 安全知识
├── tools/
│   ├── scaffold-eth/    # Scaffold-Monad 文档
│   ├── deployment/      # 部署模式
│   ├── testing/         # 前端测试
│   └── security/        # 安全工具
├── prompts/             # AI 代理提示词（构建、教学、审查、调试）
├── data/
│   └── addresses/       # Monad 上的代币、协议、鲸鱼地址
├── AGENTS.md            # skills/monad-wingman/AGENTS.md 的软链接
├── skill.json           # Skill 清单
├── .cursorrules         # Cursor IDE 集成
└── CLAUDE.md            # Claude Code 集成
```

## 核心概念

### 最重要的概念

**链上没有任何事情是自动发生的。**

智能合约无法自动执行。对于任何"需要发生"的函数：
1. 让**任何人**都可以调用（而非仅限管理员）
2. 给调用者一个**理由**（利润、奖励、自身利益）
3. 确保激励**足以**覆盖 gas 费用并有盈余

Wingman 始终会问：*"谁来调用这个函数？他们为何要支付 gas？"*

### 关键注意事项

每位 Monad 开发者必须了解：

1. **代币精度各异**：USDC = 6 位，WBTC = 8 位，大多数 = 18 位
2. **需要 Approve 模式**：合约在调用 transferFrom 前需要授权
3. **重入攻击**：始终使用检查-效果-交互模式 + ReentrancyGuard
4. **预言机操纵**：永远不要使用 DEX 现货价格
5. **无浮点数**：使用基点（500/10000 = 5%）
6. **Gas 上限计费（Monad）**：按 gas_limit 收费，而非实际用量——请设置严格上限！
7. **储备余额（Monad）**：EIP-7702 委托 EOA 的余额不能低于 10 MON
8. **--legacy 标志（Monad）**：在 Monad 上使用 forge/cast 时始终加上 `--legacy`

### Monad 链配置

| 网络 | 链 ID | RPC |
|------|-------|-----|
| 主网 | 143 | https://rpc.monad.xyz |
| 测试网（默认） | 10143 | https://testnet-rpc.monad.xyz |
| 本地（Anvil） | 31337 | http://localhost:8545 |

- **原生代币**：MON（18 位精度）
- **EVM 版本**：prague
- **Solidity**：推荐 0.8.28
- **合约最大体积**：128KB

### 智能合约挑战

| 挑战 | 概念 |
|------|------|
| 简单 NFT | ERC-721、铸造、元数据 |
| 去中心化质押 | 协调机制、截止日期、托管 |
| 代币售卖机 | ERC-20 授权模式 |
| 骰子游戏 | 随机数漏洞 |
| DEX | AMM、恒定乘积公式 |
| 预言机 | 价格数据源、防操纵 |
| 借贷 | 抵押机制、清算 |
| 稳定币 | 锚定机制 |
| 预测市场 | 结果结算 |
| ZK 投票 | 隐私保护治理 |
| 多签 | 门限签名 |
| SVG NFT | 链上生成艺术 |

## 使用示例

### 构建模式
- "帮我在 Monad 上构建一个带买卖功能的代币"
- "搭建一个带奖励的质押合约"
- "用 Scaffold-Monad 创建一个 NFT 铸造页面"

### 教学模式
- "Monad 上的并行执行是如何工作的？"
- "解释 AMM 中的恒定乘积公式"
- "借贷协议有哪些安全注意事项？"

### 代码审查模式
- "检查这个提款函数是否存在漏洞"
- "检查这个 vault 合约是否存在通胀攻击风险"
- "审计这个 Monad 上的预言机集成"

### 调试模式
- "为什么我的交易在 Monad 测试网上回滚了？"
- "我遇到了 'transaction type not supported' 错误——怎么解决？"
- "调试这个 gas 不足的问题"

## Monad 上的 DeFi 协议

- **Uniswap V3** —— AMM，集中流动性
- **Euler** —— 模块化借贷协议
- **Morpho** —— 借贷优化
- **Kuru** —— Monad 原生订单簿 DEX
- **Fastlane** —— MEV 基础设施
- **Chainlink / Pyth** —— 预言机与价格数据源
- **Kintsu / Magma** —— 流动性质押（shMON、gMON）
- **LayerZero / Wormhole** —— 跨链桥

## 贡献

添加新内容：
1. 将 Markdown 文件添加到对应目录
2. 遵循现有格式（代码示例、安全说明）
3. 如添加新功能，更新 skill.json
4. 与 AI 代理测试以确保内容清晰

## 资源

- [Monad 文档](https://docs.monad.xyz)
- [Monad LLM 文档](https://docs.monad.xyz/llms.txt)
- [Scaffold-Monad Foundry](https://github.com/monad-developers/scaffold-monad-foundry)
- [MonadVision 浏览器](https://monadvision.com)
- [Monadscan 浏览器](https://monadscan.com)
- [Monad 水龙头](https://faucet.monad.xyz)
- [OpenZeppelin](https://openzeppelin.com/)

## 许可证

MIT 许可证——可自由用于学习和开发。

## 致谢

为 Monad 开发者社区而构建。

派生自 [BuidlGuidl](https://buidlguidl.com/) 的 [Ethereum Wingman](https://github.com/BuidlGuidl/ethereum-wingman)。原版 Ethereum Wingman 提供了基础知识库结构和智能合约挑战体系。Monad Wingman 在此基础上针对 Monad 生态系统进行了适配与扩展，新增了 Monad 专属工具链、注意事项、部署工作流及 DeFi 协议文档。

整合了来自以下来源的知识：
- [Monad 文档](https://docs.monad.xyz)
- [BuidlGuidl / Scaffold-ETH](https://buidlguidl.com/)
- [OpenZeppelin](https://openzeppelin.com/)
- [Chainlink](https://chain.link/)
- [Pyth Network](https://pyth.network/)