# Unfreeze

> 定期解冻合约帮助用户锁定一定量的币， 按在指定的规制解冻给受益人，
> 适用于分期付款， 分期支付形式的员工激励等情景。

**合约提供了3类操作**

1. 创建定期解冻合约：创建时需要指定支付的资产和总量，以及定期解冻的形式。
2. 受益人提币：受益人提走解冻了的资产。
3. 发起人终止合约： 发起人可以终止合约的履行。

**解冻的形式目前支持两种**

1. 固定数额解冻：指定时间间隔，解冻固定的资产。
2. 按剩余量的固定比例解冻：指定时间间隔，按剩余量的固定比例解冻。 这种方式，越到后面解冻的越少。

------

> 说明：在合约创建时，就可以解冻一次。
> 举例：一个固定数额解冻和合约，总量为100，一个月解冻10。创建时可以由受益人提走10，第一个月后又可以提走10。
> 在受益人没有及时提币的情况下，受益人在一段时间之后可以一次性提走本该解冻的所有的币。
> 即解冻的币是按指定形式解冻的，和受益人的提币时间和次数等都不会影响解冻的进程。

## 1 创建交易

### 1.1 命令行

```
创建定期解冻合约
./chain33-cli send   unfreeze  create fix_amount -a 0.01  -e coins -s bty -b  12qyocayNF7Lv6C9qW4avxs2E7U41fKSfv -p 60 -t 2  -k  private-key
受益人提币
./chain33-cli send  unfreeze   withdraw  --id mavl-unfreeze-1a8c91077df8e2be644f61b59706be8f7745f9b800868a73624956bd551abe41  -k private-key
发起人终止合约
./chain33-cli send  unfreeze   terminate  --id mavl-unfreeze-1a8c91077df8e2be644f61b59706be8f7745f9b800868a73624956bd551abe41  -k private-key
```

### 1.2 rpc 接口

#### 1.2.1 创建定期解冻合约CreateRawUnfreezeCreate

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method" : "unfreeze.CreateRawUnfreezeCreate",
    "params" : [
        {
            "assetSymbol" : "bty",
            "assetExec" : "coins",
            "means" : "FixAmount",
            "totalCount" : 400000000,
            "beneficiary" : "",
            "startTime" : 10000,
            "fixAmount" : {
                "period" : 10,
                "amount" : 1000000
            }
        }
    ]
}
```

**参数说明：**

| 参数        | 类型                      | 说明                                                   |
| :---------- | :------------------------ | :----------------------------------------------------- |
| assetSymbol | string                    | 要冻结的资产名称                                       |
| assetExec   | string                    | 要冻结的资产执行器                                     |
| totalCount  | int64                     | 冻结的资产数量， 单位是 1e-8， 即数量除以10的8次方个币 |
| beneficiary | string                    | 受益人地址                                             |
| startTime   | int64                     | 开始解冻时间， UTC 秒， 默认为交易被打包时间           |
| means       | string                    | 指定解冻算法， 有效值 FixAmount LeftProportion         |
| meansOpt    | isUnfreezeCreate_MeansOpt | 具体解冻算法的参数，参见下面的说明                     |

meansOpt的不同取值说明：

|参数|类型|说明|
| :---------- | :------------------------ | :----------------------------------------------------- |
| fixAmount | struct | 按指定时间间隔，解冻固定的资产。|
| fixAmount.period | int64 | 按指定时间间隔，单位秒。|
| fixAmount.amount | int64 | 解冻指定的资产数量。单位 1e-8个币 |
| leftProportion | struct | 按剩余量的固定比例解冻：指定时间间隔，按剩余量的固定比例解冻。 这种方式，越到后面解冻的越少。|
| leftProportion.period | int64 | 按指定时间间隔，单位秒。|
| leftProportion.tenThousandth | int64 | 固定比例，单位万分之一。 |

**响应报文：**

```
{
    "id":int32,
    "result":"string"
}
```

**参数说明：**

| 参数   | 类型   | 说明                         |
| :----- | :----- | :--------------------------- |
| result | string | 交易对象的十六进制字符串编码 |

#### 1.2.2 受益人提取CreateRawUnfreezeWithdraw

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method" : "unfreeze.CreateRawUnfreezeWithdraw",
    "params" : [{"unfreezeID" : "string"}]
}
```

**参数说明：**

| 参数       | 类型   | 说明                                                         |
| :--------- | :----- | :----------------------------------------------------------- |
| unfreezeID | string | 冻结合约的ID， 可以查询创建冻结合约时，得到， 同创建冻结合约的交易ID的十六进制 |

**响应报文：**

```
{
    "id":int32,
    "result":"string"
}
```

**参数说明：**

| 参数   | 类型   | 说明                         |
| :----- | :----- | :--------------------------- |
| result | string | 交易对象的十六进制字符串编码 |

