APIP2V1_BasicInfoOnChain(zh-CN)

昌用

APIP2: BasicInfoOnChain
Version: 1
Language: zh-CN
Author: C_armX, Write_cash, Free_cash, F7rspPvuPhrc6xYYXjBoCieKAWSz9ShSNp
Status: draft
Created date: 2021-10-30
Update:2021-04-27
PID:""
TXID:

APIP2V1_BasicInfoOnChain(zh-CN)

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

关于本协议

本协议各接口提供Freecash主链上的主要信息。
本协议接口的数据来源涉及以下协议：
- 关于coindays：《FIPA4_Coindays》
本协议接口数据采用JSON格式。
本协议所有接口采用POST方法。
本协议的接口URL为：[服务方发布的urlMainPart]apip2/v1/[接口名称]
示例数据：

requester：FEk41Kqjar45fLDriztUDTUkdki7mmcjWK

requester的公钥pubKey：030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a

requester的私钥priKey：L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8

requester获得的对称密钥symKey：d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09

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

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

getBalanceList

查询余额接口。获取多个FCH地址的FCH余额、币天余额、累计销毁币天总额等。

url

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

示例

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

请求参数

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

query

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

sort

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

示例

查询FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts和FJ8rVdFAeqj11B5Ycmp2BgN2ULGa5uJfqA的fch余额和币天余额。

{
	"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
	"timestamp": 1635513688254,
	"url": "https://www.sign.cash/api/apip2/v1/getBalanceList",
	"query": {
		"terms": {
			"address": ["FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts", "FJ8rVdFAeqj11B5Ycmp2BgN2ULGa5uJfqA"]
		}
	},
	"sign": "171eb414ddde4248732f0776e607f7ed7fdd2e310da7e71cd52d3860d57db345"
}

sign =

