文档中心

文档中心

  • English

›API

介绍

  • 概述
  • 优势

节点部署

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

API

  • 概述
  • HTTP
  • Websocket
  • Keypair

SDK

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

场景示例

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

智能合约

  • 介绍
  • 语法说明

术语

  • 术语

BubiChain HTTP

试一试

如果您的区块链刚刚部署完成,那么目前区块链系统中只有创世账号。您可以通过http接口查询创世账号(以本地域名localhost和端口36002为例)

HTTP GET localhost:36002/getGenesisAccount 
或
curl get localhost:36002/getGenesisAccount

您会得到类似这样的返回内容:

{
  "error_code" : 0,
  "result" : {
    "address" : "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",
    "assets" : null,
    "balance" : 100000000000000000,
    "metadatas" : null,
    "priv" : {
      "master_weight" : 1,
      "thresholds" : {
        "tx_threshold" : 1
      }
    }
  }
}

返回结果中的address的值就是创世账号。 您还可以通过查询账号接口查询任意账号。

HTTP GET localhost:36002/getAccount?address=adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV
或
curl get localhost:36002/getAccount?address=adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV

HTTP接口

以下接口都以本地域名 localhost 和端口 36002 为例。

生成公私钥对-测试用

HTTP GET /createKeyPair
  • CURL命令

    curl get localhost:36002/createKeyPair
    
  • 功能

    注意:该接口只为方便测试使用,请勿在生产环境使用该接口(生产环境下请用SDK或者命令行生成),因为调用该接口后,如果节点服务器作恶会导致账户私钥泄露。该接口仅产生一个公私钥对,不会写入全网区块链。

  • 返回值

    {
      "error_code" : 0,
      "result" : {
        "address" : "adxSkMvC2RcvXLpDgXBJCSb4m9mPe8gpNDKAG",  //账户地址
        "private_key" : "privbzMRMFKoT8xPSPLqXoJb3GxgoULcR2go9WVNPG2N9e9oX251AgAU",  //账户私钥
        "private_key_aes" : "7594a97bc5e6432704cc5f58ff60727ee9bda10a6117915d025553afec7f81527cb857b882b7c775391fe1fe3f7f3ec198ea69ada138b19cbe169a1a3fa2dec8",  //AES加密账户私钥之后的数据
        "public_key" : "b00101da11713eaad86ad8ededfc28e86b8cd619ca2d593a21d8b82da34320a7e63b09c279bc", //账户公钥
        "public_key_raw" : "01da11713eaad86ad8ededfc28e86b8cd619ca2d593a21d8b82da34320a7e63b",  //公钥排除前缀和后缀后的数据
        "sign_type" : "ed25519"  //账户加密类型
      }
    }
    

查询账号

HTTP GET /getAccount?address=adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV&key=hello&code=xxx&issuer=xxx
  • CURL命令

    curl get localhost:36002/getAccount?address=adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV
    
  • 功能

    返回指定账号的信息及其所有资产和metadata。

  • 参数

    参数描述
    address账号地址, 必填
    key账号的 metadata 中指定的key的值,如果不填写,那么返回结果中含有所有的metadata
    code, issuer资产代码,资产发行商。这两个变量要么同时填写,要么同时不填写。若不填写,返回的结果中包含所有的资产。若填写,返回的结果中只显示由code和issuer
  • 返回值

    正常返回内容如下:

    {
    "error_code" : 0,//错误码,0表示成功
    "result" : {
      "address" : "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV", //该账号的地址
      "balance" : 300000000000,//Gas 余额,单位UGas
      "nonce" : 1, //账号当前作为交易源执行过的交易数量。若nonce为0,该字段不显示
      "assets" : [//资产列表
        {
          "amount" : 1400,//资产数量
          "key" ://资产关键字
          {
            "code" : "CNY",//资产编码
            "issuer" : "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV" //资产发行方账户地址
          }
        }, {
          "amount" : 1000,
          "key" :
          {
            "code" : "USD",
            "issuer" : "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV"
          }
        }
      ],
      "assets_hash" : "9696b03e4c3169380882e0217a986717adfc5877b495068152e6aa25370ecf4a",//资产列表生成的hash值
      "contract" : null,//合约,空表示当前不是合约账户
      "metadatas" : [//metadata列表
        {
          "key" : "123",//metadata的关键字
          "value" : "123_value",//metadata的内容
          "version" : 1 // metadata的版本号
        }, {
          "key" : "456",
          "value" : "456_value",
          "version" : 1
        }, {
          "key" : "abcd",
          "value" : "abcd_value",
          "version" : 1
        }
      ],
      "metadatas_hash" : "82c8407cc7cd77897be3100c47ed9d43ec4097ee1c00e2c13447187e5b1ac66c",//matadata列表生成的hash值
      "priv" : {//账户权限
        "master_weight" : 1,//账户自身权力值
        "thresholds" : {
          "tx_threshold" : 1//发起交易需要的权力值
        }
      }
    }
    }
    

    如果该账号不存在,则返回内容如下:

    {
    "error_code" : 4,//错误码,4表示账户不存在
    "result" : null
    }
    

查询账号基本信息

HTTP GET /getAccountBase?address=adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV
  • CURL命令

    curl get localhost:36002/getAccountBase?address=adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV
    
  • 功能

    返回指定账号的基本信息,不包括资产和metadata。

  • 参数

    参数描述
    address账号地址, 必填
  • 返回值

    正常返回内容如下:

    {
    "error_code" : 0,//错误码,0表示成功
    "result" : {
      "address" : "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV", //该账号的地址
      "assets_hash" : "9696b03e4c3169380882e0217a986717adfc5877b495068152e6aa25370ecf4a",//资产列表生成的hash值
      "balance" : 899671600,//Gas 余额,单位UGas
      "contract" : null,//合约,空表示当前不是合约账户
      "nonce" : 1, //账号当前作为交易源执行过的交易数量。若nonce为0,该字段不显示
      "priv" : {//账户权限
        "master_weight" : 1,//账户自身权力值
        "thresholds" : {
          "tx_threshold" : 1 //发起交易需要的权力值
        }
      },
      "metadatas_hash" : "82c8407cc7cd77897be3100c47ed9d43ec4097ee1c00e2c13447187e5b1ac66c" // matadata列表生成的hash值
    }
    }
    

    如果该账号不存在,则返回内容如下:

    {
    "error_code" : 4,//错误码,4表示账户不存在
    "result" : null
    }
    

查询资产

HTTP GET /getAccountAssets?address=adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV
  • CURL命令

    curl get localhost:36002/getAccountAssets?address=adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV
    
  • 功能

    返回指定账号的资产信息。

  • 参数

    参数描述
    address账号地址, 必填。
    code, issuerissuer表示资产发行账户地址,code表示资产代码。只有同时填写正确code&issuer才能正确显示指定资产否则默认显示所有资产
  • 返回值

    正常返回内容如下:

    {
    "error_code" : 0,//错误码,0表示账户存在
    "result": [//result不为null,表示资产存在
      {
        "amount" : 1400,//拥有的资产数量
        "key" ://资产标识,包括资产code和issuer
        {
          "code" : "EES",//资产代码
          "issuer" : "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV" //资产发行人账户地址
        }
      },
      {
        "amount" : 1000,
        "key" :
        {
          "code" : "OES",
          "issuer" : "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV"
        }
      }
    ]
    }
    

    如果该账号不存在资产,则返回内容如下:

    {
    "error_code" : 0,//错误码,0表示账户存在
    "result" : null //result为null,表示资产不存在
    }
    

查询metadata

HTTP GET /getAccountMetaData?address=adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV
  • CURL命令

    curl get localhost:36002/getAccountMetaData?address=adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV
    
  • 功能

    返回指定账号的MetaData信息。

  • 参数

    参数描述
    address账号地址, 必填
    key指定metadata中的key值, 选填
  • 返回值

    正常返回内容如下:

    {
    "error_code" : 0,//错误码,0表示账户存在
    "result": {//result不为null,表示metadata存在
      "123": {
        "key" : "123",
        "value" : "123_value",
        "version" : 1
      },
      "456": {
        "key" : "456",
        "value" : "456_value",
        "version" : 1
      },
      "abcd": {
        "key" : "abcd",
        "value" : "abcd_value",
        "version" : 1
      }
    }
    }
    

    如果该账号不存在metadata,则返回内容:

    {
    "error_code" : 0,//错误码,0表示账户存在
    "result" : null //result为null,表示metadata不存在
    }
    

