OSDN Git Service

00eb5ac59fd2850d34dcfbab325ddd4cd45830ea
[bytom/vapor.git] / 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 <!--  -->
89
90 Optional:
91
92 - `Object` - *filter*, transactions filter.
93     + Optional
94         * `String` - *status*, transactions status, which can be `pending` or `completed`.
95         * `String` - *source_chain_name*, transactions source chain, which can be `bytom` or `vapor`.
96         * `String` - *source_tx_hash*, souce transaction hash string.
97         * `String` - *dest_tx_hash*, destination transaction hash string.
98 - `Object` - *sort*, transactions sorter.
99     + Optional
100         * `String` - *order*, transactions order sorter, which can be `asc` or `desc`.
101
102
103 ##### Returns
104
105
106 `Object`:
107
108 - `String` - *source_chain_name*, source chain name of the cross-chain transaction.
109 - `Integer` - *source_block_height*, block height of the cross-chain transaction on the source chain.
110 - `String` - *source_block_hash*, block hash of the cross-chain transaction on the source chain.
111 - `Integer` - *source_tx_index*, transaction index in the source block.
112 - `String` - *source_tx_hash*, source transaction hash.
113 - `Integer` - *dest_block_height*, block height 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     + `Object` - *asset*, asset detail.
121         * `String` - *asset_id*, asset id string.
122
123 ##### Example
124
125 ```js
126 // Request
127 curl -X POST 127.0.0.1:3000/api/v1/federation/list-crosschain-txs -d '{}'
128
129 // Result
130 {
131   "code":200,
132   "msg":"",
133   "result":{
134     "_links":{
135
136     },
137     "data":[
138       {
139         "source_chain_name":"bytom",
140         "source_block_height":174,
141         "source_block_hash":"569a3a5a43910ea634a947fd092bb3085359db451235ae59c20daab4e4b0d274",
142         "source_tx_index":1,
143         "source_tx_hash":"584d1dcc4dfe741bb3ae5b193896b08db469169e6fd76098eac132af628a3183",
144         "dest_block_height":0,
145         "dest_block_hash":"",
146         "dest_tx_index":0,
147         "dest_tx_hash":"",
148         "status":"pending",
149         "crosschain_requests":[
150           {
151             "amount":1000000,
152             "asset":{
153               "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
154             }
155           }
156         ]
157       }
158     ],
159     "limit":10,
160     "start":0
161   }
162 }
163 ```