dapp-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Freenet 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
```
#[composable]
```
macro from freenet-scaffold
Implement
```
ComposableState
```
trait for each component
Implement
```
ContractInterface
```
trait for the contract
Ensure all state updates satisfy the commutative monoid requirement

Reference:

references/contract-patterns.md

首先定义需要在所有用户之间共享的状态。

关键问题：

哪些数据必须让所有用户看到一致的结果？
当两个用户同时更新时，应如何解决冲突？
需要哪些加密验证？
状态组件及其关系是什么？

实现步骤：

使用freenet-scaffold中的
```
#[composable]
```
宏定义状态结构
为每个组件实现
```
ComposableState
```
trait
为合约实现
```
ContractInterface
```
trait
确保所有状态更新满足交换幺半群的要求

参考文档：

references/contract-patterns.md

Phase 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
```
DelegateInterface
```
trait
Handle secret storage operations (Store, Get, Delete, List)
Implement cryptographic operations (signing, encryption)

Reference:

references/delegate-patterns.md

确定每个用户需要本地存储的私有数据。

关键问题：

需要持久化哪些用户特定数据？（密钥、偏好设置、缓存数据）
需要执行哪些签名/加密操作？
敏感操作需要哪些权限？

实现步骤：

定义请求/响应消息类型
实现
```
DelegateInterface
```
trait
处理机密存储操作（存储、获取、删除、列出）
实现加密操作（签名、加密）

参考文档：

references/delegate-patterns.md

Phase 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.md

Phase 4: Build and Deploy

阶段4：构建与部署

Set up the build system and deployment pipeline.

Reference:

references/build-system.md

设置构建系统和部署流水线。

参考文档：

references/build-system.md

Project 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 tasks

my-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

undefined

toml

undefined

For contracts

用于合约

freenet-stdlib = { version = "0.1", features = ["contract"] } freenet-scaffold = "0.1"

For delegates

用于委托

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

freenet/freenet-agent-skills

when:

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

当出现以下情况时，在

freenet/freenet-agent-skills

提交Issue：

说明模糊或不明确
常见用例缺少相关信息
代码示例无法编译或已过时
模式与当前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

上下文

<你当时要完成的任务>

Suggested Improvement

改进建议

<optional: how the skill could be improved>"

undefined

<可选：如何改进本技能>"

undefined

Submitting a PR

提交PR

For concrete improvements:

bash

undefined

对于具体的改进：

bash

undefined

Clone 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>

git add -A && git commit -m "dapp-builder: <描述>" gh pr create --title "dapp-builder: <描述>"
--body "## 变更内容 <描述改进点>

Reason

原因

<why this helps>"

undefined

<说明改进的作用>"

undefined

What 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