OSXBasedAnon/alphanumeric

# 字母数字 适用于 macOS/OSX、Linux 和 Windows 的 Rust 区块链节点和命令行钱包客户端。 https://www.alphanumeric.blue/  [](#构建与运行) [](#支持的平台) [](#许可证) `alphanumeric` 是一个 Rust 区块链节点 runtime，集成了节点发现、钱包管理、挖矿、本地链存储、bootstrap 同步和诊断工具。当前的发布版本线为 `7.3.8`。 ## 快速导航 - [系统目标](#system-goals) - [技术架构](#technical-architecture) - [代币经济学](#tokenomics) - [支持的平台](#supported-platforms) - [构建与运行](#build-and-run) - [Bootstrap 与存储](#bootstrap-and-storage) - [通过环境变量进行配置](#configuration-via-environment-variables) - [CLI 界面](#cli-surface) - [安全态势](#security-posture) ## 系统目标 `alphanumeric` 被设计为一个单节点可执行文件，打包了参与实时网络所需的全套操作栈： - 确定性的本地链状态持久化 (`sled`) - 受限的、带帧的 P2P 消息传递与 peer 生命周期管理 - 区块/交易传播与同步工作流 - 集成的挖矿路径 - 钱包/密钥工作流以及操作员 CLI - 本地操作遥测和诊断 ## 非目标 (当前) - 跨所有 commit 的协议稳定性保证 - 经过审计的生产级安全声明 - 严格的长期 API/CLI 兼容性保证 ## 当前状态 - 正在积极开发中。 - 接口和内部实现可能会在不同 commit 之间发生变化。 - 并非经过正式审计的生产系统。 - macOS/OSX 的发布打包支持用于命令行客户端。 ## 支持的平台 该客户端旨在运行于： - macOS/OSX，包括 Apple Silicon 的 release 构建 - Linux - Windows 该仓库可以使用 Rust stable 工具链从源码构建。Release 的 zip 压缩包可能包含一个更面向用户的 `README.md`（来自 `release/README.md`）；本仓库的 README 是项目的技术概述。 ## 功能矩阵 | 功能 | 范围 | | --- | --- | | 节点 runtime | 监听器、peer 连接/断开连接、维护循环 | | P2P 传输 | 长度前缀帧消息传递、受限的 payload | | 同步 | Peer 区块范围请求与摄取 | | 持久化 | 内置 `sled` 存储与本地 bootstrap | | 挖矿 | 本地挖矿管理器与挖矿工作流 | | 钱包操作 | 创建/重命名/列出/历史记录/账户 + 交易创建 | | 运维可见性 | 状态/同步/连接/发现命令 + stats 服务器钩子 | ## 技术架构 高层模块映射： - `src/main.rs`：进程入口点、bootstrap、CLI 循环、网络命令处理 - `src/a9/node.rs`：P2P runtime、帧处理、peer 管理、同步、事件处理 - `src/a9/blockchain.rs`：区块/交易验证与持久化 - `src/a9/mgmt.rs`：钱包管理与密钥工作流 - `src/a9/progpow.rs`：挖矿管理器与挖矿流程 - `src/a9/velocity.rs`：velocity/shred 传播支持 - `src/a9/bpos.rs`：sentinel/validator 相关逻辑 - `src/a9/whisper.rs`：whisper 消息传递支持 Runtime 形态： 1. bootstrap/加载数据库 (`blockchain.db`) 2. 初始化区块链状态 3. 初始化节点 runtime + 监听器 4. 启动后台任务： - peer 维护 - 发现/公告 - 同步 - 可选的 stats 5. 处理交互式命令和网络事件 ``` flowchart LR CLI[CLI / main.rs] --> NODE[Node Runtime / node.rs] NODE --> P2P[P2P Transport] NODE --> SYNC[Sync + Discovery] NODE --> CHAIN[Blockchain / blockchain.rs] CHAIN --> DB[(sled)] CLI --> MGMT[Wallet Mgmt / mgmt.rs] CLI --> MINER[Mining / progpow.rs] ``` ## 网络与协议说明 - 默认节点 TCP 端口：`7177` (`src/a9/node.rs` 中的 `DEFAULT_PORT`) - 出站消息传递使用帧传输（长度前缀 payload） - 强制执行消息大小限制 (`MAX_MESSAGE_SIZE`) - 出站连接池已启用，包含： - 空闲清理 - LRU 风格的驱逐机制 - 针对重复失败的每个 peer 的断路器 - 入站连接处理受并发限制 - DNS/发现 endpoint 可通过环境变量配置 - 主要 peer bootstrap：`ALPHANUMERIC_DISCOVERY_BASE`（默认为 `https://alphanumeric.blue`） - 可选的 DNS 备用 seed：`ALPHANUMERIC_DNS_SEEDS`（逗号分隔的 `host:port`） ## 共识与验证 代码库包含多个与共识/验证相关的组件（PoW/挖矿路径、sentinel/validator 逻辑以及传播优化）。其行为由 `src/a9/*` 中的当前代码路径定义。 交易见证使用紧凑最终性模型： - 实时的 mempool 和新区块准入需要完整的 ML-DSA 签名和发送方公钥 - 已确认的区块存储保留紧凑签名凭证以及 `sig_hash = SHA256(full_signature)` - 历史 P2P 同步验证区块哈希、merkle root、PoW、余额、奖励规则、公钥/地址绑定以及凭证承诺，而无需归档完整的见证 如果您正基于此仓库进行集成，请固定一个 commit 哈希，并在该确切修订版验证其行为。 ## 代币经济学 ### 供应量摘要 (简单) - 没有编码为单一数值的**固定硬上限**。 - 新增发行量**随时间衰减**： - 最大区块奖励每 6 个月下降 **17%**（每个周期 `* 0.83`） - 实际上这创造了**渐近线式的供应行为**： - 总供应量可以继续增加 - 但新增发行量随时间推移逐渐变小 - **从现在起 5 年内（网络已运行约 6 个月）的最大供应量估计：约 6.258 亿 token** ### Runtime 参数 (当前代码) - 费率：`FEE_PERCENTAGE = 0.000563063063` (0.0563063063%) - 奖励范围：`MIN_BLOCK_REWARD = 1.0`, `MAX_BLOCK_REWARD = 50.0` - 奖励网络费用：`NETWORK_FEE = 0.0005` - 费用截断因子：`MINT_CLIP = 0.35` - 目标区块时间：`TARGET_BLOCK_TIME = 5` 秒 - 空区块从当前最大奖励的 20% 开始 - 非空区块奖励随有效费用缩放，并被限制在 `[MIN_BLOCK_REWARD, current_max]` 范围内 实际实现的发行量仍取决于真实的网络活动（区块生产 + 交易费用）。 ## 构建与运行 前置条件： - Rust stable 工具链 - Cargo - macOS/OSX：如果缺少本地编译器工具链，则需要 Xcode Command Line Tools (`xcode-select --install`) 构建： ``` cargo build --release ``` 运行： ``` cargo run --release ``` 直接运行构建好的二进制文件： ``` ./target/release/alphanumeric ``` 为了获得更干净的本地安装，请将二进制文件保留在一个专用文件夹中，并始终从该文件夹运行它，或者显式设置 `ALPHANUMERIC_DB_PATH`。 ## Bootstrap 与存储 启动 bootstrap 源 (默认)： - `https://alphanumeric.blue/bootstrap/blockchain.db.zip` Bootstrap 信任模式： - 节点优先从 `https://alphanumeric.blue/api/bootstrap/manifest` 获取 manifest 进行 bootstrap。 - manifest 在使用前会进行签名验证。 - 如果 manifest 的获取/解析/验证失败，默认情况下启动将直接失败。 - 只有在显式设置 `ALPHANUMERIC_ALLOW_UNVERIFIED_BOOTSTRAP=true` 时，才允许使用静态的、未经验证的备用方案。 Launch-network 守卫： - 只有当区块 `0` 与冻结的创世区块/网络 ID 匹配时，才会重用 `blockchain.db`。 - 如果本地数据库属于不同的网络、创世区块错误或无法读取，启动时会从已签名的 bootstrap 替换它。 - 钱包密钥独立于链状态；保留 `private.key` 可保持钱包身份，但余额始终根据经过验证的 launch-chain 数据库计算。 - 即使本地数据库已经有效，`ALPHANUMERIC_FORCE_BOOTSTRAP=true` 也会强制从已签名的 bootstrap 进行替换。 默认存储行为： - `ALPHANUMERIC_DB_PATH` 控制链数据库路径。 - 如果没有设置 `ALPHANUMERIC_DB_PATH`，则默认相对路径为 `blockchain.db`。 - 相对路径在当前工作目录下解析，除非在可执行文件旁边找到了现有的 launch-network 数据库或过期的数据库并且需要重用/替换它们。 - 对于普通用户，建议使用专用文件夹，例如 `~/Alphanumeric`。 主要的本地产物： - `blockchain.db` - `private.key` - `node_identity.key` - 可选的锁文件 (`*.lock`) ## 通过环境变量进行配置 Runtime 使用的常见变量包括： - `ALPHANUMERIC_BIND_IP` - `ALPHANUMERIC_DB_PATH` - `ALPHANUMERIC_HEADLESS` (`true` 表示在没有交互式命令循环的情况下运行节点服务) - `ALPHANUMERIC_FORCE_BOOTSTRAP` - `ALPHANUMERIC_ALLOW_UNVERIFIED_BOOTSTRAP` - `ALPHANUMERIC_MAX_BOOTSTRAP_ZIP_BYTES` (未验证的备用下载限制；默认 `1073741824`；限制在 1 MiB - 10 GiB 之间) - `ALPHANUMERIC_MAX_UNVERIFIED_BOOTSTRAP_EXTRACT_BYTES` (未验证的备用解压限制；默认 10 GiB) - `ALPHANUMERIC_IGNORE_DB_LOCK` - `ALPHANUMERIC_STATS_ENABLED` - `ALPHANUMERIC_STATS_BIND` (默认为 `127.0.0.1`；仅当 stats API 需要公开时才设置 `0.0.0.0`) - `ALPHANUMERIC_STATS_PORT` - `ALPHANUMERIC_SEED_NODES` 或 `ALPHANUMERIC_BOOTSTRAP_PEERS` (逗号分隔的 `host:port`，在依赖网关回退之前会先尝试这些 peer) - `ALPHANUMERIC_DNS_SEEDS` - `ALPHANUMERIC_DISCOVERY_BASE` - `ALPHANUMERIC_DISCOVERY_BASES` - `ALPHANUMERIC_ALLOW_PRIVATE_PEERS` (默认关闭；仅用于本地/私有测试网络) - `ALPHANUMERIC_DISCOVERY_URL` - `ALPHANUMERIC_ANNOUNCE_URL` - `ALPHANUMERIC_HEADERS_URL` - `ALPHANUMERIC_ANNOUNCE_INTERVAL_SECS` (默认 `300`，最小值 `60`) - `ALPHANUMERIC_ENABLE_HEADER_SNAPSHOTS` (默认关闭；仅在受信任的发布者/validator 节点上启用) - `ALPHANUMERIC_HEADER_SNAPSHOT_INTERVAL_SECS` (默认 `300`，最小值 `60`) - `ALPHANUMERIC_ENABLE_STATS_SNAPSHOTS` (默认关闭；仅在受信任的发布者/validator 节点上启用) - `ALPHANUMERIC_STATS_SNAPSHOT_INTERVAL_SECS` (默认 `300`，最小值 `60`) - `ALPHANUMERIC_ENABLE_BLOCK_RELAY` (默认关闭；HTTP 区块中继发布是备用遥测方案，而非正常的区块同步) - `ALPHANUMERIC_ENABLE_BLOCK_RELAY_SYNC` (默认关闭；选择开启 HTTP 区块中继同步回退) - `ALPHANUMERIC_DISABLE_BLOCK_RELAY_SYNC` (强制完全禁用 HTTP 中继回退) - `ALPHANUMERIC_ENABLE_PERIODIC_BLOCK_RELAY_SYNC` (选择开启后台 HTTP 中继同步；默认关闭) - `ALPHANUMERIC_RELAY_SYNC_INTERVAL_SECS` (可选的定期中继同步间隔；`0` 表示禁用，最小值 `60`) - `ALPHANUMERIC_RELAY_SYNC_BACKFILL_DEPTH` (默认 `0`；可选的中继回填深度，最大值 `256`) - `ALPHANUMERIC_RELAY_SYNC_MAX_ROUNDS` (默认 `4`，最大值 `24`) - `ALPHANUMERIC_PUBLIC_IP` - `ALPHANUMERIC_ENABLE_UPNP` - `ALPHANUMERIC_PEER_CACHE_PATH` - `ALPHANUMERIC_TX_WITNESS_CACHE_SIZE` 只有当 blue 网关返回具有有效签名和 SHA256 的固定发布者 manifest 时，官方 bootstrap 快照才会被接受。新的 manifest 还带有已签名的压缩大小、解压大小和文件计数元数据，以便节点可以预检磁盘空间并验证解压过程，而不会施加固定的链大小上限。 Bootstrap 发布属于维护者基础设施，不属于正常的 macOS 节点设置的一部分。操作员级别的详细信息保留在 [docs/BOOTSTRAP_PUBLISHER.md](docs/BOOTSTRAP_PUBLISHER.md) 中。 ## CLI 界面 交互式命令循环示例： - `create ` - `whisper

