# 1.java-sdk设计文档
## 1.1 编写目的
本说明书主要阐述自研链java-sdk框架设计，对java-sdk的总体概述，数据结构和业务流程的概述介绍，以及对具体接口的定义。
## 1.2 项目背景
此项目背景为满足建行自研链底层业务需求，通过引入java-sdk，使底层链能更好的满足上层应用开发。

## 1.3 参考资料
无

# 2.总体设计方案

## 2.1 设计前提和约束条件
无

## 2.2 基本设计思想
设计一套灵活的，方便开发人员进行二次开发的java-sdk。

## 2.3 系统整体设计


图:java-sdk架构

sdk 模块架构图如图所示

* 首先，获取自研链的 proto 文件，proto 文件定义了每个模块的 message 数据结构和 rpc 方法及其 grpc-gateway 的请求路径。通过 openapi-generator-cli 工具生成 openapi 文件夹openapi 文件夹下包含了每个模块所提供的 grpc-gateway 接口的具体实现和数据结构。openapi 定义了 ApiClient 结构，包含 QueryApi 和 ServiceApi 服务，以及 header、参数基本校验、错误处理等。

* 其次，sdk 目录为核心代码，根据 openapi 封装定义 interface: sdk.Client 及其实现 sdk.apiClient提供以下功能模块：auth、bank、tbft、base、jvm、permission、wasm、gorverance、upgrade

* 最后，当完成 sdk.apiClient 的实例化后, 既可使用 sdk 所提供的功能模块，通过自研链的 1317 端口与其 grpc-gateway 服务进行通信，实现与链交互。

## 2.4 接口设计

### 2.4.1 给角色添加行为
#### 功能描述
已定义的角色初始化的时候拥有一些行为用来调用相关接口，可以给角色增加新的行为去增加角色的作用域。
* 通过传入执行交易的账户地址，行为名称以及角色列表，构造一条给角色添加行为的消息。通过generateApproveBehavior(final String fromAddress,final List<String>roleNames,final String behavior)方法返回一个TxOuterClass.TxBody象。

* 再通过BroadcastTx200Response broadcastTx(final Client client,finalBroadcastTxRequest.ModeEnum mode, final TxOuterClass.TxBodytxBody, final ErhaiCredentials credentials)方法将消息发送到链上，完成上链交易。

#### 处理流程
1. 由应用层传入给角色赋予行为所需要的参数以及账户的助记词和密码
2. Java-sdk接收到参数之后会利用这些参数生成对应的消息体
3. 利用传进来的账户助记词生成签名所需要的私钥，利用私钥对消息体进行签名
4. 完成签名之后会将签名之后的数据通过链上grpc-gateway的交易执行接口传入到链上进行 消息的处理 。
5. 链上首先会判断消息的有效性，然后会将交易放入mempool中处理打包交易然后出块。
6. 得到响应之后将响应数据反馈给java-sdk

#### 接口与参数
##### 接口说明

| 请求方式 | java调用|
| -------- | -------- |
| 方法名 | broadcastApproveBehavior(final Client client, final BroadcastTxRequest.ModeEnum mode, final String fromMnemonic, final String password, final List<String> roleNames,final String behavior) |
|功能说明|给角色添加行为|

#####请求参数

| 参数 | 类型 | 说明 |
| -------- | -------- | -------- |
| client | Client | sdk客户端 |
| mode | BroadcastTxRequest.ModeEnum | 广播模式 |
| fromMnemonic | String | 账户助记词 |
| password | String | 助记词密码 |
| behavior | String | 行为 |
| roles | List<string> | 角色列表 |

#### 处理流程

### 2.4.2 查询角色行为
#### 功能描述

* 通过传入角色名称，调用getAccountOfRole(final Client client, final String roleName)，查询该角色所拥有的行为。

#### 处理流程
1. 应用层传入需要查看的角色
2. Java-sdk将该角色当做http请求的入参调用链上grpc-gateway相对应的查询接口
3. 链上处理完查询的请求之后将相关数据返回给java-sdk
#### 接口与参数
##### 接口说明

| 请求方式 | java调用|
| -------- | -------- |
| 方法名 | getAccountOfRole(final Client client, final String roleName) |
|功能说明|查询角色行为|

##### 请求参数

| 参数 | 类型 | 说明 |
| -------- | -------- | -------- |
| client | Client | sdk客户端 |
| roleName | String | 角色名称 |

#### 处理流程