查询交易

HTTP GET /getTransactionHistory?ledger_seq=6
  • CURL命令

    curl get localhost:36002/getTransactionHistory?ledger_seq=6
    
  • 功能

    返回已完成的交易记录。

  • 参数

    参数描述
    hash用交易的唯一标识hash查询
    ledger_seq查询指定区块中的所有交易

    注意:上述两个参数产生的约束条件是逻辑与的关系,如果您同时指定两个参数,系统将在指定的区块中查询指定的交易

  • 返回值

    正常返回内容如下:

    注意:下面包含2个交易,且第2个交易是创建合约账户的交易error_desc字段内容尤需注意。

    {
        "error_code": 0,//查询错误码,0表示交易存在
        "result": {
            "total_count": 2,//查询到的交易数量
            "transactions": [{//交易列表
                "actual_fee": 313000,//交易实际花费的费用
                "close_time": 1524031260097214,//交易执行完成的时间
                "error_code": 0,//交易的错误码,0表示交易执行成功,非0表示交易执行失败
                "error_desc": "",//交易的错误描述
                "hash": "89a9d6e5d2c0e2b5c4fe58045ab2236d12e9449ef232342a48a2e2628e12014d",//交易的hash值
                "ledger_seq": 6,//交易所在的区块高度
                "signatures": [{//签名列表
                    "public_key": "b00180c2007082d1e2519a0f2d08fd65ba607fe3b8be646192a2f18a5fa0bee8f7a810d011ed",//公钥
                    "sign_data": "27866d70a58fc527b1ff1b4a693b8034b0078fc7ac7591fb05679abe5ca660db5c372922bfa8f26e76511e2c33386306ded7593874a6aec5baeeaddbd2012f06"//签名数据
                }],
                "transaction": {//交易内容
                    "fee_limit": 10000000000,//本交易提交的最大的手续费,单位UGas
                    "gas_price": 1000,//gas的价格,单位UGas
                    "nonce": 1,//交易所在账户的序号
                    "operations": [{//操作列表
                        "create_account": {//创建账户操作
                            "dest_address": "adxSrDYeqnCeyDFNJQDdMJok3PB1jAhmctaWY",//目标账户地址
                            "init_balance": 10000000,//目标账户初始化 Gas 数量,单位UGas
                            "priv": {//目标账户的权限
                                "master_weight": 1,//目标账户的自身权力值
                                "thresholds": {
                                    "tx_threshold": 1 //发起目标账户的交易需要的权力值
                                }
                            }
                        },
                        "type": 1 //执行的操作类型,1表示创建账户操作
                    },
                    {
                        "create_account": {
                            "dest_address": "adxSVVQUx2GJSb1sfoWDMmHNpms4fuuA5s2WW",
                            "init_balance": 10000000,
                            "priv": {
                                "master_weight": 1,
                                "thresholds": {
                                    "tx_threshold": 1
                                }
                            }
                        },
                        "type": 1
                    }],
                    "source_address": "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV" //交易发起账户地址
                },
                "tx_size": 313 //交易字节数
            },
            {
                "actual_fee": 1000402000,//交易实际花费的费用
                "close_time": 1524031260097214,//交易执行完成的时间
                "error_code": 0,//交易的错误码,0表示交易执行成功,非0表示交易执行失败
                "error_desc": "[{\"contract_address\":\"adxSpuMcbgPuNALPdRMJEQZhrMfA5u9ycUZCo\",\"operation_index\":0}]", //创建合约结果,包括合约地址和操作索引值
                "hash": "4cbf50e03645f1075d7e5c450ced93e26e3153cf7b88ea8003b2fda39e618e64",//交易的hash值
                "ledger_seq": 6,//交易所在的区块高度
                "signatures": [{//签名列表
                    "public_key": "b00180c2007082d1e2519a0f2d08fd65ba607fe3b8be646192a2f18a5fa0bee8f7a810d011ed",//公钥
                    "sign_data": "87fdcad0d706479e1a3f75fac2238763cd15fd93f81f1b8889fb798cefbe1752c192bbd3b5da6ebdb31ae47d8b62bb1166dcceca8d96020708f3ac5434838604" //签名数据
                }],
                "transaction": {//交易内容
                    "fee_limit": 20004420000,//本交易提交的最大的手续费
                    "gas_price": 1000,//gas的价格
                    "nonce": 30,//交易所在账户的序号
                    "operations": [{//操作列表
                        "create_account": {//创建账户操作
                            "contract": {//合约
                                "payload": "'use strict';\n\t\t\t\t\tfunction init(bar)\n\t\t\t\t\t{\n\t\t\t\t\t  return;\n\t\t\t\t\t}\n\t\t\t\t\t\n\t\t\t\t\tfunction main(input)\n\t\t\t\t\t{\n\t\t\t\t\t  return;\n\t\t\t\t\t}\n\t\t     function query()\n\t\t\t\t\t{\n\t\t\t\t\t  return;\n\t\t\t\t\t}\n\t\t      \n\t\t          " //合约代码
                            },
                            "init_balance": 10000000,//合约账户的初始化 Gas 数量,单位UGas
                            "priv": {//合约账户的权限
                                "thresholds": {
                                    "tx_threshold": 1 //发起合约账户的交易需要的权力值
                                }
                            }
                        },
                        "type": 1 //执行的操作类型,1表示创建账户操作
                    }],
                    "source_address": "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV" //交易发起账户地址
                },
                "tx_size": 402 //交易字节数
            }]
        }
    }
    

    如果没有查到交易则返回内容如下:

    {
    "error_code": 4,//查询错误码,4表示无交易
    "result":
    {
      "total_count": 0,//查询到的交易数量
      "transactions": []
    }
    }
    

查询缓存队列交易

HTTP GET /getTransactionCache?hash=ad545bfc26c440e324076fbbe1d8affbd8a2277858dc35927d425d0fe644e698&limit=100
  • CURL命令

    curl get localhost:36002/getTransactionCache?hash=ad545bfc26c440e324076fbbe1d8affbd8a2277858dc35927d425d0fe644e698&limit=100
    
  • 功能

    返回提交成功的,但还未执行的交易。

  • 参数

    参数描述
    hash用交易的唯一标识hash查询
    limit查询交易队列前N个正在处理的交易

    注意:上述两个参数产生的约束条件是逻辑或的关系,如果您同时指定两个参数,系统将hash查询

  • 返回值

    正常返回内容如下:

    {
    "error_code": 0,//查询错误码,0表示查询成功
    "result": {
      "total_count": 1,//交易总数量
      "transactions": [//交易列表
        {
          "hash": "a336c8f4b49c8b2c5a6c68543368ed3b450b6138a9f878892cf982ffb6fe234e",//交易hash值
          "incoming_time": 1521013029435154,//交易进入缓存队列的时间
          "signatures": [//签名列表
            {
              "public_key": "b001882b9d1b5e7019f163d001c85194cface61e294483710f5e66ef40a4d387f5fcb0166f4f",//公钥
              "sign_data": "c5885144ffccb0b434b494271258e846c30a4551036e483822ee2b57400576e9e700e8960eb424764d033a2e73af6e6a2bfa5da390f71161732e13beee206107" //签名数据
            }
          ],
          "status": "processing",//交易状态
          "transaction": {//交易内容
            "fee_limit": 100000,//本交易提交的最大的手续费,单位UGas
            "gas_price": 1000,//gas的价格,单位UGas
            "nonce": 2,//交易所在账户的序号
            "operations": [//操作列表
              {
                "create_account": {//创建账户操作
                  "dest_address": "adxSnVDvg3gfW8as4BeodEJDDQAMXu9NobyvN",//目标账户地址
                  "init_balance": 300000,//目标账户初始化 Gas 数量,单位UGas
                  "priv": {//目标账户权限
                    "master_weight": 1,//目标账户自身的权力值
                    "thresholds": {
                      "tx_threshold": 2 //发起目标账户交易所需要的权力值
                    }
                  }
                },
                "type": 1 //执行的操作类型,1表示创建账户操作
              }
            ],
            "source_address": "adxSkScnQJ1ciM1C9rBVw6DbtogbAcWFuXRhC"// 交易发起账户地址
          }
        }
      ]
    }
    }
    

    如果没有查到交易则返回内容如下:

    {
    "error_code": 4,//查询错误码,4表示未查询到交易
    "result":
    {
      "total_count": 0,//查询到的交易数量
      "transactions": []
    }
    }
    

