

# 零、 项目情况

人员构成  
产品经理：汪雪巍    
项目经理：  ？  
区块链合约开发：张振华    
DAPP前端开发：？    
DAPP服务端开发：？    


开发周期  
区块链合约：开发2周，联调1周  
DAPP前端开发：待评估  
DAPP服务端开发：待评估  

# 一、需求描述  

参见下图：
![竞猜需求](./resource/guess-requirement.png)

管理员可发布竞猜主题到区块链合约上，比如特朗普中期选举结果是什么？  选项：A：只赢得众议院 B：只赢得参议院 C：赢得参众两院 D：参众两院都输  
主题可限定什么时间或者什么区块高度之前停止投注。  

DAPP用户可参与投注，如果已停止投注，则DAPP上不能再进行投注。  

管理员到时间后，向区块链合约揭晓结果，并触发合约结算。  

合约将抽取一定比例的手续费，将剩余将近按比例分发给赢家。  

用户可查询自己的投注历史记录。

# 二、区块链合约接口  

## 1.平台方创建游戏

动作类型：  

```
start   //启动一次竞猜  
```

请求字段：  

```go
topic   //竞猜的主题，比如：2018年世界杯决赛，法国对阵克罗地亚，谁将夺冠。  
options //竞猜的选项，比如：1.法国,2.克罗地亚  
maxHeight   //截止区块高度，达到此高度后将不能再下注  
maxBetsNumber   //参与竞猜的下注次数限制，达到此数目将不能再下注  
oneBet  //一注的金额，比如5bty，如果不携带该字段表示无限制  
maxBets //单次最多可以下多少注，比如100注，如果不携带该字段表示无限制  
fee //参与精彩收取的费用，如果不带，则不收费  
feeAddr //如果fee字段有，则feeAddr也需要指定合法地址，用于存储收取的费用  
```

响应字段：  

```
gameId  //创建的游戏ID  
```

合约处理：  

>生成游戏ID，记录游戏属性  

## 2.用户下注  

动作类型  

>bet：下注  

请求字段：  

>gameId：竞猜游戏场次ID  
bets：下多少注，比如5注  

响应字段：  

>result: 下注结果，是否成功  
err：错误码： 成功；余额不足；游戏已停止投注；游戏已达最大下注人次  

合约处理：  

>判断是否可以下注（游戏id存在，未截止投注，未达最大下注人次，下注金额符合要求）  
判断用户账户余额是否够  
进行转账冻结的操作，如果需要扣除手续费，则扣除手续费  

## 3.平台方揭晓结果  

动作类型  

>drawing: 开奖  

请求字段：  

>gameId: 竞猜游戏场次  
result: 正确选项，比如2  

响应字段：  

>result：开奖是否成功  
err：错误码：成功；非游戏创建者，无权限开奖；游戏id不存在；游戏已经开过奖了；游戏尚未截止投注，还不能开奖  

合约处理：  

>判断是否可以开奖  
开奖并进行账户结算，将所有下注金额按胜者的下注金额比例进行分配及转账。  

## 4.查询可以参与的竞猜游戏  

动作类型  

>query：查询  

请求字段：  

>type：查询未截止可以参与的竞猜游戏  

响应字段：  

```
[
    {
        gameId: 竞猜游戏ID
       topic：竞猜的主题，比如：2018年世界杯决赛，法国对阵克罗地亚，谁将夺冠  
       options：竞猜的选项，比如：1.法国,2.克罗地亚  
       maxHeight：截止区块高度，达到此高度后将不能再下注  
       maxBetsNumber：参与竞猜的下注次数限制，达到此数目将不能再下注  
       oneBet:一注的金额，比如5bty，如果不携带该字段表示无限制  
       maxBets:单次最多可以下多少注，比如100注，如果不携带该字段表示无限制  
       fee：参与精彩收取的费用，如果不带，则不收费  
       feeAddr：如果fee字段有，则feeAddr也需要指定合法地址，用于存储收取的费用  
       playersNum: 当前参与玩家 数量
       optionsNum:
       [
           {
               option: option1
               betsNum：投注数量
               addrNum:  投注该选项的地址数量
           }
           ...
       ]
    }
    ...
]
```

## 5.状态查询  

动作类型  

```
query   //查询  
```

请求字段：  

```
type：单场次游戏查询
gameId  //竞猜游戏场次ID  
```

响应字段：  

