JordanNewell/crypto-key-classifier

# crypto-key-classifier (`classify-key` / `ckc`) 对任何看似合理的加密密钥字符串进行分类 —— 包括 BTC / ETH / SOL / Cosmos 系列及其他十余条链，外加 BIP-39 和 Electrum 助记词 —— 并能针对格式噪声、错误校验和、错误编码及 OCR 损坏进行强力恢复。推荐兼容的钱包，并为共享密钥系列（Cosmos IBC、EVM L2、BTC 分叉、Polkadot SS58）枚举跨链重新编码。 **状态：** v0.6.1-pypi，已发布。包含 239 个测试、17 个验证器覆盖约 50 条链，以及 hypothesis 模糊测试套件。 ## 为什么需要它 如果您曾盯着像 `0x7c13fff2d7e8...` 或 `bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh` 这样的字符串，心想*“这是一个地址还是私钥？属于哪条链？校验和有效吗？”* —— 这个工具就能快速地在本地为您解答，且不会将密钥泄露给任何查询服务。 专为恢复 / 取证 / 工单分流场景而构建：有人递给您一串字符，您需要 (a) 搞清楚它是什么，(b) 告诉他们哪些钱包可以接受它，以及 (c) 在他们可能拥有的其他相关链上进行交叉核对。 ## 安装 ``` pip install crypto-key-classifier classify-key --help ``` 要求 Python ≥ 3.10。依赖项：`base58`、`pycryptodome`。 ### 开发者安装 如需修改源代码： ``` git clone https://github.com/JordanNewell/crypto-key-classifier.git cd crypto-key-classifier pip install -e ".[dev]" # adds pytest, hypothesis, ruff, pyright ``` ## 运行效果

