APIP4V1_Reputation(zh-CN)



  • APIP4: Reputation
    Version: 1
    Language: zh-CN
    Author: C_armX
    Status: draft
    Created date: 2021-11-18
    Update: 2021-11-28
    File hash: ""
    TXid: 
    

    APIP4V1_Reputation(zh-CN)


    目录

    关于APIP

    本协议的基本共识

    [1. 声誉查询接口](#1. 声誉查询接口)

    [2. 被评记录查询接口](#2. 被评记录查询接口)

    [3. 主评记录查询接口](#3. 主评记录查询接口)


    Type: APIP
    SerialNumber: 4
    ProtocolName: Reputation
    Version: 1
    Description : 主体声誉和相互评价相关接口.
    Author: C_armX
    Language: zh-CN
    tags: APIP, API, Reputation, 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. 本协议接口的数据来源遵循以下协议:

      • Reputation:《FEIP16_Reputation》
    3. 本协议接口数据采用JSON格式。

    4. 示例数据:

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

    1. 声誉查询接口

    名称

    reputationList

    说明

    查询一个或多个地址的声誉值。

    请求参数

    name type description
    addressList string array FCH address list
    • 示例

    查询FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX,FEk41Kqjar45fLDriztUDTUkdki7mmcjWK,FT7P7SxogDhx3eSpFGqCsjnFNaMcfwPi7Z的声誉值。

    参数

    {
    	"addressList": ["FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX", "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK", "FT7P7SxogDhx3eSpFGqCsjnFNaMcfwPi7Z"],
    	"timestamp": 1635513688254
    }
    

    GET

    
    - unsignedRequest:
    
    https://www.sign.cash/api/reputationList?addressList=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&addressList=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&addressList=FT7P7SxogDhx3eSpFGqCsjnFNaMcfwPi7Z&timestamp=1635513688254
    
    - sign = sha256(sha256(https://www.sign.cash/api/reputationList?addressList=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&addressList=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&addressList=FT7P7SxogDhx3eSpFGqCsjnFNaMcfwPi7Z&timestamp=1635513688254&secretKey=d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09))=11111111111111111111110000002232222222222
    
    - signedRequest:
    
    https://www.sign.cash/api/reputationList?addressList=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&addressList=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&addressList=FT7P7SxogDhx3eSpFGqCsjnFNaMcfwPi7Z&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=11111111111111111111110000002232222222222
    

    POST

    - URL:https://www.sign.cash/api/reputationList
    
    - unsignedRequest:
    
    {"addressList":["FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX","FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","FT7P7SxogDhx3eSpFGqCsjnFNaMcfwPi7Z"],"timestamp":1635513688254,"url":"https://www.sign.cash/api/reputationList"}
    
    - sign = sha256(sha256({"addressList":["FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX","FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","FT7P7SxogDhx3eSpFGqCsjnFNaMcfwPi7Z"],"timestamp":1635513688254,"url":"https://www.sign.cash/api/reputationList","secretKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))=11111111111111111111110000002232222222222
    
    - signedRequest:
    
    {"addressList":["FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX","FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","FT7P7SxogDhx3eSpFGqCsjnFNaMcfwPi7Z"],"timestamp":1635513688254,"url":"https://www.sign.cash/api/reputationList","requester":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","sign":"00000000000000000000011111111111111111111111"}}
    

    响应参数

    name type description
    reputationList object List of addresses and their reputations.See below
    height uint The latest block height when getting the data.
    • reputationList
    name type description
    address string FCH address
    reputation uint64 value of reputation defined in "FEIPFEIP16_Reputation"
    tCdd uint64 All destroyed coindays accumulated by all transactions evaluating this address.
    • 示例
    
    {
    	"reputationList": [{
    			"address": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
    			"reputation": 348300,
    			"tCdd": 20400233
    
    		},
    		{
    			"address": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    			"reputation": 8824000,
    			"tCdd": 400233
    		},
    		{
    			"address": "FT7P7SxogDhx3eSpFGqCsjnFNaMcfwPi7Z",
    			"reputation": 71320000,
    			"tCdd": 1220400200
    		}
    	],
    	"height": 963667
    }
    
    
    排序、压缩、签名后:
    
    {"height":963667,"reputationList":[{"address":"FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX","reputation":348300,"tCdd":20400233},{"address":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","reputation":8824000,"tCdd":400233},{"address":"FT7P7SxogDhx3eSpFGqCsjnFNaMcfwPi7Z","reputation":71320000,"tCdd":1220400200}],"sign":"00000000000000000000011111111111111111111111"}
    
    

    返回值

    返回值 类型 必填 说明
    code uint Y 返回码
    msg string Y 返回信息
    data object N 相关数据
    • 返回信息详情
    code msg 说明 data字段
    0 OK 请求成功
    1 Unknown error. 未知错误 signedRequest
    3006 Too many addresses are requested. 请求的地址数量太多。 maxAddresses
    • 示例
    {
        "code":3006,
        "msg":"Too many addresses are requested.",
        "data":{
            "maxAddresses":100
        }
    }
    

    2. 被评记录查询接口

    名称

    ratedHistory

    说明

    获取某地址被他人评价的历史记录。

    请求参数

    name type description required
    address string FCH address Y
    filterCdd string Filter by cdd N
    filterRater string Filter by the address of the rater N
    filterRatingSign string Filter the sign of rating, "+" or "-". N
    filterTxTimestamp string Filter by the timestamp of transaction N
    sortTxTimestamp string Sort by the timestamp of transaction N
    count uint How many entries are wanted in a single request. N
    sequence uint Sequence in continuous request.Start from 0. N
    • 示例

    查询币天销毁在2000以上的FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX的被评价的历史记录,按交易时间降序,每次请求20条,首次请求。

    参数

    {
    	"address": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
    	"filterCdd": "2000-",
    	"sortTxTimestamp": "down",
    	"count": 20,
    	"timestamp": 1635513688254
    }
    

    GET

    - unsignedRequest:
    
    https://www.sign.cash/api/ratedHistory?address=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&count=20&filterCdd=2000-&sortTxTimestamp=down&timestamp=1635513688254
    
    - sign = sha256(sha256(https://www.sign.cash/api/ratedHistory?address=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&count=20&filterCdd=2000-&sortTxTimestamp=down&timestamp=1635513688254&secretKey=d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09))=ded5aed4d84fab123943cef117ecbeeb5338212caa44647e0f51805282632ec4
    
    - signedRequest:
    
    https://www.sign.cash/api/ratedHistory?address=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&count=20&filterCdd=2000-&sortTxTimestamp=down&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=ded5aed4d84fab123943cef117ecbeeb5338212caa44647e0f51805282632ec4
    

    POST

    - URL:https://www.sign.cash/api/ratedHistory
    
    - unsignedRequest:
    
    {"address":"FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX","count":20,"filterCdd":"2000-","sortTxTimestamp":"down","timestamp":1635513688254,"url":"https://www.sign.cash/api/ratedHistory"}
    
    - sign = sha256(sha256({"address":"FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX","count":20,"filterCdd":"2000-","sortTxTimestamp":"down","timestamp":1635513688254,"url":"https://www.sign.cash/api/ratedHistory","secretKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))=87f755ad8ae221a47e7ad93f9780a7f2ab777c2e77dd6516c2b264a69ed2119a
    
    - signedRequest:
    
    {"address":"FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX","count":20,"filterCdd":"2000-","sortTxTimestamp":"down","timestamp":1635513688254,"url":"https://www.sign.cash/api/ratedHistory","requester":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","sign":"87f755ad8ae221a47e7ad93f9780a7f2ab777c2e77dd6516c2b264a69ed2119a"}
    

    响应参数

    name type description
    address string FCH address
    ratedList object All "FEIP3_CID" operation records of this address or cid.See below
    height uint The latest block height when getting the data.
    • ratedList
    name type description
    block uint The height of the block where the transaction is written
    cdd uint64 Destroyed coindays in the rating transaction
    rater string Address of the rater
    ratingSign string The sign of the rating, "+" or "-".
    txid string The txid of this transaction
    txTimestamp timestamp The timestamp of this transaction
    • 示例
    
    {
    	"address": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
    	"ratedList": [{
    			"block": 963002,
    			"cdd": 2834,
    			"rater": "FNEjybqhAjFfAibCX5oLLB4MmV1Pvfdt9D",
    			"ratingSign": "+",
    			"txid": "dc339b7aed07d0e04905ad5c647c936da8b7bbc9b89d0aface18970fdd5fe153",
    			"txTimestamp": 1635513688254
    		},
    
    		{
    			"block": 9628342,
    			"cdd": 3400,
    			"rater": "FRc5NXWeUCAJxnCkJwZ8fyUiWTeXWykk33",
    			"ratingSign": "-",
    			"txid": "4d58e21511145cbb949d8b499398dae12287164a35af24cdbbff203390600d61",
    			"txTimestamp": 16355123487143
    		},
    
    		{
    			"block": 928330,
    			"cdd": 53100,
    			"rater": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    			"ratingSign": "+",
    			"txid": "616e80f09ca67974fd1c79919a451ced8a9f3d24c83437aa439b8f259be16ead",
    			"txTimestamp": 1634503342324
    		}
    	],
    	"height": 963667
    }
    
    排序、压缩、签名后:
    
    {"address":"FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX","height":963667,"ratedList":[{"block":963002,"cdd":2834,"rater":"FNEjybqhAjFfAibCX5oLLB4MmV1Pvfdt9D","ratingSign":"+","txTimestamp":"1635513688254","txid":"dc339b7aed07d0e04905ad5c647c936da8b7bbc9b89d0aface18970fdd5fe153"},{"block":9628342,"cdd":3400,"rater":"FRc5NXWeUCAJxnCkJwZ8fyUiWTeXWykk33","ratingSign":"-","txTimestamp":"1635512348343","txid":"4d58e21511145cbb949d8b499398dae12287164a35af24cdbbff203390600d61"},{"block":928330,"cdd":53100,"rater":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","ratingSign":"+","txTimestamp":"1634503342324","txid":"616e80f09ca67974fd1c79919a451ced8a9f3d24c83437aa439b8f259be16ead"}],"sign":"00000000000000000000011111111111111111111111"}
    
    

    返回值

    返回值 类型 必填 说明
    code uint Y 返回码
    msg string Y 返回信息
    data object N 相关数据
    • 返回信息详情
    code msg 说明 data字段
    0 OK 请求成功
    1 Unknown error. 未知错误 signedRequest
    2000 The address has not been used. 地址从未被使用 address
    4000 No matching record. 没有符合条件的信息。 signedRequest
    • 示例
    {
        "code":4000,
        "msg":"No matching record.",
        "data":{
            "signedRequest":"https://www.sign.cash/api/ratedHistory?address=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&filterCdd=2000&count=20&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=ded5aed4d84fab123943cef117ecbeeb5338212caa44647e0f51805282632ec4"
        }
    }
    

    3. 主评记录查询接口

    名称

    ratingHistory

    说明

    获取某地址评价他人的历史记录。

    请求参数

    name type description required
    address string FCH address Y
    filterCdd string Filter by cdd N
    filterTxTimestamp string Filter by the timestamp of transaction N
    filterRatedAddress string Filter by the ratedAddress N
    filterRatingSign string Filter the sign of rating, "+" or "-". N
    sortTxTimestamp string Sort by the timestamp of transaction N
    count uint How many entries are wanted in a single request. N
    sequence uint Sequence in continuous request.Start from 0. N
    • 示例

    查询币天销毁在2000以上的被FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX评价的历史记录,每次请求20条,首次请求,按交易时间降序排列。

    参数

    {
    	"address": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
    	"filterCdd": "2000-",
    	"sortTxTimestamp": "down",
    	"count": 20,
    	"timestamp": 1635513688254
    }
    

    GET

    - unsignedRequest:
    
    https://www.sign.cash/api/ratingHistory?address=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&count=20&filterCdd=2000-&sortTxTimestamp=down&timestamp=1635513688254
    
    - sign = sha256(sha256(https://www.sign.cash/api/ratingHistory?address=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&count=20&filterCdd=2000-&sortTxTimestamp=down&timestamp=1635513688254&secretKey=d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09))=ded5aed4d84fab123943cef117ecbeeb5338212caa44647e0f51805282632ec4
    
    - signedRequest:
    
    https://www.sign.cash/api/ratingHistory?address=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&count=20&filterCdd=2000-&sortTxTimestamp=down&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=ded5aed4d84fab123943cef117ecbeeb5338212caa44647e0f51805282632ec4
    

    POST

    - URL:https://www.sign.cash/api/ratingHistory
    
    - unsignedRequest:
    
    {"address":"FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX","count":20,"filterCdd":"2000-","sortTxTimestamp":"down","timestamp":"1635513688254","url":"https://www.sign.cash/api/ratingHistory"}
    
    - sign = sha256(sha256({"address":"FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX","count":20,"filterCdd":"2000-","sortTxTimestamp":"down","timestamp":"1635513688254","url":"https://www.sign.cash/api/ratingHistory","secretKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))=87f755ad8ae221a47e7ad93f9780a7f2ab777c2e77dd6516c2b264a69ed2119a
    
    - signedRequest:
    
    {"address":"FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX","count":20,"filterCdd":"2000-","sortTxTimestamp":"down","timestamp":"1635513688254","url":"https://www.sign.cash/api/ratingHistory","requester":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","sign":"87f755ad8ae221a47e7ad93f9780a7f2ab777c2e77dd6516c2b264a69ed2119a"}
    

    响应参数

    name type description
    address string FCH address
    ratingList object All "FEIP3_CID" operation records of this address or cid.See below
    height uint The latest block height when getting the data.
    • ratingList
    name type description
    block uint The height of the block where the transaction is written
    cdd uint64 Destroyed coindays in the rating transaction
    ratedAddress string Address of the ratedAddress
    ratingSign string The sign of the rating, "+" or "-".
    txid string The txid of this transaction
    txTimestamp timestamp The timestamp of this transaction
    • 示例
    
    {
    	"address": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
    	"ratingList": [{
    			"block": 963002,
    			"cdd": 2834,
    			"ratedAddress": "FNEjybqhAjFfAibCX5oLLB4MmV1Pvfdt9D",
    			"ratingSign": "+",
    			"txid": "dc339b7aed07d0e04905ad5c647c936da8b7bbc9b89d0aface18970fdd5fe153",
    			"txTimestamp": 1635513688254
    		},
    		{
    			"block": 9628342,
    			"cdd": 3400,
    			"ratedAddress": "FRc5NXWeUCAJxnCkJwZ8fyUiWTeXWykk33",
    			"ratingSign": "-",
    			"txid": "4d58e21511145cbb949d8b499398dae12287164a35af24cdbbff203390600d61",
    			"txTimestamp": 1635512348343
    		},
    		{
    			"block": 928330,
    			"cdd": 53100,
    			"ratedAddress": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    			"ratingSign": "+",
    			"txid": "616e80f09ca67974fd1c79919a451ced8a9f3d24c83437aa439b8f259be16ead",
    			"txTimestamp": 1634503342324
    		}
    	],
    	"height": 963667
    }
    
    排序、压缩、签名后:
    
    {"address":"FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX","height":963667,"ratingList":[{"block":963002,"cdd":2834,"ratedAddress":"FNEjybqhAjFfAibCX5oLLB4MmV1Pvfdt9D","ratingSign":"+","txTimestamp":"1635513688254","txid":"dc339b7aed07d0e04905ad5c647c936da8b7bbc9b89d0aface18970fdd5fe153"},{"block":9628342,"cdd":3400,"ratedAddress":"FRc5NXWeUCAJxnCkJwZ8fyUiWTeXWykk33","ratingSign":"-","txTimestamp":"1635512348343","txid":"4d58e21511145cbb949d8b499398dae12287164a35af24cdbbff203390600d61"},{"block":928330,"cdd":53100,"ratedAddress":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","ratingSign":"+","txTimestamp":"1634503342324","txid":"616e80f09ca67974fd1c79919a451ced8a9f3d24c83437aa439b8f259be16ead"}],"sign":"00000000000000000000011111111111111111111111"}
    
    

    返回值

    返回值 类型 必填 说明
    code uint Y 返回码
    msg string Y 返回信息
    data object N 相关数据
    • 返回信息详情
    code msg 说明 data字段
    0 OK 请求成功
    1 Unknown error. 未知错误 signedRequest
    2000 The address has not been used. 地址从未被使用 address
    4000 No matching record. 没有符合条件的信息。 signedRequest
    • 示例
    {
        "code":4000,
        "msg":"No matching record.",
        "data":{
            "signedRequest":"https://www.sign.cash/api/ratingHistory?address=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&filterCdd=2000&count=20&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=ded5aed4d84fab123943cef117ecbeeb5338212caa44647e0f51805282632ec4"
        }
    

Log in to reply