Group Details Private

Global Moderators

Forum wide moderators

Member List

  • 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/协议
  • 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/协议
  • Freecash生态建设进展

    Freecash于2019年12月24日发布,2020年1月1日启动运行,已经安全运行2年多,所取得的成果已经远远超出启动时的预期,逐渐明确了构建密码经济基础设施的方向,底层逻辑快速演化成型,进入中间件和商业应用的开发阶段。

    1.生态建设的主要成果

    1.1.去中心化经济组织底层逻辑成熟

    Freecash的诞生是鉴于比特币和比特币现金的成功经验与教训,尝试为去中心化密码货币加入去中心化的治理机制,并做一些改进(参见《自由现金白皮书1.0(2019.7)》https://freecash.org/ )。在展开社区治理的过程中,逐渐意识到去中心化生态的治理必须有去中心化的组织,否则难以保证安全。

    在实现去中心化治理的过程中,我们看到了基于密码共识机制实现去中心化经济组织不但可行,而且更加安全、高效、自由,比特币的优势来自于此,并且可以为几乎所有互联网经济活动提供新的底层逻辑和创新动力。(参见:《密码经济宣言》(2020.4)http://freecash.cc/index.php?id=233 )

    因此,Freecash的定位从密码货币转向为去中心化经济组织提供基础设施,其生态设施也超出了Freecash本身,可以与其他去中心化系统相连,构成自由开放的社会经济共识系统,从而,自由现金(Freecash)升级为自由共识(FreeConsensus)。(参见:《自由共识:为密码经济奠基》(2020.3)(http://freecash.cc/index.php?id=166)

    底层逻辑的升级来自实践,也在实践中试验和进化,经过两年的探索,为去中心化经济组织构建基础设施的底层逻辑已经成熟,与近期DAO、NFT、元宇宙、DID等前沿方向完全一致,并且更加系统、简洁。(参见《自由共识基础设施构架》(2021.6)https://bbs.cash/topic/590/)

    1.2.去中心化经济组织的基础协议体系形成

    共识协议是去中心化经济的基石,Freecash生态的协议系统是最早构建,目前以基本成熟。

    自2020年至今,共编制38个生态共识协议,经过两年的试错演进,最终形成了由23个基础协议构成的自由共识协议体系,涵盖了去中心化的协议、身份、信誉、社交、组织、服务、存储等去中心化经济组织的主要构件。(参见《Freecash Protocol List》https://bbs.cash/topic/568/)

    1.3.底层逻辑在系列APP中得到验证

    Freecash的目标是服务于主流社会,构建更加开放的全球信息经济的基础设施。这与中本聪等早期密码朋克聚焦隐私货币、注重匿名和抗审查的无政府主义倾向有重大差异。比如,在最基本的身份功能上,比特币追求隐匿身份,而Freecash的首要任务是构建新的身份系统。

    因此,Freecash创建了新的基础协议体系,并为应用做了不同于主流dapp的新的底层逻辑。从2020年的密签、sign.cash、dplanet.io、freecash.vip,到2021年的飞签、密圈、cid.cash、write.cash等应用,逐步实现了新的底层逻辑,验证了自由共识方向的可行性。也是在这个过程中,基础协议体系快速进化成熟。

    1.4.底层逻辑和APP在社区治理中得到检验

    Freecash的升级需求来自社区治理需求,由此形成的底层逻辑、基础协议和APP也在社区治理中得到应用和验证。自2020年以来,Freecash社区贡献者们共进行了8次贡献评估,共463人次做出2398项贡献,经贡献者的相互评估,获得了最终的贡献奖励。

    作为社区治理的核心环节,首期贡献评估在主要通过微信完成,随着cid系统、dplanet.io、freecash.vip、密签、飞签、密圈等app逐渐成熟,2021年以来的贡献评估主要在Freecash内生系统中完成。(参见:https://dplanet.io/)

    1.5.API协议体系

    随着基础协议体系的成熟,APP开发的试验阶段基本完成,Freecash生态开始转向中间件和商业应用的开发。为了给商业应用提供统一、高效、去中心化的开发和运营环境,基于23个基础协议,编写了10个APIP协议,提供了46个统一的API,涵盖了去中心化的协议、身份、信誉、社交、组织、服务、存储。

    2.正在进行的主要工作

    2.1.API开发

    当前最重要的开发工作是实现10个APIP协议的46个API,并向生态开放。这是进一步展开各种应用开发的前提。(见下图)

    此项开发工作由生态三位资深开发者speak_wmmw、sirius_8zqD、master_wang承担,APIP协议的主要设计者和飞签APP开发者参与协助。开发正在进行,2022年上半年完成。

    2.2.SDK开发

    Freecash生态建设的目标是用密码共识机制重构互联网经济的基础设施,使信息经济更加安全、高效、自由。在API体系建立之后,互联网应用转用Freecash基础设施的主要障碍在于不熟悉密码技术和自由共识底层逻辑。这个环节本身并不复杂,只需要签名验证、加密解密和公钥地址3个基本开发工具。

    近期,已经委托专业团队开发Java、JavaScript、C++、Go四种语言的签名验证和加密解密SDK,其中Java、JavaScript的加密解密SDK已经完成。公钥产生fch、btc、eth、trx、bch、doge的公钥地址SDK由sirius_8zqD开发。

    2.3.飞签2.0

    飞签是在线身份和资产管理应用,是Freecash生态底层逻辑的主要试验场,1.0版本提供了cid身份管理、密码工具、freecash收支、链上信息管理等基础功能。

    随着基础协议的完善,飞签能够容纳更多Freecash生态的基础功能,在2.0版本中将增加第三方登录服务、链上密信、链上联系人、链上保险柜、utxo管理等新的功能,并将全面采用新的API系统,进一步实现去中心化。

    目前飞签2.0的UI已经设计完成,将与API开发同步展开安卓版APP开发。

    2.4.密签4.0

    密签是Freecash最早的APP,用于离线管理私钥、离线签名验证、加密解密,核心是私钥的安全保存和使用。到密签3.0版已经基本定型。

    目前正在开发4.0版本主要在fch作为身份的基础上,相同私钥增加btc、eth、bsc、trx、bch、doge等多链地址,为用户离线保存多链资产服务。该开发与公钥地址SDK同步进行。

    2.5.基础协议改进

    在API、SDK和APP的开发过程中,基础协议根据出现的问题和需求做进一步的微调和改进。

    2.6.加密备份硬件

    Freecash生态以私钥为安全核心,私钥就是一切,大幅简化由助记词、HD钱包、keystore等所增加的底层逻辑复杂性,但这需要一个安全便捷的私钥备份方式。这是一直以来,Freecash底层逻辑中缺失的并不复杂,但至关重要的一环。

    近期,隐私备份机项目已经酝酿成熟,采用离线扫描二维码打印在长效热敏纸上的办法,实现安全便捷的私钥备份,同时也可以备份助记词、账号密码、谷歌二次认证等重要信息。该项目已经由C_armX联合经验丰富的硬件团队组织实施。

    3.将要实施的主要任务

    3.1.API数据中心部署

    APIP协议开发实现后,在境内境外部署至少2个数据服务中心,以飞签2.0做服务试验调试,成熟后,为进一步的商业应用开发和运行提供服务。

    3.2.去中心化资产管理应用

    基于Freecash底层逻辑、基础协议、API服务和SDK,开发去中心化的多链资产管理应用,该应用具有去中心化的身份、信用、社交等基础模块,能够用单一身份管理fch、btc、eth、trx、bch、doge,以及相应的usdt、usdc等链上资产。

    3.3.去中心化社交通信应用

    基于Freecash底层逻辑、基础协议、API服务和SDK,开发功能较为防备的社交通信应用,主要包括身份管理、信誉管理、链上密信、离链私聊、开放群聊、组织内通讯等功能,探索安全、高效、抗垄断的新型社交模式。

    3.4.去中心化知识发布应用

    基于Freecash底层逻辑、基础协议、API服务和SDK,开发开放的个人知识发布应用,包括身份管理、信誉管理、知识编辑、知识发布、知识评价、作者关注、知识扩散等功能。

    3.5.去中心化文件管理应用

    基于Freecash底层逻辑、基础协议、API服务和SDK,以Freecash为基础账户和文件索引入口,将各种中心化和去中心化的存储系统连接起来,借助市场机制形成跨平台的分布式存储模式,为用户提供去中心化的云文件存储和管理应用。

    3.6.数字产品开放交易平台

    基于Freecash底层逻辑、基础协议、API服务和SDK,开发数字产品,尤其是数字艺术品的发布、认证、流通平台。

    3.7.各种应用的宣传推广

    飞签2.0和隐私备份机将在2022年完成,需要进行相应的宣传推广。但主要的宣传推广需要等待以上商业应用完成。这些商业应用,能够从不同角度体现Freecash所提供的去中心化基础设施的优势,并将这些优势转化为商业利润。与这些应用上市相同步,将会展开一系列的市场推广宣传活动,时间大致在2023年下半年陆续展开。

    fch生态结构.jpg

    密签:
    密签.png

    dplanet.io
    dplanet.io.png

    飞签
    飞签.png

    freecash.vip
    freecash.vip.png

    密圈
    密圈.png

    freecash.cc
    freecash.cc.png

    posted in Announcements & News/公告