简介这是一份基于以太坊的 DApp 众筹项目完整毕业设计/课程设计资料包面向区块链方向在校生、毕业设计选题者及希望快速上手 Solidity 与 Web3 开发的学习者解决从智能合约编写到前端交互演示的落地难题。资源共 31 个文件包含 14 个 JS 脚本编译、部署、交互等流程控制、1 个 Solidity 合约源文件、3 个 JSON 配置、2 个 Markdown 文档以及 XMind 项目地图和 PDF 详细设计文档合计约 34.86MB目录覆盖 contracts、public、src 等典型模块便于按图索骥。已有 110 人学习下载项目经助教审核且答辩评价 95 分以上核心代码均已本地编译运行通过。下载后可获得可直接运行的 DApp 众筹项目源码、详细设计文档、部署脚本和项目思维导图既能支撑毕设/课设文档撰写也能作为区块链 DApp 开发的入门与进阶范本。1. 基于以太坊的 Dapp 众筹项目到底在“设计”什么如果你只是想把“项目介绍 收款地址 进度条”放在网页上那根本不需要区块链。基于以太坊的 Dapp 众筹项目真正要设计的是“资金如何被约束”目标金额、截止时间、谁有权提款、失败之后钱怎么退全部写成智能合约前端只负责展示和组装交易。参与者的每一笔资助都直接打进合约地址项目方拿不到私钥就无法挪用。这套方案的读者通常有三类正在做课程设计或毕业设计的学生想从静态页面转向链上开发的前端工程师以及需要快速验证一个众筹 idea 却不想先搭建中心化结算系统的产品开发者。下面按工程落地的顺序把合约设计、Truffle 工程、钱包接入和测试网验证拆开讲。2. 众筹 Dapp 的模块边界谁记账、谁展示、谁签交易2.1 为什么不能只做一个网页传统众筹的流程是项目方提交资料平台审核用户把钱付给平台平台在活动结束后再结算给项目方。整个过程中资金托管和规则执行都由平台承担用户只能相信平台的后台数据。区块链众筹把这段信任关系压缩到合约代码里合约在部署时就锁定了收款地址、目标金额和截止时间后续任何人无法修改这些参数。当然这不代表网页没有存在价值。用户需要看到项目说明、实时进度、自己的资助记录这些展示型内容仍然由前端完成。真正发生变化的是数据的权威来源页面上的数字来自链上调用而不是某个数据库接口。客户端可以随时校验进度条和合约余额是否一致这是 Dapp 与普通网站最本质的区别。这里有个常见的误解认为 Dapp 必须完全去掉服务端前端不能有服务器。实际上众筹项目最常见的做法是静态托管前端加链上合约项目介绍、图片这些非关键数据放传统服务器完全没问题。需要保持权威性的只有资金和状态也就是合约那一层。2.2 众筹生命周期与状态转移我建议把众筹合约设计成有限状态机三个状态就够用。合约里的声明如下// 合约中的状态机声明后文会展开完整实现 enum State { Fundraising, Successful, Failed }筹集中Fundraising是合约部署后的初始状态。这个阶段用户可以调用 fund 函数转入 ETH合约按地址累计每个人的出资额。到达截止时间后合约不会自动切换状态必须由任意账户调用 finalize 函数合约才会根据“总筹集额是否达到目标”进入成功或失败状态。这里要特别说明链上没有定时器任何“到时间自动执行”的逻辑都必须依赖外部触发这是新手最容易漏掉的设计点。成功Successful状态只开放提款操作且只有合约里预先写死的项目方地址能调用。提款会把合约中全部余额转给项目方。失败Failed状态则开放退款操作每个资助者只能取回自己记录在映射里的那部分合约本身不参与分配只是执行者。2.3 三层职责与常见误判层技术载体负责的事容易做的错误设计账本层以太坊合约保存目标金额、截止时间、资助明细执行提款与退款把关键状态放在数据库里合约只存一个总金额展示层前端页面读取合约数据、组装交易、展示事件流用服务端接口代替合约读操作进度条领先于链上事实钱包层MetaMask 等浏览器钱包保存私钥、签名交易、支付 gas私自托管用户私钥或要求用户把助记词交给服务器判断误设计有个简单标准关闭数据库众筹还能不能查出每个人投了多少、能不能完成退款如果能说明权威状态在链上如果不能那只是一个画了区块链界面的传统网站。后面所有章节的代码都围绕这张表的分工展开合约只做账本层的事展示层不保存资金状态。3. 用 Truffle 搭出众筹工程骨架目录、迁移与本地链3.1 为什么选 Truffle 加 Ganache 加 MetaMask以太坊开发工具链这些年已经有很多选择Hardhat、Foundry 都很成熟但这个题目下的“设计与实现”类项目用 Truffle 仍然是最短路径。原因在于Truffle 把编译、部署、测试串成一套命令Ganache 提供本地链和即时出块的测试账户MetaMask 可以把浏览器钱包直接指向本地链三个工具组合正好覆盖合约开发、部署、前端交互三个环节。很多教程里的 pet-shop 和 metacoin 案例都是这套骨架众筹项目不需要推翻它只需要把合约层换成自己的逻辑。如果你之前没有接触过 pet-shop 这类完整案例可以把它当作参考先跑通一个最小案例确认钱包能连上本地链再着手替换合约。下面我直接给出众筹项目的最小骨架。3.2 最小工程目录与初始化命令先准备 Node 环境然后全局安装 Truffle在空目录里初始化工程npm install -g truffle truffle init再启动 Ganache。命令行版本和桌面版都能用关键是固定端口和网络 ID方便后面 MetaMask 连接ganache --port 7545 --networkId 5777 --chain.chainId 5777这里把端口固定在 7545、网络 ID 固定在 5777是为了和后续 truffle-config.js 的默认配置保持一致。初始化后的目录结构如下contracts/ Migration.sol Crowdfunding.sol migrations/ 1_initial_migration.js 2_deploy_contracts.js test/ crowdfunding.test.js build/ contracts/ Crowdfunding.json truffle-config.jscontracts 目录放 Solidity 源文件migrations 目录按编号顺序执行部署test 目录放合约测试build/contracts 是编译产物前端要用的 ABI 和部署地址都会出现在对应 JSON 文件里。3.3 truffle-config 里必须确认的三项配置module.exports { networks: { development: { host: 127.0.0.1, port: 7545, network_id: 5777, }, }, compilers: { solc: { version: 0.8.19, settings: { optimizer: { enabled: true, runs: 200 }, }, }, }, };配置有三处需要理解host 和 port 指向本地 Ganache 的 RPC 地址network_id 必须等于 Ganache 启动时输出的网络 IDsolc.version 是编译器版本建议直接写死一个 0.8.x 版本而不是用默认值否则换机器或换环境时编译结果可能和上次不一致optimizer 的 runs 参数影响合约体积和 gas 成本的平衡对演示项目来说开启优化并把 runs 设在 200 左右是常见选择。配置项作用踩坑点host / port本地链 RPC 监听地址桌面版 Ganache 默认 7545命令行版常用 8545不统一会导致部署超时network_id链的标识MetaMask 切链时也要用同一个 ID否则交易会一直 pendingsolc.versionSolidity 编译器版本合约 pragma 与配置版本不一致时Truffle 会重新拉取编译器3.4 第一个迁移脚本部署脚本写在 migrations/2_deploy_contracts.js 里。构造函数需要三个参数项目方收款地址、目标金额单位 wei、筹款时长秒const Crowdfunding artifacts.require(Crowdfunding); module.exports async function (deployer) { const beneficiary 0x你的Ganache账户地址; const goalWei web3.utils.toWei(5, ether); const duration 600; await deployer.deploy(Crowdfunding, beneficiary, goalWei, duration); const instance await Crowdfunding.deployed(); console.log(Crowdfunding at:, instance.address); };beneficiary 建议从 Ganache 生成的账户列表里随便选一个单独留作项目方地址goalWei 用 toWei 把 5 个 ETH 转成 wei避免在合约层反复换算duration 写 600 秒演示时 10 分钟足够走完一次流程。部署后控制台会打印合约地址先记下这个地址第 5 章初始化合约实例时会用到。如果迁移过程遇到 “network id not valid” 之类的报错优先检查 truffle-config.js 的 network_id 和 Ganache 启动参数是否一致。4. 众筹合约与凭证代币合约的实现状态、权限与事件4.1 用状态机约束资金流向合约是众筹项目的账本层设计目标只有一个让每一笔钱只能按照预设规则流动。下面是完整实现我会逐段说明关键决策。// SPDX-License-Identifier: MIT pragma solidity ^0.8.19; contract Crowdfunding { enum State { Fundraising, Successful, Failed } address public beneficiary; uint256 public goalWei; uint256 public deadline; uint256 public totalRaised; State public state State.Fundraising; bool public closed; mapping(address uint256) public contributions; event Funded(address indexed backer, uint256 amount); event Withdrawn(address indexed beneficiary, uint256 amount); event Refunded(address indexed backer, uint256 amount); modifier onlyBeneficiary() { require(msg.sender beneficiary, only beneficiary); _; } modifier inState(State expected) { require(state expected, wrong state); _; } constructor(address _beneficiary, uint256 _goalWei, uint256 _duration) { beneficiary _beneficiary; goalWei _goalWei; deadline block.timestamp _duration; } function fund() external payable inState(State.Fundraising) { require(block.timestamp deadline, deadline passed); require(msg.value 0, zero value); contributions[msg.sender] msg.value; totalRaised msg.value; emit Funded(msg.sender, msg.value); } function finalize() external inState(State.Fundraising) { require(block.timestamp deadline, still fundraising); state totalRaised goalWei ? State.Successful : State.Failed; } function withdraw() external onlyBeneficiary inState(State.Successful) { require(!closed, closed); closed true; uint256 amount address(this).balance; (bool ok, ) beneficiary.call{value: amount}(); require(ok, transfer failed); emit Withdrawn(beneficiary, amount); } function refund() external inState(State.Failed) { require(!closed, closed); uint256 amount contributions[msg.sender]; require(amount 0, no contribution); contributions[msg.sender] 0; (bool ok, ) msg.sender.call{value: amount}(); require(ok, refund failed); emit Refunded(msg.sender, amount); } }fund 函数加 payable用户转 ETH 时按地址累加totalRaised 每次同步增加作为 finalize 判定成功与否的依据。deadline 在构造函数里用 block.timestamp 加时长算出不使用前端传过来的时间——前端时间可以被篡改而 block.timestamp 由矿工写入所有参与者读到的都是同一个值。finalize 任何人都可以调用这是有意设计链上没有定时任务需要一个公开入口在截止后切换状态。它只做状态切换不转移任何资金。withdraw 和 refund 都加上了 inState 修饰器成功状态只能提款失败状态只能退款状态机在语法层面限制了资金流向。closed 标记把提款和退款变成一次性操作配合“先修改状态再转账”的顺序可以从结构上避免重入攻击。4.2 提款和退款为什么不直接 transfer合约里没有用 Solidity 早期常见的 transfer 方法而是用 call 加 value 的方式转账。transfer 会把 gas 限制在 2300目标地址是合约时容易因为逻辑复杂而失败call 把 gas 交给接收方配合检查和效果分离模式更安全。真正防止重入的关键在 refund 函数转账前先把 contributions 清零withdraw 先置 closed 再转账就算接收方合约在回调里再次调用 refund第二次调用也会因为余额为 0 或 closed 为 true 而直接失败。对于这个众筹合约退款逻辑用的是“拉取模式”资助者自己调用 refund 取钱而不是合约在 finalize 后逐个地址推送。这样项目方不需要维护地址列表每个资助者只对自己负责合约也不用遍历大数组gas 成本更可控。4.3 凭证代币把资助记录变成链上资产如果项目需要给资助者发放凭证可以在众筹合约旁边加一个简版代币合约。它不需要完整实现 ERC20 的全部接口只要能记账和转账就够演示。contract ReceiptToken { mapping(address uint256) public balanceOf; uint256 public totalSupply; address public owner; event Transfer(address indexed from, address indexed to, uint256 amount); modifier onlyOwner() { require(msg.sender owner, only owner); _; } constructor() { owner msg.sender; } function mint(address to, uint256 amount) external onlyOwner { balanceOf[to] amount; totalSupply amount; emit Transfer(address(0), to, amount); } function transfer(address to, uint256 amount) external returns (bool) { require(balanceOf[msg.sender] amount, insufficient balance); balanceOf[msg.sender] - amount; balanceOf[to] amount; emit Transfer(msg.sender, to, amount); return true; } }部署顺序是先把 ReceiptToken 部署给 Crowdfunding 持有也就是把代币合约的 owner 指向众筹合约地址然后在 fund 函数里增加一次 mint 调用金额与资助额等量。这样每个资助者的链上余额既是出资凭证又可以在后续活动中被项目方识别。注意 mint 只对 owner 开放而 owner 是众筹合约所以这个接口不能被任意地址调用。4.4 合约函数权限速查表函数调用条件资金变化触发事件fund筹集中且未到截止时间转入合约余额增加Fundedfinalize筹集中且已到截止时间无无withdraw成功状态仅项目方一次余额全部转给项目方Withdrawnrefund失败状态且未 closed单个资助者取回记录金额Refundedmint仅 owner众筹合约代币总供应量增加Transfer写这几个函数时我建议把“谁能调用、什么状态能调用、会不会动钱、动了钱有没有事件”作为检查清单逐行核对完再编译。这个习惯比依赖任何测试框架都能更早发现设计漏洞。5. Dapp 前端怎么连钱包读合约、写交易与监听事件5.1 从 window.ethereum 到 Web3 实例浏览器端接入以太坊核心对象是 window.ethereum也就是 MetaMask 注入的 API。页面加载时先判断它存不存在然后请求账户授权。第一次连接时 MetaMask 会弹出确认框这是正常的用户确认后返回账户地址async function connectWallet() { if (!window.ethereum) { throw new Error(请先安装 MetaMask); } const accounts await window.ethereum.request({ method: eth_requestAccounts, }); // 切换网络5777 转十六进制是 0x1691 await window.ethereum.request({ method: wallet_switchEthereumChain, params: [{ chainId: 0x1691 }], }); return accounts[0]; }eth_requestAccounts 返回的是一个数组当前选中的账户在第一位wallet_switchEthereumChain 里的 chainId 必须写十六进制字符串Ganache 网络 ID 5777 对应 0x1691。如果 MetaMask 里还没有这个网络switch 会失败此时需要用 wallet_addEthereumChain 先添加参数里带上 rpcUrls 和 chainId。5.2 初始化合约实例ABI 从哪来Truffle 编译后build/contracts/Crowdfunding.json 里有完整的 ABI以及按网络 ID 记录的部署地址。初始化合约实例的常见做法是import artifacts from ./build/contracts/Crowdfunding.json; import Web3 from web3; const web3 new Web3(window.ethereum); const networkId await web3.eth.net.getId(); const deployed artifacts.networks[networkId]; const crowdfunding new web3.eth.Contract(artifacts.abi, deployed.address);artifacts.networks 是编译产物里的部署记录key 是网络 IDvalue 是地址。这里不要手动维护一份地址否则每切一次网络就要改一次代码。把前端配置和编译产物放在一起是 Truffle 项目最省心的接法。5.3 读与写分离call 和 send 的区别读操作不需要钱包签名也不消耗 gas写操作必须由用户确认并支付 gas。众筹页面上最常见的两个操作对应两种调用方式// 读查询目标金额和当前进度 const goal await crowdfunding.methods.goalWei().call(); const raised await crowdfunding.methods.totalRaised().call(); const deadline await crowdfunding.methods.deadline().call(); // 写用户资助 0.1 ETH await crowdfunding.methods.fund().send({ from: account, value: web3.utils.toWei(0.1, ether), gas: 150000, });调用方式是否需要签名是否消耗 gas返回值典型场景call否否函数返回值查询 goalWei、totalRaised、deadlinesend是是交易回执fund、withdraw、refund、finalizesend 里的 gas 是给 MetaMask 的提示值。很多新手在这里不写 gas让 MetaMask 自动估算结果遇到 fund 的 require 条件不满足时MetaMask 会直接报出 gas estimation failed而不是告诉你“截止时间已过”。建议给 gas 留合理余量同时永远准备好处理用户拒绝签名的情况。5.4 监听 Funded 事件刷新进度资助完成后页面上的进度条要实时变化。比较直接的方式是调用一次 totalRaised也可以在事件里拿到同样的值crowdfunding.events.Funded({ filter: { backer: account }, fromBlock: 0, }) .on(data, (event) { const amount web3.utils.fromWei(event.returnValues.amount, ether); console.log(backer ${event.returnValues.backer} 资助 ${amount} ETH); });这里的 fromBlock 建议从 0 开始监听。如果写成 latest在 Ganache 这种即时出块的链上事件可能在订阅建立之前就已经被打包用户刷新页面后发现进度条没更新。真正的生产项目应该自己保存已处理的块高断线重连后从上次位置继续避免事件重复处理课程设计做到从 0 监听加页面刷新兜底已经够演示。5.5 三个常见的前端失败点MetaMask 连接的链和合约部署链不一致是最难排查的问题。调试时先打开 MetaMask 看网络名称再对比 truffle-config.js 里的 network_id。第二个是用户切换账户后前端还持有旧的 account 变量send 时 from 传入旧地址导致签名错误建议在每次交易前重新调用 eth_requestAccounts。第三个是数字精度问题前端拿到 wei 时应该用字符串处理或者用 web3.utils.toWei 与 fromWei 双向转换不要直接用 JavaScript 的 number 类型做金额比较。6. 部署测试网后的验证动作与回滚测试技巧6.1 用一条命令切到测试网本地验证通过后把同样的合约部署到 Sepolia 测试网迁移命令只需要加网络参数truffle migrate --network sepolia --resettruffle-config.js 里需要新增 sepolia 网络配置通过环境变量传入私钥和 RPC 地址避免把私钥写进代码仓库const HDWalletProvider require(truffle/hdwallet-provider); module.exports { networks: { sepolia: { provider: () new HDWalletProvider( process.env.PRIVATE_KEY, process.env.SEPOLIA_RPC_URL ), network_id: 11155111, }, }, };配置里的 PRIVATE_KEY 是部署账户的私钥建议单独建一个账户专门部署不要和你日常使用的钱包混用SEPOLIA_RPC_URL 填写测试网公开 RPC 地址或自建 RPC 地址。部署前确认账户里有测试币否则第一步迁移就会因为余额不足失败。6.2 在区块浏览器上核对三件事部署完成后先别急着接前端打开区块浏览器按地址核对三件事合约地址是否与迁移日志一致确认没有把测试网地址复制到别的网络源码验证时编译器版本、optimizer 开关和 runs 值必须和 truffle-config.js 完全一致任何一项对不上都会验证失败用事件标签页过滤 Funded 和 Refunded确认真实交易产生的记录能被浏览器解析。检查项核对方式失败时的典型表现合约地址迁移日志与浏览器页面比对前端连的旧地址交易 pending源码验证对照 compiler 和 optimizer 配置验证失败报字节码不匹配事件解析浏览器事件过滤器事件参数是乱码或缺失6.3 回滚测试两个必须写进 test 目录的用例众筹合约最容易出问题的逻辑不是“成功提款”而是“失败退款”。下面两个测试覆盖了退款路径和权限边界直接用 truffle test 跑const Crowdfunding artifacts.require(Crowdfunding); contract(Crowdfunding, (accounts) { const [beneficiary, backer] accounts; it(失败后退款重复退款会 revert, async () { const instance await Crowdfunding.new( beneficiary, web3.utils.toWei(1, ether), 2 ); await instance.fund({ from: backer, value: web3.utils.toWei(0.5, ether), }); await new Promise((resolve) setTimeout(resolve, 3000)); await instance.finalize({ from: beneficiary }); await instance.refund({ from: backer }); let reverted false; try { await instance.refund({ from: backer }); } catch (e) { reverted true; } assert.isTrue(reverted, 重复退款应该失败); }); it(非项目方调用 withdraw 会被拒绝, async () { const instance await Crowdfunding.new( beneficiary, web3.utils.toWei(1, ether), 2 ); await instance.fund({ from: backer, value: web3.utils.toWei(1, ether), }); await new Promise((resolve) setTimeout(resolve, 3000)); await instance.finalize({ from: beneficiary }); let reverted false; try { await instance.withdraw({ from: backer }); } catch (e) { reverted true; } assert.isTrue(reverted, 非项目方不能提款); }); });两个测试都先用较短时长快速走完筹款周期再主动触发 finalize缩短测试运行时间。第二段测试的侧重点在修饰器withdraw 上同时挂了 onlyBeneficiary 和 inState任意一个条件不满足都应 revert。把这两个用例留在 test 目录里之后每改一次合约就运行 truffle test回滚路径是否被破坏一眼就能看出来。本文还有配套的精品资源点击获取
简介这是一份基于以太坊的 DApp 众筹项目完整毕业设计/课程设计资料包面向区块链方向在校生、毕业设计选题者及希望快速上手 Solidity 与 Web3 开发的学习者解决从智能合约编写到前端交互演示的落地难题。资源共 31 个文件包含 14 个 JS 脚本编译、部署、交互等流程控制、1 个 Solidity 合约源文件、3 个 JSON 配置、2 个 Markdown 文档以及 XMind 项目地图和 PDF 详细设计文档合计约 34.86MB目录覆盖 contracts、public、src 等典型模块便于按图索骥。已有 110 人学习下载项目经助教审核且答辩评价 95 分以上核心代码均已本地编译运行通过。下载后可获得可直接运行的 DApp 众筹项目源码、详细设计文档、部署脚本和项目思维导图既能支撑毕设/课设文档撰写也能作为区块链 DApp 开发的入门与进阶范本。1. 基于以太坊的 Dapp 众筹项目到底在“设计”什么如果你只是想把“项目介绍 收款地址 进度条”放在网页上那根本不需要区块链。基于以太坊的 Dapp 众筹项目真正要设计的是“资金如何被约束”目标金额、截止时间、谁有权提款、失败之后钱怎么退全部写成智能合约前端只负责展示和组装交易。参与者的每一笔资助都直接打进合约地址项目方拿不到私钥就无法挪用。这套方案的读者通常有三类正在做课程设计或毕业设计的学生想从静态页面转向链上开发的前端工程师以及需要快速验证一个众筹 idea 却不想先搭建中心化结算系统的产品开发者。下面按工程落地的顺序把合约设计、Truffle 工程、钱包接入和测试网验证拆开讲。2. 众筹 Dapp 的模块边界谁记账、谁展示、谁签交易2.1 为什么不能只做一个网页传统众筹的流程是项目方提交资料平台审核用户把钱付给平台平台在活动结束后再结算给项目方。整个过程中资金托管和规则执行都由平台承担用户只能相信平台的后台数据。区块链众筹把这段信任关系压缩到合约代码里合约在部署时就锁定了收款地址、目标金额和截止时间后续任何人无法修改这些参数。当然这不代表网页没有存在价值。用户需要看到项目说明、实时进度、自己的资助记录这些展示型内容仍然由前端完成。真正发生变化的是数据的权威来源页面上的数字来自链上调用而不是某个数据库接口。客户端可以随时校验进度条和合约余额是否一致这是 Dapp 与普通网站最本质的区别。这里有个常见的误解认为 Dapp 必须完全去掉服务端前端不能有服务器。实际上众筹项目最常见的做法是静态托管前端加链上合约项目介绍、图片这些非关键数据放传统服务器完全没问题。需要保持权威性的只有资金和状态也就是合约那一层。2.2 众筹生命周期与状态转移我建议把众筹合约设计成有限状态机三个状态就够用。合约里的声明如下// 合约中的状态机声明后文会展开完整实现 enum State { Fundraising, Successful, Failed }筹集中Fundraising是合约部署后的初始状态。这个阶段用户可以调用 fund 函数转入 ETH合约按地址累计每个人的出资额。到达截止时间后合约不会自动切换状态必须由任意账户调用 finalize 函数合约才会根据“总筹集额是否达到目标”进入成功或失败状态。这里要特别说明链上没有定时器任何“到时间自动执行”的逻辑都必须依赖外部触发这是新手最容易漏掉的设计点。成功Successful状态只开放提款操作且只有合约里预先写死的项目方地址能调用。提款会把合约中全部余额转给项目方。失败Failed状态则开放退款操作每个资助者只能取回自己记录在映射里的那部分合约本身不参与分配只是执行者。2.3 三层职责与常见误判层技术载体负责的事容易做的错误设计账本层以太坊合约保存目标金额、截止时间、资助明细执行提款与退款把关键状态放在数据库里合约只存一个总金额展示层前端页面读取合约数据、组装交易、展示事件流用服务端接口代替合约读操作进度条领先于链上事实钱包层MetaMask 等浏览器钱包保存私钥、签名交易、支付 gas私自托管用户私钥或要求用户把助记词交给服务器判断误设计有个简单标准关闭数据库众筹还能不能查出每个人投了多少、能不能完成退款如果能说明权威状态在链上如果不能那只是一个画了区块链界面的传统网站。后面所有章节的代码都围绕这张表的分工展开合约只做账本层的事展示层不保存资金状态。3. 用 Truffle 搭出众筹工程骨架目录、迁移与本地链3.1 为什么选 Truffle 加 Ganache 加 MetaMask以太坊开发工具链这些年已经有很多选择Hardhat、Foundry 都很成熟但这个题目下的“设计与实现”类项目用 Truffle 仍然是最短路径。原因在于Truffle 把编译、部署、测试串成一套命令Ganache 提供本地链和即时出块的测试账户MetaMask 可以把浏览器钱包直接指向本地链三个工具组合正好覆盖合约开发、部署、前端交互三个环节。很多教程里的 pet-shop 和 metacoin 案例都是这套骨架众筹项目不需要推翻它只需要把合约层换成自己的逻辑。如果你之前没有接触过 pet-shop 这类完整案例可以把它当作参考先跑通一个最小案例确认钱包能连上本地链再着手替换合约。下面我直接给出众筹项目的最小骨架。3.2 最小工程目录与初始化命令先准备 Node 环境然后全局安装 Truffle在空目录里初始化工程npm install -g truffle truffle init再启动 Ganache。命令行版本和桌面版都能用关键是固定端口和网络 ID方便后面 MetaMask 连接ganache --port 7545 --networkId 5777 --chain.chainId 5777这里把端口固定在 7545、网络 ID 固定在 5777是为了和后续 truffle-config.js 的默认配置保持一致。初始化后的目录结构如下contracts/ Migration.sol Crowdfunding.sol migrations/ 1_initial_migration.js 2_deploy_contracts.js test/ crowdfunding.test.js build/ contracts/ Crowdfunding.json truffle-config.jscontracts 目录放 Solidity 源文件migrations 目录按编号顺序执行部署test 目录放合约测试build/contracts 是编译产物前端要用的 ABI 和部署地址都会出现在对应 JSON 文件里。3.3 truffle-config 里必须确认的三项配置module.exports { networks: { development: { host: 127.0.0.1, port: 7545, network_id: 5777, }, }, compilers: { solc: { version: 0.8.19, settings: { optimizer: { enabled: true, runs: 200 }, }, }, }, };配置有三处需要理解host 和 port 指向本地 Ganache 的 RPC 地址network_id 必须等于 Ganache 启动时输出的网络 IDsolc.version 是编译器版本建议直接写死一个 0.8.x 版本而不是用默认值否则换机器或换环境时编译结果可能和上次不一致optimizer 的 runs 参数影响合约体积和 gas 成本的平衡对演示项目来说开启优化并把 runs 设在 200 左右是常见选择。配置项作用踩坑点host / port本地链 RPC 监听地址桌面版 Ganache 默认 7545命令行版常用 8545不统一会导致部署超时network_id链的标识MetaMask 切链时也要用同一个 ID否则交易会一直 pendingsolc.versionSolidity 编译器版本合约 pragma 与配置版本不一致时Truffle 会重新拉取编译器3.4 第一个迁移脚本部署脚本写在 migrations/2_deploy_contracts.js 里。构造函数需要三个参数项目方收款地址、目标金额单位 wei、筹款时长秒const Crowdfunding artifacts.require(Crowdfunding); module.exports async function (deployer) { const beneficiary 0x你的Ganache账户地址; const goalWei web3.utils.toWei(5, ether); const duration 600; await deployer.deploy(Crowdfunding, beneficiary, goalWei, duration); const instance await Crowdfunding.deployed(); console.log(Crowdfunding at:, instance.address); };beneficiary 建议从 Ganache 生成的账户列表里随便选一个单独留作项目方地址goalWei 用 toWei 把 5 个 ETH 转成 wei避免在合约层反复换算duration 写 600 秒演示时 10 分钟足够走完一次流程。部署后控制台会打印合约地址先记下这个地址第 5 章初始化合约实例时会用到。如果迁移过程遇到 “network id not valid” 之类的报错优先检查 truffle-config.js 的 network_id 和 Ganache 启动参数是否一致。4. 众筹合约与凭证代币合约的实现状态、权限与事件4.1 用状态机约束资金流向合约是众筹项目的账本层设计目标只有一个让每一笔钱只能按照预设规则流动。下面是完整实现我会逐段说明关键决策。// SPDX-License-Identifier: MIT pragma solidity ^0.8.19; contract Crowdfunding { enum State { Fundraising, Successful, Failed } address public beneficiary; uint256 public goalWei; uint256 public deadline; uint256 public totalRaised; State public state State.Fundraising; bool public closed; mapping(address uint256) public contributions; event Funded(address indexed backer, uint256 amount); event Withdrawn(address indexed beneficiary, uint256 amount); event Refunded(address indexed backer, uint256 amount); modifier onlyBeneficiary() { require(msg.sender beneficiary, only beneficiary); _; } modifier inState(State expected) { require(state expected, wrong state); _; } constructor(address _beneficiary, uint256 _goalWei, uint256 _duration) { beneficiary _beneficiary; goalWei _goalWei; deadline block.timestamp _duration; } function fund() external payable inState(State.Fundraising) { require(block.timestamp deadline, deadline passed); require(msg.value 0, zero value); contributions[msg.sender] msg.value; totalRaised msg.value; emit Funded(msg.sender, msg.value); } function finalize() external inState(State.Fundraising) { require(block.timestamp deadline, still fundraising); state totalRaised goalWei ? State.Successful : State.Failed; } function withdraw() external onlyBeneficiary inState(State.Successful) { require(!closed, closed); closed true; uint256 amount address(this).balance; (bool ok, ) beneficiary.call{value: amount}(); require(ok, transfer failed); emit Withdrawn(beneficiary, amount); } function refund() external inState(State.Failed) { require(!closed, closed); uint256 amount contributions[msg.sender]; require(amount 0, no contribution); contributions[msg.sender] 0; (bool ok, ) msg.sender.call{value: amount}(); require(ok, refund failed); emit Refunded(msg.sender, amount); } }fund 函数加 payable用户转 ETH 时按地址累加totalRaised 每次同步增加作为 finalize 判定成功与否的依据。deadline 在构造函数里用 block.timestamp 加时长算出不使用前端传过来的时间——前端时间可以被篡改而 block.timestamp 由矿工写入所有参与者读到的都是同一个值。finalize 任何人都可以调用这是有意设计链上没有定时任务需要一个公开入口在截止后切换状态。它只做状态切换不转移任何资金。withdraw 和 refund 都加上了 inState 修饰器成功状态只能提款失败状态只能退款状态机在语法层面限制了资金流向。closed 标记把提款和退款变成一次性操作配合“先修改状态再转账”的顺序可以从结构上避免重入攻击。4.2 提款和退款为什么不直接 transfer合约里没有用 Solidity 早期常见的 transfer 方法而是用 call 加 value 的方式转账。transfer 会把 gas 限制在 2300目标地址是合约时容易因为逻辑复杂而失败call 把 gas 交给接收方配合检查和效果分离模式更安全。真正防止重入的关键在 refund 函数转账前先把 contributions 清零withdraw 先置 closed 再转账就算接收方合约在回调里再次调用 refund第二次调用也会因为余额为 0 或 closed 为 true 而直接失败。对于这个众筹合约退款逻辑用的是“拉取模式”资助者自己调用 refund 取钱而不是合约在 finalize 后逐个地址推送。这样项目方不需要维护地址列表每个资助者只对自己负责合约也不用遍历大数组gas 成本更可控。4.3 凭证代币把资助记录变成链上资产如果项目需要给资助者发放凭证可以在众筹合约旁边加一个简版代币合约。它不需要完整实现 ERC20 的全部接口只要能记账和转账就够演示。contract ReceiptToken { mapping(address uint256) public balanceOf; uint256 public totalSupply; address public owner; event Transfer(address indexed from, address indexed to, uint256 amount); modifier onlyOwner() { require(msg.sender owner, only owner); _; } constructor() { owner msg.sender; } function mint(address to, uint256 amount) external onlyOwner { balanceOf[to] amount; totalSupply amount; emit Transfer(address(0), to, amount); } function transfer(address to, uint256 amount) external returns (bool) { require(balanceOf[msg.sender] amount, insufficient balance); balanceOf[msg.sender] - amount; balanceOf[to] amount; emit Transfer(msg.sender, to, amount); return true; } }部署顺序是先把 ReceiptToken 部署给 Crowdfunding 持有也就是把代币合约的 owner 指向众筹合约地址然后在 fund 函数里增加一次 mint 调用金额与资助额等量。这样每个资助者的链上余额既是出资凭证又可以在后续活动中被项目方识别。注意 mint 只对 owner 开放而 owner 是众筹合约所以这个接口不能被任意地址调用。4.4 合约函数权限速查表函数调用条件资金变化触发事件fund筹集中且未到截止时间转入合约余额增加Fundedfinalize筹集中且已到截止时间无无withdraw成功状态仅项目方一次余额全部转给项目方Withdrawnrefund失败状态且未 closed单个资助者取回记录金额Refundedmint仅 owner众筹合约代币总供应量增加Transfer写这几个函数时我建议把“谁能调用、什么状态能调用、会不会动钱、动了钱有没有事件”作为检查清单逐行核对完再编译。这个习惯比依赖任何测试框架都能更早发现设计漏洞。5. Dapp 前端怎么连钱包读合约、写交易与监听事件5.1 从 window.ethereum 到 Web3 实例浏览器端接入以太坊核心对象是 window.ethereum也就是 MetaMask 注入的 API。页面加载时先判断它存不存在然后请求账户授权。第一次连接时 MetaMask 会弹出确认框这是正常的用户确认后返回账户地址async function connectWallet() { if (!window.ethereum) { throw new Error(请先安装 MetaMask); } const accounts await window.ethereum.request({ method: eth_requestAccounts, }); // 切换网络5777 转十六进制是 0x1691 await window.ethereum.request({ method: wallet_switchEthereumChain, params: [{ chainId: 0x1691 }], }); return accounts[0]; }eth_requestAccounts 返回的是一个数组当前选中的账户在第一位wallet_switchEthereumChain 里的 chainId 必须写十六进制字符串Ganache 网络 ID 5777 对应 0x1691。如果 MetaMask 里还没有这个网络switch 会失败此时需要用 wallet_addEthereumChain 先添加参数里带上 rpcUrls 和 chainId。5.2 初始化合约实例ABI 从哪来Truffle 编译后build/contracts/Crowdfunding.json 里有完整的 ABI以及按网络 ID 记录的部署地址。初始化合约实例的常见做法是import artifacts from ./build/contracts/Crowdfunding.json; import Web3 from web3; const web3 new Web3(window.ethereum); const networkId await web3.eth.net.getId(); const deployed artifacts.networks[networkId]; const crowdfunding new web3.eth.Contract(artifacts.abi, deployed.address);artifacts.networks 是编译产物里的部署记录key 是网络 IDvalue 是地址。这里不要手动维护一份地址否则每切一次网络就要改一次代码。把前端配置和编译产物放在一起是 Truffle 项目最省心的接法。5.3 读与写分离call 和 send 的区别读操作不需要钱包签名也不消耗 gas写操作必须由用户确认并支付 gas。众筹页面上最常见的两个操作对应两种调用方式// 读查询目标金额和当前进度 const goal await crowdfunding.methods.goalWei().call(); const raised await crowdfunding.methods.totalRaised().call(); const deadline await crowdfunding.methods.deadline().call(); // 写用户资助 0.1 ETH await crowdfunding.methods.fund().send({ from: account, value: web3.utils.toWei(0.1, ether), gas: 150000, });调用方式是否需要签名是否消耗 gas返回值典型场景call否否函数返回值查询 goalWei、totalRaised、deadlinesend是是交易回执fund、withdraw、refund、finalizesend 里的 gas 是给 MetaMask 的提示值。很多新手在这里不写 gas让 MetaMask 自动估算结果遇到 fund 的 require 条件不满足时MetaMask 会直接报出 gas estimation failed而不是告诉你“截止时间已过”。建议给 gas 留合理余量同时永远准备好处理用户拒绝签名的情况。5.4 监听 Funded 事件刷新进度资助完成后页面上的进度条要实时变化。比较直接的方式是调用一次 totalRaised也可以在事件里拿到同样的值crowdfunding.events.Funded({ filter: { backer: account }, fromBlock: 0, }) .on(data, (event) { const amount web3.utils.fromWei(event.returnValues.amount, ether); console.log(backer ${event.returnValues.backer} 资助 ${amount} ETH); });这里的 fromBlock 建议从 0 开始监听。如果写成 latest在 Ganache 这种即时出块的链上事件可能在订阅建立之前就已经被打包用户刷新页面后发现进度条没更新。真正的生产项目应该自己保存已处理的块高断线重连后从上次位置继续避免事件重复处理课程设计做到从 0 监听加页面刷新兜底已经够演示。5.5 三个常见的前端失败点MetaMask 连接的链和合约部署链不一致是最难排查的问题。调试时先打开 MetaMask 看网络名称再对比 truffle-config.js 里的 network_id。第二个是用户切换账户后前端还持有旧的 account 变量send 时 from 传入旧地址导致签名错误建议在每次交易前重新调用 eth_requestAccounts。第三个是数字精度问题前端拿到 wei 时应该用字符串处理或者用 web3.utils.toWei 与 fromWei 双向转换不要直接用 JavaScript 的 number 类型做金额比较。6. 部署测试网后的验证动作与回滚测试技巧6.1 用一条命令切到测试网本地验证通过后把同样的合约部署到 Sepolia 测试网迁移命令只需要加网络参数truffle migrate --network sepolia --resettruffle-config.js 里需要新增 sepolia 网络配置通过环境变量传入私钥和 RPC 地址避免把私钥写进代码仓库const HDWalletProvider require(truffle/hdwallet-provider); module.exports { networks: { sepolia: { provider: () new HDWalletProvider( process.env.PRIVATE_KEY, process.env.SEPOLIA_RPC_URL ), network_id: 11155111, }, }, };配置里的 PRIVATE_KEY 是部署账户的私钥建议单独建一个账户专门部署不要和你日常使用的钱包混用SEPOLIA_RPC_URL 填写测试网公开 RPC 地址或自建 RPC 地址。部署前确认账户里有测试币否则第一步迁移就会因为余额不足失败。6.2 在区块浏览器上核对三件事部署完成后先别急着接前端打开区块浏览器按地址核对三件事合约地址是否与迁移日志一致确认没有把测试网地址复制到别的网络源码验证时编译器版本、optimizer 开关和 runs 值必须和 truffle-config.js 完全一致任何一项对不上都会验证失败用事件标签页过滤 Funded 和 Refunded确认真实交易产生的记录能被浏览器解析。检查项核对方式失败时的典型表现合约地址迁移日志与浏览器页面比对前端连的旧地址交易 pending源码验证对照 compiler 和 optimizer 配置验证失败报字节码不匹配事件解析浏览器事件过滤器事件参数是乱码或缺失6.3 回滚测试两个必须写进 test 目录的用例众筹合约最容易出问题的逻辑不是“成功提款”而是“失败退款”。下面两个测试覆盖了退款路径和权限边界直接用 truffle test 跑const Crowdfunding artifacts.require(Crowdfunding); contract(Crowdfunding, (accounts) { const [beneficiary, backer] accounts; it(失败后退款重复退款会 revert, async () { const instance await Crowdfunding.new( beneficiary, web3.utils.toWei(1, ether), 2 ); await instance.fund({ from: backer, value: web3.utils.toWei(0.5, ether), }); await new Promise((resolve) setTimeout(resolve, 3000)); await instance.finalize({ from: beneficiary }); await instance.refund({ from: backer }); let reverted false; try { await instance.refund({ from: backer }); } catch (e) { reverted true; } assert.isTrue(reverted, 重复退款应该失败); }); it(非项目方调用 withdraw 会被拒绝, async () { const instance await Crowdfunding.new( beneficiary, web3.utils.toWei(1, ether), 2 ); await instance.fund({ from: backer, value: web3.utils.toWei(1, ether), }); await new Promise((resolve) setTimeout(resolve, 3000)); await instance.finalize({ from: beneficiary }); let reverted false; try { await instance.withdraw({ from: backer }); } catch (e) { reverted true; } assert.isTrue(reverted, 非项目方不能提款); }); });两个测试都先用较短时长快速走完筹款周期再主动触发 finalize缩短测试运行时间。第二段测试的侧重点在修饰器withdraw 上同时挂了 onlyBeneficiary 和 inState任意一个条件不满足都应 revert。把这两个用例留在 test 目录里之后每改一次合约就运行 truffle test回滚路径是否被破坏一眼就能看出来。本文还有配套的精品资源点击获取
)
)
