ituac-crypto-hub

面向 ETH、BTC 等虚拟货币相关操作的模块化 Python 能力库。先建设独立的 eth 包， 其他链随实际需求按同级包扩展。

当前范围

• 已实现：Python 包骨架、公共异常、ETH / Wei 精确单位转换、离线测试。
• 尚未实现：节点 RPC、余额查询、钱包管理、交易签名与广播、ERC-20、BTC。
• 当前无运行时第三方依赖；不是 HTTP 服务，导入及示例均不会连接网络或操作资金。
• 原有 main.py 保留为 IDE 示例，不作为库入口。

快速开始

使用 Python 3.11+，从仓库根目录执行：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -c 'from eth import eth_to_wei; print(eth_to_wei("0.1"))'

首次安装可能需要联网获取构建工具。仅运行离线测试不需要安装依赖：

PYTHONPATH=src python3 -m unittest discover -s tests -t . -v

-t . 让测试以 tests.eth 命名加载，避免覆盖源码中的 eth 包。

from eth import eth_to_wei, wei_to_eth

amount_wei = eth_to_wei("0.1")  # 100000000000000000
amount_eth = wei_to_eth(amount_wei)  # Decimal('0.100000000000000000')

eth_to_wei 接受十进制字符串或 Decimal，wei_to_eth 接受非负整数（不接受 bool）。 非法输入、负数及不足一个 Wei 的非零精度会抛出 InvalidAmountError，不会静默舍入。 转换只表示金额，不验证余额或交易协议的数值上限，也不用于推断代币精度。

目录

AGENT.md                    # 兼容入口，指向唯一规则正文
AGENTS.md                   # 项目协作与安全规则
docs/architecture.md        # 分层、扩展方式和演进计划
pyproject.toml              # Python 包元数据及构建配置
src/
  core/                     # 公共原语（目前为异常）
  eth/                      # ETH 专属能力（目前为单位转换）
tests/
  __init__.py               # 将测试放在 tests 命名空间
  eth/                      # ETH 离线行为测试

新增链与后续能力的边界见 架构文档。 ETH 单位依据：Ethereum 官方 Ether 技术说明。