```
topic：竞猜的主题，比如：2018年世界杯决赛，法国对阵克罗地亚，谁将夺冠  
options：竞猜的选项，比如：1.法国,2.克罗地亚  
maxHeight：截止区块高度，达到此高度后将不能再下注  
maxBetwangxuewei竞猜的下注次数限制，达到此数目将不能再下注  
oneBet:一注的金额，比如5bty，如果不携带该字段表示无限制  
maxBets:单次最多可以下多少注，比如100注，如果不携带该字段表示无限制  
fee：参与精彩收取的费用，如果不带，则不收费  
feeAddr：如果fee字段有，则feeAddr也需要指定合法地址，用于存储收取的费用  
players: 当前参与玩家  
[  
    {  
        addr:  投注地址  
        option: 投注选项  
        betsNum:   投注数量  
    }  
    ...
]  
```

## 6.投注记录查询  

动作类型  

```
query：查询  
```

请求字段：  

```
type：单地址单场次游戏查询
gameId：竞猜游戏场次ID  
addrs: 投注地址  
[  
    {  
        addr:   
    }  
]  
```

响应字段：  

```
topic：竞猜的主题，比如：2018年世界杯决赛，法国对阵克罗地亚，谁将夺冠  
options：竞猜的选项，比如：1.法国,2.克罗地亚  
maxHeight：截止区块高度，达到此高度后将不能再下注  
maxBetsNumber：参与竞猜的下注次数限制，达到此数目将不能再下注  
oneBet:一注的金额，比如5bty，如果不携带该字段表示无限制  
maxBets:单次最多可以下多少注，比如100注，如果不携带该字段表示无限制  
fee：参与精彩收取的费用，如果不带，则不收费  
feeAddr：如果fee字段有，则feeAddr也需要指定合法地址，用于存储收取的费用  
players: 当前参与玩家  
[  
    {  
        addr:  投注地址  
        option:  投注选项  
        betsNum:   投注数量  
    }  
    ...
]  
```

# 三、流程及逻辑    

# 1.由菠菜平台代用户集中投注到竞猜合约  

![平台集中投注的时序图](./resource/guess-sequence1.png)  

该方案中，菠菜平台服务端，要提供更多接口给Dapp：  

1. 管理员界面，可以发布不同类别的竞猜游戏，设置参数包括：  

>游戏类别：比如金融、体育、区块链、票房、选举等  
游戏主题：topic  
游戏选项：options  
游戏投注规则：币种（bty、游戏币等）、单注数量、单次下注上限、收费标准（可选）、收费地址（可选）、截止时间、投注人次上限  

2. 对于发布的游戏及用户参与游戏的历史记录等提供记录存储和访问接口，减轻区块链的压力，保证用户体验。  

3. 对于用户投注，进行中心化管理，截止时间后，集中代投注到合约中，结算时合约先结算，服务端再对每个用户进行中心化结算，减轻区块链合约的处理压力。


# 2.由用户各自分散投注到竞猜合约  

![用户分散投注的时序图](./resource/guess-sequence2.png)  

该方案中，菠菜平台服务端提供以下能力：  
1. 管理员界面，可以发布不同类别的竞猜游戏，设置参数包括：  

>游戏类别：比如金融、体育、区块链、票房、选举等  
游戏主题：topic  
游戏选项：options  
游戏投注规则：币种（bty、游戏币等）、单注数量、单次下注上限、收费标准（可选）、收费地址（可选）、截止时间、投注人次上限  

2. 对于发布的游戏及用户参与游戏的历史记录等提供记录存储和访问接口，减轻区块链的压力，保证用户体验。  

3. 对于用户投注，每次投注都单独投注到合约，区块链合约需要存储较多的信息，并在结算时直接结算给每个投注地址，区块链合约需要处理的事情比较多。

# 四、UI效果参考   

参考效果：  

## 1.竞猜游戏分类  

![竞猜游戏分类](./resource/guess/list-category.jpg)  

## 2.竞猜游戏列表  

![竞猜游戏列表](./resource/guess/list2.jpg)     ![竞猜游戏列表2](./resource/guess/list.jpg)  

## 3.竞猜游戏  

![竞猜游戏](./resource/guess/item.jpg)  

## 4.竞猜游戏下注

样例1：  

![竞猜游戏下注](./resource/guess/bet1_1.jpg)    ![竞猜游戏下注](./resource/guess/bet1_2.jpg)  

样例2：  

![竞猜游戏下注](./resource/guess/bet2_1.jpg)    ![竞猜游戏下注](./resource/guess/bet2_2.jpg)  

## 5.竞猜游戏停止下注

![竞猜游戏停止下注](./resource/guess/stop_bet.jpg)    

## 6.参与的竞猜游戏历史记录  

![竞猜游戏停止下注](./resource/guess/history.jpg)   