文档中心

文档中心

  • English

›API

介绍

  • 概述
  • 优势

节点部署

  • 概述和系统要求
  • 接入体验链
  • 搭建私链
  • 运维
  • 常见问题

API

  • 概述
  • HTTP
  • Websocket
  • Keypair

SDK

  • JAVA
  • Nodejs
  • GO
  • PHP
  • IOS
  • 隐私交易 JNI

场景示例

  • 资产发行
  • 存证
  • 智能合约资产
  • 隐私交易

智能合约

  • 介绍
  • 语法说明

术语

  • 术语

BubiChain Websocket

Websocket接口

BubiChain的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_HGasDER = 16; //BubiChain 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_listarray申请注册的消息类型列表
    timestampint64申请时间
  • 响应消息类型

    CHAIN_HELLO

  • 响应数据对象

    message ChainStatus {
      string self_addr        = 1;
      int64 ledger_version    = 2;
      int64 monitor_version   = 3;
      string buchain_version      = 4;
      int64   timestamp       = 5;
    }
    
  • 响应结果

    变量类型描述
    self_addrstring连接的节点地址
    ledger_versionint64区块版本号
    monitor_versionint64监控程序版本号
    bubichain_versionstringBubiChain程序版本号
    timestampint64时间戳

提交交易

  • 功能

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

  • 请求消息类型

    CHAIN_SUBMITTRANSACTION

  • 请求参数对象

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

    参数类型描述
    transactionTransaction详情请见交易结构。
    public_keystring交易提交者的公钥。
    sign_databytes对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成员

    变量类型描述
    statusTxStatus交易状态。
    tx_hashstring交易hash值。
    source_addressstring交易发起源账户地址。
    source_account_seqint64交易发起源账户的交易序号
    ledger_seqint64这个交易记录所在的区块高度
    new_account_seqint64当交易完成时的区块高度
    error_codeERRORCODE错误码
    error_descstring错误描述
    timestampint64时间戮
  • 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_envTransactionEnv提交的交易内容
    error_codeint32错误码
    error_descstring错误描述
    ledger_seqint64交易所在区块高度
    close_timeint64交易执行完成时间
    hashbytes交易hash
    actual_feeint64实际交易费用,单位UGas
    contract_tx_hashesbytes合约交易hash

消息订阅

  • 功能

    该接口可实现仅接口指定账户地址的交易通知。

  • 请求消息类型

    CHAIN_SUBSCRIBE_TX

  • 请求参数对象

    message ChainSubscribeTx{
      repeated string address = 1;
    }
    
  • 请求参数

    参数类型描述
    addressTransaction要订阅的账户地址。
  • 响应消息类型

    ChainResponse

  • 响应数据对象

    message ChainResponse{
          int32 error_code = 1;
          string error_desc = 2;
    }
    
  • 响应结果

    变量类型描述
    error_codeint32错误码
    error_descstring错误描述

交易结构

  • 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_addressstring交易源账号,即交易发起方的账号。当这笔交易成功后,交易源账号的nonce字段会自动加1。账号中的nonce意义是本账号作为交易源执行过的交易数量。
    nonceint64其值必须等于交易源账号的当前nonce+1,这是为了防止重放攻击而设计的。如何查询一个账号的nonce可参考HTTP中的查询账号接口。若查询账号没有显示nonce值,说明账号的当前nonce是0。
    fee_limitint64本交易能接受的最大的手续费。交易首先会按照这个费用收取手续费,若交易执行成功,则会收取实际的花费,否则将收取这个字段的费用。单位是UGas,1 Gas = 10^8 UGas。
    gas_priceint64用于计算每个操作的手续费,还参与交易字节费的计算。单位是UGas,1 Gas = 10^8 UGas。
    ceil_ledger_seqint64可选,针对本交易的区块高度限制条件,高级功能。
    operationsarray操作列表。本交易的有效负载,即本交易想要做什么事情。(详见:操作结构)
    metadatabytes可选,用户自定义字段,可以不填写,备注用。

操作结构

