docs/cross-chain.md

   1 # cross-chain transaction
   2
   3 Related API:
   4
   5 + `build-transaction` / `build-chain-transactions`
   6 + `sign-transaction` / `sign-transactions`
   7 + `submit-transaction` / `submit-transactions`
   8 + `list-transactions`
   9
  10 ## mainchain(bytom) to sidechain(vapor)
  11
  12 To build a mainchain-to-sidechain transaction, `build-transaction` is called by one or more federation members, using `cross_chain_in` action.
  13
  14 ### Parameters
  15
  16 `Object`:
  17
  18 - `String` - *base_transaction*, base data for the transaction, default is null.
  19 - `Arrary of Object` - *actions*:
  20   - `Object`:
  21     - `String` - *asset_id* | *asset_alias*, (type is cross_chain_in, control_program and control_address) alias or ID of asset.
  22     - `Integer` - *amount*, (type is cross_chain_in, control_program and control_address) the specified asset of the amount sent with this transaction.
  23     - `String`- *type*, type of transaction, valid types: 'cross_chain_in', 'control_address', 'control_program'.
  24     - `String` - *address*, (type is control_address) address of receiver, the style of address is P2PKH or P2SH.
  25     - `String` - *control_program*, (type is control_program) control program of receiver.
  26     - `Integer` - *vm_version*, (type is cross_chain_in) asset vm_version.
  27     - `String` - *issuance_program*, (type is cross_chain_in) asset issuance_program hexdecimal string.
  28     - `String` - *raw_definition_byte*, (type is cross_chain_in) asset raw_definition_byte hexdecimal string.
  29     - `String` - *source_id*, (type is cross_chain_in) mainchain output mux id.
  30     - `Integer` - *source_pos*, (type is cross_chain_in) mainchain output source position.
  31
  32 ### Returns
  33
  34 - `Object of build-transaction` - *transaction*, builded transaction.
  35
  36 ### Example
  37
  38 ```js
  39 // Request
  40 curl -X POST build-transaction -d '{
  41     "base_transaction":null,
  42     "actions":[
  43         {
  44             "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
  45             "amount":20000000,
  46             "source_id":"d5156f4477fcb694388e6aed7ca390e5bc81bb725ce7461caa241777c1f62236",
  47             "source_pos":3,
  48             "type":"cross_chain_in"
  49         },
  50         {
  51             "amount":20000000,
  52             "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
  53             "address":"vp1qfk5rudmkfny6x5enzxzj0qks3ce9dvgmyg4d2h",
  54             "type":"control_address"
  55         }
  56     ]
  57 }'
  58 ```
  59
  60 ```js
  61 // Result
  62 {
  63   "status":"success",
  64   "data":{
  65     "raw_transaction":"07010001019001008d01d5156f4477fcb694388e6aed7ca390e5bc81bb725ce7461caa241777c1f62236ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff80dac409030146ae2071dcacf8495651f205858a3a4b64c4d4bb24f382ff517b558c8e0acaac5819652039579ddd54e667057e175032683c1152578c9b05b5ecbc11b3f500b4263e41885152ad01000001013e003cffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff80ade204011600144da83e37764cc9a3533311852782d08e3256b11b00",
  66     "signing_instructions":[
  67       {
  68         "position":0,
  69         "witness_components":[
  70           {
  71             "type":"raw_tx_signature",
  72             "quorum":1,
  73             "keys":[
  74               {
  75                 "xpub":"71dcacf8495651f205858a3a4b64c4d4bb24f382ff517b558c8e0acaac5819650abcd618c10058f867fce07b0455cdb34c273b2bf8fc7ee9e3c70706d5bba8f4",
  76                 "derivation_path":[
  77
  78                 ]
  79               },
  80               {
  81                 "xpub":"39579ddd54e667057e175032683c1152578c9b05b5ecbc11b3f500b4263e418868da2376963dbbfb18a0d8aac64ea0d97e7c82061c58e98e22d4d1c7f5f5809d",
  82                 "derivation_path":[
  83
  84                 ]
  85               }
  86             ],
  87             "signatures":null
  88           }
  89         ]
  90       }
  91     ],
  92     "fee":10000000,
  93     "allow_additional_actions":false
  94   }
  95 }
  96 ```
  97
  98 ### Following steps
  99
 100 Then the federation members sign the transaction and submit it to a vapord node, using `sign-transaction` and `submit-transaction` respectively. The usages are as same as those for bytomd, see bytomd RPC document's [`sign-transaction`](https://github.com/Bytom/bytom/wiki/API-Reference#sign-transaction) and [`submit-transaction`](https://github.com/Bytom/bytom/wiki/API-Reference#submit-transaction) for detail.
 101
 102 ## list cross-chain transactions
 103
 104 To list cross-chain transactions, `list-transactions` needs to be called by a vapord node.
 105
 106 If a transaction contains a `cross_chain_in` input or a `cross_chain_out` output, it is recognized as a cross-chain transaction.
 107
 108 ### Parameters
 109
 110 `Object`:
 111
 112 optional:
 113
 114 - `String` - *id*, transaction id, hash of transaction.
 115 - `String` - *account_id*, id of account.
 116 - `Boolean` - *detail* , flag of detail transactions, default false (only return transaction summary)
 117 - `Boolean` - *unconfirmed*, flag of unconfirmed transactions(query result include all confirmed and unconfirmed transactions), default false.
 118 - `Integer` - *from*, \bthe start position of first transaction
 119 - `Integer` - *count*, the number of returned
 120
 121 ### Returns
 122
 123 `Array of Object`, transaction array.
 124
 125 optional:
 126
 127   - `Object`:(summary transaction)
 128     - `String` - *tx_id*, transaction id, hash of the transaction.
 129     - `Integer` - *block_time*, the unix timestamp for when the requst was responsed.
 130     - `Array of Object` - *inputs*, object of summary inputs for the transaction.
 131       - `String` - *type*, the type of input action, available option include: 'spend', 'issue', 'coinbase'.
 132       - `String` - *asset_id*, asset id.
 133       - `String` - *asset_alias*, name of asset.
 134       - `Integer` - *amount*, amount of asset.
 135       - `String` - *account_id*, account id.
 136       - `String` - *account_alias*, name of account.
 137       - `Object` - *arbitrary*, arbitrary infomation can be set by miner, it only exist when type is 'coinbase'.
 138     - `Array of Object` - *outputs*, object of summary outputs for the transaction.
 139       - `String` - *type*, the type of output action, available option include: 'retire', 'control'.
 140       - `String` - *asset_id*, asset id.
 141       - `String` - *asset_alias*, name of asset.
 142       - `Integer` - *amount*, amount of asset.
 143       - `String` - *account_id*, account id.
 144       - `String` - *account_alias*, name of account.
 145       - `Object` - *arbitrary*, arbitrary infomation can be set by miner, it only exist when type is input 'coinbase'(this place is empty).
 146
 147   - `Object`:(detail transaction)
 148     - `String` - *tx_id*, transaction id, hash of the transaction.
 149     - `Integer` - *block_time*, the unix timestamp for when the requst was responsed.
 150     - `String` - *block_hash*, hash of the block where this transaction was in.
 151     - `Integer` - *block_height*, block height where this transaction was in.
 152     - `Integer` - *block_index*, position of the transaction in the block.
 153     - `Integer` - *block_transactions_count*, transactions count where this transaction was in the block.
 154     - `Boolean` - *status_fail*, whether the state of the transaction request has failed.
 155     - `Integer` - *size*, size of transaction.
 156     - `Array of Object` - *inputs*, object of inputs for the transaction.
 157       - `String` - *type*, the type of input action, available option include: 'spend', 'issue', 'coinbase'.
 158       - `String` - *asset_id*, asset id.
 159       - `String` - *asset_alias*, name of asset.
 160       - `Object` - *asset_definition*, definition of asset(json object).
 161       - `Integer` - *amount*, amount of asset.
 162       - `Object` - *issuance_program*, issuance program, it only exist when type is 'issue'.
 163       - `Object` - *control_program*, control program of account, it only exist when type is 'spend'.
 164       - `String` - *address*, address of account, it only exist when type is 'spend'.
 165       - `String` - *spent_output_id*, the front of outputID to be spent in this input, it only exist when type is 'spend'.
 166       - `String` - *account_id*, account id.
 167       - `String` - *account_alias*, name of account.
 168       - `Object` - *arbitrary*, arbitrary infomation can be set by miner, it only exist when type is 'coinbase'.
 169       - `String` - *input_id*, hash of input action.
 170       - `Array of String` - *witness_arguments*, witness arguments.
 171     - `Array of Object` - *outputs*, object of outputs for the transaction.
 172       - `String` - *type*, the type of output action, available option include: 'retire', 'control'.
 173       - `String` - *id*, outputid related to utxo.
 174       - `Integer` - *position*, position of outputs.
 175       - `String` - *asset_id*, asset id.
 176       - `String` - *asset_alias*, name of asset.
 177       - `Object` - *asset_definition*, definition of asset(json object).
 178       - `Integer` - *amount*, amount of asset.
 179       - `String` - *account_id*, account id.
 180       - `String` - *account_alias*, name of account.
 181       - `Object` - *control_program*, control program of account.
 182       - `String` - *address*, address of account.
 183
 184 ### Example
 185
 186 list all the available transactions:
 187
 188 ```js
 189 // Request
 190 curl -X POST list-transactions -d {}
 191
 192 // Result
 193 {
 194   "status":"success",
 195   "data":[
 196     {
 197       "tx_id":"0dcd7312b120a1d4e3e441d7154710dd20093434a2184eda523ca003faba3039",
 198       "block_time":1559638198209,
 199       "inputs":[
 200         {
 201           "type":"spend",
 202           "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
 203           "asset_alias":"BTM",
 204           "amount":10000000,
 205           "account_id":"0TAOSK9J00A02",
 206           "account_alias":"11111"
 207         }
 208       ],
 209       "outputs":[
 210         {
 211           "type":"control",
 212           "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
 213           "asset_alias":"BTM",
 214           "amount":1000000,
 215           "account_id":"0TAOSK9J00A02",
 216           "account_alias":"11111"
 217         },
 218         {
 219           "type":"cross_chain_out",
 220           "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
 221           "asset_alias":"BTM",
 222           "amount":4000000
 223         }
 224       ]
 225     },
 226     {
 227       "tx_id":"137ea7ab674f41720f731e9e0e94aeef16027a993c4fb78b0b79b7ce61584789",
 228       "block_time":1559638147539,
 229       "inputs":[
 230         {
 231           "type":"cross_chain_in",
 232           "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
 233           "asset_alias":"BTM",
 234           "amount":20000000
 235         }
 236       ],
 237       "outputs":[
 238         {
 239           "type":"control",
 240           "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
 241           "asset_alias":"BTM",
 242           "amount":10000000,
 243           "account_id":"0TAOSK9J00A02",
 244           "account_alias":"11111"
 245         }
 246       ]
 247     },
 248     {
 249       "tx_id":"0c0b0ed9458fd66e1ed004cfb513cef5982dc4112db0afdf106bdf7abf88c8c1",
 250       "block_time":1559636817158,
 251       "inputs":[
 252         {
 253           "type":"spend",
 254           "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
 255           "asset_alias":"BTM",
 256           "amount":10000000,
 257           "account_id":"0TAOSK9J00A02",
 258           "account_alias":"11111"
 259         }
 260       ],
 261       "outputs":[
 262         {
 263           "type":"control",
 264           "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
 265           "asset_alias":"BTM",
 266           "amount":1000000,
 267           "account_id":"0TAOSK9J00A02",
 268           "account_alias":"11111"
 269         },
 270         {
 271           "type":"cross_chain_out",
 272           "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
 273           "asset_alias":"BTM",
 274           "amount":4000000
 275         }
 276       ]
 277     },
 278     {
 279       "tx_id":"75271e40894c198e7b2a0574227a056945fbaa28b1a9d5efde6268f4a8e30a3a",
 280       "block_time":1559636756076,
 281       "inputs":[
 282         {
 283           "type":"cross_chain_in",
 284           "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
 285           "asset_alias":"BTM",
 286           "amount":20000000
 287         }
 288       ],
 289       "outputs":[
 290         {
 291           "type":"control",
 292           "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
 293           "asset_alias":"BTM",
 294           "amount":10000000,
 295           "account_id":"0TAOSK9J00A02",
 296           "account_alias":"11111"
 297         }
 298       ]
 299     },
 300     {
 301       "tx_id":"e008984f63c2dd36a7488ba82f95e2a9caa2ed20d6fd46faa53c0b3eb51283ea",
 302       "block_time":1559635831740,
 303       "inputs":[
 304         {
 305           "type":"cross_chain_in",
 306           "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
 307           "asset_alias":"BTM",
 308           "amount":20000000
 309         }
 310       ],
 311       "outputs":[
 312         {
 313           "type":"control",
 314           "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
 315           "asset_alias":"BTM",
 316           "amount":10000000,
 317           "account_id":"0TAOSK9J00A02",
 318           "account_alias":"11111"
 319         }
 320       ]
 321     }
 322   ]
 323 }
 324 ```
 325
 326
 327 ## sidechain(vapor) to mainchain(bytom)
 328
 329 To build a sidechain-to-mainchain transaction, `build-transaction` is called by a vapor user, using `cross_chain_out` action.
 330
 331 ### Parameters
 332
 333 `Object`:
 334
 335 - `String` - *base_transaction*, base data for the transaction, default is null.
 336 - `Integer` - *ttl*, integer of the time to live in milliseconds, it means utxo will be reserved(locked) for builded transaction in this time range, if the transaction will not to be submitted into block, it will be auto unlocked for build transaction again after this ttl time. it will be set to 5 minutes(300 seconds) defaultly when ttl is 0.
 337 - `Integer` - *time_range*, the block height at which this transaction will be allowed to be included in a block. If the block height of the main chain exceeds this value, the transaction will expire and no longer be valid.
 338 - `Arrary of Object` - *actions*:
 339   - `Object`:
 340     - `String` - *account_id* | *account_alias*, (type is spend_account) alias or ID of account.
 341     - `String` - *asset_id* | *asset_alias*, (type is spend_account, cross_chain_out) alias or ID of asset.
 342     - `Integer` - *amount*, (type is spend_account, cross_chain_out) the specified asset of the amount sent with this transaction.
 343     - `String`- *type*, type of transaction, valid types: 'spend_account', 'spend_account_unspent_output', 'cross_chain_out', 'control_program'.
 344     - `String` - *address*, (type is cross_chain_out) address of receiver, the style of address is P2PKH or P2SH.
 345     - `String` - *use_unconfirmed*, (type is spend_account and spend_account_unspent_output) flag of use unconfirmed UTXO, default is false.
 346
 347 ### Returns
 348
 349 - `Object of build-transaction` - *transaction*, builded transaction.
 350
 351 ### Example
 352
 353 ```js
 354 // Request
 355 curl -X POST build-transaction -d '{
 356     "base_transaction":null,
 357     "actions":[
 358         {
 359             "amount":9000000,
 360             "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
 361             "account_id":"0TAOSK9J00A02",
 362             "type":"spend_account",
 363             "use_unconfirmed":true
 364         },
 365         {
 366             "amount":4000000,
 367             "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
 368             "address":"bm1q3yt265592czgh96r0uz63ta8fq40uzu5a8c2h0",
 369             "type":"cross_chain_out"
 370         }
 371     ]
 372 }'
 373 ```
 374
 375 ```js
 376 // Result
 377 {
 378   "status":"success",
 379   "data":{
 380     "raw_transaction":"07010001015f015dcca6be7f2b17d0695ed2ae5497f4711788e355ff1c3a93401c8e035a1f84a7b8ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff80ade20400011600144da83e37764cc9a3533311852782d08e3256b11b010002013d003bffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffc0843d011600146e544784f94bc9b6b608b561075c03804319ed4f00013e013cffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff8092f401011600148916ad528556048b97437f05a8afa7482afe0b9400",
 381     "signing_instructions":[
 382       {
 383         "position":0,
 384         "witness_components":[
 385           {
 386             "type":"raw_tx_signature",
 387             "quorum":1,
 388             "keys":[
 389               {
 390                 "xpub":"71dcacf8495651f205858a3a4b64c4d4bb24f382ff517b558c8e0acaac5819650abcd618c10058f867fce07b0455cdb34c273b2bf8fc7ee9e3c70706d5bba8f4",
 391                 "derivation_path":[
 392                   "2c000000",
 393                   "99000000",
 394                   "01000000",
 395                   "00000000",
 396                   "01000000"
 397                 ]
 398               }
 399             ],
 400             "signatures":null
 401           },
 402           {
 403             "type":"data",
 404             "value":"5b4c19722110ea7c1b5ace5d63393d401ef0797a605568a88a8fc4cdfcf293b6"
 405           }
 406         ]
 407       }
 408     ],
 409     "fee":5000000,
 410     "allow_additional_actions":false
 411   }
 412 }
 413 ```
 414
 415 ### Following steps
 416
 417 Then the vapor user sign the transaction and submit it to a vapord node, using `sign-transaction` and `submit-transaction` respectively. The usages are as same as those for bytomd, see bytomd RPC document's [`sign-transaction`](https://github.com/Bytom/bytom/wiki/API-Reference#sign-transaction) and [`submit-transaction`](https://github.com/Bytom/bytom/wiki/API-Reference#submit-transaction) for detail.