Navigation

    BBS.cash

    • Register
    • Login
    • Search
    • Recent
    • Tags
    • Popular
    • Users
    • Groups
    • header.languages
    1. Home
    2. 昌用
    3. Posts
    昌
    • Profile
    • Following
    • Followers
    • Topics
    • Posts
    • Best
    • Groups

    Posts made by 昌用

    • 创新还是攻击?比特币链上NFT巨块风波

      创新还是攻击?比特币链上NFT巨块风波

      2023年2月1日,比特币挖出近4M的史上最大区块,里面包含一个近4M的史上最大交易,并且交易费为0!

      这笔巨大交易由独立开发者@udiWertheimer 的比特币链上NFT项目“Taproot Wizard”发出,主要数据是一个NFT,不是哈希,是整张jpg图片!

      WechatIMG633.jpeg

      开发者和项目名不见经传,但此事引起比特币生态巨大的震动,Blockstream CEO Adam Back(@adam3us),Bitcoin Core 开发者 @LukeDashjr 等人指责该行为是对比特币的攻击。
      参见CoinDesk的报道:《Giant Bitcoin 'Taproot Wizard' NFT Minted in Collaboration With Luxor Mining Pool》

      但是,@udiWertheimer强调这是一个创新,所依据的是由比特币前核心开发者Casey Rodarmor提出的“Ordinals(序数理论)”。《Ordinals项目文档》

      @udiWertheimer和Casey Rodarmor声称该理论可以标记比特币的每一个基本单位:satoshi,并且可以转移。从而在无需软硬分叉升级的前提下,在比特币链上实现更多功能,NFT只是其中之一。

      Rodarmor声称提出Ordinals是因为比特币缺乏一个稳定的公共身份,比特币地址往往是一次性使用的,钱包账号是本地的,而公私钥的所有权不可转移。所以,通过标记每个output中的每个satoshi,Ordinals为比特币建立可转移的账号或身份。
      技术细节参见(《Ordinal Numbers》

      具体到在NFT项目“Taproot Wizard”中,发布者应该是用特定satoshi指代jpg图片,实现nft的标识和流通,笔者尚未完全理清具体实现方式。

      这是一个有意思的创新试验,但bitcoin core并不喜欢这种创新,主要原因有:

      1. 区块链膨胀:这会造成比特币区块链大小迅速膨胀,运行全节点的设备要求大幅提高而导致全网全节点减少,抗审查性下降。这是2014年拒绝Vatalik在OP_RETURN中做智能合约,以及2017年拒绝硬分叉扩容的主要原因。
      2. 生态冲击:超预期的巨大交易和巨大区块冲击钱包、矿池、浏览器等生态设施,导致一些设施出现异常,比如btc.com浏览器的该笔交易未能正常解析。
      3. 降低安全性:矿池或矿工为了减少同步和验证巨大交易和区块的时间,可能选择不下载,不验证该交易和区块的情况下出块,带来安全风险。
      4. 区块限制失效:比特币区块有1M限制,Taproot Wizard的4M数据是放在witness中上链的,使区块和交易都绕过了1M限制,并且似乎没有限制了!4M可以,400M也可以!从这个意义上讲,这不是创新,是对漏洞的攻击!

      在2017年扩容之争中,Bitcoin core拒绝硬分叉提高区块限制的方式扩容,选择用segwit在避免硬分叉的前提下,将验证信息拿到区块外,从而绕过1M的区块限制,实现部分扩容。但是,当时没有对验证信息的长度做出限制。现在不得不作出艰难的选择:

      • 选择一:什么都不做,放任各种应用以这种方式进入比特币区块链,当年限制OP_RETURN和扩容之争失去了意义;
      • 选择二:硬分叉升级,将隔离见证的数据的大小限制写入共识。这个也很难,硬分叉的影响很大,需要全部节点更新,这也是2017年拒绝纽约共识升级到2M的主要原因。
      • 选择三:主要矿池达成局部共识,拒绝巨大区块和巨大交易。这非常糟糕,开启了区块人工审查的先河,失去了去中心化的意义,操作上也很难让所有矿池都遵守。

      综合来看,选择一的可能性比较大,因为选择三难以实现,而比特币生态已经非常巨大,平稳硬分叉的难度很大。

      相关数据:

      区块高度:774628
      区块大小:3,955,272 bytes
      交易ID:0301e0480b374b32851a9462db29dc19fe830a7f7d7a88b81612b9d42099c0ae
      交易大小:3,938,383 bytes
      交易类型:segwit
      交易费:0
      出块矿工:“Luxor Mining”
      交易的发送地址:bc1pscu742m5eyt6vwzl62fjugy9mj5yq8pgk674qc2x44892t3zjqfs3ca78z
      

      注:笔者尚未理清所有技术细节,如Ordinals如何实现NFT、隔离见证数据的结构和相关限制等,欢迎指正或补充。

      posted in General Discussion/讨论区
      昌
      昌用
    • FEIP20V1_P2SH(en-US)

      FEIP20V1_P2SH(en-US)

      Contents

      Summary

      General consensus of FEIP

      Consensus of this protocol

      Publish

      Example

      Summary

      Protocol type: FEIP
      Serial number: 20
      Protocol name: P2SH
      Version: 1
      Description : Publish P2SH redeem script by the address from the script hash.
      Author: C_armX
      Language: en-US
      Created date: 2023-01-06
      Last modified date:2023-01-14
      

      General consensus of FEIP

      1. FEIP type protocols write data of consensus in OP_RETURN for public witness.

      2. The SIGHASH flag of all transaction inputs: ‘ALL’ (value 0x01).

      3. The max size of OP_RETURN : 4096 bytes.

      4. The format of the data in op_return: JSON.

      5. Encoding : utf-8.

      6. Since block height 2000000, any operation of writing to freecash blockchain needs more than 1cd consumed.

      Consensus of this protocol

      1. This protocol is used to publish P2SH redeem script by the address from the script hash.
      2. The address is Base58check encoded string of the redeem script's SHA256 + RIPEMD160 hash value with prefix '0x05'.

      Publish

      field number field name type content required
      1 type String Fixed: "FEIP" Y
      2 sn int Serial number. Fixed: 20 Y
      3 ver int Fixed: 1 Y
      4 name String Fixed: "P2SH" N
      5 pid string The PID of this protocol N
      6 data.script string Redeem script Y

      Example

      "3MRS39FX8bpV9CCjJHavw586q6a9Rogpw2"is a 2/3 multi-signature address of public keys :
      030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a
      02536e4f3a6871831fa91089a5d5a950b96a31c861956f01459c0cd4f4374b2f67
      03f0145ddf5debc7169952b17b5c6a8a566b38742b6aa7b33b667c0a7fa73762e2

      The muti-signature address sends a tx to publish the redeem script:
      "5221030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a2102536e4f3a6871831fa91089a5d5a950b96a31c861956f01459c0cd4f4374b2f672103f0145ddf5debc7169952b17b5c6a8a566b38742b6aa7b33b667c0a7fa73762e253ae"

      {
          "type": "FEIP",
          "sn": 20,
          "ver": 1,
          "name": "P2SH",
          "pid": "",
          "data":{
              "script": "5221030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a2102536e4f3a6871831fa91089a5d5a950b96a31c861956f01459c0cd4f4374b2f672103f0145ddf5debc7169952b17b5c6a8a566b38742b6aa7b33b667c0a7fa73762e253ae"
              }
      }
      
      posted in Protocol/协议
      昌
      昌用
    • FEIP4V1_Abandon(en-US)

      FEIP4V1_Abandon(en-US)

      Contents

      Summary

      General consensus of FEIP

      Consensus of this protocol

      Abandon

      Example

      Summary

      Protocol type: FEIP
      Serial number: 4
      Protocol name: Abandon
      Version: 1
      Description : An address abandon all rights by publishing its private key on chain.
      Author: C_armX
      Language: en-US
      Created date: 2023-01-06
      Last modified date:2023-01-13
      

      General consensus of FEIP

      1. Write important data in OP_RETURN for public witness under FEIP type protocols.

      2. The SIGHASH flag of all transaction inputs is ‘ALL’ (value 0x01).

      3. The max size of OP_RETURN : 4096 bytes.

      4. The format of the data in op_return: JSON.

      5. Encoding : utf-8.

      Consensus of this protocol

      1. This protocol is used to abandon one's all rights by itself.
      2. Any address can publish its private key on freecash blockchain to give up all its rights.
      3. Since block height 2000000, abandoning needs more than 1cd consumed.

      Abandon

      field number field name type content required
      1 type String Fixed: "FEIP" Y
      2 sn int Serial number. Fixed: 4 Y
      3 ver int Fixed: 1 Y
      4 name String Fixed: "Abandon" N
      5 pid string The PID of this protocol N
      6 data.priKey string The private key of the signer. Y

      Example

      FEk41Kqjar45fLDriztUDTUkdki7mmcjWK Abandon its all rights.

      {
          "type": "FEIP",
          "sn": 4,
          "ver": 1,
          "name": "Abandon",
          "pid": "",
          "data":{
              "priKey": "L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8"
              }
      }
      
      posted in Protocol/协议
      昌
      昌用
    • FEIP2V1_Code(en-US)

      FEIP2V1_Code(en-US)

      Contents

      Summary

      General consensus of FEIP

      consensus of this protocol

      Publish code

      Update code

      Stop code

      Recover code

      Rate code

      QR code

      Summary

      Protocol type: FEIP
      Serial number: 2
      Protocol name: code
      Version: 1
      Description : Publish program code information on Freecash blockchain. 
      Author: C_armX
      Language: en-US
      Previous version PID:""
      Published date: 2022-12-28
      Last modified date:2023-01-10
      

      General consensus of FEIP type protocols

      1. Write important data in OP_RETURN for public witness under FEIP type protocols.

      2. The SIGHASH flag of all transaction inputs is ‘ALL’ (value 0x01).

      3. The max size of OP_RETURN : 4096 bytes.

      4. The format of the data in op_return: JSON.

      5. Encoding : utf-8.

      Consensus of this protocol

      1. This protocol is used to publish program code information on Freecash blockchain.

      2. COID(Code Identity): The txid when publishing the code is the identity of the code。

      3. The publisher can name the code freely. We can take "[name]"+"@"+"[cid/address of the publisher]" to refer to the code, such as "FreeChain@No1_NrC7".

      4. The publisher should ensure its different codes having different name.

      5. One can only update, stop, or recover its own published code.

      6. The publisher can't rate its own code.

      7. Stopped or closed codes still can be rated.

      8. Owner or Owner's master (see FEIP6_Master) can Close the code and giving a closeStatement.

      9. A closed code can never be operated again.

      Publish code

      The publisher sends a tx with the content op_Return as following:

      field number field name type content required
      1 type String Fixed: "FEIP" Y
      2 sn int Serial number<br>Fixed: 2 Y
      3 ver int Fixed: 1 Y
      4 name String Fixed: "Code" N
      5 pid string The PID of this protocol N
      6 data.op string Operation: "publish" Y
      7 data.name string The name of the code in english Y
      8 data.version string The version of the code in english Y
      9 data.hash string The hash of this version code file Y
      10 data.desc string Description of this code N
      11 data.langs string array The program languages of the code N
      12 data.urls string array URLs,the locations to get the code N
      13 data.protocols string array The protocols followed by this code N
      14 data.pubKeyAdmin hex The public key of the FCH identity designated by the publisher of this code

      Example of publishing a code

      {
          "type": "FEIP",
          "sn": 2,
          "ver": 1,
          "name": "Code",
          "pid": "",
          "data":{
              "op":"publish",
              "name": "FreeChain",
      		"version": "1",
      		"hash": "fd3f2096a6f2c83cfada751db524d978f798b7a1530c212e0fd9c27a10bf85fb",
              "desc": "The code to parse basic information from the freecash blockchain.",
      		"langs":["java"],
              "urls": ["https://github.com/nobodyoffc/FreeChain.git"],
              "protocols":["b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553","37406e3e45750efccdb060ca2e748f9f026aebb7dadade8e8747340f380edaca"],
              "pubKeyAdmin": "02966dc682850550b1df046f2a03cfe546c4e4cf83f739d1497f6c292fabdad1b4"
          }
      }
      

      The txid is : 28e85989ce7e3bba56c8179d6dd9b180b23ff48a4ad031c72539d02750659212. It's also coid of the published code。

      update code

      The publisher of a code updates the code information. All fields will be replaced together.

      field number field name type content required
      1 type String Fixed: "FEIP" Y
      2 sn int 2erial number<br>Fixed: 2 Y
      3 ver int Fixed: 1 Y
      4 name String Fixed: "Code" N
      5 pid string The PID of this protocol N
      6 data.coid hex Txid when the code was published Y
      7 data.op string Operation: "update" Y
      8 data.name string he name of the code in english Y
      9 data.version string he version of the code in english Y
      10 data.hash string The hash of this version code file Y
      11 data.desc string Description of this code N
      12 data.langs string array The program languages of the code N
      13 data.urls string array URLs,the locations to get the code N
      14 data.protocols string array The protocols followed by this code N
      15 data.pubKeyAdmin hex The public key of the FCH identity designated by the publisher of this code

      Example of updating a code

      {
          "type": "FEIP",
          "sn": 2,
          "ver": 1,
          "name": "Code",
          "pid": "",
          "data":{
              "coid": "b8e1a19eadb3f7a639bddf360fe253226439c32197c81242b69a1ca390f87151",
              "op":"update",
              "name": "FreeChain",
      		"version": "2",
      		"hash": "fd3f2096a6f2c83cfada751db524d978f798b7a1530c212e0fd9c27a10bf85fb",
              "desc": "The code to parse basic information from the freecash blockchain.",
      		"langs":["java"],
              "urls": ["https://github.com/nobodyoffc/FreeChain.git"],
              "protocols":[],
              "pubKeyAdmin": "03c731d4db424e15920bf801e73a81a0e33c36391ab00c88ae95cc3e8fae5ed101"
          }
      }
      

      Stop code

      The owner stops maintaining a code as following:

      field number field name type content required
      1 type String Fixed: "FEIP" Y
      2 sn int Serial number<br>Fixed: 2 Y
      3 ver int Fixed: 1 Y
      4 name String Fixed: "Code" N
      5 pid string The PID of this protocol N
      6 data.coid hex Txid when the code was published Y
      7 data.op string Operation: "stop" Y

      Example of stoping a code

      {
          "type": "FEIP",
          "sn": 2,
          "ver": 1,
          "name": "Code",
          "pid": "",
          "data":{
              "coid": "b8e1a19eadb3f7a639bddf360fe253226439c32197c81242b69a1ca390f87151",
              "op":"stop"
          }
      }
      

      Recover code

      The owner recovers a Stopped code as following:

      field number field name type content required
      1 type String Fixed: "FEIP" Y
      2 sn int Serial number<br>Fixed: 2 Y
      3 ver int Fixed: 1 Y
      4 name String Fixed: "Code" N
      5 pid string The PID of this protocol N
      6 data.coid hex Txid when the code was published Y
      7 data.op string Operation: "recover" Y

      Example of stoping a code

      {
          "type": "FEIP",
          "sn": 2,
          "ver": 1,
          "name": "Code",
          "pid": "",
          "data":{
              "coid": "b8e1a19eadb3f7a639bddf360fe253226439c32197c81242b69a1ca390f87151",
              "op":"recover"
          }
      }
      

      Rate code

      Anyone but the owner rate a published code as following:

      field number field name type content required
      1 type String Fixed: "FEIP" Y
      2 sn int Serial number<br>Fixed: 2 Y
      3 ver int Fixed: 1 Y
      4 name String Fixed: "Code" N
      5 pid string The PID of this protocol N
      6 data.coid hex Txid when the code was published Y
      7 data.op string operation: "rate" Y
      8 data.rate int Score of rating from 0 to 5 N

      Example of rate a code

      {
          "type": "FEIP",
          "sn": 2,
          "ver": 1,
          "name": "Code",
          "pid": "",
          "data":{
              "coid": "b8e1a19eadb3f7a639bddf360fe253226439c32197c81242b69a1ca390f87151",
              "op": "rate",
              "rate": 4
          }
      }
      

      QR code

      The QR code of a published code has fields as following:

      {
          "meta":"FC",
          "type": "FEIP",
          "sn": 2,
          "ver": 1,
          "data":{
              "coid": "b8e1a19eadb3f7a639bddf360fe253226439c32197c81242b69a1ca390f87151"
          }
      }
      
      posted in Protocol/协议
      昌
      昌用
    • APIP1V1_OpenAPI(zh-CN)
      APIP1: OpenAPI
      Version: 1
      Language: zh-CN
      Author: C_armX, Write_cash
      Status: draft
      Created date: 2021-10-30
      Update:2022-12-01
      PID: ""
      TXID: 
      

      APIP1V1_OpenAPI(zh-CN)

      目录

      关于APIP

      APIP的发布

      接口标识

      接口url的构成

      时间戳格式

      密码算法

      示例身份信息

      API服务流程

      谁是API的请求方

      如何购买API服务

      connect接口

      数据请求接口

      APIP简易查询语法


      Type: APIP
      SerialNumber: 1
      ProtocolName: OpenAPI
      Version: 1
      Description : 定义在Freecash主链上发布开放API协议的一般方式.
      Author: C_armX,Write_cash
      Language: zh-CN
      PID:""
      

      关于APIP

      APIP(Application Programming Interface Protocols)是自由共识生态协议的一种类型,用于创建和发布开放的API文档,供API服务方开发部署通用API服务,以实现数据服务的去中心化。API需求方可以按照APIP协议从遵循该协议的任何一个API服务方那里获取数据服务。


      APIP协议的发布

      APIP协议与自由共识生态的其他自由协议一样,由协议作者按照《FEIP1_FreeProtocol》协议在链上发布注册,注册交易的OP_RETURN内容为:

      {
          "type": "FEIP"
          "sn": 1,
          "ver": 7,
          "name": "FreeProtocol",
          "pid": [string, FEIP1V7 协议文本的双sha256哈希值,该协议正式发布前暂时留空],
          "data": {
              "op": "register",
              "type": "APIP",
              "sn": [int,协议编号,必填],
              "ver": [int,协议版本号,必填],
              "name": [string,协议名称,必填],
              "desc": [string,对协议的描述],
              "authors": [string array, 作者们的fch地址],
              "pid": [string, 协议id,即协议文本的双sha256哈希值,留空为测试中协议],
              "lang": [string,语言,基于i18n编码],
              "prePid": [string,前一版本协议文本的pid],
              "fileUrl": [string array, 协议文本存放位置]
          }
      }
      

      自由协议的更新、注销和评价参见《FEIP1_FreeProtocol》。


      接口标识

      1. 通用标识

      接口名称@PID#[所属APIP协议的PID]

      1. 简化标识

      接口名称@协议类型+协议编号

      简化标识不一定唯一,主要便于人类记忆和识别,重要场景或机器识别应采用唯一标识。

      1. 示例:

      APIP1的balance接口的通用标识为:balance@PID#[APIP1协议文本的哈希值,待确认]

      简化标识为:balance@APIP1。


      接口url的构成

      接口的url分为两部分:urlHead和urlTail。

      1. urlHead

      urlHead为某API服务方提供的所有接口url的共同部分,由服务方依据《FEIP29_Service》在data.params.urlHead字段中发布在链上。格式为:

      scheme://domain or IP:port/subdirectory/

      所需信息 必填 说明
      scheme Y 协议类型,http、https、ws等
      domainOrIP Y 域名或IP
      port N 端口
      subdirectory N 接口子目录

      示例

      https://www.sign.cash/api/

      1. urlTail

      urlTail是该API服务方按照APIP协议,在链上发布API服务时声明的具体接口的具体位置。格式为:

      apip[协议编号]/v[版本号]/[接口名称]

      示例:

      apip1/v1/connect

      1. url

      接口的完整url = urlHead + urlTail

      示例:

      https://www.sign.cash/api/apip1/v1/connect


      时间戳格式

      APIP协议涉及的时间戳,若无特定说明,默认为13位,精确到毫秒。
      来自Freecash区块数据的时间戳为10位。


      密码算法

      哈希算法

      无特殊说明,哈希算法采用两次sha256算法,即:sha256(sha256(byte[] message_bytes)),哈希值为Hex,字母为小写.

      加密算法

      无特殊说明,文本和文件加解密采用ECC256k1-AESCBC算法,协议PID为[待开发完成后发布]。

      签名算法

      1. 对称密码签名:无特殊说明,对称密码签名验证采用数据加入sessionKey后序列化,做两次sha256哈希算法得到签名。

      2. 非对称密码签名:无特殊说明,非对称密码签名验证采用椭圆曲线算法(ECDSA)算法,以签发者私钥对数据进行签名,协议PID为[待开发完成后发布]。


      示例身份信息

      APIP协议默认采用以下请求方身份信息:

      requester:FEk41Kqjar45fLDriztUDTUkdki7mmcjWK

      requester的公钥pubKey:030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a

      requester的私钥priKey:L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8

      requester获得的对称密钥sessionKey:d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09


      API服务流程

      按照APIP协议,服务方(API服务的提供者,简称APISP)为请求方(API服务的使用者,APP或用户个人)提供API服务的一般流程为:

      1. 服务方 开发部署API服务

      服务方选择一个或多个链上注册的APIP协议,开发和部署相应的API服务。

      1. 服务方 链上注册API服务

      服务方依据《FEIP29_Service》协议,在链上发布自己的API服务,并给出订购方式、API的urlHead。

      发布者FCH地址为交易的第一个输入,发布交易的OP_RETURN内容为:

      {
          "type": "FEIP",
          "sn": 29,
          "ver": 2,
          "name": "Service",
          "pid": [string, FEIP29V1 协议文本的双sha256哈希值,该协议正式发布前暂时留空],
          "data":{
              "op": "start",
              "stdName": [string,服务的英文名],
              "localName": [string array,服务的其他语言名称],
              "desc": [string, 对服务的描述,包括:url共用部分,付费方式,服务价格等],
              "type": [string array, 服务的分类,可多个。应包含“APIP”]
              "protocols": [string array, 所遵循的协议]
              "urls": [string array, API的url的首部]
              "pubKeyAdmin": "02966dc682850550b1df046f2a03cfe546c4e4cf83f739d1497f6c292fabdad1b4",
              "params":{
      	        "urlHead": [string, API访问位置的共同部分,如http://sign.cash/api/],
      	        "account":[string,收款账号,缺省为发布者FCH'地址],
      			"currency": [string,支付的币种,缺省为FCH,法币则遵循ISO4217,如'CNY'],
      	        "pricePerRequest": [float, 每次请求的服务收费,采用选用货币的标准单位],
      	        "minPayment": [float, 最低单次购买金额,采用选用货币的标准单位]
          }
      }
      
      1. 请求方 链上查询API服务

      请求方在链上查询自己所需要的API服务方,获得订购方式(receivingAccount,pricePerRequest,minPayment,currency)和API路径的共同部分(urlHead)。

      1. 请求方 链下订购API服务

      请求方按照订购方式,向服务方订购API服务。服务方记录请求方的身份(FCH地址)和充值余额,开始服务。

      1. 请求方 发出连接服务请求

      请求方通过connect接口,向服务方发起包含自身pubKey的连接请求和私钥签名,以获得后续数据请求使用的对称密钥sessionKey,详情参见[##connect接口](##connect接口)。

      1. 服务方 验证请求分配密钥

      服务方对请求进行安全验证后,发放用请求方pubKey加密的对称密钥sessionKey。具有相同urlHead的接口共用同一个sessionKey。

      1. 请求方 解密保存sessionKey

      请求方用自己的私钥priKey解密密文,获得sessionKey,保存用于后续数据请求。

      1-7步骤的流程图:

      APIP1_OpenAPI插图 连接.png

      1. 请求方 发出数据服务请求

      请求方根据自身数据需求,选择服务方的对应接口,构造API的url和请求参数并签名后,向服务方发出数据请求。详情参见[##数据服务接口](##数据服务接口)

      1. 服务方 验证请求返回数据

      服务方收到请求后,进行安全验证无误后,返回响应数据和签名给请求方。

      1. 请求方 验证签名接受数据

      请求方收到响应数据后,验证签名是否无误则接受数据,服务完成。

      8-10的流程图:

      APIP1_OpenAPI插图 数据.png

      谁是API的请求方

      APP有两种请求方设定逻辑:

      1.用户作为请求方

      • 1)用户通过APP或其他途径用自己的FCH地址购买服务。

      • 2)用户进入APP需要获取数据时,用自己的私钥签名发起connect连接请求。

      • 3)APP为用户在本地保存sessionKey,用于向API服务方发起数据请求。

      • 4)特点:符合密码经济中“用户掌握数据”的安全准则,减少对APP的依赖,更加安全、开放、去中心化。

      2.APP作为请求方

      • 1)APP发布者用自己的地址向API服务方购买服务,获得sessionKey。

      • 2)用户使用APP时,所需要的数据由APP向API服务方提出请求。

      • 3)特点:符合传统开发习惯,便于APP运营者掌控数据,有中心化风险。


      如何购买API服务

      请求方购买API服务的方式由服务方在链上注册服务时,在data.desc字段描述,在data.params字段给出相关参数。服务方未特殊声明,则默认采用以下方式:

      1. 服务方链上注册服务时在data.params中声明收费信息
      {
      	"urlHead": [string, API访问位置的共同部分,如http://sign.cash/api/],
      	"account":[string,收款账号,缺省为发布者FCH'地址],
      	"currency": [string,支付的币种,缺省为FCH,法币则遵循ISO4217,如'CNY'],
      	"pricePerRequest": [float, 每次请求的服务收费,采用选用货币的标准单位],
      	"minPayment": [float, 最低单次购买金额,采用选用货币的标准单位]
      }
      
      1. 请求方链上获取收费信息的两种方式

        • 1)通过APP获取。APP提供API服务方及价格列表,供请求方选择购买服务。

        • 2)请求方自行查找链上API服务方,获取API服务的收费信息。

      2. 请求方链上购买服务的两种方式

        • 1)通过APP购买。APP在请求方同意购买,并填写或选择支付金额后,为请求方构造包含购买标记的交易,由请求方确认后发送交易。

          1. 请求方自行构造包含购买标记的交易完成支付。
      3. 请求方的购买标记,即购买交易的OP_RETURN内容,如下:

      {
          "type": "APIP"
          "sn": 1,
          "ver": 1,
          "name": "OpenAPI",
          "pid": [string, FEIP1V7 协议文本的双sha256哈希值,该协议正式发布前暂时留空],
          "data": {
              "op":"buy",
              "sid":[string,所购买服务的sid,必填]
          }
      }
      
      
      1. API服务方启动服务

        • API服务方收到有购买标记的交易后,自动登记第一个输入的FCH地址为用户ID,并登记余额,开始服务。

        • 请求方的每次请求按pricePerRequest计减余额。

        • 余额一旦小于pricePerRequest则服务终止,删除该用户信息,以防止用户信息累计过多,并防止与此相关的攻击。


      connect接口

      connect接口用来向服务方申请获得sessionKey,sessionKey用于后续数据请求的签名和验证。

      1. 接口名称

      connect


      2. 请求方法

      POST


      3. URL

      url = urlHead + urlTail

      = [服务方链上注册服务时的data.params.urlHead值] + "apip1/v1/connect"

      示例:

      data.params.urlHead = "https://www.sign.cash/api/"
      
      url: "https://www.sign.cash/api/apip1/v1/connect"
      
      

      4. 请求参数

      参数 类型 说明 必填
      pubKey hex 请求方的公钥,用于验证身份和授权 Y
      url string 当前connect的url,防止重放攻击 Y
      time time stamp 精确到毫秒的时间戳,防止重放攻击 Y
      sign string 用请求方私钥priKey对序列化后的其他参数的签名,防止身份伪造 Y
      • 签名

      请求方用自己的私钥priKey对除sign之外的请求参数序列化后,进行签名,得到sign,加入请求json。

      • 示例

      请求参数

      {
      	"pubKey": "030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a",
      	"url": "https://www.sign.cash/api/apip1/v1/connect",
      	"time": 1635513688254,
          "sign": "H6d+wvrsj5Bgh4Y2GeOFujYvXijMK1FG97bSDd7zaX8VY78X3a2Ey2Success.wpyo5ASiwWA8cW6gP1rejWjZMbPcS3k\u003d"
      }
      

      其中,sign为私钥priKey(L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8)对序列化后的其他请求参数({"pubKey":"030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a","time":"1635513688254","url":"https://www.sign.cash/api/apip1/v1/connect"})所做的签名。

      请求方保存API服务信息

      请求方为其使用的每个APIP协议,分别保存以下信息:

      信息名称 类型 说明 必填
      sid string 接口服务的SID,即服务方在链上注册服务时的txid Y
      pid string APIP协议的PID N
      title string APIP协议的标题,如:APIP1V1_OpenAPI(zh-CN) N
      sn int APIP协议编号 Y
      ver int APIP协议版本号 Y
      stdName string 接口服务链上注册的英文标准名称 N
      urlHead string connect的urlHead,相同sid的urlHead值相同 Y
      pubKeyAdmin string 发布者为api服务指定的管理员pubKey,用于加密和验证签名,缺省为服务发布者公钥 N
      addressAdmin string 发布者为api服务指定的管理员,即pubKeyAdmin计算的FCH地址,缺省为服务发布者地址 N
      receivingAccount string 服务方链上发布的充值收款账号,缺省为发布者FCH地址 N
      pricePerRequst string 每次请求的服务收费,采用最小单位 N
      minPayment string 最低单次购买金额,采用最小单位 N
      currency string 支付的币种,缺省为FCH,法币则遵循ISO4217,如'CNY' N
      sessionKey string 当前生效的sessionKey,相同urlHead的各接口使用同一个sessionKey N
      sessionName string sessionKey的双sha256哈希值的后6字节base64编码,请求时代表请求方 N
      time time stamp 当前生效的sessionKey获得的时间戳 N
      days int 当前生效的sessionKey的有效天数 N
      apiBalance int64 请求方当前服务余额 all

      5. 响应

      • 验证请求。服务方对请求依次验证:

        • 1)验证用户。验证requester是否在用户列表中,用户列表由余额大于pricePerRequest的FCH地址构成。不在列表返回1000.

        • 2)验证请求对象。验证签名内容中的“url”值是否与服务方当前接口的url相同,防止重放攻击。不同则返回1001

        • 3)验证时间戳。验证当前时间戳减time的绝对值是否小于服务方设定的windowTime。过期返回1002.

        • 4)验证签名:用pubKey验证签名sign是否正确,防止身份伪造。失败返回1003。

      • 响应状态

      code message 说明 响应参数
      0 Success. 请求成功.返回数据和签名 data,apiBalance
      1000 Please purchase the service. 请购买该服务。返回购买信息 receivingAccount, pricePerRequst, minPayment, currency
      1001 The URL you requested is wrong. 请求中的url与服务方接口url不符,返回服务方接口url url
      1002 Request expired, 请求已过期。返回服务方设定的时间窗口长度。 windowTime
      1003 Failed to verify signature. 验证签名失败
      1006 Other error,please contact the service provider. 其他错误,请联系服务方.
      1020~1099 API服务商自定义响应码、响应信息和响应参数
      • 响应参数
      参数 类型 说明 适用状态
      code int 响应状态码 all
      message string 响应状态描述 all
      data.sessionKeyEncrypted string sessionKey的密文 0
      data.days int sessionKey的有效天数 0
      data.receivingAccount string 服务方链上发布的充值收款地址,缺省为服务发布者地址 1000
      data.pricePerRequst string 服务方每次请求价格 1000
      data.minPayment string 服务方最低充值金额 1000
      data.currency string 充值币种,缺省为"FCH",法币则遵循ISO4217 1000
      data.url string 服务方当前接口的url 1001
      data.windowTime timestamp 服务方设置的时间窗口长度,精确到毫秒 1002
      apiBalance int64 请求方当前服务余额 all
      • 示例

      设服务方验证请求无误后,为该请求方分配sessionKey为:"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"。

      请求方公钥pubKey为:"030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a"。

      则响应参数为:

      {
      	"code": "0",
      	"message": "Success.",
      	"data": {
      		"sessionKeyEncrypted": "A+wCC1gjAoWiF+it5xnE668eoJHHMnF5UpjI2fxKQeuJyOWAiFsl5RPX0HEIEPm5ygmOifwBpZ2Yh3e5NyH2BlDEPaYPFoUZqdedBTRWoVHR48hKFN088dZYX+/6f0w+jhOsjxylXlxdwe6p/kwXNIuQ3iEVPz9cyVGNdFm8vVMQkHtbZlIdDjj0L13CCOuIJnByjNBMsPbP4qCnNSunuAIV91z2XAGlofGrIozGA3AY",
      		"days": 365
      	},
      	"apiBalance": 2000
      }
      
      

      服务方应保存的用户信息

      名称 类型 说明
      address string 用户的FCH地址,即ID,应与充值FCH地址、connect请求参数中pubKey计算的FCH地址相同。
      apiBalance int64 用户余额,余额小于pricePerRequest值,则删除该用户所有信息,充值后重建用户信息
      pubKey string 用户的公钥,connect请求时获取,用于验证connect请求的签名。若对应FCH地址未保存,则视为新用户。
      sessionName string sessionKey的双sha256哈希值的后6字节base64编码,请求时代表请求方
      sessionKey string 该用户当前的sessionKey
      time int 当前sessionKey发放时间,用于控制连接的有效期
      days int N

      数据请求接口

      1. 接口名称

      接口名称在相应APIP协议中定义。

      示例:

      在协议APIP99V1中定义接口 interface1


      2. 请求方法

      POST


      3. URL

      url = urlHead + urlTail

      urlHead为 [服务方链上注册服务时的data.params.urlHead值],如:"https://www.sign.cash/api/"

      urlTail在具体的APIP协议的具体接口处定义,格式为:apip[协议编号]/v[协议版本号]/[接口名称]。如:"apip99/v1/interface1"

      示例:

      urlHead = "https://www.sign.cash/api/"
      
      urlTail = "apip99/v1/interface1"
      
      url: "https://www.sign.cash/api/apip99/v1/interface1"
      
      

      4. 请求参数

      请求应包含以下通用参数:

      name type description requested
      requester string 请求方的sessionName Y
      url string 当前所请求api的url Y
      time timestamp 发起请求的时间戳,精确到毫秒 Y
      query object 请求数据的查询语句,参见APIP简易查询语法 N
      sort object 请求数据的排序语句,参见APIP简易查询语法 N
      from int 请求列表数据时的起始位置,从0开始 N
      size int 请求列表数据时的每页条目数 N
      sign string 用symkey对其他参数所做的签名 Y

      query、sort、from和size由具体APIP协议规定。

      • 签名

      将sessionKey加入除sign以外的其他请求参数并序列化后,做两次sha256计算,获得sign。

      • 示例:

      查询address包含“armX”,且1000<amount<=2000的条目,按amount升序排列,取前20条。

      请求参数parameters:

      {
      	"requester": "1111111111",
      	"time": 1635513688254,
      	"url": "https://www.sign.cash/api/interface1",
      	"query": {
      		"bool": {
      			"must": {
      				"match": {
      					"address": "armX"
      				},
      				"range": {
      					"amount": {
      						"gt": 1000,
      						"lte": 2000
      					}
      				}
      			}
      		}
      	},
      	"sort": [{
      		"amount": {
      			"order": "asc"
      		}
      	}],
      	"from": 0,
      	"size": 20,
      	"sign": "814b7ab051e0d4141129b7ae6e884d17e8c78c0afe91cef5790d51c0241a0d40"
      }
      

      其中:

      sign =

      sha256(sha256(parametersWithoutSign.getBytes()))

      =1111111111111111


      5. 响应

      • 验证请求:服务方按顺序验证请求

        • 1)验证用户。验证requester是否在用户列表中,用户列表由余额大于pricePerRequest的FCH地址构成。不在列表返回1000。

        • 2)验证请求对象。验证签名内容中的url值是否与服务方当前接口的url相同,防止重放攻击。不同则返回1001。

        • 3)验证时间戳。验证当前时间戳减请求参数中time的绝对值是否小于服务方设定的windowTime,防止重放攻击。过期返回1002.

        • 4)验证sessionKey时效。检查服务器保存的requeter的sessionKey是否过期。过期返回1004.

        • 5)验证签名。在请求参数中加入requester的sessionKey做两次sha256哈希,验证值是否与sign的值一致。不一致返回1003。

      • 响应状态

      code message 说明 响应参数
      0 Success. 请求成功.返回数据和签名 data, apiBalance
      1000 Please purchase the service. 请购买该服务。返回购买信息 receivingAccount, pricePerRequst, minPayment, currency
      1001 The URL you requested is wrong. 请求中的url与服务方接口url不符,返回服务方接口url url
      1002 Request expired, 请求已过期。返回服务方设定的时间窗口长度。 windowTime
      1003 Failed to verify signature. 验证签名失败
      1004 The sessionKey has expired, please connect again. sessionKey过期,请重新连接
      1005 Too much data requested. 请求数据太多。返回最大请求数量。 maxSize
      1006 No data meeting the conditions. 没查到符合条件的数据
      1007 Other error,please contact the service provider. 其他错误,请联系服务方.
      2000~ API服务商自定义响应码、响应信息和响应参数.
      • 响应参数
      参数 类型 说明 适用状态
      code int 响应状态码 all
      message string 响应状态描述 all
      data object 正常返回非列表数据,由具体APIP定义 0
      data.receivingAccount string 1000状态,服务方链上发布的充值收款地址,缺省为服务发布者地址 1000
      data.pricePerRequst string 服务方每次请求价格 1000
      data.minPayment string 服务方最低充值金额 1000
      data.currency string 充值币种,缺省为"FCH",法币则遵循ISO4217 1000
      data.url string 服务方当前接口的url 1001
      data.windowTime timestamp 服务方设置的时间窗口长度,精确到毫秒 1002
      data.maxSize int 服务方设定的最大响应数量 1005
      apiBalance int64 请求方当前服务余额 all
      sign string 将sessionKey加入响应参数做两次sha256哈希的签名值 all
      • 示例
      {
      	"code": "0",
      	"message": "Success.",
      	"data": {
      		"total": 3,
      		"p0": [{
      			"p3": 3,
      			"p4": "c",
      			"p5": "BBBBB"
      		}, {
      			"p3": 5,
      			"p4": "b",
      			"p5": "CCCCC"
      		}, {
      			"p3": 4,
      			"p4": "a",
      			"p5": "aaaaa"
      		}],
      		"bestHeight": 100
      	},
      	"apiBalance": 55000,
      	"sign": "2f09d2f1af3432063969147b9eb156fe434ed728f52f19c975d7ddca4c6bd816"
      }
      
      

      其中

      sign=

      sha256(sha256({"apiBalance":55000,"code":"0","data":{"bestHeight":100,"p0":[{"p3":3,"p4":"c","p5":"BBBBB"},{"p3":5,"p4":"b","p5":"CCCCC"},{"p3":4,"p4":"a","p5":"aaaaa"}],"total":3},"message":"Success.","sessionKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))

      = 2f09d2f1af3432063969147b9eb156fe434ed728f52f19c975d7ddca4c6bd816


      6. 请求方验证响应数据

      请求方收到数据后,取出sign,加入sessionKey序列化后,做两次sha256哈希,与sign值相比较,一致则接受数据。以防止中间人攻击。


      7. 请求方重置sessionKey

      请求方在1)希望重置sessionKey,或2)收到错误码1004,sessionKey过期时,或3)收到错误码1000,并完成充值时,用connect接口申请新的sessionKey。


      APIP简易查询语法

      • 通用语法仅实现简单查询功能,复杂查询功能语法由API服务商自行定义和发布。

      查询命令

      1. all (全查询)

      • 获取全部条目。
      {
      	"all":{}
      } 
      //查询所有条目。
      

      2. ids (id查询)

      • 获取给定id条目,可同时查询多个值。
      {
      	"ids":["0000000000000","1111111111111"]
      }查询id为"1111111111"或"22222222222"的条目
      

      3. terms (精确查询)

      • 对单一字段精确匹配,可同时查询多个值。
      {
      	"terms":{
      		"querys":["0000000000000","1111111111111"],
      		"fields":["pid","sid"]
      		}
      } //查询字符串字段“address”值为"F000000000000"或"F111111111111"的条目。
      
      {
      	"terms":{
      		"querys":["1000","2000"],
      		"fields":["cd","cdd"]
      		}
      } //查询整数字段“fee”的值为"1000"或"2000"的条目。
      

      4. part (部分查询)

      • 对单一字段,搜索包含特定值的条目,可使用通配符*和?。
      {
      	"part":{
      		"query":"arm?*“,
      		"fields":["addr","cid"]
      		}
      } //查询“address”字段值以“‘arm’加一个任意字符”开头的条目。
      

      5. match (模糊查询)

      • 对多个字段,分词模糊查询给定内容。
      {
      	"match":{
      		"query":"good bad",
      		"fields":["article","post","reply"]
      		}
      } 
      //在"article","post"和"reply"字段中,模糊查询包含’good‘或’bad‘(不区分大小写)的条目,并给出评分。
      

      6. exist (非空查询)

      • 查询某个字段存在且非null的条目。
      {
      	"exist":"cid"
      } 
      //查询“cid”字段存在且非null的条目。
      

      7. nonexist (为空查询)

      • 查询某个字段不存在或为null的条目
      {
      	"nonexist":"cid"
      } 
      //查询“cid”字段不存在或为null的条目
      

      8. range (范围查询)

      • 对单个字段按范围查询,查询条件关系为与。
      {
      	"range": {
      		"amount": {
      			"gt": 3000,
      			"lte": 10000
      		}
      	}
      }//查询amount值大于3000,小于等于10000的条目。
      
      {
      	"range": {
      		"cid": {
      			"gt": "c",
      			"lte": "f"
      		}
      	}
      }//查询cid首字母为d、e和f的条目。
      

      分页命令

      1. size (请求数量)

      • 请求返回的条目数量。
      {
      	"size":1000
      } 
      //请求返回1000条。
      

      2. sort (请求排序)

      • 查询结果的排序条件
      {
      	"sort":{
      		"address":"asc",
      		"cdd":"desc"
      		}
      } 
      //第一级按"address"升序,第二级按cdd降序排列条目。
      

      3. after (上次末位)

      • 定位从某项之后开始获取。
      • 必须与sort一起使用,并且与sort的字段名一一对应。
      • 按照”sort“给出的顺序,从"after"值之后开始获取。
      • 没有“after”则从排序第一项开始获取。
      {
      	"after":["F000000000000",2000]
      } 
      //按照address一级升序和cdd二级降序的排序,从address为F000000000000,cdd为2000之后的那一项开始获取size个条目。
      

      其他规则

      查询命令只能“与”组合

      {
      	"part": {
      		"query":"*cash",
      		"fields":["addr"]
      	},
      	"range": {
      		"cid": {
      			"gt": "c",
      			"lte": "f"
      		}
      	},
      	"sort": {
      		"address": "asc",
      		"cdd": "desc"
      	},
      	"after": ["F000000000000", 2000],
      	"size": 1000
      }
      //查询"addr"字段以“cash”结尾,且cid首字母为d、e或f的条目,
      //按"address"一级升序,"cdd"二级降序,从地址为"F000000000000",cdd为2000的条目之后开始,取1000条。
      

      分页命令默认值

      • size、sort、after可省略。
      • sort的默认值由各数据相应协议给出。
      • size默认为20条
      • after默认为空,即从排序首位置开始获取。
      posted in Protocol/协议
      昌
      昌用
    • RE: FEIP6V6_Master(en-US)
      FEIP6: Master
      Version: 6
      Language: zh-CN
      Author: C_armX
      Status: draft
      Created date: 2021-06-23
      Last modified date:2022-10-02
      PID: ""
      TXID: 
      

      FEIP6V6_Master(en-US)

      Contents

      Introduction

      General rules of FEIP type protocols

      Rules specific to this protocol

      OP RETURN

      Example of an authorition

      Introduction

      Protocol type: FEIP
      Serial number: 6
      Protocol name: Master
      Version number: 6
      Description : An address authorize another address as its master.
      Author: C_armX
      Language: en-US
      Previous version PID:"bcba4e28eb4c591a1fd1bce2108c2a220fc3a6d762eaca68bb15ca2cace22f5b"
      

      General consensus of FEIP type protocols

      1. FEIP类型协议将重要信息通过OP_RETURN写入FCH主链获得全网见证.

      2. FEIP类型协议的所有输入的SIGHASH必须是“ALL”(值为 0x01),以便签名包含OP_RETURN.

      3. OP_RETURN最大为4096字节。

      4. 数据写入OP_RETURN的格式为:JSON.

      5. 数据编码为: utf-8.

      Consensus of this protocol

      1. 一个地址一旦声明授权一个master address,被授权的master address可以控制授权地址的所有权力和利益。

      2. 一个地址不能授权自身。

      3. 授权不能被取消。

      4. 一个地址只能做一次授权声明,此后的声明无效。

      OP_RETURN

      The OP_RETURN of which contains the data as follows:

      field number field name type length content required
      1 type String 4 Fixed: "FEIP" Y
      2 sn int 1 Fixed: 6 Y
      3 ver int 1 Fixed: 6 Y
      4 name string 6 Fixed: "Master" Y
      5 pid hex 32 Sha256 value of this file N
      6 data.master string 32 The FCH address designated as the master. Y
      7 data.promise string 34 Fixed:"The master owns all my rights." Y

      Example of a authorition

      
      {
          "type": "FEIP",
          "sn": 6,
          "ver": 6,
          "name": "Master",
          "pid": ""
          "data":{
              "master":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
              "promise":"The master owns all my rights."
              }
      }
      
      posted in Protocol/协议
      昌
      昌用
    • RE: FEIP3V4_CID(en-US)
      FEIP3: CID
      Version: 4
      Language: zh-CN
      Author: C_armX, Deisler-JJ_Sboy,Free_Cash
      Status: draft
      Created date: 2021-02-5
      Last modified date:2022-10-04
      PID: "0dcdf9e355f108ce47f7cdc4043ca6fc6e3ea51090f80622eeae55a0c15f2c9a"
      TXid: 
      

      FEIP3V4_CID(zh_CN)

      Contents

      简介

      FEIP协议共识

      本协议共识

      OP_RETURN数据格式

      注册CID示例

      注销CID示例

      Introduction

      
      Protocol type: FEIP
      Serial number: 3
      Protocol name: CID
      Version: 4
      Description : Register or unregister a human friendly identity for an address.
      Author: C_armX, Deisler-JJ_Sboy,Free_Cash
      Language: en-US
      Previous version PID:"0dcdf9e355f108ce47f7cdc4043ca6fc6e3ea51090f80622eeae55a0c15f2c9a"
      
      

      General consensus of FEIP type protocols

      1. FEIP类型协议将重要信息通过OP_RETURN写入FCH主链获得全网见证.

      2. FEIP类型协议的所有输入的SIGHASH必须是“ALL”(值为 0x01),以便签名包含OP_RETURN.

      3. OP_RETURN最大为4096字节。

      4. 数据写入OP_RETURN的格式为:JSON.

      5. 数据编码为: utf-8.

      Consensus of this protocol

      1. CID(Crypto Identity,密码身份)格式:"name"+"_"+suffix, 比如:CY_vpAv.

      2. 后缀:默认为地址的后四位字符。如果新注册的CID全称与已注册(包括已注销)的CID相同,则后缀增加一位,以此类推。如:CY_SvpAv,CY_5SvpAv。

      3. 当某个地址注册了新的CID,则之前的CID自动注销。

      4. 一旦某个CID被特定地址注册成功,则其他地址将不能够注册该CID,即使该CID已注销。

      5. 已经注销的CID,只有其原地址可以重新注册该CID。

      6. 一个地址可以主动注销当前CID,注销后,该地址的状态为无CID。

      7. 一个地址最多只能占用4个CID。

      OP_RETURN

      CID操作的OP_RETURN数据格式如下:

      field number field name type length<br>bytes content required
      1 type String 4 Fixed: "FEIP" Y
      2 sn int 1 Serial number<br>Fixed: 3 Y
      3 ver int 1 Fixed: 4 Y
      4 name String 3 Fixed: "CID" N
      5 pid hex 32 Sha256 value of this protocol file N
      6 data.op string 6-8 operation: "register" or "unregister" Y
      7 data.name string 1-32 Nick name given by the user Y when operation is register,<br>N when operation is unregister

      注册CID示例

      
      Address: FPL44YJRwPdd2ipziFvqq6y2tw4VnVvpAv
      CID:CY_vpAv
      OP_RETURN content:
      
      {
          "type": "FEIP",
          "sn": 3,
          "ver": 4,
          "name": "CID",
          "pid": "",
          "data":{
              "op": "register",
              "name": "CY"
              }
      }
      
      

      注销CID示例

      
      Address: FPL44YJRwPdd2ipziFvqq6y2tw4VnVvpAv
      
      OP_RETURN content:
      
      {
          "type": "FEIP",
          "sn": 3,
          "ver": 4,
          "name": "CID",
          "pid": "",
          "data":{
              "op": "unregister"
              }
      }
      
      
      posted in Protocol/协议
      昌
      昌用
    • 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字段,将requester和sign追加至末尾,发送给服务方。

        • 验证请求:API服务方验证requester授权、sign、timestamp、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/协议
      昌
      昌用