跳到主要内容

1.介绍

2.配置

config/bubi.json

{
    "wsserver": {
        "listen_address": "0.0.0.0:7053",
        "allow_orgin": ""
	}
}

3.请求数据

  • 请求消息
{
	"type":15,
    "request":true,
    "sequence":0,
    "data":"xxxx"  // 请求消息序列化的二进制格式
}
  • protobuf结构
message WsMessage {
	int64 type = 1; //1: ping
	bool request = 2; //true :request , false:reponse
	int64 sequence = 3;
	bytes data = 4;
}

enum ChainMessageType {
	CHAIN_TYPE_NONE = 0;
	CHAIN_HELLO = 10; // response with CHAIN_STATUS = 2;  
	CHAIN_PEER_MESSAGE = 14;
	CHAIN_SUBMITTRANSACTION = 15;
	CHAIN_SUBSCRIBE_TX = 19; //response with CHAIN_RESPONSE
}

4.接口

CHAIN_HELLO​

  • 功能描述

通过该接口获取区块链的版本信息。

  • 请求消息
{
	type:10,
    request:true,
    sequence:0
}
参数描述
type消息枚举值，CHAIN_HELLO。
requesttrue为请求消息，false为响应消息。
sequence消息序列号。
  • 响应消息
{
	type:10,
    request:false,
    sequence:1,
    data:"xxxx"
}
参数描述
type消息枚举值，CHAIN_HELLO。
requesttrue为请求消息，false为响应消息。
sequence消息序列号。
data响应内容序列化之后二进制表示。
  • 响应内容
{
    "self_addr": "adxSggi9WECzaaJNGtN1m6BAVP3P64DdCLCjs",
    "ledger_version": 4003,
    "monitor_version": 4000,
    "buchain_version": "4.0.24",
    "timestamp": 1711518920242729,
    "network_id": 8108773 
}
参数类型描述
self_addrstring连接的节点地址
ledger_versionint64区块版本号
monitor_versionint64监控程序版本号
bubichain_versionstringBubiChain程序版本号
timestampint64时间戳

protobuf结构：

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

CHAIN_PEER_MESSAGE​

  • 请求消息对象
message ChainPeerMessage {
	string src_peer_addr = 1; 
	repeated string des_peer_addrs = 2; 
	bytes	data = 3;		
}

提交交易​

  • 功能描述

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

  • 请求消息
{
	"type":15,
    "request":true,
    "sequence":0,
    "data":"xxxx"
}
参数描述
type请求消息类型，CHAIN_SUBMITTRANSACTION。
requesttrue为请求消息，false为响应消息。
sequence消息序列号。
data请求内容序列化之后二进制表示。

请求消息data内容：

{
	"transaction":{
        "source_address":"adxSp1X4V7hXDDRBKHL6U21CpbPhki7YqjuUd",
        "nonce":2,
        "fee_limit":10000000000,
        "gas_price":1000,
        "operations":[
        	{
                "type":7,
                "pay_coin":{
                    "dest_address":"adxSXmVaTseEx7yuGPufL5gYFf96WKtbMG2Eo",
                    "amount":10000000,
                    "input":""
                }
            }
        ]
    },
	"signatures":[
        {
        	"sign_data" : "b7d38afd04c8d25fafca05acb695937221261a62a1087dda495b980fe23131f2b71d5523254f256430b797bbc1ace430bd4ace5376d406fdf55ab7023ccb6f05",
            "public_key" : "b001ac76f97b0fda145c68e2edf6665c247a292260694b5dfcacac8acb658bd3746e7d8a3032"
        }
    ]
}
参数描述
transaction交易结构。
signatures交易签名，参考http API签名

protobuf结构：

message TransactionEnv {
	Transaction transaction = 1;
	repeated Signature signatures 	= 2;
	Trigger trigger = 3;
}

message Transaction {
	enum Limit{
		UNKNOWN = 0;
		OPERATIONS = 1000;
	};
	string source_address = 1;
	int64 nonce = 2;
	string expr_condition = 3;
	repeated Operation operations = 4;
	bytes metadata = 5;
	int64  fee_limit = 6;
	int64  gas_price =7;
	int64 ceil_ledger_seq = 8;
	int64 chain_id = 9;
	
	int32 address_crypto_type = 10; //1:ed25519, 2:sm2, 3:rsa, 4: cfca
	bytes raw_source_address = 11;
}

message Signature {
	string public_key = 1;
	bytes sign_data = 2;
}
  • 响应消息
{
	"type":11,
    "request":true,
    "sequence":1,
    "data":"xxxx"  
}
参数描述
type请求消息类型，CHAIN_TX_STATUS。
requesttrue为请求消息，false为响应消息。
sequence消息序列号。
data请求内容序列化之后二进制表示。

响应消息data内容：

CHAIN_TX_STATUS：提交交易结果（提交交易成功，并不表示交易执行成功）。

{
    status: CONFIRMED
    tx_hash: "c90de08ae656a2f19cce7798bc1f51d95d4c3b72e37fbd5f9d386d7a24617844"
    source_address: "adxSp1X4V7hXDDRBKHL6U21CpbPhki7YqjuUd"
    timestamp: 1711524589086325
}

