# 区块链接口


## 1 获取版本 Version

**调用接口**

```
rpc Version(ReqNil) returns (VersionInfo) {}
```

**参数：**
nil

**返回数据：**

```
message VersionInfo {
    string title   = 1;
    string app     = 2;
    string chain33 = 3;
    string localDb = 4;
    int32  chainID = 5;
}
```

**参数说明：**

| 参数    | 类型   | 说明                                        |
| :------ | :----- | :------------------------------------------ |
| title   | string | 区块链名，该节点chain33.toml中配置的title值 |
| app     | string | 应用app的版本                               |
| chain33 | string | 版本信息，版本号-GitCommit(前八个字符)      |
| localDb | string | localdb版本号                               |
| chainID | string | chain ID                                    |

## 2 获取区间区块 GetBlocks

**调用接口**

```
rpc GetBlocks(ReqBlocks) returns (Reply) {}
```

**参数：**

```
 {
    int64    start      = 1;
    int64    end        = 2;
    bool     isDetail   = 3;
    repeated string pid = 4;
}
```

**参数说明：**

| 参数     | 类型     | 说明                 |
| :------- | :------- | :------------------- |
| start    | int64    | 开始区块高度         |
| end      | int64    | 结束区块高度         |
| isDetail | bool     | 是否打印区块详细信息 |
| pid      | []string | peer列表             |

**返回数据：**

```
message Reply {
    bool  isOk = 1;
    bytes msg  = 2;
}
Decode msg 得到 BlockDetails
message BlockDetails {
    repeated BlockDetail items = 1;
}
message BlockDetail {
    Block    block                   = 1;
    repeated ReceiptData receipts    = 2;
    repeated KeyValue KV             = 3;
    bytes             prevStatusHash = 4;
}
message Block {
    int64     version        = 1;
    bytes     parentHash     = 2;
    bytes     txHash         = 3;
    bytes     stateHash      = 4;
    int64     height         = 5;
    int64     blockTime      = 6;
    uint32    difficulty     = 11;
    bytes     mainHash       = 12;
    int64     mainHeight     = 13;
    Signature signature      = 8;
    repeated Transaction txs = 7;
}
message ReceiptData {
    int32    ty              = 1;
    repeated ReceiptLog logs = 3;
}
message ReceiptLog {
    int32 ty  = 1;
    bytes log = 2;
}
```

**参数说明：**

| 参数                   | 类型        | 说明                                                         |
| :--------------------- | :---------- | :----------------------------------------------------------- |
| items                  | BlockDetail | 区块数组；包含区块信息；                                     |
| items.block            | Block       | 区块的信息                                                   |
| items.block.version    | int64       | 区块版本                                                     |
| items.block.parentHash | bytes       | 上一区块的部分header信息序列化后的哈希值                     |
| items.block.txHash     | bytes       | 所有交易序列化后的哈希值                                     |
| items.block.stateHash  | bytes       | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| items.block.txs        | Transaction | 交易信息                                                     |
| items.recipts          | ReceiptData | 交易执行结果信息                                             |

## 3 获取最新的区块头 GetLastHeader

**调用接口**

```
rpc GetLastHeader(ReqNil) returns (Header) {}
```

**参数：**
nil

**返回数据：**

```
message Header {
    int64     version    = 1;
    bytes     parentHash = 2;
    bytes     txHash     = 3;
    bytes     stateHash  = 4;
    int64     height     = 5;
    int64     blockTime  = 6;
    int64     txCount    = 9;
    bytes     hash       = 10;
    uint32    difficulty = 11;
    Signature signature  = 8;
}
```

**参数说明：**

| 参数       | 类型   | 说明                                                         |
| :--------- | :----- | :----------------------------------------------------------- |
| version    | int64  | 区块版本                                                     |
| parentHash | bytes  | 上一区块的部分header信息序列化后的哈希值                     |
| txHash     | bytes  | 所有交易序列化后的哈希值                                     |
| stateHash  | bytes  | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| difficulty | uint32 | 困难值                                                       |

## 4 获取区间区块头 GetHeaders

**调用接口**

```
rpc GetHeaders(ReqBlocks) returns (Headers) {}
```

**参数：**

