BUMO Websocket

概述

了解protocol buffer3

BUMO区块链是用protocol buffer 3序列化数据的，protocol buffer 3是google推出的数据序列化协议，您如果不了解protocol buffer 3，请点击proto3了解更多。我们使用的所有数据格式都能在源码的src\proto目录中找到。其中chain.proto文件中定义的数据是和交易、区块、账号密切相关的。

protocol buffer 3

BUMO提供了proto脚本，以及 cpp、java、javascript、pyton、object-c 和 php 生成的proto源码的示例。详细信息请查看proto源码。

各语言的测试程序如下：

cpp: C++的源码
io: Java的测试程序
go: Go的测试程序
js: Javascript的测试程序
python: Python的测试程序
ios: Object-c的测试程序
php: PHP的测试程序

websocket

BUMO 区块链提供了websocket API 接口。您可以在安装目录/config/bumo.json 文件种找到"wsserver"对象，它指定了websocket服务端口。

"wsserver":
{"listen_address": "0.0.0.0:36003"
}

端口配置

网络类型	WebSocket
mainnet	16003
testnet	26003
内测版本	36003

交易过程

根据意愿组装交易对象Transaction, 不同的交易有不同的数据结构（详见:交易）
交易对象序列化为字节流 transaction_blob，Transaction对象有序列化的方法，调用之后可得到字节流 transaction_blob。
用私钥skey对transaction_blob签名得到sign_data，skey的公钥为pkey。（详见:Keypair 手册）
提交交易，并可通过响应消息得到是否执行成功的消息。（详见:提交交易）

交易

protobuf结构

message Transaction {enum Limit{UNKNOWN = 0;OPERATIONS = 1000;};string source_address = 1;int64 nonce = 2;int64  fee_limit = 3;int64  gas_price =4;int64 ceil_ledger_seq = 5;bytes metadata = 6;repeated Operation operations = 7;int64 chain_id = 8;
}

关键字

关键字	类型	描述
source_address	string	交易源账号，即交易发起方的账号。当这笔交易成功后，交易源账号的nonce字段会自动加1。账号中的nonce意义是本账号作为交易源执行过的交易数量。
nonce	int64	其值必须等于交易源账号的当前nonce+1，这是为了防止重放攻击而设计的。如何查询一个账号的nonce可参考HTTP中的查询账号接口。若查询账号没有显示nonce值，说明账号的当前nonce是0。
fee_limit	int64	本交易能接受的最大的手续费。交易首先会按照这个费用收取手续费，若交易执行成功，则会收取实际的花费，否则将收取这个字段的费用。单位是MO，1 BU ＝ 10^8 MO。
gas_price	int64	用于计算每个操作的手续费，还参与交易字节费的计算。单位是MO，1 BU ＝ 10^8 MO。
ceil_ledger_seq	int64	可选，针对本交易的区块高度限制条件，高级功能。
operations	array	操作列表。本交易的有效负载，即本交易想要做什么事情。(详见:操作)
metadata	string	可选，用户自定义字段，可以不填写，备注用。

操作

交易的protobuf结构里面对应的operations，可以包含一个或者多个操作。

protobuf结构

message Operation {enum Type {UNKNOWN = 0;CREATE_ACCOUNT          = 1;ISSUE_ASSET             = 2;PAY_ASSET               = 3;SET_METADATA            = 4;SET_SIGNER_WEIGHT       = 5;SET_THRESHOLD           = 6;PAY_COIN                = 7;LOG                     = 8;SET_PRIVILEGE           = 9;};Type type = 1;string source_address = 2;bytes metadata  = 3;OperationCreateAccount      create_account     = 4;OperationIssueAsset         issue_asset        = 5;OperationPayAsset           pay_asset          = 6;OperationSetMetadata        set_metadata       = 7;OperationSetSignerWeight    set_signer_weight  = 8;OperationSetThreshold       set_threshold      = 9;OperationPayCoin            pay_coin           = 10;OperationLog                log                = 11;OperationSetPrivilege       set_privilege      = 12;
}

