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 - `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.
  20 - `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.
  21 - `Arrary of Object` - *actions*:
  22   - `Object`:
  23     - `String` - *account_id* | *account_alias*, (type is spend_account) alias or ID of account.
  24     - `String` - *asset_id* | *asset_alias*, (type is spend_account, issue, retire, control_program and control_address) alias or ID of asset.
  25     - `Integer` - *amount*, (type is spend_account, issue, retire, control_program and control_address) the specified asset of the amount sent with this transaction.
  26     - `String`- *type*, type of transaction, valid types: 'spend_account', 'issue', 'spend_account_unspent_output', 'control_address', 'control_program', 'retire'.
  27     - `String` - *address*, (type is control_address) address of receiver, the style of address is P2PKH or P2SH.
  28     - `String` - *control_program*, (type is control_program) control program of receiver.
  29     - `String` - *use_unconfirmed*, (type is spend_account and spend_account_unspent_output) flag of use unconfirmed UTXO, default is false.
  30
  31 #### Returns
  32
  33 - `Object of build-transaction` - *transaction*, builded transaction.
  34
  35 #### Example
  36
  37 ```js
  38 // Request
  39 curl -X POST build-transaction -d '{"base_transaction":null,"actions":[{"account_id":"0BF63M2U00A04","amount":20000000,"asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff","type":"spend_account"},{"amount":10000,"asset_id":"3152a15da72be51b330e1c0f8e1c0db669269809da4f16443ff266e07cc43680","type":"issue"},{"amount":10000,"asset_id":"3152a15da72be51b330e1c0f8e1c0db669269809da4f16443ff266e07cc43680","address":"bm1q50u3z8empm5ke0g3ngl2t3sqtr6sd7cepd3z68","type":"control_address"}],"ttl":0,"time_range": 43432}'
  40 ```
  41
  42 ```js
  43 // Result
  44 {
  45   "allow_additional_actions": false,
  46   "local": true,
  47   "raw_transaction": "07010000020161015fb6a63a3361170afca03c9d5ce1f09fe510187d69545e09f95548b939cd7fffa3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff80fc93afdf01000116001426bd1b851cf6eb8a701c20c184352ad8720eeee90100015d015bb6a63a3361170afca03c9d5ce1f09fe510187d69545e09f95548b939cd7fffa33152a15da72be51b330e1c0f8e1c0db669269809da4f16443ff266e07cc43680c03e0101160014489a678741ccc844f9e5c502f7fac0a665bedb25010003013effffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff80a2cfa5df0101160014948fb4f500e66d20fbacb903fe108ee81f9b6d9500013a3152a15da72be51b330e1c0f8e1c0db669269809da4f16443ff266e07cc43680dd3d01160014cd5a822b34e3084413506076040d508bb12232c70001393152a15da72be51b330e1c0f8e1c0db669269809da4f16443ff266e07cc436806301160014a3f9111f3b0ee96cbd119a3ea5c60058f506fb1900",
  48   "signing_instructions": [
  49     {
  50       "position": 0,
  51       "witness_components": [
  52         {
  53           "keys": [
  54             {
  55               "derivation_path": [
  56                 "010100000000000000",
  57                 "0500000000000000"
  58               ],
  59               "xpub": "ee9dd8affdef7e0cacd0fbbf310217c7f588156c28e414db74c27afaedd8f876cf54547a672b431ff06ee8a146207df9595638a041b55ada1a764a8b5b30bda0"
  60             }
  61           ],
  62           "quorum": 1,
  63           "signatures": null,
  64           "type": "raw_tx_signature"
  65         },
  66         {
  67           "type": "data",
  68           "value": "62a73b6b7ffe52b6ad782b0e0efdc8309bf2f057d88f9a17d125e41bb11dbb88"
  69         }
  70       ]
  71     },
  72     {
  73       "position": 1,
  74       "witness_components": [
  75         {
  76           "keys": [
  77             {
  78               "derivation_path": [
  79                 "010100000000000000",
  80                 "0600000000000000"
  81               ],
  82               "xpub": "ee9dd8affdef7e0cacd0fbbf310217c7f588156c28e414db74c27afaedd8f876cf54547a672b431ff06ee8a146207df9595638a041b55ada1a764a8b5b30bda0"
  83             }
  84           ],
  85           "quorum": 1,
  86           "signatures": null,
  87           "type": "raw_tx_signature"
  88         },
  89         {
  90           "type": "data",
  91           "value": "ba5a63e7416caeb945eefc2ce874f40bc4aaf6005a1fc792557e41046f7e502f"
  92         }
  93       ]
  94     }
  95   ]
  96 }
  97 ```
  98
  99 #### Following steps
 100
 101 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.
 102
 103 ## list cross-chain transactions
 104
 105 To list cross-chain transactions, `list-transactions` needs to be called by a vapord node.
 106
 107 If
 108
 109
 110 ## sidechain(vapor) to mainchain(bytom)
 111
 112 To build a sidechain-to-mainchain transaction, `build-transaction` is called by a vapor user, using `cross_chain_out` action.
 113
 114 ### Parameters
 115
 116 `Object`:
 117
 118 - `String` - *base_transaction*, base data for the transaction, default is null.
 119 - `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.
 120 - `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.
 121 - `Arrary of Object` - *actions*:
 122   - `Object`:
 123     - `String` - *account_id* | *account_alias*, (type is spend_account) alias or ID of account.
 124     - `String` - *asset_id* | *asset_alias*, (type is spend_account, issue, retire, control_program and control_address) alias or ID of asset.
 125     - `Integer` - *amount*, (type is spend_account, issue, retire, control_program and control_address) the specified asset of the amount sent with this transaction.
 126     - `String`- *type*, type of transaction, valid types: 'spend_account', 'issue', 'spend_account_unspent_output', 'control_address', 'control_program', 'retire'.
 127     - `String` - *address*, (type is control_address) address of receiver, the style of address is P2PKH or P2SH.
 128     - `String` - *control_program*, (type is control_program) control program of receiver.
 129     - `String` - *use_unconfirmed*, (type is spend_account and spend_account_unspent_output) flag of use unconfirmed UTXO, default is false.
 130
 131 #### Returns
 132
 133 - `Object of build-transaction` - *transaction*, builded transaction.
 134
 135 #### Example
 136
 137 ```js
 138 // Request
 139 curl -X POST build-transaction -d '{"base_transaction":null,"actions":[{"account_id":"0BF63M2U00A04","amount":20000000,"asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff","type":"spend_account"},{"amount":10000,"asset_id":"3152a15da72be51b330e1c0f8e1c0db669269809da4f16443ff266e07cc43680","type":"issue"},{"amount":10000,"asset_id":"3152a15da72be51b330e1c0f8e1c0db669269809da4f16443ff266e07cc43680","address":"bm1q50u3z8empm5ke0g3ngl2t3sqtr6sd7cepd3z68","type":"control_address"}],"ttl":0,"time_range": 43432}'
 140 ```
 141
 142 ```js
 143 // Result
 144 {
 145   "allow_additional_actions": false,
 146   "local": true,
 147   "raw_transaction": "07010000020161015fb6a63a3361170afca03c9d5ce1f09fe510187d69545e09f95548b939cd7fffa3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff80fc93afdf01000116001426bd1b851cf6eb8a701c20c184352ad8720eeee90100015d015bb6a63a3361170afca03c9d5ce1f09fe510187d69545e09f95548b939cd7fffa33152a15da72be51b330e1c0f8e1c0db669269809da4f16443ff266e07cc43680c03e0101160014489a678741ccc844f9e5c502f7fac0a665bedb25010003013effffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff80a2cfa5df0101160014948fb4f500e66d20fbacb903fe108ee81f9b6d9500013a3152a15da72be51b330e1c0f8e1c0db669269809da4f16443ff266e07cc43680dd3d01160014cd5a822b34e3084413506076040d508bb12232c70001393152a15da72be51b330e1c0f8e1c0db669269809da4f16443ff266e07cc436806301160014a3f9111f3b0ee96cbd119a3ea5c60058f506fb1900",
 148   "signing_instructions": [
 149     {
 150       "position": 0,
 151       "witness_components": [
 152         {
 153           "keys": [
 154             {
 155               "derivation_path": [
 156                 "010100000000000000",
 157                 "0500000000000000"
 158               ],
 159               "xpub": "ee9dd8affdef7e0cacd0fbbf310217c7f588156c28e414db74c27afaedd8f876cf54547a672b431ff06ee8a146207df9595638a041b55ada1a764a8b5b30bda0"
 160             }
 161           ],
 162           "quorum": 1,
 163           "signatures": null,
 164           "type": "raw_tx_signature"
 165         },
 166         {
 167           "type": "data",
 168           "value": "62a73b6b7ffe52b6ad782b0e0efdc8309bf2f057d88f9a17d125e41bb11dbb88"
 169         }
 170       ]
 171     },
 172     {
 173       "position": 1,
 174       "witness_components": [
 175         {
 176           "keys": [
 177             {
 178               "derivation_path": [
 179                 "010100000000000000",
 180                 "0600000000000000"
 181               ],
 182               "xpub": "ee9dd8affdef7e0cacd0fbbf310217c7f588156c28e414db74c27afaedd8f876cf54547a672b431ff06ee8a146207df9595638a041b55ada1a764a8b5b30bda0"
 183             }
 184           ],
 185           "quorum": 1,
 186           "signatures": null,
 187           "type": "raw_tx_signature"
 188         },
 189         {
 190           "type": "data",
 191           "value": "ba5a63e7416caeb945eefc2ce874f40bc4aaf6005a1fc792557e41046f7e502f"
 192         }
 193       ]
 194     }
 195   ]
 196 }
 197 ```
 198
 199 #### Following steps
 200
 201 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.