Group Details Private

administrators

  • APIP15V1_ProofOnChain(zh-CN)
    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》

    关于本协议

    1. 本协议接口提供链上公开发布的声明信息。

    2. 本协议接口的数据来源和相关规则遵循以下协议:

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

    4. 示例数据:
      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. 响应”。

    posted in Protocol/协议
  • APIP14V1_DeclarationOnChain(zh-CN)
    APIP14V1_DeclarationOnChain(zh-CN)
    Version:1
    Language:zh-CN
    Author:C_armX
    Status:draft
    Create:2022-05-06
    Update:2022-05-06
    PID:""
    TXID:
    

    APIP14V1_DeclarationOnChain(zh-CN)


    目录

    关于APIP

    关于本协议

    getDeclarationList


    Type:APIP
    SerialNumber:14
    ProtocolName:DeclarationOnChain
    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》

    关于本协议

    1. 本协议接口提供链上公开发布的声明信息。

    2. 本协议接口的数据来源和相关规则遵循以下协议:

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

    4. 示例数据:
      requester:FEk41Kqjar45fLDriztUDTUkdki7mmcjWK

    requester的公钥pubKey:030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a

    requester的私钥priKey:L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8

    requester获得的对称密钥symKey:d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09

    服务方链上发布的urlMainPart: https://www.sign.cash/api/

    接口url:https://www.sign.cash/api/APIP14/v1/[接口名称]

    getDeclarationList

    获取链上链上声明信息。

    url

    [服务方发布的urlMainPart]APIP14/v1/getDeclarationList

    示例:

    https://www.sign.cash/api/APIP14/v1/getDeclarationList

    请求参数

    通用请求参数参见通用请求参数。其中:

    • query

    响应参数data.list中各字段均可作为查询字段。

    • sort

    响应参数data.list中的数字类型字段均可作为排序字段。

    • 示例

    查询FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX在链上发布的声明,按交易时间戳倒序,获取从第1条到第20条。

    {
    	"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    	"timestamp": 1635513688254,
    	"url": "https://www.sign.cash/api/APIP14/v1/getDeclarationList",
    	"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 FEIP8
    address string The address of the first input of the transaction.
    title string The title of declaration data.title
    content string The content of declaration data.content
    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
    • 示例

    响应查询FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX当前有效的链上HAT信息,按交易时间戳倒序,获取第1批20条。

    {
    	"code": 0,
    	"message": "Success.",
    	"data": {
    		"list": [{
    				"address": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
    				"title": "House for sell",
    				"content": "Sale of a property in the heart of New York City with an area of 500 square meters and a total price of 50 million US dollars.",
    				"txid": 1636526891228,
    				"txTimestamp": 230000,
    				"blockHeight": 1003034
    			},
    			{
    				"address": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
    				"title": "Exit the fiat circle",
    				"content": "Crypto is the future of the world, I announce to quit the fiat circle and embrace the crypto world.",
    				"txid": 1636526700000,
    				"txTimestamp": 220000,
    				"blockHeight": 1003000
    			}
    		],
    		"total": 2,
    		"bestHeight": 963667
    	},
    	"sign": ""
    }
    
    • 响应状态

    参见《APIP1_OpenAPI》的“数据请求接口”的“5. 响应”。


    posted in Protocol/协议
  • RE: FCH生态事件--汇总

    2022年3月
    3月2日,发布《Freecash生态建设进展》总结了Freecash生态目前已经取得的进展,正在进行的工作,以及将要展开的任务。https://bbs.cash/topic/628/
    3月6日,升级《FIPA3V2_InfluenceIndex(en-US)》基于链上币天和评价数据定义一个身份的综合影响力指数。 新版取消了指数中的非链上数据“贡献”,以使指数更加开放。https://bbs.cash/topic/629/
    3月6日,线上会议部署Open API系统的开发工作,该系统实现11个APIP协议的49个API,为利用FCH链上数据组织商业活动的各种应用提供链上数据服务。开发完成后,方案和代码将开放提供给任何人采用和部署。参会者:speak_wmmw、C_armX、master_wang、caic_f5f5、F7rspPvuPhrc6xYYXjBoCieKAWSz9ShSNp。
    3月7日,发布《APIP11V1_HatOnChain(zh-CN)》定义去中心化文件管理的链上哈希属性表信息接口。https://bbs.cash/topic/631/
    3月15日,隐私备份机项目开发方案已完成,进入“启动T0样机pcb和软件的开发”阶段。
    3月18日,发布《APIP12V1_MailOnChain(zh-CN)》定义链上密信接口(https://bbs.cash/topic/634/ );发布《APIP13V1_SafeOnChain(zh-CN)》定义链上保险柜信息接口(https://bbs.cash/topic/635/ );更新《APIP8V1_ContactsOnChain(zh-CN)定义链上联系人信息接口。(https://bbs.cash/topic/619/)
    3月27日,线上会议讨论OpenAPI接口部分开发细节。参会者:speak_wmmw、C_armX、master_wang、F7rspPvuPhrc6xYYXjBoCieKAWSz9ShSNp。
    3月31日,更新《APIP1V1_OpenAPI(zh-CN)》协议,根据API开发中遇到的问题,全面调整协议文本和签名逻辑。

    2022年4月
    4月1日,更新《FEIP29V2_Service(en-US)》,1)pubKey改为pubKeyAdmin。2)增加prot字段,给出服务所遵循的协议列表。3) 增加params字段,用于定义服务特有的参数。https://bbs.cash/topic/609/
    4月16日,线上会议讨论APIP1和APIP2接口部分开发细节。参会者:speak_wmmw、C_armX、master_wang、F7rspPvuPhrc6xYYXjBoCieKAWSz9ShSNp。
    4月18日,更新《APIP1V1_OpenAPI(zh-CN)》,查询语法改为ES Query DSL。https://bbs.cash/topic/608/apip1v1_openapi-zh-cn
    4月20日,更新《APIP2V1_BasicInfoOnChain(zh-CN)》适用新的查询语法,抽离业务层。https://bbs.cash/topic/608/apip1v1_openapi-zh-cn
    4月22日,更新《FEIP7V4_MailOnChain》《FEIP12V3_Contacts》《FEIP17V3_Safe》,增加recover操作,优化协议规则。https://bbs.cash/topic/568/
    4月23日,《APIP3V1_CIDInfo(zh-CN)》、《APIP4V1_Reputation(zh-CN)》、《APIP7V1_APP(zh-CN)》、《APIP8V1_ContactsOnChain(zh-CN)》、《APIP12V1_MailOnChain(zh-CN)》、《APIP13V1_SafeOnChain(zh-CN)》,这些协议采用新的APIP1规则,并在飞签2.0中启用。https://bbs.cash/topic/568/

    2022年5月
    5月2日,更新《APIP9V1_Group(zh-CN)》、
    《APIP10V1_Organization(zh-CN)》、《APIP11V1_HatOnChain(zh-CN)》,将用于去中心化社交应用和云盘应用。https://bbs.cash/topic/568/
    5月6日,发布协议 《APIP14V1_DeclarationOnChain(zh-CN)》
    提供链上声明信息发布接口,用于保障个人基本的信息发布渠道。https://bbs.cash/topic/637/

    5月6日,发布协议 《APIP15V1_ProofOnChain(zh-CN)》
    提供链上通用证明数据接口,用于确认个人之间的经济关系。https://bbs.cash/topic/638/
    5月17日,线下会议讨论开放API数据库开发,隐私备份机与飞签产品运营,海外生态发展等。参会者C_armX、speak_wmmw、sirius_8zqD、FGBYivqzm2u8Kop6cNNfzpPUew6e4Sq7ab、HHQ_fR8N、Makaba_3mZZ。

    posted in History/历史
  • APIP100V1_RawTxBroadcast(zh-CN)
    APIP100: RawTxBroadcast
    Version: 1
    Language: zh-CN
    Author: C_armX
    Status: draft
    Created date: 2022-04-19
    Updata:2022-04-19
    PID: ""
    TXid: 
    

    APIP100V1_RawTxBroadcast(zh-CN)


    目录

    关于APIP

    关于本协议

    rawTxBroadcast


    Type: APIP
    SerialNumber: 2
    ProtocolName: BasicInfoOnChain
    Version: 1
    Description : Freecash主链基础信息API规范.
    Author: C_armX, Write_cash, Free_cash, F7rspPvuPhrc6xYYXjBoCieKAWSz9ShSNp
    Language: zh-CN
    PrePID:""
    

    关于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》

    关于本协议

    rawTxBroadcast

    交易广播接口。在链上广播已经签名的原始交易。

    url

    [服务方发布的urlMainPart]apip2/v1/rawTxBroadcast

    示例

    https://www.sign.cash/api/apip2/v1/rawTxBroadcast

    请求参数

    name type description requested
    rawTx string Raw transaction Y
    • 示例

    广播一笔原始交易。

    请求参数:

    {
    	"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    	"timestamp": 1635513688254,
    	"url": "https://www.sign.cash/api/apip2/v1/balance",
    	"data": {
    		"rawTx": "0222222222222222222222222222"
    	},
    	"sign": "08a47ccb60c682366416e984f3d55f17014643abad512225c7856e5fae1cc933"
    }
    

    响应参数

    除通用响应状态和参数之外,交易广播后,服务方将Freecash节点的响应状态和参数,直接返回给请求方。

    posted in Protocol/协议
  • APIP13V1_SafeOnChain(zh-CN)
    APIP13:SafeOnChain
    Version:1
    Language:zh-CN
    Author:C_armX
    Status:draft
    Createddate:2021-12-01
    Update:2022-04-27
    PID:""
    Txid:
    

    APIP13V1_SafeOnChain(zh-CN)


    目录

    关于APIP

    关于本协议

    getValidSafeItems

    getDeletedSafeItems

    getSafeOpHistory


    Type:APIP
    SerialNumber:13
    ProtocolName:SafeOnChain
    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》

    关于本协议

    1. 本协议接口提供链上保险柜信息。

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

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

    4. 示例数据:

    requester:FEk41Kqjar45fLDriztUDTUkdki7mmcjWK

    requester的公钥pubKey:030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a

    requester的私钥priKey:L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8

    requester获得的对称密钥symKey:d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09

    服务方链上发布的urlMainPart: https://www.sign.cash/api/

    接口url:https://www.sign.cash/api/apip13/v1/[接口名称]


    getValidSafeItems

    获取链上当前有效的保险柜条目信息。

    url

    [服务方发布的urlMainPart]apip13/v1/getValidSafeItems

    示例

    https://www.sign.cash/api/apip13/v1/getValidSafeItems

    请求参数

    通用请求参数参见通用请求参数。其中:

    • query

    响应参数data.list中各字段均可作为查询字段。

    • sort

    响应参数data.list中的数字类型字段均可作为排序字段。

    • 示例

    查询FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX的链上保险柜信息,按交易时间戳倒序,获取第1批20条。

    {
    	"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    	"timestamp": 1635513688254,
    	"url": "https://www.sign.cash/api/apip13/v1/getValidSafeItems",
    	"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 FEIP12
    address string The address of the first input.
    alg string The encrypt algorithm data.alg
    ciphertext Safe item content encrypted with the public key of the host data.ciphertext
    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
    • 示例
    {
    	"code": 0,
    	"message": "Success.",
    	"data": {
    		"list": [{
    			"address": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
    			"alg": "ECC256k1-AES256CBC",
    			"ciphertext": "AjTU0rGQvDxhCs3F5x4Pcz3Bsiiry2LryPcKcPIZ2iDsD68U5he9FkM6AVUzEHTjmfBLkhfFu7rv4fveoyMi5YH+wQoiWDxgs/MYjGZBL/Fuq6XZ6IOCXfWyfwphE4uxhEg5TD9ZBRsrJbNxwbdfee5ev5Gvc8kwYROycs0sAG3rNdoJbEZZ7bs2DqvHbAWdG7w4gYLhP9o+C/xVTZHz7Ks9VHb6i04/1at40etlWXxPWSvkdDWxTtyWSSsY2jrbYjfe+ytXQRTRY4gYQdwg+9s=",
    			"txid": "11111111110000000000",
    			"txTimestamp": 1636180056756,
    			"blockHeight": 963220
    		}],
    		"total": 1,
    		"bestHeight": 963667
    	},
    	"sign": ""
    }
    
    • 响应状态

    参见《APIP1_OpenAPI》的“数据请求接口”的“5. 响应”。


    getDeletedSafeItems

    说明

    获取链上已经删除的保险柜信息。

    url

    [服务方发布的urlMainPart]apip13/v1/getDeletedSafeItems

    示例

    https://www.sign.cash/api/apip13/v1/getDeletedSafeItems

    请求参数

    通用请求参数参见通用请求参数。其中:

    • query

    响应参数data.list中各字段均可作为查询字段。

    • sort

    响应参数data.list中的数字类型字段均可作为排序字段。

    • 示例

    查询FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX链上已删除的保险柜信息,按交易时间戳倒序,获取第1批20条。

    {
    	"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    	"timestamp": 1635513688254,
    	"url": "https://www.sign.cash/api/apip13/v1/getDeletedSafeItems",
    	"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 FEIP12
    address string The address of the first input.
    alg string The encrypt algorithm data.alg
    ciphertext Safe item content encrypted with the public key of the host data.ciphertext
    addTxid string The txid of this transaction in which the safe item was added
    addTxTimestamp timestamp The timestamp of the transaction in which the safe item was added
    addBlockHeight uint The height of the block in which the safe item was added
    deleteTxid string The txid of this transaction in which the safe item was deleted
    deleteTxTimestamp timestamp The timestamp of the transaction in which the safe item was deleted
    deleteBlockHeight uint The height of the block in which the safe item was deleted
    • 示例
    {
    	"code": 0,
    	"message": "Success.",
    	"data": {
    		"list": [{
    			"address": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
    			"alg": "ECC256k1-AES256CBC",
    			"ciphertext": "AjTU0rGQvDxhCs3F5x4Pcz3Bsiiry2LryPcKcPIZ2iDsD68U5he9FkM6AVUzEHTjmfBLkhfFu7rv4fveoyMi5YH+wQoiWDxgs/MYjGZBL/Fuq6XZ6IOCXfWyfwphE4uxhEg5TD9ZBRsrJbNxwbdfee5ev5Gvc8kwYROycs0sAG3rNdoJbEZZ7bs2DqvHbAWdG7w4gYLhP9o+C/xVTZHz7Ks9VHb6i04/1at40etlWXxPWSvkdDWxTtyWSSsY2jrbYjfe+ytXQRTRY4gYQdwg+9s=",
    			"addTxid": "11111111110000000000",
    			"addTxTimestamp": 1636180056756,
    			"addBlockHeight": 963220,
    			"deleteTxid": "22222111100111111111",
    			"deleteTxTimestamp": 1636180838232,
    			"deleteBlockHeight": 963333
    		}],
    		"total": 1,
    		"bestHeight": 963667
    	},
    	"sign": ""
    }
    
    • 响应状态

    参见《APIP1_OpenAPI》的“数据请求接口”的“5. 响应”。

    3.getSafeOpHistory

    查询保险柜链上操作历史信息。

    url

    [服务方发布的urlMainPart]apip13/v1/getSafeOpHistory

    示例

    https://www.sign.cash/api/apip13/v1/getSafeOpHistory

    请求参数

    通用请求参数参见通用请求参数。其中:

    • query

    响应参数data.list中各字段均可作为查询字段。

    • sort

    响应参数data.list中的数字类型字段均可作为排序字段。

    • 示例

    查询FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX链上保险柜操作历史信息,按交易时间戳正序,获取第1批20条。

    {
    	"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    	"timestamp": 1635513688254,
    	"url": "https://www.sign.cash/api/apip13/v1/getSafeOpHistory",
    	"query": {
    		"term": {
    			"address": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX"
    		}
    	},
    	"sort": [{
    		"txTimestamp": {
    			"order": "asc"
    		}
    	}],
    	"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 FEIP12
    address string The address of the first input.
    op string The operation data.op
    alg string The encrypt algorithm data.alg
    ciphertext Safe item content encrypted with the public key of the host data.ciphertext
    addTxid string The txid of this transaction in which the item was added data.addTxid
    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
    • 示例
    {
    	"code": 0,
    	"message": "Success.",
    	"data": {
    		"list": [{
    				"address": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
    				"op": "add",
    				"alg": "ECC256k1-AES256CBC",
    				"ciphertext": "AjTU0rGQvDxhCs3F5x4Pcz3Bsiiry2LryPcKcPIZ2iDsD68U5he9FkM6AVUzEHTjmfBLkhfFu7rv4fveoyMi5YH+wQoiWDxgs/MYjGZBL/Fuq6XZ6IOCXfWyfwphE4uxhEg5TD9ZBRsrJbNxwbdfee5ev5Gvc8kwYROycs0sAG3rNdoJbEZZ7bs2DqvHbAWdG7w4gYLhP9o+C/xVTZHz7Ks9VHb6i04/1at40etlWXxPWSvkdDWxTtyWSSsY2jrbYjfe+ytXQRTRY4gYQdwg+9s=",
    				"txid": "11111111110000000000",
    				"txTimestamp": 1636180000111,
    				"blockHeight": 963220
    			},
    			{
    				"address": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
    				"op": "delete",
    				"addTxid": "11111111110000000000",
    				"txid": "33333333333333333333333333333333",
    				"txTimestamp": 1636180000222,
    				"blockHeight": 963201
    			}
    		],
    		"total": 2,
    		"bestHeight": 963667
    	},
    	"sign": ""
    }
    
    posted in Protocol/协议
  • APIP12V1_MailOnChain(zh-CN)
    APIP12:MailOnChain
    Version:1
    Language:zh-CN
    Author:C_armX
    Status:draft
    Createddate:2021-12-01
    Update:2022-04-27
    PID:""
    Txid:
    

    APIP12V1_MailOnChain(zh-CN)


    目录

    关于APIP

    关于本协议

    getValidMails

    getDeletedMails

    getMailOpHistory


    Type:APIP
    SerialNumber:12
    ProtocolName:MailOnChain
    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》


    关于本协议

    1. 本协议接口提供链上密信信息。

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

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

    4. 示例数据:

    requester:FEk41Kqjar45fLDriztUDTUkdki7mmcjWK

    requester的公钥pubKey:030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a

    requester的私钥priKey:L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8

    requester获得的对称密钥symKey:d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09

    服务方链上发布的urlMainPart: https://www.sign.cash/api/

    接口url:https://www.sign.cash/api/apip12/v1/[接口名称]


    getValidMails

    根据筛选条件获取某地址在链上未删除的密信。

    url

    [服务方发布的urlMainPart]apip12/v1/getValidMails

    示例

    https://www.sign.cash/api/apip12/v1/getValidMails

    请求参数

    通用请求参数参见通用请求参数。其中:

    • query

    响应参数data.list中各字段均可作为查询字段。

    • sort

    响应参数data.list中的数字类型字段均可作为排序字段。

    • 示例

    查询FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX的当前有效的链上密信,按交易时间戳倒序,获取第1批20条。

    {
    	"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    	"timestamp": 1635513688254,
    	"url": "https://www.sign.cash/api/apip12/v1/getValidMails",
    	"query": {
    		"multi_match": {
    			"query": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    
    			"fields": ["sender", "recipient"]
    		}
    	},
    	"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 FEIP7
    sender string The address of the first input.
    recipient string The address of the first output.
    alg string The encrypt algorithm data.alg
    ciphertextSend string Mail encrypted with the public key of the sender data.ciphertextSend
    ciphertextReci string Mail encrypted with the public key of the recipient data.ciphertextReci
    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
    • 示例

    响应FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX的当前有效的链上密信,按交易时间戳倒序,获取第1批20条。

    {
    	"code": 0,
    	"message": "Success.",
    	"data": {
    		"list": [{
    			"sender": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    			"recipient": "F86zoAvNaQxEuYyvQssV5WxEzapNaiDtTW",
    			"alg": "ECC256k1-AES256CBC",
    			"ciphertextSend": "AjTU0rGQvDxhCs3F5x4Pcz3Bsiiry2LryPcKcPIZ2iDsD68U5he9FkM6AVUzEHTjmfBLkhfFu7rv4fveoyMi5YH+wQoiWDxgs/MYjGZBL/Fuq6XZ6IOCXfWyfwphE4uxhEg5TD9ZBRsrJbNxwbdfee5ev5Gvc8kwYROycs0sAG3rNdoJbEZZ7bs2DqvHbAWdG7w4gYLhP9o+C/xVTZHz7Ks9VHb6i04/1at40etlWXxPWSvkdDWxTtyWSSsY2jrbYjfe+ytXQRTRY4gYQdwg+9s=",
    			"ciphertextReci": "AhJkddIcpBMI4FwtDIG1N9JdMkUdcipfHeu9cqsOyepLnET5YersPMHcd4gbZOvBMr60zCii5fWjx7Vv07HaS6KJszeiMtcfTlj/laDdJ+TqK6DWKJ4A1Rpax4WrI2TFbAGoc8rarHOTql2u3wADAdNq+11ALc/kY65alrVfjtKM7KVKBLp3xZgy00YKV9pSo22TLC0+FnWDlUv70ZoAzROKw/z8+BIKz+QipPAwAa7KBgZhlSjryZU6Ad4bydefP11JFh1MS6lkfov0V+LKVCI=",
    			"txid": "11111111110000000000",
    			"txTimestamp": 1636180056756,
    			"blockHeight": 963220
    		}],
    		"total": 1,
    		"bestHeight": 963667
    	},
    	"sign": ""
    }
    
    • 响应状态

    参见《APIP1_OpenAPI》的“数据请求接口”的“5. 响应”。


    getDeletedMails

    获取链上已经删除的密信。

    url

    [服务方发布的urlMainPart]apip12/v1/getDeletedMails

    示例

    https://www.sign.cash/api/apip12/v1/getDeletedMails

    请求参数

    通用请求参数参见通用请求参数。其中:

    • query

    响应参数data.list中各字段均可作为查询字段。

    • sort

    响应参数data.list中的数字类型字段均可作为排序字段。

    • 示例

    查询FEk41Kqjar45fLDriztUDTUkdki7mmcjWK链上已删除的密信,按交易时间戳倒序,获取第1批20条。

    {
    	"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    	"timestamp": 1635513688254,
    	"url": "https://www.sign.cash/api/apip12/v1/getDeletedMails",
    	"query": {
    		"multi_match": {
    			"query": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    
    			"fields": ["sender", "recipient"]
    		}
    	},
    	"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 FEIP12
    sender string The address of the first input.
    recipient string The address of the first output.
    alg string The encrypt algorithm data.alg
    ciphertextSend string Mail encrypted with the public key of the sender data.ciphertextSend
    ciphertextReci string Mail encrypted with the public key of the recipient data.ciphertextReci
    sendTxid string The txid of this transaction in which the mail was sent
    sendTxTimestamp timestamp The timestamp of the transaction in which the mail was sent
    sendBlockHeight uint The height of the block in which the mail was sent
    deleteTxid string The txid of this transaction in which the mail was deleted
    deleteTxTimestamp timestamp The timestamp of the transaction in which the mail was deleted
    deleteBlockHeight uint The height of the block in which the mail was deleted
    • 示例

    响应FEk41Kqjar45fLDriztUDTUkdki7mmcjWK链上已删除的密信,按交易时间戳倒序,获取第1批20条。

    {
    	"code": 0,
    	"message": "Success.",
    	"data": {
    		"list": [{
    			"sender": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    			"recipient": "F86zoAvNaQxEuYyvQssV5WxEzapNaiDtTW",
    			"alg": "ECC256k1-AES256CBC",
    			"ciphertextSend": "AjTU0rGQvDxhCs3F5x4Pcz3Bsiiry2LryPcKcPIZ2iDsD68U5he9FkM6AVUzEHTjmfBLkhfFu7rv4fveoyMi5YH+wQoiWDxgs/MYjGZBL/Fuq6XZ6IOCXfWyfwphE4uxhEg5TD9ZBRsrJbNxwbdfee5ev5Gvc8kwYROycs0sAG3rNdoJbEZZ7bs2DqvHbAWdG7w4gYLhP9o+C/xVTZHz7Ks9VHb6i04/1at40etlWXxPWSvkdDWxTtyWSSsY2jrbYjfe+ytXQRTRY4gYQdwg+9s=",
    			"ciphertextReci": "AhJkddIcpBMI4FwtDIG1N9JdMkUdcipfHeu9cqsOyepLnET5YersPMHcd4gbZOvBMr60zCii5fWjx7Vv07HaS6KJszeiMtcfTlj/laDdJ+TqK6DWKJ4A1Rpax4WrI2TFbAGoc8rarHOTql2u3wADAdNq+11ALc/kY65alrVfjtKM7KVKBLp3xZgy00YKV9pSo22TLC0+FnWDlUv70ZoAzROKw/z8+BIKz+QipPAwAa7KBgZhlSjryZU6Ad4bydefP11JFh1MS6lkfov0V+LKVCI=",
    			"sendTxid": "11111111110000000000",
    			"sendTxTimestamp": 1636180056756,
    			"sendBlockHeight": 963220,
    			"deleteTxid": "22222111100111111111",
    			"deleteTxTimestamp": 1636180838232,
    			"deleteBlockHeight": 963333
    		}],
    		"total": 1,
    		"bestHeight": 963667
    	},
    	"sign": ""
    }
    
    • 响应状态

    参见《APIP1_OpenAPI》的“数据请求接口”的“5. 响应”。


    getMailOpHistory

    获取链上加密邮件的操作历史信息。

    url

    [服务方发布的urlMainPart]apip12/v1/getMailOpHistory

    示例:

    https://www.sign.cash/api/apip12/v1/getMailOpHistory

    请求参数

    通用请求参数参见通用请求参数。其中:

    • query

    响应参数data.list中各字段均可作为查询字段。

    • sort

    响应参数data.list中的数字类型字段均可作为排序字段。

    • 示例

    查询FEk41Kqjar45fLDriztUDTUkdki7mmcjWK的链上加密邮件操作信息,按交易时间戳正序,获取第1批20条。

    {
    	"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    	"timestamp": 1635513688254,
    	"url": "https://www.sign.cash/api/apip12/v1/getMailOpHistory",
    	"query": {
    		"multi_match": {
    			"query": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    
    			"fields": ["sender", "recipient"]
    		}
    	},
    	"sort": [{
    		"txTimestamp": {
    			"order": "asc"
    		}
    	}],
    	"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 FEIP12
    sender string The address of the first input.
    recipient string The address of the first output.
    op string The operation data.op
    alg string The encrypt algorithm data.alg
    ciphertextSend string Mail encrypted with the public key of the sender data.ciphertextSend
    ciphertextReci string Mail encrypted with the public key of the recipient data.ciphertextReci
    sendTxid string The txid of this transaction in which the mail was sent data.sendTxid
    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
    • 示例

    响应FEk41Kqjar45fLDriztUDTUkdki7mmcjWK的链上加密邮件操作信息,按交易时间戳正序,获取第1批20条。

    {
    	"code": 0,
    	"message": "Success.",
    	"data": {
    		"list": [{
    
    				"op": "send",
    				"sender": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    				"recipient": "F86zoAvNaQxEuYyvQssV5WxEzapNaiDtTW",
    				"alg": "ECC256k1-AES256CBC",
    				"ciphertextSend": "AjTU0rGQvDxhCs3F5x4Pcz3Bsiiry2LryPcKcPIZ2iDsD68U5he9FkM6AVUzEHTjmfBLkhfFu7rv4fveoyMi5YH+wQoiWDxgs/MYjGZBL/Fuq6XZ6IOCXfWyfwphE4uxhEg5TD9ZBRsrJbNxwbdfee5ev5Gvc8kwYROycs0sAG3rNdoJbEZZ7bs2DqvHbAWdG7w4gYLhP9o+C/xVTZHz7Ks9VHb6i04/1at40etlWXxPWSvkdDWxTtyWSSsY2jrbYjfe+ytXQRTRY4gYQdwg+9s=",
    				"ciphertextReci": "AhJkddIcpBMI4FwtDIG1N9JdMkUdcipfHeu9cqsOyepLnET5YersPMHcd4gbZOvBMr60zCii5fWjx7Vv07HaS6KJszeiMtcfTlj/laDdJ+TqK6DWKJ4A1Rpax4WrI2TFbAGoc8rarHOTql2u3wADAdNq+11ALc/kY65alrVfjtKM7KVKBLp3xZgy00YKV9pSo22TLC0+FnWDlUv70ZoAzROKw/z8+BIKz+QipPAwAa7KBgZhlSjryZU6Ad4bydefP11JFh1MS6lkfov0V+LKVCI=",
    				"txid": "21111111111111111111111111111111",
    				"txTimestamp": 1636180000111,
    				"blockHeight": 963200
    			},
    			{
    				"sender": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    				"op": "delete",
    				"sendTxid": "21111111111111111111111111111111",
    				"txid": "33333333333333333333333333333333",
    				"txTimestamp": 1636180000222,
    				"blockHeight": 963201
    			}
    		],
    		"total": 2,
    		"bestHeight": 963667
    	},
    	"sign": ""
    }
    
    • 响应状态

    参见《APIP1_OpenAPI》的“数据请求接口”的“5. 响应”。

    posted in Protocol/协议
  • APIP20V1_Avatar(zh-CN)
    APIP20V1_Avatar(zh-CN)
    Version:1
    Language:zh-CN
    Author:C_armX
    Status:draft
    Createddate:2022-03-07
    Createddate:2022-03-07
    Filehash:""
    TXid:
    

    APIP20V1_Avatar(zh-CN)


    目录

    关于APIP

    本协议的基本共识

    接口名称

    接口说明

    请求参数

    响应参数

    返回值


    Type:APIP
    SerialNumber:11
    ProtocolName:HATOnChain
    Version:1
    Description:定义头像获取通用接口。
    Author:C_armX
    Language:zh-CN
    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服务,成功后获得对称密钥symKey用于数据请求和验证。

      • 准备参数:准备请求参数,注意,采用POST方法时,需包括该API的url

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

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

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

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

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

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

    本协议的基本共识

    1. 本协议定义提供头像服务的接口通用格式。

    2. 头像的具体形成和分配方式由服务方自行设计。

    3. 示例数据:

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

    接口名称

    avatar

    接口说明

    批量获取fch地址对应的头像。

    请求参数

    name type description
    addressList string array The List of FCH addresses
    timestamp timestamp 请求的时间戳,精确到毫秒
    url string 请求的url,仅在post方法时出现
    sign string 用symKey对请求经两次sha256计算得到的签名,参见“构造请求示例”

    响应参数

    方案一:二进制文件,按大端序fch地址+图像大小+图像文件存放所有头像,在文件末尾加入symKey两次sha256哈希得到签名sign值,去除symKey,加入sign值,响应给请求者。
    方案二: 每个头像独立文件,文件名为fch地址。每个文件分别用symKey签名。

    返回值

    返回值 类型 必填 说明
    code uint Y 返回码
    msg string Y 返回信息
    data object N 相关数据
    • 返回信息详情
    code msg 说明 data字段
    0 OK 请求成功
    1 Other error. 其他错误 signedRequest, errorMessage

    构造请求示例

    请求内容:获取FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX的头像。

    参数

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

    GET:

    - unsignedRequest:
    
    https://www.sign.cash/api/cidInfo?addressList=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&timestamp=1635513688254
    
    - sign = sha256(sha256(https://www.sign.cash/api/cidInfo?addressList=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&timestamp=1635513688254&symKey=d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09))=33333333333335555555555522222222211111111111111111111111111111
    
    - signedRequest:
    
    https://www.sign.cash/api/cidInfo?addressList=FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=33333333333335555555555522222222211111111111111111111111111111
    

    POST:

    - URL:https://www.sign.cash/api/cidInfo
    
    - unsignedRequest:
    
    {"addressList":["FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX"],"timestamp":1635513688254,"url":"https://www.sign.cash/api/cidInfo"}
    
    - sign = sha256(sha256({"addressList":["FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX"],"timestamp":1635513688254,"url":"https://www.sign.cash/api/cidInfo","symKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))=555555555555555555555555522222222211111111111111111111111111111
    
    - signedRequest:
    
    {"addressList":["FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX"],"timestamp":1635513688254,"url":"https://www.sign.cash/api/cidInfo","requester":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","sign":"555555555555555555555555522222222211111111111111111111111111111"}
    
    posted in Protocol/协议
  • APIP11V1_HatOnChain(zh-CN)
    APIP11V1_HatOnChain(zh-CN)
    Version:1
    Language:zh-CN
    Author:C_armX
    Status:draft
    

    APIP11V1_HatOnChain(zh-CN)
    Version:1
    Language:zh-CN
    Author:C_armX
    Status:draft
    Create:2022-03-07
    Update:2022-05-01
    PID:""
    TXID:

    
    # APIP11V1_HatOnChain(zh-CN)
    ---
    ## 目录
    
    [关于APIP](#关于APIP)
    
    [关于本协议](#关于本协议)
    
    [getHatList](#getHatList)
    
    
    ---
    
    

    Type:APIP
    SerialNumber:11
    ProtocolName:HatOnChain
    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》`
    
    ## 关于本协议
    
    1. 本协议接口提供用于文件管理的哈希属性表(HAT)文件的链上信息。
    
    2. 本协议接口的数据来源和相关规则遵循以下协议:
    
       - 《FEIP32_HAT》
    
    3. 本协议接口数据采用JSON格式。
    
    4. 示例数据:
    `requester`:FEk41Kqjar45fLDriztUDTUkdki7mmcjWK
    
    requester的公钥`pubKey`:030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a
    
    requester的私钥`priKey`:L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8
    
    requester获得的对称密钥`symKey`:d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09
    
    服务方链上发布的`urlMainPart`: https://www.sign.cash/api/
    
    接口url:https://www.sign.cash/api/apip11/v1/[接口名称]
    
    ## getHatList
    
    获取链上当前有效的HAT信息。
    
    ### url
    
    [服务方发布的urlMainPart]apip11/v1/getHatList
    
    示例:
    
    https://www.sign.cash/api/apip11/v1/getHatList
    
    
    ### 请求参数
    
    通用请求参数参见[通用请求参数](#通用请求参数)。其中:
    
    * query
    
    响应参数`data.list`中各字段均可作为查询字段。
    
    * sort
    
    响应参数`data.list`中的数字类型字段均可作为排序字段。
    
    * 示例
    
    查询FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX当前有效的链上HAT信息,按交易时间戳倒序,获取第1批20条。
    
    

    {
    "requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    "timestamp": 1635513688254,
    "url": "https://www.sign.cash/api/apip11/v1/getHatList",
    "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 FEIP28|
    |:---|:---|:---|:---|
    |address|string|fch地址,本HAT文件所有者||
    |active|bool|标记同一srcFid的系列最新的条目(含所有分片)为1,其他为0||
    |fid|string|本HAT文件的双sha256值|data.fid|
    |srcFid|string|源HAT文件哈希,双Sha256,本文件为源版时等于fid|data.srcFid|
    |preVerFid|string|前版哈希,双Sha256,本文件为源版时为空|data.preVerFid|
    |firstPartFid|string|首哈希,双sha256,无分片为空|data.firstPartFid|
    |prePartFid|string|前片哈希,双sha256,无分片为空|data.prePartFid|
    |algo|string|加密算法,空为未加密,建议"ECC256k1-AES256CBC"|data.algo|
    |pubKey|string|加密公钥,空为上链签名者公钥|data.pubKey|
    |symKeyEncrypted|string|加密后的对称密钥|data.symKeyEncrypted|
    |loca|string array|存放位置,url|data.loca|
    |aid|string|上链HAT文件归属的应用的aid,aid of the app|data.aid|
    |pid|string|上链HAT文件归属的协议的pid,pid of the protocol|data.pid|
    |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|
    
    * 示例
    
    响应查询FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX当前有效的链上HAT信息,按交易时间戳倒序,获取第1批20条。
    
    

    {
    "code": 0,
    "message": "Success.",
    "data": {
    "list": [{
    "address": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
    "active": 1,
    "fid": "1111111111111122222222222222",
    "srcFid": "0000000011222222222222222222222",
    "preVerFid": "0000000011222222222222222222222",
    "firstPartFid": "",
    "prePartFid": "",
    "algo": "",
    "pubKey": "0222222222222222222222222",
    "symKeyEncrypted": "",
    "loca": "http://www.cid.cash/file/02dssssssssssssssss,
    "aid": "2k32k323kkkkkkkkkkkkkkkkkkkkkkkk",
    "pid": "33333333333888888888888888888889",
    "txid": 1636526891228,
    "txTimestamp": 230000,
    "blockHeight": 1003034
    }],
    "total": 1,
    "bestHeight": 963667
    },
    "sign": ""
    }

    * 响应状态
    
    参见`《APIP1_OpenAPI》`的“数据请求接口”的“5. 响应”。
    
    ---
    
    Create:2022-03-07
    Update:2021-05-01
    PID:""
    TXID:
    

    APIP11V1_HatOnChain(zh-CN)


    目录

    关于APIP

    关于本协议

    getHatList


    Type:APIP
    SerialNumber:11
    ProtocolName:HatOnChain
    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》

    关于本协议

    1. 本协议接口提供用于文件管理的哈希属性表(HAT)文件的链上信息。

    2. 本协议接口的数据来源和相关规则遵循以下协议:

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

    4. 示例数据:
      requester:FEk41Kqjar45fLDriztUDTUkdki7mmcjWK

    requester的公钥pubKey:030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a

    requester的私钥priKey:L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8

    requester获得的对称密钥symKey:d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09

    服务方链上发布的urlMainPart: https://www.sign.cash/api/

    接口url:https://www.sign.cash/api/apip11/v1/[接口名称]

    getHatList

    获取链上当前有效的HAT信息。

    url

    [服务方发布的urlMainPart]apip11/v1/getHatList

    示例:

    https://www.sign.cash/api/apip11/v1/getHatList

    请求参数

    通用请求参数参见通用请求参数。其中:

    • query

    响应参数data.list中各字段均可作为查询字段。

    • sort

    响应参数data.list中的数字类型字段均可作为排序字段。

    • 示例

    查询FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX当前有效的链上HAT信息,按交易时间戳倒序,获取第1批20条。

    {
    	"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    	"timestamp": 1635513688254,
    	"url": "https://www.sign.cash/api/apip11/v1/getHatList",
    	"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 FEIP28
    address string fch地址,本HAT文件所有者
    active bool 标记同一srcFid的系列最新的条目(含所有分片)为1,其他为0
    fid string 本HAT文件的双sha256值 data.fid
    srcFid string 源HAT文件哈希,双Sha256,本文件为源版时等于fid data.srcFid
    preVerFid string 前版哈希,双Sha256,本文件为源版时为空 data.preVerFid
    firstPartFid string 首哈希,双sha256,无分片为空 data.firstPartFid
    prePartFid string 前片哈希,双sha256,无分片为空 data.prePartFid
    algo string 加密算法,空为未加密,建议"ECC256k1-AES256CBC" data.algo
    pubKey string 加密公钥,空为上链签名者公钥 data.pubKey
    symKeyEncrypted string 加密后的对称密钥 data.symKeyEncrypted
    loca string array 存放位置,url data.loca
    aid string 上链HAT文件归属的应用的aid,aid of the app data.aid
    pid string 上链HAT文件归属的协议的pid,pid of the protocol data.pid
    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
    • 示例

    响应查询FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX当前有效的链上HAT信息,按交易时间戳倒序,获取第1批20条。

    {
    	"code": 0,
    	"message": "Success.",
    	"data": {
    		"list": [{
    			"address": "FMZsWGT5hEUqhnZhLhXrxNXXG6uDHcarmX",
    			"active": 1,
    			"fid": "1111111111111122222222222222",
    			"srcFid": "0000000011222222222222222222222",
    			"preVerFid": "0000000011222222222222222222222",
    			"firstPartFid": "",
    			"prePartFid": "",
    			"algo": "",
    			"pubKey": "0222222222222222222222222",
    			"symKeyEncrypted": "",
    			"loca": "http://www.cid.cash/file/02dssssssssssssssss,
    			"aid": "2k32k323kkkkkkkkkkkkkkkkkkkkkkkk",
    			"pid": "33333333333888888888888888888889",
    			"txid": 1636526891228,
    			"txTimestamp": 230000,
    			"blockHeight": 1003034
    		}],
    		"total": 1,
    		"bestHeight": 963667
    	},
    	"sign": ""
    }
    
    • 响应状态

    参见《APIP1_OpenAPI》的“数据请求接口”的“5. 响应”。


    posted in Protocol/协议
  • RE: 增加一个fch生态安全的板块吧

    @水雷_zzHe 内容不多,暂时不用。算力攻击相关的可以放到“挖矿”版块。

    posted in General Discussion/讨论区
  • FIPA3V2_InfluenceIndex(en-US)
    FIPA3: InfluenceIndex
    Version: 2
    Language: zh-CN
    Author: C_armX
    Status: draft
    Create: 2022-03-03
    Update:2022-05-07
    PId: ""
    TXID: 
    

    FIPA3V2_InfluenceIndex(zh-CN)

    Contents

    About FIPA

    About this protocol

    计算单位

    [参数构图](#参数构成)

    计算方法

    未来扩展

    Examples

    
    ProtocolType: FIPA
    SerialNumber: 3
    ProtocolName: InfluenceIndex
    VersionNumber: 2
    Description : Define the influence index of the identity calculated based on the coindays and evaluation of the identity on the chain. 基于链上币天和评价数据定义一个身份的综合影响力指数。
    Author: C_armX
    Language: zh-CN
    PreVersionPid:"32c3322189660804581c5647a799811d162eaa8106182d6e6c7d1739be4904fb"
    
    

    About FIPA

    FIPA protocols make improvements to the FCH ecosystem. These improvements will not lead to a hard fork of the main network, and will not write information on the blockchain.

    About this protocol

    1. 本协议基于链上币天和评价数据定义一个身份的综合影响力指数。
    2. 信任降低社会成本。人类之间的信任,可以大幅降低交易成本,提高经济效率。密码共识并未消灭信任,而是在更大范围内,建立更加可靠的信任。
    3. cid在链上留存的数据能够成为其影响力的基础依据。
    4. 币天(Coin Days,CD)能够体现经济价值和时间价值,具有不可人为篡改的基本特征,适合成为量化影响力的基础。

    计算单位

    1. 单位:影响力指数的单位为“点”,“point”。
    2. 基准:影响力指数计量以“万币天”为基准,10000币天=1点
    3. 币天:一笔utxo存在的时间,1FCH存在1天得到1币天。
    4. 币天销毁:花掉某笔utxo,即销毁了其已经存在的币天,销毁数量即其金额乘以销毁时已经存在的天数。如花掉一笔5天前产生的10FCH的utxo,则销毁的币天为10*5=50币天。

    参数构成

    1. **财富:**以“币天余额”和“币天销毁”作为衡量某CID在财富方面的影响力。自由共识生态衡量经济价值的基础量为FCH,但FCH可以随时转移,直接计量财富容易舞弊。因而采用币天进行衡量。其中“币天余额”反映CID当前持有的币天量,反映当前财富数量和持有时间;“币天销毁”反映该CID历史上销毁过的币天量,反映该CID曾经持有的财富数量和时间,反映对生态经济产生过的影响。
    2. 声誉:CID之间按照FEIP16声誉评价协议做的评价衡量CID的社会声誉。人们相互之间的主观评价是社会影响力体系的重要组成部分。FEIP16以币天销毁为基础的声誉评价即实现了主观评价,又实现了量化。

    计算方法

    1. 财富=币天余额0.7+币天销毁0.3。即:当前币天余额占7成权重,历史上销毁的币天总和占3成权重。如果cidA的币天余额为100万币天,历史上曾经销毁200万币天,则cidA的财富=1000.7+2000.3=130点。
    2. **声誉=**Σ(评价方向币天销毁)0.3。**如果cidA总共获得两个声誉评价,分别是1)积极评价,销毁100万币天,2)消极评价,销毁20万币天。0.3为声誉相对于财富的权重。则声誉=11000.3+(-1)200.3=24点。
    3. 影响力=财富+声誉=130+24=154点**。即**cidA的影响力为154点。

    未来扩展

    本协议是早期的尝试,更多扩展的影响力指数,或类似指数,以及计算模式可以自由设计,开放竞争,在市场中进化。

    Examples

    Alice于2020年2月1日获得一笔1万FCH的utxo,8月21日(200天)时,在不同情况下的影响力计算:

    1. 从未动用:财富=10000f*200days*0.7/10000=140点。总影响力140点。
    2. 100天时全部转给自己:财富=(10000*100*0.7+1*100*0.3)/10000 =100点。币天余额100万币天,币天销毁100万币天。总影响力100点
    3. 100天时全部转给Bob:Alice财富=10000*100*0.3/10000=30点。币天余额为0,币天销毁100万。如果Bob一直未花费,Bob财富=10000*100*0.7/10000=70点。总影响力100点
    4. 200天时全部转给Bob:Alice财富=10000*200*0.3/10000=60点。Bob财富=1*0*0.3/10000=0点。总影响力60点
    5. 200天时销毁全部币天给Bob好评:Alice财富=1*200*0.3/10000=60点。Bob声誉=10000*(1*200)*0.3/10000=60点。总影响力120点。(介于1与2两种情况之间,一方面减弱给本人其他CID互评的动机,一方面鼓励相互评价)。
    posted in Protocol/协议