关键字

关键字	类型	描述
type	Type	操作码，不同的操作码执行不同的操作，详见操作码。
source_address	string	可选，操作源账户，即操作的执行方。当不填写时，默认与交易的源账户相同。
metadata	bytes	可选，用户自定义字段，可以不填写，备注用。
create_account	OperationCreateAccount	创建账号操作
issue_asset	OperationIssueAsset	发行资产操作
pay_asset	OperationPayAsset	转移资产操作
set_metadata	OperationSetMetadata	设置metadata操作
pay_coin	OperationPayCoin	转移BU资产操作
log	OperationLog	记录日志操作
set_privilege	OperationSetPrivilege	设置权限操作

操作码

操作码	说明
1	创建账号
2	发行资产
3	转移资产
4	设置metadata
7	转移BU资产
8	记录日志
9	设置权限

创建账号

操作源账号在区块链上创建一个新的账号。创建账户操作分为创建普通账号和创建合约账号。

protobuf定义如下：

// key-value对
message KeyPair{string key = 1;string value = 2;int64 version = 3;
}// 权限相关定义
message Signer {enum Limit{SIGNER_NONE = 0;SIGNER = 100;};string address = 1;int64 weight = 2;
}
message OperationTypeThreshold{Operation.Type type = 1;int64 threshold = 2;
}
message AccountThreshold{int64 tx_threshold = 1; //required, [-1,MAX(INT64)] -1: indicates no settingrepeated OperationTypeThreshold type_thresholds = 2;
}
message AccountPrivilege {int64 master_weight = 1;repeated Signer signers = 2;AccountThreshold thresholds = 3;
}// 合约相关定义
message Contract{enum ContractType{JAVASCRIPT = 0;}ContractType type = 1;string payload = 2;
}//　创建账户操作对象
message OperationCreateAccount{string dest_address = 1;Contract contract = 2;AccountPrivilege priv = 3;repeated KeyPair metadatas = 4; int64   init_balance = 5;string  init_input = 6;
}

创建普通账号

注意：在当前操作中，master_weight和tx_threshold都必须是1。且仅允许初始化下面的关键字。

关键字

关键字	类型	描述
dest_address	string	目标账号的地址。创建普通账号时，不能为空。
init_balance	int64	目标账户的初始化 BU 值，单位是MO，1 BU = 10^8 MO。
master_weight	int64	目标账号的 master 权重，数值范围［0, MAX(UINT32)]。
tx_threshold	int64	发起交易的门限，低于该值，无法发起交易，数值范围[0, MAX(INT64)]。

查询

账户信息通过HTTP中的查询账号接口查询。

创建合约账号

注意：在当前操作中，master_weight必须是0，tx_threshold必须是1。且仅允许初始化下面的关键字。

关键字

关键字	类型	描述
payload	string	合约代码内容。
init_balance	int64	目标账户的初始化 BU 值，单位是MO，1 BU = 10^8 MO。
init_input	string	可选，合约代码中init函数的入参。
master_weight	int64	目标账号的 master 权重。
tx_threshold	int64	发起交易的门限，低于该值，无法发起交易。

查询

账户信息通过HTTP中的查询账号接口查询。

通过通过HTTP中的查询交易接口查询，在result中transactions的error_desc字段中，结果如下：

