# 事件接口

## 1 发布事件

### 1.1 生成发布事件的交易（未签名） CreateTransaction

**调用接口**

```
rpc CreateTransaction(CreateTxIn) returns (UnsignTx) {}
```

**参数：**

```
message CreateTxIn {
    bytes  execer     = 1;
    string actionName = 2;
    bytes  payload    = 3;
}
message EventPublish {
    string type         = 2; //游戏类别
    string subType      = 3; //游戏子类别
    int64  time         = 4; //结果公布参考时间
    string content      = 5; //事件内容
    string introduction = 6; //事件描述
}
```

**参数说明：**

Chain33.CreateTransaction结构按通用要求填写：
execer,执行器名称，这里固定为oralce
actionName,操作名称，这里固定为EventPublish
payload携带的内容格式如下：

| 参数         | 类型   | 说明                             |
| :----------- | :----- | :------------------------------- |
| type         | string | 事件类型                         |
| subType      | string | 事件子类型                       |
| time         | int64  | 事件结果预计公布时间，UTC时间    |
| content      | string | 事件内容，例如可以用json格式表示 |
| introduction | string | 事件介绍                         |

**返回数据：**

```
message UnsignTx {
    bytes data = 1;
}
```

**参数说明：**

| 参数 | 类型  | 说明                     |
| :--- | :---- | :----------------------- |
| data | bytes | 交易十六进制编码后的数据 |

### 1.2 交易签名 SignRawTx

**调用接口**

```
rpc SignRawTx(ReqSignRawTx) returns (ReplySignRawTx) {}
```

**参数：**

```
message ReqSignRawTx {
    string addr    = 1;
    string privkey = 2;
    string txHex   = 3;
    string expire  = 4;
    int32  index   = 5;
    // 签名的模式类型
    // 0：普通交易
    // 1：隐私交易
    // int32  mode  = 6;
    string token = 7;
    int64  fee   = 8;
    // bytes  newExecer = 9;
    string newToAddr = 10;
}
```

**参数说明**

| 参数      | 类型   | 是否必填 | 说明                                                         |
| :-------- | :----- | :------- | :----------------------------------------------------------- |
| addr      | string | 否       | addr与privkey可以只输入其一，如果使用addr则依赖钱包中存储的私钥签名 |
| privkey   | string | 否       | addr与privkey可以只输入其一，如果使用privkey则直接签名       |
| txHex     | string | 是       | 上一步生成的原始交易数据                                     |
| expire    | string | 是       | 过期时间可输入如”300s”，”-1.5h”或者”2h45m”的字符串，有效时间单位为”ns”, “us” (or “µs”), “ms”, “s”, “m”, “h” |
| index     | int32  | 否       | 若是签名交易组，则为要签名的交易序号，从1开始，小于等于0则为签名组内全部交易 |
| token     | string | 否       |                                                              |
| fee       | int64  | 是       | 费用                                                         |
| newToAddr | string | 否       | -                                                            |

**返回数据：**

```
message ReplySignRawTx {
    string txHex = 1;
}
```

**参数说明**

| 参数  | 类型   | 说明                       |
| :---- | :----- | :------------------------- |
| txHex | string | 交易签名后的十六进制字符串 |

### 1.3 发送交易 SendTransaction

**调用接口**

```
rpc SendTransaction(Transaction) returns (Reply) {}
```

**参数：**

```
message Transaction {
    bytes     execer    = 1;
    bytes     payload   = 2;
    Signature signature = 3;
    int64     fee       = 4;
    int64     expire    = 5;
    //随机ID，可以防止payload 相同的时候，交易重复
    int64 nonce = 6;
    //对方地址，如果没有对方地址，可以为空
    string to         = 7;
    int32  groupCount = 8;
    bytes  header     = 9;
    bytes  next       = 10;
    int32  chainID    = 11;
}
```

**参数说明**