sha256(sha256({"query":{"terms":{"address":["FJ8rVdFAeqj11B5Ycmp2BgN2ULGa5uJfqA","FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts"]}},"requesrer":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","symKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09","timestamp":"1635513688254","url":"https://www.sign.cash/api/apip2/v1/getBalanceList"}))

=171eb414ddde4248732f0776e607f7ed7fdd2e310da7e71cd52d3860d57db345

响应参数

通用参数参见通用响应方式。本接口响应参数：

data

name	type	description	requested
list	object	The list of UTXOs returned,see below.	N
total	uint	The total number of items.	Y
bestHeight	uint	The latest block height when getting the data.	Y

data.list:

name	type	description	requested
address	string	FCH address	Y
fchBalance	uint64	Fch balance of the address in units of "satoshi".
changeUnconfirmed	int64	Unconfirmed balance changes。Negative value means a decrease in the amount in units of "satoshi".
utxoNumber	uint	The number of UTXOs of this address.
cdBalance	uint64	Coindays balance of the address.
tCdd	uint64	The total coindays destroyed of this address

示例


{
	"code": 0,
	"message": "Success.",
	"data": {
		"list": [{
			"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
			"cdBalance": 2100000000,
			"tCdd": 342742273400,
			"changeUnconfirmed": -110000000,
			"utxoNumber": 18,
			"fchBalance": 210000000
		}],
		"total": 1,
		"bestHeight": 963667
	},
	"sign": "b89a27ab039071eeb2c9d8bf2a9e1a96f82a62c4ff877ca927e8830861c7cdae"
}

sign=

sha256(sha256({"code":0,"data":{"bestHeight":963667,"list":[{"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","cdBalance":2100000000,"changeUnconfirmed":-110000000,"fchBalance":210000000,"tCdd":"342742273400","utxoNumber":18}],"total":1},"message":"Success.","symKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))

=b89a27ab039071eeb2c9d8bf2a9e1a96f82a62c4ff877ca927e8830861c7cdae

响应状态

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

getUtxoList

获取某地址的utxo列表。

url

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

示例

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

请求参数

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

query

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

sort

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

示例

查询FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts地址，cd大于等于1000的utxo列表，按txTimestamp升序，从第0个开始取20条。

{
	"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
	"timestamp": 1635513688254,
	"url": "https://www.sign.cash/api/apip2/v1/getUtxoList",
	"query": {
		"bool": {
			"must": {
				"term": {
					"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts"
				},
				"range": {
					"cd": {
						"gte": 1000
					}
				}
			}
		}
	},
	"sort": [{
		"txTimestamp": {
			"order": "asc"
		}
	}],
	"from": 0,
	"size": 20,
	"sign": "5f6be9b9f420f5dda0bd5cbf16ea5b39086865261f66a0288dfba4893a5bc270"
}

响应参数

通用参数参见通用响应方式。本接口响应参数：

data

name	type	description	requested
list	object	The list of UTXOs returned,see below.	N
total	uint	The total number of items.	Y
bestHeight	uint	The latest block height when getting the data.	Y

data.list

name	type	description
txid	string	The txid of the trasaction including the utxo.
n	uint	The index number of the utxo in the transaction.
valueSatoshi	uint	The fch amount of the utxo in unit of satoshi.
cd	uint	The coindays of the utxo.
txTimestamp	timestamp	The time stamp of this transaction
blockHeight	uint	The height of the block where this transaction was written.

示例

{
	"code": 0,
	"message": "Success.",
	"data": {
		"list": [{
				"txid": "b70afeba69341ee5c026bff348388c1f8e52a9862cf699f2f65e731890bdf186",
				"n": 2,
				"valueSatoshi": 899876,
				"cd": 198247800,
				"txTimestamp": 1636180056756,
				"blockHeight": 963220
			},
			{
				"txid": "b70afeba69341ee5c026bff348388c1f8e52a9862cf699f2f65e731890bdf186",
				"n": 0,
				"valueSatoshi": 100000,
				"cd": 0,
				"txTimestamp": 1636180087654,
				"blockHeight": 963654
			}
		],
		"total":2,
		"bestHeight": 963667
	},
	"sign": "b4d81e03afef92953d7026625f537e82e297f905f5551291e99b51a1ab05aa5c"
}

响应状态

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

getTxList

交易列表查询接口。

url

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

示例

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

请求参数

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

query

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

sort

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

示例

请求输入或输出包含地址FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts，且OP_RETURN非空，且币天销毁大于等于100的交易列表，按txTimestamp降序，从第40条开始取20条。

{
	"requesrer": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
	"timestamp": 1635513688254,
	"url": "https://www.sign.cash/api/apip2/v1/getTxList",
	"query": {
		"bool": {
			"must": [{
					"range": {
						"cdd": {
							"gte": 100
						}
					}
				},
				{
					"exists": {
						"field": "opReturn"
					}
				},
				{
					"bool": {
						"should": [{
								"term": {
									"vin.address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts"
								}
							},
							{
								"term": {
									"vout.address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts"
								}
							}
						]
					}
				}
			]
		}
	},
	"sort": [{
		"txTimestamp": {
			"order": "desc"
		}
	}],
	"from": 40,
	"size": 20,
	"sign": "ebe9d877b03af97b6c15225c50f9c80c8fdf870705a2f8c3bc7aa47f525d4ef6"
}

响应参数

通用参数参见通用响应方式。本接口响应参数：

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
txid	string	The txid of this transaction
txTimestamp	string	The time stamp of this transaction
fee	uint64	Transaction fee in unit of satoshi
cdd	uint64	The coindays destroyed in this transaction
opReturn	string	message in OP_RETURN
valueSatoshi	uint64	total amount spent in unit of satoshi
blockHeight	uint	The height of the block where this transaction was written. A value of empty indicates an unconfirmed transaction.
vin	object array	The list of input. See below
vout	object array	The list of vout. See below

vin

name	type	description
txid	string	The txid where the prevout is located
n	uint	The sequence in the input list
address	string
valueSatoshi	uint64	In unit of satoshi
txTimestamp	timestamp	The time stamp of the transaction where the prevout is located

vout

name	type	description
n	uint	The sequence in the output list，Counting from 1.
address	string
valueSatoshi	uint64	In unit of satoshi

示例

{
	"code": 0,
	"message": "Success.",
	"data": {
		"list": [{
				"txid": "111111111111111111111111111111111111111111111111",
				"txTimestamp": 1636180054032,
				"fee": 2431,
				"cdd": 3600,
				"opReturn": "test in",
				"valueSatoshi": "210000000",
				"blockHeight": 963220,
				"vin": [{
						"txid": "1111111111111111111",
						"n": 2,
						"address": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
						"valueSatoshi": 10000000,
						"txTimestamp": 1600000000000
					},
					{
						"txid": "2222222222222222222",
						"n": 1,
						"address": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
						"valueSatoshi": 200000000,
						"txTimestamp": 1600000111111
					}
				],
				"vout": [{
						"n": 0,
						"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
						"valueSatoshi": 10000000
					},
					{
						"n": 1,
						"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
						"valueSatoshi": 199997569
					}
				]
			},

			{
				"txid": "211111111111111111111111111111111111111111111111",
				"txTimestamp": 1636180054239,
				"fee": 531,
				"cdd": 230,
				"opReturn": "hi",
				"valueSatoshi": "110000000",
				"blockHeight": 963233,
				"vin": [{
						"txid": "1111111111111111111",
						"n": 1,
						"address": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
						"valueSatoshi": 10000000,
						"txTimestamp": 1600000333333
					},
					{
						"txid": "2222222222222222222",
						"n": 2,
						"address": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
						"valueSatoshi": 100000000,
						"txTimestamp": 1600000444444
					}
				],
				"vout": [{
						"n": 0,
						"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
						"valueSatoshi": 10000000
					},
					{
						"n": 1,
						"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
						"valueSatoshi": 99999469
					}
				]
			}
		],
		"total": 2,
		"bestHeight": 963667
	},
	"sign": "cd31769b44f7fe3ffe725a524742cbd70c9a0d068fd8baea19f92c4cc3e8f985"
}

响应状态

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

昌用

This post is deleted!

APIP2V1_BasicInfoOnChain(zh-CN)

APIP2V1_BasicInfoOnChain(zh-CN)

目录

关于APIP

概述

通用规则

建立连接

通用请求参数

通用响应方式

签名与验证

关于本协议

getBalanceList

url

请求参数

响应参数

getUtxoList

url

请求参数

响应参数

getTxList

url

请求参数

响应参数