protobuf结构：

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;          
}
变量类型描述
statusTxStatus交易状态。
tx_hashstring交易hash值。
source_addressstring交易发起源账户地址。
source_account_seqint64交易发起源账户的交易序号
ledger_seqint64这个交易记录所在的区块高度
new_account_seqint64当交易完成时的区块高度
error_codeERRORCODE错误码
error_descstring错误描述
timestampint64时间戮

CHAIN_TX_ENV_STORE：返回交易执行结果。

{
    transaction_env {
        transaction {
            source_address: "adxSp1X4V7hXDDRBKHL6U21CpbPhki7YqjuUd"
            nonce: 3
            operations {
                type: PAY_COIN
                pay_coin {
                    dest_address: "adxSg5szfwh7bLaF9MF2KiUD2XNGVdB8ybLz9"
                    amount: 10000000
                }
            }
            fee_limit: 1000000000
            gas_price: 1000
        }
        signatures[
            {
                public_key: "b001ac76f97b0fda145c68e2edf6665c247a292260694b5dfcacac8acb658bd3746e7d8a3032"
                sign_data: "\304p\310\237#pme\221Q\352e\202o\336*\215\360\030\372E\217\022\212\362Cx\001W\r\002\264\207\2153\345\300\244\327\262U\340}\023\\f\271\024\221\350\374\255\354\214\000L6L\2321/\027\247\005"
            },
            {
                public_key: "b00132c3d1244e0be4d711fb12d5b3d24abeb60f11e8c61c5efe28ad20b793d7fb2402f819e9"
                sign_data: "\b\257\032\254LU\301\264\255\317*\363\306\336e&wj\267\324\303\001P\236Q\203UYO\370T;\206\2006\305r\206/\323^\221>\234G\357\000\230D\315\343\033\203\263\300w\346x\311|\347e\267\001"
            }
        ] 
    }
    ledger_seq: 413
    close_time: 1711524591204288
    hash: "\311\r\340\212\346V\242\361\234\316w\230\274\037Q\331]L;r\343\177\275_\2358mz$axD"
    actual_fee: 396000

protobuf结构：

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;
}
变量类型描述
transaction_envTransactionEnv提交的交易内容
error_codeint32错误码
error_descstring错误描述
ledger_seqint64交易所在区块高度
close_timeint64交易执行完成时间
hashbytes交易hash
actual_feeint64实际交易费用，单位UGas
contract_tx_hashesbytes合约交易has

消息订阅​

  • 功能描述

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

  • 请求消息
{
	"type":19,
    "request":true,
    "sequence":0,
    "data":"xxxx"
}
参数描述
type请求消息类型，CHAIN_SUBSCRIBE_TX。
requesttrue为请求消息，false为响应消息。
sequence消息序列号。
data请求内容序列化之后二进制表示。
  • 请求内容
{
	address:"adxSp1X4V7hXDDRBKHL6U21CpbPhki7YqjuUd"
}

protobuf结构：

message ChainSubscribeTx{
    repeated string address = 1;
}
参数类型描述
addressTransaction要订阅的账户地址。
  • 响应消息

消息订阅结果：

{
	"type":19,
    "request":true,
    "sequence":1,
    "data":"xxxx"  
}
参数描述
type请求消息类型，CHAIN_SUBSCRIBE_TX。
requesttrue为请求消息，false为响应消息。
sequence消息序列号。
data消息订阅成功，data为空。订阅失败时返回错误信息。

订阅失败错误信息protobuf结构

message ChainResponse{
      int32 error_code = 1;
      string error_desc = 2;
}
参数描述
error_code错误码
error_desc错误描述
  • 节点发布订阅内容：

节点监测到订阅账户的交易时，发送TransactionEnvStore数据给客户端：

{
    transaction_env {
		actual_fee: 10000000000,
        close_time: 1711525922974654,
        error_code: 106,
        error_desc: "Account(adxShnhz4XLfLkzvUyza4mxCaw63eQUdBWdRc)'s init balance(1) is not enough for reserve(10000000)",
        hash: '4acfd12fbf1a83001a8b855a7b4edb9c51fddce2484e1ddc6ef1a3492a958c39',
        ledger_seq: 529,
        signatures: [
            {
                public_key: 'b001ac76f97b0fda145c68e2edf6665c247a292260694b5dfcacac8acb658bd3746e7d8a3032',
                sign_data: '650a5089bf26bada36f4cbf0d392d0f702fcf10198c7aae131f112a41581634af6171824f8aef0026b48f0571420fffc20b47741dea907c87cec0b32d309c707'
            },
            {
                public_key: 'b00132c3d1244e0be4d711fb12d5b3d24abeb60f11e8c61c5efe28ad20b793d7fb2402f819e9',
                sign_data: 'e18557d2aba99c4fa367aaeec7ceb11a42ff8fe8603c0bf767d1cd7a5e74ed2583f4a524d0cdeda83511a61db899b6f7887682aa5ec045a17fef6d24783c2e06'
            }
        ],
        transaction: {
            fee_limit: 10000000000,
            gas_price: 1000,
            nonce: 4,
            operations: [
                {
                    pay_coin: {
                  	    amount: 1,
                   	    dest_address: 'adxShnhz4XLfLkzvUyza4mxCaw63eQUdBWdRc'
                  	},
                	type: 7
           		}
            ],
            source_address: 'adxSp1X4V7hXDDRBKHL6U21CpbPhki7YqjuUd'
        },
    	tx_size: 39
	}
}