` (根据流程可以提供金额) - `balance` - `new [wallet_name]` - `account

` - `history` - `rename ` - `mine ` - `info` - `diagnostics` 进程标志/网络命令： - `--status` 或 `-s` - `--sync` - `--sync --force` - `--connect ` - `--getpeers` - `--discover` ## 安全态势 本项目处理密钥材料和 peer 输入。请谨慎对待。 - `private.key` 属于敏感信息。请确保主机和文件系统权限的安全。 - 不要将密钥材料提交到源代码版本控制中。 - 将所有网络输入视为不受信任的。 - 在类似主网的使用之前，请验证操作假设。 ## 操作清单 可访问节点的最低推荐设置： 1. 在主机防火墙/路由器上开放 TCP 端口 `7177` 2. 在具有持久磁盘的稳定主机上运行节点 3. 监控日志和 peer 数量 4. 安全备份敏感的密钥材料 Windows 防火墙示例： ``` New-NetFirewallRule -Name "Alphanumeric Network" -DisplayName "Alphanumeric Network (Port 7177)" -Protocol TCP -LocalPort 7177 -Direction Inbound,Outbound -Action Allow ``` macOS/OSX 防火墙说明： - 如果 macOS 防火墙提示要求传入连接，如果此机器应接受 peer，请允许 `alphanumeric`。 - 如果 Gatekeeper 阻止了下载的 release 二进制文件，请在 Finder 中右键单击该二进制文件并选择“打开”，或者使用 `xattr -dr com.apple.quarantine ./alphanumeric` 移除隔离属性。 ## 开发工作流 快速本地检查： ``` cargo check ``` 更改协议/runtime 代码时，首选： - 显式的消息帧处理 - 受限的缓冲区和超时机制 - 清晰的锁作用域 - 确定性的错误处理 威胁模型与控制映射： - `docs/THREAT_MODEL.md` ## 前端 - 官方前端：https://www.alphanumeric.blue/ ## 社区 - Discord：https://discord.gg/D3r7TRcj9t ## 许可证 MIT

标签：P2P网络, Rust, 加密货币, 区块链, 可视化界面, 命令行钱包, 挖矿, 网络流量审计, 节点, 通知系统