# 区块链开发规范 - CODING-STANDARDS-BLOCKCHAIN

**版本**: 2.0.0
**适用范围**: 区块链开发岗位（智能合约/DApp/链开发，平台无关）
**最后更新**: 2025-12-25

---

## 🚨 核心铁律（继承自 common.md）

> **必须遵循 common.md 的四大核心铁律**

```
铁律1: SPEC 是唯一真源（SSOT）
       - 智能合约必须符合 SPEC 定义
       - 接口、事件、权限以 SPEC 为准

铁律2: 智能复用与销毁重建
       - 现有合约完全匹配 → 直接复用
       - 部分匹配 → 重新部署新合约

铁律3: 禁止渐进式开发
       - 禁止在旧合约上添加新功能
       - 禁止保留兼容性函数

铁律4: Context7 调研先行
       - 使用成熟的安全库（OpenZeppelin）
       - 禁止自己实现加密/认证功能
```

---

## 🔒 智能合约安全

### 安全原则
- ✅ 默认安全（Secure by Default）
- ✅ 最小权限原则
- ✅ 防御性编程
- ✅ 代码审计（第三方审计）
- ❌ 永远不要假设输入可信

### 常见漏洞防护
- ✅ 重入攻击防护（Reentrancy Guard）
- ✅ 整数溢出/下溢检查（SafeMath）
- ✅ 前端运行防护（Front-Running）
- ✅ 时间戳依赖风险
- ✅ 自毁函数谨慎使用
- ❌ 禁止使用tx.origin进行授权

### 访问控制
- ✅ 使用修饰符（Modifier）控制权限
- ✅ 角色基础访问控制（RBAC）
- ✅ 多签机制（关键操作）
- ✅ 时间锁（Timelock）
- ❌ 避免单点故障（单一管理员）

---

## ⛽ Gas优化

### 存储优化
- ✅ 减少存储操作（最贵）
- ✅ 打包变量（Struct Packing）
- ✅ 使用事件代替存储
- ✅ 短路求值
- ✅ 删除不用的存储释放Gas
- ❌ 避免动态数组（无限增长）

### 代码优化
- ✅ 使用常量和不可变变量
- ✅ 缓存状态变量到内存
- ✅ 循环优化（减少迭代）
- ✅ 函数可见性明确（external vs public）
- ✅ 使用库（Library）共享代码
- ❌ 避免不必要的计算

### 调用优化
- ✅ 批量操作（减少交易次数）
- ✅ 使用委托调用（delegatecall）复用逻辑
- ✅ 预估Gas限制
- ❌ 避免无限循环

---

## 🏗️ 合约设计

### 架构模式
- ✅ 单一职责合约
- ✅ 代理模式（可升级合约）
- ✅ 工厂模式（批量部署）
- ✅ 注册模式（合约发现）
- ❌ 避免单体合约（过大）

### 可升级性
- ✅ 使用代理合约（Proxy Pattern）
- ✅ 存储和逻辑分离
- ✅ 初始化函数代替构造函数
- ✅ 升级机制安全（多签/时间锁）
- ❌ 避免破坏存储布局

### 模块化
- ✅ 接口定义清晰
- ✅ 库合约复用
- ✅ 合约间松耦合
- ✅ 事件驱动通信
- ❌ 避免循环依赖

---

## 💰 代币和资产

### ERC标准遵循
- ✅ 严格遵循ERC-20/721/1155标准
- ✅ 完整实现必需接口
- ✅ 事件正确触发
- ✅ 返回值和异常处理
- ❌ 不要修改标准接口

### 资产安全
- ✅ 转账前检查余额
- ✅ 批准机制（Approval）
- ✅ 防止意外销毁
- ✅ 支持紧急暂停（Pausable）
- ❌ 禁止自动铸币（Mint）漏洞

### 精度处理
- ✅ 使用定点数（避免浮点数）
- ✅ 明确精度单位
- ✅ 防止精度损失
- ✅ 除法放在最后
- ❌ 避免除零错误

---

## 📡 事件和日志

### 事件设计
- ✅ 关键状态变更触发事件
- ✅ 事件参数indexed（可搜索）
- ✅ 事件命名清晰（动词+名词）
- ✅ 事件包含足够上下文
- ❌ 不要过度使用indexed（最多3个）

### 日志优化
- ✅ 使用事件代替存储（节省Gas）
- ✅ 链下索引事件
- ✅ 事件版本化（升级兼容）
- ❌ 避免敏感数据记录到事件

