feat(federation): add address and timestamp (#223)

[bytom/vapor.git] / docs / federation / README-en.md

diff --git a/docs/federation/README-en.md b/docs/federation/README-en.md
index c6e05b9..00eb5ac 100644 (file)
--- a/docs/federation/README-en.md
+++ b/docs/federation/README-en.md
@@ -11,7 +11,7 @@ A `fed_cfg.json` would look like this:
 
 ```json
 {
-    "gin-gonic" : {
+    "api" : {
         "listening_port" : 3000,
         "is_release_mode": false
     },
@@ -28,23 +28,10 @@ A `fed_cfg.json` would look like this:
     "warders" : [
         {
             "position" : 1,
-            "xpub" : "7f23aae65ee4307c38d342699e328f21834488e18191ebd66823d220b5a58303496c9d09731784372bade78d5e9a4a6249b2cfe2e3a85464e5a4017aa5611e47",
-            "host_port" : "192.168.0.2:3000",
-            "is_local" : false
-        },
-        {
-            "position" : 1,
-            "xpub" : "585e20143db413e45fbc82f03cb61f177e9916ef1df0012daa8cbf6dbb1025ce8f98e51ae319327b63505b64fdbbf6d36ef916d79e6dd67d51b0bfe76fe544c5",
-            "host_port" : "127.0.0.1:3000",
-            "is_local" : true
-        },
-        {
-            "position" : 1,
-            "xpub" : "b58170b51ca61604028ba1cb412377dfc2bc6567c0afc84c83aae1c0c297d0227ccf568561df70851f4144bbf069b525129f2434133c145e35949375b22a6c9d",
-            "host_port" : "192.168.0.3:3000",
-            "is_local" : false
+            "xpub" : "50ef22b3a3fca7bc08916187cc9ec2f4005c9c6b1353aa1decbd4be3f3bb0fbe1967589f0d9dec13a388c0412002d2c267bdf3b920864e1ddc50581be5604ce1"
         }
     ],
+    "quorum": 1,
     "mainchain" : {
         "name" : "bytom",
         "confirmations" : 10,
@@ -59,3 +46,118 @@ A `fed_cfg.json` would look like this:
     }
 }
 ```
+## API
+A federation node can function as an api server for querying cross-chain transactions.
+
+The default JSON-RPC endpoint is: [http://host:port/api/v1/federation/](http://host:port/api/v1/federation/)
+
+The response contains some meta data of:
+
++ success/error status, which can be told from `code` and `msg`;
++ pagination info, which can be told from `start`, `limit` and `_links` (`_links` is used to look up the preceding and the succeeding items);
+
+and looks like:
+```
+{
+  "code":200,
+  "msg":"",
+  "result":{
+    "_links":{
+    },
+    "data":...,
+    "limit":10,
+    "start":0
+  }
+}
+```
+
+If a request succeed, `data` field contains the detailed result as an object or as an array of objects.
+
+### Pagination
+
+Append `?start=<integer>&limit=<integer>` to the url in order to use pagination.
+
+### Methods
+
+#### `/list-crosschain-txs`
+
+To list cross-chain transactions and filter the transactions.
+
+##### Parameters
+
+<!--  -->
+
+Optional:
+
+- `Object` - *filter*, transactions filter.
+    + Optional
+        * `String` - *status*, transactions status, which can be `pending` or `completed`.
+        * `String` - *source_chain_name*, transactions source chain, which can be `bytom` or `vapor`.
+        * `String` - *source_tx_hash*, souce transaction hash string.
+        * `String` - *dest_tx_hash*, destination transaction hash string.
+- `Object` - *sort*, transactions sorter.
+    + Optional
+        * `String` - *order*, transactions order sorter, which can be `asc` or `desc`.
+
+
+##### Returns
+
+
+`Object`:
+
+- `String` - *source_chain_name*, source chain name of the cross-chain transaction.
+- `Integer` - *source_block_height*, block height of the cross-chain transaction on the source chain.
+- `String` - *source_block_hash*, block hash of the cross-chain transaction on the source chain.
+- `Integer` - *source_tx_index*, transaction index in the source block.
+- `String` - *source_tx_hash*, source transaction hash.
+- `Integer` - *dest_block_height*, block height of the cross-chain transaction on the destination chain, `0` if `status` is `pending`.
+- `String` - *dest_block_hash*, block hash of the cross-chain transaction on the destination chain, empty string if `status` is `pending`.
+- `Integer` - *dest_tx_index*, transaction index in the destination block, `0` if `status` is `pending`.
+- `String` - *dest_tx_hash*, destination transaction hash, empty string if `status` is `pending`.
+- `String` - *status*, cross-chain transaction status, can be `pending` or `completed`.
+- `Array of objects` - *crosschain_requests*, asset transfer details per request included in the cross-chain transaction.
+    + `Integer` - *amount*, asset transfer amount.
+    + `Object` - *asset*, asset detail.
+        * `String` - *asset_id*, asset id string.
+
+##### Example
+
+```js
+// Request
+curl -X POST 127.0.0.1:3000/api/v1/federation/list-crosschain-txs -d '{}'
+
+// Result
+{
+  "code":200,
+  "msg":"",
+  "result":{
+    "_links":{
+
+    },
+    "data":[
+      {
+        "source_chain_name":"bytom",
+        "source_block_height":174,
+        "source_block_hash":"569a3a5a43910ea634a947fd092bb3085359db451235ae59c20daab4e4b0d274",
+        "source_tx_index":1,
+        "source_tx_hash":"584d1dcc4dfe741bb3ae5b193896b08db469169e6fd76098eac132af628a3183",
+        "dest_block_height":0,
+        "dest_block_hash":"",
+        "dest_tx_index":0,
+        "dest_tx_hash":"",
+        "status":"pending",
+        "crosschain_requests":[
+          {
+            "amount":1000000,
+            "asset":{
+              "asset_id":"ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
+            }
+          }
+        ]
+      }
+    ],
+    "limit":10,
+    "start":0
+  }
+}
+```