WhisperGrove

# Whisper GroveWhisper Grove 是一个部署在 Monad Testnet 上的匿名心声应用。用户可以写下一段心情，由后端调用 DeepSeek 生成温和的情绪回应，然后将内容证明和支持行为记录到 Monad 链上。## 项目特点- 匿名心声：前端不要求用户填写姓名。- AI 回应：后端调用 DeepSeek deepseek-chat 分析情绪并生成回复。- 链上证明：原始文字不会以明文写入区块链，链上保存内容哈希、postId、创建时间和支持数据。- Monad Testnet：发布和支持操作通过 MetaMask 发起 Monad 链上交易，使用测试币 MON 支付 gas。- 可验证性：任何人都可以通过 Monad Explorer 查看合约调用和交易结果。- 容错机制：DeepSeek 未配置、超时或请求失败时，应用会使用本地安全回复，不会阻塞演示流程。## 技术架构```textBrowser / MetaMask | vRender Static Site: React + Vite + Three.js | | POST /api/whispers/analyze vRender Web Service: Express + DeepSeek API | +--> DeepSeek: 情绪分析和回复生成 | +--> Monad Testnet RPC: 链上数据读取和交易验证 | v WhisperTree 合约```## Monad 合约网络：Monad Testnet链 ID：10143RPC：https://testnet-rpc.monad.xyz合约地址：```text0x597240f8b308dF2313bCA312902A61E64D04663c```主要方法：- createWhisper(bytes32 postId, bytes32 contentHash)：发布一条心声证明。- support(bytes32 postId, uint8 supportType)：对心声进行链上支持。- getWhisper(bytes32 postId)：读取心声摘要数据。- hasSupported(bytes32 postId, address supporter)：检查一个钱包是否已经支持过。原始心声保存在后端记录中，链上只保存哈希和摘要数据。这样既可以验证内容证明，又不会把用户的私密文字公开写入区块链。## 目录结构```textWhisperGrove/├─ contracts/ Solidity 合约├─ scripts/ Hardhat 部署脚本├─ test/ 合约测试├─ frontend/ React + Vite 前端│ ├─ src/abi/ 前端合约 ABI│ ├─ src/grove/ Three.js 流光宝海场景│ ├─ src/components/ UI 组件│ └─ src/monad.ts 钱包、RPC 和合约调用├─ backend/ Express 后端│ └─ src/server.ts AI 分析、列表和链上确认接口├─ render.yaml Render 后端部署配置└─ README.md 项目说明和配置文档```## 环境要求- Node.js 20 或更高版本- npm- MetaMask 或其他 EVM 钱包- Monad Testnet 测试币 MON- DeepSeek API Key（需要使用真实 AI 回复时）安装依赖：```powershellnpm install```## 环境变量配置### Hardhat 部署环境在项目根目录创建 .env：```envMONAD_RPC_URL=https://testnet-rpc.monad.xyzPRIVATE_KEY=你的部署钱包私钥ETHERSCAN_API_KEY=你的Etherscan或区块浏览器验证Key```PRIVATE_KEY 只用于部署合约，不要提交到 GitHub，也不要发送给其他人。### 后端环境在 backend/.env 中配置：```envPORT=3000MONAD_RPC_URL=https://testnet-rpc.monad.xyzCONTRACT_ADDRESS=0x597240f8b308dF2313bCA312902A61E64D04663cDEEPSEEK_API_KEY=你的DeepSeek_API_KeyDEEPSEEK_BASE_URL=https://api.deepseek.comDEEPSEEK_MODEL=deepseek-chat```DeepSeek Key 必须只放在后端，不能放入前端环境变量。### 前端环境在 frontend/.env 中配置：```envVITE_API_BASE_URL=http://localhost:3000VITE_MONAD_RPC_URL=https://testnet-rpc.monad.xyzVITE_CONTRACT_ADDRESS=0x597240f8b308dF2313bCA312902A61E64D04663c```前端的 VITE_* 变量会被写入浏览器构建文件，只能放公开配置，不能放私钥或 DeepSeek Key。## 本地运行启动后端，在第一个终端执行：```powershellnpm run backend:dev```启动前端，在第二个终端执行：```powershellnpm run frontend:dev```打开：```texthttp://localhost:5173/```后端健康检查：```texthttp://localhost:3000/health```正常返回：```json{"ok":true}```## 构建和测试```powershellnpm run frontend:buildnpm run backend:buildnpm test```合约测试用于验证创建心声、支持行为和链上状态。修改 Solidity 合约后才需要重新部署；只修改前端或后端时，不需要重新部署合约。如确实修改了合约并需要重新部署：```powershellnpm run deploy:monad```重新部署后必须同步更新：- frontend/.env 的 VITE_CONTRACT_ADDRESS- backend/.env 的 CONTRACT_ADDRESS- Render 和前端托管平台中的同名环境变量- 前端 src/abi/WhisperTree.json（如果 ABI 发生变化）## 线上部署当前推荐使用 Render 部署前后端：```text前端：Render Static Site后端：Render Web Service```### 后端 Render Web Service仓库：```texthttps://github.com/Listen167/WhisperGrove.git```配置：```textBranch: mainRoot Directory: .Build Command: npm install && npm run backend:buildStart Command: npm --prefix backend run startHealth Check Path: /health```后端环境变量：```envMONAD_RPC_URL=https://testnet-rpc.monad.xyzCONTRACT_ADDRESS=0x597240f8b308dF2313bCA312902A61E64D04663cDEEPSEEK_API_KEY=你的DeepSeek_API_KeyDEEPSEEK_MODEL=deepseek-chat```部署后测试：```texthttps://你的后端域名/health```### 前端 Render Static Site同一个 GitHub 仓库创建 Static Site：```textBranch: mainRoot Directory: frontendBuild Command: npm run buildPublish Directory: dist```前端环境变量：```envVITE_API_BASE_URL=https://你的后端域名VITE_MONAD_RPC_URL=https://testnet-rpc.monad.xyzVITE_CONTRACT_ADDRESS=0x597240f8b308dF2313bCA312902A61E64D04663c```其中 VITE_API_BASE_URL 不要添加 /api 后缀，前端代码会自动拼接接口路径。修改线上前端环境变量后必须重新构建部署，因为 Vite 在构建阶段注入 VITE_* 配置。## 用户操作流程1. 用户打开线上前端并连接 MetaMask。2. 钱包切换到 Monad Testnet。3. 用户输入 50 到 200 字的心声。4. 后端调用 DeepSeek，返回情绪、温暖指数和回应。5. 用户点击发布，前端计算 contentHash 和 postId。6. MetaMask 请求用户确认 Monad 交易。7. WhisperTree 在 Monad 上保存内容证明。8. 后端验证交易收据中的 WhisperCreated 事件。9. 其他钱包可以发送支持交易，更新链上支持次数。## 答辩演示重点可以按以下顺序演示：1. 展示 Monad Testnet 合约地址和已验证的合约页面。2. 展示线上前端地址和 Monad Testnet 钱包连接状态。3. 输入一段心声，展示 DeepSeek 动态回复。4. 点击发布，展示 MetaMask 交易确认窗口。5. 打开 Monad Explorer，展示交易哈希、合约调用和确认结果。6. 使用另一个钱包点击支持，展示第二笔链上交易。7. 说明原始文字没有以明文写入链上，链上只保存哈希和支持数据。项目使用 Monad 的理由：- Monad 与 EVM 和 Solidity 工具链兼容，现有 Hardhat、viem 和 MetaMask 可以直接使用。- 较快的区块确认适合发布、支持这类实时互动操作。- 高吞吐能力适合多个用户同时进行支持和链上互动。- 链上交易提供了独立于后端数据库的公开可验证记录。## 常见问题### 页面显示备用回复检查：- 后端 Render 服务是否为 Live。- https://你的后端域名/health 是否返回 {"ok":true}。- 前端的 VITE_API_BASE_URL 是否填写了线上后端地址。- 修改环境变量后是否重新部署了前端。- Render 免费服务是否正在从休眠状态恢复。### 前端构建失败并出现 buildnpm如果 Root Directory 是 frontend，Build Command 必须是：```textnpm run build```不要把多个命令重复粘贴到同一个输入框。### 页面可以打开但无法发布检查：- MetaMask 是否连接到 Monad Testnet。- 钱包是否有测试币 MON。- VITE_CONTRACT_ADDRESS 是否为当前合约地址。- 浏览器是否允许 MetaMask 弹出交易确认窗口。### Render 第一次访问很慢免费实例可能会休眠。第一次访问或第一次调用后端时需要等待一段时间，服务启动后后续请求会恢复正常。## 安全注意事项以下内容绝对不能提交到 GitHub：```textPRIVATE_KEYDEEPSEEK_API_KEYETHERSCAN_API_KEY钱包助记词```项目的 .gitignore 已忽略根目录、前端和后端的 .env 文件。公开仓库中只应保留 .env.example 和不包含密钥的配置说明。