Address comments

* Move from specs to docs folder
* Attempt to fix markdown links
* Address general comments from the PR
* Remove overview.md due to duplication with readme.md

docs/light/api.md

@@ -25,9 +25,10 @@ similar API.
 
 url: /broadcast_tx_sync
 
-Functionality: Submit a signed transaction and wait for it to be committed.
+Functionality: Submit a signed transaction synchronously. This returns a response from CheckTx.
 
 Parameters:
+
 | Parameter   | Type   | Default | Required | Description     |
 | ----------- | ------ | ------- | -------- | --------------- |
 | transaction | string | null    | true     | signed tx bytes |
@@ -36,14 +37,14 @@ Returns on success:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":200,
-    "error": "",
-    "result": {
-	"code": 0,
-	"hash": "0D33F2F03A5234F38706E43004489E061AC40A2E",
-	"data": "",
-	"log": ""
+    "error":"",
+    "result":{
+	"code":0,
+	"hash":"0D33F2F03A5234F38706E43004489E061AC40A2E",
+	"data":"",
+	"log":""
     }
 }
 ```
@@ -52,10 +53,10 @@ Returns on failure:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":500,
-    "error": "Could not submit the transaction synchronously.",
-    "result": {}
+    "error":"Could not submit the transaction synchronously.",
+    "result":{}
 }
 ```
 
@@ -63,9 +64,10 @@ Returns on failure:
 
 url: /broadcast_tx_async
 
-Functionality: Submit a signed transaction asynchronously.
+Functionality: Submit a signed transaction asynchronously. This does not return a response from CheckTx.
 
 Parameters:
+
 | Parameter   | Type   | Default | Required | Description     |
 | ----------- | ------ | ------- | -------- | --------------- |
 | transaction | string | null    | true     | signed tx bytes |
@@ -74,14 +76,14 @@ Returns on success:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":200,
-    "error": "",
+    "error":"",
     "result": {
-		"code": 0,
-		"hash": "E39AAB7A537ABAA237831742DCE1117F187C3C52",
-		"data": "",
-		"log": ""
+		"code":0,
+		"hash":"E39AAB7A537ABAA237831742DCE1117F187C3C52",
+		"data":"",
+		"log":""
     }
 }
 ```
@@ -90,10 +92,56 @@ Returns on failure:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":500,
-    "error": "Could not submit the transaction asynchronously.",
-    "result": {}
+    "error":"Could not submit the transaction asynchronously.",
+    "result":{}
+}
+```
+
+### /broadcast_tx_commit - POST
+
+url: /broadcast_tx_commit
+
+Functionality: Submit a signed transaction and waits for it to be committed in a block.
+
+Parameters:
+
+| Parameter   | Type   | Default | Required | Description     |
+| ----------- | ------ | ------- | -------- | --------------- |
+| transaction | string | null    | true     | signed tx bytes |
+
+Returns on success:
+
+```json
+{
+    "rest api":"2.0",
+    "code":200,
+    "error":"",
+    "result":{
+        "height":26682,
+        "hash":"75CA0F856A4DA078FC4911580360E70CEFB2EBEE",
+        "deliver_tx":{
+            "log":"",
+            "data":"",
+            "code":0
+        },
+        "check_tx":{
+        "log":"",
+        "data":"",
+        "code":0
+    }
+}
+```
+
+Returns on failure:
+
+```json
+{
+    "rest api":"2.0",
+    "code":500,
+    "error":"Could not commit the transaction.",
+    "result":{}
 }
 ```
 
