dapp-builder
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseFreenet Decentralized Application Builder
Freenet 去中心化应用构建指南
Build decentralized applications on Freenet following the architecture patterns established in River (decentralized chat).
遵循River（去中心化聊天应用）确立的架构模式，在Freenet上构建去中心化应用。
How Freenet Applications Work
Freenet 应用的工作原理
Freenet is a platform for building decentralized applications that run without centralized servers. Apps rely on a global, peer-to-peer Key-Value Store where the "Keys" are cryptographic contracts.
Freenet 是一个无需中心化服务器即可运行的去中心化应用构建平台。应用依赖于一个全球分布式的点对点键值存储系统，其中的“键”是加密合约。
Core Concept: The Contract is the Key
核心概念：合约即键
The "Key" for any piece of data is the cryptographic hash of the WebAssembly (WASM) code that controls it.
- This ties the identity of the data to its logic
- If you change the code (logic), the key changes
- This creates a "Trustless" system: You don't need to trust the node storing the data, because the data is self-verifying against the contract code
任何数据的“键”都是控制该数据的WebAssembly（WASM）代码的加密哈希值。
- 这将数据的“身份”与其“逻辑”绑定
- 如果你修改代码（逻辑），键也会随之改变
- 这创建了一个“无需信任”的系统：你无需信任存储数据的节点，因为数据可通过合约代码自我验证
The Three Components of a Freenet App
Freenet 应用的三大组件
1. The Contract (Network Side)
1. 合约（网络端）
- Role: Acts as the "Backend" or Database
- Location: Runs on the public network (untrusted peers)
- Functionality:
- Defines what data (State) is valid
- Defines how that data can be modified
- State: Holds the actual application data (arbitrary bytes)
- Constraint: Cannot hold private keys or secrets - all data is public (unless encrypted by the client)
- 作用： 充当“后端”或数据库
- 运行位置： 公共网络（不可信节点）
- 功能：
- 定义哪些数据（状态）是有效的
- 定义数据的修改方式
- 状态： 存储实际的应用数据（任意字节）
- 约束： 不能存储私钥或机密信息——所有数据都是公开的（除非由客户端加密）
2. The Delegate (Local Side)
2. 委托（本地端）
- Role: Acts as the "Middleware" or private agent
- Location: Runs locally on the user's device (within the Freenet Kernel)
- Functionality:
- Trust Zone: Safely stores secrets, private keys, and user data
- Computation: Performs signing, encryption, and complex logic before sending data to the network
- Background Tasks: Can run continuously to monitor contracts or handle notifications even when the UI is closed
- 作用： 充当“中间件”或私有代理
- 运行位置： 用户设备本地（Freenet Kernel 内部）
- 功能：
- 可信区域： 安全存储机密信息、私钥和用户数据
- 计算处理： 在将数据发送到网络前执行签名、加密和复杂逻辑运算
- 后台任务： 可持续运行以监控合约或处理通知，即使UI已关闭
3. The User Interface (Frontend)
3. 用户界面（前端）
- Role: Interaction layer for the user
- Location: Web Browser (SPA) or native app
- Functionality:
- Connects to the local Freenet Kernel via WebSocket/HTTP
- Built using standard web frameworks (Dioxus, React, Vue, etc.)
- Agnostic to underlying P2P network complexity
- 作用： 用户交互层
- 运行位置： 网页浏览器（SPA）或原生应用
- 功能：
- 通过WebSocket/HTTP连接到本地Freenet Kernel
- 使用标准Web框架构建（Dioxus、React、Vue等）
- 无需关注底层P2P网络的复杂性
Data Synchronization & Consistency
数据同步与一致性
Freenet solves "Eventual Consistency" using a specific mathematical requirement:
Commutative Monoid: The function that merges updates must be a commutative monoid.
- Order Independent: It shouldn't matter what order updates arrive in
- If Peer A merges Update X then Y, and Peer B merges Update Y then X, they must end up with the same result
Efficiency: Peers exchange Summaries (compact representations) and Deltas (patches/diffs) rather than re-downloading full state.
Freenet 通过特定的数学要求解决“最终一致性”问题：
交换幺半群： 合并更新的函数必须是一个交换幺半群。
- 顺序无关：更新到达的顺序不影响结果
- 如果节点A先合并更新X再合并Y，节点B先合并更新Y再合并X，二者最终结果必须一致
效率： 节点之间交换摘要（紧凑表示形式）和增量补丁（Diff），而非重新下载完整状态。
Advanced Capabilities
高级功能
- Subscriptions: Clients can subscribe to contracts and get notified of changes immediately (real-time apps)
- Contract Interoperability: Contracts reading other contracts' state is planned but not yet implemented
- 订阅： 客户端可以订阅合约，实时接收变更通知（适用于实时应用）
- 合约互操作性： 合约读取其他合约状态的功能正在规划中，尚未实现
Development Workflow
开发流程
Follow these phases in order:
按以下阶段依次进行：
Phase 1: Contract Design (Shared State)
阶段1：合约设计（共享状态）
Start by defining what state needs to be shared across all users.
Key questions:
- What data must all users see consistently?
- How should conflicts be resolved when two users update simultaneously?
- What cryptographic verification is needed?
- What are the state components and their relationships?
Implementation steps:
- Define state structure using macro from freenet-scaffold
#[composable] - Implement trait for each component
ComposableState - Implement trait for the contract
ContractInterface - Ensure all state updates satisfy the commutative monoid requirement
Reference:
references/contract-patterns.md首先定义需要在所有用户之间共享的状态。
关键问题：
- 哪些数据必须让所有用户看到一致的结果？
- 当两个用户同时更新时，应如何解决冲突？
- 需要哪些加密验证？
- 状态组件及其关系是什么？
实现步骤：
- 使用freenet-scaffold中的宏定义状态结构
#[composable] - 为每个组件实现trait
ComposableState - 为合约实现trait
ContractInterface - 确保所有状态更新满足交换幺半群的要求
参考文档：
references/contract-patterns.mdPhase 2: Delegate Design (Private State)
阶段2：委托设计（私有状态）
Determine what private data each user needs stored locally.
Key questions:
- What user-specific data needs persistence? (keys, preferences, cached data)
- What signing/encryption operations are needed?
- What permissions are needed for sensitive operations?
Implementation steps:
- Define request/response message types
- Implement trait
DelegateInterface - Handle secret storage operations (Store, Get, Delete, List)
- Implement cryptographic operations (signing, encryption)
Reference:
references/delegate-patterns.md确定每个用户需要本地存储的私有数据。
关键问题：
- 需要持久化哪些用户特定数据？（密钥、偏好设置、缓存数据）
- 需要执行哪些签名/加密操作？
- 敏感操作需要哪些权限？
实现步骤：
- 定义请求/响应消息类型
- 实现trait
DelegateInterface - 处理机密存储操作（存储、获取、删除、列出）
- 实现加密操作（签名、加密）
参考文档：
references/delegate-patterns.mdPhase 3: UI Design
阶段3：UI设计
Build the user interface connecting to contracts and delegates.
Key questions:
- What components/views does the app need?
- How should state synchronization work?
- What's the user flow for key operations?
Implementation steps:
- Set up Dioxus project with WASM target
- Implement WebSocket connection to Freenet gateway
- Create synchronizer for contract state subscriptions
- Implement delegate communication for private storage
- Build reactive UI components
Reference:
references/ui-patterns.md构建连接合约与委托的用户界面。
关键问题：
- 应用需要哪些组件/视图？
- 状态同步应如何工作？
- 关键操作的用户流程是什么？
实现步骤：
- 搭建支持WASM目标的Dioxus项目
- 实现与Freenet网关的WebSocket连接
- 为合约状态订阅创建同步器
- 实现与委托的通信以进行私有存储操作
- 构建响应式UI组件
参考文档：
references/ui-patterns.mdPhase 4: Build and Deploy
阶段4：构建与部署
Set up the build system and deployment pipeline.
Reference:
references/build-system.md设置构建系统和部署流水线。
参考文档：
references/build-system.mdProject Structure Template
项目结构模板
my-dapp/
├── common/ # Shared types between contract/delegate/UI
│ └── src/
│ ├── lib.rs
│ └── state/ # State definitions
├── contracts/
│ └── my-contract/
│ ├── Cargo.toml
│ └── src/lib.rs # ContractInterface implementation
├── delegates/
│ └── my-delegate/
│ ├── Cargo.toml
│ └── src/lib.rs # DelegateInterface implementation
├── ui/
│ ├── Cargo.toml
│ ├── Dioxus.toml
│ └── src/
│ ├── main.rs
│ └── components/
├── Cargo.toml # Workspace root
└── Makefile.toml # cargo-make build tasksmy-dapp/
├── common/ # 合约/委托/UI之间的共享类型
│ └── src/
│ ├── lib.rs
│ └── state/ # 状态定义
├── contracts/
│ └── my-contract/
│ ├── Cargo.toml
│ └── src/lib.rs # ContractInterface实现
├── delegates/
│ └── my-delegate/
│ ├── Cargo.toml
│ └── src/lib.rs # DelegateInterface实现
├── ui/
│ ├── Cargo.toml
│ ├── Dioxus.toml
│ └── src/
│ ├── main.rs
│ └── components/
├── Cargo.toml # 工作区根目录
└── Makefile.toml # cargo-make构建任务Reference Project
参考项目
River demonstrates all patterns:
- Contracts:
contracts/room-contract/ - Delegates:
delegates/chat-delegate/ - UI:
ui/ - Common types:
common/
River 展示了所有模式：
- 合约：
contracts/room-contract/ - 委托：
delegates/chat-delegate/ - UI：
ui/ - 通用类型：
common/
Key Dependencies
核心依赖
toml
undefinedtoml
undefinedFor contracts
用于合约
freenet-stdlib = { version = "0.1", features = ["contract"] }
freenet-scaffold = "0.1"
freenet-stdlib = { version = "0.1", features = ["contract"] }
freenet-scaffold = "0.1"
For delegates
用于委托
freenet-stdlib = { version = "0.1", features = ["delegate"] }
freenet-stdlib = { version = "0.1", features = ["delegate"] }
For UI
用于UI
dioxus = "0.7"
freenet-stdlib = "0.1"
---dioxus = "0.7"
freenet-stdlib = "0.1"
---Improving This Skill
改进本技能
This skill is designed to be self-improving. When encountering issues while using this skill, agents should file GitHub issues or submit PRs to improve it.
本技能设计为可自我改进。使用本技能遇到问题时，Agent应提交GitHub Issue或PR来改进它。
When to File an Issue
何时提交Issue
File an issue at when:
freenet/freenet-agent-skills- Instructions are unclear or ambiguous
- Information is missing for a common use case
- Code examples don't compile or are outdated
- Patterns don't match current River implementation
- A referenced API has changed
当出现以下情况时，在提交Issue：
freenet/freenet-agent-skills- 说明模糊或不明确
- 常见用例缺少相关信息
- 代码示例无法编译或已过时
- 模式与当前River实现不匹配
- 引用的API已变更
How to File an Issue
如何提交Issue
bash
gh issue create --repo freenet/freenet-agent-skills \
--title "dapp-builder: <brief description>" \
--body "## Problem
<describe what was unclear or incorrect>bash
gh issue create --repo freenet/freenet-agent-skills \
--title "dapp-builder: <简要描述>" \
--body "## 问题
<描述不清楚或错误的内容>Context
上下文
<what were you trying to accomplish>
<你当时要完成的任务>
Suggested Improvement
改进建议
<optional: how the skill could be improved>"
undefined<可选：如何改进本技能>"
undefinedSubmitting a PR
提交PR
For concrete improvements:
bash
undefined对于具体的改进：
bash
undefinedClone and create branch
克隆仓库并创建分支
gh repo clone freenet/freenet-agent-skills
cd freenet-agent-skills
git checkout -b improve-<topic>
gh repo clone freenet/freenet-agent-skills
cd freenet-agent-skills
git checkout -b improve-<主题>
Make changes to dapp-builder/SKILL.md or references/*.md
修改dapp-builder/SKILL.md或references/*.md文件
... edit files ...
... 编辑文件 ...
Submit PR
提交PR
git add -A && git commit -m "dapp-builder: <description>"
gh pr create --title "dapp-builder: <description>"
--body "## Changes <describe improvements>
--body "## Changes <describe improvements>
git add -A && git commit -m "dapp-builder: <描述>"
gh pr create --title "dapp-builder: <描述>"
--body "## 变更内容 <描述改进点>
--body "## 变更内容 <描述改进点>
Reason
原因
<why this helps>"
undefined<说明改进的作用>"
undefinedWhat Makes a Good Improvement
优秀改进的标准
- Fixes factual errors or outdated information
- Adds missing patterns discovered while building a dApp
- Clarifies confusing instructions based on real usage
- Adds test examples that would have helped
- Updates code to match current Freenet/River APIs
- 修复事实错误或过时信息
- 添加构建dApp时发现的缺失模式
- 根据实际使用情况澄清模糊的说明
- 添加有帮助的测试示例
- 更新代码以匹配当前Freenet/River API