UfkuAcik/Embedded_Proof-of-Device_Network
GitHub: UfkuAcik/Embedded_Proof-of-Device_Network
EPDN 是一个基于 ESP32 嵌入式设备的实验性区块链测试网络，研究无需算力竞争的设备身份证明共识机制。
Stars: 1 | Forks: 0
# 嵌入式设备证明网络 (EPDN)
**一个开源的 MVP，旨在研究如何让已注册的嵌入式设备在不进行算力竞争的情况下加入测试网络。**
[](https://github.com/UfkuAcik/EPDN-Network/actions/workflows/ci.yml)
## 一分钟了解 EPDN
您可以将 EPDN 想象成一种抽奖：
1. 嵌入式设备首先注册到网络中。
2. 在每个 **30 秒的轮次**中，已注册的身份最多可获得一次抽签资格。
3. 设备使用其私钥对票（Ticket）进行签名。
4. Validator（验证者）验证票、设备证书和网络规则。
5. 数值分数最低的有效票赢得该轮。
6. 获胜者指定的钱包地址将获得仅在测试网络中使用的奖励。
```
flowchart LR
A["1. Cihaz kaydedilir"] --> B["2. Tur için tek bilet üretir"]
B --> C["3. Bileti cihaz imzalar"]
C --> D["4. Validator kuralları doğrular"]
D --> E["5. En düşük puan kazanır"]
E --> F["6. Blok ve test ödülü oluşur"]
```
这里的关键区别在于：在经典的 Proof of Work（工作量证明）系统中，更高的算力意味着更多的尝试次数。而在 EPDN 中，对于同一个已注册的身份，使用更快的 CPU、GPU、FPGA 或 ASIC 并不能获得额外的票。
## 目录
- [一分钟了解 EPDN](#bir-dakikada-epdn)
- [该项目研究什么问题？](#hangi-problem)
- [EPDN 是什么，不是什么？](#nedir-ne-degildir)
- [当前状态](#mevcut-durum)
- [核心概念词汇表](#sozluk)
- [系统架构](#mimari)
- [组件及其任务](#bilesenler)
- [端到端工作流](#calisma-akisi)
- [PoPED 如何工作？](#poped)
- [一个 epoch 内会发生什么？](#epoch)
- [为什么设备身份与钱包是分开的？](#anahtar-ayrimi)
- [硬件支持](#donanim-destegi)
- [安全等级](#guvenlik-siniflari)
- [信任与威胁模型](#guven-modeli)
- [隐私与数据边界](#gizlilik)
- [快速入门](#hizli-baslangic)
- [路径 1：仅查看界面](#arayuz-demo)
- [路径 2：本地 validator 和 dashboard](#yerel-validator)
- [路径 3：三进程测试](#uc-surecli-test)
- [路径 4：编译 ESP32 代码](#esp32-derleme)
- [仓库结构](#depo-yapisi)
- [API 摘要](#api-ozeti)
- [测试与质量门禁](#testler)
- [已知局限](#sinirlar)
- [文档](#belgeler)
- [路线图](#yol-haritasi)
- [贡献与安全报告](#katki)
- [许可证](#lisans)
## 该项目研究什么问题？
许多区块链系统通过算力、资金或其他稀缺资源来限制参与者。EPDN 研究以下问题：
这种方法将三件事分开：
- **设备的参与身份：** 用于设备对票进行签名。
- **钱包所有权：** 用于接收奖励和签署转账。
- **网络验证：** Validator 执行所有的证书、签名、重放和状态规则。
```
flowchart TB
Q["Araştırma sorusu"] --> I["Kayıtlı kimlik başına
bir turda bir hak"] I --> N["Nonce araması yok"] N --> P["İşlem gücü avantajı azalır"] P --> R["Deterministik ve tekrar üretilebilir seçim"] ``` ## EPDN 是什么，不是什么？ | EPDN 是... | 说明 | |---|---| | **一个实验性的测试网络** | 协议、设备、validator 和界面可以一起进行测试。 | | **研究 Proof-of-device 理念** | 参与权与已注册的加密身份绑定。 | | **确定性的** | 相同的有效输入会产生相同的票序和结果。 | | **一个多组件的示例** | Rust、Arduino/C++、Python 和 TypeScript 组件协同工作。 | | **明确限制其安全性** | 不支持的生产环境配置不会静默降级到弱安全模式。 | | EPDN 不是... | 原因 | |---|---| | **主网或真实的加密货币** | 单位仅用于测试目的，没有任何真实价值的承诺。 | | **Proof of Work** | 没有寻找 Nonce 和算力竞争。 | | **物理设备唯一性保证** | 目前的 ESP32 开发密钥存储在软件中。 | | **完全去中心化的网络** | 正在运行的 MVP 采用单 validator 模型。 | | **生产就绪** | 缺乏独立审计、P2P 最终性以及经过验证的硬件密钥。 | | **目前支持所有嵌入式开发板** | 协议设计为可移植的；当前运行的设备层以 ESP32 为中心。 | ## 当前状态 | 领域 | 当前状态 | |---|---| | 协议与规则 | 使用 Rust 实现并正在测试中 | | Validator node | 用于本地开发的运行中 REST/SSE 服务 | | 设备软件 | 在 Arduino 生态中以 ESP32 为中心 | | 物理测试 | 在经典 ESP32 系列上验证了 UART 网关流程 | | 额外的 ESP32 目标 | 针对 ESP32-S2、ESP32-S3 和 ESP32-C3 的 `WiFiMiner` 正在 CI 中编译 | | 其他嵌入式系列 | 架构目标/路线图；暂无可用且验证过的客户端 | | Dashboard 和钱包 | 可本地运行、可安装的 PWA | | Indexer | 可重建的 SQLite 视图和 JSON 导出 | | 三 validator 实验 | 三个独立的本地 API 进程和确定性比对测试 | | 生产模式 | 设计目标；目前尚不是可用的生产网络 | 该项目的长期目标不仅仅是 ESP32。但在整个 README 中，**已实现**、**仅编译**、**经过物理测试**和**已规划**等表述被刻意区分开来。 ``` flowchart LR A["Platformdan bağımsız
EPDN protokolü"] --> B["Arduino cihaz katmanı"] B --> C["Bugün:
ESP32 ailesi"] B -.->|"yeni adaptör gerekir"| D["Hedef:
RP2040 / Pico W"] B -.->|"yeni adaptör gerekir"| E["Hedef:
STM32 / SAMD / Renesas"] B -.->|"yeni adaptör gerekir"| F["Hedef:
ESP8266 ve diğerleri"] ``` ## 核心概念词汇表 | 概念 | 简述 | |---|---| | **Node / Validator** | 执行网络规则并生成有效区块的 Rust 服务。 | | **Miner / 设备** | 在每轮中以其已注册的身份最多准备一张票的嵌入式设备。 | | **Provisioning** | 为设备提供开发身份/证书并将其注册到 validator 的过程。 | | **设备证书** | 证明某设备密钥已被该测试网络接受的签名记录。 | | **Epoch** | 默认时长为 30 秒的一个网络轮次。 | | **Ticket / 票** | 表示设备参与该轮次的确定性数据。 | | **PoPED** | `Proof of Provisioned Embedded Device`（已配置嵌入式设备证明）；每个已注册身份限一张票的规则。 | | **Gateway** | 被视为不安全的桥接器，通过 UART 传输已签名的数据到 node。 | | **Indexer** | 从已最终确定的区块生成可查询的 SQLite 视图。 | | **Wallet / 钱包** | 使用独立密钥来接收和发送测试代币的本地浏览器钱包。 | | **PWA** | 可从浏览器打开并在受支持的系统上像应用一样安装的 Web 界面。 | | **Hash** | 数据的固定长度数字指纹。如果数据发生变化，Hash 也会改变。 | | **规范化** | 相同的信息以唯一有效的字节排列格式被每个人一致地记录下来。 | | **REST / SSE** | REST 是请求-响应 API；SSE 将 node 事件实时推送给 dashboard。 | | **CI** | 在每次代码更改时自动运行编译、测试和安全检查的系统。 | | **P2P / 最终性** | node 之间的直接通信，以及就某个区块不再可更改达成的共识。 | | **Secure element** | 在设备内部生成签名而不泄露私钥的独立安全芯片。 | | **L0–L4** | 描述设备密钥受保护强度的安全等级分类。 | ## 系统架构 ``` flowchart LR subgraph DEVICE["Gömülü cihaz"] MINER["EPDN Miner"] DKEY["Cihaz kimlik anahtarı"] MINER --- DKEY end subgraph HOST["Yerel / operatör bilgisayarı"] PROV["Provisioning CLI"] GATE["UART Gateway
(güvensiz röle)"] end subgraph NETWORK["EPDN test ağı"] NODE["Rust Validator Node"] STATE[("İmzalı durum
kaydı")] NODE --- STATE end subgraph READ["Okuma ve kullanıcı katmanı"] INDEX[("SQLite Indexer")] DASH["Dashboard / Explorer"] WALLET["Şifreli yerel cüzdan"] ANALYTICS["Harici analiz aracı"] end MINER -->|"yalnız açık kimliği verir"| PROV PROV -->|"sertifikayı kurar"| MINER PROV -->|"sertifika ve ödül adresini kaydeder"| NODE MINER -->|"Wi-Fi ile imzalı bilet"| NODE MINER -->|"UART ile imzalı bilet"| GATE GATE -->|"aynı baytları iletir"| NODE INDEX -->|"GET /api/v1/blocks"| NODE NODE -->|"blok listesi yanıtı"| INDEX NODE -->|"REST + SSE"| DASH INDEX -->|"isteğe bağlı JSON export"| ANALYTICS WALLET -->|"imzalı transfer"| NODE ``` 箭头的含义至关重要： - Gateway 不会代表设备生成签名；它只传输字节。 - Miner 不知道钱包的私钥；它只知道接收奖励的公开地址。 - Indexer 不是准确性的主要来源；它可以根据 validator 的数据被删除并重建。 - JSON 仅用于 API 边界。签名和 Hash 处理的值采用固定排序的 `EPDN Binary Encoding v1` 格式。 ## 组件及其任务 | 组件 | 语言 | 作用 | 不做的事 | |---|---|---|---| | [`protocol/`](protocol/) | Rust | 编码、证书、票、区块、交易和选举规则 | 不包含 HTTP 接口或设备驱动程序 | | [`node/`](node/) | Rust | Validator、注册表、epoch、奖励、转账、撤销、REST/SSE 和持久化状态 | 不提供生产级的 P2P 共识 | | [`arduino/`](arduino/) | C++ / Arduino | 设备身份、票引擎、Wi-Fi/UART miner 示例 | 目前并不支持所有的开发板系列 | | [`provisioning/`](provisioning/) | Python | 审查、开发注册、烧录、监控和撤销工具 | 在 MVP 中不会进行不可逆的 eFuse 更改 | | [`gateway/`](gateway/) | Python | UART 设备与 node 之间的受限数据中继 | 不保存私钥，也不代替设备签名 | | [`indexer/`](indexer/) | Python / SQLite | 验证已确定的区块并生成可查询的视图 | 不取代 Validator | | [`dashboard/`](dashboard/) | TypeScript / React | 浏览器、设备面板、PWA 和加密的本地钱包 | 在没有 validator 时不会提供虚假的实时网络假象；会显示演示标签 | | [`scripts/testnet.py`](scripts/testnet.py) | Python | 启动三个本地 node 进程并运行冒烟测试 | 不会将这些进程转换为 P2P 节点 | ## 端到端工作流 ``` sequenceDiagram actor Operator as Operatör participant Provisioner as Provisioning CLI participant Device as Gömülü cihaz participant Node as Validator participant Indexer as Indexer participant UI as Dashboard Operator->>Provisioner: Geliştirme kaydını başlatır Provisioner->>Device: Açık cihaz kimliğini ister Device->>Device: Özel anahtarı cihazda üretir veya yükler Device-->>Provisioner: Yalnız açık anahtarı verir Provisioner->>Node: Açık kimlik için geliştirme sertifikası ister Node-->>Provisioner: İmzalı cihaz sertifikasını verir Provisioner->>Device: Yalnız sertifikayı kurar Provisioner->>Node: Sertifikayı ve ödül adresini kaydeder Node-->>Device: Cihaza bağlı epoch challenge verir Device->>Device: Tek bileti hesaplar ve imzalar Device->>Node: İmzalı bilet gönderir Node->>Node: Sertifika, imza, epoch ve tekrar kontrolleri Node->>Node: En düşük geçerli puanı seçer Indexer->>Node: GET /api/v1/blocks ile blok listesini ister Node-->>Indexer: Kesinleşmiş blok listesini döndürür Node-->>UI: REST verisi ve SSE olayları gönderir UI-->>Operator: Blok, cihaz ve test ödülünü gösterir ``` 要使一张票被接受，仅凭签名正确是不够的。Validator 还会同时检查网络身份、epoch、前一个区块的链接、固件策略、证书有效期、安全等级、撤销状态、数据包大小以及重放情况。 ## PoPED 如何工作？ `Proof of Provisioned Embedded Device (PoPED)` 为每个已注册的身份在一个 epoch 中提供最多一个确定性的结果。 简化逻辑如下： ``` bilet = SHA256("EPDN_TICKET_V1" || cihaz_açık_anahtar_hash || epoch_challenge) puan = SHA256("EPDN_SCORE_V1" || bilet) ``` 签名证明了设备拥有已注册的私钥。但是，签名字节并不参与票面分数的计算。因此，为同一消息生成不同的有效 ECDSA 签名并不能用于寻找更好的分数。 | 特性 | Proof of Work | EPDN PoPED MVP | |---|---|---| | 参与来源 | 计算能力 | 已注册的设备身份 | | 每轮尝试次数 | 根据硬件速度有极多次 | 每个身份最多一次 | | 寻找 Nonce（通过尝试大量值来寻找解） | 有 | 无 | | 更快的 GPU/ASIC 优势 | 通常有 | 对同一身份不提供额外票数 | | 核心信任假设 | 经济和计算成本 | Provisioning（配置）授权方和设备密钥 | | 物理设备保证 | 无 | MVP 中无；需要硬件支持的密钥 | ``` flowchart TD A["Validator epoch challenge yayınlar"] --> B{"Kimlik kayıtlı ve
sertifika geçerli mi?"} B -->|"Hayır"| X["Bilet reddedilir"] B -->|"Evet"| C["Cihaz tek deterministik bileti üretir"] C --> D["Cihaz proof ve submission imzalar"] D --> E{"İmza, firmware, epoch,
iptal ve tekrar kontrolleri"} E -->|"Başarısız"| X E -->|"Başarılı"| F["Bilet havuzuna eklenir"] F --> G["En düşük puan seçilir"] G --> H["İmzalı blok kesinleşir"] ``` 详细的格式和安全说明： [`PROTOCOL.md`](PROTOCOL.md) 和 [`docs/consensus.md`](docs/consensus.md)。 ## 一个 epoch 内会发生什么？ 默认的 epoch 时长为 **30 秒**： - 前 20 秒：提交票的窗口期。 - 后 10 秒：结束窗口期。 - 从有效票据中确定性地选出获胜者。 - 转账和撤销只有在被打包进区块后才会被最终确认。 ``` stateDiagram-v2 [*] --> BiletPenceresi BiletPenceresi: 0–20 saniye BiletPenceresi: Geçerli biletler kabul edilir BiletPenceresi --> SonlandirmaPenceresi: 20. saniye SonlandirmaPenceresi: 20–30 saniye SonlandirmaPenceresi: Yeni bilet reddedilir SonlandirmaPenceresi --> Dogrulama: Epoch kapanır Dogrulama --> NormalBlok: Geçerli kazanan varsa Dogrulama --> YonetimBlogu: Yalnız kesinleşecek iptaller varsa Dogrulama --> Sonucsuz: İşlenecek veri yoksa NormalBlok --> [*] YonetimBlogu --> [*] Sonucsuz --> [*] ``` 数据包到达 node 的顺序不用于决定获胜者。如果出现平局，将使用设备公钥 Hash 和提交 Hash 等规范化值。 ## 为什么设备身份与钱包是分开的？ EPDN 使用两个不同的私钥： ``` flowchart LR subgraph DEVICE["Cihaz güven sınırı"] DK["Cihaz özel anahtarı"] SIGN["Bilet imzalama"] DK --> SIGN end subgraph BROWSER["Tarayıcı güven sınırı"] WK["Şifrelenmiş cüzdan özel anahtarı"] TX["Transfer imzalama"] WK --> TX end SIGN -->|"imzalı bilet"| NODE["Validator"] TX -->|"imzalı transfer"| NODE WALLETADDR["Yalnız açık ödül adresi"] --> DEVICE DK -.->|"gönderilmez"| BROWSER WK -.->|"gönderilmez"| DEVICE DK -.->|"gönderilmez"| NODE WK -.->|"gönderilmez"| NODE ``` - **设备密钥** 证明 miner 是已注册的参与者。 - **钱包密钥** 授权使用测试代币。 - Miner 只知道公开的奖励地址。 - 将钱包私钥硬写入固件属于违反设计原则的行为。 - 将设备私钥发送给 dashboard 同样属于违反设计原则的行为。 ## 硬件支持 ### 标签代表什么含义？ | 标签 | 含义 | |---|---| | **物理测试** | 代码已在真实的开发板上运行并观察了其行为。 | | **CI 编译** | 代码已针对目标进行编译；并未声称已在真实开发板上运行。 | | **已规划** | 具有架构目标；尚无完整且验证过的支持。 | ### 当前支持情况表 | 硬件 / 系列 | 状态 | 范围 | |---|---|---| | 经典 ESP32 系列 | **物理测试 + CI 编译** | UART 网关、协议向量、注册、票、奖励和撤销流程 | | ESP32-S2 | **CI 编译** | 仅 `WiFiMiner`；无物理测试 | | ESP32-S3 | **CI 编译** | 仅 `WiFiMiner`；无物理测试 | | ESP32-C3 | **CI 编译** | 仅 `WiFiMiner`；无物理测试 | | ESP32-C2/C5/C6/C61/H2/P4 | **已规划** | 需要适应特定型号的网络和身份适配器 | | ESP8266 | **已规划** | 无可用/经验证的 miner | | RP2040 / Raspberry Pi Pico W | **已规划** | 无可用/经验证的 miner | | SAMD / Nano / MKR 系列 | **已规划** | 需额外验证开发板和 secure-element 能力 | | STM32 Arduino 内核 | **已规划** | 需基于 MCU 和开发板进行适配 | | Renesas Arduino 内核 | **已规划** | 需基于目标进行适配 | | ATECC608A / ECC508 | **已规划** | 目前的示例为 fail-closed 占位符；并非真正的集成 | 物理证据： [`arduino/HARDWARE_TEST_REPORT.md`](arduino/HARDWARE_TEST_REPORT.md) 和 [`arduino/board-configs/support-matrix.json`](arduino/board-configs/support-matrix.json)。 ## 安全等级 EPDN 将身份存储的强度分为 L0 到 L4： ``` flowchart LR L0["L0
Yazılım test anahtarı"] --> L1["L1
Korumalı yazılım"] L1 --> L2["L2
Yerel donanım kimliği"] L2 --> L3["L3
Harici secure element"] L3 --> L4["L4
Attestation destekli platform"] ``` | 等级 | 简述 | 本仓库中的状态 | |---|---|---| | **L0** | 可导出的开发/测试密钥 | 目前的 ESP32 开发路径 | | **L1** | 软件可访问但受到更好保护的存储 | 需要特定目标的证明 | | **L2** | 签名过程依赖于本地硬件 | 尚无经过验证的通用 backend | | **L3** | 密钥不离开 secure element | 计划集成 ATECC | | **L4** | 通过签名的 attestation 提供平台度量 | 设计目标 | 生产策略拒绝 L0 身份。开发板名称中带有“secure”或“ESP32”并不足以赋予其 L2/L4 等级。详情参见： [`docs/security-classes.md`](docs/security-classes.md)。 ## 信任与威胁模型 ``` flowchart TB PA["Provisioning otoritesi
GÜVENİLİR"] -->|"sertifika imzalar"| CERT["Cihaz sertifikası"] DEVICE["Cihaz anahtarı
SEÇİLEN BACKEND KADAR GÜVENLİ"] -->|"bilet imzalar"| TICKET["İmzalı bilet"] GATE["UART Gateway
GÜVENİLMEZ"] -->|"düşürebilir / geciktirebilir / tekrar oynatabilir"| NODE["Validator"] CERT --> NODE TICKET --> GATE NODE -->|"bütün kuralları yeniden doğrular"| BLOCK["İmzalı blok"] BLOCK -->|"buradan yeniden oluşturulur"| INDEX["Indexer
YENİDEN OLUŞTURULABİLİR"] ``` 系统基于以下假设： - Provisioning 授权方不应生成虚假身份。 - Validator 的 CA 和区块签名密钥必须受到保护。 - 设备密钥的安全等级取决于所选 backend 的强度。 - Gateway 不被视为可信；node 会对收到的数据进行重新验证。 - MAC 地址、IP 地址、RSSI、开发板型号、重置原因或时间延迟都不是设备身份的信任根。 关键防御措施： - P-256 签名和基于 SHA-256 的域分离 Hash。 - 固定排序、大小受限的规范化二进制编码。 - 每个身份在每个 epoch 仅限一张票，并进行重放检查。 - 证书、固件、安全等级和撤销策略。 - 签名、带有校验和且原子化的 V3 node 状态记录。 - 对于向 loopback 之外暴露的 node，强制要求使用强大的 admin token、严格的 CORS 列表以及相互独立的 CA/validator 密钥。 - 对于不支持的生产后端，直接报错而不是静默降级。 完整的威胁模型：[`THREAT_MODEL.md`](THREAT_MODEL.md)。 ## 隐私与数据边界 EPDN 不是一款提供匿名性的产品。区块、交易、奖励地址和公开的设备身份可能是测试网络中的公开数据。这里的隐私目标是防止不必要的个人和设备识别数据泄漏到源代码、日志和公开的浏览器中。 ``` flowchart LR PRIVATE["Yerel ve gizli kalmalı
özel anahtarlar
Wi-Fi parolası
admin token'ı
ham seri loglar"] PUBLIC["Ağda paylaşılabilir
açık anahtar hash'i
sertifika
imzalı bilet
blok ve işlem"] UI["Dashboard / Indexer
yalnız gerekli genel alanlar"] PRIVATE -.->|"gönderilmez"| PUBLIC PUBLIC --> UI ``` | 数据 | 应存放的位置 | |---|---| | 设备私钥 | 仅限设备所选的身份 backend | | 钱包私钥 | 加密的 IndexedDB 记录，以及解锁状态下的浏览器内存 | | Wi-Fi 密码 | 交互式本地输入和设备的本地存储 | | Admin token | 本地/runtime 环境变量 | | 原始串口输出 | 被 Git 忽略的本地测试文件夹 | | 公开的设备身份和证书 | 测试网络注册表 | | 区块和已签名的交易 | 公开的测试网络数据 | | 个人的设备标签 | 仅限授权的 dashboard 应用数据 | 请勿将以下内容放入 issue、commit、截图或公开日志中： - 私钥和恢复数据 - Wi-Fi SSID/密码 - Admin token - 完整的串口转储 - MAC 地址、USB 标识和唯一的芯片 ID - eFuse/security posture 转储 - 个人文件路径、用户名或电子邮件地址 ## 快速入门 首先选择您想要查看的内容： ``` flowchart TD START["Neyi denemek istiyorsunuz?"] START -->|"Sadece arayüz"| DEMO["Yol 1
Dashboard demo"] START -->|"Gerçek yerel API"| LOCAL["Yol 2
Validator + dashboard"] START -->|"Otomatik ağ kontrolü"| SMOKE["Yol 3
Üç süreçli smoke testi"] START -->|"Cihaz kodu"| HW["Yol 4
ESP32 derleme"] ``` ### 前置条件 您只需安装所选路径所需的工具。 | 工具 | 版本 | 何处需要 | |---|---:|---| | Git | 最新版 | 用于下载仓库 | | Rust | 1.85 | 协议和 node | | Python | 3.11+ | Provisioning、gateway、indexer 和 testnet 脚本 | | Node.js | 22.13+ | Dashboard/PWA | | Arduino CLI | 1.5.0 | 编译 ESP32 代码 | | ESP32 Arduino core | 2.0.11 | ESP32 目标 | | Docker | 可选 | Node container | 下载仓库： ``` git clone https://github.com/UfkuAcik/EPDN-Network.git cd EPDN-Network ``` ### 路径 1：仅查看界面 此路径不需要物理设备、Rust 或 Python。如果找不到 Validator，dashboard 会明确显示 **DEMO DATA** 标签并使用确定性的示例数据。 ``` cd dashboard npm ci npm run dev ``` 在浏览器中打开 [http://localhost:3000](http://localhost:3000)。 预期结果： - 打开浏览器界面。 - 显示示例区块和设备。 - 顶部会标明这是演示数据而非实时网络。 - 在演示模式下，转账或撤销操作不会发送到真实网络。 ### 路径 2：本地 validator 和 dashboard #### 1. 启动 Validator 在仓库根目录下： ``` cargo run -p epdn-node ``` Node 默认仅在 `127.0.0.1:8745` 上监听。健康检查： ``` curl http://127.0.0.1:8745/healthz ``` 在 loopback 开发模式下，可以使用本地且刻意设为不安全的默认密钥。在将 Node 暴露给其他计算机访问之前，请阅读 [`node/README.md`](node/README.md) 中必需的安全配置变量。 #### 2. 将 dashboard 连接到 node 打开一个新的终端。 PowerShell： ``` Set-Location dashboard $env:EPDN_API_BASE_URL = "http://127.0.0.1:8745" npm ci npm run dev ``` Bash： ``` cd dashboard npm ci EPDN_API_BASE_URL=http://127.0.0.1:8745 npm run dev ``` 在 dashboard 的 API 字段中也可以选择 `http://127.0.0.1:8745`。如果连接成功，数据源将显示为实时 node 而不是演示。 ### 路径 3：三进程测试 ``` python scripts/testnet.py smoke ``` 此命令将执行以下操作： 1. 编译最新的 `epdn-node` 代码。 2. 在 `8745`、`8746` 和 `8747` 端口上启动三个独立的本地进程。 3. 检查健康状态和基本的网络信息。 4. 运行带有三个 validator 的确定性 commit/reveal 测试。 5. 关闭进程并清理临时状态。 如果端口被占用： ``` python scripts/testnet.py --ports 18745,18746,18747 smoke ``` ### 路径 4：编译 ESP32 代码 首先安装固定的 ESP32 核心： ``` arduino-cli config init arduino-cli config add board_manager.additional_urls https://espressif.github.io/arduino-esp32/package_esp32_index.json arduino-cli core update-index arduino-cli core install esp32:esp32@2.0.11 ``` 在不对硬件进行任何烧录的情况下编译识别示例： ``` arduino-cli compile \ --fqbn esp32:esp32:esp32 \ --libraries arduino/libraries \ arduino/examples/SecurityDiagnostic ``` 在 PowerShell 中，同样的命令也可以作为单行运行： ``` arduino-cli compile --fqbn esp32:esp32:esp32 --libraries arduino/libraries arduino/examples/SecurityDiagnostic ``` 其他示例： | 示例 | 目的 | |---|---| | `SecurityDiagnostic` | 安全地检查目标报告的安全能力 | | `SerialProvisioning` | 通过串口连接接收 Wi-Fi 和开发注册数据 | | `WiFiMiner` | 通过 Wi-Fi 直接与 node 通信 | | `GatewayMiner` | 通过 UART 网关发送已签名的票 | | `ProtocolTestVectors` | 验证 Rust 和 Arduino 编码是否产生相同的字节 | | `SecureElementMiner` | 规划中的 secure-element 路径的 fail-closed 占位符 | 有关设备设置，请参见： [`arduino/README.md`](arduino/README.md)、 [`docs/hardware-testing.md`](docs/hardware-testing.md) 和 [`docs/wifi-provisioning.md`](docs/wifi-provisioning.md)。 ## 仓库结构 ``` EPDN-Network/ ├── protocol/ Konsensüs kuralları ve kanonik binary kodlama ├── node/ Rust validator, REST/SSE API ve kalıcı durum ├── arduino/ EPDN cihaz kütüphanesi ve ESP32 örnekleri ├── provisioning/ Cihaz kayıt ve yönetim CLI'ı ├── gateway/ UART ile node arasında imzalı veri rölesi ├── indexer/ SQLite okuma modeli ve JSON dışa aktarma ├── dashboard/ Explorer, cihaz paneli ve yerel cüzdan PWA ├── scripts/ Testnet çalıştırıcısı ve secret tarayıcısı ├── tests/ Gizlilik korunmuş donanım kanıtları ├── docs/ Mimari ve operasyon belgeleri ├── PROTOCOL.md Protokol güven sınırı ├── THREAT_MODEL.md Tehdit modeli ├── ROADMAP.md Planlanan geliştirmeler └── SECURITY.md Güvenlik açığı bildirim kuralları ``` ``` flowchart TB PROTOCOL["protocol/
Ortak kurallar"] --> NODE["node/
Kuralları uygular"] PROTOCOL --> ARD["arduino/
Uyumlu bilet üretir"] PROV["provisioning/
Kimlik kurar"] --> ARD ARD --> GATE["gateway/
UART rölesi"] ARD --> NODE GATE --> NODE IDX["indexer/
Okuma modeli"] -->|"GET blok listesi"| NODE NODE --> WEB["dashboard/
Explorer ve cüzdan"] ``` ## API 摘要 Node 提供两种类型的 endpoint： | 类型 | 示例 | 授权 | |---|---|---| | 健康/网络 | `/healthz`, `/metrics`, `/api/v1/network/status` | 公开 | | Epoch 和票 | `/api/v1/epochs/current`, `/api/v1/tickets` | Challenge 公开；票将通过加密方式验证 | | 区块和账户 | `/api/v1/blocks`, `/api/v1/address/{address}` | 公开 | | 设备视图 | `/api/v1/miners`, `/api/v1/miners/{public_id}` | 公开字段 | | 事件流 | `/api/v1/events` | 公开 SSE | | 注册和管理 | `/api/v1/admin/enroll`, `/api/v1/admin/register`, `/api/v1/admin/miners/{public_id}/revoke` | Admin token | | 转账 | `/api/v1/transactions` | 钱包签名 | 完整的 API 列表和环境变量： [`node/README.md`](node/README.md)。 ## 测试与质量门禁 ``` flowchart LR PUSH["Push / Pull Request"] --> RUST["Rust
build + fmt + clippy + test + audit"] PUSH --> PY["Python
compile + test + audit"] PUSH --> WEB["Dashboard
lint + build + test + audit"] PUSH --> ARD["Arduino
ESP32 derleme matrisi"] PUSH --> SEC["Secret taraması
mevcut ağaç + Git geçmişi"] PUSH --> NET["Yerel testnet
üç süreçli smoke"] PUSH --> DOCKER["Docker
node image build"] ``` 本地基本检查： ``` cargo fmt --all -- --check cargo clippy --locked --workspace --all-targets -- -D warnings cargo test --locked --workspace python -m pip install -e "./provisioning[test]" -e "./gateway" -e "./indexer[test]" python -m pytest -q provisioning/tests gateway/tests indexer/tests scripts/tests python scripts/check-secrets.py --history cd dashboard npm ci npm run lint npm test ``` CI 还会： - 扫描 Rust、Python 和生产环境 dashboard 的依赖项是否存在安全漏洞。 - 验证 Rust 通用协议向量，并检查 Arduino 向量示例是否已编译。 - 编译 ESP32 示例及额外的 ESP32 目标。 - 验证生产 build 中是否拒绝 L0 身份。 - 构建 Docker node 镜像。 详情见：[`docs/ci.md`](docs/ci.md)。 ## 已知局限 - 目前运行的设备应用程序以 ESP32 为中心；其他嵌入式系列尚未准备好。 - 目前的 ESP32 开发身份是存储在 NVS 中的 L0 软件密钥；它不是硬件支持的，也不是不可克隆的。 - 尚未进行物理 Wi-Fi 端到端测试。 - 签名的 V3 状态记录已进行自动化测试；使用物理 ESP32 的重启测试在 V2 中曾通过，而 V3 尚待进行物理复测。 - 单 node 开发的随机性并非安全或无偏见的生产级随机性。 - 三进程测试不提供真正的 P2P 同步或 Byzantine 最终性。 - Indexer 尚未具备已发布的可信 validator 密钥检查点，无法独立验证 validator 签名的真实性。 - Dashboard 钱包在本地进行加密；当钱包解锁时，浏览器中的 XSS 或恶意插件可能会滥用签名操作。 - 生产配置流程、HSM/离线 CA、签名 OTA、回滚机制和独立的安全审计尚未完成。 ## 文档 ### 首先阅读这些 | 文档 | 何时阅读？ | |---|---| | [`PROTOCOL.md`](PROTOCOL.md) | 了解协议对哪些内容进行了签名和 Hash | | [`THREAT_MODEL.md`](THREAT_MODEL.md) | 查看系统信任什么以及不防范什么 | | [`docs/architecture.md`](docs/architecture.md) | 详细了解组件边界 | | [`docs/consensus.md`](docs/consensus.md) | 了解 PoPED、epoch 和 commit/reveal 逻辑 | | [`SECURITY.md`](SECURITY.md) | 私下披露安全漏洞 | ### 运行与操作 | 文档 主题 | |---|---| | [`docs/local-testnet.md`](docs/local-testnet.md) | 本地 node 进程和 Docker | | [`node/README.md`](node/README.md) | Node 配置、状态格式和 API | | [`arduino/README.md`](arduino/README.md) | Arduino 库和 miner 示例 | | [`provisioning/README.md`](provisioning/README.md) | 设备注册 CLI | | [`gateway/README.md`](gateway/README.md) | UART gateway | | [`indexer/README.md`](indexer/README.md) | SQLite indexer 和 export | | [`dashboard/README.md`](dashboard/README.md) | PWA、钱包和 dashboard | ### 硬件与安全 | 文档 | 主题 | |---|---| | [`docs/supported-boards.md`](docs/supported-boards.md) | 目标开发板系列及其评估方法 | | [`docs/security-classes.md`](docs/security-classes.md) | L0–L4 等级分类 | | [`docs/hardware-testing.md`](docs/hardware-testing.md) | 安全的物理测试顺序 | | [`docs/wifi-provisioning.md`](docs/wifi-provisioning.md) | 在不将 Wi-Fi 信息硬编码到源代码中的情况进行配置 | | [`docs/wallet-security.md`](docs/wallet-security.md) | 浏览器钱包的安全边界 | | [`docs/production-hardening.md`](docs/production-hardening.md) | 投入生产前所需的准备 | | [`arduino/HARDWARE_TEST_REPORT.md`](arduino/HARDWARE_TEST_REPORT.md) | 保护隐私的物理测试摘要 | ## 路线图 主要目标： 1. 为 ESP32 以外的嵌入式系列提供真实且经过测试的平台适配器。 2. 使用如 ATECC608A/ECC508 之类的 secure element 实现 L3 身份。 3. 为 ESP32 系列提供经验证的 L2 硬件身份方案。 4. 实现已签名且可重现的 OTA、回滚机制和 measured boot。 5. 基于 HSM 的 CA、双重控制和证书生命周期管理。 6. 真正的 P2P 节点同步和生产级的最终性协议。 7. 长期的模糊测试、断电测试和存储损耗测试。 8. 独立的协议和密码学审计。 完整列表：[`ROADMAP.md`](ROADMAP.md)。 ``` flowchart LR MVP["Bugün
ESP32 merkezli MVP"] --> PORT["Çoklu cihaz adaptörleri"] MVP --> HWKEY["Doğrulanmış donanım anahtarları"] PORT --> HITL["Hardware-in-the-loop CI"] HWKEY --> AUDIT["Bağımsız güvenlik denetimi"] MVP --> P2P["P2P senkronizasyon ve finality"] HITL --> PROD["Üretim hazırlığı"] AUDIT --> PROD P2P --> PROD ``` ## 贡献与安全报告 在做出贡献之前： 1. 请阅读您将要更改的组件的 README。 2. 如果您正在更改共识数据，请查看 `PROTOCOL.md` 和二进制 V1 规范。 3. 在报告新的开发板支持时，请明确区分“已规划”、“编译”和“物理测试”的证据。 4. 请勿 commit 私钥、Wi-Fi 信息、设备身份或原始硬件输出。 5. 运行相关的测试和密钥扫描。 请勿在公开的 issue 中披露安全漏洞。请使用 [`SECURITY.md`](SECURITY.md) 中的私密报告方法。 ## 许可证 本项目基于 [MIT 许可证](LICENSE) 发布。
bir turda bir hak"] I --> N["Nonce araması yok"] N --> P["İşlem gücü avantajı azalır"] P --> R["Deterministik ve tekrar üretilebilir seçim"] ``` ## EPDN 是什么，不是什么？ | EPDN 是... | 说明 | |---|---| | **一个实验性的测试网络** | 协议、设备、validator 和界面可以一起进行测试。 | | **研究 Proof-of-device 理念** | 参与权与已注册的加密身份绑定。 | | **确定性的** | 相同的有效输入会产生相同的票序和结果。 | | **一个多组件的示例** | Rust、Arduino/C++、Python 和 TypeScript 组件协同工作。 | | **明确限制其安全性** | 不支持的生产环境配置不会静默降级到弱安全模式。 | | EPDN 不是... | 原因 | |---|---| | **主网或真实的加密货币** | 单位仅用于测试目的，没有任何真实价值的承诺。 | | **Proof of Work** | 没有寻找 Nonce 和算力竞争。 | | **物理设备唯一性保证** | 目前的 ESP32 开发密钥存储在软件中。 | | **完全去中心化的网络** | 正在运行的 MVP 采用单 validator 模型。 | | **生产就绪** | 缺乏独立审计、P2P 最终性以及经过验证的硬件密钥。 | | **目前支持所有嵌入式开发板** | 协议设计为可移植的；当前运行的设备层以 ESP32 为中心。 | ## 当前状态 | 领域 | 当前状态 | |---|---| | 协议与规则 | 使用 Rust 实现并正在测试中 | | Validator node | 用于本地开发的运行中 REST/SSE 服务 | | 设备软件 | 在 Arduino 生态中以 ESP32 为中心 | | 物理测试 | 在经典 ESP32 系列上验证了 UART 网关流程 | | 额外的 ESP32 目标 | 针对 ESP32-S2、ESP32-S3 和 ESP32-C3 的 `WiFiMiner` 正在 CI 中编译 | | 其他嵌入式系列 | 架构目标/路线图；暂无可用且验证过的客户端 | | Dashboard 和钱包 | 可本地运行、可安装的 PWA | | Indexer | 可重建的 SQLite 视图和 JSON 导出 | | 三 validator 实验 | 三个独立的本地 API 进程和确定性比对测试 | | 生产模式 | 设计目标；目前尚不是可用的生产网络 | 该项目的长期目标不仅仅是 ESP32。但在整个 README 中，**已实现**、**仅编译**、**经过物理测试**和**已规划**等表述被刻意区分开来。 ``` flowchart LR A["Platformdan bağımsız
EPDN protokolü"] --> B["Arduino cihaz katmanı"] B --> C["Bugün:
ESP32 ailesi"] B -.->|"yeni adaptör gerekir"| D["Hedef:
RP2040 / Pico W"] B -.->|"yeni adaptör gerekir"| E["Hedef:
STM32 / SAMD / Renesas"] B -.->|"yeni adaptör gerekir"| F["Hedef:
ESP8266 ve diğerleri"] ``` ## 核心概念词汇表 | 概念 | 简述 | |---|---| | **Node / Validator** | 执行网络规则并生成有效区块的 Rust 服务。 | | **Miner / 设备** | 在每轮中以其已注册的身份最多准备一张票的嵌入式设备。 | | **Provisioning** | 为设备提供开发身份/证书并将其注册到 validator 的过程。 | | **设备证书** | 证明某设备密钥已被该测试网络接受的签名记录。 | | **Epoch** | 默认时长为 30 秒的一个网络轮次。 | | **Ticket / 票** | 表示设备参与该轮次的确定性数据。 | | **PoPED** | `Proof of Provisioned Embedded Device`（已配置嵌入式设备证明）；每个已注册身份限一张票的规则。 | | **Gateway** | 被视为不安全的桥接器，通过 UART 传输已签名的数据到 node。 | | **Indexer** | 从已最终确定的区块生成可查询的 SQLite 视图。 | | **Wallet / 钱包** | 使用独立密钥来接收和发送测试代币的本地浏览器钱包。 | | **PWA** | 可从浏览器打开并在受支持的系统上像应用一样安装的 Web 界面。 | | **Hash** | 数据的固定长度数字指纹。如果数据发生变化，Hash 也会改变。 | | **规范化** | 相同的信息以唯一有效的字节排列格式被每个人一致地记录下来。 | | **REST / SSE** | REST 是请求-响应 API；SSE 将 node 事件实时推送给 dashboard。 | | **CI** | 在每次代码更改时自动运行编译、测试和安全检查的系统。 | | **P2P / 最终性** | node 之间的直接通信，以及就某个区块不再可更改达成的共识。 | | **Secure element** | 在设备内部生成签名而不泄露私钥的独立安全芯片。 | | **L0–L4** | 描述设备密钥受保护强度的安全等级分类。 | ## 系统架构 ``` flowchart LR subgraph DEVICE["Gömülü cihaz"] MINER["EPDN Miner"] DKEY["Cihaz kimlik anahtarı"] MINER --- DKEY end subgraph HOST["Yerel / operatör bilgisayarı"] PROV["Provisioning CLI"] GATE["UART Gateway
(güvensiz röle)"] end subgraph NETWORK["EPDN test ağı"] NODE["Rust Validator Node"] STATE[("İmzalı durum
kaydı")] NODE --- STATE end subgraph READ["Okuma ve kullanıcı katmanı"] INDEX[("SQLite Indexer")] DASH["Dashboard / Explorer"] WALLET["Şifreli yerel cüzdan"] ANALYTICS["Harici analiz aracı"] end MINER -->|"yalnız açık kimliği verir"| PROV PROV -->|"sertifikayı kurar"| MINER PROV -->|"sertifika ve ödül adresini kaydeder"| NODE MINER -->|"Wi-Fi ile imzalı bilet"| NODE MINER -->|"UART ile imzalı bilet"| GATE GATE -->|"aynı baytları iletir"| NODE INDEX -->|"GET /api/v1/blocks"| NODE NODE -->|"blok listesi yanıtı"| INDEX NODE -->|"REST + SSE"| DASH INDEX -->|"isteğe bağlı JSON export"| ANALYTICS WALLET -->|"imzalı transfer"| NODE ``` 箭头的含义至关重要： - Gateway 不会代表设备生成签名；它只传输字节。 - Miner 不知道钱包的私钥；它只知道接收奖励的公开地址。 - Indexer 不是准确性的主要来源；它可以根据 validator 的数据被删除并重建。 - JSON 仅用于 API 边界。签名和 Hash 处理的值采用固定排序的 `EPDN Binary Encoding v1` 格式。 ## 组件及其任务 | 组件 | 语言 | 作用 | 不做的事 | |---|---|---|---| | [`protocol/`](protocol/) | Rust | 编码、证书、票、区块、交易和选举规则 | 不包含 HTTP 接口或设备驱动程序 | | [`node/`](node/) | Rust | Validator、注册表、epoch、奖励、转账、撤销、REST/SSE 和持久化状态 | 不提供生产级的 P2P 共识 | | [`arduino/`](arduino/) | C++ / Arduino | 设备身份、票引擎、Wi-Fi/UART miner 示例 | 目前并不支持所有的开发板系列 | | [`provisioning/`](provisioning/) | Python | 审查、开发注册、烧录、监控和撤销工具 | 在 MVP 中不会进行不可逆的 eFuse 更改 | | [`gateway/`](gateway/) | Python | UART 设备与 node 之间的受限数据中继 | 不保存私钥，也不代替设备签名 | | [`indexer/`](indexer/) | Python / SQLite | 验证已确定的区块并生成可查询的视图 | 不取代 Validator | | [`dashboard/`](dashboard/) | TypeScript / React | 浏览器、设备面板、PWA 和加密的本地钱包 | 在没有 validator 时不会提供虚假的实时网络假象；会显示演示标签 | | [`scripts/testnet.py`](scripts/testnet.py) | Python | 启动三个本地 node 进程并运行冒烟测试 | 不会将这些进程转换为 P2P 节点 | ## 端到端工作流 ``` sequenceDiagram actor Operator as Operatör participant Provisioner as Provisioning CLI participant Device as Gömülü cihaz participant Node as Validator participant Indexer as Indexer participant UI as Dashboard Operator->>Provisioner: Geliştirme kaydını başlatır Provisioner->>Device: Açık cihaz kimliğini ister Device->>Device: Özel anahtarı cihazda üretir veya yükler Device-->>Provisioner: Yalnız açık anahtarı verir Provisioner->>Node: Açık kimlik için geliştirme sertifikası ister Node-->>Provisioner: İmzalı cihaz sertifikasını verir Provisioner->>Device: Yalnız sertifikayı kurar Provisioner->>Node: Sertifikayı ve ödül adresini kaydeder Node-->>Device: Cihaza bağlı epoch challenge verir Device->>Device: Tek bileti hesaplar ve imzalar Device->>Node: İmzalı bilet gönderir Node->>Node: Sertifika, imza, epoch ve tekrar kontrolleri Node->>Node: En düşük geçerli puanı seçer Indexer->>Node: GET /api/v1/blocks ile blok listesini ister Node-->>Indexer: Kesinleşmiş blok listesini döndürür Node-->>UI: REST verisi ve SSE olayları gönderir UI-->>Operator: Blok, cihaz ve test ödülünü gösterir ``` 要使一张票被接受，仅凭签名正确是不够的。Validator 还会同时检查网络身份、epoch、前一个区块的链接、固件策略、证书有效期、安全等级、撤销状态、数据包大小以及重放情况。 ## PoPED 如何工作？ `Proof of Provisioned Embedded Device (PoPED)` 为每个已注册的身份在一个 epoch 中提供最多一个确定性的结果。 简化逻辑如下： ``` bilet = SHA256("EPDN_TICKET_V1" || cihaz_açık_anahtar_hash || epoch_challenge) puan = SHA256("EPDN_SCORE_V1" || bilet) ``` 签名证明了设备拥有已注册的私钥。但是，签名字节并不参与票面分数的计算。因此，为同一消息生成不同的有效 ECDSA 签名并不能用于寻找更好的分数。 | 特性 | Proof of Work | EPDN PoPED MVP | |---|---|---| | 参与来源 | 计算能力 | 已注册的设备身份 | | 每轮尝试次数 | 根据硬件速度有极多次 | 每个身份最多一次 | | 寻找 Nonce（通过尝试大量值来寻找解） | 有 | 无 | | 更快的 GPU/ASIC 优势 | 通常有 | 对同一身份不提供额外票数 | | 核心信任假设 | 经济和计算成本 | Provisioning（配置）授权方和设备密钥 | | 物理设备保证 | 无 | MVP 中无；需要硬件支持的密钥 | ``` flowchart TD A["Validator epoch challenge yayınlar"] --> B{"Kimlik kayıtlı ve
sertifika geçerli mi?"} B -->|"Hayır"| X["Bilet reddedilir"] B -->|"Evet"| C["Cihaz tek deterministik bileti üretir"] C --> D["Cihaz proof ve submission imzalar"] D --> E{"İmza, firmware, epoch,
iptal ve tekrar kontrolleri"} E -->|"Başarısız"| X E -->|"Başarılı"| F["Bilet havuzuna eklenir"] F --> G["En düşük puan seçilir"] G --> H["İmzalı blok kesinleşir"] ``` 详细的格式和安全说明： [`PROTOCOL.md`](PROTOCOL.md) 和 [`docs/consensus.md`](docs/consensus.md)。 ## 一个 epoch 内会发生什么？ 默认的 epoch 时长为 **30 秒**： - 前 20 秒：提交票的窗口期。 - 后 10 秒：结束窗口期。 - 从有效票据中确定性地选出获胜者。 - 转账和撤销只有在被打包进区块后才会被最终确认。 ``` stateDiagram-v2 [*] --> BiletPenceresi BiletPenceresi: 0–20 saniye BiletPenceresi: Geçerli biletler kabul edilir BiletPenceresi --> SonlandirmaPenceresi: 20. saniye SonlandirmaPenceresi: 20–30 saniye SonlandirmaPenceresi: Yeni bilet reddedilir SonlandirmaPenceresi --> Dogrulama: Epoch kapanır Dogrulama --> NormalBlok: Geçerli kazanan varsa Dogrulama --> YonetimBlogu: Yalnız kesinleşecek iptaller varsa Dogrulama --> Sonucsuz: İşlenecek veri yoksa NormalBlok --> [*] YonetimBlogu --> [*] Sonucsuz --> [*] ``` 数据包到达 node 的顺序不用于决定获胜者。如果出现平局，将使用设备公钥 Hash 和提交 Hash 等规范化值。 ## 为什么设备身份与钱包是分开的？ EPDN 使用两个不同的私钥： ``` flowchart LR subgraph DEVICE["Cihaz güven sınırı"] DK["Cihaz özel anahtarı"] SIGN["Bilet imzalama"] DK --> SIGN end subgraph BROWSER["Tarayıcı güven sınırı"] WK["Şifrelenmiş cüzdan özel anahtarı"] TX["Transfer imzalama"] WK --> TX end SIGN -->|"imzalı bilet"| NODE["Validator"] TX -->|"imzalı transfer"| NODE WALLETADDR["Yalnız açık ödül adresi"] --> DEVICE DK -.->|"gönderilmez"| BROWSER WK -.->|"gönderilmez"| DEVICE DK -.->|"gönderilmez"| NODE WK -.->|"gönderilmez"| NODE ``` - **设备密钥** 证明 miner 是已注册的参与者。 - **钱包密钥** 授权使用测试代币。 - Miner 只知道公开的奖励地址。 - 将钱包私钥硬写入固件属于违反设计原则的行为。 - 将设备私钥发送给 dashboard 同样属于违反设计原则的行为。 ## 硬件支持 ### 标签代表什么含义？ | 标签 | 含义 | |---|---| | **物理测试** | 代码已在真实的开发板上运行并观察了其行为。 | | **CI 编译** | 代码已针对目标进行编译；并未声称已在真实开发板上运行。 | | **已规划** | 具有架构目标；尚无完整且验证过的支持。 | ### 当前支持情况表 | 硬件 / 系列 | 状态 | 范围 | |---|---|---| | 经典 ESP32 系列 | **物理测试 + CI 编译** | UART 网关、协议向量、注册、票、奖励和撤销流程 | | ESP32-S2 | **CI 编译** | 仅 `WiFiMiner`；无物理测试 | | ESP32-S3 | **CI 编译** | 仅 `WiFiMiner`；无物理测试 | | ESP32-C3 | **CI 编译** | 仅 `WiFiMiner`；无物理测试 | | ESP32-C2/C5/C6/C61/H2/P4 | **已规划** | 需要适应特定型号的网络和身份适配器 | | ESP8266 | **已规划** | 无可用/经验证的 miner | | RP2040 / Raspberry Pi Pico W | **已规划** | 无可用/经验证的 miner | | SAMD / Nano / MKR 系列 | **已规划** | 需额外验证开发板和 secure-element 能力 | | STM32 Arduino 内核 | **已规划** | 需基于 MCU 和开发板进行适配 | | Renesas Arduino 内核 | **已规划** | 需基于目标进行适配 | | ATECC608A / ECC508 | **已规划** | 目前的示例为 fail-closed 占位符；并非真正的集成 | 物理证据： [`arduino/HARDWARE_TEST_REPORT.md`](arduino/HARDWARE_TEST_REPORT.md) 和 [`arduino/board-configs/support-matrix.json`](arduino/board-configs/support-matrix.json)。 ## 安全等级 EPDN 将身份存储的强度分为 L0 到 L4： ``` flowchart LR L0["L0
Yazılım test anahtarı"] --> L1["L1
Korumalı yazılım"] L1 --> L2["L2
Yerel donanım kimliği"] L2 --> L3["L3
Harici secure element"] L3 --> L4["L4
Attestation destekli platform"] ``` | 等级 | 简述 | 本仓库中的状态 | |---|---|---| | **L0** | 可导出的开发/测试密钥 | 目前的 ESP32 开发路径 | | **L1** | 软件可访问但受到更好保护的存储 | 需要特定目标的证明 | | **L2** | 签名过程依赖于本地硬件 | 尚无经过验证的通用 backend | | **L3** | 密钥不离开 secure element | 计划集成 ATECC | | **L4** | 通过签名的 attestation 提供平台度量 | 设计目标 | 生产策略拒绝 L0 身份。开发板名称中带有“secure”或“ESP32”并不足以赋予其 L2/L4 等级。详情参见： [`docs/security-classes.md`](docs/security-classes.md)。 ## 信任与威胁模型 ``` flowchart TB PA["Provisioning otoritesi
GÜVENİLİR"] -->|"sertifika imzalar"| CERT["Cihaz sertifikası"] DEVICE["Cihaz anahtarı
SEÇİLEN BACKEND KADAR GÜVENLİ"] -->|"bilet imzalar"| TICKET["İmzalı bilet"] GATE["UART Gateway
GÜVENİLMEZ"] -->|"düşürebilir / geciktirebilir / tekrar oynatabilir"| NODE["Validator"] CERT --> NODE TICKET --> GATE NODE -->|"bütün kuralları yeniden doğrular"| BLOCK["İmzalı blok"] BLOCK -->|"buradan yeniden oluşturulur"| INDEX["Indexer
YENİDEN OLUŞTURULABİLİR"] ``` 系统基于以下假设： - Provisioning 授权方不应生成虚假身份。 - Validator 的 CA 和区块签名密钥必须受到保护。 - 设备密钥的安全等级取决于所选 backend 的强度。 - Gateway 不被视为可信；node 会对收到的数据进行重新验证。 - MAC 地址、IP 地址、RSSI、开发板型号、重置原因或时间延迟都不是设备身份的信任根。 关键防御措施： - P-256 签名和基于 SHA-256 的域分离 Hash。 - 固定排序、大小受限的规范化二进制编码。 - 每个身份在每个 epoch 仅限一张票，并进行重放检查。 - 证书、固件、安全等级和撤销策略。 - 签名、带有校验和且原子化的 V3 node 状态记录。 - 对于向 loopback 之外暴露的 node，强制要求使用强大的 admin token、严格的 CORS 列表以及相互独立的 CA/validator 密钥。 - 对于不支持的生产后端，直接报错而不是静默降级。 完整的威胁模型：[`THREAT_MODEL.md`](THREAT_MODEL.md)。 ## 隐私与数据边界 EPDN 不是一款提供匿名性的产品。区块、交易、奖励地址和公开的设备身份可能是测试网络中的公开数据。这里的隐私目标是防止不必要的个人和设备识别数据泄漏到源代码、日志和公开的浏览器中。 ``` flowchart LR PRIVATE["Yerel ve gizli kalmalı
özel anahtarlar
Wi-Fi parolası
admin token'ı
ham seri loglar"] PUBLIC["Ağda paylaşılabilir
açık anahtar hash'i
sertifika
imzalı bilet
blok ve işlem"] UI["Dashboard / Indexer
yalnız gerekli genel alanlar"] PRIVATE -.->|"gönderilmez"| PUBLIC PUBLIC --> UI ``` | 数据 | 应存放的位置 | |---|---| | 设备私钥 | 仅限设备所选的身份 backend | | 钱包私钥 | 加密的 IndexedDB 记录，以及解锁状态下的浏览器内存 | | Wi-Fi 密码 | 交互式本地输入和设备的本地存储 | | Admin token | 本地/runtime 环境变量 | | 原始串口输出 | 被 Git 忽略的本地测试文件夹 | | 公开的设备身份和证书 | 测试网络注册表 | | 区块和已签名的交易 | 公开的测试网络数据 | | 个人的设备标签 | 仅限授权的 dashboard 应用数据 | 请勿将以下内容放入 issue、commit、截图或公开日志中： - 私钥和恢复数据 - Wi-Fi SSID/密码 - Admin token - 完整的串口转储 - MAC 地址、USB 标识和唯一的芯片 ID - eFuse/security posture 转储 - 个人文件路径、用户名或电子邮件地址 ## 快速入门 首先选择您想要查看的内容： ``` flowchart TD START["Neyi denemek istiyorsunuz?"] START -->|"Sadece arayüz"| DEMO["Yol 1
Dashboard demo"] START -->|"Gerçek yerel API"| LOCAL["Yol 2
Validator + dashboard"] START -->|"Otomatik ağ kontrolü"| SMOKE["Yol 3
Üç süreçli smoke testi"] START -->|"Cihaz kodu"| HW["Yol 4
ESP32 derleme"] ``` ### 前置条件 您只需安装所选路径所需的工具。 | 工具 | 版本 | 何处需要 | |---|---:|---| | Git | 最新版 | 用于下载仓库 | | Rust | 1.85 | 协议和 node | | Python | 3.11+ | Provisioning、gateway、indexer 和 testnet 脚本 | | Node.js | 22.13+ | Dashboard/PWA | | Arduino CLI | 1.5.0 | 编译 ESP32 代码 | | ESP32 Arduino core | 2.0.11 | ESP32 目标 | | Docker | 可选 | Node container | 下载仓库： ``` git clone https://github.com/UfkuAcik/EPDN-Network.git cd EPDN-Network ``` ### 路径 1：仅查看界面 此路径不需要物理设备、Rust 或 Python。如果找不到 Validator，dashboard 会明确显示 **DEMO DATA** 标签并使用确定性的示例数据。 ``` cd dashboard npm ci npm run dev ``` 在浏览器中打开 [http://localhost:3000](http://localhost:3000)。 预期结果： - 打开浏览器界面。 - 显示示例区块和设备。 - 顶部会标明这是演示数据而非实时网络。 - 在演示模式下，转账或撤销操作不会发送到真实网络。 ### 路径 2：本地 validator 和 dashboard #### 1. 启动 Validator 在仓库根目录下： ``` cargo run -p epdn-node ``` Node 默认仅在 `127.0.0.1:8745` 上监听。健康检查： ``` curl http://127.0.0.1:8745/healthz ``` 在 loopback 开发模式下，可以使用本地且刻意设为不安全的默认密钥。在将 Node 暴露给其他计算机访问之前，请阅读 [`node/README.md`](node/README.md) 中必需的安全配置变量。 #### 2. 将 dashboard 连接到 node 打开一个新的终端。 PowerShell： ``` Set-Location dashboard $env:EPDN_API_BASE_URL = "http://127.0.0.1:8745" npm ci npm run dev ``` Bash： ``` cd dashboard npm ci EPDN_API_BASE_URL=http://127.0.0.1:8745 npm run dev ``` 在 dashboard 的 API 字段中也可以选择 `http://127.0.0.1:8745`。如果连接成功，数据源将显示为实时 node 而不是演示。 ### 路径 3：三进程测试 ``` python scripts/testnet.py smoke ``` 此命令将执行以下操作： 1. 编译最新的 `epdn-node` 代码。 2. 在 `8745`、`8746` 和 `8747` 端口上启动三个独立的本地进程。 3. 检查健康状态和基本的网络信息。 4. 运行带有三个 validator 的确定性 commit/reveal 测试。 5. 关闭进程并清理临时状态。 如果端口被占用： ``` python scripts/testnet.py --ports 18745,18746,18747 smoke ``` ### 路径 4：编译 ESP32 代码 首先安装固定的 ESP32 核心： ``` arduino-cli config init arduino-cli config add board_manager.additional_urls https://espressif.github.io/arduino-esp32/package_esp32_index.json arduino-cli core update-index arduino-cli core install esp32:esp32@2.0.11 ``` 在不对硬件进行任何烧录的情况下编译识别示例： ``` arduino-cli compile \ --fqbn esp32:esp32:esp32 \ --libraries arduino/libraries \ arduino/examples/SecurityDiagnostic ``` 在 PowerShell 中，同样的命令也可以作为单行运行： ``` arduino-cli compile --fqbn esp32:esp32:esp32 --libraries arduino/libraries arduino/examples/SecurityDiagnostic ``` 其他示例： | 示例 | 目的 | |---|---| | `SecurityDiagnostic` | 安全地检查目标报告的安全能力 | | `SerialProvisioning` | 通过串口连接接收 Wi-Fi 和开发注册数据 | | `WiFiMiner` | 通过 Wi-Fi 直接与 node 通信 | | `GatewayMiner` | 通过 UART 网关发送已签名的票 | | `ProtocolTestVectors` | 验证 Rust 和 Arduino 编码是否产生相同的字节 | | `SecureElementMiner` | 规划中的 secure-element 路径的 fail-closed 占位符 | 有关设备设置，请参见： [`arduino/README.md`](arduino/README.md)、 [`docs/hardware-testing.md`](docs/hardware-testing.md) 和 [`docs/wifi-provisioning.md`](docs/wifi-provisioning.md)。 ## 仓库结构 ``` EPDN-Network/ ├── protocol/ Konsensüs kuralları ve kanonik binary kodlama ├── node/ Rust validator, REST/SSE API ve kalıcı durum ├── arduino/ EPDN cihaz kütüphanesi ve ESP32 örnekleri ├── provisioning/ Cihaz kayıt ve yönetim CLI'ı ├── gateway/ UART ile node arasında imzalı veri rölesi ├── indexer/ SQLite okuma modeli ve JSON dışa aktarma ├── dashboard/ Explorer, cihaz paneli ve yerel cüzdan PWA ├── scripts/ Testnet çalıştırıcısı ve secret tarayıcısı ├── tests/ Gizlilik korunmuş donanım kanıtları ├── docs/ Mimari ve operasyon belgeleri ├── PROTOCOL.md Protokol güven sınırı ├── THREAT_MODEL.md Tehdit modeli ├── ROADMAP.md Planlanan geliştirmeler └── SECURITY.md Güvenlik açığı bildirim kuralları ``` ``` flowchart TB PROTOCOL["protocol/
Ortak kurallar"] --> NODE["node/
Kuralları uygular"] PROTOCOL --> ARD["arduino/
Uyumlu bilet üretir"] PROV["provisioning/
Kimlik kurar"] --> ARD ARD --> GATE["gateway/
UART rölesi"] ARD --> NODE GATE --> NODE IDX["indexer/
Okuma modeli"] -->|"GET blok listesi"| NODE NODE --> WEB["dashboard/
Explorer ve cüzdan"] ``` ## API 摘要 Node 提供两种类型的 endpoint： | 类型 | 示例 | 授权 | |---|---|---| | 健康/网络 | `/healthz`, `/metrics`, `/api/v1/network/status` | 公开 | | Epoch 和票 | `/api/v1/epochs/current`, `/api/v1/tickets` | Challenge 公开；票将通过加密方式验证 | | 区块和账户 | `/api/v1/blocks`, `/api/v1/address/{address}` | 公开 | | 设备视图 | `/api/v1/miners`, `/api/v1/miners/{public_id}` | 公开字段 | | 事件流 | `/api/v1/events` | 公开 SSE | | 注册和管理 | `/api/v1/admin/enroll`, `/api/v1/admin/register`, `/api/v1/admin/miners/{public_id}/revoke` | Admin token | | 转账 | `/api/v1/transactions` | 钱包签名 | 完整的 API 列表和环境变量： [`node/README.md`](node/README.md)。 ## 测试与质量门禁 ``` flowchart LR PUSH["Push / Pull Request"] --> RUST["Rust
build + fmt + clippy + test + audit"] PUSH --> PY["Python
compile + test + audit"] PUSH --> WEB["Dashboard
lint + build + test + audit"] PUSH --> ARD["Arduino
ESP32 derleme matrisi"] PUSH --> SEC["Secret taraması
mevcut ağaç + Git geçmişi"] PUSH --> NET["Yerel testnet
üç süreçli smoke"] PUSH --> DOCKER["Docker
node image build"] ``` 本地基本检查： ``` cargo fmt --all -- --check cargo clippy --locked --workspace --all-targets -- -D warnings cargo test --locked --workspace python -m pip install -e "./provisioning[test]" -e "./gateway" -e "./indexer[test]" python -m pytest -q provisioning/tests gateway/tests indexer/tests scripts/tests python scripts/check-secrets.py --history cd dashboard npm ci npm run lint npm test ``` CI 还会： - 扫描 Rust、Python 和生产环境 dashboard 的依赖项是否存在安全漏洞。 - 验证 Rust 通用协议向量，并检查 Arduino 向量示例是否已编译。 - 编译 ESP32 示例及额外的 ESP32 目标。 - 验证生产 build 中是否拒绝 L0 身份。 - 构建 Docker node 镜像。 详情见：[`docs/ci.md`](docs/ci.md)。 ## 已知局限 - 目前运行的设备应用程序以 ESP32 为中心；其他嵌入式系列尚未准备好。 - 目前的 ESP32 开发身份是存储在 NVS 中的 L0 软件密钥；它不是硬件支持的，也不是不可克隆的。 - 尚未进行物理 Wi-Fi 端到端测试。 - 签名的 V3 状态记录已进行自动化测试；使用物理 ESP32 的重启测试在 V2 中曾通过，而 V3 尚待进行物理复测。 - 单 node 开发的随机性并非安全或无偏见的生产级随机性。 - 三进程测试不提供真正的 P2P 同步或 Byzantine 最终性。 - Indexer 尚未具备已发布的可信 validator 密钥检查点，无法独立验证 validator 签名的真实性。 - Dashboard 钱包在本地进行加密；当钱包解锁时，浏览器中的 XSS 或恶意插件可能会滥用签名操作。 - 生产配置流程、HSM/离线 CA、签名 OTA、回滚机制和独立的安全审计尚未完成。 ## 文档 ### 首先阅读这些 | 文档 | 何时阅读？ | |---|---| | [`PROTOCOL.md`](PROTOCOL.md) | 了解协议对哪些内容进行了签名和 Hash | | [`THREAT_MODEL.md`](THREAT_MODEL.md) | 查看系统信任什么以及不防范什么 | | [`docs/architecture.md`](docs/architecture.md) | 详细了解组件边界 | | [`docs/consensus.md`](docs/consensus.md) | 了解 PoPED、epoch 和 commit/reveal 逻辑 | | [`SECURITY.md`](SECURITY.md) | 私下披露安全漏洞 | ### 运行与操作 | 文档 主题 | |---|---| | [`docs/local-testnet.md`](docs/local-testnet.md) | 本地 node 进程和 Docker | | [`node/README.md`](node/README.md) | Node 配置、状态格式和 API | | [`arduino/README.md`](arduino/README.md) | Arduino 库和 miner 示例 | | [`provisioning/README.md`](provisioning/README.md) | 设备注册 CLI | | [`gateway/README.md`](gateway/README.md) | UART gateway | | [`indexer/README.md`](indexer/README.md) | SQLite indexer 和 export | | [`dashboard/README.md`](dashboard/README.md) | PWA、钱包和 dashboard | ### 硬件与安全 | 文档 | 主题 | |---|---| | [`docs/supported-boards.md`](docs/supported-boards.md) | 目标开发板系列及其评估方法 | | [`docs/security-classes.md`](docs/security-classes.md) | L0–L4 等级分类 | | [`docs/hardware-testing.md`](docs/hardware-testing.md) | 安全的物理测试顺序 | | [`docs/wifi-provisioning.md`](docs/wifi-provisioning.md) | 在不将 Wi-Fi 信息硬编码到源代码中的情况进行配置 | | [`docs/wallet-security.md`](docs/wallet-security.md) | 浏览器钱包的安全边界 | | [`docs/production-hardening.md`](docs/production-hardening.md) | 投入生产前所需的准备 | | [`arduino/HARDWARE_TEST_REPORT.md`](arduino/HARDWARE_TEST_REPORT.md) | 保护隐私的物理测试摘要 | ## 路线图 主要目标： 1. 为 ESP32 以外的嵌入式系列提供真实且经过测试的平台适配器。 2. 使用如 ATECC608A/ECC508 之类的 secure element 实现 L3 身份。 3. 为 ESP32 系列提供经验证的 L2 硬件身份方案。 4. 实现已签名且可重现的 OTA、回滚机制和 measured boot。 5. 基于 HSM 的 CA、双重控制和证书生命周期管理。 6. 真正的 P2P 节点同步和生产级的最终性协议。 7. 长期的模糊测试、断电测试和存储损耗测试。 8. 独立的协议和密码学审计。 完整列表：[`ROADMAP.md`](ROADMAP.md)。 ``` flowchart LR MVP["Bugün
ESP32 merkezli MVP"] --> PORT["Çoklu cihaz adaptörleri"] MVP --> HWKEY["Doğrulanmış donanım anahtarları"] PORT --> HITL["Hardware-in-the-loop CI"] HWKEY --> AUDIT["Bağımsız güvenlik denetimi"] MVP --> P2P["P2P senkronizasyon ve finality"] HITL --> PROD["Üretim hazırlığı"] AUDIT --> PROD P2P --> PROD ``` ## 贡献与安全报告 在做出贡献之前： 1. 请阅读您将要更改的组件的 README。 2. 如果您正在更改共识数据，请查看 `PROTOCOL.md` 和二进制 V1 规范。 3. 在报告新的开发板支持时，请明确区分“已规划”、“编译”和“物理测试”的证据。 4. 请勿 commit 私钥、Wi-Fi 信息、设备身份或原始硬件输出。 5. 运行相关的测试和密钥扫描。 请勿在公开的 issue 中披露安全漏洞。请使用 [`SECURITY.md`](SECURITY.md) 中的私密报告方法。 ## 许可证 本项目基于 [MIT 许可证](LICENSE) 发布。
标签：ESP32, PWA仪表盘, Rust, 区块链, 可视化界面, 物联网, 网络流量审计, 设备证明, 逆向工具, 通知系统