# 原生币余额检查工具 v0.2

适用场景：运维人员定时检查指定 EVM 地址的原生币余额，并区分 RPC 数据故障。Python 3.10+，仅标准库，无安装依赖。源码采用MIT许可，配置与部署服务报价见SERVICE-OFFER.md。

在本目录运行合成演示（不联网）：

```sh
python3 monitor.py --demo
python3 -m unittest discover -s tests -v
```

真实检查：复制 `config.example.json` 到自己的配置文件，修改公开地址、链ID、最低余额和可接受的区块年龄。最小余额须为十进制字符串，最多18位小数；本原型只支持18位精度的原生币。配置中不填私钥或助记词。将自己的 HTTPS RPC 地址设置在 `MONITOR_RPC_URL` 环境变量，然后运行：

```sh
python3 monitor.py --config config.json --total-timeout 5
```

RPC 地址可能含服务商 API 密钥；程序不输出它或服务商原始错误。不上传配置和环境文件。网络请求会向所配置的服务商公开待查地址和本机IP；只在自己信任的 RPC 上使用。

输出一次 JSON，退出码0表示健康且余额达到阈值；1表示健康数据下余额不足；2表示配置或数据不可用。状态可能是 `ok`、`low_balance`、`wrong_chain`、`stale_rpc`、`rpc_error`、`config_error`。数据错误不会输出零余额或健康结论。最低余额是使用者配置的告警阈值，不能保证一定足够支付下一笔交易 gas。

每次最多4个请求，依次核验链ID、固定区块高度和时间，再按该区块读取余额。CLI默认给整个检查5秒总时限，可用`--total-timeout`调整为1–60秒；超时终止并回收工作进程，输出`rpc_error/total_timeout`，退出码2。直接调用库函数`check()`时，调用方需管理总体时限。HTTP 429与503返回 `rpc_error`，无自动重试。截断或大于1MiB的响应被拒绝。只允许 `eth_chainId`、`eth_blockNumber`、`eth_getBlockByNumber`、`eth_getBalance`；拒绝HTTP重定向。使用整数wei，余额输出字符串。

本模块没有私钥读取、签名、交易、授权、通知、账号注册、后台服务或自动安装机制。它只读取指定配置文件，无钱包项目依赖；演示文件全部为合成数据。未进行真实地址网络查询或生产部署。

限制：单RPC可能谎报链或余额，链ID/时间检查不是密码学验证；没有多源核验、重组最终性保证、ERC20、连续区块推进检查、历史账本、通知去重或服务部署文件。120秒区块年龄仅为示例，应按具体链调整。演示的时间和链ID固定，示例地址不代表客户账户。

35项本地测试通过：12项离线单元测试、19项回环HTTP集成测试、4项新增总时限测试方法（含多个子场景）。覆盖正常POST、协议错误、429/503、重定向、超大及截断响应、慢速响应头/体、累计请求、超时进程回收和CLI退出码。临时服务仅监听127.0.0.1；生产配置使用HTTPS。

`deadline-validation.json`记录v0.2的35项验证结果；`http-validation.json`、`validation.json`保留旧版本历史。`MANIFEST.sha256`用于逐文件核对交付包。

技术依据：[Ethereum JSON-RPC](https://ethereum.org/developers/docs/apis/json-rpc/)、[Python subprocess](https://docs.python.org/3.12/library/subprocess.html#subprocess.run)。下一步验证客户需求并完成首单配置或部署交付。