| 参数 | 类型        | 是否必填 | 说明                     |
| :--- | :---------- | :------- | :----------------------- |
| tx   | Transaction | 是       | 为上一步签名后的交易数据 |

**返回数据：**

```
message Reply {
    bool  isOk = 1;
    bytes msg  = 2;
}
```

**参数说明**

| 参数 | 类型  | 说明                                                         |
| :--- | :---- | :----------------------------------------------------------- |
| msg  | bytes | 交易发送后，生成的交易哈希 后面可以使用此哈希查询交易状态和历史 |

[go 代码示例](../grpcAPI/transactionAPI.md#13-发送交易-sendtransaction)

## 2 生成取消发布事件的交易（未签名） EventAbort

**调用接口**

```
rpc CreateTransaction(CreateTxIn) returns (UnsignTx) {}
```

**参数：**

```
message CreateTxIn {
bytes  execer     = 1;
string actionName = 2;
bytes  payload    = 3;
}
message EventAbort {
    string eventID = 2; //发布事件的ID
}
```

**参数说明**

Chain33.CreateTransaction结构按通用要求填写：
execer,执行器名称，这里固定为oralce
actionName,操作名称，这里固定为EventAbort
payload携带的内容格式如下：

| 参数    | 类型   | 说明             |
| :------ | :----- | :--------------- |
| eventID | string | 发布事件的事件ID |

**返回数据：**

```
message UnsignTx {
    bytes data = 1;
}
```

**参数说明：**

| 参数 | 类型  | 说明                     |
| :--- | :---- | :----------------------- |
| data | bytes | 交易十六进制编码后的数据 |

## 3 生成预发布事件结果交易（未签名） ResultPrePublish

**调用接口**

```
rpc CreateTransaction(CreateTxIn) returns (UnsignTx) {}
```

**参数：**

```
message CreateTxIn {
    bytes  execer     = 1;
    string actionName = 2;
    bytes  payload    = 3;
}
message ResultPrePublish {
    string eventID = 2; //发布事件的ID
    string source  = 3; //数据来源
    string result  = 4; //发布数据
}
```

**参数说明**

Chain33.CreateTransaction结构按通用要求填写：
execer,执行器名称，这里固定为oralce
actionName,操作名称，这里固定为ResultPrePublish
payload携带的内容格式如下：

| 参数    | 类型   | 说明                         |
| :------ | :----- | :--------------------------- |
| eventID | string | 发布事件的事件ID             |
| source  | string | 发布结果的源，比如XX体育     |
| result  | string | 发布的事件结果，比如比赛比分 |

**返回数据：**

```
message UnsignTx {
    bytes data = 1;
}
```

**参数说明：**

| 参数 | 类型  | 说明                     |
| :--- | :---- | :----------------------- |
| data | bytes | 交易十六进制编码后的数据 |

## 4 生成取消预发布结果的交易（未签名） ResultAbort

**调用接口**

```
rpc CreateTransaction(CreateTxIn) returns (UnsignTx) {}
```

**参数：**

```
message CreateTxIn {
    bytes  execer     = 1;
    string actionName = 2;
    bytes  payload    = 3;
}
message ResultAbort {
    string eventID = 2; //发布事件的ID
}
```

**参数说明**

Chain33.CreateTransaction结构按通用要求填写：
execer,执行器名称，这里固定为oralce
actionName,操作名称，这里固定为ResultAbort
payload携带的内容格式如下：

| 参数    | 类型   | 说明             |
| :------ | :----- | :--------------- |
| eventID | string | 发布事件的事件ID |

**返回数据：**

```
message UnsignTx {
    bytes data = 1;
}
```

**参数说明：**

| 参数 | 类型  | 说明                     |
| :--- | :---- | :----------------------- |
| data | bytes | 交易十六进制编码后的数据 |

## 5 生成正式发布事件结果交易（未签名） ResultPublish

**调用接口**

```
rpc CreateTransaction(CreateTxIn) returns (UnsignTx) {}
```

**参数：**

```
message CreateTxIn {
    bytes  execer     = 1;
    string actionName = 2;
    bytes  payload    = 3;
}
message ResultPublish {
    string eventID = 2; //发布事件的ID
    string source  = 3; //数据来源
    string result  = 4; //发布数据
}
```

**参数说明**

Chain33.CreateTransaction结构按通用要求填写：
execer,执行器名称，这里固定为oralce
actionName,操作名称，这里固定为ResultPublish
payload携带的内容格式如下：

| 参数    | 类型   | 说明                         |
| :------ | :----- | :--------------------------- |
| eventID | string | 发布事件的事件ID             |
| source  | string | 发布结果的源，比如XX体育     |
| result  | string | 发布的事件结果，比如比赛比分 |

**返回数据：**

```
message UnsignTx {
    bytes data = 1;
}
```

**参数说明：**

| 参数 | 类型  | 说明                     |
| :--- | :---- | :----------------------- |
| data | bytes | 交易十六进制编码后的数据 |

## 6 查询接口

### 6.1 根据发布事件的事件ID查询当前状态 QueryOraclesByIDs

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message QueryOracleInfos {
    repeated string eventID = 1; //发布的事件的ID
}
```

**参数说明：**

| 参数      | 类型     | 说明                                                         |
| :-------- | :------- | :----------------------------------------------------------- |
| driver    | bytes    | 执行器名称, 这里固定为 oracle                                |
| funcName  | string   | 操作名称, 这里固定为 QueryOraclesByIDs                       |
| stateHash | bytes    | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param     | bytes    | types.Encode(&QueryOracleInfos)                              |
| extra     | bytes    | 扩展字段，用于额外的用途                                     |
| eventID   | []string | 需要查询信息的事件ID数组                                     |

**返回数据：**

```
message ReplyOracleStatusList {
    repeated OracleStatus status = 1; //状态集
}
message OracleStatus {
    string      eventID      = 1;  //事件ID
    string      addr         = 2;  //发布者地址
    string      type         = 3;  //游戏类别
    string      subType      = 4;  //游戏子类别
    int64       time         = 5;  //结果公布参考时间
    string      content      = 6;  //事件内容
    string      introduction = 7;  //事件描述
    EventStatus status       = 8;  //操作状态
    string      source       = 9;  //数据来源
    string      result       = 10; //事件结果
    EventStatus preStatus    = 11; //上次操作后状态及操作者地址
}
```

**参数说明**

| 参数         | 类型   | 说明                                                         |
| :----------- | :----- | :----------------------------------------------------------- |
| eventID      | string | 事件ID                                                       |
| addr         | string | 事件的地址                                                   |
| type         | string | 事件的类型                                                   |
| subType      | string | 发布事件的子类型                                             |
| time         | int64  | 事件结果预计公布时间，UTC时间                                |
| content      | string | 事件内容，例如可以用json格式表示                             |
| introduction | string | 事件介绍                                                     |
| status       | json   | 当前状态，包括操作者地址，当前状态值；0：初始状态，1：事件已发布，2：事件已取消，3：事件结果已预发布，4：事件预发布的结果已取消，5：事件结果已发布 |
| source       | string | 发布结果的源，比如XX体育                                     |
| result       | string | 发布事件的结果，比如比赛比分                                 |
| preStatus    | json   | 前一个状态，包括操作者地址，当前状态值                       |

### 6.2 根据事件所处状态查询事件ID QueryEventIDsByStatus

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message QueryEventID {
    int32  status  = 1; //事件状态
    string addr    = 2; //事件发布者的地址
    string type    = 3; //事件类型
    string eventID = 4; //事件ID
}
```

**参数说明：**

| 参数      | 类型   | 是否必须 | 说明                                                         |
| :-------- | :----- | :------- | :----------------------------------------------------------- |
| driver    | bytes  | 是       | 执行器名称, 这里固定为 oracle                                |
| funcName  | string | 是       | 操作名称, 这里固定为 QueryEventIDsByStatus                   |
| stateHash | bytes  | 否       | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param     | bytes  | 是       | types.Encode(&QueryEventID)                                  |
| extra     | bytes  | 否       | 扩展字段，用于额外的用途                                     |
| status    | int32  | 是       | 事件所处状态值                                               |
| addr      | string | 不填     | 创建事件的地址                                               |
| type      | string | 不填     | 事件的类型                                                   |
| eventID   | string | 视情况   | 事件ID，第一次查询为空，如果得到结果数量超过一页，将eventID设置为上次查询结果的最后一个id，从而查到下一页的数据 |

**返回数据：**

```
message ReplyEventIDs {
    repeated string eventID = 1; //发布事件的ID
}
```

**参数说明**

| 参数    | 类型     | 说明                 |
| :------ | :------- | :------------------- |
| eventID | []string | 符合条件的事件ID数组 |

### 6.3 根据创建事件的用户地址和事件所处状态查询事件ID QueryEventIDsByAddrAndStatus

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message QueryEventID {
    int32  status  = 1; //事件状态
    string addr    = 2; //事件发布者的地址
    string type    = 3; //事件类型
    string eventID = 4; //事件ID
}
```

**参数说明：**

| 参数      | 类型   | 是否必须 | 说明                                                         |
| :-------- | :----- | :------- | :----------------------------------------------------------- |
| driver    | bytes  | 是       | 执行器名称, 这里固定为 oracle                                |
| funcName  | string | 是       | 操作名称, 这里固定为 QueryEventIDsByAddrAndStatus            |
| stateHash | bytes  | 否       | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param     | bytes  | 是       | types.Encode(&QueryEventID)                                  |
| extra     | bytes  | 否       | 扩展字段，用于额外的用途                                     |
| status    | int32  | 是       | 事件所处状态值                                               |
| addr      | string | 是       | 创建事件的地址                                               |
| type      | string | 不填     | 事件的类型                                                   |
| eventID   | string | 视情况   | 事件ID，第一次查询为空，如果得到结果数量超过一页，将eventID设置为上次查询结果的最后一个id，从而查到下一页的数据 |

**返回数据：**

```
message ReplyEventIDs {
    repeated string eventID = 1; //发布事件的ID
}
```

**参数说明**

| 参数    | 类型     | 说明                 |
| :------ | :------- | :------------------- |
| eventID | []string | 符合条件的事件ID数组 |

### 6.4 根据创建事件的类型和事件所处状态查询事件ID

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message QueryEventID {
    int32  status  = 1; //事件状态
    string addr    = 2; //事件发布者的地址
    string type    = 3; //事件类型
    string eventID = 4; //事件ID
}
```

**参数说明：**

| 参数      | 类型   | 是否必须 | 说明                                                         |
| :-------- | :----- | :------- | :----------------------------------------------------------- |
| driver    | bytes  | 是       | 执行器名称, 这里固定为 oracle                                |
| funcName  | string | 是       | 操作名称, 这里固定为 QueryEventIDsByTypeAndStatus            |
| stateHash | bytes  | 否       | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param     | bytes  | 是       | types.Encode(&QueryEventID)                                  |
| extra     | bytes  | 否       | 扩展字段，用于额外的用途                                     |
| status    | int32  | 是       | 事件所处状态值                                               |
| addr      | string | 不填     | 创建事件的地址                                               |
| type      | string | 是       | 事件的类型                                                   |
| eventID   | string | 视情况   | 事件ID，第一次查询为空，如果得到结果数量超过一页，将eventID设置为上次查询结果的最后一个id，从而查到下一页的数据 |

**返回数据：**

```
message ReplyEventIDs {
    repeated string eventID = 1; //发布事件的ID
}
```

**参数说明**

| 参数    | 类型     | 说明                 |
| :------ | :------- | :------------------- |
| eventID | []string | 符合条件的事件ID数组 |