Skip to main content

ChainMaker Python SDK

Project description

Chainmaker-Python-SDK

[长安链]Python SDK。基于gRPC及chainmaker/pb(protos)的链客户端。 提供链查询、链配置、用户合约管理、证书管理、公钥管理、订阅管理、多签管理、归档、Gas管理、交易池查询、DPos Erc20、DPos Stake、隐私计算等操作。

sdk-python开源仓库地址

特性

  • 支持PermissionedWithCert、PermissionedWithKey、Public三种模式
  • 支持链查询,查询区块信息、区块头、区块高度、交易信息等
  • 支持查询链配置,更新核心配置、区块配置,增加修改删除信任根证书,增加修改共识节点等
  • 支持用户合约操作,合约查询、创建、更新、调用、查询、冻结、解冻、吊销等
  • 支持证书管理、证书哈希、证书别名管理及公钥管理
  • 支持Gas管理,查询设置Gas管理员,查询Gas账户状态、余额,Gas充值、退款等操作
  • 支持DPos Erc20、DPos权益、DPos惩罚、DPos奖励等相关操作
  • 支持交易池状态查询
  • 支持区块订阅、交易合约及订阅合约事件
  • 支持多签请求、投票、查询等,支持多签手动运行及自动运行
  • 支持交易黑名单功能
  • 支持隐私计算
  • 支持国密非TLS场景(如,Public模式+国密)
  • 支持共识高度、共识状态等查询

安装方法

chainmaker-python-sdk支持 python3.6~python3.10, 已知python3.11安装pysha3存在问题

在线安装

$ pip install chainmaker

使用方法

以配置文件形式创建ChainClient

配置文件sdk_config.yml格式参考

配置文件./testdata/sdk_config.yml参考内容

chain_client:
  chain_id: "chain1"
  org_id: "wx-org1.chainmaker.org"
  user_key_file_path: "./testdata/crypto-config/wx-org1.chainmaker.org/user/client1/client1.tls.key"
  user_crt_file_path: "./testdata/crypto-config/wx-org1.chainmaker.org/user/client1/client1.tls.crt"
  user_sign_key_file_path: "./testdata/crypto-config/wx-org1.chainmaker.org/user/client1/client1.sign.key"
  user_sign_crt_file_path: "./testdata/crypto-config/wx-org1.chainmaker.org/user/client1/client1.sign.crt"

  nodes:
    - node_addr: "127.0.0.1:12301"  # 节点rpc服务地址
      enable_tls: true
      conn_cnt: 1
      trust_root_paths:
        - "./testdata/crypto-config/wx-org1.chainmaker.org/ca"
        - "./testdata/crypto-config/wx-org2.chainmaker.org/ca"
      tls_host_name: "chainmaker.org" 

注: sdk_config.yml中私钥/证书等如果使用相对路径应相对于当前运行起始目录,建议使用绝对路径

使用配置文件创建链客户端

from chainmaker import ChainClient
# 创建链客户端
cc = ChainClient.from_conf('./testdata/sdk_config.yml')
# 获取链版本
print(cc.get_chainmaker_server_version())

使用管理台生成的链由于生成的证书未包含部署服务器的域名使用sdk-python可能导致连接不上,参见已知问题

以参数形式创建ChainClient

from chainmaker import Node, User, ChainClient

crypto_config_path = './testdata/crypto-config'
node_addr = '127.0.0.1:12301'

def read_file_bytes(file_path):
    return open(file_path, 'rb').read()

# 创建签名用户
user = User(
    org_id='wx-org1.chainmaker.org',
    sign_key_bytes=read_file_bytes(f'{crypto_config_path}/wx-org1.chainmaker.org/user/client1/client1.tls.key'),
    sign_cert_bytes=read_file_bytes(f'{crypto_config_path}/wx-org1.chainmaker.org/user/client1/client1.tls.crt'),
    tls_key_bytes=read_file_bytes(f'{crypto_config_path}/wx-org1.chainmaker.org/user/client1/client1.sign.key'),
    tls_cert_bytes=read_file_bytes(f'{crypto_config_path}/wx-org1.chainmaker.org/user/client1/client1.sign.crt')
)

# 创建连接节点
node = Node(
    node_addr=node_addr,
    conn_cnt=1,
    enable_tls=True,
    trust_cas=[read_file_bytes(f'{crypto_config_path}/wx-org1.chainmaker.org/ca'),
               read_file_bytes(f'{crypto_config_path}/wx-org2.chainmaker.org/ca')],
    tls_host_name='chainmaker.org'
)

# 创建链客户端
cc = ChainClient(chain_id='chain1', user=user, nodes=[node])
# 获取链版本
print(cc.get_chainmaker_server_version())

创建wasm合约

from chainmaker import ChainClient, RuntimeType

crypto_config_path = './testdata/crypto-config'

# 背书用户配置
endorsers_config = [
    {'org_id': 'wx-org1.chainmaker.org',
     'user_sign_crt_file_path': f'{crypto_config_path}/wx-org1.chainmaker.org/user/admin1/admin1.sign.crt',
     'user_sign_key_file_path': f'{crypto_config_path}/wx-org1.chainmaker.org/user/admin1/admin1.sign.key'},
    {'org_id': 'wx-org2.chainmaker.org',
     'user_sign_crt_file_path': f'{crypto_config_path}/wx-org2.chainmaker.org/user/admin1/admin1.sign.crt',
     'user_sign_key_file_path': f'{crypto_config_path}/wx-org2.chainmaker.org/user/admin1/admin1.sign.key'},
    {'org_id': 'wx-org3.chainmaker.org',
     'user_sign_crt_file_path': f'{crypto_config_path}/wx-org3.chainmaker.org/user/admin1/admin1.sign.crt',
     'user_sign_key_file_path': f'{crypto_config_path}/wx-org3.chainmaker.org/user/admin1/admin1.sign.key'},
]

