eth-keys

以太坊密钥操作的通用API

这个库和存储库之前位于 https://github.com/pipermerriam/ethereum-keys。它于2017年11月转移到了以太坊基金会GitHub，并重命名为 eth-keys。PyPi包也由 ethereum-keys 更名为 eth-keys。

在下文文档中了解更多。 查看变更日志。

快速入门

python -m pip install eth-keys

>>> from eth_keys import keys
>>> pk = keys.PrivateKey(b'\x01' * 32)
>>> signature = pk.sign_msg(b'a message')
>>> pk
'0x0101010101010101010101010101010101010101010101010101010101010101'
>>> pk.public_key
'0x1b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f70beaf8f588b541507fed6a642c5ab42dfdf8120a7f639de5122d47a69a8e8d1'
>>> signature
'0xccda990dba7864b79dc49158fea269338a1cf5747bc4c4bf1b96823e31a0997e7d1e65c06c5bf128b7109e1b4b9ba8d1305dc33f32f624695b2fa8e02c12c1e000'
>>> pk.public_key.to_checksum_address()
'0x1a642f0E3c3aF545E7AcBD38b07251B3990914F1'
>>> signature.verify_msg(b'a message', pk.public_key)
True
>>> signature.recover_public_key_from_msg(b'a message') == pk.public_key
True

文档

KeyAPI(backend=None)

KeyAPI 对象是与 eth-keys 库交互的主要API。该对象在其构造函数中接受一个单选可选参数，指定将用于椭圆曲线密码学操作的哪个后端。内置后端包括：

• eth_keys.backends.NativeECCBackend：ECC操作的纯Python实现。
• eth_keys.backends.CoinCurveECCBackend：使用 coincurve 库进行ECC操作。

默认情况下，eth-keys 将尝试使用 CoinCurveECCBackend，如果 coincurve 库不可用，则回退到 NativeECCBackend。

注意：coincurve 库不是与 eth-keys 自动安装的，必须单独安装。

backend 参数可以以下任何一种形式给出。

• 后端类的实例
• 后端类
• 包含后端类的点分隔导入路径的字符串。

>>> from eth_keys import KeyAPI
>>> from eth_keys.backends import NativeECCBackend
# These are all the same
>>> keys = KeyAPI(NativeECCBackend)
>>> keys = KeyAPI(NativeECCBackend())
>>> keys = KeyAPI('eth_keys.backends.NativeECCBackend')
# Or for the coincurve base backend
>>> keys = KeyAPI('eth_keys.backends.CoinCurveECCBackend')

后端还可以使用环境变量 ECC_BACKEND_CLASS 进行配置，该变量应设置为要使用的后端点的Python导入路径。

>>> import os
>>> os.environ['ECC_BACKEND_CLASS'] = 'eth_keys.backends.CoinCurveECCBackend'

KeyAPI.ecdsa_sign(message_hash, private_key) -> Signature

此方法返回给定 message_hash 的签名，并由提供的 private_key 签名。

• message_hash：必须是长度为32的字节串
• private_key：必须是 PrivateKey 的实例

KeyAPI.ecdsa_verify(message_hash, signature, public_key) -> bool

根据提供的 signature 是否为给定 message_hash 和 public_key 的有效签名，返回 True 或 False。

• message_hash：必须是长度为32的字节串
• signature：必须是 Signature 的实例
• public_key：必须是 PublicKey 的实例

KeyAPI.ecdsa_recover(message_hash, signature) -> PublicKey

返回从给定的 signature 和 message_hash 恢复的 PublicKey 实例。

• message_hash：必须是长度为32的字节串
• signature：必须是 Signature 的实例

KeyAPI.private_key_to_public_key(private_key) -> PublicKey

返回从给定的 private_key 实例计算出的 PublicKey 实例。

• private_key：必须是 PublicKey 的实例

Public Key、Private Key 和 Signature 的常见 API

以下对象具有共同的API。

• Public Key
• Private Key
• Signature

这些对象都有以下API。

• obj.to_bytes()：返回对象的规范 bytes 序列化。
• obj.to_hex()：返回十六进制编码的规范表示的文本字符串。

KeyAPI.PublicKey(public_key_bytes)

PublicKey 类接受一个参数，该参数必须是一个长度为64的字节串。

请注意，还有两种公共密钥的常见格式：以 \x04 为首的65字节和以 \x02 或 \x03 开头的33字节。要使用前者与 PublicKey 对象一起使用，请删除第一个字节。对于后者，请参阅 PublicKey.from_compressed_bytes。

以下方法可用

PublicKey.from_compressed_bytes(compressed_bytes) -> PublicKey

此 classmethod 返回一个新的 PublicKey 实例，该实例从其压缩表示形式计算得出。

• compressed_bytes 必须是一个以 \x02 或 \x03 开头的长度为33的字节串。

PublicKey.from_private(private_key) -> PublicKey

此 classmethod 返回一个新的 PublicKey 实例，该实例从给定的 private_key 计算得出。

• private_key 可以是长度为32的字节串或 KeyAPI.PrivateKey 类的实例。

PublicKey.recover_from_msg(message, signature) -> PublicKey

