60 lines
2.2 KiB
Markdown
60 lines
2.2 KiB
Markdown
# 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)。
|