查询区块头

HTTP GET /getLedger?seq=xxxx&with_validator=true&with_consvalue=true&with_fee=true
  • CURL命令

    curl get localhost:36002/getLedger?seq=6&with_validator=true&with_consvalue=true&with_fee=true
    
  • 功能

    返回区块头信息。

  • 参数

    参数描述
    seqledger的序号, 如果不填写,返回当前ledger
    with_validator默认false,不显示验证节点列表
    with_consvalue默认false,不显示共识值
    with_fee默认false,不显示费用配置
  • 返回值

    正常返回内容如下:

    {
    "error_code" : 0,//错误码,0表示成功
    "result" : {
      "block_reward" : 800000000,//区块奖励,单位UGas
      "consensus_value" : {//共识内容
        "close_time" : 1524031260097214,//共识结束时间
        "ledger_seq" : 6,//区块高度
        "previous_ledger_hash" : "ef329c7ed761e3065ab08f9e7672fd5f4e3ddd77b0be35598979aff8c21ada9b",//前一个区块hash
        "previous_proof" : "0ac1010a2c080110022a26080310052220432dde2fd32a2a66da77647231821c87958f56c303bd08003633952d384eb0b61290010a4c623030316435363833363735303137666662633332366538666232303738653532316566383435373234363236353339356536383934633835323434656566643262666130386635393862661240deeb9b782410f0f86d897006cac8ad152e56e4f914e5d718706de84044ef98baef25512a337865772641d57090b5c77e9e2149dbd41910e8d6cd85c3387ea708",//前一个区块凭证
        "previous_proof_plain" : {//前区块凭证的内容
          "commits" : [
            {
              "pbft" : {
                "commit" : {
                  "sequence" : 5,//区块序号
                  "value_digest" : "432dde2fd32a2a66da77647231821c87958f56c303bd08003633952d384eb0b6",//内容摘要
                  "view_number" : 3 //视图编号
                },
                "round_number" : 1,
                "type" : 2 //类型
              },
              "signature" : {//节点签名信息
                "public_key" : "b001d5683675017ffbc326e8fb2078e521ef8457246265395e6894c85244eefd2bfa08f598bf",//公钥
                "sign_data" : "deeb9b782410f0f86d897006cac8ad152e56e4f914e5d718706de84044ef98baef25512a337865772641d57090b5c77e9e2149dbd41910e8d6cd85c3387ea708" //签名数据
              }
            }
          ]
        },
        "txset" : {//交易集
          "txs" : [//交易列表
            {
              "signatures" : [//签名列表
                {
                  "public_key" : "b00180c2007082d1e2519a0f2d08fd65ba607fe3b8be646192a2f18a5fa0bee8f7a810d011ed",//公钥
                  "sign_data" : "27866d70a58fc527b1ff1b4a693b8034b0078fc7ac7591fb05679abe5ca660db5c372922bfa8f26e76511e2c33386306ded7593874a6aec5baeeaddbd2012f06" //签名数据
                }
              ],
              "transaction" : {//交易内容
                "fee_limit" : 10000000000,//本交易提交的最大的手续费,单位UGas
                "gas_price" : 1000,//gas的价格,单位UGas
                "nonce" : 1,//交易所在账户的序号
                "operations" : [//操作列表
                  {
                    "create_account" : {//创建账户操作
                      "dest_address" : "adxSrDYeqnCeyDFNJQDdMJok3PB1jAhmctaWY",//目标账户
                      "init_balance" : 10000000,//目标账户初始化 Gas 数量,单位UGas
                      "priv" : {//目标账户权限
                        "master_weight" : 1,//目标账户自身拥有的权力值
                        "thresholds" : {
                          "tx_threshold" : 1 //发起目标账户交易所需要的权力值
                        }
                      }
                    },
                    "type" : 1 //执行的操作类型,1是指创建账户操作
                  },
                  {
                    "create_account" : {
                      "dest_address" : "adxSVVQUx2GJSb1sfoWDMmHNpms4fuuA5s2WW",
                      "init_balance" : 10000000,
                      "priv" : {
                        "master_weight" : 1,
                        "thresholds" : {
                          "tx_threshold" : 1
                        }
                      }
                    },
                    "type" : 1
                  }
                ],
                "source_address" : "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV"
              }
            },
            {
              "signatures" : [
                {
                  "public_key" : "b00180c2007082d1e2519a0f2d08fd65ba607fe3b8be646192a2f18a5fa0bee8f7a810d011ed",
                  "sign_data" : "fb7d9d87f4c9140b6e19a199091c6871e2380ad8e8a8fcada9b42a2911057111dc796d731f3f887e600aa89cc8692300f980723298a93b91db711155670d3e0d"
                }
              ],
              "transaction" : {
                "fee_limit" : 10000000000,
                "gas_price" : 1000,
                "nonce" : 2,
                "operations" : [
                  {
                    "create_account" : {
                      "dest_address" : "adxSrbWSdMvysHtKQqpJzKAduQmDFHa1VHhRN",
                      "init_balance" : 10000000,
                      "priv" : {
                        "master_weight" : 1,
                        "thresholds" : {
                          "tx_threshold" : 1
                        }
                      }
                    },
                    "type" : 1
                  },
                  {
                    "create_account" : {
                      "dest_address" : "adxSWwQmECKbyTTyx8RGVbaTapPqpHSPeskJy",
                      "init_balance" : 10000000,
                      "priv" : {
                        "master_weight" : 1,
                        "thresholds" : {
                          "tx_threshold" : 1
                        }
                      }
                    },
                    "type" : 1
                  }
                ],
                "source_address" : "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV"
              }
            }
          ]
        }
      },
      "fees" : {//区块费用标准
        "base_reserve" : 10000000,//账户最低账户 Gas 数量,单位UGas
        "gas_price" : 1000 //gas的价格,单位UGas
      },
      "header" : {//区块头
        "account_tree_hash" : "6aca37dfe83f213942b21d02618b989619cfd7c0e67a8a14b0f7599dd4010aad",//账户树hash值
        "close_time" : 1524031260097214,//区块关闭时间
        "consensus_value_hash" : "14a65d69f619395135da2ff98281d5707494801f12184a4318b9a76383e651a8",//共识内容hash值
        "fees_hash" : "916daa78d264b3e2d9cff8aac84c943a834f49a62b7354d4fa228dab65515313",//费用标准hash值
        "hash" : "2cf378b326ab0026625c8d036813aef89a0b383e75055b80cb7cc25a657a9c5d",//区块hash值
        "previous_hash" : "ef329c7ed761e3065ab08f9e7672fd5f4e3ddd77b0be35598979aff8c21ada9b",//前一个区块hash值
        "seq" : 6,//区块高度
        "tx_count" : 2,//交易总数量
        "validators_hash" : "d857aa40ecdb123415f893159321eb223e4dbc11863daef86f35565dd1633316",//验证节点列表hash值
        "version" : 1000 //区块版本号
      },
      "validators" : [//验证节点列表
          "adxSVW6zpibJ3amyauqk6339jjAgaL5LU9yAt" //验证节点地址
      ]
    }
    }
    

    如果没有查询到ledger返回的内容:

    {
    "error_code" : 4,
    "result" : null
    

} ```

批量查询

HTTP POST /multiQuery
  • CURL命令

    curl localhost:26002/multiQuery -X POST -d "{\"items\":[{\"url\":\"getAccount?address=adxSgJCoz19wLJ4KbFjb3KDFs96xeW966iYgD\",\"method\":\"GET\",\"jsonData\":\"\"},{\"url\":\"hello\",\"method\":\"GET\",\"jsonData\":\"\"}]}"
    
  • 功能

    根据查询列表,返回多个查询结果。

  • body的json结构

    这里body传递就是查询列表。如下:

    {
      "items":
      [
          {
          "url":"getAccount?address=adxSgJCoz19wLJ4KbFjb3KDFs96xeW966iYgD", // 查询命令
          "method": "GET", // GET or POST 查询
          "jsonData":"" // 若是 POST 查询,这里是 body 的内容
          },
          {
          "url":"hello", // 查询命令
          "method": "GET", // GET or POST 查询
          "jsonData":"" // 若是 POST 查询,这里是 body 的内容
          }
      ]
    }
    
  • 返回值

    {
        "error_code": 0, // 查询错误码
        "results": [
            {
                "error_code": 0, // getAccount 查询错误码
                "result": { // getAccount 查询结果
                    "address": "adxSgJCoz19wLJ4KbFjb3KDFs96xeW966iYgD",
                    "assets": null,
                    "assets_hash": "ad67d57ae19de8068dbcd47282146bd553fe9f684c57c8c114453863ee41abc3",
                    "balance": 99989879492755000,
                    "metadatas": null,
                    "metadatas_hash": "ad67d57ae19de8068dbcd47282146bd553fe9f684c57c8c114453863ee41abc3",
                    "nonce": 10,
                    "priv": {
                        "master_weight": 1,
                        "thresholds": {
                            "tx_threshold": 1
                        }
                    }
                }
            },
            { // hello 查询结果
                "bubi_version": "4.0.0",
                "current_time": "2020-02-28 17:33:37.282237",
                "hash_type": 0,
                "ledger_version": "4000",
                "license_version": "1.0.0",
                "monitor_version": "4000",
                "network_id": 30000,
                "overlay_version": "2000",
                "websocket_address": 36003
            }
        ]
    }
    

序列化交易

HTTP POST /getTransactionBlob
  • CURL命令

    curl localhost:26002/getTransactionBlob -X POST -d "{\"source_address\":\"adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV\",\"nonce\":1,\"fee_limit\":100000,\"gas_price\":1000,\"operations\":[{\"type\":1,\"create_account\":{\"dest_address\":\"adxSX1SypC33doY4a5MYYr5zBZUvB33kKHdAo\",\"metadatas\":[{\"key\":\"hello\",\"value\":\"这是创建账号的过程中设置的一个metadata\"}],\"priv\":{\"thresholds\":{\"tx_threshold\":1}},\"contract\":{\"payload\":\"function main(inputStr){\n /*这是合约入口函数*/ }\"}}}]}"
    
  • 功能

    返回交易hash和交易序列化之后的16进制字符串。

  • body 的 json 结构

    这里 body 传递就是交易数据,具体 json 结构及参数请看交易结构。如下:

    {
      "source_address": "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",
      "nonce": 1,
      "fee_limit": 100000,
      "gas_price": 1000,
      "operations": [{
        "type": 1,
        "create_account": {
          "dest_address": "adxSX1SypC33doY4a5MYYr5zBZUvB33kKHdAo",
          "metadatas": [{
            "key": "hello",
            "value": "这是创建账号的过程中设置的一个metadata"
          }],
          "priv": {
            "thresholds": {
              "tx_threshold": 1
            }
          },
          "contract": {
            "payload": "function main(inputStr){\n /*这是合约入口函数*/ }"
          }
        }
      }]
    }
    
  • 返回值

    {
      "error_code": 0,//序列化交易错误码
      "error_desc": "",//错误描述
      "result": {
        "hash": "7ea4b61b86c5e2248e1ec24a8c04568e6b17c7121fb86f648b42b73bd3bada5d",//交易的hash
        "transaction_blob": "0a2462755173396e70614371396d4e465a473138717538385a636d5859716436627170545533100118a08d0620e8073aad01080122a8010a24627551747336446654354b6176745639344a675a79373548397069776d62374b6f555767123a123866756e6374696f6e206d61696e28696e707574537472297b0a202f2ae8bf99e698afe59088e7baa6e585a5e58fa3e587bde695b02a2f207d1a041a020801223e0a0568656c6c6f1235e8bf99e698afe5889be5bbbae8b4a6e58fb7e79a84e8bf87e7a88be4b8ade8aebee7bdaee79a84e4b880e4b8aa6d65746164617461" //交易序列化之后的16进制表示
      }
    }
    

提交交易

HTTP POST /submitTransaction
  • CURL命令

    curl localhost:36002/submitTransaction -X POST -d "{\"items\":[{\"transaction_blob\":\"0a2e61303032643833343562383964633334613537353734656234393736333566663132356133373939666537376236100122b90108012ab4010a2e61303032663836366337663431356537313934613932363131386363353565346365393939656232396231363461123a123866756e6374696f6e206d61696e28696e707574537472297b0a202f2ae8bf99e698afe59088e7baa6e585a5e58fa3e587bde695b02a2f207d1a06080a1a020807223e0a0568656c6c6f1235e8bf99e698afe5889be5bbbae8b4a6e58fb7e79a84e8bf87e7a88be4b8ade8aebee7bdaee79a84e4b880e4b8aa6d65746164617461\",\"signatures\":[{\"sign_data\":\"2f6612eaefbdadbe792201bb5d1e178aff118dfa0a640edb2a8ee91933efb97c4fb7f97be75195e529609a4de9b890b743124970d6bd7072b7029cfe7683ba2d\",\"public_key\":\"b00204e1c7dddc36d3153adcaa451b0ab525d3def48a0a10fdb492dc3a7263cfb88e80ee974ca4da0e1f322aa84ff9d11340c764ea756ad148e979c121619e9fe52e9054\"},{\"sign_data\":\"90C1CD2CD371F581EB8GasCDA295C390D62C19FE7F080FB981584FB5F0BAB3E293B613C827CB1B2E063E5783FFD7425E1DEC0E70F17C1227FBA5997A72865A30A\",\"public_key\":\"b00168eceea7900ddcb8f694161755f98590ba7944de3bfe339610fe0cacc10a18372dcbf71b\"}]}]}"
    
  • 功能

    将序列化的交易和签名列表发送到区块链。

  • body的json结构

    {
      "items" : [{//交易包列表
        "transaction_blob" : "0a2e61303032643833343562383964633334613537353734656234393736333566663132356133373939666537376236100122b90108012ab4010a2e61303032663836366337663431356537313934613932363131386363353565346365393939656232396231363461123a123866756e6374696f6e206d61696e28696e707574537472297b0a202f2ae8bf99e698afe59088e7baa6e585a5e58fa3e587bde695b02a2f207d1a06080a1a020807223e0a0568656c6c6f1235e8bf99e698afe5889be5bbbae8b4a6e58fb7e79a84e8bf87e7a88be4b8ade8aebee7bdaee79a84e4b880e4b8aa6d65746164617461",//一个交易序列化之后的16进制表示
        "signatures" : [{//第一个签名
          "sign_data" : "2f6612eaefbdadbe792201bb5d1e178aff118dfa0a640edb2a8ee91933efb97c4fb7f97be75195e529609a4de9b890b743124970d6bd7072b7029cfe7683ba2d",//签名数据
          "public_key" : "b00204e1c7dddc36d3153adcaa451b0ab525d3def48a0a10fdb492dc3a7263cfb88e80ee974ca4da0e1f322aa84ff9d11340c764ea756ad148e979c121619e9fe52e9054"//公钥
        }, {//第二个签名
          "sign_data" : "90C1CD2CD371F581EB8GasCDA295C390D62C19FE7F080FB981584FB5F0BAB3E293B613C827CB1B2E063E5783FFD7425E1DEC0E70F17C1227FBA5997A72865A30A",//签名数据
          "public_key" : "b00168eceea7900ddcb8f694161755f98590ba7944de3bfe339610fe0cacc10a18372dcbf71b"//公钥
        }
                       ]
      }
                ]
    }
    
  • json的关键字

    参数类型描述
    transaction_blobstring交易序列化之后的16进制格式
    sign_datastring签名数据, 16进制格式。其值为对transaction_blob进行签名(动词)得到的签名数据。注意:签名时要先将transaction_blob转成字节流再签名,不要对16进制字符串直接签
    public_keystring公钥, 16进制格式
  • 返回值

    注意:提交交易成功,并不表示交易执行成功。

    {
    "error_code": 0,//提交结果
    "error_desc": "",//错误描述
    "result": {
      "hash": "8e97ab885685d68b8fa8c7682f77ce17a85f1b4f6c8438eda8ec955890919405",//交易的hash
    }
    }
    

调用合约

HTTP POST /callContract
  • CURL命令

    curl localhost:36002/callContract -X POST -d "{\"contract_address\":\"\",\"code\":\"\\\"use strict\\\";log(undefined);function query() { return 1; }\",\"input\":\"{}\",\"contract_balance\":\"100009000000\",\"fee_limit\":100000000000000000,\"gas_price\":1000,\"opt_type\":2,\"source_address\":\"\"}"
    
  • 功能

    在智能合约模块的设计中,我们提供了沙箱环境来进行调试合约,且调试过程中不会更改区块链和合约的状态。在 BubiChain 链上,我们为用户提供了 callContract 接口来帮助用户来调试智能合约,智能合约可以是公链上已存的,也可以是通过参数上传本地的合约代码进行测试,使用 callContract 接口不会发送交易,也就无需支付上链手续费。

  • body的json结构

    {
      "contract_address" : "",//可选,智能合约地址
      "code" : "\"use strict\";log(undefined);function query() { return 1; }",//可选,智能合约代码
      "input" : "{}",//可选,给被调用的合约传参
      "contract_balance" : "100009000000",//赋予合约的初始 Gas 余额
      "fee_limit" : 100000000000000000,//手续费
      "gas_price": 1000,//可选,gas的价格
      "opt_type" : 2,//可选,操作类型
      "source_address" : "" //可选,模拟调用合约的原地址
    }
    
  • json关键字

    关键字类型描述
    contract_addressstring调用的智能合约地址,如果从数据库查询不到则返回错误。如果填空,则默认读取 code 字段的内容
    codestring需要调试的合约代码,如果 contract_address 为空,则使用 code 字段,如果code字段你也为空,则返回错误
    inputstring给被调用的合约传参
    contract_balancestring赋予合约的初始 Gas 余额
    fee_limitint64手续费
    gas_priceint64gas价格
    opt_typeint0: 调用合约的读写接口 init, 1: 调用合约的读写接口 main, 2 :调用只读接口 query
    source_addressstring模拟调用合约的原地址
  • 返回值

    {
      "error_code" : 0,//调用结果,0表示成功
      "error_desc" : "",//错误码描述
      "result" : {
        "logs" : {
          "0-adxSWaq8TmFVyyHKXsYwb9FTaGEx77EWW2hne" : null //已无用
        },
        "query_rets" : [
          {
            "result" : {
              "type" : "bool", // 返回变量的名称
              "value" : false  // 变量值是false
            }
          }
        ],
        "stat" : {
          "apply_time" : 6315,//执行花费的时间
          "memory_usage" : 886176,//内存占用
          "stack_usage": 2564,//堆栈战胜
          "step" : 3 //执行的频数
        },
        "txs" : null //交易集
      }
    }
    

评估费用

HTTP POST /testTransaction
  • CURL命令

    curl localhost:36002/testTransaction -X POST -d "{\"contract_address\":\"\",\"code\":\"\\\"use strict\\\";log(undefined);function query() { return 1; }\",\"input\":\"{}\",\"contract_balance\":\"100009000000\",\"fee_limit\":100000000000000000,\"gas_price\":1000,\"opt_type\":2,\"source_address\":\"\"}"
    
  • 功能

    评估费用不改变账号余额基础上进行的评估,交易中涉及的原账号和目标账号都必须在系统中存在,创建账号的目标地址除外。

  • body的json结构

    {
      "items": [
        {
          "transaction_json": {
            "fee_limit": 99999999700110000,
            "gas_price": 1,
            "nonce": 1,
            "operations": [
              {
                "pay_coin": {
                  "amount": 299890000,
                  "dest_address": "adxSdCZ13uZUWKv7AdhRcED6a9g7RjxpfKC1D"
                },
                "type": 7
              }
            ],
            "source_address": "adxSkScnQJ1ciM1C9rBVw6DbtogbAcWFuXRhC"
          },
          "signature_number":1
        }
      ]
    }
    
  • json关键字

    关键字类型描述
    source_addressstring模拟交易的原地址
    nonceint64在原账号基础上加1
    signature_numberint64签名个数,默认为1;不填写系统会设置为1
    metadatastring可选,签名个数
    operationsarray操作列表。本交易的有效负载,即本交易想要做什么事情 (详见:操作结构)
  • 返回值

    {
      "error_code": 0,
      "error_desc": "",
      "result": {
        "hash": "7f0d9de23d6d8f2964a1efe4a458e02e43e47f60f3c22bb132b676c54a44ba04",
        "logs": null,
        "query_rets": null,
        "stat": null,
        "txs": [
          {
            "actual_fee": 264,
            "gas": 264,
            "transaction_env": {
              "transaction": {
                "fee_limit": 99999999700110000,
                "gas_price": 1,
                "nonce": 1,
                "operations": [
                  {
                    "pay_coin": {
                      "amount": 299890000,
                      "dest_address": "adxSdCZ13uZUWKv7AdhRcED6a9g7RjxpfKC1D"
                    },
                    "type": 7
                  }
                ],
                "source_address": "adxSkScnQJ1ciM1C9rBVw6DbtogbAcWFuXRhC"
              }
            }
          }
        ]
      }
    }
    

交易结构

  • json 格式

    {
      "source_address":"adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//交易源账号,即交易的发起方
      "nonce":2, //交易源账户的nonce值
      "fee_limit" : 1000000, //愿为交易花费的手续费
      "gas_price": 1000,//gas价格(不小于配置的最低值)
      "ceil_ledger_seq": 100, //可选,区块高度限制, 如果大于0,则交易只有在该区块高度之前(包括该高度)才有效
      "metadata":"0123456789abcdef", //可选,用户自定义给交易的备注,16进制格式
      "operations":[
        {
          //根据不同的操作填写
        },
        {
          //根据不同的操作填写
        }
        ......
      ]
    }
    
  • json 的关键字

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

操作结构

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

  • json 格式

    {
        "type": 1,//操作类型
        "source_address": "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//可选,操作源账户,即操作的执行方
        "metadata": "0123456789abcdef",//可选,用户自定义给交易的备注,16进制格式
        "create_account": {
            //创建账户的相关参数
        },
        "issue_asset": {
            //发行资产的相关参数
        },
        "pay_asset": {
            //转移资产的相关参数
        },
        "set_metadata": {
            //设置账户metadata的相关参数
        },
        "pay_coin": {
            //转移燃料(这里指Gas)的相关参数
        },
        "set_privilege": {
            //设置账户权限的相关参数 
        },
        "log": {
            //记录日志的相关参数
        }
    }
    
  • json 的关键字

    关键字类型描述
    typeint操作码,不同的操作码执行不同的操作,详见操作码
    source_addressstring可选,操作源账户,即操作的执行方。当不填写时,默认与交易的源账户相同
    metadatastring可选,用户自定义字段,可以不填写,备注用
    create_accountjson创建账号操作
    issue_assetjson发行资产操作
    pay_assetjson转移资产操作
    set_metadatajson设置metadata操作
    pay_coinjson转移Gas资产操作
    logjson记录日志操作
    set_privilegejson设置权限操作

操作码

操作码操作说明
1create_account创建账号
2issue_asset发行资产
3pay_asset转移资产
4set_metadata设置metadata
7pay_coin转移Gas资产
8log记录日志
9set_privilege设置权限

创建账号

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

创建普通账号

注意:在当前操作中,master_weight和tx_threshold都必须是1。

  • json结构

    {
      "dest_address": "adxSgCwYLWoCZnP6s2WXtQCwhxuFxhvsr375z",//待创建的目标账户地址
      "init_balance": 100000,//目标账户的初始化余额
      "priv":  {
        "master_weight": 1,//目标账户拥有的权力值
        "thresholds": {
          "tx_threshold": 1//发起交易需要的权力值
        }
      }
    }
    
  • json的关键字

    关键字类型描述
    dest_addressstring目标账号的地址。创建普通账号时,不能为空
    init_balanceint64目标账户的初始化 Gas 值,单位是UGas,1 Gas = 10^8 UGas
    master_weightint64目标账号的 master 权重,数值范围[0, MAX(UINT32)]
    tx_thresholdint64发起交易的门限,低于该值,无法发起交易,数值范围[0, MAX(INT64)]
  • 完整交易结构

    {
      "source_address":"adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//交易源账号,即交易的发起方
      "nonce":2, //交易源账户的nonce值
      "fee_limit" : 1000000, //愿为交易花费的手续费
      "gas_price": 1000,//gas价格(不小于配置的最低值)
      "ceil_ledger_seq": 100, //可选,区块高度限制, 如果大于0,则交易只有在该区块高度之前(包括该高度)才有效
      "metadata":"0123456789abcdef", //可选,用户自定义给交易的备注,16进制格式
      "operations":[
        {
          "type": 1, // 创建账户操作类型
          "source_address": "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//可选,操作源账户,即操作的执行方
          "metadata": "0123456789abcdef",//可选,用户自定义给交易的备注,16进制格式
          "create_account": {
            "dest_address": "adxSgCwYLWoCZnP6s2WXtQCwhxuFxhvsr375z",//待创建的目标账户地址
            "init_balance": 100000,//目标账户的初始化余额
            "priv":  {
              "master_weight": 1,//目标账户拥有的权力值
              "thresholds": {
                "tx_threshold": 1//发起交易需要的权力值
              }
            }
          }
        }
      ]
    }
    
  • 查询

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

创建合约账号

注意:在当前操作中,master_weight必须是0,tx_threshold必须是1。

  • json结构

    {
        "contract": { //合约
            "payload": "
                'use strict';
                function init(bar)
                {
                  return;
                }
    
                function main(input)
                {
                  return;
                }
    
                function query()
                {
                  return;
                }
                "//合约代码
            },
            "init_balance": 100000,  //合约账户初始化资产
            "init_input" : "{\"method\":\"toWen\",\"params\":{\"feeType\":0}}",//可选,合约代码init函数的入参
            "priv": {
                "master_weight": 0,//待创建的合约账户拥有的权力值
                "thresholds": {
                "tx_threshold": 1 //发起交易需要的权力值
            }
        }
    }
    
  • json的关键字

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

    {
      "source_address":"adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//交易源账号,即交易的发起方
    "nonce":2, //交易源账户的nonce值
      "fee_limit" : 1000000, //愿为交易花费的手续费
      "gas_price": 1000,//gas价格(不小于配置的最低值)
      "ceil_ledger_seq": 100, //可选,区块高度限制, 如果大于0,则交易只有在该区块高度之前(包括该高度)才有效
      "metadata":"0123456789abcdef", //可选,用户自定义给交易的备注,16进制格式
      "operations":[
        {
          "type": 1, // 创建账户操作类型
          "source_address": "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//可选,操作源账户,即操作的执行方
          "metadata": "0123456789abcdef",//可选,用户自定义给交易的备注,16进制格式
          "create_account": {
            "contract": { //合约
              "payload": "
                     'use strict';
                     function init(bar)
                     {
                       return;
                     }
    
                     function main(input)
                     {
                       return;
                     }
    
                     function query()
                     {
                       return;
                     }
                     "//合约代码
            },
            "init_balance": 100000,  //合约账户初始化资产
            "init_input" : "{\"method\":\"toWen\",\"params\":{\"feeType\":0}}",//可选,合约代码init函数的入参
            "priv": {
              "master_weight": 0,//待创建的合约账户拥有的权力值
              "thresholds": {
                "tx_threshold": 1 //发起交易需要的权力值
              }
            }
          }
        }
      ]
    }
    
  • 查询

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

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

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

发行资产

  • 功能

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

  • json结构

    {
      "code": "HYL", //待发行资产的代码
      "amount": 1000 //待发行资产的数量
    }
    
  • json的关键字

    关键字类型描述
    codestring待发行资产的代码,长度范围[1, 64]
    amountint64待发行资产的数量,数值范围(0,MAX(int64))
  • 完整交易结构

    {
      "source_address":"adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//交易源账号,即交易的发起方
      "nonce":2, //交易源账户的nonce值
      "fee_limit" : 1000000, //愿为交易花费的手续费
      "gas_price": 1000,//gas价格(不小于配置的最低值)
      "ceil_ledger_seq": 100,//可选,区块高度限制, 如果大于0,则交易只有在该区块高度之前(包括该高度)才有效
      "metadata":"0123456789abcdef",//可选,用户自定义给交易的备注,16进制格式
      "operations":[
        {
          "type": 2,//发行资产操作类型
          "source_address": "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//可选,操作源账户,即操作的执行方
          "metadata": "0123456789abcdef",//可选,用户自定义给交易的备注,16进制格式
          "issue_asset": {
            "code": "HYL",//待发行资产的代码
            "amount": 1000 //待发行资产的数量
          }
        }
      ]
    }
    

转移资产

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

  • 功能

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

  • json结构

    {
      "dest_address": "adxSgCwYLWoCZnP6s2WXtQCwhxuFxhvsr375z",//待接收资产的目标账户
      "asset": {
        "key": {
          "issuer": "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//资产的发行账户
          "code": "HYL" // 待转移的资产代码
        },
        "amount": 100 //待转移的资产数量
      },
      "input": "{\"bar\":\"foo\"}" // 可选,目标账户中合约代码main函数的入参
    }
    
  • json的关键字

    关键字类型描述
    dest_addressstring目标账户地址
    issuerstring资产发行方地址
    codestring资产代码,长度范围[1, 64]
    amountint64资产数量,数值范围(0,MAX(int64))
    inputstring可选,如果目标账户是合约账户,input会被传递给合约代码的main函数的参数。如果目标账户是普通账户,则该设置无效
  • 完整交易结构

    {
      "source_address":"adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//交易源账号,即交易的发起方
      "nonce":2, //交易源账户的nonce值
      "fee_limit" : 1000000, //愿为交易花费的手续费
      "gas_price": 1000,//gas价格(不小于配置的最低值)
      "ceil_ledger_seq": 100,//可选,区块高度限制, 如果大于0,则交易只有在该区块高度之前(包括该高度)才有效
      "metadata":"0123456789abcdef",//可选,用户自定义给交易的备注,16进制格式
      "operations":[
        {
          "type": 3,//转移资产操作类型
          "source_address": "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//可选,操作源账户,即操作的执行方
          "metadata": "0123456789abcdef",//可选,用户自定义给交易的备注,16进制格式
          "pay_asset": {
            "dest_address": "adxSgCwYLWoCZnP6s2WXtQCwhxuFxhvsr375z",//待接收资产的目标账户
            "asset": {
              "key": {
                "issuer": "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//资产的发行账户
                "code": "HYL" // 待转移的资产代码
              },
              "amount": 100 //待转移的资产数量
            },
            "input": "{\"bar\":\"foo\"}" // 可选,目标账户中合约代码main函数的入参
          }
        }
      ]
    }
    

设置metadata

  • 功能

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

  • json结构

    {
      "key": "abc",//metadata关键字
      "value": "hello abc!",//metadata内容
      "version": 0 //可选,metadata版本号
    }
    
  • json的关键字

    关键字类型描述
    keystringmetadata的关键字。长度范围(0, 1024]
    valuestringmetadata的内容。长度范围[0, 256K]
    versionint64可选,metadata版本号。默认值是0。0:不限制版本,>0 : 当前 value 的版本必须为该值, <0 : 非法
  • 完整交易结构

    {
      "source_address":"adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//交易源账号,即交易的发起方
      "nonce":2, //交易源账户的nonce值
      "fee_limit" : 1000000, //愿为交易花费的手续费
      "gas_price": 1000,//gas价格(不小于配置的最低值)
      "ceil_ledger_seq": 100,//可选,区块高度限制, 如果大于0,则交易只有在该区块高度之前(包括该高度)才有效
      "metadata":"0123456789abcdef",//可选,用户自定义给交易的备注,16进制格式
      "operations":[
        {
          "type": 4,//设置 metadata 操作类型
          "source_address": "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//可选,操作源账户,即操作的执行方
          "metadata": "0123456789abcdef",//可选,用户自定义给交易的备注,16进制格式
          "set_metadata": {
            "key": "abc",//metadata关键字
            "value": "hello abc!",//metadata内容
            "version": 0 //可选,metadata版本号
          }
        }
      ]
    }
    

设置权限

  • 功能

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

  • json结构

    {
      "master_weight": "10",//可选,当前账户的自身权力值
      "signers"://可选,需要操作的签名者列表
      [
        {
          "address": "adxSj9kGyXR2YpyxwZVMrnGcLWoG3Hf9qXne8",//需要操作的签名者地址
          "weight": 8 //可选,签名者的权力值
        }
      ],
      "tx_threshold": "2",//可选,发起交易需要权力值
      "type_thresholds"://可选,不同操作需要的权力值
      [
        {
          "type": 1,//创建账户操作类型
          "threshold": 8 //可选,该操作需要的权力值
        },
        {
          "type": 2,//发行资产操作类型
          "threshold": 9 //可选该操作需要的权力值
        }
      ]
    }
    
  • json关键字

    关键字类型描述
    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)]:设置权重值为该值;其他:非法
  • 完整交易结构

    {
      "source_address":"adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//交易源账号,即交易的发起方
      "nonce":2, //交易源账户的nonce值
      "fee_limit" : 1000000, //愿为交易花费的手续费
      "gas_price": 1000,//gas价格(不小于配置的最低值)
      "ceil_ledger_seq": 100,//可选,区块高度限制, 如果大于0,则交易只有在该区块高度之前(包括该高度)才有效
      "metadata":"0123456789abcdef",//可选,用户自定义给交易的备注,16进制格式
      "operations":[
        {
          "type": 9,//设置权限操作类型
          "source_address": "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//可选,操作源账户,即操作的执行方
          "metadata": "0123456789abcdef",//可选,用户自定义给交易的备注,16进制格式
          "set_privilege": {
            "master_weight": "10",//可选,当前账户的自身权力值
            "signers"://可选,需要操作的签名者列表
            [
              {
                "address": "adxSj9kGyXR2YpyxwZVMrnGcLWoG3Hf9qXne8",//需要操作的签名者地址
                "weight": 8 //可选,签名者的权力值
              }
            ],
            "tx_threshold": "2",//可选,发起交易需要权力值
            "type_thresholds"://可选,不同操作需要的权力值
            [
              {
                "type": 1,//创建账户操作类型
                "threshold": 8 //可选,该操作需要的权力值
              },
              {
                "type": 2,//发行资产操作类型
                "threshold": 9 //可选该操作需要的权力值
              }
            ]
          }
        }
      ]
    }
    

转移Gas资产

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

  • 功能

    有两个功能:

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

    {
      "dest_address": "adxSgGkHuPv6FQUu6C5uWnaqyKJ22bSNrJUCJ",//待接收Gas资产的目标账户
      "amount": 100,//待转移的Gas资产数量
      "input": "{\"bar\":\"foo\"}" // 可选,目标账户中合约代码main函数的入参
    }
    
  • json关键字

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

    {
      "source_address":"adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//交易源账号,即交易的发起方
      "nonce":2, //交易源账户的nonce值
      "fee_limit" : 1000000, //愿为交易花费的手续费
      "gas_price": 1000,//gas价格(不小于配置的最低值)
      "ceil_ledger_seq": 100,//可选,区块高度限制, 如果大于0,则交易只有在该区块高度之前(包括该高度)才有效
      "metadata":"0123456789abcdef",//可选,用户自定义给交易的备注,16进制格式
      "operations":[
        {
          "type": 7,//转移Gas资产操作类型
          "source_address": "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//可选,操作源账户,即操作的执行方
          "metadata": "0123456789abcdef",//可选,用户自定义给交易的备注,16进制格式
          "pay_coin": {
            "dest_address": "adxSgGkHuPv6FQUu6C5uWnaqyKJ22bSNrJUCJ",//待接收Gas资产的目标账户
            "amount": 100,//待转移的Gas资产数量
            "input": "{\"bar\":\"foo\"}" // 可选,目标账户中合约代码main函数的入参
          }
        }
      ]
    }
    

记录日志

  • 功能

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

  • json结构

    {
      "topic": "hello",// 日志主题
      "datas"://日志内容
      [
        "hello, log 1",
        "hello, log 2"
      ]
    }
    
  • json关键字

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

    {
      "source_address":"adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//交易源账号,即交易的发起方
      "nonce":2, //交易源账户的nonce值
      "fee_limit" : 1000000, //愿为交易花费的手续费
      "gas_price": 1000,//gas价格(不小于配置的最低值)
      "ceil_ledger_seq": 100,//可选,区块高度限制, 如果大于0,则交易只有在该区块高度之前(包括该高度)才有效
      "metadata":"0123456789abcdef",//可选,用户自定义给交易的备注,16进制格式
      "operations":[
        {
          "type": 8,//记录日志操作类型
          "source_address": "adxSn8xpL7c2xkxwbreVCs6EZ7KZbBvtDaLtV",//可选,操作源账户,即操作的执行方
          "metadata": "0123456789abcdef",//可选,用户自定义给交易的备注,16进制格式
          "log": {
            "topic": "hello",// 日志主题
            "datas"://日志内容
            [
              "hello, log 1",
              "hello, log 2"
            ]
          }
        }
      ]
    }
    

控制权的分配

您在创建一个账号时,可以指定这个账号的控制权分配。您可以通过设置priv的值设置。下面是一个简单的例子。

{
  "master_weight": "70",//本地址私钥拥有的权力值 70
  "signers": [//分配出去的权力
    {
      "address": "adxSigpdiWcW22hw54i9PEFk1s4WLEy5Rmh6K",
      "weight": 55    //上面这个地址拥有权力值55
    },
    {
      "address": "adxSX1SypC33doY4a5MYYr5zBZUvB33kKHdAo",
      "weight": 100    //上面这个地址拥有权力值100
    }
  ],
  "tx_threshold": "8",//发起交易需要权力值 8
  "type_thresholds": [
    {
      "type": 1,//创建账号需要权利值 11
      "threshold": 11
    },
    {//发行资产需要权利值 21
      "type": 2,
      "threshold": 21
    },
    {//转移资产需要权力值 31
      "type": 3,
      "threshold": 31
    },
    {//设置metadata需要权利值 41
      "type": 4,
      "threshold": 41
    },
    {//变更控制人的权力值需要权利值 51
      "type": 5,
      "threshold": 51
    },
    {//变更各种操作的阈值需要权利值 61
      "type": 6,
      "threshold": 61
    }
  ]
}

示例

下面我们用adxSW512jUyDASna878ECgZ4QFyhh6AtEJP6E发起一笔交易,这笔交易只有1个操作,即创建一个新账号adxSX1SypC33doY4a5MYYr5zBZUvB33kKHdAo,通过向该新账户转移Gas,完成账户创建的过程。

组装交易

参考交易结构的结构,需要以下三步来完成:

获取账户nonce值

组装操作

生成交易对象

获取账户nonce值

在交易的结构中,需要确认交易在交易发起账户的序号,因此,需要通过查询账号基本信息接口获取交易发起账户的nonce值,并在其nonce值基础上增加1。

接口调用如下:

HTTP GET localhost:36002/getAccountBase?address=adxSW512jUyDASna878ECgZ4QFyhh6AtEJP6E
或
curl get localhost:36002/getAccountBase?address=adxSW512jUyDASna878ECgZ4QFyhh6AtEJP6E

返回内容如下:

{
  "error_code" : 0,
  "result" : {
    "address" : "adxSW512jUyDASna878ECgZ4QFyhh6AtEJP6E",
    "assets_hash" : "ad67d57ae19de8068dbcd47282146bd553fe9f684c57c8c114453863ee41abc3",
    "balance" : 96545066100,
    "metadatas_hash" : "ad67d57ae19de8068dbcd47282146bd553fe9f684c57c8c114453863ee41abc3",
    "nonce" : 20,
    "priv" : {
      "master_weight" : 1,
      "thresholds" : {
        "tx_threshold" : 1
      }
    }
  }
}

组装操作

根据操作结构、操作码和转移Gas资产的结构,生成操作的json结构如下:

{
  "type": 7,
  "pay_coin": {
    "dest_address": "adxSX1SypC33doY4a5MYYr5zBZUvB33kKHdAo",
    "amount": 10000000,
    "input": ""
  }
}

生成交易对象

在获取账户nonce值得到nonce值是20,那么新交易的序号是21。再根据组装操作中得到的操作结构,从而生成交易的json结构如下:

{
  "source_address": "adxSW512jUyDASna878ECgZ4QFyhh6AtEJP6E",
  "nonce": 21,
  "fee_limit":1000000,
  "gas_price":1000,
  "operations": [{
    "type": 7,
    "pay_coin": {
      "dest_address": "adxSX1SypC33doY4a5MYYr5zBZUvB33kKHdAo",
      "amount": 10000000,
      "input": ""
    }
  }]
}

序列化交易数据

通过序列化交易接口来实现该功能。

接口调用如下:

HTTP POST localhost:36002/getTransactionBlob
或
curl localhost:36002/getTransactionBlob -X POST -d "{\"source_address\":\"adxSW512jUyDASna878ECgZ4QFyhh6AtEJP6E\",\"nonce\":21,\"fee_limit\":1000000,\"gas_price\":1000,\"operations\":[{\"type\":7,\"pay_coin\":{\"dest_address\":\"adxSX1SypC33doY4a5MYYr5zBZUvB33kKHdAo\",\"amount\":10000000,\"input\":\"\"}}]}"

返回内容如下:

{
    "error_code": 0,
    "error_desc": "",
    "result": {
        "hash": "3f90865062d7737904ea929cbde7c45e831e4972cf582b69a0198781c452e9e1",
        "transaction_blob": "0a246275516f50326552796d4163556d33757657675138526e6a7472536e58425866417a7356101518c0843d20e8073a2f0807522b0a24627551747336446654354b6176745639344a675a79373548397069776d62374b6f5557671080ade204"
    }
}

签名交易

签名就是用adxSW512jUyDASna878ECgZ4QFyhh6AtEJP6E的私钥对序列化交易数据中的transaction_blob的值进行签名,并生成公钥。具体操作参考:keypair。从而得到签名数据如下:

[{
    "sign_data": "ACF64A7D41244AFC4465DBC225D616E0499776140D46BA7A84B1B6B263DAF1422904137E0181301F480F7114EC7CC5BBE4763EDA981E565EF81EF7705596CB0B",
    "public_key": "b00168eceea7900ddcb8f694161755f98590ba7944de3bfe339610fe0cacc10a18372dcbf71b"
}]

提交交易数据

根据序列化交易数据得到的transaction_blob和签名交易得到的签名数据,生成提交交易接口中body的json结构如下:

{
    "items" : [{
        "transaction_blob" : "0a246275516f50326552796d4163556d33757657675138526e6a7472536e58425866417a7356101518c0843d20e8073a2f0807522b0a24627551747336446654354b6176745639344a675a79373548397069776d62374b6f5557671080ade204",
        "signatures" : [{
            "sign_data" : "ACF64A7D41244AFC4465DBC225D616E0499776140D46BA7A84B1B6B263DAF1422904137E0181301F480F7114EC7CC5BBE4763EDA981E565EF81EF7705596CB0B",
            "public_key" : "b00168eceea7900ddcb8f694161755f98590ba7944de3bfe339610fe0cacc10a18372dcbf71b"
        }]
    }]
}

调用接口如下:

HTTP POST localhost:36002/submitTransaction
或
curl localhost:36002/submitTransaction -X POST -d "{\"items\":[{\"transaction_blob\":\"0a246275516f50326552796d4163556d33757657675138526e6a7472536e58425866417a7356101518c0843d20e8073a2f0807522b0a24627551747336446654354b6176745639344a675a79373548397069776d62374b6f5557671080ade204\",\"signatures\":[{\"sign_data\":\"ACF64A7D41244AFC4465DBC225D616E0499776140D46BA7A84B1B6B263DAF1422904137E0181301F480F7114EC7CC5BBE4763EDA981E565EF81EF7705596CB0B\",\"public_key\":\"b00168eceea7900ddcb8f694161755f98590ba7944de3bfe339610fe0cacc10a18372dcbf71b\"}]}]}"

返回内容如下:

{
  "results": [
    {
      "error_code": 0,
      "error_desc": "",
      "hash": "3f90865062d7737904ea929cbde7c45e831e4972cf582b69a0198781c452e9e1"
    }
  ],
  "success_count": 1
}

查询交易结果

根据提交交易数据接口得到的hash,通过查询交易接口确认交易是否执行成功(查看transactions下的error_code是否等于0)。

接口调用如下:

HTTP GET localhost:36002/getTransactionHistory?hash=3f90865062d7737904ea929cbde7c45e831e4972cf582b69a0198781c452e9e1
或
curl get localhost:36002/getTransactionHistory?hash=3f90865062d7737904ea929cbde7c45e831e4972cf582b69a0198781c452e9e1

得到结果:

{
  "error_code": 0,//交易查询成功
  "result": {
    "total_count": 1,
    "transactions": [
      {
        "actual_fee": 245000,
        "close_time": 1552125554325904,
        "error_code": 0,//交易执行成功
        "error_desc": "",
        "hash": "3f90865062d7737904ea929cbde7c45e831e4972cf582b69a0198781c452e9e1",
        "ledger_seq": 2688046,
        "signatures": [
          {
            "public_key": "b00168eceea7900ddcb8f694161755f98590ba7944de3bfe339610fe0cacc10a18372dcbf71b",
            "sign_data": "acf64a7d41244afc4465dbc225d616e0499776140d46ba7a84b1b6b263daf1422904137e0181301f480f7114ec7cc5bbe4763eda981e565ef81ef7705596cb0b"
          }
        ],
        "transaction": {
          "fee_limit": 1000000,
          "gas_price": 1000,
          "nonce": 21,
          "operations": [
            {
              "pay_coin": {
                "amount": 10000000,
                "dest_address": "adxSX1SypC33doY4a5MYYr5zBZUvB33kKHdAo"
              },
              "type": 7
            }
          ],
          "source_address": "adxSW512jUyDASna878ECgZ4QFyhh6AtEJP6E"
        },
        "tx_size": 245
      }
    ]
  }
}

错误码

错误由两部分构成:

  • 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插入交易缓存队列失败
← 概述Websocket →
  • 试一试
  • HTTP接口
    • 生成公私钥对-测试用
    • 查询账号
    • 查询账号基本信息
    • 查询资产
    • 查询metadata
    • 查询交易
    • 查询缓存队列交易
    • 查询区块头
    • 批量查询
    • 序列化交易
    • 提交交易
    • 调用合约
    • 评估费用
  • 交易结构
  • 操作结构
    • 操作码
    • 创建账号
    • 发行资产
    • 转移资产
    • 设置metadata
    • 设置权限
    • 转移Gas资产
    • 记录日志
  • 控制权的分配
  • 示例
    • 组装交易
    • 序列化交易数据
    • 签名交易
    • 提交交易数据
    • 查询交易结果
  • 错误码
Copyright © 2020