#### 1.2.3 终止冻结合约CreateRawUnfreezeTerminate

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method" : "unfreeze.CreateRawUnfreezeTerminate",
    "params" : [{"unfreezeID" : "string"}]
}
```

**参数说明：**

| 参数       | 类型   | 说明                                                         |
| :--------- | :----- | :----------------------------------------------------------- |
| unfreezeID | string | 冻结合约的ID， 可以查询创建冻结合约时，得到， 同创建冻结合约的交易ID的十六进制 |

**响应报文：同其他创建交易接口， 需要在签名发送**

```
{
    "id":int32,
    "result":"string"
}
```

**参数说明：**

| 参数   | 类型   | 说明                         |
| :----- | :----- | :--------------------------- |
| result | string | 交易对象的十六进制字符串编码 |

## 2 查询合约状态 GetUnfreeze

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method" : "Chain33.Query"
    "params" : [
        {
            "funcName" : "GetUnfreeze",
            "payload" : {"data":"1a8c91077df8e2be644f61b59706be8f7745f9b800868a73624956bd551abe41"},
            "execer" : "unfreeze"
        }
    ]
}
```

**参数说明：**

| 参数 | 类型   | 说明                                                         |
| :--- | :----- | :----------------------------------------------------------- |
| data | string | 合约的ID，可以查询创建冻结合约时得到，同创建冻结合约的交易ID的十六进制，是对应的unfreezeID去掉前缀 “mavl-unfreeze-“。 |

**响应报文：**

```
{
    "id":int32,
    "result" : {
        "assetSymbol" : "bty",
        "assetExec" : "coins",
        "startTime" : "1543888918",
        "unfreezeID" : "mavl-unfreeze-1a8c91077df8e2be644f61b59706be8f7745f9b800868a73624956bd551abe41",
        "initiator" : "14KEKbYtKKQm4wMthSK9J4La4nAiidGozt",
        "totalCount" : "200000000",
        "remaining" : "0",
        "means" : "FixAmount",
        "fixAmount" : {
            "period" : "60",
            "amount" : "1000000"
        },
        "beneficiary" : "12qyocayNF7Lv6C9qW4avxs2E7U41fKSfv",
        "terminated":bool
    },
    "error" : null

```

**参数说明：**

| 参数        | 类型   | 说明                                                         |
| :---------- | :----- | :----------------------------------------------------------- |
| assetSymbol | string | 资产标识                                                     |
| assetExec   | string | 资产所在执行器名                                             |
| startTime   | string | 合约生效时间， UTC 秒数                                      |
| unfreezeID  | string | 具体数据，这里合约的ID， 可以查询创建冻结合约时，得到， 同创建冻结合约的交易ID的十六进制。是对应的unfreezeID去掉前缀 “mavl-unfreeze-“ |
| initiator   | string | 合约创建者                                                   |
| beneficiary | string | 合约受益人                                                   |
| totalCount  | string | 冻结资产总数                                                 |
| remaining   | string | 合约中剩余资产总数                                           |
| means       | string | 合约解冻算法名                                               |
| fixAmount   | struct | 算法对应参数                                                 |
| terminated  | bool   | 是否已经终止                                                 |

## 3 查询合约可提币量 GetUnfreezeWithdraw

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method" : "Chain33.Query"
    "params" : [
        {
            "funcName" : "GetUnfreezeWithdraw",
            "payload" : {"data" : "1a8c91077df8e2be644f61b59706be8f7745f9b800868a73624956bd551abe41"},
            "execer" : "unfreeze"
        }
    ]
}
```

**参数说明：**

| 参数 | 类型   | 说明                                                         |
| :--- | :----- | :----------------------------------------------------------- |
| data | string | 合约的ID，可以查询创建冻结合约时得到，同创建冻结合约的交易ID的十六进制，是对应的unfreezeID去掉前缀 “mavl-unfreeze-“。 |

**响应报文：**

```
{
    "id":int32,
    "result" : {
        "availableAmount" : "0",
        "unfreezeID" : "mavl-unfreeze-1a8c91077df8e2be644f61b59706be8f7745f9b800868a73624956bd551abe41"
    },
    "error" : null
}
```

**参数说明：**

| 参数            | 类型   | 说明                                                         |
| :-------------- | :----- | :----------------------------------------------------------- |
| unfreezeID      | string | 具体数据，这里合约的ID，是对应创建合约的交易Hash加上前缀 “mavl-unfreeze-“ |
| availableAmount | int64  | 合约中解冻了的但还没有被提走的资产数目                       |

## 4 用创建地址查询合约列表 ListUnfreezeByCreator

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method" : "Chain33.Query",
    "params" : [
        {
            "funcName" : "ListUnfreezeByCreator",
            "execer" : "unfreeze",
            "payload" : {
                "initiator" : "1EDnnePAZN48aC2hiTDzhkczfF39g1pZZX",
                "direction":int32,
                "count":int32,
                "fromKey":"string",
                "beneficiary":"string"
            }
        }
    ]
}
```

