manastole03/Blockchain-based-e-voting-system

# 基于区块链的电子投票系统 一个安全、透明且可审计的电子投票平台，结合了**生产级自定义区块链后端** (Node.js + TypeScript + PostgreSQL) 与用于许可选举管理的 **Hyperledger Fabric 智能合约架构**。 本项目通过从高层概念框架转向结构更清晰的、由智能合约和 REST API 驱动的架构，增强了选举控制、投票完整性、可审计性和部署就绪性，从而扩展了先前基于区块链投票的研究工作。 ## 目录 1. [研究基础](#1-research-foundation) 2. [项目描述](#2-project-description) 3. [高级版本的改进](#3-what-is-improved-in-this-advanced-version) 4. [目标](#4-objectives) 5. [主要特性](#5-key-features) 6. [技术栈](#6-tech-stack) 7. [项目结构](#7-project-structure) 8. [高级架构](#8-high-level-architecture) 9. [快速开始 — 自定义区块链后端](#9-quick-start--custom-blockchain-backend) 10. [Docker](#10-docker) 11. [配置](#11-configuration) 12. [API 参考](#12-api-reference) 13. [区块链实现](#13-blockchain-implementation) 14. [共识算法](#14-consensus-algorithms) 15. [数据库](#15-database) 16. [测试](#16-tests) 17. [Hyperledger Fabric 链码](#17-hyperledger-fabric-chaincode) 18. [部署](#18-deployment) 19. [项目截图](#19-project-screenshots) ## 1. 研究基础 本代码库基于以下研究工作： - **论文：** *Hyperledger-Based Blockchain Technology for Data Security in E-Voting Systems* - **摘要 / 初始项目名称：** *A Framework to Make Voting System Using Blockchain Technology* 该研究提出基于区块链的投票，是因为区块链提供了： - 去中心化 - 不可篡改性 - 透明性 - 可审计性 - 安全的数字交易 该论文提议使用 **Hyperledger Fabric**，因为它具有许可架构、访问控制支持、组织、节点、通道以及基于链码的执行模型。它还进一步通过使用 **Next.js**、**Node.js**、Fabric SDK 以及云平台上的容器化托管，将该系统映射到 Web 架构。 ## 2. 项目描述 传统投票系统和许多电子投票的实施面临着重大挑战，例如： - 篡改风险 - 缺乏透明度 - 可审计性弱 - 集中控制 - 选举设置和计票期间的操作复杂性 - 选民之间的信任赤字 现有项目是一个 **Next.js + TypeScript** 应用。本后端保留了相同的 Node/TypeScript 技术栈，并增加了： - 带有 PostgreSQL 持久化的专用 Express REST API - 具有可插拔共识的模块化区块链服务 - Docker 支持和结构化的测试 Hyperledger Fabric 层引入了由智能合约驱动的架构，具有以下特点： - 显式的**选举生命周期管理** - 更严格的**一人一票强制执行** - **代币化选票发放** - 结构化的**链码接口** - 改进的**审计事件和结果最终确定** - 更好的跨组件职责分离 - 具备部署就绪能力的项目结构 ## 3. 此高级版本中的改进 与原始概念模型相比，本代码库引入了以下改进： ### 3.1 显式选举阶段 - 注册 - 候选人审批 - 投票开启 - 投票关闭 - 计票最终确定 ### 3.2 一人一票强制执行 - 每位选民都有一个经过验证的身份记录。 - 每位选民在一次特定的选举中只能投出一票。 ### 3.3 隐私感知的选票存储 - 系统不再直接存储明文投票选择，而是在链上存储一个**选票承诺哈希**。 - 这在保持可审计性的同时，减少了敏感投票信息的暴露。 ### 3.4 可审计的结果最终确定 - 所有状态转换和主要投票动作都会被记录在账本中。 - 最终计票可以根据已提交的投票事件进行独立验证。 ### 3.5 更清晰的智能合约结构 - 为选举创建、选民登记、候选人登记、投票、计票和查询操作提供独立的函数。 ### 3.6 选举生命周期状态机 - 草案 - 注册开启 - 投票开启 - 投票关闭 - 结果最终确定 ### 3.7 显式智能合约接口 - 更清晰的签名 - 更易于测试 - 更明确的标准对齐 ### 3.8 投票完整性控制 - 每位选民限投一票的限制 - 不可篡改的链上交易日志 - 特定选举的投票验证 ### 3.9 可审计性 - 关键操作的事件触发 - 透明的选举结束和结果发布 ### 3.10 未来的隐私增强 - 投票承诺哈希 - 可选的匿名凭证支持 - 未来版本中可选的零知识或承诺-揭示（commit-reveal）设计 ## 4. 目标 本项目的主要目标是构建一个基于区块链的投票系统，该系统： - **安全** — 投票在提交后无法被更改 - **透明** — 流程可验证且可审计 - **隐私** — 保护选民身份和投票秘密 - **可追溯** — 可检查授权的审计事件 - **可扩展** — 适用于机构级或部门级选举 - **可延伸** — 可以改进为生产级选举平台 ## 5. 主要特性 ### 5.1 当前 / 计划特性 - 选民登记和资格验证 - 候选人登记 - 选举创建和调度 - 向合格选民发放选票/代币 - 一次性投票 - 防止双重投票 - 由区块链支持的不可篡改投票记录 - 选举状态跟踪 - 投票计票和结果最终确定 - 审计日志生成 - 通过 Hyperledger Fabric 身份进行许可访问 - 用于前端集成的 REST API 中间件 - 使用 Docker 的容器化部署 ### 5.2 自定义区块链后端特性 - 在 `secp256k1` 上进行 ECDSA 签名的交易 - 可插拔共识：工作量证明、权益证明、PBFT - 带有挂起交易管理的内存池 - 每个区块的 Merkle 根计算 - 链验证（哈希、签名、前一个哈希链接、共识规则） - 从 `sha256(publicKey)` 派生的钱包地址 - 结构化的 Pino 日志记录、Helmet、CORS 和速率限制 ## 6. 技术栈 ### 自定义区块链后端 - Node.js + TypeScript - Express REST API - PostgreSQL 数据库 - 在 `secp256k1` 上的原生 Node `crypto` ECDSA 签名 - Zod 请求验证 - Pino 结构化日志 - Helmet、CORS 和速率限制 - Vitest + Supertest - Docker + Docker Compose ### Hyperledger Fabric 层 - Hyperledger Fabric（许可区块链） - JavaScript / Node.js 链码 - Fabric SDK (Node.js) - Next.js 前端 - Docker + Docker Compose ## 7. 项目结构 ### 7.1 自定义区块链后端 ``` src/ app.ts Express app composition server.ts API server entrypoint config/ environment, logger, database pool controllers/ HTTP request handlers database/ migration runner middleware/ validation, rate limit, error handling models/ blockchain domain types repositories/ Postgres and in-memory data adapters routes/ REST route definitions and schemas services/ blockchain, wallet, tx, node, validator logic services/consensus/ PoW, PoS, PBFT consensus adapters utils/ hashing, signing, Merkle root helpers database/schema.sql database schema and indexes tests/ unit and integration tests ``` ### 7.2 Hyperledger Fabric 层 ``` hyperledger-evoting-advanced-starter/ ├── README.md ├── github_repository_link.txt ├── .gitignore ├── docs/ │ ├── architecture.md │ ├── algorithm_advancements.md │ └── rubric_mapping.md └── chaincode-javascript/ ├── package.json ├── index.js └── lib/ └── election-contract.js └── frontend/ ``` ## 8. 高级架构 ``` flowchart TD U[Voter / Election Officer / Auditor] --> F[Frontend - Next.js / Web App] F --> A[API Layer - Node.js / Express] A --> SDK[Hyperledger Fabric SDK] SDK --> CC[Chaincode / Smart Contract] CC --> L[(Ledger + World State)] subgraph Fabric Network O1[Org 1 - Election Authority] O2[Org 2 - Voter Organization] O3[Org 3 - Candidate Organization] O4[Org 4 - Auditor / Observer] end SDK --> O1 SDK --> O2 SDK --> O3 SDK --> O4 ``` ### 8.1 Fabric 组织和选举通道设计 下图代表了研究论文中提出的架构的面向部署的解析。选举主管机构管理选举，候选人节点被逻辑分组，选民节点属于不同的部门/组织，投票交易通过许可的 Fabric 通道和智能合约执行。 ``` flowchart TB subgraph EA[Org 1 - Election Authority] Admin[Admin Peer] CA[Certificate Authority] end subgraph CO[Org 2 - Candidate Organization] Cand1[Candidate Peer 1] Cand2[Candidate Peer 2] end subgraph VO1[Org 3 - Department 1 / Voter Org] V1[Voter Peer 1] end subgraph VO2[Org 4 - Department 2 / Voter Org] V2[Voter Peer 2] end subgraph VO3[Org 5 - Department 3 / Voter Org] V3[Voter Peer 3] end Orderer[Ordering Service] Contract[Election Smart Contract / Chaincode] Ledger[(Ledger + World State)] Admin --> Contract V1 --> Contract V2 --> Contract V3 --> Contract Cand1 --> Contract Cand2 --> Contract Contract --> Orderer Orderer --> Ledger V1 -. Private Election Channel .- Cand1 V2 -. Private Election Channel .- Cand1 V3 -. Private Election Channel .- Cand2 Admin -. Governance / Control Access .- CA ``` ## 9. 快速开始 — 自定义区块链后端 复制环境默认配置： ``` cp .env.example .env ``` 安装依赖项： ``` npm install ``` 启动 Postgres，应用模式，然后运行后端： ``` docker compose up -d postgres npm run db:migrate npm run backend:dev ``` API 运行在 `http://localhost:4000/api`。 ## 10. Docker 使用一条命令运行完整的后端和数据库： ``` docker compose up --build ``` 后端容器在启动 API 之前会应用 `database/schema.sql`。PostgreSQL 数据持久化在 `postgres_data` Docker 卷中。 ## 11. 配置 重要的环境变量： ``` PORT=4000 DATABASE_URL=postgres://evoting:evoting_password@localhost:5432/evoting CONSENSUS_ALGORITHM=pow POW_DIFFICULTY=3 MINING_REWARD=10 MAX_TRANSACTIONS_PER_BLOCK=100 ``` 通过将 `CONSENSUS_ALGORITHM` 设置为 `pow`、`pos` 或 `pbft` 来切换共识。 ## 12. API 参考 所有响应使用： ``` { "success": true, "data": {} } ``` 错误使用： ``` { "success": false, "error": { "code": "ERROR_CODE", "message": "..." } } ``` ### 健康检查 ``` curl http://localhost:4000/api/health ``` ### 创建钱包 ``` curl -X POST http://localhost:4000/api/wallets \ -H "Content-Type: application/json" \ -d '{ "label": "voter-1" }' ``` 私钥仅返回一次。将其在客户端存储；服务器仅保留公钥和地址。 ### 获取钱包余额 ``` curl http://localhost:4000/api/wallets/0xabc123.../balance ``` ### 签名交易 ``` curl -X POST http://localhost:4000/api/transactions/sign \ -H "Content-Type: application/json" \ -d '{ "type": "VOTE", "fromAddress": "0xabc123...", "amount": 0, "payload": { "electionId": "student-council", "candidateId": "candidate-1" }, "privateKey": "-----BEGIN PRIVATE KEY-----..." }' ``` ### 创建交易 使用签名响应中的 `signingPayload`、`signature` 和 `publicKey`： ``` curl -X POST http://localhost:4000/api/transactions \ -H "Content-Type: application/json" \ -d '{ "type": "VOTE", "fromAddress": "0xabc123...", "toAddress": null, "amount": 0, "payload": { "electionId": "student-council", "candidateId": "candidate-1" }, "nonce": 1710000000000, "timestamp": "2026-04-27T12:00:00.000Z", "signature": "base64-signature", "publicKey": "-----BEGIN PUBLIC KEY-----..." }' ``` ### 验证交易 ``` curl -X POST http://localhost:4000/api/transactions/validate \ -H "Content-Type: application/json" \ -d '{ "hash": "64-char-transaction-hash" }' ``` ### 挂起交易 ``` curl http://localhost:4000/api/transactions/pending ``` ### 挖矿或创建区块 ``` curl -X POST http://localhost:4000/api/blocks/mine \ -H "Content-Type: application/json" \ -d '{ "minerAddress": "0xabc123..." }' ``` ### 查看区块链 ``` curl http://localhost:4000/api/blockchain ``` ### 按高度或哈希查看区块 ``` curl http://localhost:4000/api/blocks/1 curl http://localhost:4000/api/blocks/000abc... ``` ### 验证区块链 ``` curl http://localhost:4000/api/blockchain/validate ``` ### 注册节点 ``` curl -X POST http://localhost:4000/api/nodes \ -H "Content-Type: application/json" \ -d '{ "url": "http://node-2:4000", "metadata": { "region": "us-west" } }' ``` ### 注册验证者 权益证明 和 PBFT 必需： ``` curl -X POST http://localhost:4000/api/validators \ -H "Content-Type: application/json" \ -d '{ "address": "0xabc123...", "publicKey": "-----BEGIN PUBLIC KEY-----...", "stake": 100, "nodeUrl": "http://node-1:4000" }' ``` ## 13. 区块链实现 - 区块存储高度、前一个哈希、时间戳、Merkle 根、随机数、难度、共识类型、验证者、元数据和交易。 - 交易是经过 ECDSA 签名的载荷。交易哈希根据规范的 JSON 载荷计算得出。 - 钱包地址从 `sha256(publicKey)` 派生，并仅与公钥一起存储。 - 投票交易需要 `payload.electionId` 和 `payload.candidateId`。 - 挂起交易作为状态为 `PENDING` 的数据库行存储在内存池中。 - 挖矿验证挂起交易，拒绝无效交易，添加可选的奖励交易，计算 Merkle 根，并持久化已确认的区块。 - 链验证重新计算区块哈希、Merkle 根、交易哈希、签名、前一个哈希链接和共识规则。 ## 14. 共识算法 ### 工作量证明 根据 `POW_DIFFICULTY` 挖出带有前导零的区块哈希。 ### 权益证明 根据权益权重从活跃验证者中选择，并验证区块验证者。 ### PBFT 为本地验证者集建立模型，进行准备/提交仲裁持久化。它需要至少四个活跃验证者，并存储共识事件以供审计。接口被隔离，以便真实的网络传输可以替代本地适配器。 ## 15. 数据库 `database/schema.sql` 创建以下表： - `wallets` - `transactions` - `blocks` - `validators` - `network_nodes` - `consensus_events` 包含用于区块查找、挂起交易读取、钱包余额查询、验证者选择和共识事件查找的索引。 ## 16. 测试 ``` npm test ``` 覆盖范围包括： - 交易签名和验证 - 区块创建 - 链验证 - PoW 挖矿 - PoS 验证 - PBFT 仲裁行为 - 通过 REST API 的集成流程 ## 17. Hyperledger Fabric 链码 ### 17.1 设置 #### 必需软件 - Node.js 18+ - npm 9+ - Docker - Docker Compose (或 Docker Desktop) - Hyperledger Fabric 测试网络或 Fabric 部署环境 #### 可选但推荐 - Git - VS Code - Postman / Bruno，用于 API 测试 - Fabric CA 设置，用于基于证书的身份签发 #### 链码设置 ``` cd chaincode-javascript npm install ``` ### 17.2 智能合约概述 智能合约定义了一个名为 `ElectionContract` 的 Fabric 链码组件。 #### 主要接口 / 签名 | 函数 | 描述 | |---|---| | `InitLedger(ctx)` | 引导账本 | | `CreateElection(ctx, electionId, title, startTime, endTime, adminId)` | 创建新选举 | | `RegisterVoter(ctx, electionId, voterId, voterNameHash, department, eligibilityHash)` | 注册合格选民 | | `RegisterCandidate(ctx, electionId, candidateId, candidateName, partyName)` | 注册候选人 | | `OpenVoting(ctx, electionId)` | 将选举转为投票开启状态 | | `CastVote(ctx, electionId, voterId, candidateId, ballotCommitment)` | 投票（每人限投一次） | | `CloseVoting(ctx, electionId)` | 关闭投票阶段 | | `FinalizeTally(ctx, electionId)` | 计算并发布最终结果 | | `GetElection(ctx, electionId)` | 查询选举详情 | | `GetCandidate(ctx, election, candidateId)` | 查询候选人详情 | | `GetVoter(ctx, electionId, voterId)` | 查询选民记录 | | `GetResults(ctx, electionId)` | 查询最终结果 | | `GetElectionAuditTrail(ctx, electionId)` | 查询完整审计轨迹 | ## 18. 部署 ### 18.1 本地草案使用 本代码库包含 Hyperledger 链码的**入门草案**以及生产级 Express 后端。您可以通过三个步骤使用链码层： 1. 查看 `chaincode-javascript/lib/election-contract.js` 中的智能合约草案 2. 针对您的机构或选举模型定制账本模式和验证规则 3. 将链码部署到 Hyperledger Fabric 测试网络 ### 18.2 典型部署流程 1. 启动 Hyperledger Fabric 网络 2. 打包并安装 JavaScript 链码 3. 批准并提交链码定义 4. 使用 Fabric SDK、CLI 或中间件 API 调用链码方法 5. 在 Next.js / React 中构建 Web 应用，并通过 Node.js 后端连接 ### 18.3 未来部署架构示例 | 层 | 技术 | |---|---| | 前端 | Next.js / React 门户，用于管理员、选民和候选人仪表板 | | 后端 / API | Node.js / Express / Fabric SDK | | 区块链 | Hyperledger Fabric peers, orderers, CAs | | 存储 | 账本状态 + 可选的加密链下元数据存储 | | 基础设施 | AWS / GCP / 本地服务器集群上的 Docker 化服务 | ## 19. 项目截图          

标签：CISA项目, Docker, GNU通用公共许可证, Hyperledger Fabric, MITM代理, Node.js, PostgreSQL, REST API, TypeScript, 共识算法, 区块链, 去中心化, 可审计性, 后端开发, 学术研究, 安全插件, 安全防御评估, 智能合约, 测试用例, 电子投票, 联盟链, 请求拦截, 选举系统, 透明度, 链码, 防篡改