# ituac-crypto-hub

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

## 当前范围

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

## 快速开始

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

```sh
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"))'
```

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

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

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

```python
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`，不会静默舍入。
转换只表示金额，不验证余额或交易协议的数值上限，也不用于推断代币精度。

## 目录

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

新增链与后续能力的边界见 [架构文档](docs/architecture.md)。
ETH 单位依据：[Ethereum 官方 Ether 技术说明](https://ethereum.org/developers/docs/intro-to-ether)。