iotexproject/iotex-core
GitHub: iotexproject/iotex-core
IoTeX 区块链协议的官方 Go 实现，为 DePIN 项目提供高吞吐量、EVM 兼容的模块化 Layer-1 基础设施。
Stars: 1610 | Forks: 367
# iotex-core
IoTeX 协议的官方 Golang 实现，这是模块化的 DePIN Layer-1 网络。
## 什么是 IoTeX？
IoTeX 是为 DePIN 项目提供的模块化基础设施，支持全面部署或将模块集成到现有的框架中。请访问 [IoTeX 主页](https://iotex.io) 官方网站，以了解更多关于 IoTeX 网络的信息。
## 什么是 DePIN？
### 探索 DePIN 项目？
[DePIN Scan](https://depinscan.io/) 是 DePIN 项目的首选浏览器。DePIN Scan 跟踪加密代币价格、实时设备数据，并为 DePIN 项目提供多种视图。
## 运行 delegate？
请访问 [IoTeX Delegate 手册](https://github.com/iotexproject/iotex-bootstrap) 获取详细的设置流程。
## 构建源代码
### 最低要求
| 组件 | 版本 | 描述 |
|----------|-------------|-------------|
| [Golang](https://golang.org) | ≥ 1.22.12 | Go 编程语言 |
| [Protoc](https://developers.google.com/protocol-buffers/) | ≥ 3.6.0 | Protocol buffers，仅在重新构建 protobuf 消息时需要 |
### 编译
将代码下载到您希望的本地位置（不需要放在 `$GOPATH/src` 目录下）
```
git clone git@github.com:iotexproject/iotex-core.git
cd iotex-core
```
如果您将项目代码放在 `$GOPATH\src` 目录下，您需要设置一个环境变量
```
export GO111MODULE=on
set GO111MODULE=on (for windows)
```
通过以下命令构建通用用途（server、ioctl）的项目
```
make
```
通过以下命令构建更广泛用途（server、ioctl、injector...）的项目
```
make all
```
如果需要更新依赖，请运行
```
go get -u
go mod tidy
```
如果您想了解关于 `go mod` 的更多高级用法，可以在[这里](https://github.com/golang/go/wiki/Modules)找到。
仅运行单元测试
```
make test
```
构建 docker 镜像
```
make docker
```
### 运行 iotex-core
通过以下命令启动（或恢复）一个独立的服务器来运行区块链
```
make run
```
通过以下命令从干净的状态重启服务器
```
make reboot
```
如果“make run”由于状态数据库损坏或缺失而失败，但区块数据库状态正常时，例如：
无法从底层数据库获取 factory 的高度，请尝试通过以下命令恢复状态数据库
```
make recover
```
然后再次执行“make run”。
### 使用 CLI
用户可以通过以下命令与 iotex 区块链进行交互
```
ioctl [command]
```
请参阅 [ioctl CLI 文档](https://docs.iotex.io/blockchain/build/web3-development/ioctl-cli) 获取更多详细信息。
## IOSwarm：分布式交易验证
IOSwarm 为 iotex-core 添加了一个可选的 coordinator，它通过 gRPC 将待处理的交易验证任务分发给外部 agent。它以 **shadow mode** 运行 —— 仅作观察用途，对共识或区块生产零影响。支持 L1–L4 验证级别，包括完整的 EVM 重新执行 (L3) 和有状态的本地验证 (L4)。
### 工作原理
```
Delegate Node (iotex-core + IOSwarm coordinator)
├── actpool → pending txs
├── stateDB → account state prefetch + SimulateAccessList (L3)
├── gRPC :14689 → dispatch tasks to agents
├── HTTP :14690 → monitoring API (/api/stats, /swarm/shadow)
└── StateDiff stream → real-time state sync for L4 agents
Agent Swarm (external processes)
├── L1: signature verify
├── L2: + nonce/balance checks
├── L3: + full EVM execution (100% shadow accuracy)
├── L4: + local state (BoltDB), independent validation
└── Earn IOTX rewards per epoch (on-chain settlement)
```
### 快速部署（已有 delegate）
完整的 delegate 接入指南请参见 [ioswarm/README.md](ioswarm/README.md)。
**1. 拉取镜像：**
```
docker pull raullen/iotex-core:ioswarm-v14
```
**2. 将 IOSwarm 配置添加到您的 `config.yaml` 中：**
```
ioswarm:
enabled: true
grpcPort: 14689
swarmApiPort: 14690
maxAgents: 100
taskLevel: "L4"
shadowMode: true
pollIntervalMs: 1000
masterSecret: ""
epochRewardIOTX: 0.5
diffStoreEnabled: true
diffStorePath: "/var/data/statediffs.db"
rewardContract: "0x236CBF52125E68Db8fA88b893CcaFB2EE542F2d9"
rewardSignerKey: ""
reward:
delegateCutPct: 10
epochBlocks: 1
minTasksForReward: 1
bonusAccuracyPct: 99.5
bonusMultiplier: 1.2
```
**3. 重启 delegate 并开放额外端口：**
```
docker stop iotex && docker rm iotex
docker run -d --restart on-failure --name iotex \
-p 4689:4689 -p 14014:14014 \
-p 127.0.0.1:14689:14689 -p 127.0.0.1:14690:14690 \
-v=$IOTEX_HOME/data:/var/data:rw \
-v=$IOTEX_HOME/log:/var/log:rw \
-v=$IOTEX_HOME/etc/config.yaml:/etc/iotex/config_override.yaml:ro \
-v=$IOTEX_HOME/etc/genesis.yaml:/etc/iotex/genesis.yaml:ro \
raullen/iotex-core:ioswarm-v14 \
iotex-server \
-config-path=/etc/iotex/config_override.yaml \
-genesis-path=/etc/iotex/genesis.yaml
```
**4. 连接一个 agent：**
```
# 生成 agent key
go run ./ioswarm/cmd/keygen --master= --agent=agent-01
# 启动 agent
./ioswarm-agent \
--coordinator=:14689 \
--agent-id=agent-01 \
--api-key= \
--level=L2
```
**5. 监控：**
```
# 日志
docker logs -f iotex | grep -i ioswarm
# Status API
curl http://localhost:14690/swarm/status
curl http://localhost:14690/swarm/agents
curl http://localhost:14690/swarm/shadow
```
### 安全保障
- **默认关闭：** `ioswarm.enabled` 默认值为 `false` —— 除非明确启用，否则零影响
- **非致命错误：** 如果 IOSwarm 启动失败（端口冲突等），delegate 会记录一条警告并继续正常运行
- **Panic 隔离：** 所有 IOSwarm goroutine 都具有 `defer recover()` —— IOSwarm 中的 panic 不会导致节点崩溃
- **优雅关闭：** gRPC 停止设有 5 秒超时，以防止阻塞节点关闭
- **Shadow mode：** Agent 的结果仅用于比较，绝不会影响区块生产
### 相比 v2.3.5 有哪些变化
IOSwarm 的集成仅涉及 2 个现有文件：
| 文件 | 变更 |
|------|--------|
| `config/config.go` | +3 行：Config 结构体中的 `IOSwarm` 字段 |
| `server/itx/server.go` | +21 行：coordinator 的条件性 Start/Stop |
其他所有内容都在新的 `ioswarm/` 目录中。当 `ioswarm.enabled: false`（默认）时，不会执行任何新的代码路径。
## 联系方式
- 邮件列表：[iotex-dev](iotex-dev@iotex.io)
- 开发者论坛：[forum](https://community.iotex.io/c/research-development/protocol)
- Bug 反馈：[issues](https://github.com/iotexproject/iotex-core/issues)
## 贡献
对于任何重大的协议层更改，我们使用 [IIP](https://github.com/iotexproject/iips) 来跟踪提案、决策
等内容。
## 许可证
本项目基于 [Apache License 2.0](LICENSE) 授权。
## 什么是 IoTeX？
IoTeX 是为 DePIN 项目提供的模块化基础设施，支持全面部署或将模块集成到现有的框架中。请访问 [IoTeX 主页](https://iotex.io) 官方网站，以了解更多关于 IoTeX 网络的信息。
## 什么是 DePIN？
### 探索 DePIN 项目？
[DePIN Scan](https://depinscan.io/) 是 DePIN 项目的首选浏览器。DePIN Scan 跟踪加密代币价格、实时设备数据，并为 DePIN 项目提供多种视图。
## 运行 delegate？
请访问 [IoTeX Delegate 手册](https://github.com/iotexproject/iotex-bootstrap) 获取详细的设置流程。
## 构建源代码
### 最低要求
| 组件 | 版本 | 描述 |
|----------|-------------|-------------|
| [Golang](https://golang.org) | ≥ 1.22.12 | Go 编程语言 |
| [Protoc](https://developers.google.com/protocol-buffers/) | ≥ 3.6.0 | Protocol buffers，仅在重新构建 protobuf 消息时需要 |
### 编译
将代码下载到您希望的本地位置（不需要放在 `$GOPATH/src` 目录下）
```
git clone git@github.com:iotexproject/iotex-core.git
cd iotex-core
```
如果您将项目代码放在 `$GOPATH\src` 目录下，您需要设置一个环境变量
```
export GO111MODULE=on
set GO111MODULE=on (for windows)
```
通过以下命令构建通用用途（server、ioctl）的项目
```
make
```
通过以下命令构建更广泛用途（server、ioctl、injector...）的项目
```
make all
```
如果需要更新依赖，请运行
```
go get -u
go mod tidy
```
如果您想了解关于 `go mod` 的更多高级用法，可以在[这里](https://github.com/golang/go/wiki/Modules)找到。
仅运行单元测试
```
make test
```
构建 docker 镜像
```
make docker
```
### 运行 iotex-core
通过以下命令启动（或恢复）一个独立的服务器来运行区块链
```
make run
```
通过以下命令从干净的状态重启服务器
```
make reboot
```
如果“make run”由于状态数据库损坏或缺失而失败，但区块数据库状态正常时，例如：
无法从底层数据库获取 factory 的高度，请尝试通过以下命令恢复状态数据库
```
make recover
```
然后再次执行“make run”。
### 使用 CLI
用户可以通过以下命令与 iotex 区块链进行交互
```
ioctl [command]
```
请参阅 [ioctl CLI 文档](https://docs.iotex.io/blockchain/build/web3-development/ioctl-cli) 获取更多详细信息。
## IOSwarm：分布式交易验证
IOSwarm 为 iotex-core 添加了一个可选的 coordinator，它通过 gRPC 将待处理的交易验证任务分发给外部 agent。它以 **shadow mode** 运行 —— 仅作观察用途，对共识或区块生产零影响。支持 L1–L4 验证级别，包括完整的 EVM 重新执行 (L3) 和有状态的本地验证 (L4)。
### 工作原理
```
Delegate Node (iotex-core + IOSwarm coordinator)
├── actpool → pending txs
├── stateDB → account state prefetch + SimulateAccessList (L3)
├── gRPC :14689 → dispatch tasks to agents
├── HTTP :14690 → monitoring API (/api/stats, /swarm/shadow)
└── StateDiff stream → real-time state sync for L4 agents
Agent Swarm (external processes)
├── L1: signature verify
├── L2: + nonce/balance checks
├── L3: + full EVM execution (100% shadow accuracy)
├── L4: + local state (BoltDB), independent validation
└── Earn IOTX rewards per epoch (on-chain settlement)
```
### 快速部署（已有 delegate）
完整的 delegate 接入指南请参见 [ioswarm/README.md](ioswarm/README.md)。
**1. 拉取镜像：**
```
docker pull raullen/iotex-core:ioswarm-v14
```
**2. 将 IOSwarm 配置添加到您的 `config.yaml` 中：**
```
ioswarm:
enabled: true
grpcPort: 14689
swarmApiPort: 14690
maxAgents: 100
taskLevel: "L4"
shadowMode: true
pollIntervalMs: 1000
masterSecret: "标签：DeFi, DePIN, EVM, EVTX分析, Golang, IoTeX, Python工具, Web3, 区块链, 安全编程, 日志审计, 请求拦截