APIP15V1_ProofOnChain(zh-CN)
Version:1
Language:zh-CN
Author:C_armX
Status:draft
Create:2022-05-06
Update:2022-05-06
PID:""
TXID:
APIP15V1_ProofOnChain(zh-CN)
目录
Type:APIP
SerialNumber:14
ProtocolName:ProofOnChain
Version:1
Description:定义链上证明信息的接口。
Author:C_armX
Language:zh-CN
preVersionHash:""
关于APIP
概述
APIP(Application Programming Interface Protocols)是自由共识生态协议的一种类型，用于创建和发布开放的API文档，供API服务方开发部署通用API服务，以实现数据服务的去中心化。API需求方可以按照APIP协议从遵循该协议的任何一个API服务方那里获取数据服务。
通用规则
《APIP1_OpenAPI》规范了APIP类型协议的协议发布、接口标识、接口URL构成、时间戳格式、密码算法、服务流程、商业模式、连接接口，数据接口和查询语法的通用规则。设计、开发或应用APIP协议前，应先参考《APIP1_OpenAPI》协议。
建立连接
使用APIP协议各接口，须先采用《APIP1_OpenAPI》的connect接口从API服务方获取symKey。参见《APIP1_OpenAPI》的“connect接口”。
通用请求参数
APIP类型协议接口的通用请求参数如下：
| name | type | description | requested |
|---|---|---|---|
| requester | string | 请求方的fch地址 | Y |
| url | string | 当前所请求api的url | Y |
| timestamp | timestamp | 发起请求的时间戳，精确到毫秒 | Y |
| query | object | 请求数据的查询语句，参见”APIP简易查询语法@APIP1“ | N |
| sort | object | 请求数据的排序语句，参见”APIP简易查询语法@APIP1“ | N |
| from | int | 请求列表数据时的起始位置，从0开始 | N |
| size | int | 请求列表数据时的每页条目数 | N |
| sign | string | 用symkey对其他参数所做的签名 | Y |
通用响应方式
响应前所作的验证、通用响应状态码、通用响应参数参见《APIP1_OpenAPI》的“数据请求接口”的“5. 响应”。
请求成功的通用响应参数为：
| 参数 | 类型 | 说明 | 适用状态 |
|---|---|---|---|
| code | int | 响应状态码 | all |
| message | string | 响应状态描述 | all |
| data | object | 正常返回数据，由具体APIP定义。 | 0 |
| sign | string | 将symKey加入响应参数做两次sha256哈希的签名值 | all |
具体APIP协议的特定响应参数在data参数中给出，并定义具体接口的响应状态。
请求失败的通用响应码、响应信息和响应参数，参见《APIP1_OpenAPI》的“数据请求接口”的“5. 响应”。
签名与验证
APIP接口的请求和响应都需要签名和验证。
connect接口请求时用私钥签名，公钥验证，响应时无需签名。
所有数据请求和数据响应，采用以下方法：
签名：将对称密钥symKey加入参数压缩升序后计算两次sha256，得到sign的值，再用sign替换参数中的symKey。
验证：将sign从参数中取出，加入symKey，压缩升序后做两次sha256计算，将值与sign的值比较，一致则验证通过。
详见《APIP1_OpenAPI》
关于本协议
-
本协议接口提供链上公开发布的声明信息。
-
本协议接口的数据来源和相关规则遵循以下协议：
- 《FEIP33_Proof》
-
本协议接口数据采用JSON格式。
-
示例数据：
requester：FEk41Kqjar45fLDriztUDTUkdki7mmcjWK
requester的公钥pubKey：030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a
requester的私钥priKey：L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8
requester获得的对称密钥symKey：d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09
服务方链上发布的urlMainPart: https://www.sign.cash/api/
接口url：https://www.sign.cash/api/APIP15/v1/[接口名称]
getProofList
获取链上证明信息。
url
[服务方发布的urlMainPart]APIP15/v1/getProofList
示例：
https://www.sign.cash/api/APIP15/v1/getProofList
请求参数
通用请求参数参见通用请求参数。其中：
- query
响应参数data.list中各字段均可作为查询字段。
- sort
响应参数data.list中的数字类型字段均可作为排序字段。
- 示例
查询FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX在链上发布的证明，按交易时间戳倒序，获取从第1条到第20条。
{
"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
"timestamp": 1635513688254,
"url": "https://www.sign.cash/api/APIP15/v1/getProofList",
"query": {
"term": {
"address": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX"
}
},
"sort": [{
"txTimestamp": {
"order": "desc"
}
}],
"from": 0,
"size": 20,
"sign": ""
}
响应参数
通用参数参见通用响应方式。本接口响应参数：
- data
| name | type | description | requested |
|---|---|---|---|
| list | object | See below | |
| total | uint | The total number of items. | Y |
| bestHeight | uint | The latest block height when getting the data. | Y |
- data.list
| name | type | description | key in FEIP33 |
|---|---|---|---|
| proofId | string | The txid in which the proof was issued | |
| issuer | string | The address of the first input of the transaction in which the proof was issued. | |
| holder | string | The address of the recent holder. | |
| signer | string array | The addresses who were invited to sign and signed the proof. | |
| allHolders | string array | All addresses who had held or are holding the proof, inclouding the issuer and the holder. | |
| transferable | string | Is this proof transferable? | data.transferable |
| title | string | The title of Proof | data.title |
| content | string | The content of Proof | data.content |
| firstTimestamp | timeStamp | The timeStamp of the transaction in which the proof was first published. | |
| firstBlockHeight | uint | The height of the block in which the proof was first published. | |
| lastTxid | string | The txid of the last operation of the proof. | |
| lastTimestamp | timeStamp | The transaction timestamp of the last operation of the proof. | |
| lastBlockHeight | uint | The height of the block of the last operation of the proof. | |
| tCdd | uint64 | The total destroyed coindays of all transactions with valid operation. | |
| status | bool | Is the proof in effect. |
- 示例
响应查询FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX在链上发布的证明，按交易时间戳倒序，获取从第1条到第20条。
{
"code": 0,
"message": "Success.",
"data": {
"list": [{
"proofId": "222220000000000011111",
"issuer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
"holder": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
"signer": [""],
"allHolder": ["FEk41Kqjar45fLDriztUDTUkdki7mmcjWK", "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX"],
"transferable": 1,
"title": "IOU",
"content": "I owe the holder 1000usdt to be paid back on January 1, 2023 at 10% APR.",
"firstTimestamp": 1610261291,
"firstBlockHeight": 963510,
"lastTxid": "1111111111111111111111111",
"lastTimestamp": 1636526891,
"lastBlockHeight": 963512,
"tCdd": 12300000,
"status": 1
},
{
"proofId": "33333300000000000000000",
"issuer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
"holder": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
"signer": [""],
"allHolder": ["FEk41Kqjar45fLDriztUDTUkdki7mmcjWK", "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX"],
"transferable": 0,
"title": "Stock of sign.cash",
"content": "The holder of this proof has a 10% stake in sign.cash.",
"firstTimestamp": 1619261292,
"firstBlockHeight": 963600,
"lastTxid": "3333300000000222222233333",
"lastTimestamp": 1619261292,
"lastBlockHeight": 963612,
"tCdd": 221800,
"status": 1
}
],
"total": 2,
"bestHeight": 963667
},
"sign": ""
}
- 响应状态
参见《APIP1_OpenAPI》的“数据请求接口”的“5. 响应”。
getProofOpHistory
查询证明链上操作历史信息。
url
[服务方发布的urlMainPart]apip6/v1/getProofOpHistory
示例：
https://www.sign.cash/api/apip6/v1/getProofOpHistory
请求参数
通用请求参数参见通用请求参数。其中：
- query
响应参数data.list中各字段均可作为查询字段。
- sort
响应参数data.list中的数字类型字段均可作为排序字段。
- 示例
查询proofID为"0000000011111111111111111111111222"的证明操作记录，按交易时间戳倒序，获取第1批20条。
{
"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
"timestamp": 1635513688254,
"url": "https://www.sign.cash/api/apip7/v1/getProofOpHistory",
"query": {
"term": {
"proofID": "0000000011111111111111111111111222"
}
},
"sort": [{
"txTimestamp": {
"order": "desc"
}
}],
"from": 0,
"size": 20,
"sign": ""
}
响应参数
通用参数参见通用响应方式。本接口响应参数：
- data
| name | type | description | requested |
|---|---|---|---|
| list | object | See below | |
| total | uint | The total number of items. | Y |
| bestHeight | uint | The latest block height when getting the data. | Y |
- data.list
| name | type | description |
|---|---|---|
| proofId | string | |
| op | string | The operation. |
| signer | uint | The address of the first input of the transaction |
| recipients | string array | The addresses of the outputs except the signer. |
| transferable | string | Is this proof transferable? |
| title | string | The title of Proof |
| content | string | The content of Proof |
| cdd | uint64 | Coindays destroyed |
| txid | string | The txid of this transaction |
| txTimestamp | timestamp | The timestamp of this transaction |
| blockHeight | uint | The height of the block where the transaction is written |
- 示例
响应proofId为"0000000011111111111111111111111222"的证明操作历史，按交易时间戳倒序，从0到20条。
{
"code": 0,
"message": "Success.",
"data": {
"list": [{
"proofId": "0000000011111111111111111111111222",
"op": "destroy",
"signer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
"recipients": [""],
"cdd": 200,
"txid": "333333333333333333",
"txTimestamp": 1618999999999,
"blockHeight": 989999
},
{
"proofId": "0000000011111111111111111111111222",
"op": "issue",
"signer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
"recipients": ["FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX"],
"transferable": 0,
"title": "Stock of sign.cash",
"content": "The holder of this proof has a 10% stake in sign.cash.",
"cdd": 3100,
"txid": "2222222222222222222222",
"txTimestamp": 1618832997321,
"blockHeight": 989302
}
],
"total": 2,
"bestHeight": 993667
},
"sign": ""
}
- 响应状态
参见《APIP1_OpenAPI》的“数据请求接口”的“5. 响应”。