@@ -111,23 +159,23 @@ Returns on success:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":200,
-    "error": "",
-    "result": {
-        "keys": [
+    "error":"",
+    "result":{
+        "keys":[
            {
-                "name": "monkey",
-                "address": "cosmosaccaddr1fedh326uxqlxs8ph9ej7cf854gz7fd5zlym5pd",
-                "pub_key": "cosmosaccpub1zcjduc3q8s8ha96ry4xc5xvjp9tr9w9p0e5lk5y0rpjs5epsfxs4wmf72x3shvus0t"
+                "name":"monkey",
+                "address":"cosmosaccaddr1fedh326uxqlxs8ph9ej7cf854gz7fd5zlym5pd",
+                "pub_key":"cosmosaccpub1zcjduc3q8s8ha96ry4xc5xvjp9tr9w9p0e5lk5y0rpjs5epsfxs4wmf72x3shvus0t"
             },
             {
-                "name": "test",
-                "address": "cosmosaccaddr1thlqhjqw78zvcy0ua4ldj9gnazqzavyw4eske2",
-                "pub_key": "cosmosaccpub1zcjduc3qyx6hlf825jcnj39adpkaxjer95q7yvy25yhfj3dmqy2ctev0rxmse9cuak"
+                "name":"test",
+                "address":"cosmosaccaddr1thlqhjqw78zvcy0ua4ldj9gnazqzavyw4eske2",
+                "pub_key":"cosmosaccpub1zcjduc3qyx6hlf825jcnj39adpkaxjer95q7yvy25yhfj3dmqy2ctev0rxmse9cuak"
             }
         ],
-        "block_height": 5241
+        "block_height":5241
     }
 }
 ```
@@ -136,7 +184,7 @@ Returns on failure:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":500,
     "error":"Could not retrieve the keys.",
     "result":{}
@@ -150,6 +198,7 @@ url: /keys/recover
 Functionality: Recover your key from seed and persist it encrypted with the password.
 
 Parameter:
+
 | Parameter | Type   | Default | Required | Description      |
 | --------- | ------ | ------- | -------- | ---------------- |
 | name      | string | null    | true     | name of key      |
@@ -160,11 +209,11 @@ Returns on success:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":200,
-    "error": "",
-    "result": {
-        "address":BD607C37147656A507A5A521AA9446EB72B2C907
+    "error":"",
+    "result":{
+        "address":"BD607C37147656A507A5A521AA9446EB72B2C907"
     }
 }
 ```
@@ -173,10 +222,10 @@ Returns on failure:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":500,
-    "error": "Could not recover the key.",
-    "result": {}
+    "error":"Could not recover the key.",
+    "result":{}
 }
 ```
 
@@ -187,6 +236,7 @@ url: /keys/create
 Functionality: Create a new key.
 
 Parameter:
+
 | Parameter | Type   | Default | Required | Description      |
 | --------- | ------ | ------- | -------- | ---------------- |
 | name      | string | null    | true     | name of key      |
@@ -196,11 +246,11 @@ Returns on success:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":200,
-    "error": "",
-    "result": {
-        "seed":crime carpet recycle erase simple prepare moral dentist fee cause pitch trigger when velvet animal abandon
+    "error":"",
+    "result":{
+        "seed":"crime carpet recycle erase simple prepare moral dentist fee cause pitch trigger when velvet animal abandon"
     }
 }
 ```
@@ -209,10 +259,10 @@ Returns on failure:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":500,
-    "error": "Could not create new key.",
-    "result": {}
+    "error":"Could not create new key.",
+    "result":{}
 }
 ```
 
@@ -226,13 +276,13 @@ Returns on success:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":200,
-    "error": "",
-    "result": {
-        "name": "test",
-            "address": "cosmosaccaddr1thlqhjqw78zvcy0ua4ldj9gnazqzavyw4eske2",
-            "pub_key": "cosmosaccpub1zcjduc3qyx6hlf825jcnj39adpkaxjer95q7yvy25yhfj3dmqy2ctev0rxmse9cuak"
+    "error":"",
+    "result":{
+        "name":"test",
+            "address":"cosmosaccaddr1thlqhjqw78zvcy0ua4ldj9gnazqzavyw4eske2",
+            "pub_key":"cosmosaccpub1zcjduc3qyx6hlf825jcnj39adpkaxjer95q7yvy25yhfj3dmqy2ctev0rxmse9cuak"
     }
 }
 ```
@@ -241,10 +291,10 @@ Returns on failure:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":500,
-    "error": "Could not find information on the specified key.",
-    "result": {}
+    "error":"Could not find information on the specified key.",
+    "result":{}
 }
 ```
 
@@ -255,6 +305,7 @@ url: /keys/{name}
 Functionality: Change the encryption password for the specified key.
 
 Parameters:
+
 | Parameter       | Type   | Default | Required | Description     |
 | --------------- | ------ | ------- | -------- | --------------- |
 | old_password    | string | null    | true     | old password    |
@@ -264,10 +315,10 @@ Returns on success:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":200,
-    "error": "",
-    "result": {}
+    "error":"",
+    "result":{}
 }
 ```
 
@@ -275,10 +326,10 @@ Returns on failure:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":500,
-    "error": "Could not update the specified key.",
-    "result": {}
+    "error":"Could not update the specified key.",
+    "result":{}
 }
 ```
 
@@ -289,6 +340,7 @@ url: /keys/{name}
 Functionality: Delete the specified key.
 
 Parameters:
+
 | Parameter | Type   | Default | Required | Description      |
 | --------- | ------ | ------- | -------- | ---------------- |
 | password  | string | null    | true     | password of key  |
@@ -297,10 +349,10 @@ Returns on success:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":200,
-    "error": "",
-    "result": {}
+    "error":"",
+    "result":{}
 }
 ```
 