```
message ReqBlocks {
    int64    start      = 1;
    int64    end        = 2;
    bool     isDetail   = 3;
    repeated string pid = 4;
}
```

**参数说明：**

| 参数     | 类型     | 说明                 |
| :------- | :------- | :------------------- |
| start    | int64    | 开始区块高度         |
| end      | int64    | 结束区块高度         |
| isDetail | bool     | 是否打印区块详细信息 |
| pid      | []string | peer列表             |

**返回数据：**

```
message Headers {
    repeated Header items = 1;
}
message Header {
    int64     version    = 1;
    bytes     parentHash = 2;
    bytes     txHash     = 3;
    bytes     stateHash  = 4;
    int64     height     = 5;
    int64     blockTime  = 6;
    int64     txCount    = 9;
    bytes     hash       = 10;
    uint32    difficulty = 11;
    Signature signature  = 8;
}
```

**参数说明：**

| 参数  | 类型     | 说明           |
| :---- | :------- | :------------- |
| items | []Header | 区块头信息数组 |

## 5 获取区块哈希值 GetBlockHash

**调用接口**

```
rpc GetBlockHash(ReqInt) returns (ReplyHash) {}
```

**参数：**

```
message ReqInt {    int64 height = 1;}
```

**参数说明：**

| 参数   | 类型  | 说明                     |
| :----- | :---- | :----------------------- |
| height | int64 | 需要获取哈希的区块的高度 |

**返回数据：**

```
message ReqInt {
    int64 height = 1;
}
```

**参数说明：**

| 参数 | 类型  | 说明       |
| :--- | :---- | :--------- |
| hash | bytes | 区块哈希值 |

## 6 获取区块的详细信息 GetBlockOverview

**调用接口**

```
rpc GetBlockOverview(ReqHash) returns (BlockOverview) {}
```

**参数：**

```
message ReqHash {
    bytes hash    = 1;
    bool  upgrade = 2;
}
```

**参数说明：**

| 参数 | 类型   | 说明       |
| :--- | :----- | :--------- |
| hash | string | 区块哈希值 |

**返回数据：**

```
message BlockOverview {
    Header   head           = 1;
    int64    txCount        = 2;
    repeated bytes txHashes = 3;
}
```

**参数说明：**

| 参数     | 类型    | 说明                               |
| :------- | :------ | :--------------------------------- |
| head     | Header  | 区块头信息                         |
| txHashes | []bytes | 交易哈希数组，包含每个交易的哈希值 |

## 7 通过区块哈希获取区块信息 GetBlockByHashes

**调用接口**

```
rpc GetBlockByHashes(ReqHashes) returns (BlockDetails) {}
```

**参数：**

```
message ReqHashes {
    repeated bytes hashes = 1;
}
```

**参数说明：**

| 参数   | 类型     | 说明         |
| :----- | :------- | :----------- |
| hashes | []string | 区块哈希列表 |

**返回数据：**

```
message BlockDetails {
    repeated BlockDetail items = 1;
}
message BlockDetail {
    Block    block                   = 1;
    repeated ReceiptData receipts    = 2;
    repeated KeyValue KV             = 3;
    bytes             prevStatusHash = 4;
}
```

**参数说明：**

| 参数          | 类型          | 说明                   |
| :------------ | :------------ | :--------------------- |
| items         | []BlockDetail | 区块数组；包含区块信息 |
| items.block   | Block         | 区块的信息             |
| items.recipts | []ReceiptData | 交易执行结果信息       |

## 8 获取区块的序列信息 GetBlockSequences

程序员小哥哥正在努力研发中…

## 9 获取最新区块的序列号 GetLastBlockSequence

**调用接口**

```
rpc GetLastBlockSequence(ReqNil) returns (Int64) {}
```

**参数：**
nil

**返回数据：**

```
Int64
```

**参数说明：**

| 参数   | 类型  | 说明       |
| :----- | :---- | :--------- |
| result | int64 | 区块序列号 |

## 10 注册区块（区块头）推送服务或者合约回执推送服务 AddPushSubscribe

程序员小哥哥正在努力研发中…

## 11 列举推送服务 ListPushes

程序员小哥哥正在努力研发中…

## 12 获取某推送服务最新序列号的值 GetPushSeqLastNum

程序员小哥哥正在努力研发中…