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