@@ -308,10 +360,10 @@ Returns on failure:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":500,
-    "error": "Could not delete the specified key.",
-    "result": {}
+    "error":"Could not delete the specified key.",
+    "result":{}
 }
 ```
 
@@ -329,13 +381,13 @@ Returns on success:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":200,
-    "error": "",
+    "error":"",
     "result": {
-        "atom": 1000,
-        "photon": 500,
-        "ether": 20
+        "atom":1000,
+        "photon":500,
+        "ether":20
     }
 }
 ```
@@ -344,10 +396,10 @@ Returns on error:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":500,
-    "error": "Could not find any balance for the specified account.",
-    "result": {}
+    "error":"Could not find any balance for the specified account.",
+    "result":{}
 }
 ```
 
@@ -358,6 +410,7 @@ url: /bank/create_transfer
 Functionality: Create a transfer in the bank module.
 
 Parameters:
+
 | Parameter    | Type   | Default | Required | Description               |
 | ------------ | ------ | ------- | -------- | ------------------------- |
 | sender       | string | null    | true     | Address of sender         |
@@ -370,11 +423,11 @@ Returns on success:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":200,
-    "error": "",
-    "result": {
-     "transaction": "TODO:<JSON sign bytes for the transaction>"
+    "error":"",
+    "result":{
+     "transaction":"TODO:<JSON sign bytes for the transaction>"
     }
 }
 ```
@@ -383,9 +436,9 @@ Returns on failure:
 
 ```json
 {
-    "rest api": "2.0",
+    "rest api":"2.0",
     "code":500,
-    "error": "Could not create the transaction.",
-    "result": {}
+    "error":"Could not create the transaction.",
+    "result":{}
 }
 ```

docs/light/getting_started.md

@@ -22,19 +22,19 @@ make transaction faster and more reliable in the following cases.
 
 ### Create an account
 
