diff --git a/README.md b/README.md index e3d7ced6..9abdf8f5 100644 --- a/README.md +++ b/README.md @@ -1,128 +1,67 @@ -[TOC] -#JD区块链 +![logo](http://storage.jd.com/jd.block.chain/jdt-jdchain.png) +
[![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.jd.blockchain/sdk-pack/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.jd.blockchain/sdk-pack/) [![Build Status](https://travis-ci.com/blockchain-jd-com/jdchain.svg?branch=master)](https://travis-ci.org/blockchain-jd-com/jdchain) +
+一个面向企业应用场景的通用区块链框架系统，能够作为企业级基础设施，为业务创新提供高效、灵活和安全的解决方案。 +## 源码构建 ------------------------------------------------------------------------- +`JD Chain`源码通过`git`及`git submodule`进行管理，如下操作可快速构建： -## 一、项目介绍 -JD Chain 的目标是实现一个面向企业应用场景的通用区块链框架系统，能够作为企业级基础设施，为业务创新提供高效、灵活和安全的解决方案。 - - -## 二、部署模型 - -JD Chain 主要部署组件包括以下几种： - -- 共识节点 - - 共识节点即参与共识的节点，这是系统的核心组件，承担了运行共识协议、管理账本数据、运行智能合约的职责。 - - 一个区块链网络由多个共识节点组成，共识节点的数量范围由选择的共识协议决定。 - - 共识节点和账本是两个不同的概念，共识节点是个物理上的概念，账本是个逻辑上的概念。JD Chain 是一个多账本区块链系统，一个共识节点上可以装载运行多个账本。账本是数据维度的独立管理单元。共识节点和账本的关系，就像关系数据库系统中，数据库服务器和数据库实例的关系。 - - 共识节点通常都部署在参与方的内部网络中，通过由网络管理员指定的安全的网络出口与其它的共识节点建立通讯连接。 - - 共识节点在形态上是服务器中的一个处理进程，背后需要连接一个本地或者内网的NoSQL数据库系统作为账本的存储。当前版本，共识节点目前是单进程的，未来版本将实现多进程以及多服务器集群模式。 - -- 网关节点 - - 网关节点是负责终端接入的节点，负责终端连接、协议转换、交易准入、本地密码运算、密钥管理等职责。 - - 网关节点是一种轻量节点，需要绑定一个特定参与方的密钥对，连接到一个或多个共识节点。 - - 网关节点向共识节点的连接是需要通过认证的，绑定的参与方的密钥对必须事先已经注册到区块链账本中，且得到接入授权。 - -- 终端 - - 终端泛指可以提交交易的客户端，典型来说，包括人、自动化设备、链外的信息系统等。 - - 终端只能通过网关节点来提交交易。终端提交的交易需要用体现该终端身份的私钥来签署，产生一份电子签名。随后当交易提交给网关节点时，网关节点需要在把交易提交到共识节点之前，对交易请求以网关节点绑定的私钥追加一项“节点签名”。 - - -- 备份节点 - - 仅对账本数据提供备份，但不参与交易共识的节点。（注：目前版本中尚未实现，将在后续版本中提供） - - -![](docs/images/deployment.jpg) +```bash +$ git clone https://github.com/blockchain-jd-com/jdchain.git jdchain +$ cd jdchain -## 三、构建源代码 +# 此处仅以 master 分支为例，正常情况下 master 分支可无障碍构建成功 +# 不推荐使用 develop 分支，submodule 代码可能未对齐 +# 推荐切换到具体已发布的版本分支 +$ git checkout master -1. 安装 Maven 环境 +$ chmod +x build/*.sh - JD Chain 当前版本以 Java 语言开发，需要安装配置 JVM 和 Maven，JDK 版本不低于1.8 。(没有特殊要求，请按标准方法安装，此处不赘述) - -2. 安装 Git 工具 - - 为了能够执行 git clone 命令获取代码仓库。 (没有特殊要求，请按标准方法安装，此处不赘述) - -3. 项目库说明 +# 执行完整的构建，包括执行”集成测试“和”打包“两部分；提供两个参数： +# --skipTests ：跳过集成测试部分； +# --update ：从远程仓库更新子模块。注意，采用此参数会导致子模块本地仓库丢失尚未 commit 的代码。 +# 不附带此参数的情况下不会更新子模块仓库。 +$ build/build.sh --update -JD Chain 源代码包括 3 个代码仓库 +# 跳过子模块代码更新和集成测试，直接编译和打包； +$ build/build.sh --skipTests -- jdchain 项目库： - - URL：git@github.com:blockchain-jd-com/jdchain.git - - 说明：主项目库，包含说明文档、示例代码，用于集成构建和打包； - - #### `主项目库包含以下 6 个子模块仓库，通过执行脚本 <主项目库根目录>/build/build.sh 便可以一键完成子模块的下载和整体的编译、测试和打包操作.` +# 首次代码拉取，跳过继承测试编译打包可执行： +build/build.sh --update --skipTests +``` -- project 项目库： - - URL：git@github.com:blockchain-jd-com/jdchain-project.git - - 说明：公共的父项目，定义公共的依赖； -- framework 项目库： - - URL：git@github.com:blockchain-jd-com/jdchain-framework.git - - 说明：框架源码库，定义公共数据类型、框架、模块组件接口、SDK、SPI、工具； -- core 项目库： - - URL：git@github.com:blockchain-jd-com/jdchain-core.git - - 说明：模块组件实现的源码库； -- explorer 项目库： - - URL：git@github.com:blockchain-jd-com/explorer.git - - 说明：相关产品的前端模块的源码库； -- libs/bft-smart 项目库： - - URL：git@github.com:blockchain-jd-com/bftsmart.git - - 说明：BFT-SMaRT 共识算法的源码库； -- test 项目库： - - URL：git@github.com:blockchain-jd-com/jdchain-test.git - - 说明：集成测试用例的源码库； +构建完成后会在`deploy`模块，`deploy-gateway`和`deploy-peer`目录`target`中生成网关安装部署包（`jdchain-gateway-*.zip`）和共识节点安装部署包（`jdchain-peer-*.zip`）。 -4. 构建操作 +## 部署使用 +### 快速部署 -```sh -$ git clone git@github.com:blockchain-jd-com/jdchain.git jdchain +使用[源码构建](#源码构建)生成的部署安装包，或者下载[官方部署安装包](http://ledger.jd.com/downloadapps.html) 参照[快速部署文档](docs/quick_start.md)可快速部署运行`JD Chain`网络。 -$ cd jdchain +### 数据上链 -$ git checkout develop +1. 命令行工具 -$ chmod +x build/*.sh +`JD Chain` 命令行工具集，即[jdchain-cli](docs/jdchain_cli.md)，提供密钥管理，实时交易，链上信息查询，离线交易，共识节点变更等操作。可快速执行数据上链和链上数据查询。 -# 执行完整的构建，包括执行”集成测试“和”打包“两部分；提供两个参数： -# --skipTests ：跳过集成测试部分； -# --update ：从远程仓库更新子模块。注意，采用此参数会导致子模块本地仓库丢失尚未 commit 的代码。 -# 不附带此参数的情况下不会更新子模块仓库。 -$ build/build.sh --update - -# 跳过集成测试，直接编译和打包； -$ build/build.sh --skipTests +2. SDK -# 只执行集成测试； -$ build/test.sh - -``` +`JD Chain`提供了`Java`和`Go`版本的`SDK`。实际项目开发中`Java`可参照[示例代码](https://github.com/blockchain-jd-com/jdchain/tree/master/samples)，`Go`语言`SDK`参照[framework-go](https://github.com/blockchain-jd-com/framework-go)。 -5. jdchain 的安装包 +### 更多 -当编译完成后，安装包位于主项目库的 deploy 目录中： +`JD Chain`功能开发，使用问题等欢迎`issue`中探讨，也欢迎广大开发者积极参与`JD Chain`社区活动及代码开发~ -- 共识节点的安装包： - - <主项目库根目录>/deploy/deploy-peer/target/jdchain-peer-**.zip -- 网关节点的安装包: - - <主项目库根目录>/deploy/deploy-gateway/target/jdchain-gateway-**.zip \ No newline at end of file +- `JD Chain`官方网站：https://ledger.jd.com/ +- 文档：[wiki](https://github.com/blockchain-jd-com/jdchain/wiki)，[docs](docs/) +- 京东智臻链官网：https://blockchain.jd.com/ +- 服务邮箱：jdchain-support@jd.com +- `FAQ`：https://github.com/blockchain-jd-com/jdchain/wiki/FAQ \ No newline at end of file diff --git a/deploy/deploy-gateway/src/main/resources/docs/api_doc_cn_1.3.MD b/deploy/deploy-gateway/src/main/resources/docs/api_doc_cn_1.3.MD deleted file mode 100644 index 6ef57c60..00000000 --- a/deploy/deploy-gateway/src/main/resources/docs/api_doc_cn_1.3.MD +++ /dev/null @@ -1,1716 +0,0 @@ -# 京东区块链浏览器API文档参考 V_1.3 - -## 1 API调用说明 - -该文档内的所有api的调用成功和失败均按照以下规则 - -### 1.1 成功 - -```json -{ - "data": ..., - "success": true -} -``` - -说明 - - - success 值为 true 表明api调用成功 - - data 为返回的数据，具体数据类型参考具体的api说明 - -### 1.2 失败 - -```json -{ - "error": { - "errorCode": 5000, - "errorMessage": "未预期的异常！ --Unsupported access ledger[6Gw3cK4uazegy4HjoaM81ck9NgYLNoKyBMb7a1TK1jt3d] !" - }, - "success": false -} -``` - -说明 - - - success 值为 false 表明api调用成功 - - errorCode 为异常代码 - - errorMessage 为错误提示 - -## 2 账本 - -### 2.1 获取账本总数 - -```http -GET /ledgers/count -``` - -#### 参数 -无 - - -#### 请求实例 -```http -http://localhost/ledgers/count -``` - -#### 返回实例 - -```json -{ - "data": 2, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|账本总数| - - -### 2.2 获取账本列表 - -```http -GET /ledgers?fromIndex={start_index}&count={count} -``` - -#### 参数 -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|query|start_index|否|查询账本的起始序号，默认为0|数字 -|query|count|否|查询返回账本的数量限制，默认最大限制为100，小于0或大于100均返回最大可返回结果集|数字 - - -#### 请求实例 -```http -http://localhost/ledgers?fromIndex=0&count=-1 -``` - -#### 返回实例 - -```json -{ - "data": [ - { - "value": "657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs" - } - ], - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|账本哈希列表| -|value|账户哈希| - -### 2.3 获取账本详细信息 - -```http -GET /ledgers/{ledger} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs -``` - -#### 返回实例 - -```json -{ - "data": { - "hash": { - "value": "657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs" - }, - "latestBlockHash": { - "value": "67XsKWgqZTBz1NsytKGpyNWHMbMRENWcBj8PEDYQnWiDL" - }, - "latestBlockHeight": 66 - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|账本信息| -|hash.value|账本哈希| -|latestBlockHash.value|最新区块哈希 -|latestBlockHeight|账本高度 - - -### 2.4 获取账本成员总数 - -```http -GET /ledgers/{ledger}/participants/count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/participants/count -``` - -#### 返回实例 - -```json -{ - "data": 4, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|账本成员总数| - - -### 2.5 获取账本成员列表 - -```http -GET /ledgers/{ledger}/participants?fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|query|start_index|否|查询成员起始序号，默认为0|数字 -|query|count|否|查询成员返回数量，默认最大返回100，小于0或大于100均返回最大可返回结果集|数字 - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/participants?fromIndex=0&count=-1 -``` - -#### 返回实例 - -```json -{ - "data": [ - { - "address": "5SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522", - "name": "jd.com", - "id": 0, - "pubKey": { - "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS" - } - }, - { - "address": "5SmA98VknTbZ1Z7fmbNPHBuN2pbD89ogy8Ha", - "name": "at.com", - "id": 1, - "pubKey": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - } - }, - { - "address": "5SmMWsqV2kbgrRMjyQFtSq1wvYuPzeRVepHG", - "name": "bt.com", - "id": 2, - "pubKey": { - "value": "mb4AtiGAH7vtPufMDuap2oca2Ww9X6KTkp59Eh5nZjXA5H" - } - }, - { - "address": "5Sm5QFyvN1dVB4GHFxWhDCp8vsJbNkdx31Ds", - "name": "xt.com", - "id": 3, - "pubKey": { - "value": "mb7pGhmmjqYUhxrJJ57C1YxXr9h1AWXv8QVosETyuLhVvH" - } - } - ], - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|id|成员唯一标识| -|name|成员名称| -|address|成员地址| -|pubKey.value|成员公钥| - -## 3 区块 - -### 3.1 获取最新区块 - -```http -GET /ledgers/{ledger}/blocks/latest -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/latest -``` - -#### 返回实例 - -```json -{ - "data": { - "ledgerHash": { - "value": "657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs" - }, - "previousHash": { - "value": "6EJZnMc9464DCSU2kgi96RyngEv8YeEfVoJNhH3yZ2v5T" - }, - "transactionSetHash": { - "value": "6LmZtDpMM7xE8FPChACEmLj1PLhfaoVM2rEHRsrV3ohPN" - }, - "userAccountSetHash": { - "value": "67jx7SctrwdSczxxuYjwBocA8fER7V8qcRZUzWamSav5p" - }, - "contractAccountSetHash": { - "value": "67ftaBhPDez24NEB9wiiTM3SNcn1XFz5rb7boYhpbbLXN" - }, - "adminAccountHash": { - "value": "69KEFp9m5iFyAiyGmJ2qPcVxuT79gMChMf9JkStBZe8aa" - }, - "dataAccountSetHash": { - "value": "6LB9gosVWEPG3uvWXkxTcWq22mcwMHVehbiXkavFtr5fZ" - }, - "hash": { - "value": "67XsKWgqZTBz1NsytKGpyNWHMbMRENWcBj8PEDYQnWiDL" - }, - "height": 66 - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|hash|区块哈希| -|ledgerHash|账本哈希| -|previousHash|前置区块哈希| -|transactionSetHash|交易集哈希| -|userAccountSetHash|用户集哈希| -|contractAccountSetHash|合约集哈希| -|adminAccountHash|管理员集哈希| -|dataAccountSetHash|数据账户集哈希| - -### 3.2 根据区块哈希获取区块详细信息 - -```http -GET /ledgers/{ledger}/blocks/hash/{block_hash} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串| -|path|block_hash|是|区块哈希|字符串| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/hash/67XsKWgqZTBz1NsytKGpyNWHMbMRENWcBj8PEDYQnWiDL -``` - -#### 返回实例 - -[参考](#block-detail) - - -### 3.3 根据区块高度获取区块详细信息 - -```http -GET /ledgers/{ledger}/blocks/height/{block_height} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串| -|path|block_height|是|区块高度|数字| - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/height/66 -``` - -#### 返回实例 - -[参考](#block-detail) - - -### 3.4 根据哈希查询区块总数 - -```http - GET /ledgers/{ledger}/blocks/count/search?keyword={keyword} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本，需要完整的账本哈希|string| -|**query**|**keyword**|是| 区块哈希的全部或者一部分|string| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/count/search?keyword=6D5M -``` - -#### 返回实例 - -```json -{ - "data": 26, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|查询到的区块总数| - -### 3.5 根据哈希查询区块 - -```http - GET /ledgers/{ledger}/blocks/search?keyword={keyword}&fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本，需要完整的账本哈希|string| -|**query**|**keyword**|是| 区块哈希的全部或者一部分|string| -|**query**|**start_index**|否| 查询区块结果起始序号，默认为0|string| -|**query**|**count**|否| 查询区块结果返回数量，默认最大值为100，小于0或大于100均返回最大可返回结果集|string| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/search?keyword=6D5M&fromIndex=0&count=-1 -``` - - -#### 返回实例 - -```json -{ - "data": { - "blocks": [ - { - "hash": "6D5MJZnybT69bXET5QdCZdLGT16rZBJEjxLkANmDuykcb" - } - ] - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|blocks|查询到的区块列表| -|hash|区块哈希值| -|height|区块高度| -|txCount|区块内交易数量| - -## 4 交易 - -### 4.1 获取账本交易总数 - -```http -GET /ledgers/{ledger}/txs/count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/txs/count -``` - -##### 返回实例 - -```json -{ - "data": 688, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|交易数量| - -### 4.2 根据区块高度查询区块内的交易数量 - -```http -GET /ledgers/{ledger}/blocks/height/{block_height}/txs/additional-count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串| -|path|block_height|是|区块高度|数字| - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/height/66/txs/additional-count - -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/hash/6D5MJZnybT69bXET5QdCZdLGT16rZBJEjxLkANmDuykcb/txs/additional-count -``` - -#### 返回实例 - -```json -{ - "data": 86, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|交易数量| - - -### 4.3 根据区块哈希查询区块内的交易数量 - -```http -GET /ledgers/{ledger}/blocks/hash/{block_hash}/txs/additional-count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串| -|path|block_hash|是|区块哈希|字符串| - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/hash/6D5MJZnybT69bXET5QdCZdLGT16rZBJEjxLkANmDuykcb/txs/additional-count -``` - -#### 返回实例 - -```json -{ - "data": 86, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|交易数量| - - -### 4.4 获取指定高度的区块交易列表 - -```http -GET /ledgers/{ledger}/blocks/height/{height}/txs?fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|height|是|区块高度|数字| -|query|start_index|否|查询交易的起始序号，默认为0|数字| -|query|count|否|查询返回交易的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/height/66/txs?fromIndex=0&count=-1 -``` - -#### 返回实例 - -```json -{ - "data": [ - { - "blockHeight": 1, - "executionState": "SUCCESS", - "transactionContent": { - "ledgerHash": { - "value": "657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs" - }, - "operations": [ - { - "userID": { - "address": { - "value": "5SmBgzsrnY6u9Y7DgSSkXfTkCgp83hiFin3v" - }, - "pubKey": { - "value": "mb5kukaqjWtXyAerfHU1JDtVwabSeBU5c3khMZbNh7R8VJ" - } - } - }, - { - "accountID": { - "address": { - "value": "5SmA98VknTbZ1Z7fmbNPHBuN2pbD89ogy8Ha" - }, - "pubKey": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - } - } - }, - { - "contractID": { - "address": { - "value": "5SmA98VknTbZ1Z7fmbNPHBuN2pbD89ogy8Ha" - }, - "pubKey": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - } - }, - "chainCode": "----------" - }, - { - "contractAddress": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - }, - "event": "----------", - "args": "----------" - }, - { - "writeSet": [{ - "key": "jdchain", - "value": { - "type": "TEXT", - "value": { - "value": "----------" - } - }, - "expectedVersion": 0 - }], - "accountAddress": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - } - } - ], - "hash": { - "value": "6BLtM1agb7ERKoN5AJgZKiTjzdS7BpjgzQNYK8ZeDqotA" - } - }, - "endpointSignatures": [ - { - "digest": { - "value": "42pbfM5YKnf39Gitr4UsjTCzhhnJjwNyi8MnLFYgP4VKewTLzHitzArHEMrCt3hZYUe5ex9XvqtmiCoWpeAbdc31F" - }, - "pubKey": { - "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS" - } - } - ], - "nodeSignatures": [ - { - "digest": { - "value": "66SQ95SbDaApAJhN2NsFx5sfAQTxsWhMW26D5iPqXc1jZU9rJEhRnqT1nzt62ZAcCvsfrjEsay3MxqXYA5tWPoA2U" - }, - "pubKey": { - "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS" - } - } - ] - } - ], - "success": true -} -``` - - -说明 - -|名称|说明| -|---|---| -|executionState|交易执行结果| -|transactionContent.hash|交易的哈希| -|transactionContent.operations|交易的操作列表| -|endpointSignatures|终端签名列表| -|nodeSignatures|节点的签名列表| - -### 4.5 获取指定哈希的区块的交易列表 - -```http -GET /ledgers/{ledger}/blocks/hash/{block_hash}/txs?fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|block_hash|是|区块哈希|字符串| -|query|start_index|否|查询交易的起始序号，默认为0|数字| -|query|count|否|查询返回交易的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/hash/6D5MJZnybT69bXET5QdCZdLGT16rZBJEjxLkANmDuykcb/txs?fromIndex=0&count=-1 -``` - -#### 返回实例 - -[参考](#tx-list) - - -### 4.6 获取交易详细信息 - -```http -GET /ledgers/{ledger}/txs/hash/{tx_hash} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|tx_hash|是|交易哈希|字符串| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/txs/hash/6BLtM1agb7ERKoN5AJgZKiTjzdS7BpjgzQNYK8ZeDqotA -``` - -#### 返回实例 - -```json -{ - "data": { - "blockHeight": 1, - "executionState": "SUCCESS", - "transactionContent": { - "ledgerHash": { - "value": "657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs" - }, - "operations": [ - { - "userID": { - "address": { - "value": "5SmBgzsrnY6u9Y7DgSSkXfTkCgp83hiFin3v" - }, - "pubKey": { - "value": "mb5kukaqjWtXyAerfHU1JDtVwabSeBU5c3khMZbNh7R8VJ" - } - } - }, - { - "accountID": { - "address": { - "value": "5SmA98VknTbZ1Z7fmbNPHBuN2pbD89ogy8Ha" - }, - "pubKey": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - } - } - }, - { - "contractID": { - "address": { - "value": "5SmA98VknTbZ1Z7fmbNPHBuN2pbD89ogy8Ha" - }, - "pubKey": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - } - }, - "chainCode": "----------" - }, - { - "contractAddress": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - }, - "event": "----------", - "args": "----------" - }, - { - "writeSet": [{ - "key": "jdchain", - "value": { - "type": "TEXT", - "value": { - "value": "----------" - } - }, - "expectedVersion": 0 - }], - "accountAddress": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - } - } - ], - "hash": { - "value": "6BLtM1agb7ERKoN5AJgZKiTjzdS7BpjgzQNYK8ZeDqotA" - } - }, - "endpointSignatures": [ - { - "digest": { - "value": "42pbfM5YKnf39Gitr4UsjTCzhhnJjwNyi8MnLFYgP4VKewTLzHitzArHEMrCt3hZYUe5ex9XvqtmiCoWpeAbdc31F" - }, - "pubKey": { - "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS" - } - } - ], - "nodeSignatures": [ - { - "digest": { - "value": "66SQ95SbDaApAJhN2NsFx5sfAQTxsWhMW26D5iPqXc1jZU9rJEhRnqT1nzt62ZAcCvsfrjEsay3MxqXYA5tWPoA2U" - }, - "pubKey": { - "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS" - } - } - ] - }, - "success": true -} -``` - -说明 - -[参考](#tx-keyword) - - -### 4.7 根据哈希查询交易总数 - -```http - GET /ledgers/{ledgers}/txs/count/search?keyword={keyword} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledgers**|是|所要搜索的账本范围，需要完整的账本哈希|string| -|**query**|**keyword**|是|交易哈希，签名者公钥，或者节点公钥的全部或者部分的|string| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/txs/search?keyword=6BLt -``` - -#### 返回实例 - -```json -{ - "data": 36, - "success": true -} -``` - - -说明 - -|名称|说明| -|---|---| -|data|指定交易数量| - - -### 4.8 根据哈希查询交易 - -```http - GET /ledgers/{ledgers}/txs/search?keyword={keyword}&fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledgers**|是|所要搜索的账本范围，需要完整的账本哈希|string| -|**query**|**keyword**|是|交易哈希，签名者公钥，或者节点公钥的全部或者部分的|string| -|**query**|**start_index**|否|查询交易的起始序号，默认为0|数字| -|**query**|**count**|否|查询返回交易的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/txs/search?keyword=6BLt -``` - - -#### 返回 - -```json -{ - "data": { - "txs": [ - { - "hash": "6L3ehswCmC1jqBfvGJP9vaPx8qxkLsieu2aRgYepmkiw3" - } - ] - }, - "success": true -} -``` - -## 5 用户 - -### 5.1 获取用户总数 - -```http -GET /ledgers/{ledger}/users/count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/users/count -``` - -#### 返回实例 - -```json -{ - "data": 4, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|用户总数| - - -### 5.2 获取用户列表 - -```http -GET /ledgers/{ledger}/users?fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|query|start_index|否|查询用户的起始序号，默认为0|数字| -|query|count|否|查询返回用户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/users?fromIndex=0&count=-1 -``` - -#### 返回实例 - -```json -{ - "data":[{ - "address": { - "value": "5SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522" - }, - "pubKey": { - "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS" - }, - "rootHash": { - "value": "5SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522" - } - }], - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|用户地址| -|pubKey.value|用户公钥| - - -### 5.3 获取用户详细信息 - -```http -GET /ledgers/{ledger}/users/address/{address} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|address|是|用户地址|字符串 - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/users/address/55SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522 -``` - -#### 返回实例 - -```json -{ - "data": { - "address": { - "value": "5SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522" - }, - "pubKey": { - "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS" - }, - "rootHash": { - "value": "5SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522" - } - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|用户地址| -|pubKey.value|用户公钥| -|rootHash.value|用户根Hash| - - -### 5.4 用户查询数量 - -```http - GET /ledgers/{ledger}/users/count/search?keyword={keyword} -``` - -#### 说明 - -用户有公钥和地址两个属性，可以通过公钥或者地址查找特定用户数量，也可以返回全部用户的数量 - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本，需要完整的账本哈希|string| -|**query**|**keyword**|是| 用户的公钥或者地址的全部或者部分|string| -|**query**|**start_index**|否|查询用户的起始序号，默认为0|数字| -|**query**|**count**|否|查询返回用户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/users/count/search?keyword=5Sm -``` - -#### 返回实例 - -```json -{ - "data": 4, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|用户数量| - -### 5.5 用户查询 - -```http - GET /ledgers/{ledger}/users/search?keyword={keyword}&fromIndex={start_index}&count={count} -``` - -#### 说明 - -用户有公钥和地址两个属性，可以通过公钥或者地址查找特定用户，也可以返回全部用户的列表 - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本，需要完整的账本哈希|string| -|**query**|**keyword**|是| 用户的公钥或者地址的全部或者部分|string| -|**query**|**start_index**|否|查询用户的起始序号，默认为0|数字| -|**query**|**count**|否|查询返回用户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/users/search?keyword=5Sm&fromIndex=0&count=-1 -``` - - -#### 返回实例 - -```json -{ - "data": { - "users": [ - { - "address": { - "value": "5SmAGKgmXyj5VsVvJgHbYCJ67iTizwSkNpw1" - }, - "pubKey": { - "value": "mb97eG4bba2EjrgjXYiD9chAstjg4HaNuV5xgCtSHc5TeB" - } - } - ] - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|用户地址| -|pubKey.value|用户公钥| -|rootHash.value|用户根Hash| - -## 6 数据账户 - -### 6.1 获取账户列表 - -```http -GET /ledgers/{ledger}/accounts?fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|query|start_index|否|查询数据账户的起始序号，默认为0|数字| -|query|count|否|查询返回数据账户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts?fromIndex=0&count=-1 -``` - -#### 返回实例 - -```json -{ - "data":[{ - "address": { - "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa" - }, - "rootHash": { - "value": "6GiAH2PBRLnoE724ia83bKVijkKsNuNU5danA4AAi5qMM" - }, - "pubKey": { - "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs" - } - }], - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|账户地址| -|pubKey.value|账户公钥| -|rootHash.value|默克尔树根哈希| - - -### 6.2 获取账户详细信息 - -```http -GET /ledgers/{ledger}/accounts/address/{address} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|address|是|账户地址|字符串 - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/address/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa -``` - -#### 返回实例 - -```json -{ - "data": { - "address": { - "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa" - }, - "rootHash": { - "value": "6GiAH2PBRLnoE724ia83bKVijkKsNuNU5danA4AAi5qMM" - }, - "pubKey": { - "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs" - } - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|账户地址| -|pubKey.value|账户公钥| -|rootHash.value|默克尔树根哈希| - - -### 6.3 获取账户总数 - -```http -GET /ledgers/{ledger}/accounts/count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/count -``` - -#### 返回实例 - -```json -{ - "data": 18, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|账户数量| - - -### 6.4 查询数据账户匹配的数量 - -```http -GET /ledgers/{ledger}/accounts/count/search?keyword={keyword} -``` - -#### 说明 - -通过账户的公钥和地址的全部或者部分查询特定账户的总数量，也可以通过KV值的Key来查询含有该Key的账户的总数量 - - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本，需要完整的账本哈希|字符串 -|**query**|**keyword**|是|数据账户的公钥或者地址的全部或者部分，或者是KV值的key|字符串 - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/count/search?keyword=jd -``` - -#### 返回实例 - -```json -{ - "data": 2, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|账户数量| - - -### 6.5 查询数据账户 - -```http - GET /ledgers/{ledger}/accounts/search?keyword={keyword}&fromIndex={start_index}&count={count} -``` - -#### 说明 - -通过账户的公钥和地址的全部或者部分查询特定账户，也可以通过KV值的Key来查询含有该Key的账户 - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本，需要完整的账本哈希|string| -|**query**|**keyword**|是| 数据账户的公钥或者地址的全部或者部分，或者是KV值的key|string| -|**query**|**start_index**|否|查询数据账户的起始序号，默认为0|数字| -|**query**|**count**|否|查询返回数据账户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/search?keyword=5Sm5V&fromIndex=0&count=-1 -``` - - -#### 返回实例 - -```json -{ - "data": { - "accounts": [ - { - "address": { - "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa" - }, - "pubKey": { - "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs" - } - } - ] - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|账户地址| -|pubKey.value|账户公钥| -|rootHash.value|数据账户根Hash| - - -### 6.6 获取某数据账户KV总数 - -```http - GET /ledgers/{ledger}/accounts/address/{address}/entries/count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|address|是|账户地址|字符串 - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/address/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa/entries/count -``` - -#### 返回实例 - -```json -{ - "data": 66, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|KV总数| - - -### 6.7 获取某数据账户KV详情 - -```http - GET/POST /ledgers/{ledger}/accounts/address/{address}/entries?fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|address|是|账户地址|字符串 -|form|keys|是|key详细内容列表|字符串 -|query|start_index|否|查询数据账户对应KV的起始序号，默认为0|数字| -|query|count|否|查询返回数据账户对应KV的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -> keys说明： - 1）keys使用表单方式提交，且keys为需要查询Key的列表，列表中每个Key都需要为完整Key - 2）Key提交方式使用GET或POST均可 - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/address/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa/entries -``` - -说明：表单提交参数为keys={"jd", "jdchain"} - - -#### 返回实例 - -```json -{ - "data": [ - { - "key": "jd", - "version": 0, - "type": "TEXT", - "value": "www.jd.com" - }, - { - "key": "jdchain", - "version": 0, - "type": "TEXT", - "value": "www.blockchain.com" - }], - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|key|键| -|version|版本号| -|type|value类型| -|value|值| - - - -## 7 搜索 - -### 7.1 搜索区块链 - -```http - GET /ledgers/{ledger}/all/search?keyword={keyword}&fromIndex={start_index}&count={count} -``` - -#### 说明 - -通过关键字搜索区块数据，支持区块哈希，交易哈希，用户公钥和地址，合约公钥和地址，数据账户哈希和地址的搜索 - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本，需要完整的账本哈希|string| -|**query**|**keyword**|是|关键字|string| -|**query**|**start_index**|否|查询匹配结果的起始序号，默认为0|数字| -|**query**|**count**|否|查询匹配结果的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/all/search?keyword=5Sm5V&fromIndex=0&count=-1 -``` - -#### 返回实例 - -```json -{ - "message": "OK", - "code": 0, - "data": { - "blocks": ..., - "txs": ..., - "users": ..., - "accounts": ..., - "contracts": ..., - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|blocks|[参考](#query-blocks-result)| -|txs|[参考](#query-txs-result)| -|users|[参考](#query-users-result)| -|accounts|[参考](#query-accounts-result)| -|contracts|[参考](#query-contracts-result)| - -## 8 合约 - -### 8.1 获取合约列表 - -```http -GET /ledgers/{ledger}/contracts?fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|query|start_index|否|查询合约的起始序号，默认为0|数字| -|query|count|否|查询返回合约的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/contracts?fromIndex=0&count=-1 -``` - -#### 返回实例 - -```json -{ - "data": [{ - "address": { - "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa" - }, - "rootHash": { - "value": "6GiAH2PBRLnoE724ia83bKVijkKsNuNU5danA4AAi5qMM" - }, - "pubKey": { - "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs" - } - }], - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|账户地址| -|pubKey.value|账户公钥| -|rootHash.value|默克尔树根哈希| - - -### 8.2 获取合约详细信息 - -```http -GET /ledgers/{ledger}/contracts/address/{address} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|address|是|合约地址|字符串 - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/contracts/address/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa -``` - -#### 返回实例 - -```json -{ - "data": { - "address": { - "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa" - }, - "rootHash": { - "value": "6GiAH2PBRLnoE724ia83bKVijkKsNuNU5danA4AAi5qMM" - }, - "pubKey": { - "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs" - } - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|账户地址| -|pubKey.value|账户公钥| -|rootHash.value|默克尔树根哈希| - -### 8.3 获取合约总数 - -```http -GET /ledgers/{ledger}/contracts/count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/contracts/count -``` - -#### 返回实例 - -```json -{ - "data": 27, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|合约数量| - - -### 8.4 查询指定合约数量 - -```http -GET /ledgers/{ledger}/contracts/count/search?keyword={keyword} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本范围，需要完整的账本哈希|string| -|**query**|**keyword**|是| 合约的公钥或者地址的全部或者一部分|string| - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/contracts/count/search?keyword=5Sm2 -``` - -#### 返回实例 - -```json -{ - "data": 2, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|合约数量| - -### 8.5 合约查询 - -```http - GET /ledgers/{ledger}/contracts/search?keyword={keyword}&fromIndex={start_index}&count={count} -``` - -#### 说明 - -合约有公钥和地址两个属性，可以通过合约的这两个属性查询特定合约，也可以返回一个当前所有合约的列表 - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本范围，需要完整的账本哈希|string| -|**query**|**keyword**|是| 合约的公钥或者地址的全部或者一部分|string| -|**query**|**start_index**|否|查询合约的起始序号，默认为0|数字| -|**query**|**count**|否|查询返回合约的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/contracts/earch?keyword=5Sm2&fromIndex=0&count=-1 -``` - - -#### 返回 - -```json -{ - "data": { - "contracts": [ - { - "address": { - "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa" - }, - "rootHash": { - "value": "6GiAH2PBRLnoE724ia83bKVijkKsNuNU5danA4AAi5qMM" - }, - "pubKey": { - "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs" - } - } - ] - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|合约地址| -|pubKey.value|合约公钥| -|rootHash|合约根Hash| diff --git a/deploy/deploy-gateway/src/main/resources/docs/api_doc_cn_1.3.html b/deploy/deploy-gateway/src/main/resources/docs/api_doc_cn_1.3.html deleted file mode 100644 index 169ef8b7..00000000 --- a/deploy/deploy-gateway/src/main/resources/docs/api_doc_cn_1.3.html +++ /dev/null @@ -1,2665 +0,0 @@ - - - - - api_doc_cn_1.3 - - -

京东区块链浏览器API文档参考 V_1.3

-

1 API调用说明

-

该文档内的所有api的调用成功和失败均按照以下规则

-

1.1 成功

-
{
  "data": ...,
  "success": true
}
-

说明

-
- success 值为 true 表明api调用成功
- data 为返回的数据，具体数据类型参考具体的api说明

1.2 失败

-
{
  "error": {
    "errorCode": 5000,
    "errorMessage": "未预期的异常！ --Unsupported access ledger[6Gw3cK4uazegy4HjoaM81ck9NgYLNoKyBMb7a1TK1jt3d] !"
  },
  "success": false
}
-

说明

-
- success 值为 false 表明api调用成功
- errorCode 为异常代码
- errorMessage 为错误提示

2 账本

-

2.1 获取账本总数

-
GET /ledgers/count
-

参数

-

无

-

请求实例

-
http://localhost/ledgers/count
-

返回实例

-
{
  "data": 2,
  "success": true
}
-

说明

- - - - - - - - - - - - - -
名称说明
data账本总数
-

2.2 获取账本列表

-
GET /ledgers?fromIndex={start_index}&count={count}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
querystart_index否查询账本的起始序号，默认为0数字
querycount否查询返回账本的数量限制，默认最大限制为100，小于0或大于100均返回最大可返回结果集数字
-

请求实例

-
http://localhost/ledgers?fromIndex=0&count=-1
-

返回实例

-
{
  "data": [
    {
      "value": "657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs"
    }
  ],
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - -
名称说明
data账本哈希列表
value账户哈希
-

2.3 获取账本详细信息

-
GET /ledgers/{ledger}
-

参数

- - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs
-

返回实例

-
{
  "data": {
    "hash": {
      "value": "657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs"
    },
    "latestBlockHash": {
      "value": "67XsKWgqZTBz1NsytKGpyNWHMbMRENWcBj8PEDYQnWiDL"
    },
    "latestBlockHeight": 66
  },
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - - - - - - - - - -
名称说明
data账本信息
hash.value账本哈希
latestBlockHash.value最新区块哈希
latestBlockHeight账本高度
-

2.4 获取账本成员总数

-
GET /ledgers/{ledger}/participants/count
-

参数

- - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/participants/count
-

返回实例

-
{
  "data": 4,
  "success": true
}
-

说明

- - - - - - - - - - - - - -
名称说明
data账本成员总数
-

2.5 获取账本成员列表

-
GET /ledgers/{ledger}/participants?fromIndex={start_index}&count={count}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
querystart_index否查询成员起始序号，默认为0数字
querycount否查询成员返回数量，默认最大返回100，小于0或大于100均返回最大可返回结果集数字
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/participants?fromIndex=0&count=-1
-

返回实例

-
{
  "data": [
    {
      "address": "5SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522",
      "name": "jd.com",
      "id": 0,
      "pubKey": {
        "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS"
      }
    },
    {
      "address": "5SmA98VknTbZ1Z7fmbNPHBuN2pbD89ogy8Ha",
      "name": "at.com",
      "id": 1,
      "pubKey": {
        "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR"
      }
    },
    {
      "address": "5SmMWsqV2kbgrRMjyQFtSq1wvYuPzeRVepHG",
      "name": "bt.com",
      "id": 2,
      "pubKey": {
        "value": "mb4AtiGAH7vtPufMDuap2oca2Ww9X6KTkp59Eh5nZjXA5H"
      }
    },
    {
      "address": "5Sm5QFyvN1dVB4GHFxWhDCp8vsJbNkdx31Ds",
      "name": "xt.com",
      "id": 3,
      "pubKey": {
        "value": "mb7pGhmmjqYUhxrJJ57C1YxXr9h1AWXv8QVosETyuLhVvH"
      }
    }
  ],
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - - - - - - - - - -
名称说明
id成员唯一标识
name成员名称
address成员地址
pubKey.value成员公钥
-

3 区块

-

3.1 获取最新区块

-
GET /ledgers/{ledger}/blocks/latest
-

参数

- - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/latest
-

返回实例

-
{
  "data": {
    "ledgerHash": {
      "value": "657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs"
    },
    "previousHash": {
      "value": "6EJZnMc9464DCSU2kgi96RyngEv8YeEfVoJNhH3yZ2v5T"
    },
    "transactionSetHash": {
      "value": "6LmZtDpMM7xE8FPChACEmLj1PLhfaoVM2rEHRsrV3ohPN"
    },
    "userAccountSetHash": {
      "value": "67jx7SctrwdSczxxuYjwBocA8fER7V8qcRZUzWamSav5p"
    },
    "contractAccountSetHash": {
      "value": "67ftaBhPDez24NEB9wiiTM3SNcn1XFz5rb7boYhpbbLXN"
    },
    "adminAccountHash": {
      "value": "69KEFp9m5iFyAiyGmJ2qPcVxuT79gMChMf9JkStBZe8aa"
    },
    "dataAccountSetHash": {
      "value": "6LB9gosVWEPG3uvWXkxTcWq22mcwMHVehbiXkavFtr5fZ"
    },
    "hash": {
      "value": "67XsKWgqZTBz1NsytKGpyNWHMbMRENWcBj8PEDYQnWiDL"
    },
    "height": 66
  },
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
名称说明
hash区块哈希
ledgerHash账本哈希
previousHash前置区块哈希
transactionSetHash交易集哈希
userAccountSetHash用户集哈希
contractAccountSetHash合约集哈希
adminAccountHash管理员集哈希
dataAccountSetHash数据账户集哈希
-

3.2 根据区块哈希获取区块详细信息

-
GET /ledgers/{ledger}/blocks/hash/{block_hash}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
pathblock_hash是区块哈希字符串
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/hash/67XsKWgqZTBz1NsytKGpyNWHMbMRENWcBj8PEDYQnWiDL
-

返回实例

-

参考

-

3.3 根据区块高度获取区块详细信息

-
GET /ledgers/{ledger}/blocks/height/{block_height}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
pathblock_height是区块高度数字
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/height/66
-

返回实例

-

参考

-

3.4 根据哈希查询区块总数

-
  GET /ledgers/{ledger}/blocks/count/search?keyword={keyword}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是所要搜索的账本，需要完整的账本哈希string
querykeyword是区块哈希的全部或者一部分string
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/count/search?keyword=6D5M
-

返回实例

-
{
  "data": 26,
  "success": true
}
-

说明

- - - - - - - - - - - - - -
名称说明
data查询到的区块总数
-

3.5 根据哈希查询区块

-
  GET /ledgers/{ledger}/blocks/search?keyword={keyword}&fromIndex={start_index}&count={count}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是所要搜索的账本，需要完整的账本哈希string
querykeyword是区块哈希的全部或者一部分string
querystart_index否查询区块结果起始序号，默认为0string
querycount否查询区块结果返回数量，默认最大值为100，小于0或大于100均返回最大可返回结果集string
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/search?keyword=6D5M&fromIndex=0&count=-1
-

-

返回实例

-
{
  "data": {
    "blocks": [
      {
        "hash": "6D5MJZnybT69bXET5QdCZdLGT16rZBJEjxLkANmDuykcb"
      }
    ]
  },
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - - - - - - - - - -
名称说明
blocks查询到的区块列表
hash区块哈希值
height区块高度
txCount区块内交易数量
-

4 交易

-

4.1 获取账本交易总数

-
GET /ledgers/{ledger}/txs/count
-

参数

- - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/txs/count
-
返回实例
-
{
  "data": 688,
  "success": true
}
-

说明

- - - - - - - - - - - - - -
名称说明
data交易数量
-

4.2 根据区块高度查询区块内的交易数量

-
GET /ledgers/{ledger}/blocks/height/{block_height}/txs/additional-count
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
pathblock_height是区块高度数字
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/height/66/txs/additional-count
 
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/hash/6D5MJZnybT69bXET5QdCZdLGT16rZBJEjxLkANmDuykcb/txs/additional-count
-

返回实例

-
{
  "data": 86,
  "success": true
}
-

说明

- - - - - - - - - - - - - -
名称说明
data交易数量
-

4.3 根据区块哈希查询区块内的交易数量

-
GET /ledgers/{ledger}/blocks/hash/{block_hash}/txs/additional-count
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
pathblock_hash是区块哈希字符串
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/hash/6D5MJZnybT69bXET5QdCZdLGT16rZBJEjxLkANmDuykcb/txs/additional-count
-

返回实例

-
{
  "data": 86,
  "success": true
}
-

说明

- - - - - - - - - - - - - -
名称说明
data交易数量
-

4.4 获取指定高度的区块交易列表

-
GET /ledgers/{ledger}/blocks/height/{height}/txs?fromIndex={start_index}&count={count}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
pathheight是区块高度数字
querystart_index否查询交易的起始序号，默认为0数字
querycount否查询返回交易的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集数字
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/height/66/txs?fromIndex=0&count=-1
-

返回实例

-
{
  "data": [
    {
      "blockHeight": 1,
      "executionState": "SUCCESS",
      "transactionContent": {
        "ledgerHash": {
          "value": "657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs"
        },
        "operations": [
          {
            "userID": {
              "address": {
                "value": "5SmBgzsrnY6u9Y7DgSSkXfTkCgp83hiFin3v"
              },
              "pubKey": {
                "value": "mb5kukaqjWtXyAerfHU1JDtVwabSeBU5c3khMZbNh7R8VJ"
              }
            }
          },
          {
            "accountID": {
              "address": {
                "value": "5SmA98VknTbZ1Z7fmbNPHBuN2pbD89ogy8Ha"
              },
              "pubKey": {
                "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR"
              }
            }
          },
          {
            "contractID": {
              "address": {
                "value": "5SmA98VknTbZ1Z7fmbNPHBuN2pbD89ogy8Ha"
              },
              "pubKey": {
                "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR"
              }
            },
            "chainCode": "----------"
          },
          {
            "contractAddress": {
              "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR"
            },
            "event": "----------",
            "args": "----------"
          },
          {
            "writeSet": [{
              "key": "jdchain",
              "value": {
                "type": "TEXT",
                "value": {
                  "value": "----------"
                }
              },
              "expectedVersion": 0
            }],
            "accountAddress": {
              "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR"
            }
          }
        ],
        "hash": {
          "value": "6BLtM1agb7ERKoN5AJgZKiTjzdS7BpjgzQNYK8ZeDqotA"
        }
      },
      "endpointSignatures": [
        {
          "digest": {
            "value": "42pbfM5YKnf39Gitr4UsjTCzhhnJjwNyi8MnLFYgP4VKewTLzHitzArHEMrCt3hZYUe5ex9XvqtmiCoWpeAbdc31F"
          },
          "pubKey": {
            "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS"
          }
        }
      ],
      "nodeSignatures": [
        {
          "digest": {
            "value": "66SQ95SbDaApAJhN2NsFx5sfAQTxsWhMW26D5iPqXc1jZU9rJEhRnqT1nzt62ZAcCvsfrjEsay3MxqXYA5tWPoA2U"
          },
          "pubKey": {
            "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS"
          }
        }
      ]
    }
  ],
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
名称说明
executionState交易执行结果
transactionContent.hash交易的哈希
transactionContent.operations交易的操作列表
endpointSignatures终端签名列表
nodeSignatures节点的签名列表
-

4.5 获取指定哈希的区块的交易列表

-
GET /ledgers/{ledger}/blocks/hash/{block_hash}/txs?fromIndex={start_index}&count={count}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
pathblock_hash是区块哈希字符串
querystart_index否查询交易的起始序号，默认为0数字
querycount否查询返回交易的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集数字
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/hash/6D5MJZnybT69bXET5QdCZdLGT16rZBJEjxLkANmDuykcb/txs?fromIndex=0&count=-1
-

返回实例

-

参考

-

4.6 获取交易详细信息

-
GET /ledgers/{ledger}/txs/hash/{tx_hash}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
pathtx_hash是交易哈希字符串
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/txs/hash/6BLtM1agb7ERKoN5AJgZKiTjzdS7BpjgzQNYK8ZeDqotA
-

返回实例

-
{
  "data": {
    "blockHeight": 1,
    "executionState": "SUCCESS",
    "transactionContent": {
      "ledgerHash": {
        "value": "657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs"
      },
      "operations": [
        {
          "userID": {
            "address": {
              "value": "5SmBgzsrnY6u9Y7DgSSkXfTkCgp83hiFin3v"
            },
            "pubKey": {
              "value": "mb5kukaqjWtXyAerfHU1JDtVwabSeBU5c3khMZbNh7R8VJ"
            }
          }
        },
        {
          "accountID": {
            "address": {
              "value": "5SmA98VknTbZ1Z7fmbNPHBuN2pbD89ogy8Ha"
            },
            "pubKey": {
              "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR"
            }
          }
        },
        {
          "contractID": {
            "address": {
              "value": "5SmA98VknTbZ1Z7fmbNPHBuN2pbD89ogy8Ha"
            },
            "pubKey": {
              "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR"
            }
          },
          "chainCode": "----------"
        },
        {
          "contractAddress": {
            "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR"
          },
          "event": "----------",
          "args": "----------"
        },
        {
          "writeSet": [{
            "key": "jdchain",
            "value": {
              "type": "TEXT",
              "value": {
                "value": "----------"
              }
            },
            "expectedVersion": 0
          }],
          "accountAddress": {
            "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR"
          }
        }
      ],
      "hash": {
        "value": "6BLtM1agb7ERKoN5AJgZKiTjzdS7BpjgzQNYK8ZeDqotA"
      }
    },
    "endpointSignatures": [
      {
        "digest": {
          "value": "42pbfM5YKnf39Gitr4UsjTCzhhnJjwNyi8MnLFYgP4VKewTLzHitzArHEMrCt3hZYUe5ex9XvqtmiCoWpeAbdc31F"
        },
        "pubKey": {
          "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS"
        }
      }
    ],
    "nodeSignatures": [
      {
        "digest": {
          "value": "66SQ95SbDaApAJhN2NsFx5sfAQTxsWhMW26D5iPqXc1jZU9rJEhRnqT1nzt62ZAcCvsfrjEsay3MxqXYA5tWPoA2U"
        },
        "pubKey": {
          "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS"
        }
      }
    ]
  },
  "success": true
}
-

说明

-

参考

-

4.7 根据哈希查询交易总数

-
  GET /ledgers/{ledgers}/txs/count/search?keyword={keyword}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledgers是所要搜索的账本范围，需要完整的账本哈希string
querykeyword是交易哈希，签名者公钥，或者节点公钥的全部或者部分的string
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/txs/search?keyword=6BLt
-

返回实例

-
{
  "data": 36,
  "success": true
}
-

说明

- - - - - - - - - - - - - -
名称说明
data指定交易数量
-

4.8 根据哈希查询交易

-
  GET /ledgers/{ledgers}/txs/search?keyword={keyword}&fromIndex={start_index}&count={count}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledgers是所要搜索的账本范围，需要完整的账本哈希string
querykeyword是交易哈希，签名者公钥，或者节点公钥的全部或者部分的string
querystart_index否查询交易的起始序号，默认为0数字
querycount否查询返回交易的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集数字
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/txs/search?keyword=6BLt
-

-

返回

-
{
  "data": {
    "txs": [
      {
        "hash": "6L3ehswCmC1jqBfvGJP9vaPx8qxkLsieu2aRgYepmkiw3"
      }
    ]
  },
  "success": true
}
-

5 用户

-

5.1 获取用户总数

-
GET /ledgers/{ledger}/users/count
-

参数

- - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/users/count
-

返回实例

-
{
  "data": 4,
  "success": true
}
-

说明

- - - - - - - - - - - - - -
名称说明
data用户总数
-

5.2 获取用户列表

-
GET /ledgers/{ledger}/users?fromIndex={start_index}&count={count}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
querystart_index否查询用户的起始序号，默认为0数字
querycount否查询返回用户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集数字
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/users?fromIndex=0&count=-1
-

返回实例

-
{
  "data":[{
    "address": {
      "value": "5SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522"
    },
    "pubKey": {
      "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS"
    },
    "rootHash": {
      "value": "5SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522"
    }
  }],
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - -
名称说明
address.value用户地址
pubKey.value用户公钥
-

5.3 获取用户详细信息

-
GET /ledgers/{ledger}/users/address/{address}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
pathaddress是用户地址字符串
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/users/address/55SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522
-

返回实例

-
{
  "data": {
    "address": {
      "value": "5SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522"
    },
    "pubKey": {
      "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS"
    },
    "rootHash": {
      "value": "5SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522"
    }
  },
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - - - - - -
名称说明
address.value用户地址
pubKey.value用户公钥
rootHash.value用户根Hash
-

5.4 用户查询数量

-
  GET /ledgers/{ledger}/users/count/search?keyword={keyword}
-

说明

-

用户有公钥和地址两个属性，可以通过公钥或者地址查找特定用户数量，也可以返回全部用户的数量

-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是所要搜索的账本，需要完整的账本哈希string
querykeyword是用户的公钥或者地址的全部或者部分string
querystart_index否查询用户的起始序号，默认为0数字
querycount否查询返回用户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集数字
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/users/count/search?keyword=5Sm
-

返回实例

-
{
  "data": 4,
  "success": true
}
-

说明

- - - - - - - - - - - - - -
名称说明
data用户数量
-

5.5 用户查询

-
  GET /ledgers/{ledger}/users/search?keyword={keyword}&fromIndex={start_index}&count={count}
-

说明

-

用户有公钥和地址两个属性，可以通过公钥或者地址查找特定用户，也可以返回全部用户的列表

-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是所要搜索的账本，需要完整的账本哈希string
querykeyword是用户的公钥或者地址的全部或者部分string
querystart_index否查询用户的起始序号，默认为0数字
querycount否查询返回用户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集数字
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/users/search?keyword=5Sm&fromIndex=0&count=-1
-

-

返回实例

-
{
  "data": {
    "users": [
      {
        "address": {
          "value": "5SmAGKgmXyj5VsVvJgHbYCJ67iTizwSkNpw1"
        },
        "pubKey": {
          "value": "mb97eG4bba2EjrgjXYiD9chAstjg4HaNuV5xgCtSHc5TeB"
        },
        "rootHash": {
          "value": "5SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522"
        }
      }
    ]
  },
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - - - - - -
名称说明
address.value用户地址
pubKey.value用户公钥
rootHash.value用户根Hash
-

6 数据账户

-

6.1 获取账户列表

-
GET /ledgers/{ledger}/accounts?fromIndex={start_index}&count={count}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
querystart_index否查询数据账户的起始序号，默认为0数字
querycount否查询返回数据账户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集数字
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts?fromIndex=0&count=-1
-

返回实例

-
{
  "data":[{
    "address": {
      "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa"
    },
    "rootHash": {
      "value": "6GiAH2PBRLnoE724ia83bKVijkKsNuNU5danA4AAi5qMM"
    },
    "pubKey": {
      "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs"
    }
  }],
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - - - - - -
名称说明
address.value账户地址
pubKey.value账户公钥
rootHash.value默克尔树根哈希
-

6.2 获取账户详细信息

-
GET /ledgers/{ledger}/accounts/address/{address}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
pathaddress是账户地址字符串
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/address/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa
-

返回实例

-
{
  "data": {
    "address": {
      "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa"
    },
    "rootHash": {
      "value": "6GiAH2PBRLnoE724ia83bKVijkKsNuNU5danA4AAi5qMM"
    },
    "pubKey": {
      "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs"
    }
  },
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - - - - - -
名称说明
address.value账户地址
pubKey.value账户公钥
rootHash.value默克尔树根哈希
-

6.3 获取账户总数

-
GET /ledgers/{ledger}/accounts/count
-

参数

- - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/count
-

返回实例

-
{
  "data": 18,
  "success": true
}
-

说明

- - - - - - - - - - - - - -
名称说明
data账户数量
-

6.4 查询数据账户匹配的数量

-
GET /ledgers/{ledger}/accounts/count/search?keyword={keyword}
-

说明

-

通过账户的公钥和地址的全部或者部分查询特定账户的总数量，也可以通过KV值的Key来查询含有该Key的账户的总数量

-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是所要搜索的账本，需要完整的账本哈希字符串
querykeyword是数据账户的公钥或者地址的全部或者部分，或者是KV值的key字符串
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/count/search?keyword=jd
-

返回实例

-
{
  "data": 2,
  "success": true
}
-

说明

- - - - - - - - - - - - - -
名称说明
data账户数量
-

6.5 查询数据账户

-
  GET /ledgers/{ledger}/accounts/search?keyword={keyword}&fromIndex={start_index}&count={count}
-

说明

-

通过账户的公钥和地址的全部或者部分查询特定账户，也可以通过KV值的Key来查询含有该Key的账户

-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是所要搜索的账本，需要完整的账本哈希string
querykeyword是数据账户的公钥或者地址的全部或者部分，或者是KV值的keystring
querystart_index否查询数据账户的起始序号，默认为0数字
querycount否查询返回数据账户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集数字
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/search?keyword=5Sm5V&fromIndex=0&count=-1
-

-

返回实例

-
{
  "data": {
    "accounts": [
      {
        "address": {
          "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa"
        },
        "rootHash": {
          "value": "6GiAH2PBRLnoE724ia83bKVijkKsNuNU5danA4AAi5qMM"
        },
        "pubKey": {
          "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs"
        }
      }
    ]
  },
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - - - - - -
名称说明
address.value账户地址
pubKey.value账户公钥
rootHash.value数据账户根Hash
-

6.6 获取某数据账户KV总数

-
  GET /ledgers/{ledger}/accounts/address/{address}/entries/count
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
pathaddress是账户地址字符串
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/address/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa/entries/count
-

返回实例

-
{
  "data": 66,
  "success": true
}
-

说明

- - - - - - - - - - - - - -
名称说明
dataKV总数
-

6.7 获取某数据账户KV详情

-
  GET/POST /ledgers/{ledger}/accounts/address/{address}/entries?fromIndex={start_index}&count={count}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
pathaddress是账户地址字符串
formkeys是key详细内容列表字符串
querystart_index否查询数据账户对应KV的起始序号，默认为0数字
querycount否查询返回数据账户对应KV的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集数字
-
-

keys说明： - 1）keys使用表单方式提交，且keys为需要查询Key的列表，列表中每个Key都需要为完整Key - 2）Key提交方式使用GET或POST均可

-
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/address/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa/entries
-

说明：表单提交参数为keys={"jd", "jdchain"}

-

返回实例

-
{
  "data": [
  {
    "key": "jd",
    "version": 0,
    "type": "TEXT",
    "value": "www.jd.com"
  },
  {
    "key": "jdchain",
    "version": 0,
    "type": "TEXT",
    "value": "www.blockchain.com"
  }],
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - - - - - - - - - -
名称说明
key键
version版本号
typevalue类型
value值
-

6.8 查询某数据账户键数量

-
  GET /ledgers/{ledger}/accounts/address/{address}/keys/count/search?keyword={keyword}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是所要搜索的账本，需要完整的账本哈希string
pathaddress是所要搜索的数据账户地址，需要完整的数据账户地址string
querykeyword否键的部分字符，空表示全部string
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/address/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa/keys/count/search?keyword=j
-

返回实例

-
{
  "data": 66,
  "success": true
}
-

说明

- - - - - - - - - - - - - -
名称说明
data条件查询键总数
-

6.9 查询某数据账户键

-
  GET /ledgers/{ledger}/accounts/address/{address}/keys/search?keyword={keyword}&fromIndex={start_index}&count={count}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是所要搜索的账本，需要完整的账本哈希string
pathaddress是所要搜索的数据账户地址，需要完整的数据账户地址string
querykeyword否键的部分字符，空表示全部string
querystart_index否查询数据账户对应Key的起始序号，默认为0数字
querycount否查询返回数据账户对应Key的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集数字
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/address/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa/keys/search?keyword=j&fromIndex=0&count=-1
-

返回实例

-
{
  "data": [
  {
    "key": "jd"
  },
  {
    "key": "jdchain"
  }],
  "success": true
}
-

说明

- - - - - - - - - - - - - -
名称说明
key键
-

7 搜索

-

7.1 搜索区块链

-
  GET /ledgers/{ledger}/all/search?keyword={keyword}&fromIndex={start_index}&count={count}
-

说明

-

通过关键字搜索区块数据，支持区块哈希，交易哈希，用户公钥和地址，合约公钥和地址，数据账户哈希和地址的搜索

-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是所要搜索的账本，需要完整的账本哈希string
querykeyword是关键字string
querystart_index否查询匹配结果的起始序号，默认为0数字
querycount否查询匹配结果的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集数字
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/all/search?keyword=5Sm5V&fromIndex=0&count=-1
-

返回实例

-
{
  "message": "OK",
  "code": 0,
  "data": {
    "blocks": ...,
    "txs": ...,
    "users": ...,
    "accounts": ...,
    "contracts": ...,
  },
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
名称说明
blocks参考
txs参考
users参考
accounts参考
contracts参考
-

8 合约

-

8.1 获取合约列表

-
GET /ledgers/{ledger}/contracts?fromIndex={start_index}&count={count}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
querystart_index否查询合约的起始序号，默认为0数字
querycount否查询返回合约的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集数字
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/contracts?fromIndex=0&count=-1
-

返回实例

-
{
  "data": [{
    "address": {
      "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa"
    },
    "rootHash": {
      "value": "6GiAH2PBRLnoE724ia83bKVijkKsNuNU5danA4AAi5qMM"
    },
    "pubKey": {
      "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs"
    }
  }],
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - - - - - -
名称说明
address.value账户地址
pubKey.value账户公钥
rootHash.value默克尔树根哈希
-

8.2 获取合约详细信息

-
GET /ledgers/{ledger}/contracts/address/{address}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
pathaddress是合约地址字符串
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/contracts/address/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa
-

返回实例

-
{
  "data": {
    "address": {
      "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa"
    },
    "rootHash": {
      "value": "6GiAH2PBRLnoE724ia83bKVijkKsNuNU5danA4AAi5qMM"
    },
    "pubKey": {
      "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs"
    }
  },
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - - - - - -
名称说明
address.value账户地址
pubKey.value账户公钥
rootHash.value默克尔树根哈希
-

8.3 获取合约总数

-
GET /ledgers/{ledger}/contracts/count
-

参数

- - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是账本哈希字符串
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/contracts/count
-

返回实例

-
{
  "data": 27,
  "success": true
}
-

说明

- - - - - - - - - - - - - -
名称说明
data合约数量
-

8.4 查询指定合约数量

-
GET /ledgers/{ledger}/contracts/count/search?keyword={keyword}
-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是所要搜索的账本范围，需要完整的账本哈希string
querykeyword是合约的公钥或者地址的全部或者一部分string
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/contracts/count/search?keyword=5Sm2
-

返回实例

-
{
  "data": 2,
  "success": true
}
-

说明

- - - - - - - - - - - - - -
名称说明
data合约数量
-

8.5 合约查询

-
  GET /ledgers/{ledger}/contracts/search?keyword={keyword}&fromIndex={start_index}&count={count}
-

说明

-

合约有公钥和地址两个属性，可以通过合约的这两个属性查询特定合约，也可以返回一个当前所有合约的列表

-

参数

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
请求类型名称是否必需说明数据类型
pathledger是所要搜索的账本范围，需要完整的账本哈希string
querykeyword是合约的公钥或者地址的全部或者一部分string
querystart_index否查询合约的起始序号，默认为0数字
querycount否查询返回合约的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集数字
-

请求实例

-
http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/contracts/earch?keyword=5Sm2&fromIndex=0&count=-1
-

-

返回

-
{
  "data": {
    "contracts": [
      {
        "address": {
          "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa"
        },
        "rootHash": {
          "value": "6GiAH2PBRLnoE724ia83bKVijkKsNuNU5danA4AAi5qMM"
        },
        "pubKey": {
          "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs"
        }
      }
    ]
  },
  "success": true
}
-

说明

- - - - - - - - - - - - - - - - - - - - - -
名称说明
address.value合约地址
pubKey.value合约公钥
rootHash合约根Hash
- diff --git a/deploy/deploy-gateway/src/main/resources/docs/api_doc_cn_1.4.MD b/deploy/deploy-gateway/src/main/resources/docs/api_doc_cn_1.4.MD deleted file mode 100644 index 06fd228a..00000000 --- a/deploy/deploy-gateway/src/main/resources/docs/api_doc_cn_1.4.MD +++ /dev/null @@ -1,2619 +0,0 @@ -# 京东区块链浏览器API文档参考 V_1.4 - -## 1 API调用说明 - -该文档内的所有api的调用成功和失败均按照以下规则 - -### 1.1 成功 - -```json -{ - "data": ..., - "success": true -} -``` - -说明 - - - success 值为 true 表明api调用成功 - - data 为返回的数据，具体数据类型参考具体的api说明 - -### 1.2 失败 - -```json -{ - "error": { - "errorCode": 5000, - "errorMessage": "未预期的异常！ --Unsupported access ledger[6Gw3cK4uazegy4HjoaM81ck9NgYLNoKyBMb7a1TK1jt3d] !" - }, - "success": false -} -``` - -说明 - - - success 值为 false 表明api调用成功 - - errorCode 为异常代码 - - errorMessage 为错误提示 - -## 2 账本 - -### 2.1 获取账本总数 - -```http -GET /ledgers/count -``` - -#### 参数 -无 - - -#### 请求实例 -```http -http://localhost/ledgers/count -``` - -#### 返回实例 - -```json -{ - "data": 2, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|账本总数| - - -### 2.2 获取账本列表 - -```http -GET /ledgers?fromIndex={start_index}&count={count} -``` - -#### 参数 -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|query|start_index|否|查询账本的起始序号，默认为0|数字 -|query|count|否|查询返回账本的数量限制，默认最大限制为100，小于0或大于100均返回最大可返回结果集|数字 - - -#### 请求实例 -```http -http://localhost/ledgers?fromIndex=0&count=-1 -``` - -#### 返回实例 - -```json -{ - "data": [ - { - "value": "657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs" - } - ], - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|账本哈希列表| -|value|账户哈希| - -### 2.3 获取账本详细信息 - -```http -GET /ledgers/{ledger} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs -``` - -#### 返回实例 - -```json -{ - "data": { - "hash": { - "value": "657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs" - }, - "latestBlockHash": { - "value": "67XsKWgqZTBz1NsytKGpyNWHMbMRENWcBj8PEDYQnWiDL" - }, - "latestBlockHeight": 66 - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|账本信息| -|hash.value|账本哈希| -|latestBlockHash.value|最新区块哈希 -|latestBlockHeight|账本高度 - - -### 2.4 获取账本成员总数 - -```http -GET /ledgers/{ledger}/participants/count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/participants/count -``` - -#### 返回实例 - -```json -{ - "data": 4, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|账本成员总数| - - -### 2.5 获取账本成员列表 - -```http -GET /ledgers/{ledger}/participants?fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|query|start_index|否|查询成员起始序号，默认为0|数字 -|query|count|否|查询成员返回数量，默认最大返回100，小于0或大于100均返回最大可返回结果集|数字 - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/participants?fromIndex=0&count=-1 -``` - -#### 返回实例 - -```json -{ - "data": [ - { - "address": "5SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522", - "name": "jd.com", - "id": 0, - "pubKey": { - "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS" - } - }, - { - "address": "5SmA98VknTbZ1Z7fmbNPHBuN2pbD89ogy8Ha", - "name": "at.com", - "id": 1, - "pubKey": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - } - }, - { - "address": "5SmMWsqV2kbgrRMjyQFtSq1wvYuPzeRVepHG", - "name": "bt.com", - "id": 2, - "pubKey": { - "value": "mb4AtiGAH7vtPufMDuap2oca2Ww9X6KTkp59Eh5nZjXA5H" - } - }, - { - "address": "5Sm5QFyvN1dVB4GHFxWhDCp8vsJbNkdx31Ds", - "name": "xt.com", - "id": 3, - "pubKey": { - "value": "mb7pGhmmjqYUhxrJJ57C1YxXr9h1AWXv8QVosETyuLhVvH" - } - } - ], - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|id|成员唯一标识| -|name|成员名称| -|address|成员地址| -|pubKey.value|成员公钥| - - - -### 2.6 获取账本元数据信息 - -```http -GET /ledgers/{ledger}/metadata -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/metadata -``` - -#### 返回实例 - -```json -{ - "data": { - "participantsHash": { - "value": "j5hQErg4epzNh38FR3EABx8YJqPkLYZoY828giAyKpCXMd" - }, - "seed": "ky3+I/4jIy8oPzL63TKqdoMiyi9WI2zacTazIssyP/4=", - "setting": { - "consensusProvider": "com.jd.blockchain.consensus.bftsmart.BftsmartConsensusProvider", - "cryptoSetting": { - "supportedProviders": [{ - "algorithms": [{}, {}, {}, {}, {}, {}, {}], - "name": "com.jd.blockchain.crypto.service.classic.ClassicCryptoService" - }, { - "algorithms": [{}, {}, {}], - "name": "com.jd.blockchain.crypto.service.sm.SMCryptoService" - }], - "autoVerifyHash": true, - "hashAlgorithm": 8216 - }, - "consensusSetting": { - "value": "112ky33NcTKBkV..." - } - } - }, - "success": true -} - -``` - -说明 - -|名称|说明| -|---|---| -|seed|账本生成种子| -|consensusSetting|共识配置，每种共识不同，需独立解析| - - - - -### 2.7 获取账本配置信息 - -```http -GET /ledgers/{ledger}/settings -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/settings -``` - -#### 返回实例 - -```json - -{ - "data": { - "consensusProtocol": "com.jd.blockchain.consensus.bftsmart.BftsmartConsensusProvider", - "consensusSettings": { - "nodes": [{ - "address": "LdeNgXM4J1SybrdUn71KdPhwBYvJzZ6xUG5Rd", - "id": 0, - "networkAddress": { - "host": "127.0.0.1", - "port": 26000, - "secure": false - }, - "pubKey": { - "value": "7VeRMXAkf3zoqr4N2RgLZ83xAv7wurqu6Vxak1V1GHv4Kfe3" - } - }, { - "address": "LdeNwbLhiAHQCVxnXsyKLhgcmUi2fuwYd6jkh", - "id": 1, - "networkAddress": { - "host": "127.0.0.1", - "port": 26010, - "secure": false - }, - "pubKey": { - "value": "7VeRAt79WPnMQ7TsM5cfhy2ERwVLu8fXbDezfFb6bT9BgYaZ" - } - }, { - "address": "LdeNgVjFaUTzsSHySB3ZrBaLiEeZebLkkyWFP", - "id": 2, - "networkAddress": { - "host": "127.0.0.1", - "port": 26020, - "secure": false - }, - "pubKey": { - "value": "7VeR9rnFNzgECCYGF8V3G36xhF3X9rr6YzqfN8h6CojgLpEY" - } - }, { - "address": "LdeNgVAkBAAdKLD1z3Nb7n5vtGujfqWdhx8G7", - "id": 3, - "networkAddress": { - "host": "127.0.0.1", - "port": 26030, - "secure": false - }, - "pubKey": { - "value": "7VeRPkXMyHFvpPf2jayHjiLX8H7CAcTJpF9F1FARogiroSK2" - } - }], - "systemConfigs": [{ - "name": "system.bft", - "value": "true" - }, { - "name": "system.communication.defaultkeys", - "value": "true" - }, { - "name": "system.communication.inQueueSize", - "value": "500000" - }, { - "name": "system.communication.outQueueSize", - "value": "500000" - }, { - "name": "system.communication.useMACs", - "value": "1" - }, { - "name": "system.communication.useSenderThread", - "value": "true" - }, { - "name": "system.communication.useSignatures", - "value": "0" - }, { - "name": "system.debug", - "value": "0" - }, { - "name": "system.initial.view", - "value": "0,1,2,3" - }, { - "name": "system.servers.f", - "value": "1" - }, { - "name": "system.servers.num", - "value": "4" - }, { - "name": "system.shutdownhook", - "value": "true" - }, { - "name": "system.totalordermulticast.checkpoint_period", - "value": "1000" - }, { - "name": "system.totalordermulticast.checkpoint_to_disk", - "value": "false" - }, { - "name": "system.totalordermulticast.global_checkpoint_period", - "value": "120000" - }, { - "name": "system.totalordermulticast.highMark", - "value": "10000" - }, { - "name": "system.totalordermulticast.log", - "value": "true" - }, { - "name": "system.totalordermulticast.log_parallel", - "value": "false" - }, { - "name": "system.totalordermulticast.log_to_disk", - "value": "false" - }, { - "name": "system.totalordermulticast.maxbatchsize", - "value": "400" - }, { - "name": "system.totalordermulticast.nonces", - "value": "10" - }, { - "name": "system.totalordermulticast.revival_highMark", - "value": "10" - }, { - "name": "system.totalordermulticast.state_transfer", - "value": "true" - }, { - "name": "system.totalordermulticast.sync_ckp", - "value": "false" - }, { - "name": "system.totalordermulticast.sync_log", - "value": "false" - }, { - "name": "system.totalordermulticast.timeout", - "value": "2000" - }, { - "name": "system.totalordermulticast.timeout_highMark", - "value": "200" - }, { - "name": "system.totalordermulticast.verifyTimestamps", - "value": "false" - }, { - "name": "system.ttp.id", - "value": "7002" - }] - }, - "cryptoSetting": { - "autoVerifyHash": true, - "hashAlgorithm": 8216, - "supportedProviders": [{ - "algorithms": [{}, {}, {}, {}, {}, {}, {}], - "name": "com.jd.blockchain.crypto.service.classic.ClassicCryptoService" - }, { - "algorithms": [{}, {}, {}], - "name": "com.jd.blockchain.crypto.service.sm.SMCryptoService" - }] - }, - "participantNodes": [{ - "address": "LdeNgXM4J1SybrdUn71KdPhwBYvJzZ6xUG5Rd", - "id": 0, - "name": "a.com", - "pubKey": { - "value": "7VeRMXAkf3zoqr4N2RgLZ83xAv7wurqu6Vxak1V1GHv4Kfe3" - } - }, { - "address": "LdeNwbLhiAHQCVxnXsyKLhgcmUi2fuwYd6jkh", - "id": 1, - "name": "b.com", - "pubKey": { - "value": "7VeRAt79WPnMQ7TsM5cfhy2ERwVLu8fXbDezfFb6bT9BgYaZ" - } - }, { - "address": "LdeNgVjFaUTzsSHySB3ZrBaLiEeZebLkkyWFP", - "id": 2, - "name": "c.com", - "pubKey": { - "value": "7VeR9rnFNzgECCYGF8V3G36xhF3X9rr6YzqfN8h6CojgLpEY" - } - }, { - "address": "LdeNgVAkBAAdKLD1z3Nb7n5vtGujfqWdhx8G7", - "id": 3, - "name": "d.com", - "pubKey": { - "value": "7VeRPkXMyHFvpPf2jayHjiLX8H7CAcTJpF9F1FARogiroSK2" - } - }], - "participantsHash": { - "value": "j5hQErg4epzNh38FR3EABx8YJqPkLYZoY828giAyKpCXMd" - }, - "seed": "932dfe23-fe23232f-283f32fa-dd32aa76-8322ca2f-56236cda-7136b322-cb323ffe" - }, - "success": true -} - - -``` - -说明 - -|名称|说明| -|---|---| -|seed|账本种子信息| -|consensusProtocol|共识协议，以字符串方式显示| -|consensusSettings|共识配置，不同共识协议内容不同，上述示例为BFTSmart相关配置| -|cryptoSetting|密码相关配置| -|cryptoSetting.hashAlgorithm|Hash算法Code（8216代表SHA256）| -|cryptoSetting.autoVerifyHash|是否自动校验Hash| -|cryptoSetting.supportedProviders|支持的算法库| -|participantNodes|参与方列表信息| -|participantNodes.id|参与方序号| -|participantNodes.address|参与方地址| -|participantNodes.name|参与方名称| -|participantNodes.pubKey.value|参与方公钥信息| -|participantsHash.value|参与方根Hash| - - - -## 3 区块 - -### 3.1 获取最新区块 - -```http -GET /ledgers/{ledger}/blocks/latest -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/latest -``` - -#### 返回实例 - -```json -{ - "data": { - "ledgerHash": { - "value": "657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs" - }, - "previousHash": { - "value": "6EJZnMc9464DCSU2kgi96RyngEv8YeEfVoJNhH3yZ2v5T" - }, - "transactionSetHash": { - "value": "6LmZtDpMM7xE8FPChACEmLj1PLhfaoVM2rEHRsrV3ohPN" - }, - "userAccountSetHash": { - "value": "67jx7SctrwdSczxxuYjwBocA8fER7V8qcRZUzWamSav5p" - }, - "contractAccountSetHash": { - "value": "67ftaBhPDez24NEB9wiiTM3SNcn1XFz5rb7boYhpbbLXN" - }, - "adminAccountHash": { - "value": "69KEFp9m5iFyAiyGmJ2qPcVxuT79gMChMf9JkStBZe8aa" - }, - "dataAccountSetHash": { - "value": "6LB9gosVWEPG3uvWXkxTcWq22mcwMHVehbiXkavFtr5fZ" - }, - "hash": { - "value": "67XsKWgqZTBz1NsytKGpyNWHMbMRENWcBj8PEDYQnWiDL" - }, - "height": 66 - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|hash|区块哈希| -|ledgerHash|账本哈希| -|previousHash|前置区块哈希| -|transactionSetHash|交易集哈希| -|userAccountSetHash|用户集哈希| -|contractAccountSetHash|合约集哈希| -|adminAccountHash|管理员集哈希| -|dataAccountSetHash|数据账户集哈希| - -### 3.2 根据区块哈希获取区块详细信息 - -```http -GET /ledgers/{ledger}/blocks/hash/{block_hash} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串| -|path|block_hash|是|区块哈希|字符串| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/hash/67XsKWgqZTBz1NsytKGpyNWHMbMRENWcBj8PEDYQnWiDL -``` - -#### 返回实例 - -[参考](#block-detail) - - -### 3.3 根据区块高度获取区块详细信息 - -```http -GET /ledgers/{ledger}/blocks/height/{block_height} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串| -|path|block_height|是|区块高度|数字| - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/height/66 -``` - -#### 返回实例 - -[参考](#block-detail) - - -### 3.4 根据哈希查询区块总数 - -```http - GET /ledgers/{ledger}/blocks/count/search?keyword={keyword} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本，需要完整的账本哈希|string| -|**query**|**keyword**|是| 区块哈希的全部或者一部分|string| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/count/search?keyword=6D5M -``` - -#### 返回实例 - -```json -{ - "data": 26, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|查询到的区块总数| - -### 3.5 根据哈希查询区块 - -```http - GET /ledgers/{ledger}/blocks/search?keyword={keyword}&fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本，需要完整的账本哈希|string| -|**query**|**keyword**|是| 区块哈希的全部或者一部分|string| -|**query**|**start_index**|否| 查询区块结果起始序号，默认为0|string| -|**query**|**count**|否| 查询区块结果返回数量，默认最大值为100，小于0或大于100均返回最大可返回结果集|string| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/search?keyword=6D5M&fromIndex=0&count=-1 -``` - - -#### 返回实例 - -```json -{ - "data": { - "blocks": [ - { - "hash": "6D5MJZnybT69bXET5QdCZdLGT16rZBJEjxLkANmDuykcb" - } - ] - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|blocks|查询到的区块列表| -|hash|区块哈希值| -|height|区块高度| -|txCount|区块内交易数量| - -## 4 交易 - -### 4.1 获取账本交易总数 - -```http -GET /ledgers/{ledger}/txs/count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/txs/count -``` - -##### 返回实例 - -```json -{ - "data": 688, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|交易数量| - -### 4.2 根据区块高度查询区块内的交易数量 - -```http -GET /ledgers/{ledger}/blocks/height/{block_height}/txs/additional-count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串| -|path|block_height|是|区块高度|数字| - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/height/66/txs/additional-count - -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/hash/6D5MJZnybT69bXET5QdCZdLGT16rZBJEjxLkANmDuykcb/txs/additional-count -``` - -#### 返回实例 - -```json -{ - "data": 86, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|交易数量| - - -### 4.3 根据区块哈希查询区块内的交易数量 - -```http -GET /ledgers/{ledger}/blocks/hash/{block_hash}/txs/additional-count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串| -|path|block_hash|是|区块哈希|字符串| - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/hash/6D5MJZnybT69bXET5QdCZdLGT16rZBJEjxLkANmDuykcb/txs/additional-count -``` - -#### 返回实例 - -```json -{ - "data": 86, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|交易数量| - - -### 4.4 获取指定高度的区块交易列表 - -```http -GET /ledgers/{ledger}/blocks/height/{height}/txs?fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|height|是|区块高度|数字| -|query|start_index|否|查询交易的起始序号，默认为0|数字| -|query|count|否|查询返回交易的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/height/66/txs?fromIndex=0&count=-1 -``` - -#### 返回实例 - -```json -{ - "data": [ - { - "blockHeight": 1, - "executionState": "SUCCESS", - "transactionContent": { - "ledgerHash": { - "value": "657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs" - }, - "operations": [ - { - "userID": { - "address": { - "value": "5SmBgzsrnY6u9Y7DgSSkXfTkCgp83hiFin3v" - }, - "pubKey": { - "value": "mb5kukaqjWtXyAerfHU1JDtVwabSeBU5c3khMZbNh7R8VJ" - } - } - }, - { - "accountID": { - "address": { - "value": "5SmA98VknTbZ1Z7fmbNPHBuN2pbD89ogy8Ha" - }, - "pubKey": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - } - } - }, - { - "contractID": { - "address": { - "value": "5SmA98VknTbZ1Z7fmbNPHBuN2pbD89ogy8Ha" - }, - "pubKey": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - } - }, - "chainCode": "----------" - }, - { - "contractAddress": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - }, - "event": "----------", - "args": "----------" - }, - { - "writeSet": [{ - "key": "jdchain", - "value": { - "type": "TEXT", - "value": { - "value": "----------" - } - }, - "expectedVersion": 0 - }], - "accountAddress": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - } - } - ], - "hash": { - "value": "6BLtM1agb7ERKoN5AJgZKiTjzdS7BpjgzQNYK8ZeDqotA" - } - }, - "endpointSignatures": [ - { - "digest": { - "value": "42pbfM5YKnf39Gitr4UsjTCzhhnJjwNyi8MnLFYgP4VKewTLzHitzArHEMrCt3hZYUe5ex9XvqtmiCoWpeAbdc31F" - }, - "pubKey": { - "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS" - } - } - ], - "nodeSignatures": [ - { - "digest": { - "value": "66SQ95SbDaApAJhN2NsFx5sfAQTxsWhMW26D5iPqXc1jZU9rJEhRnqT1nzt62ZAcCvsfrjEsay3MxqXYA5tWPoA2U" - }, - "pubKey": { - "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS" - } - } - ] - } - ], - "success": true -} -``` - - -说明 - -|名称|说明| -|---|---| -|executionState|交易执行结果| -|transactionContent.hash|交易的哈希| -|transactionContent.operations|交易的操作列表| -|endpointSignatures|终端签名列表| -|nodeSignatures|节点的签名列表| - -### 4.5 获取指定哈希的区块的交易列表 - -```http -GET /ledgers/{ledger}/blocks/hash/{block_hash}/txs?fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|block_hash|是|区块哈希|字符串| -|query|start_index|否|查询交易的起始序号，默认为0|数字| -|query|count|否|查询返回交易的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/blocks/hash/6D5MJZnybT69bXET5QdCZdLGT16rZBJEjxLkANmDuykcb/txs?fromIndex=0&count=-1 -``` - -#### 返回实例 - -[参考](#tx-list) - - -### 4.6 获取交易详细信息 - -```http -GET /ledgers/{ledger}/txs/hash/{tx_hash} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|tx_hash|是|交易哈希|字符串| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/txs/hash/6BLtM1agb7ERKoN5AJgZKiTjzdS7BpjgzQNYK8ZeDqotA -``` - -#### 返回实例 - -```json -{ - "data": { - "blockHeight": 1, - "executionState": "SUCCESS", - "transactionContent": { - "ledgerHash": { - "value": "657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs" - }, - "operations": [ - { - "userID": { - "address": { - "value": "5SmBgzsrnY6u9Y7DgSSkXfTkCgp83hiFin3v" - }, - "pubKey": { - "value": "mb5kukaqjWtXyAerfHU1JDtVwabSeBU5c3khMZbNh7R8VJ" - } - } - }, - { - "accountID": { - "address": { - "value": "5SmA98VknTbZ1Z7fmbNPHBuN2pbD89ogy8Ha" - }, - "pubKey": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - } - } - }, - { - "contractID": { - "address": { - "value": "5SmA98VknTbZ1Z7fmbNPHBuN2pbD89ogy8Ha" - }, - "pubKey": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - } - }, - "chainCode": "----------" - }, - { - "contractAddress": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - }, - "event": "----------", - "args": "----------" - }, - { - "writeSet": [{ - "key": "jdchain", - "value": { - "type": "TEXT", - "value": { - "value": "----------" - } - }, - "expectedVersion": 0 - }], - "accountAddress": { - "value": "mbC8hzmYBz2SsLLqwoBXAJiGeHrCnByBEvcaUZWscAiPqR" - } - } - ], - "hash": { - "value": "6BLtM1agb7ERKoN5AJgZKiTjzdS7BpjgzQNYK8ZeDqotA" - } - }, - "endpointSignatures": [ - { - "digest": { - "value": "42pbfM5YKnf39Gitr4UsjTCzhhnJjwNyi8MnLFYgP4VKewTLzHitzArHEMrCt3hZYUe5ex9XvqtmiCoWpeAbdc31F" - }, - "pubKey": { - "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS" - } - } - ], - "nodeSignatures": [ - { - "digest": { - "value": "66SQ95SbDaApAJhN2NsFx5sfAQTxsWhMW26D5iPqXc1jZU9rJEhRnqT1nzt62ZAcCvsfrjEsay3MxqXYA5tWPoA2U" - }, - "pubKey": { - "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS" - } - } - ] - }, - "success": true -} -``` - -说明 - -[参考](#tx-keyword) - - -### 4.7 根据哈希查询交易总数 - -```http - GET /ledgers/{ledgers}/txs/count/search?keyword={keyword} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledgers**|是|所要搜索的账本范围，需要完整的账本哈希|string| -|**query**|**keyword**|是|交易哈希，签名者公钥，或者节点公钥的全部或者部分的|string| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/txs/search?keyword=6BLt -``` - -#### 返回实例 - -```json -{ - "data": 36, - "success": true -} -``` - - -说明 - -|名称|说明| -|---|---| -|data|指定交易数量| - - -### 4.8 根据哈希查询交易 - -```http - GET /ledgers/{ledgers}/txs/search?keyword={keyword}&fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledgers**|是|所要搜索的账本范围，需要完整的账本哈希|string| -|**query**|**keyword**|是|交易哈希，签名者公钥，或者节点公钥的全部或者部分的|string| -|**query**|**start_index**|否|查询交易的起始序号，默认为0|数字| -|**query**|**count**|否|查询返回交易的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/txs/search?keyword=6BLt -``` - - -#### 返回 - -```json -{ - "data": { - "txs": [ - { - "hash": "6L3ehswCmC1jqBfvGJP9vaPx8qxkLsieu2aRgYepmkiw3" - } - ] - }, - "success": true -} -``` - -## 5 用户 - -### 5.1 获取用户总数 - -```http -GET /ledgers/{ledger}/users/count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/users/count -``` - -#### 返回实例 - -```json -{ - "data": 4, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|用户总数| - - -### 5.2 获取用户列表 - -```http -GET /ledgers/{ledger}/users?fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|query|start_index|否|查询用户的起始序号，默认为0|数字| -|query|count|否|查询返回用户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/users?fromIndex=0&count=-1 -``` - -#### 返回实例 - -```json -{ - "data":[{ - "address": { - "value": "5SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522" - }, - "pubKey": { - "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS" - }, - "rootHash": { - "value": "5SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522" - } - }], - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|用户地址| -|pubKey.value|用户公钥| - - -### 5.3 获取用户详细信息 - -```http -GET /ledgers/{ledger}/users/address/{address} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|address|是|用户地址|字符串 - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/users/address/55SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522 -``` - -#### 返回实例 - -```json -{ - "data": { - "address": { - "value": "5SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522" - }, - "pubKey": { - "value": "mb5kbwzACnhK9P1dVxgMPB2ySJLFyJKQbHpH7T9oRK3LpS" - }, - "rootHash": { - "value": "5SmFzgFtHtpbJwMCsmWTwjNGTk6SeMKU1522" - } - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|用户地址| -|pubKey.value|用户公钥| -|rootHash.value|用户根Hash| - - -### 5.4 用户查询数量 - -```http - GET /ledgers/{ledger}/users/count/search?keyword={keyword} -``` - -#### 说明 - -用户有公钥和地址两个属性，可以通过公钥或者地址查找特定用户数量，也可以返回全部用户的数量 - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本，需要完整的账本哈希|string| -|**query**|**keyword**|是| 用户的公钥或者地址的全部或者部分|string| -|**query**|**start_index**|否|查询用户的起始序号，默认为0|数字| -|**query**|**count**|否|查询返回用户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/users/count/search?keyword=5Sm -``` - -#### 返回实例 - -```json -{ - "data": 4, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|用户数量| - -### 5.5 用户查询 - -```http - GET /ledgers/{ledger}/users/search?keyword={keyword}&fromIndex={start_index}&count={count} -``` - -#### 说明 - -用户有公钥和地址两个属性，可以通过公钥或者地址查找特定用户，也可以返回全部用户的列表 - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本，需要完整的账本哈希|string| -|**query**|**keyword**|是| 用户的公钥或者地址的全部或者部分|string| -|**query**|**start_index**|否|查询用户的起始序号，默认为0|数字| -|**query**|**count**|否|查询返回用户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/users/search?keyword=5Sm&fromIndex=0&count=-1 -``` - - -#### 返回实例 - -```json -{ - "data": { - "users": [ - { - "address": { - "value": "5SmAGKgmXyj5VsVvJgHbYCJ67iTizwSkNpw1" - }, - "pubKey": { - "value": "mb97eG4bba2EjrgjXYiD9chAstjg4HaNuV5xgCtSHc5TeB" - } - } - ] - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|用户地址| -|pubKey.value|用户公钥| -|rootHash.value|用户根Hash| - -## 6 数据账户 - -### 6.1 获取账户列表 - -```http -GET /ledgers/{ledger}/accounts?fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|query|start_index|否|查询数据账户的起始序号，默认为0|数字| -|query|count|否|查询返回数据账户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts?fromIndex=0&count=-1 -``` - -#### 返回实例 - -```json -{ - "data":[{ - "address": { - "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa" - }, - "rootHash": { - "value": "6GiAH2PBRLnoE724ia83bKVijkKsNuNU5danA4AAi5qMM" - }, - "pubKey": { - "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs" - } - }], - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|账户地址| -|pubKey.value|账户公钥| -|rootHash.value|默克尔树根哈希| - - -### 6.2 获取账户详细信息 - -```http -GET /ledgers/{ledger}/accounts/address/{address} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|address|是|账户地址|字符串 - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/address/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa -``` - -#### 返回实例 - -```json -{ - "data": { - "address": { - "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa" - }, - "rootHash": { - "value": "6GiAH2PBRLnoE724ia83bKVijkKsNuNU5danA4AAi5qMM" - }, - "pubKey": { - "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs" - } - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|账户地址| -|pubKey.value|账户公钥| -|rootHash.value|默克尔树根哈希| - - -### 6.3 获取账户总数 - -```http -GET /ledgers/{ledger}/accounts/count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/count -``` - -#### 返回实例 - -```json -{ - "data": 18, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|账户数量| - - -### 6.4 查询数据账户匹配的数量 - -```http -GET /ledgers/{ledger}/accounts/count/search?keyword={keyword} -``` - -#### 说明 - -通过账户的公钥和地址的全部或者部分查询特定账户的总数量，也可以通过KV值的Key来查询含有该Key的账户的总数量 - - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本，需要完整的账本哈希|字符串 -|**query**|**keyword**|是|数据账户的公钥或者地址的全部或者部分，或者是KV值的key|字符串 - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/count/search?keyword=jd -``` - -#### 返回实例 - -```json -{ - "data": 2, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|账户数量| - - -### 6.5 查询数据账户 - -```http - GET /ledgers/{ledger}/accounts/search?keyword={keyword}&fromIndex={start_index}&count={count} -``` - -#### 说明 - -通过账户的公钥和地址的全部或者部分查询特定账户，也可以通过KV值的Key来查询含有该Key的账户 - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本，需要完整的账本哈希|string| -|**query**|**keyword**|是| 数据账户的公钥或者地址的全部或者部分，或者是KV值的key|string| -|**query**|**start_index**|否|查询数据账户的起始序号，默认为0|数字| -|**query**|**count**|否|查询返回数据账户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/search?keyword=5Sm5V&fromIndex=0&count=-1 -``` - - -#### 返回实例 - -```json -{ - "data": { - "accounts": [ - { - "address": { - "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa" - }, - "pubKey": { - "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs" - } - } - ] - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|账户地址| -|pubKey.value|账户公钥| -|rootHash.value|数据账户根Hash| - - -### 6.6 获取某数据账户KV总数 - -```http - GET /ledgers/{ledger}/accounts/address/{address}/entries/count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|address|是|账户地址|字符串 - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/address/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa/entries/count -``` - -#### 返回实例 - -```json -{ - "data": 66, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|KV总数| - - -### 6.7 获取某数据账户KV详情 - -```http - GET/POST /ledgers/{ledger}/accounts/address/{address}/entries?fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|address|是|账户地址|字符串 -|form|keys|是|key详细内容列表|字符串 -|query|start_index|否|查询数据账户对应KV的起始序号，默认为0|数字| -|query|count|否|查询返回数据账户对应KV的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -> keys说明： - 1）keys使用表单方式提交，且keys为需要查询Key的列表，列表中每个Key都需要为完整Key - 2）Key提交方式使用GET或POST均可 - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/address/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa/entries -``` - -说明：表单提交参数为keys={"jd", "jdchain"} - - -#### 返回实例 - -```json -{ - "data": [ - { - "key": "jd", - "version": 0, - "type": "TEXT", - "value": "www.jd.com" - }, - { - "key": "jdchain", - "version": 0, - "type": "TEXT", - "value": "www.blockchain.com" - }], - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|key|键| -|version|版本号| -|type|value类型| -|value|值| - - - - -### 6.8 获取某数据账户KV整个历史详情 - -```http - GET/POST /ledgers/{ledger}/accounts/{address}/entries-version -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|address|是|账户地址|字符串 -|form|KVInfoVO|是|Key相关信息|对象 - -KVInfoVO对应格式如下： - -```json - -{ - "data": [{ - "key": "zhangsan", - "version": [0, 1, 2] - }, { - "key": "lisi", - "version": [0, 1] - }] -} - -``` - -KVInfoVO说明： - + 1）支持多个Key作为入参； - - + 2）每个Key支持多个version； - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa/entries-version -``` - - -#### 返回实例 - -```json -{ - "data": [ - { - "key": "jd", - "version": 0, - "type": "TEXT", - "value": "www.jd.com" - }, - { - "key": "jdchain", - "version": 0, - "type": "TEXT", - "value": "www.blockchain.com" - }], - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|key|键| -|version|版本号| -|type|value类型| -|value|值| - -### 6.9 查询某数据账户键数量 -``` -GET /ledgers/{ledger}/accounts/address/{address}/keys/count/search?keyword={keyword} -``` -#### 参数 -请求类型 | 名称 | 是否必需 | 说明 | 数据类型 ---- | --- | --- | --- | --- -path | ledger | 是 | 所要搜索的账本，需要完整的账本哈希 | string -path | address | 是 | 所要搜索的数据账户地址，需要完整的数据账户地址 | string -query | keyword | 否 | 键的部分字符，空表示全部 | string - -#### 请求实例 -``` -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/address/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa/keys/count/search?keyword=j -``` -#### 返回实例 -``` -{ "data": 66, "success": true } -``` -说明 - -名称 | 说明 ---- | --- -data | 条件查询键总数 - -### 6.10 查询某数据账户键 -``` -GET /ledgers/{ledger}/accounts/address/{address}/keys/search?keyword={keyword}&fromIndex={start_index}&count={count} -``` -#### 参数 -请求类型 | 名称 | 是否必需 | 说明 | 数据类型 ---- | --- | --- | --- | --- -path | ledger | 是 | 所要搜索的账本，需要完整的账本哈希 | string -path | address | 是 | 所要搜索的数据账户地址，需要完整的数据账户地址 | string -query | keyword | 否 | 键的部分字符，空表示全部 | string -query | start_index | 否 | 查询数据账户对应Key的起始序号，默认为0 | 数字 -query | count | 否 | 查询返回数据账户对应Key的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集 | 数字 - -#### 请求实例 -``` -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/accounts/address/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa/keys/search?keyword=j&fromIndex=0&count=-1 -``` -#### 返回实例 -``` -{ "data": [ { "key": "jd" }, { "key": "jdchain" }], "success": true } -``` -说明 - -名称 | 说明 ---- | --- -key | 键 - -## 7 搜索 - -### 7.1 搜索区块链 - -```http - GET /ledgers/{ledger}/all/search?keyword={keyword}&fromIndex={start_index}&count={count} -``` - -#### 说明 - -通过关键字搜索区块数据，支持区块哈希，交易哈希，用户公钥和地址，合约公钥和地址，数据账户哈希和地址的搜索 - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本，需要完整的账本哈希|string| -|**query**|**keyword**|是|关键字|string| -|**query**|**start_index**|否|查询匹配结果的起始序号，默认为0|数字| -|**query**|**count**|否|查询匹配结果的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/all/search?keyword=5Sm5V&fromIndex=0&count=-1 -``` - -#### 返回实例 - -```json -{ - "message": "OK", - "code": 0, - "data": { - "blocks": ..., - "txs": ..., - "users": ..., - "accounts": ..., - "contracts": ..., - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|blocks|[参考](#query-blocks-result)| -|txs|[参考](#query-txs-result)| -|users|[参考](#query-users-result)| -|accounts|[参考](#query-accounts-result)| -|contracts|[参考](#query-contracts-result)| - -## 8 合约 - -### 8.1 获取合约列表 - -```http -GET /ledgers/{ledger}/contracts?fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|query|start_index|否|查询合约的起始序号，默认为0|数字| -|query|count|否|查询返回合约的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/contracts?fromIndex=0&count=-1 -``` - -#### 返回实例 - -```json -{ - "data": [{ - "address": { - "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa" - }, - "rootHash": { - "value": "6GiAH2PBRLnoE724ia83bKVijkKsNuNU5danA4AAi5qMM" - }, - "pubKey": { - "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs" - } - }], - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|账户地址| -|pubKey.value|账户公钥| -|rootHash.value|默克尔树根哈希| - - -### 8.2 获取合约详细信息 - -```http -GET /ledgers/{ledger}/contracts/address/{address} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 -|path|address|是|合约地址|字符串 - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/contracts/address/5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa -``` - -#### 返回实例 - -```json -{ - "data": { - "address": { - "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa" - }, - "rootHash": { - "value": "6GiAH2PBRLnoE724ia83bKVijkKsNuNU5danA4AAi5qMM" - }, - "pubKey": { - "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs" - } - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|账户地址| -|pubKey.value|账户公钥| -|rootHash.value|默克尔树根哈希| - -### 8.3 获取合约总数 - -```http -GET /ledgers/{ledger}/contracts/count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串 - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/contracts/count -``` - -#### 返回实例 - -```json -{ - "data": 27, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|合约数量| - - -### 8.4 查询指定合约数量 - -```http -GET /ledgers/{ledger}/contracts/count/search?keyword={keyword} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本范围，需要完整的账本哈希|string| -|**query**|**keyword**|是| 合约的公钥或者地址的全部或者一部分|string| - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/contracts/count/search?keyword=5Sm2 -``` - -#### 返回实例 - -```json -{ - "data": 2, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|合约数量| - -### 8.5 合约查询 - -```http - GET /ledgers/{ledger}/contracts/search?keyword={keyword}&fromIndex={start_index}&count={count} -``` - -#### 说明 - -合约有公钥和地址两个属性，可以通过合约的这两个属性查询特定合约，也可以返回一个当前所有合约的列表 - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|**path**|**ledger**|是|所要搜索的账本范围，需要完整的账本哈希|string| -|**query**|**keyword**|是| 合约的公钥或者地址的全部或者一部分|string| -|**query**|**start_index**|否|查询合约的起始序号，默认为0|数字| -|**query**|**count**|否|查询返回合约的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/contracts/earch?keyword=5Sm2&fromIndex=0&count=-1 -``` - - -#### 返回 - -```json -{ - "data": { - "contracts": [ - { - "address": { - "value": "5Sm4gWXrNpDWW9Boi4xZCzZMHboRvEDm29Fa" - }, - "rootHash": { - "value": "6GiAH2PBRLnoE724ia83bKVijkKsNuNU5danA4AAi5qMM" - }, - "pubKey": { - "value": "mavweXqvKGUAJzSxE9S15pV7c7qe9bgUn5R1HwpqmXVTUs" - } - } - ] - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|合约地址| -|pubKey.value|合约公钥| -|rootHash|合约根Hash| - -## 9 用户自定义事件 - -### 9.1 获取事件账户列表 - -```http -GET /ledgers/{ledger}/events/user/accounts?fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串| -|query|start_index|否|查询的起始序号，默认为0|数字| -|query|count|否|查询返回事件账户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/events/user/accounts?fromIndex=0&count=-1 -``` - -#### 返回实例 - -```json -{ - "data":[ - { - "address":{ - "value":"LdeP1yuk8Medq3Sph5ur9y1yE6nJ71XRVPPx1" - }, - "pubKey":{ - "value":"7VeRBi3xDfT1E11vFs9q5Q9gFo23RR7SoobPzivqxw9Uubzq" - } - } - ], - "success":true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|账户地址| -|pubKey.value|账户公钥| - -### 9.2 获取事件账户 - -```http -GET /ledgers/{ledger}/events/user/accounts/{address} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串| -|address|账户地址|是|事件账户地址|字符串| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/events/user/accounts/LdeP1yuk8Medq3Sph5ur9y1yE6nJ71XRVPPx1 -``` - -#### 返回实例 - -```json -{ - "data":[ - { - "address":{ - "value":"LdeP1yuk8Medq3Sph5ur9y1yE6nJ71XRVPPx1" - }, - "pubKey":{ - "value":"7VeRBi3xDfT1E11vFs9q5Q9gFo23RR7SoobPzivqxw9Uubzq" - } - } - ], - "success":true -} -``` - -说明 - -|名称|说明| -|---|---| -|address.value|账户地址| -|pubKey.value|账户公钥| - -### 9.3 获取事件账户总数 - -```http -GET /ledgers/{ledger}/events/user/accounts/count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/events/user/accounts/count -``` - -#### 返回实例 - -```json -{ - "data": 1, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|事件账户数量| - -### 9.4 获取事件名数量 - -```http -GET /ledgers/{ledger}/events/user/accounts/{address}/names/count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串| -|path|address|是|事件账户地址|字符串| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/events/user/accounts/LdeP1yuk8Medq3Sph5ur9y1yE6nJ71XRVPPx1/names/count -``` - -#### 返回实例 - -```json -{ - "data": 2, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|事件名数量| - -### 9.5 获取事件名列表 - -```http -GET /ledgers/{ledger}/events/user/accounts/{address}/names?fromIndex={start_index}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串| -|path|address|是|事件账户地址|字符串| -|query|start_index|否|查询的起始序号，默认为0|数字| -|query|count|否|查询返回事件账户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/events/user/accounts/LdeP1yuk8Medq3Sph5ur9y1yE6nJ71XRVPPx1/names?fromIndex=0&count=100 -``` - -#### 返回实例 - -```json -{ - "data": ["test1", "test2"], - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|事件名数量数组| - -### 9.6 获取最新事件 - -```http -GET /ledgers/{ledger}/events/user/accounts/{address}/names/{event_name}/latest -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串| -|path|address|是|事件账户地址|字符串| -|path|event_name|是|事件名|字符串| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/events/user/accounts/LdeP1yuk8Medq3Sph5ur9y1yE6nJ71XRVPPx1/names/test1/latest -``` - -#### 返回实例 - -```json -{ - "data": { - "sequence": 0, - "transactionSource": { - "value": "j5rENX3rsdEgi5toeNUUv7ycUUivjNxAUb9Fme6oLCU851" - }, - "blockHeight": 10, - "contractSource": "", - "eventAccount": { - "value": "LdeP1yuk8Medq3Sph5ur9y1yE6nJ71XRVPPx1" - }, - "name": "test1", - "content": { - "nil": false, - "bytes": { - "value": "Ctt6Eur" - }, - "type": "TEXT", - "value": "imuge" - } - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|sequence|事件序列| -|transactionSource.value|交易哈希| -|blockHeight|时间产生区块高度| -|contractSource|合约地址| -|eventAccount.value|事件账户地址| -|name|事件名| -|content.nil|事件内容是否为空| -|content.bytes.value|事件内容字节| -|content.type|事件内容类型| -|content.value|事件内容| - -### 9.7 获取事件数量 - -```http -GET /ledgers/{ledger}/events/user/accounts/{address}/names/{event_name}/count -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串| -|path|address|是|事件账户地址|字符串| -|path|event_name|是|事件名|字符串| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/events/user/accounts/LdeP1yuk8Medq3Sph5ur9y1yE6nJ71XRVPPx1/names/test1/count -``` - -#### 返回实例 - -```json -{ - "data": 1, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|事件数量| - -### 9.8 获取事件列表 - -```http -GET /ledgers/{ledger}/events/user/accounts/{address}/names/{event_name}?fromSequence={from_sequence}&count={count} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型| -|---|---|---|---|---| -|path|ledger|是|账本哈希|字符串| -|path|address|是|事件账户地址|字符串| -|path|event_name|是|事件名|字符串| -|query|from_sequence|否|查询的起始序号，默认为0|数字| -|query|count|否|查询返回事件的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| - - -#### 请求实例 -```http -http://localhost/ledgers/657TQAw6ssVoeKniWGwbovk7njvCTvikPambM9eBv6ezs/events/user/accounts/LdeP1yuk8Medq3Sph5ur9y1yE6nJ71XRVPPx1/names/test1?fromSequenct=0&count=100 -``` - -#### 返回实例 - -```json -{ - "data": [{ - "sequence": 0, - "transactionSource": { - "value": "j5rENX3rsdEgi5toeNUUv7ycUUivjNxAUb9Fme6oLCU851" - }, - "blockHeight": 10, - "contractSource": "", - "eventAccount": { - "value": "LdeP1yuk8Medq3Sph5ur9y1yE6nJ71XRVPPx1" - }, - "name": "test1", - "content": { - "nil": false, - "bytes": { - "value": "Ctt6Eur" - }, - "type": "TEXT", - "value": "imuge" - } - }], - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|data|事件列表| -|sequence|事件序列| -|transactionSource.value|交易哈希| -|blockHeight|时间产生区块高度| -|contractSource|合约地址| -|eventAccount.value|事件账户地址| -|name|事件名| -|content.nil|事件内容是否为空| -|content.bytes.value|事件内容字节| -|content.type|事件内容类型| -|content.value|事件内容| - -## 10.权限对外提供的API接口使用 -### 10.1根据角色获取权限信息 -```http -GET /ledgers/{ledgerHash}/authorization/role/{roleName} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|get|ledger|是|账本哈希|字符串 -|--|roleName|是|角色名|字符串 - - -#### 请求实例 -```http -http://localhost:11000/ledgers/j5pSJLyVpS8QG2wL95fiDWHHnweh2YdqNhgmnb64SBMjUh/authorization/role/DEFAULT -``` - -#### 返回实例 - -```json -{ - "data": { - "roleName": "DEFAULT", - "transactionPrivilege": { - "privilege": [ - "DIRECT_OPERATION", - "CONTRACT_OPERATION" - ], - "permissionCount": 2 - }, - "ledgerPrivilege": { - "privilege": [ - "CONFIGURE_ROLES", - "AUTHORIZE_USER_ROLES", - "SET_CONSENSUS", - "SET_CRYPTO", - "REGISTER_PARTICIPANT", - "REGISTER_USER", - "REGISTER_DATA_ACCOUNT", - "REGISTER_CONTRACT", - "UPGRADE_CONTRACT", - "SET_USER_ATTRIBUTES", - "WRITE_DATA_ACCOUNT", - "APPROVE_TX", - "CONSENSUS_TX", - "REGISTER_EVENT_ACCOUNT", - "WRITE_EVENT_ACCOUNT" - ], - "permissionCount": 15 - }, - "version": 0 - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|roleName|角色名称| -|transactionPrivilege|交易权限| -|transactionPrivilege -> privilege|交易权限->权限类别| -|transactionPrivilege -> permissionCount|交易权限->权限总数| -|ledgerPrivilege|账本权限| -|ledgerPrivilege -> privilege|账本权限->权限类别| -|ledgerPrivilege -> permissionCount|账本权限->权限总数| - -### 10.2根据用户获取权限信息 - -```http -GET /ledgers/{ledgerHash}/authorization/user/{userAddress} -``` - -#### 参数 - -|请求类型|名称|是否必需|说明|数据类型 -|---|---|---|---|---| -|get|ledger|是|账本哈希|字符串 -|--|userAddress|是|用户地址|字符串 - - -#### 请求实例 -```http -http://localhost:11000/ledgers/j5pSJLyVpS8QG2wL95fiDWHHnweh2YdqNhgmnb64SBMjUh/authorization/user/LdeNwH71wxtbf1UM8ExRG8qbPnu17MdnRSVva -``` - -#### 返回实例 - -```json -{ - "data": { - "userAddress": { - "value": "LdeNwH71wxtbf1UM8ExRG8qbPnu17MdnRSVva" - }, - "transactionPrivilegesBitset": { - "privilege": [ - "DIRECT_OPERATION" - ], - "permissionCount": 1 - }, - "userRole": [ - "MANAGER1", - "MANAGER0" - ], - "ledgerPrivilegesBitset": { - "privilege": [ - "CONFIGURE_ROLES", - "REGISTER_USER" - ], - "permissionCount": 2 - } - }, - "success": true -} -``` - -说明 - -|名称|说明| -|---|---| -|userRole|用户角色| -|transactionPrivilegesBitset|交易权限集| -|ledgerPrivilegesBitset|账本权限集| diff --git a/deploy/deploy-gateway/src/main/resources/docs/code_example.MD b/deploy/deploy-gateway/src/main/resources/docs/code_example.MD deleted file mode 100644 index 2f429d3f..00000000 --- a/deploy/deploy-gateway/src/main/resources/docs/code_example.MD +++ /dev/null @@ -1,361 +0,0 @@ -# 1. maven坐标 -```java - - com.jd.blockchain - sdk-client - 1.4.0.RELEASE - - - com.jd.blockchain - contract-starter - 1.4.0.RELEASE - - - com.jd.blockchain - crypto-classic - 1.4.0.RELEASE - - - - com.jd.blockchain - crypto-sm - 1.4.0.RELEASE - -``` -# 2. 数据快速上链 -## 2.1. 服务连接 - -```java - //使用已注册用户信息进行连接; - String GW_PUB_KEY = "3snxxx"; - String GW_PRIV_KEY = "177xxx"; - String GW_PASSWORD = "xxx"; - PrivKey gwPrivkey0 = KeyGenUtils.decodePrivKey(GW_PRIV_KEY, GW_PASSWORD); - PubKey gwPubKey0 = KeyGenUtils.decodePubKey(GW_PUB_KEY); - BlockchainKeypair adminKey = new BlockchainKeypair(gwPubKey0, gwPrivkey0); - //创建服务代理 - final String GATEWAY_IP = "127.0.0.1"; - final int GATEWAY_PORT = 80; - final boolean SECURE = false; - GatewayServiceFactory serviceFactory = GatewayServiceFactory.connect(GATEWAY_IP, GATEWAY_PORT, SECURE, - adminKey); - // 创建服务代理； - BlockchainService service = serviceFactory.getBlockchainService(); - HashDigest[] ledgerHashs = service.getLedgerHashs(); - // 获取当前账本Hash - HashDigest ledgerHash = ledgerHashs[0]; -``` -## 2.2. 用户注册 -```java - // 创建服务代理； - BlockchainService service = serviceFactory.getBlockchainService(); - // 在本地定义注册账号的 TX； - TransactionTemplate txTemp = service.newTransaction(ledgerHash); - BlockchainKeypair user = BlockchainKeyGenerator.getInstance().generate(); - - txTemp.users().register(user.getIdentity()); - - // TX 准备就绪； - PreparedTransaction prepTx = txTemp.prepare(); - // 使用私钥进行签名； - prepTx.sign(adminKey); - // 提交交易； - prepTx.commit(); -``` -## 2.3. 数据账户注册 -```java - // 创建服务代理； - BlockchainService service = serviceFactory.getBlockchainService(); - // 在本地定义注册账号的 TX； - TransactionTemplate txTemp = service.newTransaction(ledgerHash); - BlockchainKeypair dataAccount = BlockchainKeyGenerator.getInstance().generate(); - - txTemp.dataAccounts().register(dataAccount.getIdentity()); - - // TX 准备就绪； - PreparedTransaction prepTx = txTemp.prepare(); - // 使用私钥进行签名； - prepTx.sign(adminKey); - - // 提交交易； - prepTx.commit(); -``` -## 2.4. 写入数据 -```java - // 创建服务代理； - BlockchainService service = serviceFactory.getBlockchainService(); - - // 在本地定义注册账号的 TX； - TransactionTemplate txTemp = service.newTransaction(ledgerHash); - - // -------------------------------------- - // 将商品信息写入到指定的账户中； - // 对象将被序列化为 JSON 形式存储，并基于 JSON 结构建立查询索引； - String commodityDataAccount = "GGhhreGeasdfasfUUfehf9932lkae99ds66jf=="; - txTemp.dataAccount(commodityDataAccount).setText("ASSET_CODE", "value1", -1); - - // TX 准备就绪； - PreparedTransaction prepTx = txTemp.prepare(); - - String txHash = Base64Utils.encodeToUrlSafeString(prepTx.getHash().toBytes()); - // 使用私钥进行签名； - prepTx.sign(adminKey); - - // 提交交易； - prepTx.commit(); -``` -## 2.5. 查询数据 - -> 注：详细的查询可参考模块sdk-samples中SDK_GateWay_Query_Test_相关测试用例 - -```java - // 创建服务代理； - BlockchainService service = serviceFactory.getBlockchainService(); - - // 查询区块信息； - // 区块高度； - long ledgerNumber = service.getLedger(ledgerHash).getLatestBlockHeight(); - // 最新区块； - LedgerBlock latestBlock = service.getBlock(ledgerHash, ledgerNumber); - // 区块中的交易的数量； - long txCount = service.getTransactionCount(ledgerHash, latestBlock.getHash()); - // 获取交易列表； - LedgerTransaction[] txList = service.getTransactions(ledgerHash, ledgerNumber, 0, 100); - // 遍历交易列表 - for (LedgerTransaction ledgerTransaction : txList) { - TransactionContent txContent = ledgerTransaction.getTransactionContent(); - Operation[] operations = txContent.getOperations(); - if (operations != null && operations.length > 0) { - for (Operation operation : operations) { - operation = ClientResolveUtil.read(operation); - // 操作类型：数据账户注册操作 - if (operation instanceof DataAccountRegisterOperation) { - DataAccountRegisterOperation daro = (DataAccountRegisterOperation) operation; - BlockchainIdentity blockchainIdentity = daro.getAccountID(); - } - // 操作类型：用户注册操作 - else if (operation instanceof UserRegisterOperation) { - UserRegisterOperation uro = (UserRegisterOperation) operation; - BlockchainIdentity blockchainIdentity = uro.getUserID(); - } - // 操作类型：账本注册操作 - else if (operation instanceof LedgerInitOperation) { - - LedgerInitOperation ledgerInitOperation = (LedgerInitOperation)operation; - LedgerInitSetting ledgerInitSetting = ledgerInitOperation.getInitSetting(); - - ParticipantNode[] participantNodes = ledgerInitSetting.getConsensusParticipants(); - } - // 操作类型：合约发布操作 - else if (operation instanceof ContractCodeDeployOperation) { - ContractCodeDeployOperation ccdo = (ContractCodeDeployOperation) operation; - BlockchainIdentity blockchainIdentity = ccdo.getContractID(); - } - // 操作类型：合约执行操作 - else if (operation instanceof ContractEventSendOperation) { - ContractEventSendOperation ceso = (ContractEventSendOperation) operation; - } - // 操作类型：KV存储操作 - else if (operation instanceof DataAccountKVSetOperation) { - DataAccountKVSetOperation.KVWriteEntry[] kvWriteEntries = - ((DataAccountKVSetOperation) operation).getWriteSet(); - if (kvWriteEntries != null && kvWriteEntries.length > 0) { - for (DataAccountKVSetOperation.KVWriteEntry kvWriteEntry : kvWriteEntries) { - BytesValue bytesValue = kvWriteEntry.getValue(); - DataType dataType = bytesValue.getType(); - Object showVal = ClientResolveUtil.readValueByBytesValue(bytesValue); - System.out.println("writeSet.key=" + kvWriteEntry.getKey()); - System.out.println("writeSet.value=" + showVal); - System.out.println("writeSet.type=" + dataType); - System.out.println("writeSet.version=" + kvWriteEntry.getExpectedVersion()); - } - } - } - } - } - } - - // 根据交易的 hash 获得交易；注：客户端生成 PrepareTransaction 时得到交易hash； - HashDigest txHash = txList[0].getTransactionContent().getHash(); - Transaction tx = service.getTransactionByContentHash(ledgerHash, txHash); - // 获取数据； - String commerceAccount = "GGhhreGeasdfasfUUfehf9932lkae99ds66jf=="; - String[] objKeys = new String[] { "x001", "x002" }; - TypedKVEntry[] kvData = service.getDataEntries(ledgerHash, commerceAccount, objKeys); - - long payloadVersion = kvData[0].getVersion(); - - // 获取数据账户下所有的KV列表 - TypedKVEntry[] kvDatas = service.getDataEntries(ledgerHash, commerceAccount, 0, 100); - if (kvData != null && kvData.length > 0) { - for (TypedKVEntry kvDatum : kvDatas) { - System.out.println("kvData.key=" + kvDatum.getKey()); - System.out.println("kvData.version=" + kvDatum.getVersion()); - System.out.println("kvData.type=" + kvDatum.getType()); - System.out.println("kvData.value=" + kvDatum.getValue()); - } - } -``` - -## 2.6. 合约发布 - -```java - - // 创建服务代理； - BlockchainService service = serviceFactory.getBlockchainService(); - - // 在本地定义TX模板 - TransactionTemplate txTemp = service.newTransaction(ledgerHash); - - // 合约内容读取 - byte[] contractBytes = FileUtils.readBytes(new File("CONTRACT_FILE")); - - // 生成用户 - BlockchainKeypair contractKeyPair = BlockchainKeyGenerator.getInstance().generate(); - - // 发布合约 - txTemp.contracts().deploy(contractKeyPair.getIdentity(), contractBytes); - - // TX 准备就绪； - PreparedTransaction prepTx = txTemp.prepare(); - - // 使用私钥进行签名； - prepTx.sign(adminKey); - - // 提交交易； - TransactionResponse transactionResponse = prepTx.commit(); - - assertTrue(transactionResponse.isSuccess()); - - // 打印合约地址 - System.out.println(contractKeyPair.getIdentity().getAddress().toBase58()); -``` - -## 2.7. 合约执行 - -```java - - // 创建服务代理； - BlockchainService service = serviceFactory.getBlockchainService(); - - // 在本地定义TX模板 - TransactionTemplate txTemp = service.newTransaction(ledgerHash); - - // 合约地址 - String contractAddress = ""; - - // 使用接口方式调用合约 - TransferContract transferContract = txTemp.contract(contractAddress, TransferContract.class); - - // 使用decode方式调用合约内部方法（create方法） - // 返回GenericValueHolder可通过get方法获取结果，但get方法需要在commit调用后执行 - String address = "address"; - String account = "fill account"; - long money = 100000000L; - GenericValueHolder result = ContractReturnValue.decode(transferContract.create(address, account, money)); - - PreparedTransaction ptx = txTemp.prepare(); - - ptx.sign(adminKey); - - TransactionResponse transactionResponse = ptx.commit(); - - String cotractExecResult = result.get(); - - // TransactionResponse也提供了可供查询结果的接口 - OperationResult[] operationResults = transactionResponse.getOperationResults(); - - // 通过OperationResult获取结果 - for (int i = 0; i < operationResults.length; i++) { - OperationResult opResult = operationResults[i]; - System.out.printf("Operation[%s].result = %s \r\n", - opResult.getIndex(), BytesValueEncoding.decode(opResult.getResult())); - } -``` - -## 2.8. 事件账户注册 -```java - BlockchainService service = serviceFactory.getBlockchainService(); - TransactionTemplate txTemp = service.newTransaction(ledgerHash); - - BlockchainKeypair eventAccount = BlockchainKeyGenerator.getInstance().generate(); - txTemp.eventAccounts().register(eventAccount.getIdentity()); - - // TX 准备就绪； - PreparedTransaction prepTx = txTemp.prepare(); - // 使用私钥进行签名； - prepTx.sign(adminKey); - - // 提交交易； - prepTx.commit(); -``` -## 2.9. 事件发布 -```java - BlockchainService service = serviceFactory.getBlockchainService(); - TransactionTemplate txTemp = service.newTransaction(ledgerHash); - - // 发布事件到指定的账户中； - String eventAccount = "GGhhreGeasdfasfUUfehf9932lkae99ds66jf=="; - txTemp.eventAccount(eventAccount).publish("event_name", "string", -1) - .publish("event_name", 0, 0); - - // TX 准备就绪； - PreparedTransaction prepTx = txTemp.prepare(); - - // 使用私钥进行签名； - prepTx.sign(adminKey); - - // 提交交易； - prepTx.commit(); -``` - -## 2.10. 事件监听 - -- 系统事件 -> 目前仅支持新区块产生事件 -```java - EventListenerHandle handler = blockchainService.monitorSystemEvent(ledgerHash, - SystemEvent.NEW_BLOCK_CREATED, 0, new SystemEventListener() { - @Override - public void onEvents(Event[] eventMessages, EventContext eventContext) { - for (Event eventMessage : eventMessages) { - BytesValue content = eventMessage.getContent(); - // content中存放的是当前链上最新高度 - System.out.println(BytesUtils.toLong(content.getBytes().toBytes())); - } - - // 关闭监听的两种方式：1 - eventContext.getHandle().cancel(); - } - }); - - // 关闭监听的两种方式：2 - handler.cancel(); -``` - -- 用户自定义事件 -```java - EventListenerHandle handler = blockchainService.monitorUserEvent(ledgerHash, - eventAccount.getAddress().toBase58(), eventName, 0, new UserEventListener() { - @Override - public void onEvent(Event eventMessage, EventContext eventContext) { - BytesValue content = eventMessage.getContent(); - switch (content.getType()) { - case TEXT: - System.out.println(content.getBytes().toUTF8String()); - break; - case INT64: - System.out.println(BytesUtils.toLong(content.getBytes().toBytes())); - break; - default: - break; - } - - // 关闭监听的两种方式：1 - eventContext.getHandle().cancel(); - } - }); - - // 关闭监听的两种方式：2 - handler.cancel(); -``` \ No newline at end of file diff --git a/deploy/deploy-gateway/src/main/resources/docs/design_contract-dev-manual.md b/deploy/deploy-gateway/src/main/resources/docs/design_contract-dev-manual.md deleted file mode 100644 index 676e1e77..00000000 --- a/deploy/deploy-gateway/src/main/resources/docs/design_contract-dev-manual.md +++ /dev/null @@ -1,436 +0,0 @@ -# 智能合约开发手册 -版本|修改时间|修改人 ----|:--:|---: -V1.0|2020-04-17|huanghaiquan - ---- - - - -### 1. 简介 - - JD Chain 智能合约系统由5个部分组成：合约代码语言、合约引擎、合约账户、合约开发框架、合约开发插件。 - - 合约代码语言是用来编写智能合约的编程语言，合约引擎是解释和执行合约代码的虚拟机。 - - JD Chain 账本中以合约账户的方式对合约代码进行管理。一份部署上链的合约代码需要关联到一个唯一的公钥上，并生成与公钥对应的区块链账户地址，在账本中注册为一个合约账户。在执行之前，系统从账本中读出合约代码并将其加载到合约引擎，由交易执行器调用合约引擎触发合约执行。 - - JD Chain 账本定义了一组标准的账本操作指令，合约代码的执行过程实质上是向账本输出一串操作指令序列，这些指令对账本中的数据产生了变更，形成合约执行的最终结果。 - - 合约开发框架定义了进行合约代码开发中需要依赖的一组编程接口和类库。合约开发插件提供了更方便与IDE集成的合约编译、部署工具，可以简化操作，并与持续集成过程结合。 - - JD Chain 以 Java 语言作为合约代码语言，合约引擎是基于 JVM 构建的安全沙盒。为了实现与主流的应用开发方式无缝兼容， JD Chain 支持以 Maven 来管理合约代码的工程项目，并提供相应的 maven 插件来简化合约的编译和部署。 - - >智能合约是一种可以由计算机执行的合同/协议。不同于现实生活中的合同是由自然语言来编写并约定相关方的权利和义务，智能合约是用合约代码语言来编写，以合约代码的形式存在和被执行。通过账本中的数据状态来表示合同/协议相关条款信息，合约代码的运行过程体现了合同/协议条款的执行，并记录相应的结果。 - -### 2. 快速入门 - - #### 2.1. 准备开发环境 - - 按照正常的 Java 应用开发环境要求进行准备，以 Maven 作为代码工程的构建管理工具，无其它特殊要求。 - - >检查 JDK 版本不低于 1.8 ，Maven 版本不低于 3.0。 - - #### 2.2. 创建合约代码工程 - 创建一个普通的 Java Maven 工程，打开 pom.xml 把 packaging 设为 contract . - - ``` xml - - - 4.0.0 - your.group.id - your.project - 0.0.1-SNAPSHOT - - contract - - - - - - - - - - - - - ``` - - > 注：合约代码工程也是一个普通的 Java Maven 工程，因此尽管不同 IDE 创建 Maven 工程有不同的操作方式，由于对于合约开发而言并无特殊要求，故在此不做详述。 - - #### 2.3. 加入合约开发依赖 - - 在合约代码工程 pom.xml 加入对合约开发 SDK 的依赖： - - ``` xml - - com.jd.blockchain - contract-starter - ${jdchain.version} - - ``` - - #### 2.4. 加入合约插件 - - 在合约代码工程的 pom.xml 加入 contract-maven-plugin 插件： - ``` xml - - com.jd.blockchain - contract-maven-plugin - ${jdchain.version} - true - - ``` - - 完整的 pom.xml 如下： - - ``` xml - - - - 4.0.0 - your.group.id - your.project - 0.0.1-SNAPSHOT - - contract - - - 1.2.0.RELEASE - - - - - - com.jd.blockchain - contract-starter - ${jdchain.version} - - - - - - - org.apache.maven.plugins - maven-compiler-plugin - 3.8.1 - - 1.8 - 1.8 - UTF-8 - false - true - false - false - - - - - - com.jd.blockchain - contract-maven-plugin - ${jdchain.version} - true - - - - - - ``` - - #### 2.5. 编写合约代码 - - 2.5.1. **注意事项** - ``` - 1、不允许合约（包括合约接口和合约实现类）使用com.jd.blockchain开头的package； - 2、必须有且只有一个接口使用@Contract注解，且其中的event必须大于等于一个； - 3、使用@Contract注解的接口有且只有一个实现类； - 4、黑名单调用限制（具体黑名单可查看配置文件），需要注意的是，黑名单分析策略会递归分析类实现的接口和父类，也就是说调用一个实现了指定黑名单接口的类也是不允许的； - 目前设置的黑名单如下： - java.io.File - java.io.InputStream - java.io.OutputStream - java.io.DataInput - java.io.DataOutput - java.io.Reader - java.io.Writer - java.io.Flushable - java.nio.channels.* - java.nio.file.* - java.net.* - java.sql.* - java.lang.reflect.* - java.lang.Class - java.lang.ClassLoader - java.util.Random - java.lang.System-currentTimeMillis - java.lang.System-nanoTime - com.jd.blockchain.ledger.BlockchainKeyGenerator - ``` - - 2.5.2. **声明合约** - - ``` java - /** - * 声明合约接口； - **/ - @Contract - public interface AssetContract { - - @ContractEvent(name = "transfer") - String transfer(String address, String from, String to, long amount); - - } - ``` - - 2.5.3. **实现合约** - - ``` java - /** - * 实现合约； - * - * 实现 EventProcessingAware 接口是可选的，目的获得 ContractEventContext 上下文对象， - * 通过该对象可以进行账本操作； - */ - public class AssetContractImpl implements AssetContract, EventProcessingAware { - - // 合约事件上下文； - private ContractEventContext eventContext; - - /** - * 执行交易请求中对 AssetContract 合约的 transfer 调用操作； - */ - public String transfer(String address, String from, String to, long amount) { - //当前账本的哈希； - HashDigest ledgerHash = eventContext.getCurrentLedgerHash(); - //当前账本上下文； - LedgerContext ledgerContext = eventContext.getLedger(); - - //做操作； - // ledgerContext. - - //返回合约操作的结果； - return "success"; - } - - /** - * 准备执行交易中的合约调用操作； - */ - @Override - public void beforeEvent(ContractEventContext eventContext) { - this.eventContext = eventContext; - } - - /** - * 完成执行交易中的合约调用操作； - */ - @Override - public void postEvent(ContractEventContext eventContext, Exception error) { - this.eventContext = null; - } - } - ``` - #### 2.6. 编译打包合约代码 - - 合约代码工程的编译打包操作与普通的 maven 工程是相同的，在工程的根目录下输入以下命令： - - ``` bash - mvn clean package - ``` - - 执行成功之后，在 target 目录中输出合约代码文件 \.\.car 。 - - 如果合约代码加入了除 com.jd.blockchain:contract-starter 之外的其它依赖，默认配置下，第三方依赖包将与 .car 文件一起打包一起部署。（也可以把第三方依赖包独立打包，具体参见以下 “3. 合约插件详细配置” - - > 注意：合约代码虽然利用了 Java 语言，遵照 Java 语法进行编写，但本质上是作为一种运行于受限环境（合约虚拟机）的语言来使用，因而一些 Java 语法和 SDK 的 API 是不被允许使用的，在编译过程中将对此进行检查。 - - #### 2.7. 部署合约代码 - - ##### 2.7.1. 在项目中部署合约代码 - - 如果希望在构建打包的同时将合约代码部署到指定的区块链网络，可以在合约代码工程 pom.xml 的 contract-maven-plugin 插件配置中加入合约部署相关的信息（具体更详细的配置可以参考“3. 合约插件详细配置”）。 - - ``` xml - - com.jd.blockchain - contract-maven-plugin - 1.2.0.RELEASE - true - - - - - j5rpuGWVxSuUbU3gK7MDREfui797AjfdHzvAMiSaSzydu7 - - - - 192.168.10.10 - 8081 - - - - - 3snPdw7i7Po4fYcXFxS4QztR8Dm4kLBdBpjsemuGPZRyZRBmtn5Z5u - - - - - 7VeRLdGtSz1Y91gjLTqEdnkotzUfaAqdap3xw6fQ1yKHkvVq - 177gjzHTznYdPgWqZrH43W3yp37onm74wYXT4v9FukpCHBrhRysBBZh7Pzdo5AMRyQGJD7x - DYu3G8aGTMBW1WrTw76zxQJQU4DHLw9MLyy7peG4LKkY - - - - - ``` - - 加入部署配置信息之后，对工程执行编译打包操作，输出的合约代码（.car）将自动部署到指定的区块链网络。 - - ``` bash - mvn clean deploy - ``` - ##### 2.7.2. 发布已编译好的car - 如果已经通过插件的打包方式，编译打包完成一个合约文件（.car），可通过命令行的方式进行发布，命令行要求与开发环境一致的Maven环境（包括环境变量及Setting都已配置完成）。 - - ``` bash - mvn com.jd.blockchain:contract-maven-plugin:${version}:deploy - -DcarPath= - -Dledger= - -DgatewayHost= - -DgatewayPort= - -DcontractPubKey= - -DcontractAddress= - -DsignerPubKey= - -DsignerPrivKey= - -DsignerPrivKeyPwd= - ``` - - 各参数说明如下： - - | 参数名 | 含义 |是否必填| - | ---- | ---- | ---- | - | ${version} | 合约插件的版本号 | 否，系统会自动选择发布的最新的RELEASE版本，SNAPSHOT版本必须填写 | - | carPath | 合约文件所在路径 | 是 | - | ledger | 账本Hash（Base58编码） | 否，会自动选择线上第一个账本| - | gatewayHost | 可访问的网关节点地址，域名或IP地址 | 是| - | gatewayPort | 网关节点监听端口 | 是 | - | contractPubKey | 合约账户的公钥（Base58编码）| 否，会自动创建 | - | contractAddress | 合约账户的地址（Base58编码）|否，会根据contractPubKey生成| - | signerPubKey | 合约签名公钥信息（Base58编码）|是| - | signerPrivKey | 合约签名私钥信息（Base58编码）|是| - | signerPrivKeyPwd | 合约签名私钥解密密钥（Base58编码）|是| - - -下面是一个示例，供参考： - -``` bash - mvn com.jd.blockchain:contract-maven-plugin:1.2.0.RELEASE:deploy \ - -DcarPath=/root/jdchain/contracts/contract-test-1.0-SNAPSHOT.car \ - -Dledger=j5tW5HUvMjEtm2yB7E6MHoSByoH1DXvMwvF2HurEgMSaLW \ - -DgatewayHost=127.0.0.1 \ - -DgatewayPort=11000 \ - -DcontractPubKey= 7VeRBsHM2nsGwP8b2ufRxz36hhNtSqjKTquzoa4WVKWty5sD \ - -DcontractAddress= LdeNt7sEmTirh9PmE7axKvA2txTrbB9kxz6KB \ - -DsignerPubKey=7VeRLdGtSz1Y91gjLTqEdnkotzUfaAqdap3xw6fQ1yKHkvVq \ - -DsignerPrivKey=177gjzHTznYdPgWqZrH43W3yp37onm74wYXT4v9FukpCHBrhRysBBZh7Pzdo5AMRyQGJD7x \ - -DsignerPrivKeyPwd=DYu3G8aGTMBW1WrTw76zxQJQU4DHLw9MLyy7peG4LKkY - ``` - - - > 重点说明： - 命令行中输入参数的优先级高于配置文件，就是说通过2.7.1方式发布合约时也可以采用命令行的参数（指-D相关配置），其优先级高于配置文件。 - -### 3. 合约插件详细配置 - - ``` xml - - com.jd.blockchain - contract-maven-plugin - 1.2.0.RELEASE - true - - - - - - false - - - - - 1 - - - MB - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - ``` - -### 4. 最简化合约插件配置示例 - -在pom.xml中有部分配置是非必填项，下面是一份最简化的合约发布（deploy）配置示例，供参考： - - - ``` xml - - com.jd.blockchain - contract-maven-plugin - 1.2.0.RELEASE - true - - - - - - 127.0.0.1 - 8081 - - - - - 7VeRLdGtSz1Y91gjLTqEdnkotzUfaAqdap3xw6fQ1yKHkvVq - 177gjzHTznYdPgWqZrH43W3yp37onm74wYXT4v9FukpCHBrhRysBBZh7Pzdo5AMRyQGJD7x - DYu3G8aGTMBW1WrTw76zxQJQU4DHLw9MLyy7peG4LKkY - - - - - ``` \ No newline at end of file diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 00000000..2c6822fe --- /dev/null +++ b/docs/api.md @@ -0,0 +1,2924 @@ +# 网关API + +[账本](#2-账本) +- [获取账本总数](#21-获取账本总数) +- [获取账本列表](#22-获取账本列表) +- [获取账本详细信息](#23-获取账本详细信息) +- [获取账本参与方总数](#24-获取账本参与方总数) +- [获取账本参与方列表](#25-获取账本参与方列表) +- [获取账本元数据信息](#26-获取账本元数据信息) +- [获取账本初始化配置信息](#27-获取账本初始化配置信息) +- [获取账本管理数据信息](#28-获取账本管理数据信息) + +[区块](#3-区块) +- [获取最新区块](#31-获取最新区块) +- [根据区块哈希获取区块详细信息](#32-根据区块哈希获取区块详细信息) +- [根据区块高度获取区块详细信息](#33-根据区块高度获取区块详细信息) + +[交易](#4-交易) +- [获取账本交易总数](#41-获取账本交易总数) +- [根据区块高度查询交易数量](#42-根据区块高度查询交易数量) +- [根据区块哈希查询交易数量](#43-根据区块哈希查询交易数量) +- [根据区块高度查询区块内的交易数量](#44-根据区块高度查询区块内的交易数量) +- [根据区块哈希查询区块内的交易数量](#45-根据区块哈希查询区块内的交易数量) +- [获取指定区块高度的交易列表](#46-获取指定区块高度的交易列表) +- [获取指定哈希的区块的交易列表](#47-获取指定哈希的区块的交易列表) +- [获取交易详细信息](#48-获取交易详细信息) + +[用户](#5-用户) +- [获取用户总数](#51-获取用户总数) +- [获取用户列表](#52-获取用户列表) +- [获取用户详细信息](#53-获取用户详细信息) +- [获取指定高度的区块的用户总数](#54-获取指定高度的区块的用户总数) +- [获取指定哈希的区块的用户总数](#55-获取指定哈希的区块的用户总数) +- [根据区块高度查询区块内的用户数量](#56-根据区块高度查询区块内的用户数量) +- [根据区块哈希查询区块内的用户数量](#57-根据区块哈希查询区块内的用户数量) +- [查询最新区块新增用户数量](#58-查询最新区块新增用户数量) + +[角色权限](#6-角色权限) +- [根据角色获取权限信息](#61-根据角色获取权限信息) +- [根据用户获取权限信息](#62-根据用户获取权限信息) + +[数据账户](#7-数据账户) +- [获取账户列表](#71-获取账户列表) +- [获取账户详细信息](#72-获取账户详细信息) +- [获取账户总数](#73-获取账户总数) +- [获取指定高度的区块的数据账户总数](#74-获取指定高度的区块的数据账户总数) +- [获取指定哈希的区块的数据账户总数](#75-获取指定哈希的区块的数据账户总数) +- [根据区块高度查询区块内的数据账户数量](#76-根据区块高度查询区块内的数据账户数量) +- [根据区块哈希查询区块内的数据账户数量](#77-根据区块哈希查询区块内的数据账户数量) +- [获取某数据账户KV总数](#78-获取某数据账户KV总数) +- [获取某数据账户KV详情](#79-获取某数据账户KV详情) +- [获取某数据账户KV详情](#710-获取某数据账户KV详情) +- [获取某数据账户KV整个历史详情](#711-获取某数据账户KV整个历史详情) + +[合约](#8-合约) +- [获取合约总数](#81-获取合约总数) +- [获取指定区块高度的合约总数](#82-获取指定区块高度的合约总数) +- [获取指定区块哈希的合约总数](#83-获取指定区块哈希的合约总数) +- [根据区块高度查询区块内的合约总数](#84-根据区块高度查询区块内的合约总数) +- [根据区块哈希查询区块内的合约总数](#85-根据区块哈希查询区块内的合约总数) +- [获取合约列表](#86-获取合约列表) +- [获取合约详细信息](#87-获取合约详细信息) + +[事件](#9-用户自定义事件) + +- [获取事件账户列表](#91-获取事件账户列表) +- [获取事件账户](#92-获取事件账户) +- [获取事件账户总数](#93-获取事件账户总数) +- [获取事件名数量](#94-获取事件名数量) +- [获取事件名列表](#95-获取事件名列表) +- [获取最新事件](#96-获取最新事件) +- [获取事件数量](#97-获取事件数量) +- [获取事件列表](#98-获取事件列表) + +## 1 API调用说明 + +该文档内的所有api的调用成功和失败均按照以下规则 + +### 1.1 成功 + +```json +{ + "data": ..., + "success": true +} +``` + +说明 + + - success 值为 true 表明api调用成功 + - data 为返回的数据，具体数据类型参考具体的api说明 + +### 1.2 失败 + +```json +{ + "error": { + "errorCode": 5000, + "errorMessage": "未预期的异常！ --Unsupported access ledger[6Gw3cK4uazegy4HjoaM81ck9NgYLNoKyBMb7a1TK1jt3d] !" + }, + "success": false +} + +[comment]: <> (```) + +说明 + + - success 值为 false 表明api调用成功 + - errorCode 为异常代码 + - errorMessage 为错误提示 + +## 2 账本 + +### 2.1 获取账本总数 + +​```http +GET /ledgers/count +``` + +#### 参数 +无 + + +#### 请求实例 +```http +http://localhost:8080/ledgers/count +``` + +#### 返回实例 + +```json +{ + "data": 2, + "success": true +} +``` + +说明 + +|名称|说明| +|---|---| +|data|账本总数| + + +### 2.2 获取账本列表 + +```http +GET /ledgers +``` + +#### 参数 +无 + + +#### 请求实例 +```http +http://localhost:8080/ledgers +``` + +#### 返回实例 + +```json +{ + "data" : [ + "j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp" + ], + "success" : true +} +``` + +说明 + +|名称|说明| +|---|---| +|data|账本哈希列表| + +### 2.3 获取账本详细信息 + +```http +GET /ledgers/{ledger} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型 | +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串 | + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp +``` + +#### 返回实例 + +```json +{ + "success" : true, + "data" : { + "hash" : "j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp", + "latestBlockHeight" : 0, + "latestBlockHash" : "j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp" + } +} +``` + +说明 + +|名称|说明| +|---|---| +|data|账本信息| +|hash|账本哈希| +|latestBlockHash | 最新区块哈希 | +|latestBlockHeight| 最新账本高度 | + + +### 2.4 获取账本参与方总数 + +```http +GET /ledgers/{ledger}/participants/count +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型 | +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串 | + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/participants/count +``` + +#### 返回实例 + +```json +{ + "data": 4, + "success": true +} +``` + +说明 + +|名称|说明| +|---|---| +|data|账本参与方总数| + + +### 2.5 获取账本参与方列表 + +```http +GET /ledgers/{ledger}/participants +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型 | +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串 | + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/participants +``` + +#### 返回实例 + +```json +{ + "data" : [ + { + "pubKey" : "7VeRFF1ednwhrFoe5cngKwPUJ2N4iFKD9Jt53GxSCc1MmPQ6", + "participantNodeState" : "CONSENSUS", + "id" : 2, + "address" : { + "value" : "LdeNwsiuo7n6HULWhNKc87PBXJXAfGKFon9RE" + }, + "name" : "2" + }, + { + "participantNodeState" : "CONSENSUS", + "pubKey" : "7VeREmuT4fF9yRPEMbSSaNLKbLa3qoTpfGHRgwpnSWUn5tqW", + "id" : 1, + "name" : "1", + "address" : { + "value" : "LdeNiXZbsBCsTc2ZGp1PGBX81aUxPekhwEwmY" + } + }, + { + "pubKey" : "7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn", + "participantNodeState" : "CONSENSUS", + "address" : { + "value" : "LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw" + }, + "name" : "0", + "id" : 0 + }, + { + "id" : 3, + "address" : { + "value" : "LdeP2ji8PR1DPsLt5NoFeiBnhpckrLHgCJge6" + }, + "name" : "3", + "pubKey" : "7VeRGE4V9MR7HgAqTrkxGvJvaaKRZ3fAjHUjYzpNBGcjfAvr", + "participantNodeState" : "CONSENSUS" + } + ], + "success" : true +} +``` + +说明 + +|名称|说明| +|---|---| +|id|参与方唯一标识| +|name|参与方名称| +|address.value|参与方地址| +|pubKey|参与方公钥| +|participantNodeState|参与方状态| + +`ParticipantNodeState` 参与方状态： + +- `READY` 就绪，在此状态下，参与方的账户可以作为网关节点接入终端的交易请求 +- `CONSENSUS` 共识，在此状态下，参与方的账户可以作为共识节点参与共识，也可以作为网关节点接入终端的交易请求 +- `DEACTIVATED` 停用，在此状态下，参与方的账户既不能作为共识节点参与共识，也不能作为网关节点接入终端的交易请求 + +### 2.6 获取账本元数据信息 + +```http +GET /ledgers/{ledger}/metadata +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型 | +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串 | + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/metadata +``` + +#### 返回实例 + +```json +{ + "success" : true, + "data" : { + "participantsHash" : "j5qzkZgpGMczBDNKXRGJdyPTndkxPvB7Gdrfiqy6LvG7P5", + "userRolesHash" : "j5rggjQQtcjMTSwxFyDedcxPSxVVfjAB3khJDvgdiGFhiB", + "seed" : "NiSpjQVYRMMEA+1bnyU2eA==", + "settingsHash" : "j5iNkXJptLJrJcFL1YJpuvbJCh6H3iioBNJG7QKPESUUif", + "rolePrivilegesHash" : "j5hBCfTVv77mTyM5WHoGnw1cezgzB3QDqojqjhg5qmuECn", + "ledgerStructureVersion" : 0 + } +} +``` + +说明 + +|名称|说明| +|---|---| +|seed|账本生成种子| +|participantsHash|成员数据集哈希| +|userRolesHash|用户角色集哈希| +|settingsHash|配置数据集哈希| +|rolePrivilegesHash|角色权限数据集哈希| +|ledgerStructureVersion|账本结构版本| + + +### 2.7 获取账本初始化配置信息 + +```http +GET /ledgers/{ledger}/settings +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/settings +``` + +#### 返回实例 + +```json +{ + "data": { + "ledgerStructureVersion": 0, + "participantsHash": "j5qzkZgpGMczBDNKXRGJdyPTndkxPvB7Gdrfiqy6LvG7P5", + "seed": "3624a98d-055844c3-0403ed5b-9f253678", + "consensusProtocol": "com.jd.blockchain.consensus.bftsmart.BftsmartConsensusProvider", + "consensusSettings": { + "systemConfigs": [ + { + "name": "system.bft", + "value": "true" + }, + { + "value": "true", + "name": "system.communication.defaultkeys" + }, + { + "value": "500000", + "name": "system.communication.inQueueSize" + }, + { + "value": "500000", + "name": "system.communication.outQueueSize" + }, + { + "name": "system.communication.send.retryCount", + "value": "100" + }, + { + "name": "system.communication.send.retryInterval", + "value": "2000" + }, + { + "name": "system.communication.useMACs", + "value": "1" + }, + { + "name": "system.communication.useSenderThread", + "value": "true" + }, + { + "value": "0", + "name": "system.communication.useSignatures" + }, + { + "value": "0", + "name": "system.debug" + }, + { + "value": "0,1,2,3", + "name": "system.initial.view" + }, + { + "name": "system.servers.f", + "value": "1" + }, + { + "value": "4", + "name": "system.servers.num" + }, + { + "value": "true", + "name": "system.shutdownhook" + }, + { + "name": "system.totalordermulticast.checkpoint_period", + "value": "1000" + }, + { + "name": "system.totalordermulticast.checkpoint_to_disk", + "value": "false" + }, + { + "value": "120000", + "name": "system.totalordermulticast.global_checkpoint_period" + }, + { + "name": "system.totalordermulticast.highMark", + "value": "10000" + }, + { + "name": "system.totalordermulticast.log", + "value": "true" + }, + { + "value": "false", + "name": "system.totalordermulticast.log_parallel" + }, + { + "name": "system.totalordermulticast.log_to_disk", + "value": "true" + }, + { + "name": "system.totalordermulticast.maxbatchsize", + "value": "2000" + }, + { + "value": "10", + "name": "system.totalordermulticast.nonces" + }, + { + "value": "10", + "name": "system.totalordermulticast.revival_highMark" + }, + { + "name": "system.totalordermulticast.state_transfer", + "value": "true" + }, + { + "name": "system.totalordermulticast.sync_ckp", + "value": "false" + }, + { + "value": "false", + "name": "system.totalordermulticast.sync_log" + }, + { + "value": "3000000", + "name": "system.totalordermulticast.timeTolerance" + }, + { + "name": "system.totalordermulticast.timeout", + "value": "60000" + }, + { + "name": "system.totalordermulticast.timeout_highMark", + "value": "200" + }, + { + "value": "false", + "name": "system.totalordermulticast.verifyTimestamps" + }, + { + "name": "system.ttp.id", + "value": "2001" + } + ], + "viewId": 0, + "nodes": [ + { + "id": 0, + "networkAddress": { + "host": "127.0.0.1", + "port": 10080, + "secure": false + }, + "pubKey": "7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn", + "address": "LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw" + }, + { + "pubKey": "7VeREmuT4fF9yRPEMbSSaNLKbLa3qoTpfGHRgwpnSWUn5tqW", + "address": "LdeNiXZbsBCsTc2ZGp1PGBX81aUxPekhwEwmY", + "id": 1, + "networkAddress": { + "host": "127.0.0.1", + "port": 10082, + "secure": false + } + }, + { + "id": 2, + "networkAddress": { + "host": "127.0.0.1", + "port": 10084, + "secure": false + }, + "address": "LdeNwsiuo7n6HULWhNKc87PBXJXAfGKFon9RE", + "pubKey": "7VeRFF1ednwhrFoe5cngKwPUJ2N4iFKD9Jt53GxSCc1MmPQ6" + }, + { + "networkAddress": { + "host": "127.0.0.1", + "port": 10086, + "secure": false + }, + "id": 3, + "pubKey": "7VeRGE4V9MR7HgAqTrkxGvJvaaKRZ3fAjHUjYzpNBGcjfAvr", + "address": "LdeP2ji8PR1DPsLt5NoFeiBnhpckrLHgCJge6" + } + ] + }, + "cryptoSetting": { + "supportedProviders": [ + { + "algorithms": [ + { + "name": "AES", + "code": -32230 + }, + { + "name": "ED25519", + "code": 16661 + }, + { + "code": 16662, + "name": "ECDSA" + }, + { + "name": "RSA", + "code": -16105 + }, + { + "name": "RIPEMD160", + "code": 8217 + }, + { + "name": "SHA256", + "code": 8216 + }, + { + "name": "JVM-SECURE-RANDOM", + "code": 4123 + } + ], + "name": "com.jd.blockchain.crypto.service.classic.ClassicCryptoService" + }, + { + "name": "com.jd.blockchain.crypto.service.sm.SMCryptoService", + "algorithms": [ + { + "code": -16126, + "name": "SM2" + }, + { + "name": "SM3", + "code": 8195 + }, + { + "name": "SM4", + "code": -32252 + } + ] + } + ], + "hashAlgorithm": 8216, + "autoVerifyHash": false + }, + "participantNodes": [ + { + "participantNodeState": "CONSENSUS", + "pubKey": "7VeRFF1ednwhrFoe5cngKwPUJ2N4iFKD9Jt53GxSCc1MmPQ6", + "address": { + "value": "LdeNwsiuo7n6HULWhNKc87PBXJXAfGKFon9RE" + }, + "name": "2", + "id": 2 + }, + { + "id": 1, + "participantNodeState": "CONSENSUS", + "pubKey": "7VeREmuT4fF9yRPEMbSSaNLKbLa3qoTpfGHRgwpnSWUn5tqW", + "address": { + "value": "LdeNiXZbsBCsTc2ZGp1PGBX81aUxPekhwEwmY" + }, + "name": "1" + }, + { + "id": 0, + "address": { + "value": "LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw" + }, + "name": "0", + "participantNodeState": "CONSENSUS", + "pubKey": "7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn" + }, + { + "id": 3, + "participantNodeState": "CONSENSUS", + "pubKey": "7VeRGE4V9MR7HgAqTrkxGvJvaaKRZ3fAjHUjYzpNBGcjfAvr", + "address": { + "value": "LdeP2ji8PR1DPsLt5NoFeiBnhpckrLHgCJge6" + }, + "name": "3" + } + ] + }, + "success": true +} +``` + +说明 + +|名称|说明| +|---|---| +|ledgerStructureVersion|账本种子信息| +|participantsHash|参与方数据集哈希| +|seed|账本种子信息| +|consensusProtocol|共识协议，以字符串方式显示| +|consensusSettings|共识配置| +|cryptoSetting|加密算法配置| +|participantNodes|参与方节点信息| + +### 2.8 获取账本管理数据信息 + +```http +GET /ledgers/{ledger}/admininfo +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型 | +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串 | + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/admininfo +``` + +#### 返回实例 + +```json +{ + "data" : { + "participants" : [ + { + "id" : 2, + "pubKey" : "7VeRFF1ednwhrFoe5cngKwPUJ2N4iFKD9Jt53GxSCc1MmPQ6", + "name" : "2", + "participantNodeState" : "CONSENSUS", + "address" : { + "value" : "LdeNwsiuo7n6HULWhNKc87PBXJXAfGKFon9RE" + } + }, + { + "name" : "1", + "pubKey" : "7VeREmuT4fF9yRPEMbSSaNLKbLa3qoTpfGHRgwpnSWUn5tqW", + "id" : 1, + "participantNodeState" : "CONSENSUS", + "address" : { + "value" : "LdeNiXZbsBCsTc2ZGp1PGBX81aUxPekhwEwmY" + } + }, + { + "id" : 0, + "name" : "0", + "pubKey" : "7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn", + "address" : { + "value" : "LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw" + }, + "participantNodeState" : "CONSENSUS" + }, + { + "participantNodeState" : "CONSENSUS", + "address" : { + "value" : "LdeP2ji8PR1DPsLt5NoFeiBnhpckrLHgCJge6" + }, + "name" : "3", + "pubKey" : "7VeRGE4V9MR7HgAqTrkxGvJvaaKRZ3fAjHUjYzpNBGcjfAvr", + "id" : 3 + } + ], + "participantCount" : 4, + "metadata" : { + "ledgerStructureVersion" : 0, + "seed" : "NiSpjQVYRMMEA+1bnyU2eA==", + "userRolesHash" : "j5rggjQQtcjMTSwxFyDedcxPSxVVfjAB3khJDvgdiGFhiB", + "settingsHash" : "j5iNkXJptLJrJcFL1YJpuvbJCh6H3iioBNJG7QKPESUUif", + "participantsHash" : "j5qzkZgpGMczBDNKXRGJdyPTndkxPvB7Gdrfiqy6LvG7P5", + "rolePrivilegesHash" : "j5hBCfTVv77mTyM5WHoGnw1cezgzB3QDqojqjhg5qmuECn" + }, + "settings" : { + "cryptoSetting" : { + "supportedProviders" : [ + { + "algorithms" : [ + { + "name" : "AES", + "code" : -32230 + }, + { + "name" : "ED25519", + "code" : 16661 + }, + { + "code" : 16662, + "name" : "ECDSA" + }, + { + "name" : "RSA", + "code" : -16105 + }, + { + "name" : "RIPEMD160", + "code" : 8217 + }, + { + "name" : "SHA256", + "code" : 8216 + }, + { + "name" : "JVM-SECURE-RANDOM", + "code" : 4123 + } + ], + "name" : "com.jd.blockchain.crypto.service.classic.ClassicCryptoService" + }, + { + "name" : "com.jd.blockchain.crypto.service.sm.SMCryptoService", + "algorithms" : [ + { + "code" : -16126, + "name" : "SM2" + }, + { + "name" : "SM3", + "code" : 8195 + }, + { + "name" : "SM4", + "code" : -32252 + } + ] + } + ], + "hashAlgorithm" : 8216, + "autoVerifyHash" : false + }, + "consensusProvider" : "com.jd.blockchain.consensus.bftsmart.BftsmartConsensusProvider", + "consensusSetting" : { + "value" : "11u5FERE3JChMzbiFcGwjdyyegB6Dq6Nn3s1zB7U9AFs9xaphxosYGwQ2NAAXi2fM2NKf1WKpuvaWz51gsfWRSm7SJiAX9B26hxwmjwtSuGwcSJTZkDcScAFV5Pvv4pnbeZwvzcygEE4PGRYw835PN65eaaFX9114UjmaKeGBexzKwGYDAfc5hGPtpqmeuNurc6yHycRnRV1NNq9ZMUSiSpquiJgh1a8XtaYW9nakSH6jJKYSsX8axhYjMpta8CdBwkMZPZDCMcDojwzdzDQyaovTarACtxUWCdYz88U986k8SB3y5Z3PvU9QpSufCZEMPgLEGThi4PNhCSmdmcCJPEGvrfqfTTXMPDvPxLBZLKkpLHpXvmDiLot2pTCkPRicLhF7bnACW5CbNBkB73TRvdnAgFYBqKqQHuMxoTFyrABGdtWT5niFp8DXsTvv2sKSMxFZWgdDt2x5ax1xVCogzJTgxAQrd2ykDd32dkCdzKQJ6RpA3cJABguKXs6txXoeY2VPCg19mZCezNUW1SvhMVw7Dy1a8HHT2xMZ77MwHTXXfn2bEKNJCAv1PRM1re2Upnqo55am8ssoeAvABMCogKQAM56YsekyuusoYierZmi7pD7o4oNQaPGbzgHs2R9XDjLr2esNvDiJbVkr725PUw5Zgs9nqKg2vo11Z42eyXQxzw3Czg4FNts5xm7BeMwJXkT337cZHT2mJkUp58SUxmEB2TcGnzHXvz7qqdJ5NZRQaY87KgrEzo2xTwm8VW9AegiUNgExo5xxJXsGM1p24NCxgodjGnqx6FhB6JDjubDiU2oC7HAnqhwUF6AKgAQpdhGhvs2ts4dxYu8vEoZ5eyQaM2NXfUbm5jTAUvCaafd4oXZDXik4Jv79oUGtncVg52oj3MKZ4nqicMwoAz7esxDX9BWwyR1fEbU7vGPn9FPh87kdqh5koMF2BLhqnd5puobFsL38wtpmwA62DNtuekvTcTFjE97QMqpRKwzos2Kjnah6k6CyJ9DXkaUT7KE1fjWxuTv9794J93wVzheKjEy5nRqhWKHpj1AEPmrfPB9kS1TRUWGEN5aRSjWUgzydcpXutrPfm4wg3Xhgme5fURvE9Pm8F7pTdKaWS6dXDDm5bqWbQ38mMnmkvta54RL563bRPLS3fqmaRyshjN8V5nfec7LF4Fxj1PJhJ5XWR8tmHSD3Yd311BjZ8HaqtaCb74uvjGzjd6M1bh1KU8r96wMcY31Ldc2551iXU7hx2tmBKCAnJekvfQKRv7NvUphfSLJ5AqhAiibFbuQupkz9RgbcpD4Agm6Vv36CiiTDR9PNneP7xjYifuzSUL5hhJwoEpc9Zr6cdhbkAn7sePDkPMo1WCvvJPV9gR4MufSjCN1uxGTXF2fQCmucZemBJ7gTXc5uuATYyip1DRq4m8zpWQ9sz1wyMbqHVSnFKbcApDYhcxPmuF4FTm36gYbCU3q4TuMQvXUoz4Zfjc5y4kaR7im8ocuPFBCXbYgpUjeta52LTJbw2xtNG7EPdjGPXcvqNj4yQSrdGirGJc7dXoUhsJSki1j2dm2T3hdWXsu5oLmxfadoqQXqazhrd7bQJBViEYri51vkMkf8BJCJF8y8wEdZsDcusYYqSZn1mYToHKjAbu4oxGLnp7AM6TSpMjqdsxNBTCgD4u9Q2GvFKEW5S3W5fQvkPhEYSS5Q12K7oHTi2Cs22oQRADXw5FxRedzvSfuQdeA3RN8XgbSHr72mQXzso6SvLQda4Xnfz9M2hSsxg8QRsQm4dBsZ5aSGnZw45dHKHBNRv2RxmHntFbcc1JwCPhbbBxwE8zWp28pEdF1K1qRSRbNMorXvvNBQZPvjoztLc15u2KcQK3Xczvdmc5naBpqoPWmUxcntsX9STCz5ep7sjf5KAkLxq2XQjruC2mbbVNVvZ6o4vnpQxGDVegMigATbSrNWipCp6mqJA7RDdKomdb21apSANr8V3s2nCjDrqMSjgwSxnUMAfS1BuDuhBF8pJB5YnmWJ2WTFCJKndU5D1UnZPawPmtxpG9m2jxKka1DRBJrWGN4UNYZHmqwpy6pAGiFAjg1Yak5cwsPAyHvaP6AFjVqpZbphccWmch1rKhah2BKhC3Jt2WoCmdYKJB6yNJHXgyNmaesUqYTKuq6yJk12QqQGAsHw9H3PYYTARaEHt1qPo76LB8vzUmcUV9dov6Q1Laa2XvUTkdor5XNycVW5Y4SpiqHwGDAY2ujHnte5E241FEYVXfyJBgMLZwnBXFtZm38WENifVQEk1nDsfoRCMZWyg4KyPUNSCvnqq7BtjrDfGQm4X5pMoHm1MuKeL4bJP" + } + } + }, + "success" : true +} +``` + +说明 + +|名称|说明| +|---|---| +|participants|参与方列表| +|participantCount|参与方数量| +|metadata|元数据| +|settings|配置信息| +|consensusProvider|共识协议| +|consensusSetting|共识配置| + + +## 3 区块 + +### 3.1 获取最新区块 + +```http +GET /ledgers/{ledger}/blocks/latest +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型 | +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串 | + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/latest +``` + +#### 返回实例 + +```json +{ + "data" : { + "timestamp" : 1615261725429, + "transactionSetHash" : "j5ssSG7LQC2CgU7fLbMCs2m2JtwN26j5kj2buE2u8F9miP", + "userAccountSetHash" : "j5hzkPPBJAqKs4rLWbEiFhbh1VW6Jc2xk878X5A6JywPnC", + "previousHash" : "j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp", + "hash" : "j5irFH5SJBaCSa6R3QYhbWYMUA2Wos3gvXYUyDYAHVhG23", + "adminAccountHash" : "j5maavFZShDorv36Sj5W8ijm1wkm2z9GtfdiVvUcfzvwv8", + "height" : 1, + "ledgerHash" : "j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp", + "dataAccountSetHash" : "j5poz1Ced486LxYbcotGvihT42CTiQym98Mg1By8DHZBxJ" + }, + "success" : true +} +``` + +说明 + +|名称|说明| +|---|---| +|hash|区块哈希| +|height|区块高度| +|timestamp|区块创建时间戳| +|ledgerHash|账本哈希| +|previousHash|前置区块哈希| +|transactionSetHash|交易集哈希| +|userAccountSetHash|用户集哈希| +|contractAccountSetHash|合约集哈希| +|adminAccountHash|管理员集哈希| +|dataAccountSetHash|数据账户集哈希| + +### 3.2 根据区块哈希获取区块详细信息 + +```http +GET /ledgers/{ledger}/blocks/hash/{block_hash} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型 | +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|block_hash|是|区块哈希|字符串| + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/hash/j5irFH5SJBaCSa6R3QYhbWYMUA2Wos3gvXYUyDYAHVhG23 +``` + +#### 返回实例 + +同 [3.1](3.1-获取最新区块) + + +### 3.3 根据区块高度获取区块详细信息 + +```http +GET /ledgers/{ledger}/blocks/height/{block_height} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|block_height|是|区块高度|数字| + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/height/1 +``` + +#### 返回实例 + +同 [3.1](3.1-获取最新区块) + +## 4 交易 + +### 4.1 获取账本交易总数 + +```http +GET /ledgers/{ledger}/txs/count +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/txs/count +``` + +##### 返回实例 + +```json +{ + "data": 2, + "success": true +} +``` + +说明 + +|名称|说明| +|---|---| +|data|交易数量| + +### 4.2 根据区块高度查询交易数量 + +**包含当前区块以及之前区块数据** + +```http +GET /ledgers/{ledgerHash}/blocks/height/{block_height}/txs/count +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|block_height|是|区块高度|数字| + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/height/66/txs/count +``` + +#### 返回实例 + +```json +{ + "data": 1, + "success": true +} +``` + +说明 + +|名称|说明| +|---|---| +|data|交易数量| + +### 4.3 根据区块哈希查询交易数量 + +**包含当前区块以及之前区块数据** + +```http +GET /ledgers/{ledger}/blocks/hash/{block_hash}/txs/count +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|block_hash|是|区块哈希|字符串| + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/hash/j5irFH5SJBaCSa6R3QYhbWYMUA2Wos3gvXYUyDYAHVhG23/txs/additional-count +``` + +#### 返回实例 + +```json +{ + "data": 1, + "success": true +} +``` + +说明 + +|名称|说明| +|---|---| +|data|交易数量| + +### 4.4 根据区块高度查询区块内的交易数量 + +**仅包含当前区块数据** + +```http +GET /ledgers/{ledger}/blocks/height/{block_height}/txs/additional-count +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|block_height|是|区块高度|数字| + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/height/66/txs/additional-count +``` + +#### 返回实例 + +```json +{ + "data": 1, + "success": true +} +``` + +说明 + +|名称|说明| +|---|---| +|data|交易数量| + +### 4.5 根据区块哈希查询区块内的交易数量 + +**仅包含当前区块数据** + +```http +GET /ledgers/{ledger}/blocks/hash/{block_hash}/txs/additional-count +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|block_hash|是|区块哈希|字符串| + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/hash/j5irFH5SJBaCSa6R3QYhbWYMUA2Wos3gvXYUyDYAHVhG23/txs/additional-count +``` + +#### 返回实例 + +```json +{ + "data": 1, + "success": true +} +``` + +说明 + +|名称|说明| +|---|---| +|data|交易数量| + +### 4.6 获取指定区块高度的交易列表 + +**包含当前区块以及之前区块数据** + +```http +GET /ledgers/{ledger}/blocks/height/{height}/txs?fromIndex={fromIndex}&count={count} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|height|是|区块高度|数字| +|query|fromIndex|否|查询交易的起始序号，默认为0|数字| +|query|count|否|查询返回交易的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/height/66/txs?fromIndex=1&count=1 +``` + +#### 返回实例 + +```json +{ + "data" : [ + { + "request" : { + "transactionContent" : { + "timestamp" : 1615261725387, + "ledgerHash" : "j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp", + "operations" : [ + { + "@type" : "com.jd.blockchain.ledger.DataAccountRegisterOperation", + "accountID" : { + "pubKey" : "7VeRBZLMWAxcgL9DTjGWn9FHWny54bzDzrgeAH6pCFvEJ5eT", + "address" : { + "value" : "LdeNscE3MP9a1vgyVUg9LgxQx6yzkUEUS65Rn" + } + } + }, + { + "writeSet" : [ + { + "value" : { + "type" : "TEXT", + "bytes" : { + "value" : "EMeAB7i" + } + }, + "expectedVersion" : -1, + "key" : "key" + } + ], + "@type" : "com.jd.blockchain.ledger.DataAccountKVSetOperation", + "accountAddress" : { + "value" : "LdeNscE3MP9a1vgyVUg9LgxQx6yzkUEUS65Rn" + } + } + ] + }, + "nodeSignatures" : [ + { + "pubKey" : "7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn", + "digest" : "SMJHE64z77GSkBkC8Zw45r8zRhCq3KWgyGMxRo7KXZ1JWjnBBj1WkPGBdS3AUAX3UoWK5ymGxeqaskjTVgHxGtC768" + } + ], + "transactionHash" : "j5siSjjv7H6s61zsMajkGfyhASFnKpthveNDptCrM2gmui", + "endpointSignatures" : [ + { + "digest" : "SMJHE64z77GSkBkC8Zw45r8zRhCq3KWgyGMxRo7KXZ1JWjnBBj1WkPGBdS3AUAX3UoWK5ymGxeqaskjTVgHxGtC768", + "pubKey" : "7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn" + } + ] + }, + "result" : { + "executionState" : "SUCCESS", + "dataSnapshot" : { + "adminAccountHash" : "j5maavFZShDorv36Sj5W8ijm1wkm2z9GtfdiVvUcfzvwv8", + "userAccountSetHash" : "j5hzkPPBJAqKs4rLWbEiFhbh1VW6Jc2xk878X5A6JywPnC", + "dataAccountSetHash" : "j5poz1Ced486LxYbcotGvihT42CTiQym98Mg1By8DHZBxJ" + }, + "blockHeight" : 1, + "transactionHash" : "j5siSjjv7H6s61zsMajkGfyhASFnKpthveNDptCrM2gmui" + } + } + ], + "success" : true +} +``` + + +说明 + +|名称|说明| +|---|---| +|request|请求数据| +|request.transactionContent|交易内容| +|request.transactionContent.timestamp|交易时间戳，毫秒| +|request.transactionContent.ledgerHash|账本哈希| +|request.transactionContent.operations|操作列表| +|request.nodeSignatures|参与方签名列表| +|request.endpointSignatures|终端用户签名列表| +|request.transactionHash|交易哈希| +|result|交易结果| +|result.executionState|交易执行状态，SUCCESS（成功）| +|result.dataSnapshot|交易执行后数据快照| +|result.blockHeight|最新区块高度| +|result.transactionHash|交易哈希| + +### 4.7 获取指定哈希的区块的交易列表 + +```http +GET /ledgers/{ledger}/blocks/hash/{block_hash}/txs?fromIndex={fromIndex}&count={count} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|block_hash|是|区块哈希|字符串| +|query|fromIndex|否|查询交易的起始序号，默认为0|数字| +|query|count|否|查询返回交易的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/hash/j5irFH5SJBaCSa6R3QYhbWYMUA2Wos3gvXYUyDYAHVhG23/txs?fromIndex=1&count=1 +``` + +#### 返回实例 + +[同 4.4](#4.4-获取指定区块高度的交易列表) + + +### 4.8 获取交易详细信息 + +```http +GET /ledgers/{ledger}/txs/hash/{tx_hash} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|tx_hash|是|交易哈希|字符串| + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/txs/hash/j5siSjjv7H6s61zsMajkGfyhASFnKpthveNDptCrM2gmui +``` + +#### 返回实例 + +```json +{ + "success" : true, + "data" : { + "result" : { + "dataSnapshot" : { + "dataAccountSetHash" : "j5poz1Ced486LxYbcotGvihT42CTiQym98Mg1By8DHZBxJ", + "userAccountSetHash" : "j5hzkPPBJAqKs4rLWbEiFhbh1VW6Jc2xk878X5A6JywPnC", + "adminAccountHash" : "j5maavFZShDorv36Sj5W8ijm1wkm2z9GtfdiVvUcfzvwv8" + }, + "transactionHash" : "j5siSjjv7H6s61zsMajkGfyhASFnKpthveNDptCrM2gmui", + "blockHeight" : 1, + "executionState" : "SUCCESS" + }, + "request" : { + "nodeSignatures" : [ + { + "pubKey" : "7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn", + "digest" : "SMJHE64z77GSkBkC8Zw45r8zRhCq3KWgyGMxRo7KXZ1JWjnBBj1WkPGBdS3AUAX3UoWK5ymGxeqaskjTVgHxGtC768" + } + ], + "endpointSignatures" : [ + { + "pubKey" : "7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn", + "digest" : "SMJHE64z77GSkBkC8Zw45r8zRhCq3KWgyGMxRo7KXZ1JWjnBBj1WkPGBdS3AUAX3UoWK5ymGxeqaskjTVgHxGtC768" + } + ], + "transactionHash" : "j5siSjjv7H6s61zsMajkGfyhASFnKpthveNDptCrM2gmui", + "transactionContent" : { + "timestamp" : 1615261725387, + "operations" : [ + { + "@type" : "com.jd.blockchain.ledger.DataAccountRegisterOperation", + "accountID" : { + "address" : { + "value" : "LdeNscE3MP9a1vgyVUg9LgxQx6yzkUEUS65Rn" + }, + "pubKey" : "7VeRBZLMWAxcgL9DTjGWn9FHWny54bzDzrgeAH6pCFvEJ5eT" + } + }, + { + "accountAddress" : { + "value" : "LdeNscE3MP9a1vgyVUg9LgxQx6yzkUEUS65Rn" + }, + "@type" : "com.jd.blockchain.ledger.DataAccountKVSetOperation", + "writeSet" : [ + { + "value" : { + "bytes" : { + "value" : "EMeAB7i" + }, + "type" : "TEXT" + }, + "expectedVersion" : -1, + "key" : "key" + } + ] + } + ], + "ledgerHash" : "j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp" + } + } + } +} +``` + +说明 + +[同 4.4](#4.4-获取指定区块高度的交易列表) + +## 5 用户 + +### 5.1 获取用户总数 + +```http +GET /ledgers/{ledger}/users/count +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/users/count +``` + +#### 返回实例 + +```json +{ + "data": 4, + "success": true +} +``` + +说明 + +|名称|说明| +|---|---| +|data|用户总数| + + +### 5.2 获取用户列表 + +```http +GET /ledgers/{ledger}/users?fromIndex={fromIndex}&count={count} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|query|fromIndex|否|查询用户的起始序号，默认为0|数字| +|query|count|否|查询返回用户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/users?fromIndex=0&count=2 +``` + +#### 返回实例 + +```json +{ + "success" : true, + "data" : [ + { + "pubKey" : "7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn", + "address" : { + "value" : "LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw" + } + }, + { + "pubKey" : "7VeREmuT4fF9yRPEMbSSaNLKbLa3qoTpfGHRgwpnSWUn5tqW", + "address" : { + "value" : "LdeNiXZbsBCsTc2ZGp1PGBX81aUxPekhwEwmY" + } + } + ] +} +``` + +说明 + +|名称|说明| +|---|---| +|address.value|用户地址| +|pubKey|用户公钥| + + +### 5.3 获取用户详细信息 + +```http +GET /ledgers/{ledger}/users/address/{address} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|address|是|用户地址|字符串| + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/users/address/LdeNiXZbsBCsTc2ZGp1PGBX81aUxPekhwEwmY +``` + +#### 返回实例 + +```json +{ + "success" : true, + "data" : { + "pubKey" : "7VeREmuT4fF9yRPEMbSSaNLKbLa3qoTpfGHRgwpnSWUn5tqW", + "iD" : { + "pubKey" : "7VeREmuT4fF9yRPEMbSSaNLKbLa3qoTpfGHRgwpnSWUn5tqW", + "address" : { + "value" : "LdeNiXZbsBCsTc2ZGp1PGBX81aUxPekhwEwmY" + } + }, + "dataRootHash" : "j5uJfAqLw1ptaZYJyKVZm37zZybboqxMPpS6Mv59rNd4xF", + "headerRootHash" : "j5oYeBmoBJ4jLpijwi6eoKAqh4BsQ3RWHzxdBnTvvTqSK6", + "dataset" : { + "dataCount" : 0, + "updated" : false, + "readonly" : false, + "rootHash" : "j5uJfAqLw1ptaZYJyKVZm37zZybboqxMPpS6Mv59rNd4xF" + }, + "address" : { + "value" : "LdeNiXZbsBCsTc2ZGp1PGBX81aUxPekhwEwmY" + } + } +} +``` + +说明 + +|名称|说明| +|---|---| +|address.value|用户地址| +|pubKey|用户公钥| +|dataset.rootHash|用户根Hash| + +### 5.4 获取指定高度的区块的用户总数 + +**包含当前区块以及之前区块数据** + +```http +GET /ledgers/{ledger}/blocks/height/{block_height}/users/count +``` + +#### 参数 + +| 请求类型 | 名称 | 是否必需 | 说明 | 数据类型 | +| -------- | ------------ | -------- | -------- | -------- | +| path | ledger | 是 | 账本哈希 | 字符串 | +| path | block_height | 是 | 区块高度 | 数字 | + +#### 请求实例 + +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/users/height/1/users/count +``` + +#### 返回实例 + +```json +{ + "data": 4, + "success": true +} +``` + +说明 + +| 名称 | 说明 | +| ---- | ------------ | +| data | 数据账户数量 | + +### 5.5 获取指定哈希的区块的用户总数 + +**包含当前区块以及之前区块数据** + +```http +GET /ledgers/{ledger}/blocks/hash/{block_hash}/users/count +``` + +#### 参数 + +| 请求类型 | 名称 | 是否必需 | 说明 | 数据类型 | +| -------- | ---------- | -------- | -------- | -------- | +| path | ledger | 是 | 账本哈希 | 字符串 | +| path | block_hash | 是 | 区块哈希 | 字符串 | + +#### 请求实例 + +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/hash/j5opzRbH2fB6YmjvEdMLQ8VHVeZoUuKyVWzExCtJF1wecw/users/count +``` + +#### 返回实例 + +```json +{ + "data": 4, + "success": true +} +``` + +说明 + +| 名称 | 说明 | +| ---- | ------------ | +| data | 数据账户数量 | + +### 5.6 根据区块高度查询区块内的用户数量 + +**仅包含当前区块数据** + +```http +GET /ledgers/{ledger}/blocks/height/{block_height}/users/additional-count +``` + +#### 参数 + +| 请求类型 | 名称 | 是否必需 | 说明 | 数据类型 | +| -------- | ------------ | -------- | -------- | -------- | +| path | ledger | 是 | 账本哈希 | 字符串 | +| path | block_height | 是 | 区块高度 | 数字 | + +#### 请求实例 + +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/height/2/users/additional-count +``` + +#### 返回实例 + +```json +{ + "data": 1, + "success": true +} +``` + +说明 + +| 名称 | 说明 | +| ---- | -------- | +| data | 用户数量 | + +### 5.7 根据区块哈希查询区块内的用户数量 + +**仅包含当前区块数据** + +```http +GET /ledgers/{ledger}/blocks/hash/{block_hash}/users/additional-count +``` + +#### 参数 + +| 请求类型 | 名称 | 是否必需 | 说明 | 数据类型 | +| -------- | ---------- | -------- | -------- | -------- | +| path | ledger | 是 | 账本哈希 | 字符串 | +| path | block_hash | 是 | 区块哈希 | 字符串 | + +#### 请求实例 + +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/hash/j5irFH5SJBaCSa6R3QYhbWYMUA2Wos3gvXYUyDYAHVhG23/users/additional-count +``` + +#### 返回实例 + +```json +{ + "data": 1, + "success": true +} +``` + +说明 + +| 名称 | 说明 | +| ---- | -------- | +| data | 用户数量 | + +### 5.8 查询最新区块新增用户数量 + +**仅包含最新区块数据** + +```http +GET /ledgers/{ledger}/blocks/users/additional-count +``` + +#### 参数 + +| 请求类型 | 名称 | 是否必需 | 说明 | 数据类型 | +| -------- | ------ | -------- | -------- | -------- | +| path | ledger | 是 | 账本哈希 | 字符串 | + +#### 请求实例 + +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/users/additional-count +``` + +#### 返回实例 + +```json +{ + "data": 0, + "success": true +} +``` + +说明 + +| 名称 | 说明 | +| ---- | -------- | +| data | 用户数量 | + +## 6 角色权限 + +有关用户/角色/权限说明参照[用户文档](user.md) + +### 6.1 根据角色获取权限信息 +```http +GET /ledgers/{ledger}/authorization/role/{roleName} +``` + +#### 参数 + +| 请求类型 | 名称 | 是否必需 | 说明 | 数据类型 | +| -------- | -------- | -------- | -------- | -------- | +| path | ledger | 是 | 账本哈希 | 字符串 | +| path | roleName | 是 | 角色名 | 字符串 | + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5pSJLyVpS8QG2wL95fiDWHHnweh2YdqNhgmnb64SBMjUh/authorization/role/DEFAULT +``` + +#### 返回实例 + +```json +{ + "success" : true, + "data" : { + "roleName" : "DEFAULT", + "transactionPrivilege" : { + "privilege" : [ + "DIRECT_OPERATION", + "CONTRACT_OPERATION" + ], + "permissionCount" : 2 + }, + "version" : 0, + "ledgerPrivilege" : { + "privilege" : [ + "CONFIGURE_ROLES", + "AUTHORIZE_USER_ROLES", + "SET_CONSENSUS", + "SET_CRYPTO", + "REGISTER_PARTICIPANT", + "REGISTER_USER", + "REGISTER_DATA_ACCOUNT", + "REGISTER_CONTRACT", + "UPGRADE_CONTRACT", + "SET_USER_ATTRIBUTES", + "WRITE_DATA_ACCOUNT", + "APPROVE_TX", + "CONSENSUS_TX", + "REGISTER_EVENT_ACCOUNT", + "WRITE_EVENT_ACCOUNT" + ], + "permissionCount" : 15 + } + } +} +``` + +说明 + +| 名称 | 说明 | +| ------------------------------------ | ----------------- | +| roleName | 角色名称 | +| transactionPrivilege | 交易权限 | +| transactionPrivilege.privilege | 交易权限.权限类别 | +| transactionPrivilege.permissionCount | 交易权限.权限总数 | +| ledgerPrivilege | 账本权限 | +| ledgerPrivilege.privilege | 账本权限.权限类别 | +| ledgerPrivilege.permissionCount | 账本权限.权限总数 | + +### 6.2 根据用户获取权限信息 + +```http +GET /ledgers/{ledger}/authorization/user/{userAddress} +``` + +#### 参数 + +| 请求类型 | 名称 | 是否必需 | 说明 | 数据类型 | +| -------- | ----------- | -------- | -------- | -------- | +| path | ledger | 是 | 账本哈希 | 字符串 | +| path | userAddress | 是 | 用户地址 | 字符串 | + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5pSJLyVpS8QG2wL95fiDWHHnweh2YdqNhgmnb64SBMjUh/authorization/user/LdeP2ji8PR1DPsLt5NoFeiBnhpckrLHgCJge6 +``` + +#### 返回实例 + +```json +{ + "data" : { + "userAddress" : { + "value" : "LdeP2ji8PR1DPsLt5NoFeiBnhpckrLHgCJge6" + }, + "userRole" : [ + "DEFAULT" + ], + "ledgerPrivilegesBitset" : { + "privilege" : [ + "CONFIGURE_ROLES", + "AUTHORIZE_USER_ROLES", + "SET_CONSENSUS", + "SET_CRYPTO", + "REGISTER_PARTICIPANT", + "REGISTER_USER", + "REGISTER_DATA_ACCOUNT", + "REGISTER_CONTRACT", + "UPGRADE_CONTRACT", + "SET_USER_ATTRIBUTES", + "WRITE_DATA_ACCOUNT", + "APPROVE_TX", + "CONSENSUS_TX", + "REGISTER_EVENT_ACCOUNT", + "WRITE_EVENT_ACCOUNT" + ], + "permissionCount" : 15 + }, + "transactionPrivilegesBitset" : { + "permissionCount" : 2, + "privilege" : [ + "DIRECT_OPERATION", + "CONTRACT_OPERATION" + ] + } + }, + "success" : true +} +``` + +说明 + +| 名称 | 说明 | +| --------------------------- | ---------- | +| userRole | 用户角色 | +| transactionPrivilegesBitset | 交易权限集 | +| ledgerPrivilegesBitset | 账本权限集 | + +> 请求链上不存在的用户地址，会返回DEFAULT角色权限列表 + +## 7 数据账户 + +### 7.1 获取账户列表 + +```http +GET /ledgers/{ledger}/accounts?fromIndex={fromIndex}&count={count} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|query|fromIndex|否|查询数据账户的起始序号，默认为0|数字| +|query|count|否|查询返回数据账户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/accounts?fromIndex=0&count=-1 +``` + +#### 返回实例 + +```json +{ + "data" : [ + { + "address" : { + "value" : "LdeNscE3MP9a1vgyVUg9LgxQx6yzkUEUS65Rn" + }, + "pubKey" : "7VeRBZLMWAxcgL9DTjGWn9FHWny54bzDzrgeAH6pCFvEJ5eT" + } + ], + "success" : true +} +``` + +说明 + +|名称|说明| +|---|---| +|address.value|账户地址| +|pubKey|账户公钥| + + +### 7.2 获取账户详细信息 + +```http +GET /ledgers/{ledger}/accounts/address/{address} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|address|是|账户地址|字符串| + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/accounts/address/LdeNscE3MP9a1vgyVUg9LgxQx6yzkUEUS65Rn +``` + +#### 返回实例 + +```json +{ + "data" : { + "dataset" : { + "updated" : false, + "readonly" : false, + "dataCount" : 1, + "rootHash" : "j5vjKBpdFncVW9dYnjefiKgs858QKNc98XAvy5pFXmgLKp" + }, + "headerRootHash" : "j5jUf96A8678xdggUdAZUtADL43WFsFu76gWxT9KkknjLf", + "dataRootHash" : "j5vjKBpdFncVW9dYnjefiKgs858QKNc98XAvy5pFXmgLKp", + "pubKey" : "7VeRBZLMWAxcgL9DTjGWn9FHWny54bzDzrgeAH6pCFvEJ5eT", + "iD" : { + "pubKey" : "7VeRBZLMWAxcgL9DTjGWn9FHWny54bzDzrgeAH6pCFvEJ5eT", + "address" : { + "value" : "LdeNscE3MP9a1vgyVUg9LgxQx6yzkUEUS65Rn" + } + }, + "address" : { + "value" : "LdeNscE3MP9a1vgyVUg9LgxQx6yzkUEUS65Rn" + } + }, + "success" : true +} +``` + +说明 + +|名称|说明| +|---|---| +|address.value|账户地址| +|pubKey|账户公钥| + + +### 7.3 获取账户总数 + +```http +GET /ledgers/{ledger}/accounts/count +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/accounts/count +``` + +#### 返回实例 + +```json +{ + "data": 1, + "success": true +} +``` + +说明 + +|名称|说明| +|---|---| +|data|账户数量| + +### 7.4 获取指定高度的区块的数据账户总数 + +**包含当前区块以及之前区块数据** + +```http +GET /ledgers/{ledger}/blocks/height/{block_height}/accounts/count +``` + +#### 参数 + +| 请求类型 | 名称 | 是否必需 | 说明 | 数据类型 | +| -------- | ------------ | -------- | -------- | -------- | +| path | ledger | 是 | 账本哈希 | 字符串 | +| path | block_height | 是 | 区块高度 | 数字 | + +#### 请求实例 + +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/height/1/accounts/count +``` + +#### 返回实例 + +```json +{ + "data": 1, + "success": true +} +``` + +说明 + +| 名称 | 说明 | +| ---- | ------------ | +| data | 数据账户数量 | + +### 7.5 获取指定哈希的区块的数据账户总数 + +**包含当前区块以及之前区块数据** + +```http +GET /ledgers/{ledger}/blocks/hash/{block_hash}/accounts/count +``` + +#### 参数 + +| 请求类型 | 名称 | 是否必需 | 说明 | 数据类型 | +| -------- | ---------- | -------- | -------- | -------- | +| path | ledger | 是 | 账本哈希 | 字符串 | +| path | block_hash | 是 | 区块哈希 | 字符串 | + +#### 请求实例 + +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/hash/j5opzRbH2fB6YmjvEdMLQ8VHVeZoUuKyVWzExCtJF1wecw/accounts/count +``` + +#### 返回实例 + +```json +{ + "data": 1, + "success": true +} +``` + +说明 + +| 名称 | 说明 | +| ---- | ------------ | +| data | 数据账户数量 | + +### 7.6 根据区块高度查询区块内的数据账户数量 + +**仅包含当前区块数据** + +```http +GET /ledgers/{ledger}/blocks/height/{block_height}/accounts/additional-count +``` + +#### 参数 + +| 请求类型 | 名称 | 是否必需 | 说明 | 数据类型 | +| -------- | ------------ | -------- | -------- | -------- | +| path | ledger | 是 | 账本哈希 | 字符串 | +| path | block_height | 是 | 区块高度 | 数字 | + +#### 请求实例 + +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/height/1/accounts/additional-count +``` + +#### 返回实例 + +```json +{ + "data": 1, + "success": true +} +``` + +说明 + +| 名称 | 说明 | +| ---- | ------------ | +| data | 数据账户数量 | + +### 7.7 根据区块哈希查询区块内的数据账户数量 + +**仅包含当前区块数据** + +```http +GET /ledgers/{ledger}/blocks/hash/{block_hash}/accounts/additional-count +``` + +#### 参数 + +| 请求类型 | 名称 | 是否必需 | 说明 | 数据类型 | +| -------- | ---------- | -------- | -------- | -------- | +| path | ledger | 是 | 账本哈希 | 字符串 | +| path | block_hash | 是 | 区块哈希 | 字符串 | + +#### 请求实例 + +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/hash/j5irFH5SJBaCSa6R3QYhbWYMUA2Wos3gvXYUyDYAHVhG23/accounts/additional-count +``` + +#### 返回实例 + +```json +{ + "data": 1, + "success": true +} +``` + +说明 + +| 名称 | 说明 | +| ---- | ------------ | +| data | 数据账户数量 | + +### 7.8 获取某数据账户KV总数 + +```http + GET /ledgers/{ledger}/accounts/address/{address}/entries/count +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|address|是|账户地址|字符串| + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/accounts/address/LdeNscE3MP9a1vgyVUg9LgxQx6yzkUEUS65Rn/entries/count +``` + +#### 返回实例 + +```json +{ + "data": 1, + "success": true +} +``` + +说明 + +|名称|说明| +|---|---| +|data|KV总数| + + +### 7.9 获取某数据账户KV详情 + +```http +GET /ledgers/{ledger}/accounts/address/{address}/entries?fromIndex={fromIndex}&count={count} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|address|是|账户地址|字符串| +|query|fromIndex|否|查询数据账户对应KV的起始序号，默认为0|数字| +|query|count|否|查询返回数据账户对应KV的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/accounts/address/LdeNscE3MP9a1vgyVUg9LgxQx6yzkUEUS65Rn/entries?fromIndex=0&count=1 +``` + +#### 返回实例 + +```json +{ + "data" : [ + { + "type" : "TEXT", + "version" : 0, + "key" : "key", + "value" : "value" + } + ], + "success" : true +} +``` + +说明 + +|名称|说明| +|---|---| +|key|键| +|version|版本号| +|type|value类型| +|value|值| + +> 数据类型参照[数据账户](data_account.md)中描述。 + +### 7.10 获取某数据账户KV详情 + +```http +GET/POST /ledgers/{ledger}/accounts/{address}/entries?keys={keys} +``` + +#### 参数 + +| 请求类型 | 名称 | 是否必需 | 说明 | 数据类型 | +| -------- | ------- | -------- | --------------- | -------- | +| path | ledger | 是 | 账本哈希 | 字符串 | +| path | address | 是 | 账户地址 | 字符串 | +| form | keys | 是 | key详细内容列表 | 字符串 | + +#### 请求实例 + +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/accounts/LdeNscE3MP9a1vgyVUg9LgxQx6yzkUEUS65Rn/entries?keys=key,key1 +``` + + +#### 返回实例 + +```json +{ + "success" : true, + "data" : [ + { + "key" : "key", + "value" : 1024, + "version" : 2, + "type" : "INT64" + }, + { + "type" : "NIL", + "version" : -1, + "key" : "key1" + } + ] +} +``` + +说明 + +| 名称 | 说明 | +| ------- | --------- | +| key | 键 | +| version | 版本号 | +| type | value类型 | +| value | 值 | + + +### 7.11 获取某数据账户KV整个历史详情 + +```http + GET/POST /ledgers/{ledger}/accounts/{address}/entries-version +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|address|是|账户地址|字符串| +|body|kvInfoVO|是|Key相关信息|对象| + +KVInfoVO对应格式如下： + +```json + +{ + "data": [{ + "key": "key", + "version": [0, 1] + } +} + +``` + +kvInfoVO说明： + - 支持多个Key作为入参； + - 每个Key支持多个version； + + +#### 请求实例 +```curl +curl -H 'Content-Type:application/json' --data '{"data":[{"key":"key","version":[0,1]}]}' 'http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/accounts/LdeNscE3MP9a1vgyVUg9LgxQx6yzkUEUS65Rn/entries-version' +``` + +#### 返回实例 + +```json +{ + "data" : [ + { + "type" : "TEXT", + "key" : "key", + "value" : "value", + "version" : 0 + }, + { + "type" : "BYTES", + "version" : 1, + "value" : "Ynl0ZXM=", + "key" : "key" + } + ], + "success" : true +} +``` + +说明 + +|名称|说明| +|---|---| +|key|键| +|version|版本号| +|type|value类型| +|value|值，BASE64编码| + +## 8 合约 + +### 8.1 获取合约总数 + +```http +GET /ledgers/{ledger}/contracts/count +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| + + +#### 请求实例 + +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/contracts/count +``` + +#### 返回实例 + +```json +{ + "data": 1, + "success": true +} +``` + +说明 + +| 名称 | 说明 | +| ---- | -------- | +| data | 合约数量 | + +### 8.2 获取指定区块高度的合约总数 + +**包含当前区块以及之前区块数据** + +```http +GET /ledgers/{ledger}/blocks/height/{blockHeight}/contracts/count +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|blockHeight|是|区块高度|数字| + +#### 请求实例 + +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/height/7/contracts/count +``` + +#### 返回实例 + +```json +{ + "data": 2, + "success": true +} +``` + +说明 + +| 名称 | 说明 | +| ---- | -------- | +| data | 合约数量 | + + + +### 8.3 获取指定区块哈希的合约总数 + +**包含当前区块以及之前区块数据** + +```http +GET /ledgers/{ledger}/blocks/hash/{blockHash}/contracts/count +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|blockHash|是|区块哈希|字符串| + + +#### 请求实例 + +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/hash/j5hhTQPyZQHqkvP5UBq3sAaqxq8QUda6asJLzZ2VFUhvQ8/contracts/count +``` + +#### 返回实例 + +```json +{ + "data": 2, + "success": true +} +``` + +说明 + +| 名称 | 说明 | +| ---- | -------- | +| data | 合约数量 | + +### 8.4 根据区块高度查询区块内的合约总数 + +**仅包含当前区块数据** + +```http +GET /ledgers/{ledger}/blocks/height/{blockHeight}/contracts/additional-count +``` + +#### 参数 + +| 请求类型 | 名称 | 是否必需 | 说明 | 数据类型 | +| -------- | ----------- | -------- | -------- | -------- | +| path | ledger | 是 | 账本哈希 | 字符串 | +| path | blockHeight | 是 | 区块高度 | 数字 | + +#### 请求实例 + +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/height/7/contracts/additional-count +``` + +#### 返回实例 + +```json +{ + "data": 1, + "success": true +} +``` + +说明 + +| 名称 | 说明 | +| ---- | -------- | +| data | 合约数量 | + + + +### 8.5 根据区块哈希查询区块内的合约总数 + +**仅包含当前区块数据** + +```http +GET /ledgers/{ledger}/blocks/hash/{blockHash}/contracts/additional-count +``` + +#### 参数 + +| 请求类型 | 名称 | 是否必需 | 说明 | 数据类型 | +| -------- | --------- | -------- | -------- | -------- | +| path | ledger | 是 | 账本哈希 | 字符串 | +| path | blockHash | 是 | 区块哈希 | 字符串 | + + +#### 请求实例 + +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/blocks/hash/j5hhTQPyZQHqkvP5UBq3sAaqxq8QUda6asJLzZ2VFUhvQ8/contracts/additional-count +``` + +#### 返回实例 + +```json +{ + "data": 1, + "success": true +} +``` + +说明 + +| 名称 | 说明 | +| ---- | -------- | +| data | 合约数量 | + +### 8.6 获取合约列表 + +```http +GET /ledgers/{ledger}/contracts?fromIndex={fromIndex}&count={count} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|query|fromIndex|否|查询合约的起始序号，默认为0|数字| +|query|count|否|查询返回合约的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/contracts?fromIndex=0&count=-1 +``` + +#### 返回实例 + +```json +{ + "data" : [ + { + "pubKey" : "7VeRCfSaoBW3uRuvTqVb26PYTNwvQ1iZ5HBY92YKpEVN7Qht", + "address" : { + "value" : "LdeNr7H1CUbqe3kWjwPwiqHcmd86zEQz2VRye" + } + }, + { + "pubKey" : "7VeRALfcPigCTSEPHSwz7U7TDNLoet85z3nRfr5cYspUWLAR", + "address" : { + "value" : "LdeNwApbVMHqTCzNKuynUtJXH7vN2rG8gxHN5" + } + } + ], + "success" : true +} + +``` + +说明 + +|名称|说明| +|---|---| +|address.value|账户地址| +|pubKey|账户公钥| + + +### 8.7 获取合约详细信息 + +```http +GET /ledgers/{ledger}/contracts/address/{address} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|address|是|合约地址|字符串| + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/contracts/address/LdeNr7H1CUbqe3kWjwPwiqHcmd86zEQz2VRye +``` + +#### 返回实例 + +```json +{ + "success" : true, + "data" : { + "dataRootHash" : "j5uJfAqLw1ptaZYJyKVZm37zZybboqxMPpS6Mv59rNd4xF", + "chainCode" : "package com.jdchain.samples.contract;\n\nimport com.jd.blockchain.contract.*;\nimport utils.*;\nimport com.jd.blockchain.crypto.*;\nimport com.jd.blockchain.ledger.*;\n\npublic class SampleContractImpl implements EventProcessingAware, SampleContract\n{\n private ContractEventContext eventContext;\n \n public void setKVWithVersion(final String address, final String key, final String value, final long version) {\n this.eventContext.getLedger().dataAccount(Bytes.fromBase58(address)).setText(key, value, version);\n }\n \n public void setKV(final String address, final String key, final String value) {\n final TypedKVEntry[] entries = this.eventContext.getUncommittedLedger().getDataEntries(address, new String[] { key });\n long version = -1L;\n if (null != entries && entries.length > 0) {\n version = entries[0].getVersion();\n }\n this.eventContext.getLedger().dataAccount(Bytes.fromBase58(address)).setText(key, value, version);\n }\n \n public String registerUser(final String seed) {\n final CryptoAlgorithm algorithm = Crypto.getAlgorithm(\"ed25519\");\n final SignatureFunction signFunc = Crypto.getSignatureFunction(algorithm);\n final AsymmetricKeypair cryptoKeyPair = signFunc.generateKeypair(seed.getBytes());\n final BlockchainKeypair keypair = new BlockchainKeypair(cryptoKeyPair.getPubKey(), cryptoKeyPair.getPrivKey());\n this.eventContext.getLedger().users().register(keypair.getIdentity());\n return keypair.getAddress().toBase58();\n }\n \n public String registerDataAccount(final String seed) {\n final CryptoAlgorithm algorithm = Crypto.getAlgorithm(\"ed25519\");\n final SignatureFunction signFunc = Crypto.getSignatureFunction(algorithm);\n final AsymmetricKeypair cryptoKeyPair = signFunc.generateKeypair(seed.getBytes());\n final BlockchainKeypair keypair = new BlockchainKeypair(cryptoKeyPair.getPubKey(), cryptoKeyPair.getPrivKey());\n this.eventContext.getLedger().dataAccounts().register(keypair.getIdentity());\n return keypair.getAddress().toBase58();\n }\n \n public String registerEventAccount(final String seed) {\n final CryptoAlgorithm algorithm = Crypto.getAlgorithm(\"ed25519\");\n final SignatureFunction signFunc = Crypto.getSignatureFunction(algorithm);\n final AsymmetricKeypair cryptoKeyPair = signFunc.generateKeypair(seed.getBytes());\n final BlockchainKeypair keypair = new BlockchainKeypair(cryptoKeyPair.getPubKey(), cryptoKeyPair.getPrivKey());\n this.eventContext.getLedger().eventAccounts().register(keypair.getIdentity());\n return keypair.getAddress().toBase58();\n }\n \n public void publishEventWithSequence(final String address, final String topic, final String content, final long sequence) {\n this.eventContext.getLedger().eventAccount(Bytes.fromBase58(address)).publish(topic, content, sequence);\n }\n \n public void publishEvent(final String address, final String topic, final String content) {\n final Event event = this.eventContext.getUncommittedLedger().getLatestEvent(address, topic);\n long sequence = -1L;\n if (null != event) {\n sequence = event.getSequence();\n }\n this.eventContext.getLedger().eventAccount(Bytes.fromBase58(address)).publish(topic, content, sequence);\n }\n \n public void beforeEvent(final ContractEventContext eventContext) {\n this.eventContext = eventContext;\n }\n \n public void postEvent(final ContractEventContext eventContext, final Exception error) {\n }\n}\n", + "address" : { + "value" : "LdeNr7H1CUbqe3kWjwPwiqHcmd86zEQz2VRye" + }, + "headerRootHash" : "j5r72A4PMdDrAU4zhniJNRWM5nKV8kAKMdt6naNrtjRp3A", + "chainCodeVersion" : 0, + "pubKey" : "7VeRCfSaoBW3uRuvTqVb26PYTNwvQ1iZ5HBY92YKpEVN7Qht" + } +} +``` + +说明 + +|名称|说明| +|---|---| +|address.value|账户地址| +|pubKey|账户公钥| +|chainCode|合约源代码| + + + +## 9 用户自定义事件 + +### 9.1 获取事件账户列表 + +```http +GET /ledgers/{ledger}/events/user/accounts?fromIndex={fromIndex}&count={count} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|query|fromIndex|否|查询的起始序号，默认为0|数字| +|query|count|否|查询返回事件账户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/events/user/accounts?fromIndex=0&count=-1 +``` + +#### 返回实例 + +```json +{ + "data" : [ + { + "address" : { + "value" : "LdeNqYND7M82fxrej7ffRPXZwahQZEoUSoUzz" + }, + "pubKey" : "7VeRJe66QNfuacfSVPzTfXPooFcRmMJKXPYqkUsn4r9v8DqA" + }, + { + "pubKey" : "7VeRMwxWNcpMszstXtaxJ1fupauuJpwedB81nMJJQB93LiAJ", + "address" : { + "value" : "LdeNiAPuZ5tpYZVrrbELJNjqdvB51PBpNd8QA" + } + } + ], + "success" : true +} +``` + +说明 + +|名称|说明| +|---|---| +|address.value|账户地址| +|pubKey|账户公钥| + +### 9.2 获取事件账户 + +```http +GET /ledgers/{ledger}/events/user/accounts/{address} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|address|账户地址|是|事件账户地址|字符串| + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/events/user/accounts/LdeNqYND7M82fxrej7ffRPXZwahQZEoUSoUzz +``` + +#### 返回实例 + +```json +{ + "success" : true, + "data" : { + "address" : { + "value" : "LdeNqYND7M82fxrej7ffRPXZwahQZEoUSoUzz" + }, + "pubKey" : "7VeRJe66QNfuacfSVPzTfXPooFcRmMJKXPYqkUsn4r9v8DqA" + } +} +``` + +说明 + +|名称|说明| +|---|---| +|address.value|账户地址| +|pubKey|账户公钥| + +### 9.3 获取事件账户总数 + +```http +GET /ledgers/{ledger}/events/user/accounts/count +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/events/user/accounts/count +``` + +#### 返回实例 + +```json +{ + "success" : true, + "data" : 2 +} +``` + +说明 + +|名称|说明| +|---|---| +|data|事件账户数量| + +### 9.4 获取事件名数量 + +```http +GET /ledgers/{ledger}/events/user/accounts/{address}/names/count +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|address|是|事件账户地址|字符串| + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/events/user/accounts/LdeNiAPuZ5tpYZVrrbELJNjqdvB51PBpNd8QA/names/count +``` + +#### 返回实例 + +```json +{ + "data" : 5, + "success" : true +} +``` + +说明 + +|名称|说明| +|---|---| +|data|事件名数量| + +### 9.5 获取事件名列表 + +```http +GET /ledgers/{ledger}/events/user/accounts/{address}/names?fromIndex={fromIndex}&count={count} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|address|是|事件账户地址|字符串| +|query|fromIndex|否|查询的起始序号，默认为0|数字| +|query|count|否|查询返回事件账户的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/events/user/accounts/LdeNiAPuZ5tpYZVrrbELJNjqdvB51PBpNd8QA/names?fromIndex=0&count=-1 +``` + +#### 返回实例 + +```json +{ + "data" : [ + "topic4", + "topic3", + "topic", + "topic1", + "topic2" + ], + "success" : true +} +``` + +说明 + +|名称|说明| +|---|---| +|data|事件名数量数组| + +### 9.6 获取最新事件 + +```http +GET /ledgers/{ledger}/events/user/accounts/{address}/names/{event_name}/latest +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|address|是|事件账户地址|字符串| +|path|event_name|是|事件名|字符串| + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/events/user/accounts/LdeNiAPuZ5tpYZVrrbELJNjqdvB51PBpNd8QA/names/topic/latest +``` + +#### 返回实例 + +```json +{ + "success" : true, + "data" : { + "sequence" : 0, + "blockHeight" : 8, + "transactionSource" : "j5p868BwtU4w5BxG7gnuhQCFqpAgddVzTWNEKMAzZ8bnrF", + "eventAccount" : { + "value" : "LdeNiAPuZ5tpYZVrrbELJNjqdvB51PBpNd8QA" + }, + "name" : "topic", + "contractSource" : "", + "content" : { + "bytes" : { + "value" : "4mZ4ZZRGDZ" + }, + "nil" : false, + "value" : "content", + "type" : "TEXT" + } + } +} +``` + +说明 + +|名称|说明| +|---|---| +|sequence|事件序列| +|transactionSource|交易哈希| +|blockHeight|时间产生区块高度| +|contractSource|合约地址| +|eventAccount.value|事件账户地址| +|name|事件名| +|content.nil|事件内容是否为空| +|content.bytes.value|事件内容字节，BASE64编码| +|content.type|事件内容类型| +|content.value|事件内容| + +### 9.7 获取事件数量 + +```http +GET /ledgers/{ledger}/events/user/accounts/{address}/names/{event_name}/count +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|address|是|事件账户地址|字符串| +|path|event_name|是|事件名|字符串| + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/events/user/accounts/LdeP1yuk8Medq3Sph5ur9y1yE6nJ71XRVPPx1/names/topic/count +``` + +#### 返回实例 + +```json +{ + "data": 1, + "success": true +} +``` + +说明 + +|名称|说明| +|---|---| +|data|事件数量| + +### 9.8 获取事件列表 + +```http +GET /ledgers/{ledger}/events/user/accounts/{address}/names/{event_name}?fromSequence={fromSequence}&count={count} +``` + +#### 参数 + +|请求类型|名称|是否必需|说明|数据类型| +|---|---|---|---|---| +|path|ledger|是|账本哈希|字符串| +|path|address|是|事件账户地址|字符串| +|path|event_name|是|事件名|字符串| +|query|fromSequence|否|查询的起始序号，默认为0|数字| +|query|count|否|查询返回事件的数量，默认最大返回值为100，小于0或大于100均返回最大可返回结果集|数字| + + +#### 请求实例 +```http +http://localhost:8080/ledgers/j5hQrVB8y78xXbDR9vB92WBjiJShH36G7YLdQYsxtRxkpp/events/user/accounts/LdeNiAPuZ5tpYZVrrbELJNjqdvB51PBpNd8QA/names/topic?fromSequenct=0&count=-1 +``` + +#### 返回实例 + +```json +{ + "data" : [ + { + "content" : { + "value" : "content", + "nil" : false, + "type" : "TEXT", + "bytes" : { + "value" : "4mZ4ZZRGDZ" + } + }, + "eventAccount" : { + "value" : "LdeNiAPuZ5tpYZVrrbELJNjqdvB51PBpNd8QA" + }, + "contractSource" : "", + "name" : "topic", + "sequence" : 0, + "transactionSource" : "j5p868BwtU4w5BxG7gnuhQCFqpAgddVzTWNEKMAzZ8bnrF", + "blockHeight" : 8 + } + ], + "success" : true +} +``` + +说明 + +|名称|说明| +|---|---| +|data|事件列表| +|sequence|事件序列| +|transactionSource|交易哈希| +|blockHeight|时间产生区块高度| +|contractSource|合约地址| +|eventAccount.value|事件账户地址| +|name|事件名| +|content.nil|事件内容是否为空| +|content.bytes.value|事件内容字节，BASE64编码| +|content.type|事件内容类型| +|content.value|事件内容| \ No newline at end of file diff --git a/docs/block.md b/docs/block.md new file mode 100644 index 00000000..552f156c --- /dev/null +++ b/docs/block.md @@ -0,0 +1,80 @@ +## 区块 + +采用`BFT-SMaRt`共识协议，即时出块，单个区块交易数限制默认为`2000`（`bftsmart.config`中参数`system.totalordermulticast.maxbatchsize`） + +### 结构 + +- `LedgerBlock`: + +```java +@DataContract(code = DataCodes.BLOCK) +public interface LedgerBlock extends BlockBody { + + /** + * 区块哈希； + */ + @DataField(order = 1, primitiveType = PrimitiveType.BYTES) + HashDigest getHash(); + +} +``` + +- `BlockBody`: + +```java +@DataContract(code= DataCodes.BLOCK_BODY) +public interface BlockBody extends LedgerDataSnapshot{ + + // 上一个区块哈希 + @DataField(order=2, primitiveType = PrimitiveType.BYTES) + HashDigest getPreviousHash(); + + // 账本哈希 + @DataField(order=3, primitiveType = PrimitiveType.BYTES) + HashDigest getLedgerHash(); + + // 区块高度 + @DataField(order=4, primitiveType= PrimitiveType.INT64) + long getHeight(); + + // 交易数据集哈希 + @DataField(order=5, primitiveType = PrimitiveType.BYTES) + HashDigest getTransactionSetHash(); + + // 区块时间戳，毫秒 + @DataField(order=6, primitiveType = PrimitiveType.INT64) + long getTimestamp(); +} +``` + +- `LedgerDataSnapshot`: + +```java +@DataContract(code=DataCodes.DATA_SNAPSHOT) +public interface LedgerDataSnapshot { + + // 管理数据集哈希 + @DataField(order=1, primitiveType = PrimitiveType.BYTES) + HashDigest getAdminAccountHash(); + + // 用户集哈希 + @DataField(order=2, primitiveType = PrimitiveType.BYTES) + HashDigest getUserAccountSetHash(); + + // 数据账户集哈希 + @DataField(order=3, primitiveType = PrimitiveType.BYTES) + HashDigest getDataAccountSetHash(); + + // 合约集哈希 + @DataField(order=4, primitiveType = PrimitiveType.BYTES) + HashDigest getContractAccountSetHash(); + + // 系统事件集哈希 + @DataField(order=5, primitiveType = PrimitiveType.BYTES) + HashDigest getSystemEventSetHash(); + + // 用户事件集哈希 + @DataField(order=6, primitiveType = PrimitiveType.BYTES) + HashDigest getUserEventSetHash(); +} +``` \ No newline at end of file diff --git a/docs/cli/keys.md b/docs/cli/keys.md new file mode 100644 index 00000000..a3410b54 --- /dev/null +++ b/docs/cli/keys.md @@ -0,0 +1,120 @@ +### 密钥管理 + +`jdchain-cli`提供基于本地目录的密钥管理：[密钥对列表](#密钥对列表)，[添加密钥对](#添加密钥对)，[更新私钥密码](#更新私钥密码)，[删除密钥对](#删除密钥对) + +```bash +:bin$ ./jdchain-cli.sh keys -h +Usage: git status [...] [--] [...] +List, create, update or delete keypairs. + -h, --help Show this help message and exit. + --home= Set the home directory. + Default: ../ + --pretty Pretty json print + -V, --version Print version information and exit. +Commands: + list List all the keypairs. + add Create a new keypair. + update Update privkey password. + delete Delete keypair. + help Displays help information about the specified command +``` + +#### 密钥对列表 +```bash +:bin$ ./jdchain-cli.sh keys list -h +List all the keypairs. +Usage: jdchain-cli keys list [-hV] [--pretty] [--home=] + -h, --help Show this help message and exit. + --home= Set the home directory. + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `home`，指定密钥存储相关目录，`${home}/config/keys` + +如： +```bash +:bin$ ./jdchain-cli.sh keys list +NAME ALGORITHM ADDRESS PUBKEY +``` +- `NAME`，名称 +- `ALGORITHM`，算法 +- `ADDRESS`，地址 +- `PUBKEY`，公钥 + +#### 添加密钥对 +```bash +:bin$ ./jdchain-cli.sh keys add -h +Create a new keypair. +Usage: jdchain-cli keys add [-hV] [--pretty] [-a=] [--home=] + -n= + -a, --algorithm= + Crypto algorithm + -h, --help Show this help message and exit. + --home= Set the home directory. + -n, --name= Name of the key + --pretty Pretty json print + -V, --version Print version information and exit. +``` + +- `a`/`algorithm`，密钥算法：`SM2`，`ED25519`等，默认`ED25519` +- `name`，密钥对名称 + +如： +```bash +:bin$ ./jdchain-cli.sh keys add -n k1 +please input password: > +// 输入私钥密码 +1 +NAME ALGORITHM ADDRESS PUBKEY +k1 ED25519 LdeP1iczD3zpmcayKAxTfSywict9y2r6Jpq6n 7VeRBamwPeMb7jzTNg3Ap2DscBiy3QE3PK5NqBvv9tUjQVk4 +``` + +#### 更新私钥密码 + +```bash +:bin$ ./jdchain-cli.sh keys update -h +Update privkey password. +Usage: jdchain-cli keys update [-hV] [--pretty] [--home=] -n= + -h, --help Show this help message and exit. + --home= Set the home directory. + -n, --name= Name of the key + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `name`，密钥对名称 + +如： +```bash +:bin$ ./jdchain-cli.sh keys update -n k1 +input the current password: > +// 输入当前密码 +1 +input new password: > +// 输入新密码 +2 +NAME ALGORITHM ADDRESS PUBKEY +k1 ED25519 LdeP1iczD3zpmcayKAxTfSywict9y2r6Jpq6n 7VeRBamwPeMb7jzTNg3Ap2DscBiy3QE3PK5NqBvv9tUjQVk4 +``` + +#### 删除密钥对 + +```bash +:bin$ ./jdchain-cli.sh keys delete -h +Delete keypair. +Usage: jdchain-cli keys delete [-hV] [--pretty] [--home=] -n= + -h, --help Show this help message and exit. + --home= Set the home directory. + -n, --name= Name of the key + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `name`，密钥对名称 + +如： +```bash +:bin$ ./jdchain-cli.sh keys delete -n k1 +input the current password: > +// 输入当前密码 +2 +[k1] deleted +``` \ No newline at end of file diff --git a/docs/cli/participant.md b/docs/cli/participant.md new file mode 100644 index 00000000..0d23df02 --- /dev/null +++ b/docs/cli/participant.md @@ -0,0 +1,219 @@ +### 共识节点变更 + +借助`BFT-SMaRt`共识提供的Reconfig操作元语，`JD Chain`实现了在不停机的情况下快速更新共识网络拓扑，实现添加共识节点，移除共识节点，更新共识信息 等功能。 +```bash +:bin$ ./jdchain-cli.sh participant -h +Usage: jdchain-cli participant [-hV] [--pretty] [--home=] [COMMAND] +Add, update or delete participant. + -h, --help Show this help message and exit. + --home= Set the home directory. + Default: ../ + --pretty Pretty json print + -V, --version Print version information and exit. +Commands: + register Register new participant. + active Active participant. + update Update participant. + inactive Inactive participant. + help Displays help information about the specified command +``` +- `register` [注册新节点](#注册新节点) +- `active` [激活节点](#激活节点) +- `active` [更新节点](#更新节点) +- `inactive` [移除节点](#移除节点) + +#### 注册新节点 + +```bash +:bin$ ./jdchain-cli.sh participant register -h +Register new participant. +Usage: jdchain-cli participant register [-hV] [--pretty] [--gw-host=] + [--gw-port=] [--home=] + --name= + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --name= Name of the participant + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `name`，新节点名称 + +注册新节点： +```bash +:bin$ ./jdchain-cli.sh participant register --name node4 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +// 选择账本 +> 0 +// 选择待注册节点公私钥（链上必须不存在此公私钥对应的用户） +select keypair to register, input the index: +0 k1 LdeNq3862vtUCeptww1T5mVvLbAeppYqVNdqD +1 1627618939 LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw +2 node4 LdeNwG6ECEGz57o2ufhwSbnW4C35TvPqANK7T +2 +input password of the key: +> 1 +// 选择此交易签名用户（必须是链上存在的用户，且有相应操作权限） +select keypair to sign tx, input the index: +0 k1 LdeNq3862vtUCeptww1T5mVvLbAeppYqVNdqD +1 1627618939 LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw +2 node4 LdeNwG6ECEGz57o2ufhwSbnW4C35TvPqANK7T +1 +input password of the key: +> 1 +register participant: [LdeNwG6ECEGz57o2ufhwSbnW4C35TvPqANK7T] +``` +成功在账本`j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg`中注册了新的节点`LdeNwG6ECEGz57o2ufhwSbnW4C35TvPqANK7T` + +可通过[共识节点列表](query.md#共识节点列表)查看新的账本列表： +```bash +:bin$ ./jdchain-cli.sh query participants +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +[{"address":"LdeNwsiuo7n6HULWhNKc87PBXJXAfGKFon9RE","id":2,"name":"2","participantNodeState":"CONSENSUS","pubKey":"7VeRFF1ednwhrFoe5cngKwPUJ2N4iFKD9Jt53GxSCc1MmPQ6"},{"address":"LdeNiXZbsBCsTc2ZGp1PGBX81aUxPekhwEwmY","id":1,"name":"1","participantNodeState":"CONSENSUS","pubKey":"7VeREmuT4fF9yRPEMbSSaNLKbLa3qoTpfGHRgwpnSWUn5tqW"},{"address":"LdeNwG6ECEGz57o2ufhwSbnW4C35TvPqANK7T","id":4,"name":"node4","participantNodeState":"READY","pubKey":"7VeRKiWHcHjNoYH9kJk2fxoJxgBrstVJ7bHRecKewJAKcvUD"},{"address":"LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw","id":0,"name":"0","participantNodeState":"CONSENSUS","pubKey":"7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn"},{"address":"LdeP2ji8PR1DPsLt5NoFeiBnhpckrLHgCJge6","id":3,"name":"3","participantNodeState":"CONSENSUS","pubKey":"7VeRGE4V9MR7HgAqTrkxGvJvaaKRZ3fAjHUjYzpNBGcjfAvr"}] +register participant: [LdeNwG6ECEGz57o2ufhwSbnW4C35TvPqANK7T] +``` +可以看出`node4`注册成功，地址为`LdeNwG6ECEGz57o2ufhwSbnW4C35TvPqANK7T` + +#### 激活节点 + +激活节点前请正确配置并启动新节点，以下以刚注册成功的`node4`为例 + +1. 配置`node4` + +解压`peer`压缩包，复制待加入账本其他节点中数据最新的节点数据库数据，然后修改`config/ledger-binding.conf`： +```bash +# Base58编码的账本哈希 +ledger.bindings=<账本hash> +# 账本名字，与账本相关的其他其他peer保持一致 +binding.<账本HASH>.name=<节点名称> +# peer4的名名称，与[向现有共识网络注册新的参与方]操作中保持一致 +binding.<账本hash>.parti.name=<节点名称> +# peer4的用户地址 +binding.<账本hash>.parti.address= +# 新参与方base58编码的私钥，与[向现有共识网络注册新的参与方]操作中保持一致 +binding.<账本hash>.parti.pk=<新参与方base58编码的私钥> +# 新参与方base58编码的私钥读取密码，与[向现有共识网络注册新的参与方]操作中保持一致 +binding.<账本hash>.parti.pwd=<新参与方base58编码的私钥读取密码> +# 新参与方对应的账本数据库连接uri，即peer4的账本数据库存放位置，参照其他peer修改，不可与其他peer混用 +binding.<账本hash>.db.uri=<账本数据库连接> +``` + +2. 启动`node4` +| **一定注意在启动新参与方节点进程之前确保完成了账本数据库的复制工作** + +执行`peer4`中`bin`目录下`peer-startup.sh`脚本启动启动新参与方`peer4`节点进程： +```bash +./peer-startup.sh +``` + +3. 激活新节点 +```bash +:bin$ ./jdchain-cli.sh participant active -h +Active participant. +Usage: jdchain-cli participant active [-hV] [--pretty] [--shutdown] + --consensus-port= + [--home=] --host= + --ledger= --port= + --syn-host= --syn-port= + --consensus-port= + Set the participant consensus port. + -h, --help Show this help message and exit. + --home= Set the home directory. + --host= Set the participant host. + --ledger= Set the ledger. + --port= Set the participant service port. + --pretty Pretty json print + --shutdown Restart the node server. + --syn-host= Set synchronization participant host. + --syn-port= Set synchronization participant port. + -V, --version Print version information and exit. +``` +- `ledger`，账本哈希 +- `host`，新节点地址 +- `port`，新节点服务端口 +- `consensus-port`，新节点共识端口 +- `syn-host`，数据同步节点地址 +- `syn-port`，数据同步节点服务端口 + +在账本`j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg`中激活`node4`（以步骤2中启动的服务地址和端口为`127.0.0.1`和`7084`例），共识端口设置为`10088`，同步节点地址和端口为`127.0.0.1`和`7080`为例： +```bash +./jdchain-cli.sh participant active --ledger j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg --host 127.0.0.1 --port 7084 --consensus-port 10088 --syn-host 127.0.0.1 --syn-port 7080 +participant activated +``` + +成功后可通过[共识节点列表](query.md#共识节点列表)查询最新共识节点列表状态，`node4`为`CONSENSUS` + +#### 更新节点 + +通过[激活节点](#激活节点)操作除了激活新增的节点外，还可以动态修改已经处于激活状态的共识节点的`IP`和`共识端口`信息，从而实现本机的共识端口变更，不同机器之间进行`账本迁移`。 + +| **在进行节点信息变更时，要求暂停向共识网络中发起新的业务数据上链请求** + +1. 变更共识端口 + +| **操作前请确保变更到的端口未被占用** + +如将`node4`共识端口由`10088`修改为`10188`，操作指令如下： + +```bash +./jdchain-cli.sh participant update --ledger j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg --host 127.0.0.1 --port 7084 --consensus-port 10188 --syn-host 127.0.0.1 --syn-port 7080 +participant updated +``` +指令成功执行后，`peer1`的共识端口将自动变更为`10188` + +2. 账本迁移 + +账本迁移指将一台机器（`IP`）上的共识节点迁移到另一台机器（`IP`）上，主要操作流程如下： + +| **操作前请确保变更到的端口未被占用** + +如将`node4`共识`IP`由`127.0.0.1`修改为`192.168.1.100`（另一台机器），操作指令如下： + +```bash +./jdchain-cli.sh participant update --ledger j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg --host 192.168.1.100 --port 7084 --consensus-port 10188 --syn-host 127.0.0.1 --syn-port 7080 -shutdown +participant updated +``` + +**特别注意**：`-shutdown`会停止当前运行的当前账本共识服务，为必填选项，否则可能将导致整个网络需要重启。 + +#### 移除节点 + +``` +:bin$ ./jdchain-cli.sh participant inactive -h +Inactive participant. +Usage: jdchain-cli participant inactive [-hV] [--pretty] --address=
+ [--home=] --host= + --ledger= --port= + --syn-host= + --syn-port= + --address=
Set the participant address. + -h, --help Show this help message and exit. + --home= Set the home directory. + --host= Set the participant host. + --ledger= Set the ledger. + --port= Set the participant service port. + --pretty Pretty json print + --syn-host= Set synchronization participant host. + --syn-port= Set synchronization participant port. + -V, --version Print version information and exit. +``` +- `ledger`，账本哈希 +- `address`，待移除节点共识端口 +- `host`，待移除节点服务地址 +- `port`，待移除节点服务端口 +- `syn-host`，数据同步节点地址 +- `syn-port`，数据同步节点服务端口 + +如移除`node4`： +```bash +:bin$ ./jdchain-cli.sh participant inactive --ledger j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg --address LdeNwG6ECEGz57o2ufhwSbnW4C35TvPqANK7T --host 127.0.0.1 --port 7084 --syn-host 127.0.0.1 --syn-port 7080 +participant inactivated +``` + +成功后可通过[共识节点列表](query.md#共识节点列表)查询最新共识节点列表状态，`node4`为`DEACTIVATED` \ No newline at end of file diff --git a/docs/cli/query.md b/docs/cli/query.md new file mode 100644 index 00000000..87e36020 --- /dev/null +++ b/docs/cli/query.md @@ -0,0 +1,914 @@ +### 链上信息查询 + +```bash +:bin$ ./jdchain-cli.sh query -h +Usage: jdchain-cli query [-hV] [--pretty] [--gw-host=] + [--gw-port=] [--home=] [COMMAND] +Query commands. + --gw-host= Set the gateway host. Default: 127.0.0.1 + Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + Default: ../ + --pretty Pretty json print + -V, --version Print version information and exit. +Commands: + ledgers Query ledgers. + ledger Query ledger. + participants Query participants. + block Query block. + txs-count Query transactions count. + txs Query transactions. + tx Query transaction. + users Query users. + users-count Query users count. + user Query user. + role-privileges Query role privileges. + user-privileges Query user privileges. + data-accounts-count Query data accounts count. + data-accounts Query data accounts. + data-account Query data account. + kvs-count Query key-values count. + kvs Query kvs. + kv Query kv. + user-event-accounts-count Query user event accounts count. + user-event-accounts Query user event accounts. + user-event-account Query user event account. + user-event-names-count Query user event names count. + user-event-names Query user event names. + user-events-count Query user events count. + user-events Query user events. + latest-user-event Query latest user event. + contracts-count Query contracts count. + contracts Query contracts. + contract Query contract. + help Displays help information about the specified command +``` +查询命令：[账本列表](#账本列表)，[账本详情](#账本详情)，[共识节点列表](#共识节点列表)，[区块详情](#区块详情)，[交易总数](#交易总数)，[交易列表](#交易列表)，[交易详情](#交易详情)，[用户总数](#用户总数)，[用户列表](#用户列表)，[用户详情](#用户详情)，[角色权限](#角色权限)，[用户权限](#用户权限)，[数据账户总数](#数据账户总数)，[数据账户列表](#数据账户列表)，[数据账户详情](#数据账户详情)，[KV总数](#KV总数)，[KV列表](#KV列表)，[KV详情](#KV详情)，[用户事件账户总数](#用户事件账户总数)，[用户事件账户列表](#用户事件账户列表)，[用户事件账户详情](#用户事件账户详情)，[用户事件名总数](#用户事件名总数)，[用户事件名列表](#用户事件名列表)，[用户事件总数](#用户事件总数)，[用户事件列表](#用户事件列表)，[最新用户事件](#最新用户事件)，[合约总数](#合约总数)，[合约列表](#合约列表)，[合约详情](#合约详情) + +#### 账本列表 + +```bash +:bin$ ./jdchain-cli.sh query ledgers +j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +``` +返回当前网关服务所有账本列表 + +#### 账本详情 + +选择账本，打印当前账本详细信息： +```bash +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +{"hash":"j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg","latestBlockHash":"j5n8KGMFsRM7jzf99XK1jDK342fauj3myKcdgPJyLYyxws","latestBlockHeight":18} +``` + +可添加`--pretty`格式化输出`json`数据 + +#### 共识节点列表 + +查询共识节点列表： +```bash +:bin$ ./jdchain-cli.sh query participants +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +[{"address":"LdeNwsiuo7n6HULWhNKc87PBXJXAfGKFon9RE","id":2,"name":"2","participantNodeState":"CONSENSUS","pubKey":"7VeRFF1ednwhrFoe5cngKwPUJ2N4iFKD9Jt53GxSCc1MmPQ6"},{"address":"LdeNiXZbsBCsTc2ZGp1PGBX81aUxPekhwEwmY","id":1,"name":"1","participantNodeState":"CONSENSUS","pubKey":"7VeREmuT4fF9yRPEMbSSaNLKbLa3qoTpfGHRgwpnSWUn5tqW"},{"address":"LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw","id":0,"name":"0","participantNodeState":"CONSENSUS","pubKey":"7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn"},{"address":"LdeP2ji8PR1DPsLt5NoFeiBnhpckrLHgCJge6","id":3,"name":"3","participantNodeState":"CONSENSUS","pubKey":"7VeRGE4V9MR7HgAqTrkxGvJvaaKRZ3fAjHUjYzpNBGcjfAvr"}] +``` +账本`j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg`中有四个共识节点，均为`CONSENSUS`状态 + +#### 区块详情 + +```bash +:bin$ ./jdchain-cli.sh query block -h +Query block. +Usage: jdchain-cli query block [-hV] [--pretty] [--gw-host=] + [--gw-port=] [--hash=] + [--height=] [--home=] + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --hash= Block hash + --height= Block height. + --home= Set the home directory. + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `height`，区块高度，默认`-1`查询当前最高区块 + +如： +```bash +:bin$ ./jdchain-cli.sh query block --pretty +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +{ + "adminAccountHash":"j5p5z4es9RPrQWFu2nSJBQFT68byeGqAdUDu63qa5xV8Df", + "contractAccountSetHash":"j5kbvGQ1tFH2GXgk8ThF1co7H2gCrFdeZn7Nibva7Md72P", + "dataAccountSetHash":"j5fSmQkk8tb9v9SYDmaAko3oJJqmCm54HGbQwgbV2nTCVk", + "hash":"j5n8KGMFsRM7jzf99XK1jDK342fauj3myKcdgPJyLYyxws", + "height":18, + "ledgerHash":"j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg", + "previousHash":"j5motWQdmckqTxkG3x8DcE6quv2oGteKzsHqoV89Lfo4Mj", + "timestamp":1627703544928, + "transactionSetHash":"j5rc9PV5p9C8mXDAt8p9MR4QY3VAr4wQNG7zC3MSvFpcGG", + "userAccountSetHash":"j5haZvthy9gGaJ8M3mEbwtpeUg9Z113ifZbcWtzAeQcQdu", + "userEventSetHash":"j5nke9ZAnVRf1Qgg4u9Ske8RoZFbFVzVrKQid14qcqXaAn" +} +``` +返回当前最高区块详情 + +#### 交易总数 + +```bash +:bin$ ./jdchain-cli.sh query txs-count -h +Query transactions count. +Usage: jdchain-cli query txs-count [-hV] [--in-block] [--pretty] + [--gw-host=] [--gw-port=] + --height= [--home=] + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --height= Block height. + --home= Set the home directory. + --in-block In the given block. + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `height`，区块高度 +- `in-block`，是否只统计`height`参数指定区块数据 + +如查询高度`10`区块交易总数（会统计区块`0-10`内所有交易）： +```bash +:bin$ ./jdchain-cli.sh query txs-count --height 10 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +11 +``` + +查询高度`10`区块内交易总数（仅统计区块`10`交易）： +```bash +:bin$ ./jdchain-cli.sh query txs-count --height 10 --in-block +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +1 +``` + +#### 交易列表 + +```bash +:bin$ ./jdchain-cli.sh query txs -h +Query transactions. +Usage: jdchain-cli query txs [-hV] [--in-block] [--pretty] --count= + [--gw-host=] [--gw-port=] + [--height=] [--home=] --index= + --count= Transaction item count + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --height= Block height. + --home= Set the home directory. + --in-block In the given block. + --index= Transaction item index + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `height`，区块高度 +- `in-block`，是否只统计`height`参数指定区块数据 +- `index`，查询起始位置 +- `count`，最大返回 + +如查询高度`10`区块交易列表（会统计区块`0-10`内所有交易），从第`0`条开始，最大返回`1`条： +```bash +:bin$ ./jdchain-cli.sh query txs --height 10 --index 0 --count 1 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +[{"request":{"endpointSignatures":[],"nodeSignatures":[{"digest":"SMHYntB7uTm3N4mReke4srWHhpDkjDFGRuz7Bis8quJt19igevwA4rEwNmZqFGGLMExgmrPvdGrxgRrhLhpxUo1KGW","pubKey":"7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn"},{"digest":"SMHbyCLcvds5sRKaWPptSjixxoaiwkQfM1noLGpLSvsmxwUSg4J55UhJtK1ZWiQp3rxy5FEMZpwHGkywexYuwXEWHo","pubKey":"7VeREmuT4fF9yRPEMbSSaNLKbLa3qoTpfGHRgwpnSWUn5tqW"},{"digest":"SMGP3a7GHW6qWbQY3ZXX5UBhHNFLrSkUzRLLfCFA9Gu6CJVoYVvBQjjCEzaYq9ox38DvyZJQFuLWPirV2G6VMeARqQ","pubKey":"7VeRFF1ednwhrFoe5cngKwPUJ2N4iFKD9Jt53GxSCc1MmPQ6"},{"digest":"SMHGzmEVzZPKyvN3zC6nLbVypufWEfd6cFvnMMjuEXFk5WncLeUx4CyAohTnNLP21ksJ6r15usowbkRFeaUYQgJkre","pubKey":"7VeRGE4V9MR7HgAqTrkxGvJvaaKRZ3fAjHUjYzpNBGcjfAvr"}],"transactionContent":{"operations":[{"@type":"com.jd.blockchain.ledger.LedgerInitOperation","initSetting":{"consensusParticipants":[{"address":"LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw","id":0,"name":"0","participantNodeState":"CONSENSUS","pubKey":"7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn"},{"address":"LdeNiXZbsBCsTc2ZGp1PGBX81aUxPekhwEwmY","id":1,"name":"1","participantNodeState":"CONSENSUS","pubKey":"7VeREmuT4fF9yRPEMbSSaNLKbLa3qoTpfGHRgwpnSWUn5tqW"},{"address":"LdeNwsiuo7n6HULWhNKc87PBXJXAfGKFon9RE","id":2,"name":"2","participantNodeState":"CONSENSUS","pubKey":"7VeRFF1ednwhrFoe5cngKwPUJ2N4iFKD9Jt53GxSCc1MmPQ6"},{"address":"LdeP2ji8PR1DPsLt5NoFeiBnhpckrLHgCJge6","id":3,"name":"3","participantNodeState":"CONSENSUS","pubKey":"7VeRGE4V9MR7HgAqTrkxGvJvaaKRZ3fAjHUjYzpNBGcjfAvr"}],"consensusProvider":"com.jd.blockchain.consensus.bftsmart.BftsmartConsensusProvider","consensusSettings":"115kLavjaNTn9Grf9orxPmABexqr5Dvac5LEyhWXbQCd4vEScsxxGTEtyrgDfCwLsNBGYQBj8UGkEPCZNsWNMrH8H2naZUsszwbwnSka6jgahxJepH6jDRMP4X31qxksorr23dpwfemhezwVUbTNyvu54HW76wmtvAyCk7m3DKE1CJhLtDTXAWt8LjqE3xhNXfKZJLT2np69nKDqi41hGVYjZfPz4ZmUzuo34ae3syvgKDPYJCNscSP7UoJgvk142x7ggy8KX2bbENZSUSdbV9qLzPDfsdnkLFDzyDJjd6wMxdzV4Tb9fh5WvkciYyh1SE2Ew7peoaLmUDEULd9LKCKmJYXhPCmbbjxecLYvtcUoarGMHKpHKxDAQZjsX3ik5o8B1WwnQG8VazZEZbepDVtX8p1T7TGryXJUZfGZ6ajKX8shE2PpvkjWTMXgW1ebwPKLziqpzxcBLy1pBTtwztgnexbzCGCUYTgS9FiEfn3aRuhHKhzHfAe6gH6Lkk4PQWeAKScPrG1PzQKNRpxJfxZJV3ZBEesDvV85i2HT829tvATUfdUK8s5Zhy9TT33ZrkkC3QWH6saFBCCHyq9gUGrMgWXi5jn5D2GqNwWFJSvDXRNzYArvqkcqCB5gzfP23kYq9RKVvonvtmhww5hdLGzHdSU19dghHkyvbYi4VSFT57QQET7z7qvQYSNxDbCWNfn2osNipdMmFWY7AVetZvkowQPEZqr5xYV8j9pawam4WETomeeEPb11BhXXmyBbhuJx3xpNPcfFHE2Y52NcM7LdLxpmkdBgpFTdLh5Y3mGup6opJWp8WzXzi5zHsM5eXxyfq2uQ9ttQB5KPwTi1wgAskDdcgYRtH3MmVMB1MBHVAGAu2asZpRWXnZT39iPzshzJRck1PC2yhiYq8We5wfMgoA4KDPxp55wwWNtPpC1fBpjsNuLtqiHYSdZxTy32dASA1Zmm3XPFhPm6vcbCcod2n4uUSK2Vv9gMtzVVmprstVoB47whfhvgerfPiHMEJemeG5sF5vKcxMrpAxZtM4sHNMJf9xPucMTUzyWcSbyvSsRshFjnHRAEhSGHSCzRrjsTiLo2KZyLrzyBBc6DqdwdNC1RnmgirS1baaL2xTg3jkQystmH5VNJ5EQRVPqKQeSDXw9tUAHqMyknmL4zdZJjkfnw7rRXueQayHsfH4FGodGoNxJdYkbyjrYyrQZM8BeCLYHEqEyxKyAJHGm2kt96Cj8v6z9Ezv6CRh8ZZgnQBSvVvWtK1NWmjA1ZAf6fNv3KAEUsXfM6fy37HrThd9tqH32S25b3GeFJh8evnVou33hqK7JNwEk6o4ymwNWjuWMzqjp4Ag7jrFe5h5HG1J8NZg1KZKLvK2PChyR1oyNz1dH6RkguEz6XENhWLnmiuzPPbN4RrXSWWbgtjjbgM7megLEB5J8AqBnKR7RM1Gt3KB41xQx1F3yLCkhVXwYFUijdMtCNwCQKdBRSB9K6fBoSXbFcxzBFhNVc4x6g3CdZzC8F2Yewa1eZubcsZYyeVCSX6x1wBeocpZwsy2b9KxTQevuHuhJ1fpLjTLBFcfqbaC3NxGr2Q391fPzUsNTNvybsh7vySRyFtskYJ4ZJnUrviHUgnk7AbsBjKMxweaMur3ykm5dGgvTJT2EgbuqCNFPpcV2w1v6fFnALYMipvHWtszY4JSC8T5JERVhttBY9esq1dzoddpMNuKJvqkASaRDADJ6muMjDgXUeYkNtqftCohLxNPz4r49jbmeaFJgqdNCWEbdE4SqBeJpLjsUUfcpeNRXmJkCD8G9kV4njBniJP5pgoU1CDNYjDgAjvXx6kzSnEmtYGdzRCbmkUUPEJaXMVi3UnjmbRWcnkt979xwepW7KyhpvrWmxHrsqge6YfPLNbfNB5xohVuAbQkJgS5b1S8SJGDs1DEG1hxzEpby4HVBDehyzUZjSKKfJeh3NzkJ9khswYJ5jCZgjrwndf8kLKNbgVpTxoipSVPyswavLpE6BQ271GHatniVZFyRqFD4NnZ6a9LvwB5LdfRziXoUUF6wejAx7oy6yw5bF1LzAuZogAjRVbGXZ2wR4LYf4FszM8R2G6UEzNGW3jiXNG7iUJJV1orfjgdJHAFh2miDojxi3iRL1WnQSuYcj5jtse85m2iMWsB7USrMoFzkSuh7ST4VoNvLEr2SugYxuek8pcVCKvKiBbZXTwEEDSh59R2cYSZJ6uGSKy2BJyizb3ShUdbp8gMzVN9jdbDnTkfFyz8jzySes58gs8M8J9m4P1cxNYNXm7aZLroUZhw2iUS5tzq5ttxYVT7oQoBUrQiAwfzGv55Pbthbq4A7NaiihbhUHFGAFpkmLM9T4vMWsi7","createdTime":1627618941000,"cryptoSetting":{"autoVerifyHash":true,"hashAlgorithm":8216,"supportedProviders":[{"algorithms":[{},{},{},{},{},{},{}],"name":"com.jd.blockchain.crypto.service.classic.ClassicCryptoService"},{"algorithms":[{},{},{}],"name":"com.jd.blockchain.crypto.service.sm.SMCryptoService"}]},"ledgerSeed":"kULN7uzXyZuC7rD9BMLIgA==","ledgerStructureVersion":-1}},{"@type":"com.jd.blockchain.ledger.UserRegisterOperation","userID":{"address":"LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw","pubKey":"7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn"}},{"@type":"com.jd.blockchain.ledger.UserRegisterOperation","userID":{"address":"LdeNiXZbsBCsTc2ZGp1PGBX81aUxPekhwEwmY","pubKey":"7VeREmuT4fF9yRPEMbSSaNLKbLa3qoTpfGHRgwpnSWUn5tqW"}},{"@type":"com.jd.blockchain.ledger.UserRegisterOperation","userID":{"address":"LdeNwsiuo7n6HULWhNKc87PBXJXAfGKFon9RE","pubKey":"7VeRFF1ednwhrFoe5cngKwPUJ2N4iFKD9Jt53GxSCc1MmPQ6"}},{"@type":"com.jd.blockchain.ledger.UserRegisterOperation","userID":{"address":"LdeP2ji8PR1DPsLt5NoFeiBnhpckrLHgCJge6","pubKey":"7VeRGE4V9MR7HgAqTrkxGvJvaaKRZ3fAjHUjYzpNBGcjfAvr"}},{"@type":"com.jd.blockchain.ledger.RolesConfigureOperation","roles":[{"disableLedgerPermissions":[],"disableTransactionPermissions":[],"enableLedgerPermissions":["CONFIGURE_ROLES","AUTHORIZE_USER_ROLES","SET_CONSENSUS","SET_CRYPTO","REGISTER_PARTICIPANT","REGISTER_USER","REGISTER_DATA_ACCOUNT","REGISTER_CONTRACT","UPGRADE_CONTRACT","SET_USER_ATTRIBUTES","WRITE_DATA_ACCOUNT","APPROVE_TX","CONSENSUS_TX","REGISTER_EVENT_ACCOUNT","WRITE_EVENT_ACCOUNT"],"enableTransactionPermissions":["DIRECT_OPERATION","CONTRACT_OPERATION"],"roleName":"DEFAULT"}]},{"@type":"com.jd.blockchain.ledger.UserAuthorizeOperation","userRolesAuthorizations":[{"authorizedRoles":[],"policy":"UNION","unauthorizedRoles":[],"userAddresses":["LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw"]}]},{"@type":"com.jd.blockchain.ledger.UserAuthorizeOperation","userRolesAuthorizations":[{"authorizedRoles":[],"policy":"UNION","unauthorizedRoles":[],"userAddresses":["LdeNiXZbsBCsTc2ZGp1PGBX81aUxPekhwEwmY"]}]},{"@type":"com.jd.blockchain.ledger.UserAuthorizeOperation","userRolesAuthorizations":[{"authorizedRoles":[],"policy":"UNION","unauthorizedRoles":[],"userAddresses":["LdeNwsiuo7n6HULWhNKc87PBXJXAfGKFon9RE"]}]},{"@type":"com.jd.blockchain.ledger.UserAuthorizeOperation","userRolesAuthorizations":[{"authorizedRoles":[],"policy":"UNION","unauthorizedRoles":[],"userAddresses":["LdeP2ji8PR1DPsLt5NoFeiBnhpckrLHgCJge6"]}]}],"timestamp":1627618941000},"transactionHash":"j5vJGDBQLi6Vo5Gxtsab1vyL2TFaf1NoXDi6Xv2uvCcj9T"},"result":{"blockHeight":0,"dataSnapshot":{"adminAccountHash":"j5u4gqeAkKb3DoELpXP9bDgAxCVRQgKsguPvE1Wc9re1UT","userAccountSetHash":"j5hzkPPBJAqKs4rLWbEiFhbh1VW6Jc2xk878X5A6JywPnC"},"executionState":"SUCCESS","transactionHash":"j5vJGDBQLi6Vo5Gxtsab1vyL2TFaf1NoXDi6Xv2uvCcj9T"}}] +``` + +查询高度`10`区块内交易列表（仅统计区块`10`交易），从第`0`条开始，最大返回`1`： +```bash +:bin$ ./jdchain-cli.sh query txs --height 10 --index 0 --count 1 --in-block +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +[{"request":{"endpointSignatures":[{"digest":"SMKgce34AxQ8JEDDZY3x7iMvbL5QymiC93XPWqSirUB2AN8rvx18ynDS9f1zFA6QyXQNowA1XNhaLWnArrt7JHHxhY","pubKey":"7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn"}],"nodeSignatures":[{"digest":"SMKgce34AxQ8JEDDZY3x7iMvbL5QymiC93XPWqSirUB2AN8rvx18ynDS9f1zFA6QyXQNowA1XNhaLWnArrt7JHHxhY","pubKey":"7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn"}],"transactionContent":{"ledgerHash":"j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg","operations":[{"@type":"com.jd.blockchain.ledger.DataAccountKVSetOperation","accountAddress":"LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC","writeSet":[{"expectedVersion":-1,"key":"k1","value":{"bytes":"djE=","type":"TEXT"}}]}],"timestamp":1627632026435},"transactionHash":"j5fo2aAwp2tsneHm4wE8AnWLV7CKyax7BLWJqJm2V3WsrD"},"result":{"blockHeight":10,"dataSnapshot":{"adminAccountHash":"j5p5z4es9RPrQWFu2nSJBQFT68byeGqAdUDu63qa5xV8Df","dataAccountSetHash":"j5fSmQkk8tb9v9SYDmaAko3oJJqmCm54HGbQwgbV2nTCVk","userAccountSetHash":"j5mwiewVaxPLYQciovrB9nShWD5nr7YYFopbmWx28jqiFH","userEventSetHash":"j5wf9v6ixDDSD2gRi47r3vomkmTaRCqSLNbaNxrKcVdtD7"},"executionState":"SUCCESS","transactionHash":"j5fo2aAwp2tsneHm4wE8AnWLV7CKyax7BLWJqJm2V3WsrD"}}] +``` + +#### 交易详情 + +```bash +e:bin$ ./jdchain-cli.sh query tx -h +Query transaction. +Usage: jdchain-cli query tx [-hV] [--pretty] [--gw-host=] + [--gw-port=] [--hash=] [--home=] + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --hash= Transaction hash + --home= Set the home directory. + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `hash`，交易哈希 + +如查询交易`j5fo2aAwp2tsneHm4wE8AnWLV7CKyax7BLWJqJm2V3WsrD`详情： +```bash +:bin$ ./jdchain-cli.sh query tx --hash j5fo2aAwp2tsneHm4wE8AnWLV7CKyax7BLWJqJm2V3WsrD +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +{"request":{"endpointSignatures":[{"digest":"SMKgce34AxQ8JEDDZY3x7iMvbL5QymiC93XPWqSirUB2AN8rvx18ynDS9f1zFA6QyXQNowA1XNhaLWnArrt7JHHxhY","pubKey":"7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn"}],"nodeSignatures":[{"digest":"SMKgce34AxQ8JEDDZY3x7iMvbL5QymiC93XPWqSirUB2AN8rvx18ynDS9f1zFA6QyXQNowA1XNhaLWnArrt7JHHxhY","pubKey":"7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn"}],"transactionContent":{"ledgerHash":"j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg","operations":[{"@type":"com.jd.blockchain.ledger.DataAccountKVSetOperation","accountAddress":"LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC","writeSet":[{"expectedVersion":-1,"key":"k1","value":{"bytes":"djE=","type":"TEXT"}}]}],"timestamp":1627632026435},"transactionHash":"j5fo2aAwp2tsneHm4wE8AnWLV7CKyax7BLWJqJm2V3WsrD"},"result":{"blockHeight":10,"dataSnapshot":{"adminAccountHash":"j5p5z4es9RPrQWFu2nSJBQFT68byeGqAdUDu63qa5xV8Df","dataAccountSetHash":"j5fSmQkk8tb9v9SYDmaAko3oJJqmCm54HGbQwgbV2nTCVk","userAccountSetHash":"j5mwiewVaxPLYQciovrB9nShWD5nr7YYFopbmWx28jqiFH","userEventSetHash":"j5wf9v6ixDDSD2gRi47r3vomkmTaRCqSLNbaNxrKcVdtD7"},"executionState":"SUCCESS","transactionHash":"j5fo2aAwp2tsneHm4wE8AnWLV7CKyax7BLWJqJm2V3WsrD"}} +``` + +#### 用户总数 + +查询用户总数： +```bash +:bin$ ./jdchain-cli.sh query users-count +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +10 +``` +当前区块链网络共有`10`个用户 + +#### 用户列表 + +```bash +:bin$ ./jdchain-cli.sh query users -h +Query users. +Usage: jdchain-cli query users [-hV] [--pretty] --count= + [--gw-host=] [--gw-port=] + [--home=] --index= + --count= User item count + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --index= User item index + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `index`，起始位置 +- `count`，最大返回 + +如分页查询用户列表，从第`0`个开始，最大返回`10`条： +```bash +:bin$ ./jdchain-cli.sh query users --index 0 --count 10 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +ADDRESS PUBKEY +LdeP2ji8PR1DPsLt5NoFeiBnhpckrLHgCJge6 7VeRGE4V9MR7HgAqTrkxGvJvaaKRZ3fAjHUjYzpNBGcjfAvr +LdeNq3862vtUCeptww1T5mVvLbAeppYqVNdqD 7VeRGuwP2iUykAL4beftP1DuDTj7y2uFGEM6mx3Dy7YSm2j1 +LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC 7VeRFk4ANQHjWjAmAoL7492fuykTpXujihJeAgbXT2J9H9Yk +LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw 7VeRJpb2XX8XKAaC7G5zQg9DbgKM8gmLhUBtGFmerFbhJTZn +LdeNwTWpyzqioLURrHQuoGcnwA6YLiFWn3LNn 7VeRH7BsRntvJmomjw7YvF5HZVsSMb48GKzPnAP7iekRCLGq +LdeNiXZbsBCsTc2ZGp1PGBX81aUxPekhwEwmY 7VeREmuT4fF9yRPEMbSSaNLKbLa3qoTpfGHRgwpnSWUn5tqW +LdeNisM5oTypwPYv9tnhFNosRjCyXzzViU4SA 7VeREyEcDcY85DRdWAEsmJ4Moh89eE21AU2LEDbYG3t3MrGo +LdeNqvSjL4izfpMNsGpQiBpTBse4g6qLxZ6j5 7VeRFd2LB8ZmYnVNc2pux5TwVqHv3pwT6JXoF3fzDon9bSXK +LdeNwsiuo7n6HULWhNKc87PBXJXAfGKFon9RE 7VeRFF1ednwhrFoe5cngKwPUJ2N4iFKD9Jt53GxSCc1MmPQ6 +LdeNufGZewrvS7sE4VWC9m1SFkPqVwjBN87LB 7VeRMGBMMBQVoZQTU3mcJYGgbVcQzxXiq6NK69TaCjEoktLf +``` +返回`10`个用户的地址和公私钥信息 + +| 由于`JD Chain`网络并不保证用户（数据账户/事件账户/合约账户）按创建顺序排列，所以当有新的用户注册后，前后两次相同参数的查询数据可能不一致！！！ + +#### 用户详情 + +```bash +:bin$ ./jdchain-cli.sh query user -h +Query user. +Usage: jdchain-cli query user [-hV] [--pretty] --address=
+ [--gw-host=] [--gw-port=] + [--home=] + --address=
User address + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `address`，用户地址 + +根据地址`LdeNufGZewrvS7sE4VWC9m1SFkPqVwjBN87LB`查询用户详情： +```bash +:bin$ ./jdchain-cli.sh query user --address LdeNufGZewrvS7sE4VWC9m1SFkPqVwjBN87LB +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +{"address":"LdeNufGZewrvS7sE4VWC9m1SFkPqVwjBN87LB","pubKey":"7VeRMGBMMBQVoZQTU3mcJYGgbVcQzxXiq6NK69TaCjEoktLf"} +``` + +#### 角色权限 + +```bash +:bin$ ./jdchain-cli.sh query role-privileges -h +Query role privileges. +Usage: jdchain-cli query role-privileges [-hV] [--pretty] [--gw-host=] + [--gw-port=] [--home=] --role= + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --pretty Pretty json print + --role= Role name + -V, --version Print version information and exit. +``` +- `role`，角色名称 + +查询角色`ROLE1`权限信息： +```bash +:bin$ ./jdchain-cli.sh query role-privileges --role ROLE1 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +{"ledgerPrivilege":{"permissionCount":2,"privilege":["REGISTER_USER","REGISTER_DATA_ACCOUNT"]},"transactionPrivilege":{"permissionCount":2,"privilege":["DIRECT_OPERATION","CONTRACT_OPERATION"]}} +``` + +#### 用户权限 + +```bash +:bin$ ./jdchain-cli.sh query user-privileges -h +Query user privileges. +Usage: jdchain-cli query user-privileges [-hV] [--pretty] --address=
+ [--gw-host=] [--gw-port=] [--home=] + --address=
User address + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `address`，用户地址 + +查询用户`LdeNufGZewrvS7sE4VWC9m1SFkPqVwjBN87LB`权限信息： +```bash +:bin$ ./jdchain-cli.sh query user-privileges --address LdeNufGZewrvS7sE4VWC9m1SFkPqVwjBN87LB +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +{"ledgerPrivilegesBitset":{"privilege":["CONFIGURE_ROLES","AUTHORIZE_USER_ROLES","SET_CONSENSUS","SET_CRYPTO","REGISTER_PARTICIPANT","REGISTER_USER","REGISTER_DATA_ACCOUNT","REGISTER_CONTRACT","UPGRADE_CONTRACT","SET_USER_ATTRIBUTES","WRITE_DATA_ACCOUNT","APPROVE_TX","CONSENSUS_TX","REGISTER_EVENT_ACCOUNT","WRITE_EVENT_ACCOUNT"]},"transactionPrivilegesBitset":{"privilege":["DIRECT_OPERATION","CONTRACT_OPERATION"]},"userAddress":"LdeNufGZewrvS7sE4VWC9m1SFkPqVwjBN87LB","userRole":["DEFAULT"]} +``` + +#### 数据账户总数 + +查询数据账户总数： +```bash +:bin$ ./jdchain-cli.sh query data-accounts-count +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +1 +``` +当前账本共有一个数据账户 + +#### 数据账户列表 + +```bash +:bin$ ./jdchain-cli.sh query data-accounts -h +Query data accounts. +Usage: jdchain-cli query data-accounts [-hV] [--pretty] --count= + [--gw-host=] + [--gw-port=] [--home=] + --index= + --count= Data account item count + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --index= Data account item index + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `index`，起始位置 +- `count`，最大返回 + +如分页查询数据账户列表，从第`0`个开始，最大返回`10`条： +```bash +:bin$ ./jdchain-cli.sh query data-accounts --index 0 --count 10 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +ADDRESS PUBKEY +LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC 7VeRFk4ANQHjWjAmAoL7492fuykTpXujihJeAgbXT2J9H9Yk +``` +返回数据账户的地址和公私钥信息 + +#### 数据账户详情 + +```bash +:bin$ ./jdchain-cli.sh query data-account -h +Query data account. +Usage: jdchain-cli query data-account [-hV] [--pretty] --address=
+ [--gw-host=] [--gw-port=] + [--home=] + --address=
Data account address + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `address`，数据账户地址 + +查询数据账户`LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC`详情： +```bash +:bin$ ./jdchain-cli.sh query data-account --address LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +{"address":"LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC","dataRootHash":"j5vyv6SmvSXQNKyjsEVCQJsyqXxKGZMBU62fKvtdJm2W4y","headerRootHash":"j5sA2KPgY9vidgTUCjCJiscn2CXapgSJsVnWe54xXKohej","pubKey":"7VeRFk4ANQHjWjAmAoL7492fuykTpXujihJeAgbXT2J9H9Yk"} +``` + +#### KV总数 + +```bash +:bin$ ./jdchain-cli.sh query kvs-count -h +Query key-values count. +Usage: jdchain-cli query kvs-count [-hV] [--pretty] --address=
+ [--gw-host=] [--gw-port=] + [--home=] + --address=
Data account address + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `address`，数据账户地址 + +查询数据账户`LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC`中`kv`数据总数： +```bash +:bin$ ./jdchain-cli.sh query kvs-count --address LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +1 +``` +共有一个`kv` + +#### KV列表 + +```bash +:bin$ ./jdchain-cli.sh query kvs -h +Query kvs. +Usage: jdchain-cli query kvs [-hV] [--pretty] --address=
+ --count= [--gw-host=] + [--gw-port=] [--home=] + --index= + --address=
Data account address + --count= KV item count + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --index= KV item index + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `address`，数据账户地址 +- `index`，起始位置 +- `count`，最大返回 + +如分页查询数据账户`LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC`中`kv`列表，从第`0`个开始，最大返回`10`条： +```bash +:bin$ ./jdchain-cli.sh query kvs --address LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC --index 0 --count 10 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +{"key":"k1","type":"TEXT","value":"v1","version":0} +``` + +#### KV详情 + +```bash +:bin$ ./jdchain-cli.sh query kv -h +Query kv. +Usage: jdchain-cli query kv [-hV] [--pretty] --address=
+ [--gw-host=] [--gw-port=] + [--home=] --key= + --address=
Data account address + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --key= Key + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `address`，数据账户地址 +- `key`，`key` + +查询数据账户`LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC`中`k1`最新数据： +```bash +:bin$ ./jdchain-cli.sh query kv --address LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC --key k1 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +{"key":"k1","type":"TEXT","value":"v1","version":0} +``` + +#### 用户事件账户总数 + +查询数据账户总数： +```bash +:bin$ ./jdchain-cli.sh query user-event-accounts-count +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +4 +``` +当前账本共有`4`个数据账户 + +#### 用户事件账户列表 + +```bash +:bin$ ./jdchain-cli.sh query user-event-accounts -h +Query user event accounts. +Usage: jdchain-cli query user-event-accounts [-hV] [--pretty] --count= + [--gw-host=] [--gw-port=] [--home=] --index= + --count= Event account item count + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --index= Event account item index + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `index`，起始位置 +- `count`，最大返回 + +如分页查询用户事件账户列表，从第`0`个开始，最大返回`10`条： +```bash +:bin$ ./jdchain-cli.sh query user-event-accounts --index 0 --count 10 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +ADDRESS PUBKEY +LdeNhAxxXjbh56LqeB7xHpgZgHG6GDTZ45GgJ 7VeR82o3hZy1AVEjmxfNpHHW3d1zabbELmJUnijGkKJNDXu5 +LdeP33nxsYxYgaELQUkd8tBsTmwrkySiqnAVF 7VeRBA5zD2EDCiRtsiHzMQUEPf52hjKwhAi6PfNCgoiRQrSw +LdeNnDJyqYgxDernBf6Vh68CkM5FbJNYtQCPA 7VeRB71W3anhCBretEP2R9YjiFB7ne2o5qhsivPo3XmHZ7cJ +LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC 7VeRFk4ANQHjWjAmAoL7492fuykTpXujihJeAgbXT2J9H9Yk +``` +返回用户事件账户的地址和公私钥信息 + +#### 用户事件账户详情 + +```bash +:bin$ ./jdchain-cli.sh query user-event-account -h +Query user event account. +Usage: jdchain-cli query user-event-account [-hV] [--pretty] + --address=
[--gw-host=] [--gw-port=] + [--home=] + --address=
Event account address + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `address`，用户事件账户地址 + +查询事件账户`LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC`详情： +```bash +:bin$ ./jdchain-cli.sh query user-event-account --address LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +{"address":"LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC","pubKey":"7VeRFk4ANQHjWjAmAoL7492fuykTpXujihJeAgbXT2J9H9Yk"} +``` + +#### 用户事件名总数 + +```bash +:bin$ ./jdchain-cli.sh query user-event-names-count -h +Query user event names count. +Usage: jdchain-cli query user-event-names-count [-hV] [--pretty] + --address=
[--gw-host=] [--gw-port=] + [--home=] + --address=
Event account address + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `address`，用户事件账户地址 + +查询事件账户`LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC`事件名总数： +```bash +:bin$ ./jdchain-cli.sh query user-event-names-count --address LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +1 +``` + +#### 用户事件名列表 + +```bash +:bin$ ./jdchain-cli.sh query user-event-names -h +Query user event names. +Usage: jdchain-cli query user-event-names [-hV] [--pretty] --address=
+ --count= [--gw-host=] [--gw-port=] + [--home=] --index= + --address=
Event account address + --count= Event name item count + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --index= Event name item index + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `address`，事件账户地址 +- `index`，起始位置 +- `count`，最大返回 + +如分页查询用户事件账户`LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC`事件名列表，从第`0`个开始，最大返回`10`条： +```bash +:bin$ ./jdchain-cli.sh query user-event-names --address LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC --index 0 --count 10 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +t1 +``` +当前事件账户仅有一个事件名 + +#### 用户事件总数 + +```bash +:bin$ ./jdchain-cli.sh query user-events-count -h +Query user events count. +Usage: jdchain-cli query user-events-count [-hV] [--pretty] --address=
+ [--gw-host=] [--gw-port=] [--home=] --name= + --address=
Event account address + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --name= Event name + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `address`，事件账户地址 +- `name`，事件名 + +查询事件账户`LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC`事件名`t1`中事件总数： +```bash +:bin$ ./jdchain-cli.sh query user-events-count --address LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC --name t1 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +1 +``` +当前事件名仅有一个事件 + +#### 用户事件列表 + +```bash +:bin$ ./jdchain-cli.sh query user-events -h +Query user events. +Usage: jdchain-cli query user-events [-hV] [--pretty] --address=
+ --count= [--gw-host=] + [--gw-port=] [--home=] + --index= --name= + --address=
Event account address + --count= Event name item count + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --index= Event name item index + --name= Event name + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `address`，事件账户地址 +- `name`，事件名 +- `index`，起始位置 +- `count`，最大返回 + +分页查询用户事件账户`LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC`事件名`t1`中事件，从第`0`个开始，最大返回`10`条： +```bash +:bin$ ./jdchain-cli.sh query user-events --address LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC --name t1 --index 0 --count 10 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +{"blockHeight":12,"content":{"bytes":"YzE=","type":"TEXT"},"contractSource":"","eventAccount":"LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC","name":"t1","sequence":0,"transactionSource":"j5jSszhiJUTbCGtFgxd6uBWyxj56CEHRyhDF6nAnUvJTp7"} +``` + +#### 最新用户事件 + +```bash +:bin$ ./jdchain-cli.sh query latest-user-event -h +Query latest user event. +Usage: jdchain-cli query latest-user-event [-hV] [--pretty] --address=
+ [--gw-host=] [--gw-port=] [--home=] --name= + --address=
Event account address + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --name= Event name + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `address`，时间账户地址 +- `name`，事件名 + +查询用户事件账户`LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC`事件名`t1`最新事件： +```bash +:bin$ ./jdchain-cli.sh query latest-user-event --address LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC --name t1 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +{"blockHeight":12,"content":{"bytes":"YzE=","type":"TEXT"},"contractSource":"","eventAccount":"LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC","name":"t1","sequence":0,"transactionSource":"j5jSszhiJUTbCGtFgxd6uBWyxj56CEHRyhDF6nAnUvJTp7"} +``` + +#### 合约总数 + +查询合约总数： +```bash +:bin$ ./jdchain-cli.sh query contracts-count +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +1 +``` +当前账本仅有一个合约 + +#### 合约列表 + +```bash +:bin$ ./jdchain-cli.sh query contracts -h +Query contracts. +Usage: jdchain-cli query contracts [-hV] [--pretty] --count= + [--gw-host=] [--gw-port=] + [--home=] --index= + --count= Contract item count + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --index= Contract item index + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `index`，起始位置 +- `count`，最大返回 + +分页查询合约，从第`0`个开始，最大返回`10`条： +```bash +:bin$ ./jdchain-cli.sh query contracts --index 0 --count 10 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +ADDRESS PUBKEY +LdeNyF6jdNry5iCqmHdAFTQPvC8UkbJ9avoXH 7VeRFZEqSdXWQxaLUFaAgJVdVTssuwQdBg4KPGgCCTbrzqxA +``` +返回合约地址和公钥信息 + +#### 合约详情 + +```bash +e:bin$ ./jdchain-cli.sh query contract -h +Query contract. +Usage: jdchain-cli query contract [-hV] [--pretty] --address=
+ [--gw-host=] [--gw-port=] + [--home=] + --address=
Contract address + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `address`，合约地址 + +查询合约`LdeNyF6jdNry5iCqmHdAFTQPvC8UkbJ9avoXH`详情： +```bash +:bin$ ./jdchain-cli.sh query contract --address LdeNyF6jdNry5iCqmHdAFTQPvC8UkbJ9avoXH +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +package com.jdchain.samples.contract; + +import com.jd.blockchain.contract.*; +import utils.*; +import com.jd.blockchain.crypto.*; +import com.jd.blockchain.ledger.*; + +public class SampleContractImpl implements EventProcessingAware, SampleContract +{ + private ContractEventContext eventContext; + + public void setKVWithVersion(final String address, final String key, final String value, final long version) { + this.eventContext.getLedger().dataAccount(Bytes.fromBase58(address)).setText(key, value, version); + } + + public void setKV(final String address, final String key, final String value) { + final TypedKVEntry[] entries = this.eventContext.getUncommittedLedger().getDataEntries(address, new String[] { key }); + long version = -1L; + if (null != entries && entries.length > 0) { + version = entries[0].getVersion(); + } + this.eventContext.getLedger().dataAccount(Bytes.fromBase58(address)).setText(key, value, version); + } + + public String registerUser(final String seed) { + final CryptoAlgorithm algorithm = Crypto.getAlgorithm("ed25519"); + final SignatureFunction signFunc = Crypto.getSignatureFunction(algorithm); + final AsymmetricKeypair cryptoKeyPair = signFunc.generateKeypair(seed.getBytes()); + final BlockchainKeypair keypair = new BlockchainKeypair(cryptoKeyPair.getPubKey(), cryptoKeyPair.getPrivKey()); + this.eventContext.getLedger().users().register(keypair.getIdentity()); + return keypair.getAddress().toBase58(); + } + + public String registerDataAccount(final String seed) { + final CryptoAlgorithm algorithm = Crypto.getAlgorithm("ed25519"); + final SignatureFunction signFunc = Crypto.getSignatureFunction(algorithm); + final AsymmetricKeypair cryptoKeyPair = signFunc.generateKeypair(seed.getBytes()); + final BlockchainKeypair keypair = new BlockchainKeypair(cryptoKeyPair.getPubKey(), cryptoKeyPair.getPrivKey()); + this.eventContext.getLedger().dataAccounts().register(keypair.getIdentity()); + return keypair.getAddress().toBase58(); + } + + public String registerEventAccount(final String seed) { + final CryptoAlgorithm algorithm = Crypto.getAlgorithm("ed25519"); + final SignatureFunction signFunc = Crypto.getSignatureFunction(algorithm); + final AsymmetricKeypair cryptoKeyPair = signFunc.generateKeypair(seed.getBytes()); + final BlockchainKeypair keypair = new BlockchainKeypair(cryptoKeyPair.getPubKey(), cryptoKeyPair.getPrivKey()); + this.eventContext.getLedger().eventAccounts().register(keypair.getIdentity()); + return keypair.getAddress().toBase58(); + } + + public void publishEventWithSequence(final String address, final String topic, final String content, final long sequence) { + this.eventContext.getLedger().eventAccount(Bytes.fromBase58(address)).publish(topic, content, sequence); + } + + public void publishEvent(final String address, final String topic, final String content) { + final Event event = this.eventContext.getUncommittedLedger().getLatestEvent(address, topic); + long sequence = -1L; + if (null != event) { + sequence = event.getSequence(); + } + this.eventContext.getLedger().eventAccount(Bytes.fromBase58(address)).publish(topic, content, sequence); + } + + public void beforeEvent(final ContractEventContext eventContext) { + this.eventContext = eventContext; + } + + public void postEvent(final ContractEventContext eventContext, final Exception error) { + } +} + +``` \ No newline at end of file diff --git a/docs/cli/tx.md b/docs/cli/tx.md new file mode 100644 index 00000000..a6bf3b74 --- /dev/null +++ b/docs/cli/tx.md @@ -0,0 +1,531 @@ +### 交易 + +```bash +:bin$ ./jdchain-cli.sh tx -h +Usage: git status [...] [--] [...] +Build, sign or send transaction. + --export= Transaction export directory + --gw-host= Set the gateway host. Default: 127.0.0.1 + Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + Default: ../ + --pretty Pretty json print + -V, --version Print version information and exit. +Commands: + user-register Register new user. + role Create or config role. + authorization User role authorization. + data-account-register Register new data account. + kv Set key-value. + event Publish event. + contract-deploy Deploy or update contract. + contract Call contract method. + event-account-register Register event account. + sign Sign transaction. + send Send transaction. + help Displays help information about the specified command +``` + +参数： +- `export`，导出交易到指定位置，用于离线交易相关命令 +- `gw-host`，网关服务地址，默认`127.0.0.1` +- `gw-port`，网关服务端口，默认`8080` +- `home`，指定密钥存储相关目录，`${home}/config/keys` + +命令： +- `user-register`，[注册用户](#注册用户) +- `role`，[角色管理](#角色管理) +- `authorization`，[权限配置](#权限配置) +- `data-account-register`，[注册数据账户](#注册数据账户) +- `kv`，[KV设值](#KV设值) +- `event-account-register`，[注册事件账户](#注册事件账户) +- `event`，[发布事件](#发布事件) +- `contract-deploy`，[部署合约](#部署合约) +- `contract`，[合约调用](#合约调用) +- `sign`，[离线交易签名](#离线交易签名) +- `send`，[离线交易发送](#离线交易发送) + +#### 注册用户 + +```bash +:bin$ ./jdchain-cli.sh tx user-register -h +Register new user. +Usage: jdchain-cli tx user-register [-hV] [--pretty] [--export=] + [--gw-host=] [--gw-port=] + [--home=] + --export= Transaction export directory + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --pretty Pretty json print + -V, --version Print version information and exit. +``` +从`${home}/config/keys`目录下密钥对选择密钥注册到网关服务对应的区块链网络。 + +如： +```bash +:bin$ ./jdchain-cli.sh tx user-register +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +// 选择账本，当前网关服务只有上面一个可用账本 +> 0 +select keypair to register: +INDEX KEY ADDRESS +0 peer0 LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw +1 k1 LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC +// 选择公私钥对用于注册用户 +> 1 +input password of the key: +// 输入所选择公私钥对密钥密码 +> 1 +select keypair to sign tx: +INDEX KEY ADDRESS +0 peer0 LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw +1 k1 LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC +// 选择链上已存在且有注册用户权限的用户所对应的公私钥对，用于交易签名 +> 0 +input password of the key: +// 输入签名私钥密码 +> 1 +register user: [LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC] +``` +会在链上注册地址为`LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC`的用户账户信息。 + + +#### 角色管理 +```bash +:bin$ ./jdchain-cli.sh tx role -h +Create or config role. +Usage: jdchain-cli tx role [-hV] [--pretty] [--export=] + [--gw-host=] [--gw-port=] + [--home=] --name= + [--disable-ledger-perms=[, + ...]]... + [--disable-transaction-perms=[,...]]... + [--enable-ledger-perms=[, + ...]]... + [--enable-transaction-perms= + [,...]]... + --disable-ledger-perms=[,...] + Disable ledger permissions + --disable-transaction-perms=[, + ...] + Disable transaction permissions + --enable-ledger-perms=[,...] + Enable ledger permissions + --enable-transaction-perms=[, + ...] + Enable transaction permissions + --export= Transaction export directory + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --name= Role name + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `name`，角色名称，不存在则创建 +- `disable-ledger-perms`，禁用的账本权限列表，半角逗号分割 +- `disable-transaction-perms`，禁用的交易权限列表，半角逗号分割 +- `enable-ledger-perms`，的账本权限列表，半角逗号分割 +- `enable-transaction-perms`，禁用的交易权限列表，半角逗号分割 + +如： +```bash +:bin$ ./jdchain-cli.sh tx role --name ROLE1 --enable-ledger-perms REGISTER_USER,REGISTER_DATA_ACCOUNT --enable-transaction-perms DIRECT_OPERATION,CONTRACT_OPERATION +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +// 选择账本 +> 0 +select keypair to sign tx: +INDEX KEY ADDRESS +0 peer0 LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw +1 k1 LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC +// 选择签名账户 +> 0 +input password of the key: +// 输入签名账户私钥密码 +> 1 +Role config success! +``` + +#### 权限配置 + +```bash +:bin$ ./jdchain-cli.sh tx authorization -h +User role authorization. +Usage: jdchain-cli tx authorization [-hV] [--pretty] --address=
+ [--export=] [--gw-host=] + [--gw-port=] [--home=] + [--policy=] + [--authorize=[, + ...]]... + [--unauthorize=[, + ...]]... + --address=
User address + --authorize=[,...] + Authorize roles + --export= Transaction export directory + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --policy= Role policy + --pretty Pretty json print + --unauthorize=[,...] + Unauthorize roles + -V, --version Print version information and exit. +``` +- `address`，用户地址 +- `authorize`，赋予角色列表，半角逗号分割 +- `unauthorize`，移除角色列表，半角逗号分割 +- `policy`，角色策略，`UNION`/`INTERSECT`，默认`UNION`合并所有角色权限 + +如： +```bash +:bin$ ./jdchain-cli.sh tx authorization --address LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC --authorize ROLE1 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +select keypair to sign tx: +INDEX KEY ADDRESS +0 peer0 LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw +1 k1 LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC +> 0 +input password of the key: +> 1 +Authorization config success! +``` + +#### 注册数据账户 + +```bash +:bin$ ./jdchain-cli.sh tx data-account-register -h +Register new data account. +Usage: jdchain-cli tx data-account-register [-hV] [--pretty] + [--export=] [--gw-host=] [--gw-port=] + [--home=] [--pubkey=] + --export= Transaction export directory + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --pretty Pretty json print + --pubkey= The pubkey of the exist data account + -V, --version Print version information and exit. +``` +- `pubkey`，待注册数据账户私钥 + +如： +```bash +:bin$ ./jdchain-cli.sh tx data-account-register --pubkey 7VeRFk4ANQHjWjAmAoL7492fuykTpXujihJeAgbXT2J9H9Yk +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +select keypair to sign tx: +INDEX KEY ADDRESS +0 peer0 LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw +1 k1 LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC +> 0 +input password of the key: +> 1 +register data account: [LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC] +``` +会在链上注册地址为`LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC`的数据账户信息。 + +#### KV设值 + +```bash +:bin$ ./jdchain-cli.sh tx kv -h +Set key-value. +Usage: jdchain-cli tx kv [-hV] [--pretty] --address=
+ [--export=] [--gw-host=] + [--gw-port=] [--home=] --key= + --value= [--ver=] + --address=
Data account address + --export= Transaction export directory + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --key= Key to set + --pretty Pretty json print + -V, --version Print version information and exit. + --value= Value to set + --ver= Version of the key-value +``` +- `address`，数据账户地址 +- `key`，键 +- `value`，值 +- `ver`，版本 + +如向账户地址`LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC`写入`k1`:`v1`:`-1`键值对数据： +```bash +:bin$ ./jdchain-cli.sh tx kv --address LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC --key k1 --value v1 --ver -1 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +select keypair to sign tx: +INDEX KEY ADDRESS +0 peer0 LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw +1 k1 LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC +> 0 +input password of the key: +> 1 +set kv success +``` + +#### 注册事件账户 + +```bash +:bin$ ./jdchain-cli.sh tx event-account-register -h +Register event account. +Usage: jdchain-cli tx event-account-register [-hV] [--pretty] + [--export=] [--gw-host=] [--gw-port=] + [--home=] [--pubkey=] + --export= Transaction export directory + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --pretty Pretty json print + --pubkey= The pubkey of the exist event account + -V, --version Print version information and exit. +``` +- `pubkey`，待注册事件账户私钥 + +如： +```bash +:bin$ ./jdchain-cli.sh tx event-account-register --pubkey 7VeRFk4ANQHjWjAmAoL7492fuykTpXujihJeAgbXT2J9H9Yk +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +select keypair to sign tx: +INDEX KEY ADDRESS +0 peer0 LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw +1 k1 LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC +> 0 +input password of the key: +> 1 +register event account: [LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC] +``` +会在链上注册地址为`LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC`的事件账户信息。 + +#### 发布事件 +```bash +:bin$ ./jdchain-cli.sh tx event -h +Publish event. +Usage: jdchain-cli tx event [-hV] [--pretty] --address=
+ --content= [--export=] + [--gw-host=] [--gw-port=] + [--home=] [--sequence=] + --name= + --address=
Contract address + --content= Event content + --export= Transaction export directory + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --pretty Pretty json print + --sequence= Sequence of the event + --name= Event name + -V, --version Print version information and exit. +``` +- `address`，事件账户地址 +- `name`，事件名 +- `content`，事件内容 +- `sequence`，事件序号 + +如向账户地址`LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC`发布事件`n1`:`c1`:`-1`： +```bash +:bin$ ./jdchain-cli.sh tx event --address LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC --name n1 --content c1 --sequence -1 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +select keypair to sign tx: +INDEX KEY ADDRESS +0 peer0 LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw +1 k1 LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC +> 0 +input password of the key: +> 1 +event publish success +``` + +#### 部署合约 + +```bash +:bin$ ./jdchain-cli.sh tx contract-deploy -h +Deploy or update contract. +Usage: jdchain-cli tx contract-deploy [-hV] [--pretty] --car= + [--export=] [--gw-host=] + [--gw-port=] [--home=] + [--pubkey=] + --car= The car file path + --export= Transaction export directory + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --pretty Pretty json print + --pubkey= The pubkey of the exist contract + -V, --version Print version information and exit. +``` +- `pubkey`，合约公钥，更新合约时使用 +- `car`，合约`car`文件 + +如将`contract-samples-1.5.0.RELEASE.car`文件中的合约部署上链： +```bash +:bin$ ./jdchain-cli.sh tx contract-deploy --car /home/imuge/Desktop/jdchain-cli/1.5.0/contract-samples-1.5.0.RELEASE.car +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +select keypair to sign tx: +INDEX KEY ADDRESS +0 peer0 LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw +1 k1 LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC +> 0 +input password of the key: +> 1 +deploy contract: [LdeNyF6jdNry5iCqmHdAFTQPvC8UkbJ9avoXH] +``` +合约地址：`LdeNyF6jdNry5iCqmHdAFTQPvC8UkbJ9avoXH` + +#### 合约调用 + +```bash +:bin$ ./jdchain-cli.sh tx contract -h +Call contract method. +Usage: jdchain-cli tx contract [-hV] [--pretty] --address=
+ [--export=] [--gw-host=] + [--gw-port=] [--home=] + --method= [--args=[,...]]... + --address=
Contract address + --args=[,...] + Method arguments + --export= Transaction export directory + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --method= Contract method + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `address`，合约地址 +- `method`，合约方法 +- `args`，合约参数，半角逗号分割，命令行中会将所有参数处理为字符串，非字符串参数方法调用暂无法通过命令行工具调用 + +如调用合约`LdeNyF6jdNry5iCqmHdAFTQPvC8UkbJ9avoXH`中`registerUser`方法，传参`ed386a148fcb48b281b325f66103c805`： +```bash +:bin$ ./jdchain-cli.sh tx contract --address LdeNyF6jdNry5iCqmHdAFTQPvC8UkbJ9avoXH --method registerUser --args ed386a148fcb48b281b325f66103c805 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +select keypair to sign tx: +INDEX KEY ADDRESS +0 peer0 LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw +1 k1 LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC +> 0 +input password of the key: +> 1 +call contract success +return string: LdeNqvSjL4izfpMNsGpQiBpTBse4g6qLxZ6j5 +``` +调用成功并返回了字符串：`LdeNqvSjL4izfpMNsGpQiBpTBse4g6qLxZ6j5` + + +#### 离线交易签名 + +1. 离线交易 + +执行以上所有交易时，若`export`参数不为空，则会执行交易写入本地操作，而非签名并发送交易，离线交易可以 + +如构造合约调用操作交易并保存到本地： +```bash +:bin$ ./jdchain-cli.sh tx contract --address LdeNyF6jdNry5iCqmHdAFTQPvC8UkbJ9avoXH --method registerUser --args ed386a148fcb48b281b325f66103c810 --export /txs +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +export transaction success: /txs/j5xR8ty8YbujTYKNRshmbfMYsL4jfe3yRUtMparmeHppd3 +``` +交易内容会被序列化报存在`/txs/j5xR8ty8YbujTYKNRshmbfMYsL4jfe3yRUtMparmeHppd3`中，其中`j5xR8ty8YbujTYKNRshmbfMYsL4jfe3yRUtMparmeHppd3`是该交易哈希。 + +2. 离线签名 + +```bash +:bin$ ./jdchain-cli.sh tx sign -h +Sign transaction. +Usage: jdchain-cli tx sign [-hV] [--pretty] [--export=] + [--gw-host=] [--gw-port=] + [--home=] [--tx=] + --export= Transaction export directory + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --tx= Local transaction file + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `import`，离线交易路径 + +如对步骤1中创建的离线交易添加终端用户（此用户需是链上存在的且有相关权限的用户）签名： +```bash +:bin$ ./jdchain-cli.sh tx sign --tx /txs/j5xR8ty8YbujTYKNRshmbfMYsL4jfe3yRUtMparmeHppd3 +select keypair to sign tx: +INDEX KEY ADDRESS +0 peer0 LdeNyibeafrAQXgHjBxgQxoLbna6hL4BcXZiw +1 k1 LdeNwQWabrf6WSjZ35saFo52MfQFhVKvm11aC +> 0 +input password of the key: +> 1 +Sign transaction success! +``` + +#### 离线交易发送 + +发送本地已经签名完成的交易 +```bash +:bin$ ./jdchain-cli.sh tx send -h +Send transaction. +Usage: jdchain-cli tx send [-hV] [--pretty] [--export=] + [--gw-host=] [--gw-port=] + [--home=] [--tx=] + --export= Transaction export directory + --gw-host= Set the gateway host. Default: 127.0.0.1 + --gw-port= Set the gateway port. Default: 8080 + -h, --help Show this help message and exit. + --home= Set the home directory. + --tx= Local transaction file + --pretty Pretty json print + -V, --version Print version information and exit. +``` +- `import`，离线交易路径 + +如发送`/txs/j5xR8ty8YbujTYKNRshmbfMYsL4jfe3yRUtMparmeHppd3`中包含的交易数据： +```bash +:bin$ ./jdchain-cli.sh tx send --tx /home/imuge/Desktop/jdchain-cli/1.5.0/txs/j5xR8ty8YbujTYKNRshmbfMYsL4jfe3yRUtMparmeHppd3 +select ledger, input the index: +INDEX LEDGER +0 j5sB3sVTFgTqTYzo7KtQjBLSy8YQGPpJpvQZaW9Eqk46dg +> 0 +Send transaction success: j5xR8ty8YbujTYKNRshmbfMYsL4jfe3yRUtMparmeHppd3 +``` \ No newline at end of file diff --git a/docs/contract.md b/docs/contract.md new file mode 100644 index 00000000..fca1fa53 --- /dev/null +++ b/docs/contract.md @@ -0,0 +1,549 @@ +# 智能合约 + +### 1. 简介 + +JD Chain 智能合约系统由5个部分组成：合约代码语言、合约引擎、合约账户、合约开发框架、合约开发插件。 + +合约代码语言是用来编写智能合约的编程语言，合约引擎是解释和执行合约代码的虚拟机。 + +JD Chain 账本中以合约账户的方式对合约代码进行管理。一份部署上链的合约代码需要关联到一个唯一的公钥上，并生成与公钥对应的区块链账户地址，在账本中注册为一个合约账户。在执行之前，系统从账本中读出合约代码并将其加载到合约引擎，由交易执行器调用合约引擎触发合约执行。 + +JD Chain 账本定义了一组标准的账本操作指令，合约代码的执行过程实质上是向账本输出一串操作指令序列，这些指令对账本中的数据产生了变更，形成合约执行的最终结果。 + +合约开发框架定义了进行合约代码开发中需要依赖的一组编程接口和类库。合约开发插件提供了更方便与IDE集成的合约编译、部署工具，可以简化操作，并与持续集成过程结合。 + +JD Chain 以 Java 语言作为合约代码语言，合约引擎是基于 JVM 构建的安全沙盒。为了实现与主流的应用开发方式无缝兼容， JD Chain 支持以 Maven 来管理合约代码的工程项目，并提供相应的 maven 插件来简化合约的编译和部署。 + +>智能合约是一种可以由计算机执行的合同/协议。不同于现实生活中的合同是由自然语言来编写并约定相关方的权利和义务，智能合约是用合约代码语言来编写，以合约代码的形式存在和被执行。通过账本中的数据状态来表示合同/协议相关条款信息，合约代码的运行过程体现了合同/协议条款的执行，并记录相应的结果。 + +### 2. 快速入门 + +#### 2.1. 准备开发环境 + +按照正常的 Java 应用开发环境要求进行准备，以 Maven 作为代码工程的构建管理工具，无其它特殊要求。 + +>检查 JDK 版本不低于 1.8 ，Maven 版本不低于 3.0。 + +#### 2.2. 创建合约代码工程 +创建一个普通的 Java Maven 工程，打开 pom.xml 把 packaging 设为 contract . + +```xml + + 4.0.0 + your.group.id + your.project + 0.0.1-SNAPSHOT + + contract + + + + + + + + + + + +``` + +> 注：合约代码工程也是一个普通的 Java Maven 工程，因此尽管不同 IDE 创建 Maven 工程有不同的操作方式，由于对于合约开发而言并无特殊要求，故在此不做详述。 + +#### 2.3. 加入合约开发依赖 + +在合约代码工程 pom.xml 加入对合约开发 SDK 的依赖： + + ```xml + + com.jd.blockchain + contract-starter + ${jdchain.version} + + ``` + +#### 2.4. 加入合约插件 + +在合约代码工程的 pom.xml 加入 contract-maven-plugin 插件： + ```xml + + com.jd.blockchain + contract-maven-plugin + ${jdchain.version} + true + + ``` + +完整的 pom.xml 如下： + + ```xml + + 4.0.0 + your.group.id + your.project + 0.0.1-SNAPSHOT + + contract + + + 1.4.2.RELEASE + + + + + + com.jd.blockchain + contract-starter + ${jdchain.version} + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.8.1 + + 1.8 + 1.8 + UTF-8 + false + true + false + false + + + + + + com.jd.blockchain + contract-maven-plugin + ${jdchain.version} + true + + + + + ``` + +#### 2.5. 编写合约代码 + +2.5.1. **注意事项** + +1. 不允许合约（包括合约接口和合约实现类）使用com.jd.blockchain开头的package； +2. 必须有且只有一个接口使用@Contract注解，且其中的event必须大于等于一个； +3. 使用@Contract注解的接口有且只有一个实现类； +4. 黑名单调用限制（具体黑名单可查看配置文件），需要注意的是，黑名单分析策略会递归分析类实现的接口和父类，也就是说调用一个实现了指定黑名单接口的类也是不允许的； + + +目前设置的黑名单如下： +```conf +java.io.File +java.io.InputStream +java.io.OutputStream +java.io.DataInput +java.io.DataOutput +java.io.Reader +java.io.Writer +java.io.Flushable +java.nio.channels.* +java.nio.file.* +java.net.* +java.sql.* +java.lang.reflect.* +java.lang.Class +java.lang.ClassLoader +java.util.Random +java.lang.System-currentTimeMillis +java.lang.System-nanoTime +com.jd.blockchain.ledger.BlockchainKeyGenerator +``` + +2.5.2. **声明合约** + +```java +/** + * 声明合约接口； +**/ +@Contract +public interface AssetContract { + + @ContractEvent(name = "transfer") + String transfer(String address, String from, String to, long amount); + +} +``` + +2.5.3. **实现合约** + +```java +/** + * 实现合约； + * + * 实现 EventProcessingAware 接口是可选的，目的获得 ContractEventContext 上下文对象， + * 通过该对象可以进行账本操作； + */ +public class AssetContractImpl implements AssetContract, EventProcessingAware { + + // 合约事件上下文； + private ContractEventContext eventContext; + + /** + * 执行交易请求中对 AssetContract 合约的 transfer 调用操作； + */ + public String transfer(String address, String from, String to, long amount) { + //当前账本的哈希； + HashDigest ledgerHash = eventContext.getCurrentLedgerHash(); + //当前账本上下文； + LedgerContext ledgerContext = eventContext.getLedger(); + + //做操作； + // ledgerContext. + + //返回合约操作的结果； + return "success"; + } + + /** + * 准备执行交易中的合约调用操作； + */ + @Override + public void beforeEvent(ContractEventContext eventContext) { + this.eventContext = eventContext; + } + + /** + * 完成执行交易中的合约调用操作； + */ + @Override + public void postEvent(ContractEventContext eventContext, Exception error) { + this.eventContext = null; + } +} +``` + +**账本数据可见范围**： + +`ContractEventContext`中`getUncommittedLedger`方法可访问执行中的未提交区块数据，此方法的合理使用可以解决客户并发调用合约方法涉及数据版本/事件序列冲突的问题。 +```java +/** + * 当前包含未提交区块数据账本查询上下文； + */ +LedgerQueryService getUncommittedLedger(); +``` + +`ContractEventContext`中`getLedger`方法访问的是链上已提交的最新区块数据，不包含未提交交易，所以存在未提交交易中多个合约方法调用操作间数据不可见，导致并发时数据版本等冲突问题。 +```java +/** + * 账本操作上下文； + */ +LedgerContext getLedger(); +``` + +合约方法中对账本的操作通过调用`LedgerContext`中相关方法，可参照[示例合约](https://github.com/blockchain-jd-com/jdchain/tree/master/samples/contract-samples/src/main/java/com/jdchain/samples/contract) + +#### 2.6. 编译打包合约代码 + +合约代码工程的编译打包操作与普通的 maven 工程是相同的，在工程的根目录下输入以下命令： + +```bash +mvn clean package +``` + +执行成功之后，在 target 目录中输出合约代码文件 \.\.car 。 + +如果合约代码加入了除 com.jd.blockchain:contract-starter 之外的其它依赖，默认配置下，第三方依赖包将与 .car 文件一起打包一起部署。（也可以把第三方依赖包独立打包，具体参见以下 “3. 合约插件详细配置” + +> 注意：合约代码虽然利用了 Java 语言，遵照 Java 语法进行编写，但本质上是作为一种运行于受限环境（合约虚拟机）的语言来使用，因而一些 Java 语法和 SDK 的 API 是不被允许使用的，在编译过程中将对此进行检查。 + +#### 2.7. 部署合约代码 + +##### 2.7.1. 在项目中部署合约代码 + +如果希望在构建打包的同时将合约代码部署到指定的区块链网络，可以在合约代码工程 pom.xml 的 contract-maven-plugin 插件配置中加入合约部署相关的信息（具体更详细的配置可以参考“3. 合约插件详细配置”）。 + +```xml + + com.jd.blockchain + contract-maven-plugin + 1.2.0.RELEASE + true + + + + + j5rpuGWVxSuUbU3gK7MDREfui797AjfdHzvAMiSaSzydu7 + + + + 192.168.10.10 + 8081 + + + + + 7VeRMpXVeTY4cqPogUHeNoZNk86CGAejBh9Xbd5ndFZXNFj3 + + + + + 7VeRLdGtSz1Y91gjLTqEdnkotzUfaAqdap3xw6fQ1yKHkvVq + 177gjzHTznYdPgWqZrH43W3yp37onm74wYXT4v9FukpCHBrhRysBBZh7Pzdo5AMRyQGJD7x + DYu3G8aGTMBW1WrTw76zxQJQU4DHLw9MLyy7peG4LKkY + + + + +``` + +加入部署配置信息之后，对工程执行编译打包操作，输出的合约代码（.car）将自动部署到指定的区块链网络。 + +```bash +mvn clean deploy +``` +##### 2.7.2. 发布已编译好的car +如果已经通过插件的打包方式，编译打包完成一个合约文件（.car），可通过命令行的方式进行发布，命令行要求与开发环境一致的Maven环境（包括环境变量及Setting都已配置完成）。 + +```bash +mvn com.jd.blockchain:contract-maven-plugin:${version}:deploy + -DcarPath= + -Dledger= + -DgatewayHost= + -DgatewayPort= + -DcontractPubKey= + -DcontractAddress= + -DsignerPubKey= + -DsignerPrivKey= + -DsignerPrivKeyPwd= +``` + +各参数说明如下： + +| 参数名 | 含义 |是否必填| +| ---- | ---- | ---- | +| ${version} | 合约插件的版本号 | 否，系统会自动选择发布的最新的RELEASE版本，SNAPSHOT版本必须填写 | +| carPath | 合约文件所在路径 | 是 | +| ledger | 账本Hash（Base58编码） | 否，会自动选择线上第一个账本| +| gatewayHost | 可访问的网关节点地址，域名或IP地址 | 是| +| gatewayPort | 网关节点监听端口 | 是 | +| contractPubKey | 合约账户的公钥（Base58编码）| 否，会自动创建 | +| contractAddress | 合约账户的地址（Base58编码）|否，会根据contractPubKey生成| +| signerPubKey | 合约签名公钥信息（Base58编码）|是| +| signerPrivKey | 合约签名私钥信息（Base58编码）|是| +| signerPrivKeyPwd | 合约签名私钥解密密钥（Base58编码）|是| + + +下面是一个示例，供参考： + +```bash +mvn com.jd.blockchain:contract-maven-plugin:1.2.0.RELEASE:deploy \ + -DcarPath=/root/jdchain/contracts/contract-test-1.0-SNAPSHOT.car \ + -Dledger=j5tW5HUvMjEtm2yB7E6MHoSByoH1DXvMwvF2HurEgMSaLW \ + -DgatewayHost=127.0.0.1 \ + -DgatewayPort=11000 \ + -DcontractPubKey= 7VeRBsHM2nsGwP8b2ufRxz36hhNtSqjKTquzoa4WVKWty5sD \ + -DcontractAddress= LdeNt7sEmTirh9PmE7axKvA2txTrbB9kxz6KB \ + -DsignerPubKey=7VeRLdGtSz1Y91gjLTqEdnkotzUfaAqdap3xw6fQ1yKHkvVq \ + -DsignerPrivKey=177gjzHTznYdPgWqZrH43W3yp37onm74wYXT4v9FukpCHBrhRysBBZh7Pzdo5AMRyQGJD7x \ + -DsignerPrivKeyPwd=DYu3G8aGTMBW1WrTw76zxQJQU4DHLw9MLyy7peG4LKkY +``` + +> 重点说明： +命令行中输入参数的优先级高于配置文件，就是说通过2.7.1方式发布合约时也可以采用命令行的参数（指-D相关配置），其优先级高于配置文件。 + +### 3. 合约插件详细配置 + +```xml + + com.jd.blockchain + contract-maven-plugin + 1.2.0.RELEASE + true + + + + + + false + + + + + 1 + + + MB + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + +``` + +### 4. 最简化合约插件配置示例 + +在pom.xml中有部分配置是非必填项，下面是一份最简化的合约发布（deploy）配置示例，供参考： + + +```xml + + com.jd.blockchain + contract-maven-plugin + 1.2.0.RELEASE + true + + + + + + 127.0.0.1 + 8081 + + + + + 7VeRLdGtSz1Y91gjLTqEdnkotzUfaAqdap3xw6fQ1yKHkvVq + 177gjzHTznYdPgWqZrH43W3yp37onm74wYXT4v9FukpCHBrhRysBBZh7Pzdo5AMRyQGJD7x + DYu3G8aGTMBW1WrTw76zxQJQU4DHLw9MLyy7peG4LKkY + + + + +``` + +### 5. 合约SDK + +除上述使用 maven 命令方式部署合约外，JD Chain SDK 提供了 Java 和 Go 语言的合约部署/升级，合约调用等方法。 +以下以 Java SDK 为例讲述主要步骤，完整代码参照[JD Chain Samples](https://github.com/blockchain-jd-com/jdchain/tree/master/samples)合约部分。 + +#### 5.1 合约部署 + +```java +// 新建交易 +TransactionTemplate txTemp = blockchainService.newTransaction(ledger); +// 生成合约账户 +BlockchainKeypair contractAccount = BlockchainKeyGenerator.getInstance().generate(); +System.out.println("合约地址：" + contractAccount.getAddress()); +// 部署合约 +txTemp.contracts().deploy(contractAccount.getIdentity(), FileUtils.readBytes("src/main/resources/contract-samples-1.4.2.RELEASE.car")); +``` + +#### 5.2 合约升级 + +```java +// 新建交易 +TransactionTemplate txTemp = blockchainService.newTransaction(ledger); +// 解析合约身份信息 +BlockchainIdentity contractIdentity = new BlockchainIdentityData(KeyGenUtils.decodePubKey("7VeRCfSaoBW3uRuvTqVb26PYTNwvQ1iZ5HBY92YKpEVN7Qht")); +System.out.println("合约地址：" + contractIdentity.getAddress()); +// 指定合约地址，升级合约，如合约地址不存在会创建该合约账户 +txTemp.contracts().deploy(contractIdentity, FileUtils.readBytes("src/main/resources/contract-samples-1.4.2.RELEASE.car")); +``` + +#### 5.3 合约调用 + +5.3.1 动态代理方式 + +基于动态代理方式合约调用，需要依赖合约接口 + +```java +// 新建交易 +TransactionTemplate txTemp = blockchainService.newTransaction(ledger); + +// 一次交易中可调用多个（多次调用）合约方法 +// 调用合约的 registerUser 方法 +SampleContract sampleContract = txTemp.contract("LdeNr7H1CUbqe3kWjwPwiqHcmd86zEQz2VRye", SampleContract.class); +GenericValueHolder userAddress = ContractReturnValue.decode(sampleContract.registerUser(UUID.randomUUID().toString())); + +// 准备交易 +PreparedTransaction ptx = txTemp.prepare(); +// 交易签名 +ptx.sign(adminKey); +// 提交交易 +TransactionResponse response = ptx.commit(); +Assert.assertTrue(response.isSuccess()); + +// 获取返回值 +System.out.println(userAddress.get()); +``` + +5.3.2 非动态代理方式 + +不需要依赖合约接口及实现，传入参数构造合约调用操作 + +```java +// 新建交易 +TransactionTemplate txTemp = blockchainService.newTransaction(ledger); + +ContractEventSendOperationBuilder builder = txTemp.contract(); + +// 一次交易中可调用多个（多次调用）合约方法 +// 调用合约的 registerUser 方法，传入合约地址，合约方法名，合约方法参数列表 +builder.send("LdeNr7H1CUbqe3kWjwPwiqHcmd86zEQz2VRye", "registerUser", + new BytesDataList(new TypedValue[]{ + TypedValue.fromText(UUID.randomUUID().toString()) + }) +); +// 准备交易 +PreparedTransaction ptx = txTemp.prepare(); +// 交易签名 +ptx.sign(adminKey); +// 提交交易 +TransactionResponse response = ptx.commit(); +Assert.assertTrue(response.isSuccess()); + +Assert.assertEquals(1, response.getOperationResults().length); +// 解析合约方法调用返回值 +for (int i = 0; i < response.getOperationResults().length; i++) { + BytesValue content = response.getOperationResults()[i].getResult(); + switch (content.getType()) { + case TEXT: + System.out.println(content.getBytes().toUTF8String()); + break; + case INT64: + System.out.println(BytesUtils.toLong(content.getBytes().toBytes())); + break; + case BOOLEAN: + System.out.println(BytesUtils.toBoolean(content.getBytes().toBytes()[0])); + break; + default: // byte[], Bytes + System.out.println(content.getBytes().toBase58()); + break; + } +} +``` \ No newline at end of file diff --git a/docs/data_account.md b/docs/data_account.md new file mode 100644 index 00000000..b27366cd --- /dev/null +++ b/docs/data_account.md @@ -0,0 +1,63 @@ +## 数据账户 + +`JD Chain`存放`KV`数据的数据结构。 + +### 1. 基本概念 + +可类比传统数据库的表的概念，上层应用需要保存的应用数据最终都应表现为`KV`类型数据写入到数据账户中。 + +写入`KV`数据之前，需要创建或使用已存在数据账户。 + +一个账本可以创建无限多个数据账户，一个数据账户中可以写入无限多个`KV`数据。 + +`KV`数据有`Version`（数据版本）的概念，以`KEY`作为唯一标识，`VALUE`的更新写入需要提供当前该`KEY`的最高版本，`KEY`不存在时为`-1`。 + +### 2. SDK + +以下只描述主要步骤，完整示例代码可参照[JD Chain Samples](samples.md)数据账户部分。 + +#### 2.1 注册数据账户 + +创建数据账户： +```java +BlockchainKeypair dataAccount = BlockchainKeyGenerator.getInstance().generate(); +System.out.println("数据账户地址：" + dataAccount.getAddress()); +// 注册数据账户 +txTemp.dataAccounts().register(dataAccount.getIdentity()); +``` + +从已存在数据账户公钥恢复： +```java +PubKey pubKey = KeyGenUtils.decodePubKey("7VeRLdGtSz1Y91gjLTqEdnkotzUfaAqdap3xw6fQ1yKHkvVq"); +BlockchainIdentity dataAccountIdentity = new BlockchainIdentityData(pubKey); +System.out.println("数据账户地址：" + dataAccountIdentity.getAddress()); +// 注册数据账户 +txTemp.dataAccounts().register(dataAccountIdentity); +``` + +#### 2.2 写入数据 + +```java +TransactionTemplate txTemp = blockchainService.newTransaction(ledger); + +txTemp.dataAccount("LdeNr7H1CUbqe3kWjwPwiqHcmd86zEQz2VRye") + .setText("key1", "value1", -1) + .setText("key1", "value1", 0) + .setInt64("key2", 1, -1) + .setJSON("key3", "{}", -1) + .setBytes("key4", Bytes.fromInt(2), -1); +``` + +支持写入数据类型： + +- `setText`，字符类型 +- `setInt64`，长整型 +- `setJSON`，`JSON`串 +- `setBytes`，字节数组 +- `setTimestamp`，时间戳，长整型 +- `setXML`，`XML`文本 +- `setImage`，图片字节数据 + +> 本质上仅支持`String/Long/[]byte`这三种数据类型，`JSON/XML/Image/Timestamp`等起标识作用，用于扩展差异化数据展示等场景需求 + +`setText("key1", "value1", -1)`中第三个参数即为数据版本，需要传入`JD Chain`网络中当前`key1`的最高数据版本，首次写入时传入`-1`。 \ No newline at end of file diff --git a/docs/event.md b/docs/event.md new file mode 100644 index 00000000..a753f7f5 --- /dev/null +++ b/docs/event.md @@ -0,0 +1,185 @@ +## 事件 + +`JD Chain`账本中设计了事件数据集，用以存储事件账户，事件数据。 + +`事件账户`与`用户`，`数据账户`，`合约账户`是相互独立的，所承载的数据也是相互隔离的。 + +`JD Chain`事件分为两类：[系统事件](#系统事件)，[用户事件](#用户事件) + +`JD Chain SDK` 针对事件数据集开发了[事件发布](#事件发布)，[事件监听](#事件监听)实现。 + +### 1. 系统事件 + +系统运行期间产生的事件，目前仅定义了`新区块产生`这一个： + +```java +/** + * 系统事件类型 + */ +public enum SystemEvent { + // 新区块 + NEW_BLOCK_CREATED("new_block_created"); +} +``` + +### 2. 用户事件 + +用户自定义事件类型，需要创建`事件账户`，用户自定义事件名 + +`事件账户`数量没有限制，一个事件账户内`Topic`（事件名）数量没有限制 + +同一个`事件账户`的同一个`Topic`所指向的`Content`（事件内容）有`Sequence`（事件序号）的概念，以`Topic`作为唯一标识，同一个`Topic`的更新发布需要提供当前该`Topic`的最高序号，`Topic`不存在时为`-1`。 + +### 3. 事件结构 + +```java +/** + * 事件； + * + */ +@DataContract(code = DataCodes.EVENT_MESSAGE) +public interface Event { + /** + * 事件名； + * + * @return + */ + @DataField(order = 1, primitiveType = PrimitiveType.TEXT) + String getName(); + + /** + * 事件序号； + * + * @return + */ + @DataField(order = 2, primitiveType = PrimitiveType.INT64) + long getSequence(); + + /** + * 事件内容； + * + * @return + */ + @DataField(order=3, refContract = true) + BytesValue getContent(); + + /** + * 产生事件的交易哈希；  + * + * @return + */ + @DataField(order = 4, primitiveType = PrimitiveType.BYTES) + HashDigest getTransactionSource(); + + /** + * 产生事件的合约地址； + * + * @return + */ + @DataField(order = 5, primitiveType = PrimitiveType.TEXT) + String getContractSource(); + + /** + * 产生事件的区块高度 + * + * @return + */ + @DataField(order = 6, primitiveType = PrimitiveType.INT64) + long getBlockHeight(); + + /** + * 事件账户地址，系统事件此字段为空 + * + * @return + */ + @DataField(order = 7, primitiveType = PrimitiveType.BYTES) + Bytes getEventAccount(); +} +``` + +### 4. SDK + +`JD Chain`事件监听是`SDK`端以`拉`的方式实现，消息可重复消费，需要使用者自行保存消费位置。 + +以下只描述主要步骤，完整示例代码可参照[JD Chain Samples](samples.md)事件相关部分。 + +#### 4.1 生成事件账户 + +> 用户事件才有事件账户 + +```java +// 新建交易 +TransactionTemplate txTemp = blockchainService.newTransaction(ledger); +// 生成事件账户 +BlockchainKeypair eventAccount = BlockchainKeyGenerator.getInstance().generate(); +System.out.println("事件账户地址：" + eventAccount.getAddress()); +// 注册事件账户 +txTemp.eventAccounts().register(eventAccount.getIdentity()); +``` + +#### 4.2 事件发布 + +> 系统事件由系统运行期间自动产生，用户事件可通过SDK发布 + +```java +// 新建交易 +TransactionTemplate txTemp = blockchainService.newTransaction(ledger); + +txTemp.eventAccount(Bytes.fromBase58("LdeNr7H1CUbqe3kWjwPwiqHcmd86zEQz2VRye")) + .publish("topic1", "content1", -1) + .publish("topic1", "content2", 0) + .publish("topic1", "content3", 1) + .publish("topic2", "content", -1) + .publish("topic3", 1, -1) + .publish("topic4", Bytes.fromInt(1), -1); +``` + +支持发布数据类型： + +- `Text`，字符类型 +- `Int64`，长整型 +- `JSON`，`JSON`串 +- `Bytes`，字节数组 +- `Timestamp`，时间戳，长整型 +- `XML`，`XML`文本 +- `Image`，图片字节数据 + +> 本质上仅支持`String/Long/[]byte`这三种数据类型，`JSON/XML/Image/Timestamp`等起标识作用，用于扩展差异化数据展示等场景需求 + +`publish("topic1", "content1", -1)`中第三个参数即为事件序号，需要传入`JD Chain`网络中当前`topic1`的最高序号，首次写入时传入`-1`。 + +#### 4.3 事件监听 + +- 监听系统事件 +```java +// 目前仅有新区快产生事件 +blockchainService.monitorSystemEvent(ledger, + SystemEvent.NEW_BLOCK_CREATED, 0, (eventMessages, eventContext) -> { + for (Event eventMessage : eventMessages) { + // content中存放的是当前链上最新高度 + System.out.println("New block:" + eventMessage.getSequence() + ":" + BytesUtils.toLong(eventMessage.getContent().getBytes().toBytes())); + } + }); +``` + +- 监听用户事件： +```java +blockchainService.monitorUserEvent(ledger, "LdeNr7H1CUbqe3kWjwPwiqHcmd86zEQz2VRye", "sample-event", 0, (eventMessage, eventContext) -> { + + BytesValue content = eventMessage.getContent(); + switch (content.getType()) { + case TEXT: + case XML: + case JSON: + System.out.println(eventMessage.getName() + ":" + eventMessage.getSequence() + ":" + content.getBytes().toUTF8String()); + break; + case INT64: + case TIMESTAMP: + System.out.println(eventMessage.getName() + ":" + eventMessage.getSequence() + ":" + BytesUtils.toLong(content.getBytes().toBytes())); + break; + default: // byte[], Bytes + System.out.println(eventMessage.getName() + ":" + eventMessage.getSequence() + ":" + new String(content.getBytes().toBytes())); + break; + } +}); +``` \ No newline at end of file diff --git a/docs/gateway.md b/docs/gateway.md new file mode 100644 index 00000000..10574bc4 --- /dev/null +++ b/docs/gateway.md @@ -0,0 +1,53 @@ +## 网关服务 + +`JD Chain`的网关服务是应用的接入层。 +终端接入是`JD Chain`网关的基本功能，在确认终端身份的同时提供连接节点、转发消息和隔离共识节点与客户端等服务。网关确认客户端的合法身份，接收并验证交易；网关根据初始配置文件与对应的共识节点建立连接，并转发交易数据。 + +### 1. 配置 + +网关配置在文件`gateway.conf`中： + +```properties +#网关的HTTP服务地址； +http.host=0.0.0.0 +#网关的HTTP服务端口； +http.port=8080 +#网关的HTTP服务上下文路径，可选； +#http.context-path= + +#共识节点的服务地址（与该网关节点连接的Peer节点的IP地址）； +peer.host=127.0.0.1 +#共识节点的服务端口（与该网关节点连接的Peer节点的端口，即在Peer节点的peer-startup.sh中定义的端口）； +peer.port=7080 +#共识节点的服务是否启用安全证书； +peer.secure=false + +#是否存储共识拓扑信息，网关重启后若存储存在有效的拓扑信息可快速建立与拓扑中所有节点的连接 +topology.store=false + +#共识节点的服务提供解析器 +#BftSmart共识Provider：com.jd.blockchain.consensus.bftsmart.BftsmartConsensusProvider +#简单消息共识Provider：com.jd.blockchain.consensus.mq.MsgQueueConsensusProvider +peer.providers=com.jd.blockchain.consensus.bftsmart.BftsmartConsensusProvider + +#数据检索服务对应URL，格式：http://{ip}:{port}，例如：http://127.0.0.1:10001 +#若该值不配置或配置不正确，则浏览器模糊查询部分无法正常显示 +data.retrieval.url= +schema.retrieval.url= + +#默认公钥的内容（Base58编码数据）； +keys.default.pubkey= +#默认私钥的路径；在 pk-path 和 pk 之间必须设置其一； +keys.default.privkey-path= +#默认私钥的内容（加密的Base58编码数据）；在 pk-path 和 pk 之间必须设置其一； +keys.default.privkey= +#默认私钥的解码密码； +keys.default.privkey-password= + +``` + +其中： + +- `data.retrieval.url`与`schema.retrieval.url`分别与[Argus（高级检索）](https://github.com/blockchain-jd-com/jdchain-indexer)中的[区块链基础数据检索服务](https://github.com/blockchain-jd-com/jdchain-indexer#%E5%90%AF%E5%8A%A8%E5%8C%BA%E5%9D%97%E9%93%BE%E5%9F%BA%E7%A1%80%E6%95%B0%E6%8D%AE%E7%B4%A2%E5%BC%95%E6%A3%80%E7%B4%A2%E6%9C%8D%E5%8A%A1)和[`Schema`服务](https://github.com/blockchain-jd-com/jdchain-indexer#%E5%90%AF%E5%8A%A8value%E7%B4%A2%E5%BC%95%E6%9C%8D%E5%8A%A1)相对应，只有启动并正确配置了`Argus`，`JD Chain`浏览器才能正常使用搜索功能。 + +- `keys.default`几个参数代表接入`JD Chain`网络的身份信息，只有处于非停用（`DEACTIVATED`）状态的参与方身份才可作为此处的配置。 \ No newline at end of file diff --git a/docs/images/deployment.jpg b/docs/images/deployment.jpg deleted file mode 100644 index aec66f03..00000000 Binary files a/docs/images/deployment.jpg and /dev/null differ diff --git a/docs/images/deployment.png b/docs/images/deployment.png deleted file mode 100644 index a0b2e722..00000000 Binary files a/docs/images/deployment.png and /dev/null differ diff --git a/docs/indexer.md b/docs/indexer.md new file mode 100644 index 00000000..da642c8f --- /dev/null +++ b/docs/indexer.md @@ -0,0 +1,15 @@ +# 高级检索 + +## Argus + +穿透式检索Argus提供JD Chain区块链基础数据索引，自定义键值索引服务 + +源码已开源，请参照[Argus](https://github.com/blockchain-jd-com/jdchain-indexer)首页说明安装使用。 + +## JD Chain + Argus + +修改JD Chain网关配置文件`gateway.conf`中： +- `data.retrieval.url` 对应`Argus`中区块链基础数据检索服务 +- `schema.retrieval.url` 对应`Argus`中`Schema`服务 + +重启网关后可在区块连浏览器中使用搜索功能 \ No newline at end of file diff --git a/docs/jdchain_cli.md b/docs/jdchain_cli.md new file mode 100644 index 00000000..dcab9053 --- /dev/null +++ b/docs/jdchain_cli.md @@ -0,0 +1,30 @@ +## JD Chain Cli + +JD Chain 命令行工具集，提供密钥管理，实时交易，链上信息查询，离线交易，共识节点变更等操作。 + +```bash +:bin$ ./jdchain-cli.sh -h +Usage: jdchain-cli [-hV] [--pretty] [--home=] [COMMAND] +JDChain Cli is a convenient tool to manage jdchain keys, sign and send +transactions to jdchain network, query data from jdchain network. + -h, --help Show this help message and exit. + --home= Set the home directory. + --pretty Pretty json print + -V, --version Print version information and exit. + +Commands: + +The most commonly used git commands are: + keys List, create, update or delete keypairs. + tx Build, sign or send transaction. + query Query commands. + participant Add, update or delete participant. + help Displays help information about the specified command + +See 'jdchain-cli help ' to read about a specific subcommand or concept. +``` + +- `keys` [密钥管理](cli/keys.md) +- `tx` [交易](cli/tx.md) +- `query` [链上信息查询](cli/query.md) +- `participant` [共识节点变更](cli/participant.md) \ No newline at end of file diff --git a/docs/kvdb.md b/docs/kvdb.md new file mode 100644 index 00000000..4774f20a --- /dev/null +++ b/docs/kvdb.md @@ -0,0 +1,365 @@ +## RocksDB as a server + +### 1.简介 + +`KVDB`是一个简单的`NoSQL`数据库，支持简单的“键值”读写操作。 + +`KVDB`包装了`RocksDB`作为数据库引擎，实现了单机部署和集群部署。 + +`KVDB`的集群是一个分布式的分片服务集群，每个分片节点是一个`KVDB`的数据库服务实例，采用对等模式部署，没有主节点。 + +### 2.安装 + +> java 版本>= 1.8 + +下载源代码，执行： +```bash +mvn clean package +``` +`kvdb-server`模块`target`下会生成`kvdb-***.zip`，解压缩安装包，结构如下： +```bash +bin # 脚本文件目录 + start # 启动本机的数据库服务的脚本文件 + stop # 停止本机的数据库服务的脚本文件 + kvdb-cli # 连接本机的数据库服务控制台的脚本文件 + kvdb-benchmark # 基准测试 +conf # 配置文件目录 + kvdb.conf # 本机的数据库服务配置 + cluster.conf # 数据库集群的配置 +libs # 数据库服务的代码库目录 +system # 系统数据目录 + dblist # 文件记录了本数据库服务实例装载的数据库列表 + pid # 文件记录了本数据库服务实例的运行进程ID；当服务实例运行时创建，服务实例退出后删除 +``` + +### 3.部署配置 + +#### 3.1 `kvdb.conf` + +```bash +# 数据库服务的本机监听地址； +server.host=0.0.0.0 + +# 数据库服务的本机监听端口； +server.port=7078 + +# 管理控制台的端口； +# 注：管理控制台总是绑定到环回地址 127.0.0.1，只允许本机访问； +manager.port=7060 + +# 数据库实例默认的根目录 +dbs.rootdir=/usr/kvdb/dbs + +# 数据库实例默认的本地分区数 +dbs.partitions=4 + +# 是否禁用WAL +wal.disable=false + +# WAL刷新机制，-1跟随系统，0实时刷新，n(n>0)秒刷新一次 +wal.flush=1 +``` + +> `WAL`写入成功，但`RocksDB`写入失败，服务器将在后续所有数据库读写操作前根据`WAL`进行重试操作，直至成功。 + +#### 3.2 `cluster.conf` +```bash +# 数据库集群的分片数，每一个分片都赋予唯一的编号，分片编号最小为 0，所有分片的编号必须连续递增 +# ‘’表示集群名称，只允许用字母、数字、下划线组成； +cluster..partitions=3 + +# 数据库集群 ‘’ 的第 1 个分片的数据库实例地址(URL格式)； +cluster..0=kvdb://:/ + +# 数据库集群 ‘’ 的第 2 个分片的数据库实例地址(URL格式)； +cluster..1=kvdb://:/ + +# 数据库集群 ‘’ 的第 3 个分片的数据库实例地址(URL格式)； +cluster..2=kvdb://:/ + +# 指定多个不同的集群 +#cluster..partitions=3 +... +``` +> 一个数据库实例只能加入唯一的集群；一旦加入集群，则不能再被客户端以单库连接方式访问，对该库实例的连接自动转为集群连接。集群中配置的数据库必须在`dblist`中已存在且设置为`true` +> 所有`host`使用明确的可通畅连接的地址，不同服务器节点中同一集群配置必须完全一致 + +#### 3.3 `dblist` +```bash +# 是否激活数据库 ‘’ ；如果为`true`，则创建或加载该数据库并提供访问； +# ‘’表示数据库名称，只允许用字母、数字、下划线组成； +# db..enable=true + +# 数据库 的根目录；如果未配置，则从默认目录加载(由`conf/kvdb.conf`指定了默认配置${dbs.rootdir}/)； +# db.test.rootdir= + +# 数据库 的本地分区数；如果未配置，则采用`conf/kvdb.conf`中指定的默认配置${dbs.partitions} +# db.test.partitions= +``` +> `dblist`中配置的数据库会在`kvdb-server`启动时自动创建。在`kvdb-server`启动完成后由管理工具执行`create database `创建数据库，创建成功的数据库会追加到`dblist`中。使用`kvdb-cli`命令行工具执行数据库实例更新操作。 + +#### 3.4 日志 + +1. `kvdb-server` + +修改`bin`目录下，`start.sh`文件： +```bash +LOG_SET="-Dlogging.path="$HOME/logs" -Dlogging.level=ERROR" +``` +默认日志路径：程序解压缩后主目录下`logs`目录 +默认日志等级：`ERROR` + +可配置日志等级：`ALL`,`TRACE`,`DEBUG`,`INFO`,`WARN`,`ERROR`,`FATAL`,`OFF` + +2. `kvdb-cli` + +修改`bin`目录下，`kvdb-cli.sh`文件： +```bash +LOG_SET="-Dlogging.path="$HOME/logs" -Dlogging.level.root=error" +``` +默认日志路径：程序解压缩后主目录下`logs`目录 +默认日志等级：`error` + +#### 3.5 启动 + +```bash +./start.sh +``` +#### 停止 +```bash +./stop.sh +``` + +### 4.SDK + +1. 依赖 +```maven + + com.jd.blockchain + kvdb-client + ${project.version} + +``` + +2. 创建客户端连接 +```java +// `host`、`port`为服务器地址和端口，`database`为数据库名称 +KVDBClient client = new KVDBClient("kvdb://:/"); +# KVDBClient client = new KVDBClient(new KVDBURI("kvdb://:/")); +# KVDBClient client = new KVDBClient(new ClientConfig(host, port, db)); +``` + +> 对于集群的连接，客户端将开启`WAL`，在`WAL`写入成功，部分服务器失败的情况下，客户端在执行后续所有操作前都将根据`WAL`日志执行重试操作，直至成功。 + +3. 操作 + +```java +/** + * 存在性查询 + * + * @param key + * @return + * @throws KVDBException + */ +boolean exists(Bytes key) throws KVDBException; + +/** + * 存在性查询，支持多个键值 + * + * @param keys + * @return + * @throws KVDBException + */ +boolean[] exists(Bytes... keys) throws KVDBException; + +/** + * 键值获取 + * + * @param key + * @return + * @throws KVDBException + */ +Bytes get(Bytes key) throws KVDBException; + +/** + * 键值获取，支持多个键值 + * + * @param keys + * @return + * @throws KVDBException + */ +Bytes[] get(Bytes... keys) throws KVDBException; + +/** + * 设置键值对 + * + * @param key + * @param value + * @return + * @throws KVDBException + */ +boolean put(Bytes key, Bytes value) throws KVDBException; + +/** + * 设置键值对 + * + * @param key + * @param value + * @param aSync + * @return + * @throws KVDBException + */ +boolean put(Bytes key, Bytes value, boolean aSync) throws KVDBException; + +/** + * 开启批处理 + * + * @return + * @throws KVDBException + */ +boolean batchBegin() throws KVDBException; + +/** + * 取消批处理 + * + * @return + * @throws KVDBException + */ +boolean batchAbort() throws KVDBException; + +/** + * 提交批处理，服务器掉线重连后会丢失未提交批处理数据 + *

+ * 未提交的`batch`对其他客户端连接不可见。 + * + * @return + * @throws KVDBException + */ +boolean batchCommit() throws KVDBException; + +/** + * 提交批处理 + * + * @param size 此次批处理操作去重后的key数量 + * @return + * @throws KVDBException + */ +boolean batchCommit(long size) throws KVDBException; + +/** + * 关闭 + */ +void close(); +``` + +### 5.管理工具 + +`kvdb-cli`是基于[`SDK`](#SDK)的命令行工具实现： + +```bash +./kvdb-cli.sh -h -p -db -t