APIP8V1_EncryptedInfoOnChain(zh-CN)



  • APIP8:EncryptedInfoOnChain
    Version:1
    Language:zh-CN
    Author:C_armX
    Status:draft
    Createddate:2021-12-01
    Update:2021-12-01
    Filehash:""
    TXid:
    

    APIP8V1_EncryptedInfoOnChain(zh-CN)


    目录

    关于APIP

    本协议的基本共识

    1.链上密信接口

    2.链上联系人接口

    3.链上保险柜接口


    Type:APIP
    SerialNumber:8
    ProtocolName:EncryptedInfoOnChain
    Version:1
    Description:定义密信、联系人、保险柜等链上加密信息接口。
    Author:C_armX
    Language:zh-CN
    tags:APIP,API, on-chain, mail, contact, safe, encrypted, op_return
    preVersionHash:""
    

    关于APIP

    1. APIP(Application Programming Interface Protocols)是自由共识生态协议的一种类型,用于创建开放的API文档,并且按照《FEIP1_FreeProtocol》协议发布在Freecash主链上。

    2. API的URL路径由服务方按照《FEIP29_Service》协议发布在Freecash主链上。

    3. APIP类型协议的一般共识在《APIP1_OpenAPI》中描述,包括接口标识、连接方式、请求方式、数据验证、常用参数、筛选与排序方式等。

    4. 按照《APIP1_OpenAPI》,API请求方向API服务方请求连接请求数据的流程概括如下:

      • 建立连接:请求方通过connect接口提交私钥签名,请求连接API服务,成功后获得对称密钥secretKey用于数据请求和验证。

      • 准备参数:请求数据时,在请求参数中加入timestamp,采用POST方法时,还需加入API的url

      • 参数排序:所有请求参数按字母升序排列,不区分大小写。

      • 数据签名:将secretKey追加至参数末尾,然后经两次sha256哈希获得签名sign

      • 发送请求:删除secretKey字段,将requestersign追加至末尾,发送给服务方。

      • 验证请求:API服务方验证requester授权、signtimestamp、POST方法url等均有效或正确后予以响应。

      • 响应数据:响应数据尾部加入secretKey后做两次sha256哈希获得sign,再用sign替换secretKey后将数据返回请求方。

      • 验证数据:请求方获得数据后,用secretKey替换sign后哈希签名,值与sign值一致则接受数据。

    本协议的基本共识

    1. 本协议接口提供密信、联系人、保险柜等链上加密信息。

    2. 本协议接口的数据来源遵循以下协议:

      • 《FEIP7_MailOnChain》
      • 《FEIP12_Contacts》
      • 《FEIP17_Safe》
    3. 本协议接口数据采用JSON格式。

    4. 示例数据:

    requester的地址:FEk41Kqjar45fLDriztUDTUkdki7mmcjWK
    
    requester的公钥:030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a
    
    requester的私钥:L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8
    
    requester的secretKey:d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09
    
    apiURL:https://www.sign.cash/api/
    

    1.链上密信接口

    名称

    mailOnChain

    说明

    根据筛选条件获取链上密信信息。

    请求参数

    name type description required
    filterSender string Filter by the address of the first input. N
    filterRecipient string Filter by the address of the first output. N
    filterDeleted bool Filter by whether it has been deleted. 1 means it has been deleted. N
    filterAlg string Filter by encrypt algorithm. N
    filterTxTimestamp string Filter by the timestamp of the transaction N
    sortTxTimestamp string Sort by the timestamp of the transaction N
    sortDeleted string Filter by whether it has been deleted. N
    count uint How many entries are wanted in a single request. N
    sequence uint Sequence in continuous request.Start from 0. N
    • 示例

    第2批获取20封收件人为F99999999999999999999999xxxx的未删除密信,按时间倒序排列。

    参数

    {
    	"filterRecipinent": "F99999999999999999999999xxxx",
    	"filterDeleted": 0,
    	"sortTxTimestamp": "down",
        "count":20,
        "sequence":1
    }
    

    GET

    - unsignedRequest:
    
    https://www.sign.cash/api/mailOnChain?count=20&filterDeleted=0&filterRecipinent=F99999999999999999999999xxxx&sequence=1&sortTxTimestamp=down&timestamp=1635513688254
    
    - sign =sha256(sha256(https://www.sign.cash/api/mailOnChain?aid=00000000000000000000000000111111111111111132222222222222&aid=2222222200000000000000000001111111111111111333333333333333&timestamp=1635513688254&secretKey=d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09))=00000000000000000000011111111111111111111111
    
    - signedRequest:
    
    https://www.sign.cash/api/mailOnChain?aid=00000000000000000000000000111111111111111132222222222222&aid=2222222200000000000000000001111111111111111333333333333333&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=00000000000000000000011111111111111111111111
    

    POST

    - URL:https://www.sign.cash/api/mailOnChain
    
    - unsignedRequest:
    
    {"count":20,"filterDeleted":0,"filterRecipinent":"F99999999999999999999999xxxx","sequence":1,"sortTxTimestamp":"down","timestamp":1635513688254,"url":"https://www.sign.cash/api/mailOnChain"}
    
    - sign =sha256(sha256({"count":20,"filterDeleted":0,"filterRecipinent":"F99999999999999999999999xxxx","sequence":1,"sortTxTimestamp":"down","secretKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))=0000000222223333333333355555555555
    
    - signedRequest:
    
    {"count":20,"filterDeleted":0,"filterRecipinent":"F99999999999999999999999xxxx","sequence":1,"sortTxTimestamp":"down","timestamp":1635513688254,"url":"https://www.sign.cash/api/mailOnChain","requester":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","sign":"0000000222223333333333355555555555"}
    

    响应参数

    name type description
    mailList object See below.
    height uint The latest block height when getting the data.
    • mailList
    name type description key in FEIP7
    alg string The encrypt algorithm data.alg
    msgSend Mail encrypted with the public key of the sender data.msgSend
    msgReci Mail encrypted with the public key of the recipient data.msgReci
    sender string The address of the first input.
    recipient string The address of the first output.
    deleted bool Filter by whether it has been deleted. 1 means it has been deleted.
    txid string The txid of this transaction
    txTimestamp timestamp The timestamp of this transaction
    block uint The height of the block where the transaction is written
    • 示例

    响应第2批获取20封收件人为F99999999999999999999999xxxx的未删除密信,按时间倒序排列。

    {
    	"mailList": [{
    			"alg": "ECC256k1-AES256CBC",
    			"msgSend": "Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
    			"msgReci": "Aooooooooooooooooooooooooooooooooo=",
    			"sender": "F1111111111111111111xxxx",
    			"recipient": "F99999999999999999999999xxxx",
    			"deleted": 0,
    			"txid": "022222222222222222222222222",
    			"txTimestamp": 1636526891,
    			"block": 923432
    		},
    		{
    			"alg": "ECC256k1-AES256CBC",
    			"msgSend": "Arrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr=",
    			"msgReci": "Asssssssssssssssssssssssssssssssss=",
    			"sender": "F222222222222222222222222xxxx",
    			"recipient": "F99999999999999999999999xxxx",
    			"deleted": 0,
    			"txid": "033333333333333333333333333333",
    			"txTimestamp": 1636834722,
    			"block": 902000
    		}
    	],
    	"height": 989430
    }
    

    排序、压缩、签名后:

    
    {"height":989430,"mailList":[{"alg":"ECC256k1-AES256CBC","block":923432,"deleted":0,"msgReci":"Aooooooooooooooooooooooooooooooooo=","msgSend":"Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=","recipient":"F99999999999999999999999xxxx","sender":"F1111111111111111111xxxx","txTimestamp":1636526891,"txid":"022222222222222222222222222"},{"alg":"ECC256k1-AES256CBC","block":902000,"deleted":0,"msgReci":"Asssssssssssssssssssssssssssssssss=","msgSend":"Arrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr=","recipient":"F99999999999999999999999xxxx","sender":"F222222222222222222222222xxxx","txTimestamp":1636834722,"txid":"033333333333333333333333333333"}],"sign":"00000000000000000000011111111111111111111111"}
    
    

    返回值

    返回值 类型 必填 说明
    code uint Y 返回码
    msg string Y 返回信息
    data object N 相关数据
    • 返回信息详情
    code msg 说明 data字段
    0 OK 请求成功
    1 Unknown error. 未知错误 signedRequest
    4000 No matching record. 没有符合条件的信息。 signedRequest
    • 示例
    {
    	"code": 4000,
    	"msg": "No matching record.",
    	"data": {
    		"signedRequest": "https://www.sign.cash/api/mailOnChain?aid=00000000000000000000000000111111111111111132222222222222&aid=2222222200000000000000000001111111111111111333333333333333&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=00000000000000000000011111111111111111111111"
    	}
    }
    

    2.链上联系人接口

    名称

    contactsOnChain

    说明

    根据筛选条件获取链上联系人信息。

    请求参数

    name type description required
    filterHost string Filter by the host, the first address of the first output. N
    filterOperator string Filter by the operator,the first address of the first input. N
    filterDeleted bool Filter by whether it has been deleted. 1 means it has been deleted. N
    filterAlg string Filter by encrypt algorithm. N
    filterTxTimestamp string Filter by the timestamp of the transaction N
    sortTxTimestamp string Sort by the timestamp of the transaction N
    sortDeleted string Filter by whether it has been deleted. N
    count uint How many entries are wanted in a single request. N
    sequence uint Sequence in continuous request.Start from 0. N
    • 示例

    第2批获取20条由F99999999999999999999999xxxx为自己保存的未删除联系人信息,按时间倒序排列。

    参数

    {
    	"filterHost": "F99999999999999999999999xxxx",
    	"filterOperator": "F99999999999999999999999xxxx",
    	"filterDeleted": 0,
    	"sortTxTimestamp": "down",
        "count":20,
        "sequence":1
    }
    

    GET

    - unsignedRequest:
    
    https://www.sign.cash/api/contactsOnChain?count=20&filterDeleted=0&filterHost=F99999999999999999999999xxxx&filterOperator=F99999999999999999999999xxxx&sequence=1&sortTxTimestamp=down&timestamp=1635513688254
    
    - sign =sha256(sha256(https://www.sign.cash/api/contactsOnChain?count=20&filterDeleted=0&filterHost=F99999999999999999999999xxxx&filterOperator=F99999999999999999999999xxxx&sequence=1&sortTxTimestamp=down&timestamp=1635513688254&secretKey=d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09))=00000000000000000000011111111111111111111111
    
    - signedRequest:
    
    https://www.sign.cash/api/contactsOnChain?count=20&filterDeleted=0&filterHost=F99999999999999999999999xxxx&filterOperator=F99999999999999999999999xxxx&sequence=1&sortTxTimestamp=down&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=00000000000000000000011111111111111111111111
    

    POST

    - URL:https://www.sign.cash/api/contactsOnChain
    
    - unsignedRequest:
    
    {"count":20,"filterDeleted":0,"filterHost":"F99999999999999999999999xxxx","filterOperator":"F99999999999999999999999xxxx","sequence":1,"sortTxTimestamp":"down","url":"https://www.sign.cash/api/contactsOnChain"}
    
    - sign =sha256(sha256({"count":20,"filterDeleted":0,"filterRecipinent":"F99999999999999999999999xxxx","sequence":1,"sortTxTimestamp":"down","secretKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))=0000000222223333333333355555555555
    
    - signedRequest:
    
    {"count":20,"filterDeleted":0,"filterHost":"F99999999999999999999999xxxx","filterOperator":"F99999999999999999999999xxxx","sequence":1,"sortTxTimestamp":"down","url":"https://www.sign.cash/api/contactsOnChain","requester":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","sign":"0000000222223333333333355555555555"}
    

    响应参数

    name type description
    contactList object See below.
    height uint The latest block height when getting the data.
    • contactList
    name type description key in FEIP12
    alg string The encrypt algorithm data.alg
    msg Contact information encrypted with the public key of the host data.msg
    host string The host, the first address of the first output. N
    operator string The operator,the first address of the first input. N
    deleted bool Filter by whether it has been deleted. 1 means it has been deleted.
    txid string The txid of this transaction
    txTimestamp timestamp The timestamp of this transaction
    block uint The height of the block where the transaction is written
    • 示例

    响应第2批获取20条由F99999999999999999999999xxxx为自己保存的未删除联系人信息,按时间倒序排列。

    {
    	"contactList": [{
    			"alg": "ECC256k1-AES256CBC",
    			"msg": "Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
    			"host": "F1111111111111111111xxxx",
    			"operator": "F99999999999999999999999xxxx",
    			"deleted": 0,
    			"txid": "022222222222222222222222222",
    			"txTimestamp": 1636526891,
    			"block": 923432
    		},
    		{
    			"alg": "ECC256k1-AES256CBC",
    			"msg": "Arrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr=",
    			"host": "F222222222222222222222222xxxx",
    			"operator": "F99999999999999999999999xxxx",
    			"deleted": 0,
    			"txid": "033333333333333333333333333333",
    			"txTimestamp": 1636834722,
    			"block": 902000
    		}
    	],
    	"height": 989430
    }
    

    排序、压缩、签名后:

    {"contactList":[{"alg":"ECC256k1-AES256CBC","block":923432,"deleted":0,"host":"F1111111111111111111xxxx","msg":"Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=","operator":"F99999999999999999999999xxxx","txTimestamp":1636526891,"txid":"022222222222222222222222222"},{"alg":"ECC256k1-AES256CBC","block":902000,"deleted":0,"host":"F222222222222222222222222xxxx","msg":"Arrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr=","operator":"F99999999999999999999999xxxx","txTimestamp":1636834722,"txid":"033333333333333333333333333333"}],"height":989430,"sign":"00000000000000000000011111111111111111111111"}
    
    

    返回值

    返回值 类型 必填 说明
    code uint Y 返回码
    msg string Y 返回信息
    data object N 相关数据
    • 返回信息详情
    code msg 说明 data字段
    0 OK 请求成功
    1 Unknown error. 未知错误 signedRequest
    4000 No matching record. 没有符合条件的信息。 signedRequest
    • 示例
    {
    	"code": 4000,
    	"msg": "No matching record.",
    	"data": {
    		"signedRequest": "https://www.sign.cash/api/contactsOnChain?count=20&filterDeleted=0&filterHost=F99999999999999999999999xxxx&filterOperator=F99999999999999999999999xxxx&sequence=1&sortTxTimestamp=down&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=00000000000000000000011111111111111111111111
    	}
    }
    

    3.链上保险柜接口

    名称

    safeOnChain

    说明

    根据筛选条件获取链上保险柜信息。

    请求参数

    name type description required
    filterHost string Filter by the host, the first address of the first output. N
    filterOperator string Filter by the operator,the first address of the first input. N
    filterDeleted bool Filter by whether it has been deleted. 1 means it has been deleted. N
    filterAlg string Filter by encrypt algorithm. N
    filterTxTimestamp string Filter by the timestamp of the transaction N
    sortTxTimestamp string Sort by the timestamp of the transaction N
    sortDeleted string Filter by whether it has been deleted. N
    count uint How many entries are wanted in a single request. N
    sequence uint Sequence in continuous request.Start from 0. N
    • 示例

    第2批获取20条由F99999999999999999999999xxxx为自己保存的未删除保险柜信息,按时间倒序排列。

    参数

    {
    	"filterHost": "F99999999999999999999999xxxx",
    	"filterOperator": "F99999999999999999999999xxxx",
    	"filterDeleted": 0,
    	"sortTxTimestamp": "down",
        "count":20,
        "sequence":1
    }
    

    GET

    - unsignedRequest:
    
    https://www.sign.cash/api/safeOnChain?count=20&filterDeleted=0&filterHost=F99999999999999999999999xxxx&filterOperator=F99999999999999999999999xxxx&sequence=1&sortTxTimestamp=down&timestamp=1635513688254
    
    - sign =sha256(sha256(https://www.sign.cash/api/safeOnChain?count=20&filterDeleted=0&filterHost=F99999999999999999999999xxxx&filterOperator=F99999999999999999999999xxxx&sequence=1&sortTxTimestamp=down&timestamp=1635513688254&secretKey=d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09))=00000000000000000000011111111111111111111111
    
    - signedRequest:
    
    https://www.sign.cash/api/safeOnChain?count=20&filterDeleted=0&filterHost=F99999999999999999999999xxxx&filterOperator=F99999999999999999999999xxxx&sequence=1&sortTxTimestamp=down&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=00000000000000000000011111111111111111111111
    
    

    POST

    - URL:https://www.sign.cash/api/safeOnChain
    
    - unsignedRequest:
    
    {"count":20,"filterDeleted":0,"filterHost":"F99999999999999999999999xxxx","filterOperator":"F99999999999999999999999xxxx","sequence":1,"sortTxTimestamp":"down","url":"https://www.sign.cash/api/safeOnChain"}
    
    - sign =sha256(sha256({"count":20,"filterDeleted":0,"filterRecipinent":"F99999999999999999999999xxxx","sequence":1,"sortTxTimestamp":"down","secretKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))=0000000222223333333333355555555555
    
    - signedRequest:
    
    {"count":20,"filterDeleted":0,"filterHost":"F99999999999999999999999xxxx","filterOperator":"F99999999999999999999999xxxx","sequence":1,"sortTxTimestamp":"down","url":"https://www.sign.cash/api/safeOnChain","requester":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","sign":"0000000222223333333333355555555555"}
    

    响应参数

    name type description
    safeList object See below.
    height uint The latest block height when getting the data.
    • safeList
    name type description key in FEIP17
    alg string The encrypt algorithm data.alg
    msg Safe entry information encrypted with the public key of the host data.msg
    host string The host, the first address of the first output. N
    operator string The operator,the first address of the first input. N
    deleted bool Filter by whether it has been deleted. 1 means it has been deleted.
    txid string The txid of this transaction
    txTimestamp timestamp The timestamp of this transaction
    block uint The height of the block where the transaction is written
    • 示例

    响应第2批获取20条由F99999999999999999999999xxxx为自己保存的未删除保险柜条目信息,按时间倒序排列。

    {
    	"safeLsit": [{
    			"alg": "ECC256k1-AES256CBC",
    			"msg": "Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
    			"host": "F1111111111111111111xxxx",
    			"operator": "F99999999999999999999999xxxx",
    			"deleted": 0,
    			"txid": "022222222222222222222222222",
    			"txTimestamp": 1636526891,
    			"block": 923432
    		},
    		{
    			"alg": "ECC256k1-AES256CBC",
    			"msg": "Arrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr=",
    			"host": "F222222222222222222222222xxxx",
    			"operator": "F99999999999999999999999xxxx",
    			"deleted": 0,
    			"txid": "033333333333333333333333333333",
    			"txTimestamp": 1636834722,
    			"block": 902000
    		}
    	],
    	"height": 989430
    }
    

    排序、压缩、签名后:

    
    {"safeList":[{"alg":"ECC256k1-AES256CBC","block":923432,"deleted":0,"host":"F1111111111111111111xxxx","msg":"Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=","operator":"F99999999999999999999999xxxx","txTimestamp":1636526891,"txid":"022222222222222222222222222"},{"alg":"ECC256k1-AES256CBC","block":902000,"deleted":0,"host":"F222222222222222222222222xxxx","msg":"Arrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr=","operator":"F99999999999999999999999xxxx","txTimestamp":1636834722,"txid":"033333333333333333333333333333"}],"height":989430,"sign":"00000000000000000000011111111111111111111111"}
    
    

    返回值

    返回值 类型 必填 说明
    code uint Y 返回码
    msg string Y 返回信息
    data object N 相关数据
    • 返回信息详情
    code msg 说明 data字段
    0 OK 请求成功
    1 Unknown error. 未知错误 signedRequest
    4000 No matching record. 没有符合条件的信息。 signedRequest
    • 示例
    {
    	"code": 4000,
    	"msg": "No matching record.",
    	"data": {
    		"signedRequest": "https://www.sign.cash/api/safeOnChain?count=20&filterDeleted=0&filterHost=F99999999999999999999999xxxx&filterOperator=F99999999999999999999999xxxx&sequence=1&sortTxTimestamp=down&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=00000000000000000000011111111111111111111111"
    	}
    }
    

Log in to reply