Paypunk 项目

这是实验性软件，请勿用于真实资金

## 目标 隐私正面临威胁。人们用来进行私密交易的工具是碎片化的，难以集成，并被锁在围墙花园内。每种隐私币都有自己的钱包、自己的架构、自己的签名模型——它们彼此之间互不相通。 Paypunk 正在朝着一个不同的未来迈进：**一个钱包框架，涵盖所有隐私协议，完全可扩展。** 想象一个这样的钱包： - 你的 **Zcash, Monero, Ethereum, Railgun, Bitcoin** 并存于其中，通过单一界面进行管理 - 相同的后端支持 **终端 UI、桌面应用、移动应用和 agent SDK** —— 因为架构从一开始就是前端无关的 - 你的密钥永远不会触碰联网设备 —— 得益于架构设计，**通过二维码进行气隙签名** 是一等公民流程 - **Agent** 可以通过可脚本化的 CLI 和 IPC API 代替你进行交易，敏感操作需经人工批准 - ZEC 和 ETH 之间的 **兑换** 在钱包内进行，通过去中心化协议路由，且无需放弃资产控制权 - 在服务器上托管你的钱包，在手机上进行批准 - 新的隐私协议 —— **Aleo, Aztec, Railgun** —— 只需实现几个 trait 即可接入，而无需 fork 该钱包 - 随着新的去中心化跨链兑换机制出现，它们会被逐步集成（例如 near-intents / thorchain 等） 该架构是可用的。Trait 系统运行正常。Zcash 和 Ethereum 已被证明可行。基础是坚实的。目前所欠缺的是加强它、打磨它，并将其扩展到更多重要协议的工作。 ## 什么是 Paypunk？ Paypunk 最初是作为 Zcash Hackathon 的参赛作品而诞生的——这是一个构建我多年来一直想做的隐私钱包的机会。但目标从来不仅仅是一个钱包。它是一个 **用于构建隐私保护加密货币钱包的可扩展框架**，其设计使得添加新链（Monero、Bitcoin 及其他）比从零开始要轻松得多。 两个架构决策决定了其他一切： - **签名/钱包分离** —— 密钥存在于独立的进程（`keypunkd`）或完全气隙的设备（移动签名应用）中。钱包 daemon 从不持有密钥材料。这使得离线签名、硬件钱包和多重签名流程成为自然的扩展，而非生硬添加的功能。 - **设计上的多 token** —— 特定于链的逻辑被隔离在 `Protocol` 和 `SignerProtocol` trait 之后。Zcash 和 Ethereum 是前两个实现；添加新链只需实现这些 trait，而无需重构钱包。 IPC 层（Unix socket + tactix actor）意味着前端可以使用任何技术构建——当前的 TUI 只是一次性的初稿。相同的后端既服务于用于脚本化的 CLI，也服务于用于交互的 TUI、用于基于二维码签名的 Web 桥接，以及未来的桌面/移动应用。传输层被设计为可替换的——`UnixSocketTransport` 将所有 I/O 封装在带帧的读/写接口之后，因此可以添加 TCP 或 TLS 传输层以用于远程/Web部署，而无需更改 actor 代码。敏感 payload（密码、助记词）在通过 IPC 发送之前，会使用 X25519 + AES-256-GCM 在应用层进行端到端加密，并且每条消息都使用源自 X25519 密钥交换的每消息 Blake2b MAC 进行身份验证。 不要将其视为“一个带有 TUI 和离线签名器的 Zcash 钱包”，而应视为一个 **可脚本化、隐私优先的钱包框架**，随时准备扩展到任何接下来出现的重要协议。 ## 架构 分层、多进程设计： - **`types`** —— 链无关的领域类型（`Address`, `Amount`, `Balance`, `Transfer`, `Intent`, `Protocol`/`SignerProtocol` trait 等）。无链特定逻辑。 - **`config`** —— 基于 TOML 的配置，支持环境变量覆盖（socket 路径、数据目录、RPC endpoint、网络选择）。 - **`api`** —— 链无关的库。通过 `ProtocolId` (Zcash, Ethereum) 分发到相应的链后端。对使用者隐藏 IPC 和 actor 细节。 - **`paypunkd`** —— 应用 daemon（库 crate，通过 `paypunk paypunkd` 启动）。托管 `Paypunkd` actor、用例、服务编排、链后端注入。 - **`keypunkd`** —— 密钥 daemon（库 crate，通过 `paypunk keypunkd` 启动）。托管 `Keypunkd` actor。种子生成、签名、证明。设计为以单独的系统用户身份运行（属于部署关注点，非代码强制执行）。 - **`ipc`** —— 用于进程间通信的 Tactix actor 发送器。传输无关的组帧（目前为 Unix socket；TCP/TLS 可替换）。每消息 X25519 + Blake2b MAC 身份验证。敏感 payload 在应用层加密（X25519 + AES-256-GCM）。承载不透明的字节 payload；序列化由调用者完成。 - **`protocols/{zcash,ethereum}`** —— 对来自 `paypunk-types` 的 `Protocol` 和 `SignerProtocol` trait 的链特定实现。 - **`cli`** —— 命令行界面二进制文件（`paypunk`）。使用 `api` 进行脚本编写和自动化。同时也启动 daemon 和 TUI。 - **`tui`** —— 基于终端的交互式 UI（ratatui）。由 CLI 使用的库 crate，也可作为独立二进制文件构建。 - **`bridge`** —— 本地 IPC 客户端与浏览器之间的 WebSocket/HTTP 中继，用于气隙的基于 QR 的签名。 - **`signer`** —— 用于离线气隙签名的 Tauri v2 移动应用（独立构建，不包含在 workspace 中）。 - **`ping`/`pong`** —— 用于诊断的 IPC 往返测试对。 ### 进程模型 具有严格安全边界的三个进程： - **paypunk** —— CLI/TUI 二进制文件。通过 `api` 库连接到 paypunkd。从不直接触碰密钥材料。 - **paypunkd`** —— 管理地址、链同步、余额跟踪和转账构建。将签名委托给 keypunkd。从不持有密钥材料。 - **keypunkd** —— 在受保护的内存中持有已解密的密钥。接受来自任何完成 X25519 IPC 握手的进程的签名/证明请求，从不暴露原始密钥材料。 ## 隐私 - 支持 Zcash Orchard shielded pool 和 Ethereum - 静态种子使用 Argon2id 派生密钥 (AES-256-GCM) 进行加密 - 钱包状态数据库目前为纯文本（`paypunkd.db`）；计划支持静态加密 ## 安装 ### 从 GitHub 安装 ``` cargo install --locked --git https://github.com/blockhackersio/paypunk ``` ### 从源码安装 ``` git clone https://github.com/blockhackersio/paypunk.git cd paypunk cargo install --locked --path cli ``` `paypunk` 二进制文件将安装到 `~/.cargo/bin/paypunk`。 ## 入门指南 当不带任何子命令运行时，`paypunk` 二进制文件会自动启动两个 daemon 和 TUI。也可以使用单独的子命令： ``` paypunk # auto-launch keypunkd + paypunkd + TUI paypunk keypunkd # launch key daemon only paypunk paypunkd # launch app daemon only paypunk tui # launch TUI only (daemons must be running) paypunk generate-seed -p # CLI: generate a new wallet paypunk get-balance --protocol zcash # CLI: check balance ``` ### 运行 TUI 最简单的方法——自动启动两个 daemon 并打开 TUI： ``` paypunk ``` 针对已经在运行的 daemon 运行 TUI（例如单独启动的 daemon 或在另一台机器上的 daemon）： ``` paypunk tui ``` TUI 也可以连接到离线签名器，而不是本地的 keypunkd： ``` paypunk tui --signer ``` TUI 内的快捷键： | 键 | 操作 | |-----|--------| | `?` | 帮助浮层（上下文相关） | | `Enter` | 选择 / 确认 | | `Esc` | 返回 / 取消 | | `q` | 退出 | | `s` | 发送 | | `o` | 接收 | | `a` | 添加账户 | | `r` | 刷新 | | `c` | 复制到剪贴板 | ### 网络 Paypunk 支持 Zcash 的 `regtest`、`testnet` 和 `mainnet`。网络通过 `--zcash-network` 标志或 `PAYPUNK_ZCASH_NETWORK` 环境变量进行选择。每个网络使用其自己的数据目录和默认的 lightwalletd endpoint： | 网络 | Lightwalletd 默认值 | 数据目录 | |---------|---------------------|-----------------| | `regtest` | `http://127.0.0.1:9067` (本地) | `~/.local/share/paypunk/regtest/` | | `testnet` | `https://testnet.zec.rocks:443` | `~/.local/share/paypunk/testnet/` | | `mainnet` | `https://zec.rocks:443` | `~/.local/share/paypunk/mainnet/` | #### Regtest（本地开发） 需要在端口 9067 上运行本地的 `zcashd` + `lightwalletd`。有关基于 Docker 的 regtest 设置，请参阅 [`support/zcash/README.md`](support/zcash/README.md)。 ``` # 启动 regtest stack cd support/zcash && make up # 针对 regtest 运行 paypunk（默认） paypunk --zcash-network regtest # 或者通过 env var PAYPUNK_ZCASH_NETWORK=regtest paypunk ``` 要在 regtest 中为你的钱包注入资金，请挖掘区块并将 coinbase 屏蔽至你钱包的地址： ``` cd support/zcash make fund UA= ``` #### 主网 默认连接到公共的 lightwalletd endpoint。为了更好的隐私或可靠性，请使用自定义 endpoint： ``` # 使用默认的 public endpoint (https://zec.rocks:443) paypunk --zcash-network mainnet # 使用自定义的 lightwalletd paypunk --zcash-network mainnet --lightwalletd-host https://my-lwd.example.com:443 # 或者通过 env vars PAYPUNK_ZCASH_NETWORK=mainnet PAYPUNK_LIGHTWALLETD_HOST=https://my-lwd.example.com:443 paypunk ``` #### 以太坊 Ethereum 使用 RPC URL（基于 HTTP 的 JSON-RPC）。默认指向本地节点（`http://127.0.0.1:8545`）；针对主网或测试网覆盖此设置： ``` # 本地 anvil/hardhat 节点（参见 support/ethereum/README.md） paypunk --ethereum-rpc-url http://127.0.0.1:8545 # Mainnet（通过您自己的节点或 provider） PAYPUNK_ETHEREUM_RPC_URL=https://mainnet.infura.io/v3/ paypunk # Sepolia testnet PAYPUNK_ETHEREUM_RPC_URL=https://sepolia.infura.io/v3/ paypunk ``` #### 配置文件 所有默认值都可以在 `~/.config/paypunk/config.toml` 中被覆盖。使用以下命令生成模板： ``` paypunk # creates the config file on first run if it doesn't exist ``` 有关所有可用字段和环境变量覆盖，请参见 [`config/src/lib.rs`](config/src/lib.rs)。 ### 离线签名器 Paypunk 支持通过两种机制进行气隙签名：**QR 桥接**（桌面到移动设备）和 **Tauri 移动应用**。 #### QR 桥接（桌面） 在离线签名器模式下，paypunk 会生成一个 WebSocket/HTTP 桥接而不是 keypunkd。该桥接通过二维码将签名请求中继到浏览器（或移动签名应用），将密钥材料保留在气隙设备上。 ``` # 以 signer 模式运行 TUI — 生成 bridge + paypunkd，然后启动 TUI paypunk --signer # 或者通过 env var / config PAYPUNK_OFFLINE_SIGNER=true paypunk # 或者在 config.toml 中设置： # offline_signer = true ``` 手动运行桥接（例如在单独的机器上）： ``` # 在自定义端口和 socket 上启动 bridge paypunk bridge --port 12345 --socket-path /tmp/keypunkd.sock # 然后启动 paypunkd 并指向 bridge socket paypunk paypunkd --keypunkd-socket /tmp/keypunkd.sock # 然后启动 TUI paypunk tui --signer ``` 桥接在 `http://0.0.0.0:12345/` 提供 HTML 页面，并在 `ws://0.0.0.0:12345/ws` 提供 WebSocket endpoint。在签名设备上的浏览器中打开该页面以扫描/显示二维码。 #### 移动签名应用 (Tauri v2) `signer/` 目录包含一个适用于 Android 的 Tauri v2 移动应用，用于在手机上处理基于二维码的签名。它封装了与 keypunkd 相同的 `Keypunk` 签名逻辑，但完全在设备上运行——密钥永远不会离开手机。 构建和安装说明请参见 [`signer/README.md`](signer/README.md)。 **签名流程：** 1. 钱包（桌面）构建交易并将其编码为二维码 2. 用户使用签名应用（或桥接 Web 页面）扫描二维码 3. 签名应用预览交易（接收者、金额、费用） 4. 用户批准——签名器使用设备上的种子进行签名 5. 已签名的产物显示为二维码 6. 用户将结果扫描回钱包，钱包将其广播 ## 路线图 1. **基于签名器密码熵的数据库加密** —— 使用从签名器密码派生的密钥材料对静态的 `paypunkd.db` 进行加密，并与种子加密进行单独的隔离 2. **Tauri 桌面 UI** —— 使用相同的 IPC 后端，用一个正式的桌面应用程序替换一次性的 TUI 3. **Tauri 移动 UI** —— 完整的移动钱包体验（签名器应用是第一步；随后是完整的移动钱包） 4. **Transparent / Sapling 地址** —— 将 Zcash 支持扩展到 Orchard 之外，包括 Sapling 和 transparent pool 5. **Zcash / Ethereum 强化** —— 生产级的错误处理、边缘情况、重放保护，以及现有链的测试覆盖率 6. **跨链资产兑换** —— 使用 `Intent` enum 模式在资产之间（例如 ZEC ↔ ETH）进行近意图级别的兑换 7. **ZSA** —— 支持 Zcash Shielded Assets 8. **进一步的隐私 token 集成** —— Monero、Railgun、Aleo、Aztec token 以及其他隐私保护协议

标签：Python安全, Rust, 加密货币钱包, 区块链, 去中心化金融, 可视化界面, 空气隔离签名, 网络流量审计, 通知系统, 隐私币