昌
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)
目录
关于APIP
关于本协议
getProofList
getProofOpHistory
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. 响应”。