-![deposit](https://github.com/irisnet/cosmos-sdk/raw/bianjie/lcd_spec/docs/spec/lcd/pics/create-account.png)
+![deposit](pics/create-account.png)
 
-First you need to get a new seed phrase :[get-seed](https://github.com/irisnet/cosmos-sdk/blob/bianjie/lcd_spec/docs/spec/lcd/api.md#keysseed---get)
+First you need to get a new seed phrase :[get-seed](api.md#keysseed---get)
 
-After having new seed, you could generate a new account with it : [keys](https://github.com/irisnet/cosmos-sdk/blob/bianjie/lcd_spec/docs/spec/lcd/api.md#keys---post)
+After having new seed, you could generate a new account with it : [keys](api.md#keys---post)
 
 ### Transfer a token
 
-![transfer](https://github.com/irisnet/cosmos-sdk/raw/bianjie/lcd_spec/docs/spec/lcd/pics/transfer-tokens.png)
+![transfer](pics/transfer-tokens.png)
 
 The first step is to build an asset transfer transaction. Here we can post all necessary parameters
 to /create_transfer to get the unsigned transaction byte array. Refer to this link for detailed
-operation: [build transaction](https://github.com/irisnet/cosmos-sdk/blob/bianjie/lcd_spec/docs/spec/lcd/api.md#create_transfer---post)
+operation: [build transaction](api.md#create_transfer---post)
 
 Then sign the returned transaction byte array with users' private key. Finally broadcast the signed
-transaction. Refer to this link for how to broadcast the signed transaction: [broadcast transaction](https://github.com/irisnet/cosmos-sdk/blob/bianjie/lcd_spec/docs/spec/lcd/api.md#create_transfer---post)
+transaction. Refer to this link for how to broadcast the signed transaction: [broadcast transaction](api.md#create_transfer---post)

docs/light/load_balancer.md

@@ -1,4 +1,4 @@
-# Load Balancing Module
+# Load Balancing Module - WIP
 
 The LCD will be an important bridge between service providers and cosmos blockchain network. Suppose
 a service provider wants to monitor token information for millions of accounts. Then it has to keep

docs/light/readme.md

@@ -16,11 +16,10 @@ LCD will be used in the Cosmos Hub, the first Hub in the Cosmos network.
 
 ## Contents
 
-1. [**Overview**](#Overview)
-2. [**Get Started**](https://github.com/irisnet/cosmos-sdk/blob/bianjie/lcd_spec/docs/spec/lcd/getting_started.md)
-3. [**API**](https://github.com/irisnet/cosmos-sdk/blob/bianjie/lcd_spec/docs/spec/lcd/api.md)
-4. [**Specifications**](https://github.com/irisnet/cosmos-sdk/blob/bianjie/lcd_spec/docs/spec/lcd/specification.md)
-5. [**Future Improvements**](https://github.com/irisnet/cosmos-sdk/blob/bianjie/lcd_spec/docs/spec/lcd/Future%20Improvements.md)
+1. [**Overview**](##Overview)
+2. [**Get Started**](getting_started.md)
+3. [**API**](api.md)
+4. [**Specifications**](hspecification.md)
 
 ## Overview
 
@@ -40,7 +39,7 @@ An application developer that would like to build a third party integration can
 with the LCD for the Cosmos Hub (or any other zone) and only needs to initialise it. Afterwards his
 application can interact with the zone as if it was running against a full node.
 
-![high-level](https://github.com/irisnet/cosmos-sdk/raw/bianjie/lcd_spec/docs/spec/lcd/pics/high-level.png)
+![high-level](pics/high-level.png)
 
 An application developer that wants to build an third party application for the Cosmos Hub (or any
 other zone) should build it against it's canonical API. That API is a combination of multiple parts.
@@ -60,15 +59,15 @@ A full node of ABCI is different from its light client in the following ways:
 |-| ------------- | ----- | -------------- |
 | Execute and verify transactions|Yes|No|Full node will execute and verify all transactions while LCD won't|
 | Verify and save blocks|Yes|No|Full node will verify and save all blocks while LCD won't|
-| Participate consensus| Yes|No|Only when the full node is a validator, it will participate consensus. LCD nodes never participate consensus|
+| Participate consensus| Yes|No|Only when the full node is a validtor, it will participate consensus. LCD nodes never participate consensus|
 | Bandwidth cost|Huge|Little|Full node will receive all blocks. if the bandwidth is limited, it will fall behind the main network. What's more, if it happens to be a validator,it will slow down the consensus process. LCD requires little bandwidth. Only when serving local request, it will cost bandwidth|
 | Computing resource|Huge|Little|Full node will execute all transactions and verify all blocks which require much computing resource|
 | Storage resource|Huge|Little|Full node will save all blocks and ABCI states. LCD just saves validator sets and some checkpoints|
 | Power consume|Huge|Little|Full nodes have to be deployed on machines which have high performance and will be running all the time. So power consume will be huge. LCD can be deployed on the same machines as users' applications, or on independent machines but with poor performance. Besides, LCD can be shutdown anytime when necessary. So LCD only consume very little power, even mobile devices can meet the power requirement|
 | Provide APIs|All cosmos APIs|Modular APIs|Full node supports all cosmos APIs. LCD provides modular APIs according to users' configuration|
-| Security level| High|High|Full node will verify all transactions and blocks by itself. LCD can't do this, but it can query any data from other full nodes and verify the data independently. So both full node and LCD don't need to trust any third nodes, they all can achieve high security|
+| Secuity level| High|High|Full node will verify all transactions and blocks by itself. LCD can't do this, but it can query any data from other full nodes and verify the data independently. So both full node and LCD don't need to trust any third nodes, they all can achieve high security|
 
-According to the above table, LCD can meet all users' functionality and security requirements, but
+According to the above table, LCD can meet all users' functionality and security requirements, but 
 only requires little resource on bandwidth, computing, storage and power.
 
 ## How does LCD achieve high security?
@@ -84,7 +83,7 @@ The original trusted validator set should be prepositioned into its trust store,
 validator set comes from genesis file. During running time, if LCD detects different validator set,
 it will verify it and save new validated validator set to trust store.
 
-![validator-set-change](https://github.com/irisnet/cosmos-sdk/raw/bianjie/lcd_spec/docs/spec/lcd/pics/validatorSetChange.png)
+![validator-set-change](pics/validatorSetChange.png)
 
 ### Trust propagation
 
@@ -93,7 +92,7 @@ validator set evolution. Validator set is the foundation of trust, and the trust
 other blockchain data, such as block and transaction. The propagate architecture is shown as
 follows:
 
-![change-process](https://github.com/irisnet/cosmos-sdk/raw/bianjie/lcd_spec/docs/spec/lcd/pics/trustPropagate.png)
+![change-process](pics/trustPropagate.png)
 
 In general, by trusted validator set, LCD can verify each block commit which contains all pre-commit
 data and block header data. Then the block hash, data hash and appHash are trusted. Based on this

docs/spec/light/overview.md

@@ -1,55 +0,0 @@
-# Overview
-
-## What is a Light Client?
-
- The LCD is split into two separate components. The first component is generic for any Tendermint based application. It handles the security and connectivity aspects of following the header chain and verify proofs from full nodes against locally trusted validator set. Furthermore it exposes exactly the same API as any Tendermint Core node. The second component is specific for the Cosmos Hub (Gaiad). It works as a query endpoint and exposes the application specific functionality, which can be arbitrary. All queries against the application state have to go through the query endpoint. The advantage of the query endpoint is that it can verify the proofs that the application returns.
-
-## High-Level Architecture
-
-An application developer that would like to build a third party integration can ship his application with the LCD for the Cosmos Hub (or any other zone) and only needs to initialise it. Afterwards his application can interact with the zone as if it was running against a full node.
-
-![high-level](https://github.com/irisnet/cosmos-sdk/raw/bianjie/lcd_spec/docs/spec/lcd/pics/high-level.png)
-
-An application developer that wants to build an third party application for the Cosmos Hub (or any other zone) should build it against it's canonical API. That API is a combination of multiple parts. All zones have to expose ICS0 (TendermintAPI). Beyond that any zone is free to choose any combination of module APIs, depending on which modules the state machine uses. The Cosmos Hub will initially support ICS0 (TendermintAPI), ICS1 (KeyAPI), ICS20 (TokenAPI), ICS21 (StakingAPI) and ICS22 (GovernanceAPI).
-
-All applications are expected to only run against the LCD. The LCD is the only piece of software that offers stability guarantees around the zone API.
-
-### Comparision
-
-A full node of ABCI is different from its light client in the following ways:
-
-|| Full Node | LCD | Description|
-|-| ------------- | ----- | -------------- |
-| Execute and verify transactions|Yes|No|Full node will execute and verify all transactions while LCD won't|
-| Verify and save blocks|Yes|No|Full node will verify and save all blocks while LCD won't|
-| Participate consensus| Yes|No|Only when the full node is a validtor, it will participate consensus. LCD nodes never participate consensus|
-| Bandwidth cost|Huge|Little|Full node will receive all blocks. if the bandwidth is limited, it will fall behind the main network. What's more, if it happens to be a validator,it will slow down the consensus process. LCD requires little bandwidth. Only when serving local request, it will cost bandwidth|
-| Computing resource|Huge|Little|Full node will execute all transactions and verify all blocks which require much computing resource|
-| Storage resource|Huge|Little|Full node will save all blocks and ABCI states. LCD just saves validator sets and some checkpoints|
-| Power consume|Huge|Little|Full nodes have to be deployed on machines which have high performance and will be running all the time. So power consume will be huge. LCD can be deployed on the same machines as users' applications, or on independent machines but with poor performance. Besides, LCD can be shutdown anytime when necessary. So LCD only consume very little power, even mobile devices can meet the power requirement|
-| Provide APIs|All cosmos APIs|Modular APIs|Full node supports all cosmos APIs. LCD provides modular APIs according to users' configuration|
-| Secuity level| High|High|Full node will verify all transactions and blocks by itself. LCD can't do this, but it can query any data from other full nodes and verify the data independently. So both full node and LCD don't need to trust any third nodes, they all can achieve high security|
-
-According to the above table, LCD can meet all users' functionality and security requirements, but only requires little resource on bandwidth, computing, storage and power.
-
-## How does LCD achieve high security?
-
-### Trusted validator set
-
-The base design philosophy of lcd follows the two rules:
-
-1. **Doesn't trust any blockchin nodes, including validator nodes and other full nodes**
-2. **Only trusts the whole validator set**
-
-The original trusted validator set should be prepositioned into its trust store, usually this validator set comes from genesis file. During running time, if LCD detects different validator set, it will verify it and save new validated validator set to trust store.
-
-![validator-set-change](https://github.com/irisnet/cosmos-sdk/raw/bianjie/lcd_spec/docs/spec/lcd/pics/validatorSetChange.png)
-
-
-### Trust propagation
-
-From the above section, we come to know how to get trusted validator set and how lcd keeps track of validator set evolution. Validator set is the foundation of trust, and the trust can propagate to other blockchain data, such as block and transaction. The propagate architecture is shown as follows:
-
-![change-process](https://github.com/irisnet/cosmos-sdk/raw/bianjie/lcd_spec/docs/spec/lcd/pics/trustPropagate.png)
-
-In general, by trusted validator set, LCD can verify each block commit which contains all pre-commit data and block header data. Then the block hash, data hash and appHash are trusted. Based on this and merkle proof, all transactions data and ABCI states can be verified too. Detailed implementation will be posted on technical specification.