---

## 🔐 密码学

### 签名验证
- ✅ 使用标准签名算法（ECDSA）
- ✅ 防重放攻击（Nonce/时间戳）
- ✅ 签名消息哈希化
- ✅ 验证签名者身份
- ❌ 禁止直接使用私钥

### 哈希函数
- ✅ 使用keccak256进行哈希
- ✅ 哈希前拼接数据类型（防碰撞）
- ✅ Merkle树验证
- ❌ 避免使用弱哈希算法

### 随机数
- ✅ 使用可验证随机函数（VRF）
- ✅ 链下随机数+链上验证
- ❌ 禁止使用区块哈希作为随机源（可预测）
- ❌ 禁止使用block.timestamp作为随机源

---

## 🧪 测试

### 测试覆盖
- ✅ 单元测试（每个函数）
- ✅ 集成测试（合约交互）
- ✅ 边界测试（极值/溢出）
- ✅ 安全测试（漏洞扫描）
- ✅ Gas消耗测试
- ✅ 升级测试（可升级合约）

### 测试网部署
- ✅ 在测试网充分测试
- ✅ 模拟真实场景
- ✅ 压力测试
- ✅ 第三方集成测试
- ❌ 不要直接在主网部署未测试代码

### 形式化验证
- ✅ 关键合约形式化验证
- ✅ 不变量检查
- ✅ 属性测试
- ✅ 符号执行

---

## 🌐 DApp开发

### 前端集成
- ✅ 使用Web3库（ethers.js/web3.js）
- ✅ 钱包连接（MetaMask/WalletConnect）
- ✅ 网络切换提示
- ✅ 交易状态追踪
- ✅ 错误处理和用户提示
- ❌ 不要在前端存储私钥

### 用户体验
- ✅ 交易确认前显示Gas估算
- ✅ 等待交易确认时显示加载
- ✅ 交易失败友好提示
- ✅ 支持交易加速/取消
- ❌ 避免无响应的等待

---

## 🔧 部署和运维

### 部署流程
- ✅ 使用脚本自动化部署
- ✅ 多签部署关键合约
- ✅ 验证合约源码（Etherscan）
- ✅ 记录合约地址和交易哈希
- ✅ 文档化部署步骤
- ❌ 避免手动部署（易出错）

### 监控和告警
- ✅ 监控合约状态
- ✅ 异常活动告警
- ✅ 余额监控
- ✅ Gas价格监控
- ✅ 事件监听

### 紧急响应
- ✅ 暂停机制（Circuit Breaker）
- ✅ 紧急提款功能
- ✅ 升级/修复流程
- ✅ 事件响应预案
- ❌ 不要依赖单点控制

---

## 📋 区块链开发检查清单

- [ ] 重入攻击和整数溢出防护
- [ ] 访问控制和权限管理
- [ ] Gas优化（存储、计算、调用）
- [ ] 事件完整触发
- [ ] 遵循ERC标准（代币合约）
- [ ] 测试网充分测试
- [ ] 安全审计（第三方）
- [ ] 可升级性和紧急暂停
- [ ] 前端集成和用户体验
- [ ] 部署脚本和监控

---

---

## 🏛️ 高级区块链架构（20+年经验）

### DeFi 协议架构
```
核心模式：
- AMM（自动做市商）：Uniswap v2/v3
- 借贷协议：Compound/Aave
- 稳定币机制：MakerDAO
- 收益聚合：Yearn

架构要点：
- 协议可组合性
- 闪电贷攻击防护
- 预言机依赖管理
- 治理机制设计

风险管理：
- 清算机制
- 抵押率监控
- 价格滑点保护
- 紧急暂停
```

### Layer 2 开发
```
扩容方案：
- Rollup：Optimistic/ZK
- 侧链：Polygon PoS
- 状态通道：Lightning Network
- Validium

开发要点：
- L1/L2 通信
- 数据可用性
- 提款延迟
- 跨链桥安全

ZK 技术：
- SNARKs/STARKs
- 证明生成和验证
- 电路设计
- 可信设置
```

### 跨链架构
```
跨链模式：
- 原子交换
- 哈希时间锁
- 中继链
- 桥接协议

安全考量：
- 桥接合约安全
- 验证者选择
- 多签门槛
- 欺诈证明

互操作协议：
- IBC（Cosmos）
- XCM（Polkadot）
- LayerZero
- Wormhole
```

---

## 🔧 资深区块链专家必备技巧