此 classmethod 方法返回一个由提供的 message 和 signature 计算出的新的 PublicKey 实例。

• message 必须是一个字节字符串
• signature 必须是 KeyAPI.Signature 的一个实例

PublicKey.recover_from_msg_hash(message_hash, signature) -> PublicKey

与 PublicKey.recover_from_msg 相同，只不过 message_hash 应该是 message 的 Keccak 哈希。

PublicKey.verify_msg(message, signature) -> bool

此方法根据签名是否为给定消息的有效签名返回 True 或 False。

PublicKey.verify_msg_hash(message_hash, signature) -> bool

与 PublicKey.verify_msg 相同，只不过 message_hash 应该是 message 的 Keccak 哈希。

PublicKey.to_compressed_bytes() -> bytes

返回此公钥的压缩表示形式。

PublicKey.to_address() -> text

返回此公钥的十六进制编码的以太坊地址。

PublicKey.to_checksum_address() -> text

返回此公钥的 ERC55 校验和格式的以太坊地址。

PublicKey.to_canonical_address() -> bytes

返回此公钥的以太坊地址的 20 字节表示形式。

KeyAPI.PrivateKey(private_key_bytes)

PrivateKey 类接受一个参数，它必须是一个长度为 32 的字节字符串。

以下方法和支持属性可用：

PrivateKey.public_key

此 属性 包含与该私钥对应的 PublicKey 实例。

PrivateKey.sign_msg(message) -> Signature

此方法返回一个签名，该签名以 Signature 实例的形式表示给定的 message。

• message 必须是一个字节字符串。

PrivateKey.sign_msg_hash(message_hash) -> Signature

与 PrivateKey.sign 相同，只不过 message_hash 应该是 message 的 Keccak 哈希。

KeyAPI.Signature(signature_bytes=None, vrs=None)

Signature 类可以通过两种方式之一进行实例化。

• signature_bytes：长度为 65 的字节字符串。
• vrs：由整数 v、r 和 s 组成的三元组。

注意：如果使用 signature_bytes 实例化，则字节字符串应编码为 r_bytes | s_bytes | v_bytes，其中 | 代表连接。 r_bytes 和 s_bytes 应为 32 字节长度。v_bytes 应为单个字节 \x00 或 \x01。

签名期望使用 1 或 0 作为它们的 v 值。

以下方法和支持属性可用：

Signature.v

此属性返回签名的 v 值作为整数。

Signature.r

此属性返回签名的 r 值作为整数。

Signature.s

此属性返回签名的 s 值作为整数。

Signature.vrs

此属性返回一个 (v, r, s) 的三元组。

Signature.verify_msg(message, public_key) -> bool

此方法根据签名是否为给定公钥的有效签名返回 True 或 False。

• message：必须是一个字节字符串。
• public_key：必须是 PublicKey 的实例

Signature.verify_msg_hash(message_hash, public_key) -> bool

与 Signature.verify_msg 相同，只不过 message_hash 应该是 message 的 Keccak 哈希。

Signature.recover_public_key_from_msg(message) -> PublicKey

此方法返回从签名恢复的 PublicKey 实例。

• message：必须是一个字节字符串。

Signature.recover_public_key_from_msg_hash(message_hash) -> PublicKey

与 Signature.recover_public_key_from_msg 相同，只不过 message_hash 应该是 message 的 Keccak 哈希。

异常

eth_api.exceptions.ValidationError

在实例化 PublicKey、PrivateKey 或 Signature 类的任何类时，如果它们的构造函数参数无效，则会引发此错误。

eth_api.exceptions.BadSignature

此错误会在签名无效时从任何涉及签名的 recover 或 verify 方法中引发。

开发者设置

如果您想对 eth-keys 进行开发，请查阅 Snake Charmers 战术手册，了解我们如何进行。

• 测试
• 拉取请求
• 文档

我们使用 pre-commit 来维护一致的代码风格。安装后，它将在每次提交时自动运行。您也可以使用 make lint 手动运行它。如果您需要提交跳过 pre-commit 检查的提交，可以使用 git commit --no-verify。

开发环境设置

您可以使用以下方法设置您的开发环境

git clone git@github.com:ethereum/eth-keys.git
cd eth-keys
virtualenv -p python3 venv
. venv/bin/activate
python -m pip install -e ".[dev]"
pre-commit install

发布设置

要发布新版本

make release bump=$$VERSION_PART_TO_BUMP$$

如何增加版本号

此存储库的版本格式为稳定版 {major}.{minor}.{patch}，以及不稳定版 {major}.{minor}.{patch}-{stage}.{devnum}（stage 可以是 alpha 或 beta）。

要发布下一个版本，请指定要增加的部分，例如 make release bump=minor 或 make release bump=devnum。这通常在主分支上进行，除非发布 beta 版本（在这种情况下，beta 版本从主分支发布，而之前稳定分支从该分支发布）。

如果您处于 beta 版本，使用 make release bump=stage 将切换到稳定版本。

当当前版本为稳定版本时，要发布不稳定版本，请明确指定新版本，例如 make release bump="--new-version 4.0.0-alpha.1 devnum"