## 用法 ``` # 分类单个密钥 — 丰富的多行输出（单个输入的默认行为） classify-key 0x7c13fff2d7e8b1f7b8e1d8a1f3c5b8a1f3c5b8a1 # 批量处理 — 每个密钥一行（2+ 个输入的默认行为） classify-key addr1.txt addr2.txt classify-key --file keys.txt cat keys.txt | classify-key # 用于脚本化的 JSON — 通过管道传递给 jq classify-key --json addr.txt | jq '.[] | .best_guess' # 缩小到特定 chains classify-key --chains btc,eth,sol # 过滤低置信度匹配 classify-key --min-confidence 80 # 显示修复 trace（即哪些 mutations 恢复了损坏的输入） classify-key --explain # 打印完整私钥（DANGEROUS — 请阅读 Safety 章节） classify-key --no-mask ``` ## 验证器覆盖范围（17 个验证器，约 50 条链） | 验证器 | 链 | 显著特性 | |---|---|---| | `btc` | BTC、LTC、DOGE | WIF 私钥 + 通过前缀字节识别的 legacy/segwit/bech32 地址 | | `evm` | ETH + Polygon、Arbitrum、Base、Optimism、BSC、Avalanche、Gnosis、Linea、Scroll、Zora | EIP-55 校验和，同一把密钥 → 11 个跨链地址 | | `sol` | Solana | base58 编码的 ed25519 公钥（32 字节）或私钥（64 字节） | | `cosmos` | ATOM、OSMO、JUNO、AKT、INJ、EVMOS、STRD、REGEN、XPRT、SCRT、KAVA、CRO、LUNA、BAND、UMEE、STARS、DVPN、LIKE、AXL、CRE | **核心特性：** 一次解码 → 20 个跨链 HRP 重新编码 | | `cardano` | ADA | bech32 `addr1` / `stake1` / `addr_test1` | | `polkadot` | DOT、KSM | 使用 Blake2b-512 + SS58PRE 域分隔符的 SS58 | | `ripple` | XRP | 自定义 base58 字母表，`0x00` 前缀 | | `stellar` | XLM | base32 + CRC16-XMODEM（G 账户 / S 密钥） | | `tron` | TRX | base58check，`0x41` 前缀 | | `algorand` | ALGO | base32 + SHA512/256 校验和 | | `tezos` | XTZ | base58check，4 种前缀类型（Ed25519 / secp256k1 / P-256 / BLS12-381） | | `ton` | TON | base64 + CRC16-XMODEM，可弹回 / 不可弹回 | | `monero` | XMR | 区块编码的 base58 + Keccak-256，95 字符主网 | | `sui_aptos` | Sui、Aptos | `0x` + 64 位十六进制（结构上存在歧义 —— 已标记） | | `near` | NEAR | 隐式 64 位十六进制 ed25519 + 命名账户 | | `kaspa` | KAS | bech32 `kaspa` / `kaspatest` HRP | | `mnemonic` | BIP-39（12/15/18/21/24 个单词），Electrum（12/13 个单词） | 针对 OCR 错误 / 拼写错误的 Levenshtein 单词修复 | ## Cosmos HRP 替换（本工具存在的原因） 每条 Cosmos SDK 链底层都使用相同的 Ed25519 私钥。只需解码一次 bech32，再使用不同的人类可读前缀（HRP）重新编码，您就能获得该系列中每条链上的有效地址： ``` $ classify-key cosmos1... --json | jq '.[0].cross_chain_alternates | length' 20 ``` 二十条链，一把密钥。如果您曾恢复过 ATOM 钱包，并疑惑*“我是不是也拥有对应地址上的 OSMO/JUNO/AKT？”* —— 是的，您拥有。本工具会将它们全部枚举出来。 相同的模式也适用于 EVM（一个地址生成 11 条 L2）和 BTC 分叉（一个 WIF 生成 LTC/DOGE）。 ## 恢复流水线 每个输入都会经历三个阶段： 1. **预处理 (Preprocess)** —— 去除空格，规范化易混淆字符（`O`→`0`、`l`→`1`），处理大小写转换，移除不可见字符，处理复制粘贴产生的伪影。 2. **验证 (Validate)** —— 针对 17 个验证器中的每一个，进行形态匹配（长度/字符集）→ 严格验证（校验和、前缀、结构）。在首次匹配到 `checksum_status: valid` 时即短路返回。 3. **修复 (Repair)**（可选）—— 如果没有完全匹配的结果，则生成强力候选：OCR 替换、编码变体（十六进制↔base58↔base64）、针对助记词的 Levenshtein 单词修复。设有上限以控制运行时间。 `classify-key --explain ` 会显示修复轨迹，以便您查看*哪里出错了*以及*什么修复方案使其恢复*。 ## 安全性 - 私钥**默认掩码** —— WIF / 助记词 / 私钥在打印时将显示为 `bc1q…wlh (已掩码 8 个字符)`，除非您传入 `--no-mask`。避免意外将密钥泄露到您的终端滚动历史中。 - **零网络调用** —— 纯本地运行，无遥测，无任何密钥材料离开该进程。 - `tests/fixtures/` 中**仅包含公开的测试向量** —— 代码库中不存在真实的主网密钥。 - 在任何输出之前，`--no-mask` 会向 stderr 打印一条警告。请勿将 `--no-mask` 的输出通过管道传递给日志、云存储或 LLM prompt。 ## 开发 ``` pip install -e ".[dev]" # 运行全套测试（239 个测试） pytest # 通过 hypothesis 进行属性测试 pytest tests/fuzz # Lint + typecheck ruff check . pyright ``` 验证器通过 `src/ckc/validators/__init__.py` 自动发现 —— 只需放入一个新的 `foo.py` 文件，其中包含暴露 `chain`、`formats`、`shape_match` 和 `validate` 的 `Validator` 子类，它就会在下次运行时加入流水线。 ## 更新日志 请参阅 [`CHANGELOG.md`](CHANGELOG.md) 了解 `v0.1.0-mvp` → `v0.6.1-pypi` 的发布版本。 ## 许可证 [MIT](LICENSE) © Jordan Newell

标签：Python, 加密货币, 区块链, 安全规则引擎, 密钥识别, 数据恢复, 无后门, 逆向工具