### 智能合约安全深度
```
审计方法：
- 手动代码审查
- 自动化工具（Slither/Mythril）
- 形式化验证（Certora）
- 模糊测试（Echidna）

攻击向量分析：
- 重入攻击变种
- 闪电贷攻击
- 预言机操纵
- 治理攻击
- MEV 攻击

防御模式：
- CEI（检查-效果-交互）
- 重入锁
- 价格 TWAP
- 时间锁治理
```

### Gas 优化深度
```
存储优化：
- 打包变量（256位槽）
- 映射 vs 数组
- 不可变变量（immutable）
- 瞬态存储（EIP-1153）

计算优化：
- 位运算替代除法
- 短路求值
- 缓存存储读取
- 内联汇编（Yul）

模式优化：
- Merkle 空投
- 批量操作
- 懒惰铸造
- 签名验证链下
```

### 升级模式深度
```
代理模式：
- 透明代理（TransparentProxy）
- UUPS 代理
- Beacon 代理
- Diamond 模式（EIP-2535）

存储布局：
- 存储槽管理
- 存储碰撞检测
- 升级兼容性检查
- 初始化器模式

升级安全：
- 多签治理
- 时间锁延迟
- 升级测试
- 回滚计划
```

### MEV 和交易排序
```
MEV 类型：
- 抢跑（Front-running）
- 夹击（Sandwich）
- 套利
- 清算

防护策略：
- 私有交易（Flashbots）
- 提交-揭示模式
- 时间锁
- 滑点保护

MEV 利用（合规）：
- 套利机器人
- 清算机器人
- Searcher 策略
```

---

## 🚨 资深区块链专家常见陷阱

### 安全陷阱
```
❌ 假设外部调用安全：
- 信任外部合约
- 无重入保护
- 正确做法：CEI 模式，重入锁

❌ 预言机单点依赖：
- 单一价格源
- 无延迟/均值处理
- 正确做法：多源聚合，TWAP

❌ 忽视权限管理：
- 过度集中权限
- 无时间锁
- 正确做法：多签，时间锁，渐进式去中心化
```

### 经济陷阱
```
❌ 经济模型缺陷：
- 代币经济不可持续
- 激励不对齐
- 正确做法：博弈论分析

❌ 清算机制不足：
- 清算延迟
- 价格下跌过快
- 正确做法：多级清算，保险基金

❌ 忽视闪电贷风险：
- 可被无成本攻击
- 正确做法：闪电贷防护，价格校验
```

### 运维陷阱
```
❌ 部署后不监控：
- 异常活动未发现
- 正确做法：事件监控，告警

❌ 无紧急响应计划：
- 攻击时手忙脚乱
- 正确做法：预案演练，紧急暂停

❌ 私钥管理不当：
- 热钱包存大额
- 正确做法：冷热分离，多签
```

---

## 📊 性能监控指标

| 指标 | 目标值 | 告警阈值 | 测量方法 |
|------|--------|----------|----------|
| Gas 消耗 | < 预算 | > 150% 预算 | 交易统计 |
| 交易成功率 | > 99% | < 95% | 链上分析 |
| 合约 TVL | 根据业务 | 异常变动 | 链上查询 |
| 治理参与率 | > 30% | < 10% | 治理统计 |
| 审计覆盖率 | 100% | < 100% | 审计报告 |
| 安全事件 | 0 | > 0 | 监控系统 |
| 清算健康度 | > 150% | < 120% | 协议统计 |
| 预言机延迟 | < 1分钟 | > 10分钟 | 监控系统 |
| 治理提案通过时间 | 根据设计 | 异常 | 治理统计 |
| 智能合约升级次数 | 根据需要 | 频繁异常 | 版本历史 |

---

## 📋 区块链开发检查清单（完整版）

### 安全检查
- [ ] 重入攻击防护
- [ ] 整数溢出检查
- [ ] 访问控制完整
- [ ] 预言机安全

### 经济设计
- [ ] 代币经济可持续
- [ ] 激励机制对齐
- [ ] 清算机制健全
- [ ] 闪电贷防护

### 代码质量
- [ ] 第三方审计
- [ ] 形式化验证
- [ ] 测试覆盖完整
- [ ] Gas 优化

### 运维准备
- [ ] 监控和告警
- [ ] 紧急暂停机制
- [ ] 升级流程
- [ ] 事件响应预案

---

**区块链开发原则总结**：
安全第一、Gas优化、代码审计、测试充分、可升级性、事件完整、访问控制、防御编程、用户体验、监控告警