[{"contract_address": "buQm5RazrT9QYjbTPDwMkbVqjkVqa7WinbjM", //合约账号"operation_index": 0                                        //交易数组中的操作索引值，0 表示第一笔交易}
]

发行资产

功能

操作源账号发行一笔数字资产，执行成功后操作源账号的资产余额中会出现这一笔资产。

protobuf结构

message OperationIssueAsset{string code = 1;int64 amount = 2;
}

关键字

关键字	类型	描述
code	string	待发行资产的代码，长度范围[1, 64]
amount	int64	待发行资产的数量，数值范围(0,MAX(int64))

转移资产

注意：如果目标账户是合约账户，则当前操作会触发目标账户的合约执行。

功能

操作源账号将一笔资产转给目标账户。

protobuf结构

message AssetKey{string issuer = 1;string code = 2;int32 type = 3;
}
message Asset{AssetKey   key = 1;int64      amount = 2;
}//　转移资产操作对象
message OperationPayAsset{string dest_address = 1;Asset asset = 2;string input = 3;
}

关键字

关键字	类型	描述
dest_address	string	目标账户地址。
issuer	string	资产发行方地址。
code	string	资产代码，长度范围[1, 64]。
type	int32	仅允许填0。
amount	int64	资产数量，数值范围(0,MAX(int64))。
input	string	可选，如果目标账户是合约账户，input会被传递给合约代码的main函数的参数。如果目标账户是普通账户，则该设置无效。

设置metadata

功能

操作源账号修改或添加一个metadata到自己的metadata表中。

protobuf结构

message OperationSetMetadata{string  key = 1;  string  value = 2;int64   version = 3;bool    delete_flag = 4;
}

关键字

关键字	类型	描述
key	string	metadata的关键字。长度范围(0, 1024]
value	string	metadata的内容。长度范围[0, 256K]
version	int64	可选，metadata版本号。默认值是0。0：不限制版本，>0 : 当前 value 的版本必须为该值， <0 : 非法
delete_flag	bool	是否删除该metadata。

设置权限

功能

设置签名者拥有的权重，设置各个操作所需要的门限。详情请见HTTP中的控制权的分配的介绍。

protobuf结构

message Signer {enum Limit{SIGNER_NONE = 0;SIGNER = 100;};string address = 1;int64 weight = 2;
}
message OperationTypeThreshold{Operation.Type type = 1;int64 threshold = 2;
}//　设置权限操作对象
message OperationSetPrivilege{string master_weight = 1;repeated Signer signers = 2;string tx_threshold = 3;repeated OperationTypeThreshold type_thresholds = 4;
}

protobuf关键字

关键字	类型	描述
master_weight	string	可选，default ""，表示该账号的 master 权重。 "" ：不设置该值；"0": 设置 master 权重为 0；("0", "MAX(UINT32)"]：设置权重值为该值；其他：非法
signers	array	可选，需要操作的 signer 列表，default 为空对象。空对象不设置
address	string	需要操作的 signer 地址，符合地址校验规则
weight	int64	可选，default 0。0 ：删除该 signer; (0, MAX(UINT32)]：设置权重值为该值，其他：非法
tx_threshold	string	可选，default ""，表示该账号的最低权限。""，不设置该值；"0": 设置 tx_threshold 权重为 0；("0", "MAX(INT64)"]：设置权重值为该值；其他：非法
type_thresholds	array	可选，不同操作需要的权力值列表，default 为空对象。空对象不设置
type	int	表示某种类型的操作 (0, 100]
threshold	int64	可选，default 0。 0 ：删除该类型操作；(0, MAX(INT64)]：设置权重值为该值；其他：非法

转移BU资产

注意：如果目标账户是合约账户，则当前操作会触发目标账户的合约执行。

功能

有两个功能：
1. 操作源账号将一笔BU 资产转给目标账户。
2. 操作源账号在区块链上创建一个新的账号。

protobuf结构

message OperationPayCoin{string dest_address = 1;int64 amount = 2;string input = 3;
}

protobuf关键字

关键字	类型	描述
dest_address	string	目标账户
amount	array	可选，需要操作的 signer 列表，default 为空对象。空对象不设置
input	string	可选，如果目标账户是合约账户，input会被传递给合约代码的main函数的参数。如果目标账户是普通账户，则该设置无效

记录日志

功能

操作源账户写日志到区块链中。

protobuf结构

message OperationLog{string topic = 1;repeated string datas = 2;
}

protobuf关键字

关键字	类型	描述
topic	string	日志主题。参数长度(0,128]
datas	array	日志内容。每个元素长度(0,1024]

Websocket接口

BUMO的websocket接口针对各种已定义的消息类型进行处理的。

消息类型

enum ChainMessageType {CHAIN_TYPE_NONE = 0;CHAIN_HELLO = 10; // response with CHAIN_STATUS = 2;CHAIN_TX_STATUS = 11;CHAIN_PEER_ONLINE = 12;CHAIN_PEER_OFFLINE = 13;CHAIN_PEER_MESSAGE = 14;CHAIN_SUBMITTRANSACTION = 15;CHAIN_LEDGER_HEADER = 16; //bumo notifies the client ledger(protocol::LedgerHeader) when closedCHAIN_SUBSCRIBE_TX = 17; //response with CHAIN_RESPONSECHAIN_TX_ENV_STORE = 18;
}

通知消息注册

功能

客户端通过该接口向区块链进行消息注册，即申请需要接收的消息类型（当前该功能不可用）。只能通过该接口获取区块链的版本信息。
请求消息类型

CHAIN_HELLO

请求消息对象

message ChainHello {repeated ChainMessageType api_list = 1; //By default, enable all apisint64   timestamp = 2;
}

请求参数

参数	类型	描述
api_list	array	申请注册的消息类型列表
timestamp	int64	申请时间

响应消息类型

CHAIN_HELLO

响应数据对象

message ChainStatus {string self_addr        = 1;int64 ledger_version    = 2;int64 monitor_version   = 3;string bumo_version     = 4;int64   timestamp       = 5;
}

响应结果

变量	类型	描述
self_addr	string	连接的节点地址
ledger_version	int64	区块版本号
monitor_version	int64	监控程序版本号
bumo_version	string	BUMO程序版本号
timestamp	int64	时间戳

提交交易

功能

将需要执行的交易，通过该消息类型发送给区块链执行。交易结构详情请见交易。
请求消息类型

CHAIN_SUBMITTRANSACTION

请求参数对象

//　签名
message Signature {string public_key = 1;bytes sign_data = 2;
}//　请求对象
message TransactionEnv {Transaction transaction = 1;repeated Signature signatures   = 2;Trigger trigger = 3;
}

请求参数

参数	类型	描述
transaction	Transaction	详情请见交易。
public_key	string	交易提交者的公钥。
sign_data	bytes	对`transaction_blob`签名得到的签名数据。

响应消息类型
- CHAIN_TX_STATUS：提交交易结果（提交交易成功，并不表示交易执行成功）。
- CHAIN_TX_ENV_STORE：返回交易执行结果。

CHAIN_TX_STATUS对象

message ChainTxStatus {enum TxStatus {UNDEFINED   = 0;CONFIRMED   = 1;    // web server will check tx parameters, signatures etc fist, noitfy CONFIRMED if passPENDING     = 2;    // master will check futher before put it into pending queueCOMPLETE    = 3;    // notify if Tx write ledger successfullyFAILURE     = 4;    // notify once failed and set error_code};TxStatus    status = 1;string      tx_hash = 2;string      source_address = 3;int64       source_account_seq = 4;int64       ledger_seq = 5;         //on which block this tx recordsint64       new_account_seq = 6;        //new account sequence if COMPLETEERRORCODE   error_code = 7;         //use it if FAILstring      error_desc = 8  ;           //error descint64       timestamp = 9;
}

CHAIN_TX_STATUS成员

变量	类型	描述
status	TxStatus	交易状态。
tx_hash	string	交易hash值。
source_address	string	交易发起源账户地址。
source_account_seq	int64	交易发起源账户的交易序号
ledger_seq	int64	这个交易记录所在的区块高度
new_account_seq	int64	当交易完成时的区块高度
error_code	ERRORCODE	错误码
error_desc	string	错误描述
timestamp	int64	时间戮

CHAIN_TX_ENV_STORE对象

message TransactionEnvStore{TransactionEnv transaction_env = 1;int32 error_code = 2;string error_desc = 3;int64 ledger_seq = 4;int64 close_time = 5;//for notifybytes hash = 6;int64 actual_fee = 7;repeated bytes contract_tx_hashes = 8;
}

CHAIN_TX_ENV_STORE成员

变量	类型	描述
transaction_env	TransactionEnv	提交的交易内容
error_code	int32	错误码
error_desc	string	错误描述
ledger_seq	int64	交易所在区块高度
close_time	int64	交易执行完成时间
hash	bytes	交易hash
actual_fee	int64	实际交易费用，单位MO
contract_tx_hashes	bytes	合约交易hash

消息订阅

功能

该接口可实现仅接口指定账户地址的交易通知。
请求消息类型

CHAIN_SUBSCRIBE_TX

请求参数对象

message ChainSubscribeTx{repeated string address = 1;
}

请求参数

参数	类型	描述
address	Transaction	要订阅的账户地址。

响应消息类型

ChainResponse

响应数据对象

message ChainResponse{int32 error_code = 1;string error_desc = 2;
}

响应结果

变量	类型	描述
error_code	int32	错误码
error_desc	string	错误描述

错误码

错误由两部分构成:

error_code : 错误码，大概的错误分类
error_desc : 错误描述，一般能从错误描述准确发现错误具体信息

错误列表如下:

error_code/错误码	枚举名	错误描述
0	ERRCODE_SUCCESS	操作成功
1	ERRCODE_INTERNAL_ERROR	服务内部错误
2	ERRCODE_INVALID_PARAMETER	参数错误
3	ERRCODE_ALREADY_EXIST	对象已存在，如重复提交交易
4	ERRCODE_NOT_EXIST	对象不存在，如查询不到账号、TX、区块等
5	ERRCODE_TX_TIMEOUT	TX 超时，指该 TX 已经被当前节点从 TX 缓存队列去掉，但并不代表这个一定不能被执行
7	ERRCODE_MATH_OVERFLOW	数学计算溢出
20	ERRCODE_EXPR_CONDITION_RESULT_FALSE	指表达式执行结果为 false，意味着该 TX 当前没有执行成功，但这并不代表在以后的区块不能成功
21	ERRCODE_EXPR_CONDITION_SYNTAX_ERROR	指表达式语法分析错误，代表该 TX 一定会失败
90	ERRCODE_INVALID_PUBKEY	公钥非法
91	ERRCODE_INVALID_PRIKEY	私钥非法
92	ERRCODE_ASSET_INVALID	无效的资产
93	ERRCODE_INVALID_SIGNATURE	签名权重不够，达不到操作的门限值
94	ERRCODE_INVALID_ADDRESS	地址非法
97	ERRCODE_MISSING_OPERATIONS	交易缺失操作
98	ERRCODE_TOO_MANY_OPERATIONS	单笔交易内超过了100个操作
99	ERRCODE_BAD_SEQUENCE	交易序号错误，nonce错误
100	ERRCODE_ACCOUNT_LOW_RESERVE	余额不足
101	ERRCODE_ACCOUNT_SOURCEDEST_EQUAL	源和目的账号相等
102	ERRCODE_ACCOUNT_DEST_EXIST	创建账号操作，目标账号已存在
103	ERRCODE_ACCOUNT_NOT_EXIST	账户不存在
104	ERRCODE_ACCOUNT_ASSET_LOW_RESERVE	支付操作，资产余额不足
105	ERRCODE_ACCOUNT_ASSET_AMOUNT_TOO_LARGE	资产数量过大，超出了int64的范围
106	ERRCODE_ACCOUNT_INIT_LOW_RESERVE	创建账号初始化资
111	ERRCODE_FEE_NOT_ENOUGH	费用不足
114	ERRCODE_OUT_OF_TXCACHE	TX 缓存队列已满
120	ERRCODE_WEIGHT_NOT_VALID	权重值不在有效范围
121	ERRCODE_THRESHOLD_NOT_VALID	门限值不在有效范围
144	ERRCODE_INVALID_DATAVERSION	metadata的version版本号不与已有的匹配（一个版本化的数据库）
146	ERRCODE_TX_SIZE_TOO_BIG	交易数据超出上限
151	ERRCODE_CONTRACT_EXECUTE_FAIL	合约执行失败
152	ERRCODE_CONTRACT_SYNTAX_ERROR	合约语法分析失败
153	ERRCODE_CONTRACT_TOO_MANY_RECURSION	合约递归深度超出上限
154	ERRCODE_CONTRACT_TOO_MANY_TRANSACTIONS	合约产生的交易超出上限
155	ERRCODE_CONTRACT_EXECUTE_EXPIRED	合约执行超时
160	ERRCODE_TX_INSERT_QUEUE_FAIL	插入交易缓存队列失败

API：BUMO Websocket相关推荐

API：BUMO Keypair 指导
BUMO Keypair 指导概述本文档详细介绍了Keypair(公.私钥对)的生成过程以及在此基础上如何生成地址(address)并对交易签名,介绍了执行交易调用的两种接口方式以及相关流程,提供 ...
API：BUMO HTTP
BUMO HTTP 概要在使用BUMO的http接口前需要对http接口中的数据格式.http的web服务器.端口配置.交易过程.交易的操作等基本信息进行了解. json http接口中的数据都是j ...
Feign核心API：Contract
Feign的核心API:Contract 前言 Feign Contract parseAndValidateMetadata BaseContract Default SynchronousMeth ...
sync-player：使用websocket实现异地同步播放视频
本文作者:星空无限原文链接:https://liyangzone.com/2020/09/20/%E5%89%8D%E7%AB%AF/sync-player/ GoEasy已获作者授权转载,GoEa ...
node.js入门 - 9.api：http
node一个重要任务是用来创建web服务,接下来我们就学习与此相关的一个重要的api -- http.我们使用http.createServer()创建一个http服务的实例,用来处理来自客户的请求. ...
Netflix Play API：我们为什么构建了一个演进式架构？
在QCon SF大会上,Suudhan Rangarajan做了题为"Netflix Play API:我们为什么构建了一个演进式架构"的演讲.他演讲的要点包括:具有单一标识/职责 ...
CV之API：利用Face++的人体识别接口，实现摄像头实时手势识别
CV之API:利用Face++的人体识别接口,实现摄像头实时手势识别目录测试图片实现代码(部分) 测试图片实现代码(部分) #利用Face++的人体识别接口,实现摄像头实时手势识别 impor ...
TF学习——TF之API：TensorFlow的高级机器学习API—tf.contrib.learn的简介、使用方法、案例应用之详细攻略
TF学习--TF之API:TensorFlow的高级机器学习API-tf.contrib.learn的简介.使用方法.案例应用之详细攻略目录 tf.contrib.learn的简介 tf.contr ...
ML之API：国内外各大人工智能平台(百度云/华为云/阿里云/Face++等)及其API的简介、使用方法之详细攻略
ML之API:国内外各大人工智能平台(百度云/华为云/阿里云/Face++等)及其API的简介.使用方法之详细攻略目录一.百度云api 1.api之CV 二.旷视科技(face++)api 1.a ...

API：BUMO Websocket

BUMO Websocket

概述

了解protocol buffer3

protocol buffer 3

websocket

端口配置

交易过程

交易

操作

操作码

创建账号

发行资产

转移资产

设置metadata

设置权限

转移BU资产

记录日志

Websocket接口

消息类型

通知消息注册

提交交易

消息订阅

错误码

API：BUMO Websocket相关推荐

最新文章

热门文章