docs/federation/README-en.md

   1 # Federation
   2
   3 To run a federation node, you will need to:
   4
   5 1. init a MySQL database with this [schema](./federation.sql);
   6 2. run a `bytomd` node;
   7 3. run a `vapord` node and import the federation private key;
   8 4. and last but not least, run a `fedd` node with a `fed_cfg.json` and it will listen at 9886 port.
   9
  10 A `fed_cfg.json` would look like this:
  11
  12 ```json
  13 {
  14     "api" : {
  15         "is_release_mode": false
  16     },
  17     "mysql" : {
  18         "connection" : {
  19             "host": "127.0.0.1",
  20             "port": 3306,
  21             "username": "root",
  22             "password": "",
  23             "database": "federation"
  24         },
  25         "log_mode" : true
  26     },
  27     "federation_prog" : "0020305dc12c0dbec0c1dc1f30e835034c1f19094c06afb0eb953a6d1af42222a721",
  28     "mainchain" : {
  29         "name" : "bytom",
  30         "confirmations" : 10,
  31         "upstream" : "http://127.0.0.1:9888",
  32         "sync_seconds" : 150
  33     },
  34     "sidechain" : {
  35         "name" : "vapor",
  36         "confirmations" : 100,
  37         "upstream" : "http://127.0.0.1:9889",
  38         "sync_seconds" : 5
  39     }
  40 }
  41 ```
  42 ## API
  43 A federation node can function as an api server for querying cross-chain transactions.
  44
  45 The default JSON-RPC endpoint is: [http://host:port/api/v1/federation/](http://host:port/api/v1/federation/)
  46
  47 The response contains some meta data of:
  48
  49 + success/error status, which can be told from `code` and `msg`;
  50 + pagination info, which can be told from `start`, `limit` and `_links` (`_links` is used to look up the preceding and the succeeding items);
  51
  52 and looks like:
  53 ```
  54 {
  55   "code":200,
  56   "msg":"",
  57   "result":{
  58     "_links":{
  59     },
  60     "data":...,
  61     "limit":10,
  62     "start":0
  63   }
  64 }
  65 ```
  66
  67 If a request succeed, `data` field contains the detailed result as an object or as an array of objects.
  68
  69 ### Pagination
  70
  71 Append `?start=<integer>&limit=<integer>` to the url in order to use pagination.
  72
  73 ### Methods
  74
  75 #### `/list-crosschain-txs`
  76
  77 To list cross-chain transactions and filter the transactions.
  78
  79 ##### Parameters
  80
  81 Optional:
  82
  83 - `Object` - *filter*, transactions filter.
  84     + Optional
  85         * `String` - *status*, transactions status, which can be `pending` or `completed`.
  86         * `String` - *source_chain_name*, transactions source chain, which can be `bytom` or `vapor`.
  87         * `String` - *address*, filter cross-chain requests by address. The address can be either a mainchain or a sidechain one. Note that other requests in such a transaction will also be filtered.
  88         * `String` - *source_tx_hash*, souce transaction hash string.
  89         * `String` - *dest_tx_hash*, destination transaction hash string.
  90 - `Object` - *sort*, transactions sorter.
  91     + Optional
  92         * `String` - *order*, transactions order sorter, which can be `asc` or `desc`.
  93
  94
  95 ##### Returns
  96
  97
  98 `Object`:
  99
 100 - `String` - *source_chain_name*, source chain name of the cross-chain transaction.
 101 - `Integer` - *source_block_height*, block height of the cross-chain transaction on the source chain.
 102 - `Integer` - *source_block_timestamp*, block timestamp of the cross-chain transaction on the source chain.
 103 - `String` - *source_block_hash*, block hash of the cross-chain transaction on the source chain.
 104 - `Integer` - *source_tx_index*, transaction index in the source block.
 105 - `String` - *source_tx_hash*, source transaction hash.
 106 - `Integer` - *dest_block_height*, block height of the cross-chain transaction on the destination chain, `0` if `status` is `pending`.
 107 - `Integer` - *dest_block_timestamp*, block timestamp of the cross-chain transaction on the destination chain, `0` if `status` is `pending`.
 108 - `String` - *dest_block_hash*, block hash of the cross-chain transaction on the destination chain, empty string if `status` is `pending`.
 109 - `Integer` - *dest_tx_index*, transaction index in the destination block, `0` if `status` is `pending`.
 110 - `String` - *dest_tx_hash*, destination transaction hash, empty string if `status` is `pending`.
 111 - `String` - *status*, cross-chain transaction status, can be `pending` or `completed`.
 112 - `Array of objects` - *crosschain_requests*, asset transfer details per request included in the cross-chain transaction.
 113     + `Integer` - *amount*, asset transfer amount.
 114     + `String` - *from_address*, source address.
 115     + `String` - *to_address*, destination address.
 116     + `Object` - *asset*, asset detail.
 117         * `String` - *asset_id*, asset id string.
 118
 119 ##### Example
 120
 121 ```js
 122 // Request
 123 curl -X POST 127.0.0.1:9886/api/v1/federation/list-crosschain-txs -d '{}'
 124
 125 // Result
 126 {
 127   "code":200,
 128   "msg":"",
 129   "result":{
 130     "_links":{
 131
 132     },
 133     "data":[
 134       {
 135         "source_chain_name":"bytom",
 136         "source_block_height":174,
 137         "source_block_timestamp":1561457348,
 138         "source_block_hash":"569a3a5a43910ea634a947fd092bb3085359db451235ae59c20daab4e4b0d274",
 139         "source_tx_index":1,
 140         "source_tx_hash":"584d1dcc4dfe741bb3ae5b193896b08db469169e6fd76098eac132af628a3183",
 141         "dest_block_height":0,
 142         "dest_block_timestamp":0,
 143         "dest_block_hash":"",
 144         "dest_tx_index":0,
 145         "dest_tx_hash":"",
 146         "status":"pending",
 147         "crosschain_requests":[
 148           {
 149             "amount":1000000,
 150             "from_address":"bm1qf872k7nr8pwjt4afx60m2wwz5hwj2tu4jaxm9g",
 151             "to_address":"vp1qf872k7nr8pwjt4afx60m2wwz5hwj2tu4eukxq7",
 152             "asset":{
 153               "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
 154             }
 155           }
 156         ]
 157       }
 158     ],
 159     "limit":10,
 160     "start":0
 161   }
 162 }
 163 ```