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. 响应”。