ChainMaker Python SDK
Project description
ChainMaker-Python-SDK
长安链Python SDK
特性
目前python-sdk 除了不支持private_compute、hibe及国密通信外,支持go-sdk所有接口, 支持列表如下:
- 链查询(系统合约)apis/system_contract.py
- 链配置管理 apis/chain_config.py
- 用户合约管理 apis/user_contract.py
- 证书管理 apis/cert_manage.py
- 公钥管理 apis/pubkey_manage.py
- Gas管理 apis/gas_manage.py
- 证书别名管理 apis/cert_alias_manage.py
- 归档 apis/archive.py
- 多签 apis/multisign_contract.py
- 订阅 apis/subscribe.py
详细接口及使用方式可以查看 apis/base_client.py
另外
- 支持PermissionedWithCert、PermissionedWithKey、Public三种模式
- PermissionedWithCert模式下,支持启用证书哈希(短证书)、支持证书别名
- 支持RSA、EC加密,及SHA256哈希算法
- 支持EVM合约名称、方法、参数转换 utils/evm_utils.calc_evm_contarct_name calc_evm_method_params
- 支持EVM账户地址生成、至信链地址生成 utils/crypto_utils.get_evm_address_from_public_key get_zx_address_from_public_key
- 支持crl吊销文件生成 utils/crypto_utils/create_crl_bytes
- 支持归档及恢复逻辑 utils/archive_utils.ArchiveUtils
- 支持日志 cc.logger 默认只输出到控制台,不输出到文件
- 支持链接池 cc.pool
- 支持同步获取交易结果 cc.send_request_with_sync_result(payload, endorsers, with_sync_result=True)
环境依赖
Python
版本为Python3.6或以上 下载地址:https://www.python.org/downloads/ 若已安装,请通过命令查看版本:
$ python3 --version
Python 3.8.2
下载安装
$ pip3 install git+https://git.chainmaker.org.cn/chainmaker/sdk-python.git
TODO: 发布到PyPi
pip3 install chainmaker
示例代码
创建节点
注️:需要拷贝目标链chainmaker-go/build/crypto-config到脚本所在目录
from chainmaker.node import Node
# 创建节点
node = Node(
node_addr='127.0.0.1:12301',
conn_cnt=10,
enable_tls=True,
cas=['./testdata/crypto-config/wx-org1.chainmaker.org/ca', './testdata/crypto-config/wx-org2.chainmaker.org/ca'],
tls_host_name='chainmaker.org'
)
以参数形式创建ChainClient
更多内容请参考:
tests/test_chain_client.py
注:示例中证书采用路径方式去设置,也可以使用证书内容去设置,具体请参考
createClientWithCaCerts
方法
from chainmaker.chain_client import ChainClient
from chainmaker.node import Node
from chainmaker.user import User
from chainmaker.utils import file_utils
user = User('wx-org1.chainmaker.org',
sign_key_bytes=file_utils.read_file_bytes('./testdata/crypto-config/wx-org1.chainmaker.org/user/client1/client1.tls.key'),
sign_cert_bytes=file_utils.read_file_bytes('./testdata/crypto-config/wx-org1.chainmaker.org/user/client1/client1.tls.crt'),
tls_key_bytes=file_utils.read_file_bytes('./testdata/crypto-config/wx-org1.chainmaker.org/user/client1/client1.sign.key'),
tls_cert_bytes=file_utils.read_file_bytes('./testdata/crypto-config/wx-org1.chainmaker.org/user/client1/client1.sign.crt')
)
node = Node(
node_addr='127.0.0.1:12301',
conn_cnt=1,
enable_tls=True,
trust_cas=[
file_utils.read_file_bytes('./testdata/crypto-config/wx-org1.chainmaker.org/ca/ca.crt'),
file_utils.read_file_bytes('./testdata/crypto-config/wx-org2.chainmaker.org/ca/ca.crt')
],
tls_host_name='chainmaker.org'
)
cc = ChainClient(chain_id='chain1', user=user, nodes=[node])
print(cc.get_chainmaker_server_version())
以配置文件形式创建ChainClient
注:参数形式和配置文件形式两个可以同时使用,同时配置时,以参数传入为准
from chainmaker.chain_client import ChainClient
# ./testdata/sdk_config.yml 中私钥/证书等如果使用相对路径应相对于当前运行起始目录
cc = ChainClient.from_conf('./testdata/sdk_config.yml')
创建合约
from google.protobuf import json_format
from chainmaker.chain_client import ChainClient
from chainmaker.utils.evm_utils import calc_evm_contract_name
from chainmaker.keys import RuntimeType
endorsers_config = [{'org_id': 'wx-org1.chainmaker.org',
'user_sign_crt_file_path': './testdata/crypto-config/wx-org1.chainmaker.org/user/admin1/admin1.sign.crt',
'user_sign_key_file_path': './testdata/crypto-config/wx-org1.chainmaker.org/user/admin1/admin1.sign.key'},
{'org_id': 'wx-org2.chainmaker.org',
'user_sign_crt_file_path': './testdata/crypto-config/wx-org2.chainmaker.org/user/admin1/admin1.sign.crt',
'user_sign_key_file_path': './testdata/crypto-config/wx-org2.chainmaker.org/user/admin1/admin1.sign.key'},
{'org_id': 'wx-org3.chainmaker.org',
'user_sign_crt_file_path': './testdata/crypto-config/wx-org3.chainmaker.org/user/admin1/admin1.sign.crt',
'user_sign_key_file_path': './testdata/crypto-config/wx-org3.chainmaker.org/user/admin1/admin1.sign.key'},
]
cc = ChainClient.from_conf('./testdata/sdk_config.yml')
def create_contract(contract_name: str, version: str, byte_code_path: str, runtime_type: RuntimeType, params: dict = None,
with_sync_result=True) -> dict:
"""创建合约"""
# 创建请求payload
payload = cc.create_contract_create_payload(contract_name, version, byte_code_path, runtime_type, params)
# 创建背书
endorsers = cc.create_endorsers(payload, endorsers_config)
# 携带背书发送请求
res = cc.send_request_with_sync_result(payload, with_sync_result=with_sync_result, endorsers=endorsers)
# 交易响应结构体转为字典格式
return json_format.MessageToDict(res)
# 创建WASM合约,本地合约文件./testdata/claim-wasm-demo/rust-fact-2.0.0.wasm应存在
result1 = create_contract('fact', '1.0', './testdata/claim-wasm-demo/rust-fact-2.0.0.wasm', RuntimeType.WASMER, {})
print(result1)
# 创建EVM合约,本地合约文件./testdata/balance-evm-demo/ledger_balance.bin应存在
contract_name = calc_evm_contract_name('balance001')
result2 = create_contract(contract_name, '1.0', './testdata/balance-evm-demo/ledger_balance.bin', RuntimeType.EVM)
print(result2)
调用合约
from google.protobuf import json_format
from chainmaker.chain_client import ChainClient
from chainmaker.utils.evm_utils import calc_evm_contract_name, calc_evm_method_params
# 创建客户端
cc = ChainClient.from_conf('./testdata/sdk_config.yml')
# 调用WASM合约
res1 = cc.invoke_contract('fact', 'save', {"file_name":"name007","file_hash":"ab3456df5799b87c77e7f88","time":"6543234"},
with_sync_result=True)
# 交易响应结构体转为字典格式
print(json_format.MessageToDict(res1))
# 调用EVM合约
evm_contract_name = calc_evm_contract_name('balance001')
evm_method, evm_params = calc_evm_method_params('updateBalance', [{"uint256": "10000"}, {"address": "0xa166c92f4c8118905ad984919dc683a7bdb295c1"}])
res2 = cc.invoke_contract(evm_contract_name, evm_method, evm_params, with_sync_result=True)
# 交易响应结构体转为字典格式
print(json_format.MessageToDict(res2))
更多示例和用法
更多示例和用法,请参考单元测试用例
功能 | 单测代码 |
---|---|
用户合约 | tests/test_user_contract.py |
系统合约 | tests/test_system_contract.py |
链配置 | tests/test_chain_config.py |
证书管理 | tests/test_cert_manage.py |
消息订阅 | tests/test_user_contract.py |
接口说明
提供Go、Java、JS、Python多语言SDK。
各语言版本需要覆盖的接口有:
接口清单
- 已实现 ✅ 测试通过
1 用户合约接口
- 1.1 生成合约创建待签名Payload cc.create_contract_create_payload ✅
- 1.2 生成合约升级待签名Payload cc.create_contract_upgrade_payload ✅
- 1.3 生成合约冻结待签名Payload cc.create_contract_freeze_payload ✅
- 1.4 生成合约解冻待签名Payload cc.create_contract_unfreeze_payload ✅
- 1.5 生成合约吊销待签名Payload cc.create_contract_revoke_payload ✅
- 1.6 签名合约管理Payload cc.sign_contract_manage_payload ✅
- 1.7 合约管理Payload签名收集&合并
- 1.8 发送合约管理请求(创建、更新、冻结、解冻、吊销)cc.send_contract_manage_request ✅
- 1.9 调用合约 cc.invoke_contract ✅
- 1.10 查询合约 cc.query_contract ✅
- 1.11 获取交易请求体 cc.get_tx_request ✅
- 1.12 发送交易请求体 cc.send_tx_request ✅
2 系统合约接口
- 2.1 根据交易ID获取交易信息 cc.get_tx_by_tx_id ✅
- 2.2 根据区块高度获取区块信息 cc.get_block_by_height ✅
- 2.3 根据区块哈希获取区块信息 cc.get_block_by_hash
- 2.4 根据交易ID获取区块信息 cc.get_block_by_tx_id ✅
- 2.5 获取最新的配置块信息 cc.get_last_config_block ✅
- 2.6 获取最新区块信息 cc.get_last_block ✅
- 2.7 获取链信息 cc.get_chain_info ✅
- 2.8 获取链配置 cc.get_chain_config ✅
- 2.9 获取节点加入的链列表 cc.get_node_chain_list ✅
- 2.10 根据区块高度获取完整区块信息 cc.get_full_block_by_height ✅
- 2.11 根据交易ID获取区块高度 cc.get_block_height_by_tx_id ✅
- 2.12 根据区块哈希获取区块高度 cc.get_block_height_by_hash
- 2.13 获取已归档的区块高度 cc.get_archived_block_height ✅
- 2.14
根据交易ID或区块hash获取区块高度 cc.get_block_height✅ # TODO 转为私有方法 _get_block_height - 2.15 获取当前区块高度 cc.get_current_block_height ✅
- 2.16 根据区块高度获取区块头信息 cc.get_block_header_by_height ✅
- 2.17 调用系统合约 cc.invoke_system_contract
- 2.18 查询系统合约 cc.query_system_contract
3 链配置接口
- 3.1 获取链配置 cc.get_chain_config ✅
- 3.2 根据区块高度获取链配置 cc.get_chain_config_by_block_height ✅
- 3.3 获取链配置序号 cc.get_chain_config_sequence ✅
- 3.4 签名链配置更新Payload cc.sign_chain_config_payload ✅
- 3.5 链配置更新Payload签名收集&合并
- 3.6 发送链配置更新请求
- 3.7 生成链配置Core模块更新待签名Payload cc.create_chain_config_core_update_payload ✅
- 3.7 生成链配置Block模块更新待签名Payload cc.create_chain_config_block_update_payload ✅
- 3.8 生成链配置信任组织根证书添加待签名Payload cc.create_chain_config_trust_root_add_payload ✅
- 3.9 生成链配置信任组织根证书更新待签名Payload cc.create_chain_config_trust_root_update_payload ✅
- 3.10 生成链配置信任组织根证书删除待签名Payload cc.create_chain_config_trust_root_delete_payload ✅
- 3.11 生成链配置权限配置添加待签名Payload cc.create_chain_config_permission_add_payload ✅
- 3.12 生成链配置权限配置更新待签名Payload cc.create_chain_config_permission_update_payload ✅
- 3.13 生成链配置权限配置删除待签名Payload cc.create_chain_config_permission_delete_payload ✅
- 3.14 生成链配置共识节点地址添加待签名Payload cc.create_chain_config_consensus_node_id_add_payload ✅
- 3.15 生成链配置共识节点地址更新待签名Payload cc.create_chain_config_consensus_node_id_update_payload ✅
- 3.16 生成链配置共识节点地址删除待签名Payload cc.create_chain_config_consensus_node_id_delete_payload ✅
- 3.17 生成链配置共识节点组织添加待签名Payload cc.create_chain_config_consensus_node_org_add_payload ✅
- 3.18 生成链配置共识节点组织更新待签名Payload cc.create_chain_config_consensus_node_org_update_payload ✅
- 3.19 生成链配置共识节点组织删除待签名Payload cc.create_chain_config_consensus_node_org_delete_payload ✅
- 3.20 生成链配置共识扩展字段添加待签名Payload cc.create_chain_config_consensus_ext_add_payload ✅
- 3.21 生成链配置共识扩展字段更新待签名Payload cc.create_chain_config_consensus_ext_update_payload ✅
- 3.22 生成链配置共识扩展字段删除待签名Payload cc.create_chain_config_consensus_ext_delete_payload ✅
- 3.23 生成链配置第三方证书信息添加待签名Payload cc.create_chain_config_trust_member_add_payload
- 3.24
生成链配置更新第三方证书信息Payload cc.create_chain_config_trust_member_update_payload - 3.25 生成链配置第三方证书信息删除待签名Payload cc.create_chain_config_trust_member_delete_payload
4 证书管理接口
- 4.1 添加证书 cc.add_cert ✅
- 4.2 删除证书 cc.delete_cert ✅
- 4.3 查询证书 cc.query_cert ✅
- 4.4 获取证书哈希值 cc.get_cert_hash ✅
- 4.5 生成证书管理待签名Payload cc.create_cert_manage_payload ✅
- 4.6 生成证书冻结待签名Payload cc.create_cert_manage_frozen_payload ✅
- 4.7 生成证书解冻待签名Payload cc.create_cert_manage_unfrozen_payload ✅
- 4.8 生成证书吊销待签名Payload cc.create_cert_manage_revocation_payload ✅
- 4.9 签名证书管理Payload cc.sign_cert_manage_payload ✅
- 4.10 证书管理Payload签名收集&合并
- 4.11 发送证书管理请求 cc.send_cert_manage_request ✅
5 在线多签接口
- 5.1 待签payload签名
- 5.2 多签请求
- 5.3 多签投票
- 5.4 投票获取
6 消息订阅接口
- 6.1 区块订阅 cc.subscribe_block
- 6.2 交易订阅 cc.subscribe_tx
- 6.3 多合一订阅 cc.subscribe
7 证书压缩
- 7.1 启用压缩证书功能 cc.enable_cert_hash
- 7.2 停用压缩证书功能 cc.disable_cert_hash
8 工具类
- 8.1 将EasyCodec编码解码成map
- 8.2 根据X.509证书路径得到EVM地址
- 8.3 根据X.509证书内容得到EVM地址
9 层级属性加密类接口
- 9.1 生成层级属性参数初始化交易待签名Payload
- 9.2 生成层级属性加密交易待签名Payload,加密参数已知
- 9.3 生成层级属性加密交易待签名Payload,参数由链上获取得出
- 9.5 已知交易id,根据私钥解密密文交易
10 系统类接口
- 10.1 SDK停止接口 ✅
- 10.2 获取链版本 ✅
11 公钥管理
仅适用于 permissionedWithKey 模式
- 11.1 生成公钥添加待签名Payload cc.create_pubkey_add_payload ✅
- 11.1 生成公钥删除待签名Payload cc.create_pubkey_del_payload ✅
- 11.1 生成公钥获取待签名Payload cc.create_pubkey_query_payload ✅
- 11.1 发送公钥管理请求 cc.send_pubkey_manage_request ✅
12 Gas 计费管理
仅使用于 Pubic 模式
- 12.1 获取Gas管理员地址 cc.get_gas_admin ✅
- 12.2 获取Gas账户余额 cc.get_gas_balance ✅
- 12.3 获取Gas账户状态 cc.get_gas_account_status ✅
- 12.4 生成设置Gas管理员地址待签名Payload cc.create_set_gas_admin_payload ✅
- 12.5 生成Gas充值待签名Payload cc.create_recharge_gas_payload ✅
- 12.6 生成Gas退款待签名Payload cc.create_refund_gas_payload ✅
- 12.7 生成Gas冻结待签名Payload cc.create_frozen_gas_account_payload ✅
- 12.8 生成Gas解冻待签名Payload cc.create_unfrozen_gas_account_payload ✅
- 12.9 发送Gas管理请求 cc.send_gas_manage_request
- 12.10 附加Gas限制 cc.attach_gas_limit
TODO
- 支持国密
参考
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
chainmaker-2.2.0.tar.gz
(115.1 kB
view hashes)
Built Distribution
chainmaker-2.2.0-py3-none-any.whl
(144.1 kB
view hashes)
Close
Hashes for chainmaker-2.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4dc670c4e03a256c7187db547f81f2bdb5590aeff4ccf5756b5efeffcb7d0499 |
|
MD5 | 0e4b1d914706da2c1b4b3f9985c1777a |
|
BLAKE2b-256 | f793164189501d4b6ce5accf32991a2baf2647f79c643f9026372b01055cb7ad |