**参数说明：**

| 参数        | 类型   | 说明                     |
| :---------- | :----- | :----------------------- |
| initiator   | string | 具体数据，创建合约的地址 |
| beneficiary | string | 受益人地址               |
| count       | int32  | 查询的数量               |
| direction   | int32  | 查询的方向               |
| fromKey     | string | 查询开始的主键           |

**响应报文：**

```
{
    "id":int32
    "result" : {
        "unfreeze" : [
            {
                "means" : "FixAmount",
                "assetExec" : "coins",
                "key" : "000000000053200001",
                "startTime" : "10000",
                "fixAmount" : {
                    "period" : "10",
                    "amount" : "1000000"
                },
                "terminated" : false,
                "initiator" : "1EDnnePAZN48aC2hiTDzhkczfF39g1pZZX",
                "remaining" : "0",
                "unfreezeID" : "mavl-unfreeze-086bca6fa6a7f232df95802637c756526abc04a9ea7169191fb90f389d914471",
                "beneficiary" : "1PUiGcbsccfxW3zuvHXZBJfznziph5miAo",
                "assetSymbol" : "bty",
                "totalCount" : "400000000"
            }
        ]
    },
    "error" : null
}
```

**参数说明：**

| 参数        | 类型   | 说明                                                         |
| :---------- | :----- | :----------------------------------------------------------- |
| assetSymbol | string | 资产标识                                                     |
| assetExec   | string | 资产所在执行器名                                             |
| startTime   | string | 合约生效时间， UTC 秒数                                      |
| unfreezeID  | string | 具体数据，这里合约的ID， 可以查询创建冻结合约时，得到， 同创建冻结合约的交易ID的十六进制。是对应的unfreezeID去掉前缀 “mavl-unfreeze-“ |
| initiator   | string | 合约创建者                                                   |
| beneficiary | string | 合约受益人                                                   |
| totalCount  | string | 冻结资产总数                                                 |
| remaining   | string | 合约中剩余资产总数                                           |
| means       | string | 合约解冻算法名                                               |
| fixAmount   | struct | 算法对应参数                                                 |

## 5 用受益地址查询合约列表 ListUnfreezeByBeneficiary

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method" : "Chain33.Query",
    "params" : [
        {
            "funcName" : "ListUnfreezeByBeneficiary",
            "execer" : "unfreeze",
            "payload" : {
                "beneficiary":"1PUiGcbsccfxW3zuvHXZBJfznziph5miAo",
                "initiator" : "1EDnnePAZN48aC2hiTDzhkczfF39g1pZZX",
                "direction":int32,
                "count":int32,
                "fromKey":"string"
            }
        }
    ]
}
```

**参数说明：**

| 参数        | 类型   | 说明           |
| :---------- | :----- | :------------- |
| initiator   | string | 创建者地址     |
| beneficiary | string | 受益人地址     |
| count       | int32  | 查询的数量     |
| direction   | int32  | 查询的方向     |
| fromKey     | string | 查询开始的主键 |

**响应报文：**

```
{
    "id":int32
    "result" : {
        "unfreeze" : [
            {
                "means" : "FixAmount",
                "assetExec" : "coins",
                "key" : "000000000053200001",
                "startTime" : "10000",
                "fixAmount" : {
                    "period" : "10",
                    "amount" : "1000000"
                },
                "terminated" : false,
                "initiator" : "1EDnnePAZN48aC2hiTDzhkczfF39g1pZZX",
                "remaining" : "0",
                "unfreezeID" : "mavl-unfreeze-086bca6fa6a7f232df95802637c756526abc04a9ea7169191fb90f389d914471",
                "beneficiary" : "1PUiGcbsccfxW3zuvHXZBJfznziph5miAo",
                "assetSymbol" : "bty",
                "totalCount" : "400000000"
            }
        ]
    },
    "error" : null
}
```

**参数说明：**

| 参数        | 类型   | 说明                                                         |
| :---------- | :----- | :----------------------------------------------------------- |
| assetSymbol | string | 资产标识                                                     |
| assetExec   | string | 资产所在执行器名                                             |
| startTime   | string | 合约生效时间， UTC 秒数                                      |
| unfreezeID  | string | 具体数据，这里合约的ID， 可以查询创建冻结合约时，得到， 同创建冻结合约的交易ID的十六进制。是对应的unfreezeID去掉前缀 “mavl-unfreeze-“ |
| initiator   | string | 合约创建者                                                   |
| beneficiary | string | 合约受益人                                                   |
| totalCount  | string | 冻结资产总数                                                 |
| remaining   | string | 合约中剩余资产总数                                           |
| means       | string | 合约解冻算法名                                               |
| fixAmount   | struct | 算法对应参数                                                 |

