Group Details Private

administrators

  • 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分为两部分:urlHeadurlTail

    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位,应转换为13位。


    密码算法

    哈希算法

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

    加密算法

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

    签名算法

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

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


    示例身份信息

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

    requester:FEk41Kqjar45fLDriztUDTUkdki7mmcjWK

    requester的公钥pubKey:030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a

    requester的私钥priKey:L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8

    requester获得的对称密钥symKey: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”]
            "prot": [string array, 所遵循的协议]
            "urlHead": [string, API的url的首部]
            "pubKeyAdmin": "02966dc682850550b1df046f2a03cfe546c4e4cf83f739d1497f6c292fabdad1b4",
            "params":{
    	        "urlHead": [string, API访问位置的共同部分,如http://sign.cash/api/],
    	        "receivingAccount":[string,收款账号,缺省为发布者FCH'地址],
    	        "pricePerRequest": [int, 每次请求的服务收费,采用最小单位],
    	        "minPayment": [int64, 最低单次购买金额,采用最小单位],
    	        "currency": [string,支付的币种,缺省为FCH,法币则遵循ISO4217,如'CNY']
        }
    }
    
    1. 请求方 链上查询API服务

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

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

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

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

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

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

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

    1. 请求方 解密保存symKey

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

    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为用户在本地保存symKey,用于向API服务方发起数据请求。

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

    2.APP作为请求方

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

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

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


    如何购买API服务

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

    1. 服务方链上注册服务时在data.params中声明收费信息
    {
        "receivingAccount":[string,收款账号,缺省为发布者FCH'地址],
        "pricePerRequest": [int, 每次请求的服务收费,采用最小单位],
        "minPayment": [int64, 最低单次购买金额,采用最小单位],
        "currency": [string,支付的币种,缺省为FCH,法币则遵循ISO4217,如'CNY']
    }
    
    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接口用来向服务方申请获得symKey,symKey用于后续数据请求的签名和验证。

    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
    timestamp time stamp 精确到毫秒的时间戳,防止重放攻击 Y
    sign string 用请求方私钥priKey对序列化后的其他参数的签名,防止身份伪造 Y
    • 签名

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

    • 示例

    请求参数

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

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

    请求方保存API服务信息

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

    信息名称 类型 说明 必填
    sid string 接口服务的SID,即服务方在链上注册服务时的txid N
    pid string APIP协议的PID N
    title string APIP协议的标题,如:APIP1V1_OpenAPI(zh-CN) N
    sn int APIP协议编号 Y
    ver int APIP协议版本号 Y
    sid string 当前接口服务的SID,即服务方在链上注册服务时的txid N
    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
    symKey string 当前生效的symKey,相同urlHead的各接口使用同一个symKey N
    timestamp time stamp 当前生效的symKey获得的时间戳 N
    days int 当前生效的symKey的有效天数 N
    apiBalance int64 请求方当前服务余额 all

    5. 响应

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

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

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

      • 3)验证时间戳。验证当前时间戳减timestamp的绝对值是否小于服务方设定的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.symKeyEncrypted string symKey的密文 0
    data.days int symKey的有效天数 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
    • 示例

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

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

    则响应参数为:

    {
    	"code": "0",
    	"message": "Success.",
    	"data": {
    		"symKeyEncrypted": "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地址未保存,则视为新用户。
    symKey string 该用户最新的symKey,过期保留直至用户重置
    timestamp int 当前symKey发放时间,用于控制连接的有效期
    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 请求方的fch地址 Y
    url string 当前所请求api的url Y
    timestamp 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协议规定。

    • 签名

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

    • 示例:

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

    请求参数parameters

    {
    	"requester": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    	"timestamp": 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)验证时间戳。验证当前时间戳减请求参数中timestamp的绝对值是否小于服务方设定的windowTime,防止重放攻击。过期返回1002.

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

      • 5)验证签名。在请求参数中加入requester的symKey做两次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 symKey has expired, please connect again. symKey过期,请重新连接
    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 将symKey加入响应参数做两次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.","symKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))

    = 2f09d2f1af3432063969147b9eb156fe434ed728f52f19c975d7ddca4c6bd816


    6. 请求方验证响应数据

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


    7. 请求方重置symKey

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


    APIP简易查询语法

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

    查询命令

    1. all (全查询)

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

    2. ids (id查询)

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

    3. terms (精确查询)

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

    4. part (部分查询)

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

    5. matchs (模糊查询)

    • 对多个字段,分词模糊查询给定内容。
    {
    	"matchs":{
    		"query":"good bad",
    		"fileds":["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": {
    		"address": "*cash"
    	},
    	"range": {
    		"cid": {
    			"gt": "c",
    			"lte": "f"
    		}
    	},
    	"sort": {
    		"address": "asc",
    		"cdd": "desc"
    	},
    	"after": ["F000000000000", 2000],
    	"size": 1000
    }
    //查询"address"字段以“cash”结尾,且cid首字母为d、e或f的条目,
    //按"address"一级升序,"cdd"二级降序,从地址为"F000000000000",cdd为2000的条目之后开始,取1000条。
    

    分页命令默认值

    • size、sort、after可省略。
    • sort的默认值由各数据相应协议给出。
    • size默认为20条
    • after默认为空,即从排序首位置开始获取。
    posted in Protocol/协议
  • RE: FEIP27V1_NoticeFee(en-US)
    FEIP27: NoticeFee
    Version: 1
    Language: en-US
    Author: C_armX
    Status: draft
    Created date: 2021-04-26
    Last modified date:2022-10-02
    PID: unknown
    TXID: Unpublished
    

    FEIP27V1_NoticeFee(en-US)

    Contents

    Introduction

    General rules of FEIP type protocols

    Rules specific to this protocol

    Declare

    Introduction

    
    Protocol type: FEIP
    Serial number: 27
    Protocol name: NoticeFee
    Version: 1
    Description : A identity declares the minimum payment amount with which it is willing to receive the on-chain message notifications.
    Author: C_armX
    Language: en-US
    Previous version PID:
    
    

    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. Notice fee 指的是一个地址愿意接受链上信息通知的最小FCH支付门槛,通过OP_RETURN发布用于过滤垃圾信息。

    2. Notice fee声明只针对交易的第一个输入地址。

    3. 当新的Notice fee声明时,旧的声明自动失效。

    declare

    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 2 Serial number<br>Fixed: 27 Y
    3 ver int 1 Fixed: 1 Y
    4 name String 8 Fixed: "NoticeFee" N
    5 pid hex 32 Sha256 value of this protocol file N
    6 data.noticeFee float64 8 Amout of fch<br>Up to 8 decimal places Y

    Example

    {
        "type": "FEIP",
        "sn": 27,
        "ver": 1,
        "name": "NoticeFee",
        "pid": "",
        "data":{"noticeFee":0.0001}
    }
    
    posted in Protocol/协议
  • RE: FEIP26V1_Homepage(en-US)
    FEIP26: Homepage
    Version: 2
    Language: zh-CN
    Author: C_armX
    Status: draft
    Created date: 2022-10-02
    Last modified date:2022-10-02
    PID: unknown
    TxID: Unpublished
    

    FEIP26V1_Homepage(en-US)

    Contents

    Introduction

    General rules of FEIP type protocols

    Rules specific to this protocol

    Register

    Unregister

    Introduction

    
    Protocol type: FEIP
    Serial number: 26
    Protocol name: Homepage
    Version: 1
    Description : Register homepage path on the freecash blockchain for an address.
    Author: C_armX
    Language: en-US
    Previous version PID:
    
    

    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. 通过本协议一个地址将一个URL或多个URL声明为自己的Homepage.

    2. 声明者为第一个输入地址。

    3. 新的Homepage被声明时,旧的自动注销。

    register

    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 2 Serial number<br>Fixed: 26 Y
    3 ver int 1 Fixed: 1 Y
    4 name String 8 Fixed: "Homepage"< N
    5 pid hex 32 Sha256 value of this protocol file N
    6 data.op string 7 operation: "register" Y
    7 data.url string array 512 URLs of the homepage Y

    Example

    
    {
        "type": "FEIP",
        "sn": 26,
        "ver": 1,
        "name": "Homepage",
        "pid": "",
        "data":{
            "op": "register",
            "url": ["https://cid.cash/html/others/cid.html?cid=CY_vpAv","100.100.100.100:9300"]
            }
    }
    

    Unregister

    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 2 Serial number<br>Fixed: 26 Y
    3 ver int 1 Fixed: 1 Y
    4 name String 8 Fixed: "Homepage" N
    5 pid hex 32 Sha256 value of this protocol file N
    6 data.op string 9 operation: "unregister" Y

    Example

    {
        "type": "FEIP",
        "sn": 26,
        "ver": 1,
        "name": "Homepage",
        "pid": "",
        "data":{
            "op": "unregister"
            }
    }
    
    posted in Protocol/协议
  • RE: FEIP16V1_Reputation(en-US)
    FEIP16: Reputation
    Version: 1
    Language: zh-CN
    Author: Deisler-JJ_Sboy, C_armX
    Status: draft
    Created date: 2021-02-5
    Last modified date:2022-10-02
    PID: ""
    TXID: 
    

    FEIP16V1_Reputation(en-US)

    Contents

    Introduction

    General rules of FEIP type protocols

    Rules specific to this protocol

    Example of positive rating

    Example of negative rating

    Introduction

    Protocol type: FEIP
    Serial number: 16
    Protocol name: Reputation
    Version: 1
    Description : Evaluate an CID to increase/decrease its reputation.
    Author: Deisler-JJ_Sboy,C_armX
    Language: en-US
    

    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如何在链上评价另一个地址或CID。
    2. 在链上评价他人需要消耗币天。
    3. 评价以正值符号“+”表示好评,用负值符号“-”表示差评。
    4. 评价的量用评价交易的总币天销毁表示,单位为“cd”。比如:在销毁100币天的交易中给出的差评”表示为“-100cd”,销毁88币天的好评表示为“88cd”或“+88cd”.
    5. 第一个输入地址为评价者,除了op_return以外的第一个输出地址为被评价者。

    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 2 Serial number<br>Fixed: 16 Y
    3 ver int 1 Fixed: 1 Y
    4 name String 10 Fixed: "Reputation" N
    5 pid hex 32 Sha256 value of this protocol file N
    6 data.sign string 1 must be "+" or "-" Y

    Example of positive rating

    
    First input address: FPL44YJRwPdd2ipziFvqq6y2tw4VnVvpAv
    First output address: FS2AWq1dgdhCpNTwqfBbMBBJGNNj1LSboy
    
    OP_RETURN content:
    {
        "type": "FEIP",
        "sn": 16,
        "ver": 1,
        "name": "Reputation",
        "pid": "",
        "data":{
            "sign": "+"
            }
    }
    
    

    Example of negative rating

    
    First Input address: FPL44YJRwPdd2ipziFvqq6y2tw4VnVvpAv
    First output address: FS2AWq1dgdhCpNTwqfBbMBBJGNNj1LSboy
    
    OP_RETURN content:
    
    {
        "type": "FEIP",
        "sn": 3,
        "ver": 4,
        "name": "Reputation",
        "pid": "",
        "data":{
            "sign": "-"
            }
    }
    
    
    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/协议
  • RE: FCH生态事件--汇总

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

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

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

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

    2022年6月
    6月22日,隐私备份机样机完成,基本功能全部实现,进入优化阶段。

    posted in History/历史