交易的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;
    }
    
  • 关键字

    关键字类型描述
    typeType操作码,不同的操作码执行不同的操作,详见操作码。
    source_addressstring可选,操作源账户,即操作的执行方。当不填写时,默认与交易的源账户相同。
    metadatabytes可选,用户自定义字段,可以不填写,备注用。
    create_accountOperationCreateAccount创建账号操作
    issue_assetOperationIssueAsset发行资产操作
    pay_assetOperationPayAsset转移资产操作
    set_metadataOperationSetMetadata设置metadata操作
    pay_coinOperationPayCoin转移Gas资产操作
    logOperationLog记录日志操作
    set_privilegeOperationSetPrivilege设置权限操作

操作码

操作码说明
1创建账号
2发行资产
3转移资产
4设置metadata
7转移Gas资产
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_addressstring目标账号的地址。创建普通账号时,不能为空。
    init_balanceint64目标账户的初始化 Gas 值,单位是UGas,1 Gas = 10^8 UGas。
    master_weightint64目标账号的 master 权重,数值范围[0, MAX(UINT32)]。
    tx_thresholdint64发起交易的门限,低于该值,无法发起交易,数值范围[0, MAX(INT64)]。
  • 查询

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

创建合约账号

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

  • 关键字

    关键字类型描述
    payloadstring合约代码内容。
    init_balanceint64目标账户的初始化 Gas 值,单位是UGas,1 Gas = 10^8 UGas。
    init_inputstring可选,合约代码中init函数的入参。
    master_weightint64目标账号的 master 权重。
    tx_thresholdint64发起交易的门限,低于该值,无法发起交易。
  • 查询

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

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

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

发行资产

  • 功能

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

  • protobuf结构

    message OperationIssueAsset{
        string code = 1;
        int64 amount = 2;
    }
    
  • 关键字

    关键字类型描述
    codestring待发行资产的代码,长度范围[1, 64]
    amountint64待发行资产的数量,数值范围(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_addressstring目标账户地址。
    issuerstring资产发行方地址。
    codestring资产代码,长度范围[1, 64]。
    typeint32仅允许填0。
    amountint64资产数量,数值范围(0,MAX(int64))。
    inputstring可选,如果目标账户是合约账户,input会被传递给合约代码的main函数的参数。如果目标账户是普通账户,则该设置无效。

设置metadata

  • 功能

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

  • protobuf结构

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

    关键字类型描述
    keystringmetadata的关键字。长度范围(0, 1024]
    valuestringmetadata的内容。长度范围[0, 256K]
    versionint64可选,metadata版本号。默认值是0。0:不限制版本,>0 : 当前 value 的版本必须为该值, <0 : 非法
    delete_flagbool是否删除该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_weightstring可选,default "",表示该账号的 master 权重。 "" :不设置该值;"0": 设置 master 权重为 0;("0", "MAX(UINT32)"]:设置权重值为该值;其他:非法
    signersarray可选,需要操作的 signer 列表,default 为空对象。空对象不设置
    addressstring需要操作的 signer 地址,符合地址校验规则
    weightint64可选,default 0。0 :删除该 signer; (0, MAX(UINT32)]:设置权重值为该值,其他:非法
    tx_thresholdstring可选,default "",表示该账号的最低权限。"",不设置该值;"0": 设置 tx_threshold 权重为 0;("0", "MAX(INT64)"]:设置权重值为该值;其他:非法
    type_thresholdsarray可选,不同操作需要的权力值列表,default 为空对象。空对象不设置
    typeint表示某种类型的操作 (0, 100]
    thresholdint64可选,default 0。 0 :删除该类型操作;(0, MAX(INT64)]:设置权重值为该值;其他:非法

转移Gas资产

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

  • 功能

    有两个功能:

    1. 操作源账号将一笔Gas 资产转给目标账户。
    2. 操作源账号在区块链上创建一个新的账号。
  • protobuf结构

    message OperationPayCoin{
        string dest_address = 1;
        int64 amount = 2;
        string input = 3;
    }
    
  • protobuf关键字

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

记录日志

  • 功能

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

  • protobuf结构

    message OperationLog{
        string topic = 1;
        repeated string datas = 2;
    }
    
  • protobuf关键字

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

错误码

错误由两部分构成:

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

错误列表如下:

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