cc = ChainClient.from_conf('./testdata/sdk_config.yml')


# 创建WASM合约,本地合约文件./testdata/contracts/rust-fact-2.0.0.wasm应存在
payload = cc.create_contract_create_payload(
    contract_name='fact', 
    version='1.0', 
    byte_code_or_file_path='./testdata/contracts/rust-fact-2.0.0.wasm',
    runtime_type=RuntimeType.WASMER, 
    params={})
# 创建背书
endorsers = cc.create_endorsers(payload, endorsers_config)
# 发送创建合约请求
tx_response = cc.send_contract_manage_request(payload, endorsers=endorsers, with_sync_result=True)
print(tx_response)

创建evm合约

from chainmaker import ChainClient, RuntimeType

crypto_config_path = './testdata/crypto-config'

# 背书用户配置
endorsers_config = [
    {'org_id': 'wx-org1.chainmaker.org',
     'user_sign_crt_file_path': f'{crypto_config_path}/wx-org1.chainmaker.org/user/admin1/admin1.sign.crt',
     'user_sign_key_file_path': f'{crypto_config_path}/wx-org1.chainmaker.org/user/admin1/admin1.sign.key'},
    {'org_id': 'wx-org2.chainmaker.org',
     'user_sign_crt_file_path': f'{crypto_config_path}/wx-org2.chainmaker.org/user/admin1/admin1.sign.crt',
     'user_sign_key_file_path': f'{crypto_config_path}/wx-org2.chainmaker.org/user/admin1/admin1.sign.key'},
    {'org_id': 'wx-org3.chainmaker.org',
     'user_sign_crt_file_path': f'{crypto_config_path}/wx-org3.chainmaker.org/user/admin1/admin1.sign.crt',
     'user_sign_key_file_path': f'{crypto_config_path}/wx-org3.chainmaker.org/user/admin1/admin1.sign.key'},
]

cc = ChainClient.from_conf('./testdata/sdk_config.yml')
# 创建EVM合约,本地合约文件./testdata/contracts/ledger_balance.bin应存在
payload = cc.create_contract_create_payload(
    contract_name='balance001', 
    version='1.0', 
    byte_code_or_file_path='./testdata/contracts/ledger_balance.bin',
    runtime_type=RuntimeType.EVM)
# 创建背书
endorsers = cc.create_endorsers(payload, endorsers_config)
# 发送创建合约请求
tx_response = cc.send_contract_manage_request(payload, endorsers=endorsers, with_sync_result=True)
print(tx_response)

调用wasm合约

from chainmaker.chain_client import ChainClient
from chainmaker.utils.evm_utils import calc_evm_method_params

# 创建客户端
cc = ChainClient.from_conf('./testdata/sdk_config.yml')

# 调用WASM合约
tx_response = cc.invoke_contract(
    contract_name='fact',
    method='save',
    params={"file_name": "name007", "file_hash": "ab3456df5799b87c77e7f88", "time": "6543234"},
    with_sync_result=True)

print(tx_response)

调用evm合约

from chainmaker.chain_client import ChainClient
from chainmaker.utils.evm_utils import calc_evm_method_params

# 创建客户端
cc = ChainClient.from_conf('./testdata/sdk_config.yml')
# 调用EVM合约
evm_contract_name = 'balance001'  # EVM合约名不再需要进行转换
evm_method, evm_params = calc_evm_method_params(
    method='updateBalance', 
    params=[{"uint256": "10000"}, {"address": "0xa166c92f4c8118905ad984919dc683a7bdb295c1"}])

tx_response = cc.invoke_contract(
    contract_name=evm_contract_name, 
    method=evm_method, 
    params=evm_params, 
    with_sync_result=True)

print(tx_response)

更多示例和用法

更多示例和用法,请参考单元测试用例

功能 单测代码
用户合约 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

接口说明

详细参考: SDK接口文档

变更纪录

详细参考CHANGELOG

如何运行测试

  1. 安装测试需要的依赖
pip install -r requirements-test.txt
  1. 下载并拷贝被测环境的crypto-config到tests/resources/目录下

  2. 修改tests/resources/sdk_config.yml中的节点地址或修改tests/pytest.ini中是sdk_config配置指定sdk_config.yml路径

  3. 运行测试

pytest tests

如何进行开发

  1. 安装依赖
pip install requirements-dev

更新protos

make proto

测试覆盖率

make coverage

检查代码

make lint

发布

make release

TODO

  • 支持国密TLS
  • 实现Hibe加密

已知问题

  • 使用Python3.11安装时,pysha3会build失败,可以改为Python3.6~python3.10,建议使用Python3.9
  • 使用管理台部署的链,使用sdk-python连接报错(使用sdk-go能连接),可能原因为管理台生成的证书扩展SAN(SubjectAlternativeName)中不包含部署服务的域名导致OpenSSL验证失败所致(sdk-go不验证该项),可以尝试在sdk_config.yml的tls_host_name修改为你的域名,或尝试使用 chainmaker-cryptogen项目生成证书。

参考

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-3.0.4.tar.gz (61.1 kB view hashes)

Uploaded Source

Built Distribution

chainmaker-3.0.4-py3-none-any.whl (277.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page