API：BUMO Websocket

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 setting
    repeated 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 closed
    CHAIN_SUBSCRIBE_TX = 17; //response with CHAIN_RESPONSE
    CHAIN_TX_ENV_STORE = 18;
}

通知消息注册

• 功能

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

• 请求消息类型

  CHAIN_HELLO

• 请求消息对象

  message ChainHello {
    repeated ChainMessageType api_list = 1; //By default, enable all apis
    int64   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 pass
        PENDING     = 2;    // master will check futher before put it into pending queue
        COMPLETE    = 3;    // notify if Tx write ledger successfully
        FAILURE     = 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 records
    int64       new_account_seq = 6;        //new account sequence if COMPLETE
    ERRORCODE   error_code = 7;         //use it if FAIL
    string      error_desc = 8  ;           //error desc
    int64       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 notify
    bytes 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	插入交易缓存队列失败