项目架构

1. 背景与本次决策

目标是沉淀可复用的虚拟货币操作解决方案，从 ETH 开始，逐步加入 BTC 等链。现有仓库只有 Python IDE 示例，故延续 Python，采用单仓库、单分发包、链能力模块化布局。 src 仅作为源码目录，直接包含同级 core、eth 包，不再增加项目名命名空间。分发包名称仍为 ituac-crypto-hub，导入使用 from eth import ... / from core import ...。顶层包名较通用，使用项目独立虚拟环境；未来引入 SDK 时检查是否与 eth、core 同名冲突。本次状态：基础骨架已落地；下文节点、钱包和交易能力均为后续方向，不代表已经实现。

备选方案及取舍：

暂不引入 FastAPI / 微服务：尚无 HTTP、认证或部署需求，先让能力能被脚本和未来服务复用。
暂不为每条链建立独立仓库或分发包：降低早期维护成本；需独立发布或出现依赖冲突时再拆分。
不建立统一交易大接口：仅有 ETH 首期需求，提前抽象容易把链特有语义泄漏到公共层。
暂不安装链 SDK：首期只有离线基础能力；节点接入时再按官方维护状态、接口和测试支持选型。

2. 依赖方向

调用方（脚本 / 未来 API / 任务）
        ↓             ↓
       eth        btc（未来）
        ↓             ↓
              core

core 不导入任何币种包；币种包互不导入。当前 eth.units 依赖 core.errors， eth.__init__ 暴露经过测试的金额转换接口。

每条链在真实需求出现时再增长为：

eth/
  units.py              # 已有：原生币单位转换
  models.py             # 未来：本链请求、结果和值对象
  ports.py              # 未来：节点与签名器接口，按能力拆分
  services/             # 未来：查询、交易等用例，不绑定 SDK
  adapters/             # 未来：RPC / SDK / 外部签名器实现

以上未来文件不预建空壳。外部适配器实现端口，调用入口负责组装和注入；用例不直接实例化 SDK。单元测试注入离线替身；集成测试独立配置网络及节点，不在包导入时建立连接。

3. 公共层与链专属层

归属	内容
`core`	当前公共异常；未来有真实复用证据的原语
`eth`	原生 ETH 单位、后续地址 / chain ID / 费用 / 交易与回执语义
未来 `btc`	BTC 自有单位、网络 / 地址 / UTXO / 手续费 / 交易模型
调用应用	身份权限、业务订单、持久化、调度、审计和部署，当前不实现

链与资产分开：原生 ETH 的单位转换不能用于未知精度的代币。 ERC-20 若进入范围，先归于 ETH / EVM 相关能力，不因币种名称拆成重复的链客户端。其他 EVM 链及共享 evm 层只有在需求明确、复用证据充分后再决定。

4. 后续操作的安全契约

节点 URL、目标网络、预期链标识显式配置，并核验节点身份；不得隐式落到主网。
金额边界使用最小单位整数，展示才转换 Decimal；拒绝浮点和静默精度损失。
密钥通过专门签名接口管理，不进入普通配置对象、日志、测试夹具或异常输出；不自行实现密码学。
交易构建、费用估算、签名、广播、回执查询及最终确认分离。返回交易哈希不等于成功。
对外错误需区分输入错误、节点拒绝、传输故障、响应格式错误、执行失败和结果未知。
广播超时不自动重发资金操作；引入写能力前明确幂等、并发、费用上限、重试和链重组策略。
真实转账或合约授权必须另行明确授权；离线测试不构成资金操作许可。

5. 增加 BTC 等链

明确该链首批用例与非目标，验证协议和 SDK 官方资料。
新建 src/btc/，独立维护公共接口和链特有模型，不从 eth 继承。
新建 tests/btc/，验证单位、边界、失败路径；有节点适配器后再提供可选集成测试。
SDK 依赖优先用按链可选依赖声明，防止 ETH 用户被迫安装 BTC 全部依赖。
只有已经出现的共同需求才提取到 core，同时更新此文档和 README。

6. 建议演进顺序（待具体需求确认）

ETH 只读接入：节点身份、区块、原生币余额、交易及回执查询。
ETH 写能力：构建和估算 → 独立签名器 → 显式广播 → 确认跟踪及异常恢复。
按需求扩展代币、事件查询等能力。
BTC 首期只读能力，再按其自身模型补充资金操作。

验收分开记录源码 / 离线测试 / 本地链或测试网 / 真实节点 / 真实资金证据。目前只提供并验证基础库；不声明主网、RPC 或真实交易已验证。

4.8 KiB Raw Blame History Unescape Escape