From ce23ad41ce7bc53494c80a2d73fdc1c9e39f7ec7 Mon Sep 17 00:00:00 2001 From: Zach Date: Wed, 17 Oct 2018 20:46:03 -0400 Subject: [PATCH] Merge PR #2447: Cleanup docs/light --- docs/.vuepress/config.js | 8 + docs/light/api.md | 961 ------------------ docs/light/load_balancer.md | 203 ---- docs/light/todo.md | 16 - docs/{light => lite}/getting_started.md | 31 +- docs/{light => lite}/pics/C2H.png | Bin docs/{light => lite}/pics/H2C.png | Bin docs/{light => lite}/pics/MA.png | Bin docs/{light => lite}/pics/absence1.png | Bin docs/{light => lite}/pics/absence2.png | Bin docs/{light => lite}/pics/absence3.png | Bin docs/{light => lite}/pics/architecture.png | Bin docs/{light => lite}/pics/changeProcess.png | Bin .../{light => lite}/pics/commitValidation.png | Bin docs/{light => lite}/pics/create-account.png | Bin docs/{light => lite}/pics/deposit.png | Bin docs/{light => lite}/pics/existProof.png | Bin docs/{light => lite}/pics/high-level.png | Bin .../pics/light-client-architecture.png | Bin .../pics/loadbalanceDiagram.png | Bin .../{light => lite}/pics/simpleMerkleTree.png | Bin docs/{light => lite}/pics/substoreProof.png | Bin docs/{light => lite}/pics/transfer-tokens.png | Bin docs/{light => lite}/pics/transfer.png | Bin docs/{light => lite}/pics/trustPropagate.png | Bin .../pics/updateValidatorToHeight.png | Bin .../pics/validatorSetChange.png | Bin docs/{light => lite}/pics/withdraw.png | Bin docs/{light => lite}/readme.md | 43 +- docs/{light => lite}/specification.md | 147 --- 30 files changed, 29 insertions(+), 1380 deletions(-) delete mode 100644 docs/light/api.md delete mode 100644 docs/light/load_balancer.md delete mode 100644 docs/light/todo.md rename docs/{light => lite}/getting_started.md (59%) rename docs/{light => lite}/pics/C2H.png (100%) rename docs/{light => lite}/pics/H2C.png (100%) rename docs/{light => lite}/pics/MA.png (100%) rename docs/{light => lite}/pics/absence1.png (100%) rename docs/{light => lite}/pics/absence2.png (100%) rename docs/{light => lite}/pics/absence3.png (100%) rename docs/{light => lite}/pics/architecture.png (100%) rename docs/{light => lite}/pics/changeProcess.png (100%) rename docs/{light => lite}/pics/commitValidation.png (100%) rename docs/{light => lite}/pics/create-account.png (100%) rename docs/{light => lite}/pics/deposit.png (100%) rename docs/{light => lite}/pics/existProof.png (100%) rename docs/{light => lite}/pics/high-level.png (100%) rename docs/{light => lite}/pics/light-client-architecture.png (100%) rename docs/{light => lite}/pics/loadbalanceDiagram.png (100%) rename docs/{light => lite}/pics/simpleMerkleTree.png (100%) rename docs/{light => lite}/pics/substoreProof.png (100%) rename docs/{light => lite}/pics/transfer-tokens.png (100%) rename docs/{light => lite}/pics/transfer.png (100%) rename docs/{light => lite}/pics/trustPropagate.png (100%) rename docs/{light => lite}/pics/updateValidatorToHeight.png (100%) rename docs/{light => lite}/pics/validatorSetChange.png (100%) rename docs/{light => lite}/pics/withdraw.png (100%) rename docs/{light => lite}/readme.md (81%) rename docs/{light => lite}/specification.md (67%) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 4042de37eb..5f09b5bb0c 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -68,6 +68,14 @@ module.exports = { "/sdk/sdk-by-examples/simple-governance/running-the-application" ] }, + { + title: "Light Client", + collapsable: false, + children: [ + "/light/", + "/light/getting_started" + ] + }, { title: "Lotion JS", collapsable: false, diff --git a/docs/light/api.md b/docs/light/api.md deleted file mode 100644 index 7fbf9fbe19..0000000000 --- a/docs/light/api.md +++ /dev/null @@ -1,961 +0,0 @@ -# Cosmos Hub (Gaia-Lite) LCD API - -This document describes the API that is exposed by the specific Light Client Daemon (LCD) implementation of the Cosmos Hub (Gaia). Those APIs are exposed by a REST server and can easily be accessed over HTTP/WS (websocket) -connections. - -The complete API is comprised of the sub-APIs of different modules. The modules in the Cosmos Hub (Gaia-Lite) API are: - -- ICS0 ([TendermintAPI](api.md#ics0---tendermintapi)) -- ICS1 ([KeyAPI](api.md#ics1---keyapi)) -- ICS20 ([TokenAPI](api.md#ics20---tokenapi)) -- ICS21 ([StakingAPI](api.md#ics21---stakingapi)) -- ICS22 ([GovernanceAPI](api.md#ics22---governanceapi)) -- ICS23 ([SlashingAPI](api.md#ics23---slashingapi)) - -Error messages my change and should be only used for display purposes. Error messages should not be -used for determining the error type. - -## ICS0 - TendermintAPI - -Exposes the same functionality as the Tendermint RPC from a full node. It aims to have a very similar API. - -### POST /txs - -- **URL**: `/txs` -- Query Parameters: - - `?return={sync|async|block}`: - - `return=sync`: Waits for the transaction to pass `CheckTx` - - `return=async`: Returns the request immediately after it is received by the server - - `return=block`: waits for for the transaction to be committed in a block -- POST Body: - -```json -{ - "transaction": "string", - "return": "string", -} -``` - -- Returns on success: - -```json -{ - "rest api":"2.0", - "code":200, - "error":"", - "result":{ - "code":0, - "hash":"0D33F2F03A5234F38706E43004489E061AC40A2E", - "data":"", - "log":"" - } -} -``` - -## ICS1 - KeyAPI - -This API exposes all functionality needed for key creation, signing and management. - -### GET /keys - -- **URL**: `/keys` -- **Functionality**: Gets a list of all the keys. -- Returns on success: - -```json -{ - "rest api":"1.0", - "code":200, - "error":"", - "result":{ - "account":[ - { - "name":"monkey", - "address":"cosmos1fedh326uxqlxs8ph9ej7cf854gz7fd5zlym5pd", - "pub_key":"cosmospub1zcjduc3q8s8ha96ry4xc5xvjp9tr9w9p0e5lk5y0rpjs5epsfxs4wmf72x3shvus0t" - }, - { - "name":"test", - "address":"cosmos1thlqhjqw78zvcy0ua4ldj9gnazqzavyw4eske2", - "pub_key":"cosmospub1zcjduc3qyx6hlf825jcnj39adpkaxjer95q7yvy25yhfj3dmqy2ctev0rxmse9cuak" - } - ], - "block_height":5241 - } -} -``` - -### POST /keys - -- **URL**: `/keys` -- **Functionality**: Create a new key. -- POST Body: - -```json -{ - "name": "string", - "password": "string", - "seed": "string", -} -``` - -Returns on success: - -```json -{ - "rest api":"1.0", - "code":200, - "error":"", - "result":{ - "seed":"crime carpet recycle erase simple prepare moral dentist fee cause pitch trigger when velvet animal abandon" - } -} -``` - -### GET /keys/{name} - -- **URL** : `/keys/{name}` -- **Functionality**: Get the information for the specified key. -- Returns on success: - -```json -{ - "rest api":"1.0", - "code":200, - "error":"", - "result":{ - "name":"test", - "address":"cosmos1thlqhjqw78zvcy0ua4ldj9gnazqzavyw4eske2", - "pub_key":"cosmospub1zcjduc3qyx6hlf825jcnj39adpkaxjer95q7yvy25yhfj3dmqy2ctev0rxmse9cuak" - } -} -``` - -### PUT /keys/{name} - -- **URL** : `/keys/{name}` -- **Functionality**: Change the encryption password for the specified key. -- PUT Body: - -```json -{ - "old_password": "string", - "new_password": "string", -} -``` - -- Returns on success: - -```json -{ - "rest api":"2.0", - "code":200, - "error":"", - "result":{} -} -``` - -### DELETE /keys/{name} - -- **URL**: `/keys/{name}` -- **Functionality**: Delete the specified key. -- DELETE Body: - -```json -{ - "password": "string", -} -``` - -- Returns on success: - -```json -{ - "rest api":"1.0", - "code":200, - "error":"", - "result":{} -} -``` - -### POST /keys/{name}/recover - -- **URL**: `/keys/{name}/recover` -- **Functionality**: Recover your key from seed and persist it encrypted with the password. -- POST Body: - -```json -{ - "password": "string", - "seed": "string", -} -``` - -- Returns on success: - -```json -{ - "rest api":"1.0", - "code":200, - "error":"", - "result":{ - "address":"BD607C37147656A507A5A521AA9446EB72B2C907" - } -} -``` - -### GET /auth/accounts/{address} - -- **URL**: `/auth/accounts/{address}` -- **Functionality**: Query the information of an account . -- Returns on success: - -```json -{ - "rest api":"1.0", - "code":200, - "error":"", - "result":{ - "address": "82A57F8575BDFA22F5164C75361A21D2B0E11089", - "public_key": "PubKeyEd25519{A0EEEED3C9CE1A6988DEBFE347635834A1C0EBA0B4BB1125896A7072D22E650D}", - "coins": [ - {"atom": 300}, - {"photon": 15} - ], - "account_number": 1, - "sequence": 7 - } -} -``` - -### POST /auth/tx/sign - -- **URL**: `/auth/tx/sign` -- **Functionality**: Sign a transaction without broadcasting it. -- Returns on success: - -```json -{ - "rest api": "1.0", - "code": 200, - "error": "", - "result": { - "type": "auth/StdTx", - "value": { - "msg": [ - { - "type": "cosmos-sdk/Send", - "value": { - "inputs": [ - { - "address": "cosmos1ql4ekxkujf3xllk8h5ldhhgh4ylpu7kwec6q3d", - "coins": [ - { - "denom": "steak", - "amount": "1" - } - ] - } - ], - "outputs": [ - { - "address": "cosmos1dhyqhg4px33ed3erqymls0hc7q2lxw9hhfwklj", - "coins": [ - { - "denom": "steak", - "amount": "1" - } - ] - } - ] - } - } - ], - "fee": { - "amount": [ - { - "denom": "", - "amount": "0" - } - ], - "gas": "2742" - }, - "signatures": [ - { - "pub_key": { - "type": "tendermint/PubKeySecp256k1", - "value": "A2A/f2IYnrPUMTMqhwN81oas9jurtfcsvxdeLlNw3gGy" - }, - "signature": "MEQCIGVn73y9QLwBa3vmsAD1bs3ygX75Wo+lAFSAUDs431ZPAiBWAf2amyqTCDXE9J87rL9QF9sd5JvVMt7goGSuamPJwg==", - "account_number": "1", - "sequence": "0" - } - ], - "memo": "" - } - } -} -``` - -### POST /auth/tx/broadcast - -- **URL**: `/auth/broadcast` -- **Functionality**: Broadcast a transaction. -- Returns on success: - -```json -{ - "rest api": "1.0", - "code": 200, - "error": "", - "result": - { - "check_tx": { - "log": "Msg 0: ", - "gasWanted": "2742", - "gasUsed": "1002" - }, - "deliver_tx": { - "log": "Msg 0: ", - "gasWanted": "2742", - "gasUsed": "2742", - "tags": [ - { - "key": "c2VuZGVy", - "value": "Y29zbW9zMXdjNTl6ZXU3MmNjdnp5ZWR6ZGE1N3pzcXh2eXZ2Y3poaHBhdDI4" - }, - { - "key": "cmVjaXBpZW50", - "value": "Y29zbW9zMTJ4OTNmY3V2azg3M3o1ejZnejRlNTl2dnlxcXp1eDdzdDcwNWd5" - } - ] - }, - "hash": "784314784503582AC885BD6FB0D2A5B79FF703A7", - "height": "5" - } -} -``` - -## ICS20 - TokenAPI - -The TokenAPI exposes all functionality needed to query account balances and send transactions. - -### GET /bank/balance/{account} - -- **URL**: `/bank/balance/{account}` -- **Functionality**: Query the specified account's balance. -- Returns on success: - -```json -{ - "rest api":"2.0", - "code":200, - "error":"", - "result": { - "atom":1000, - "photon":500, - "ether":20 - } -} -``` - -### POST /bank/transfers - -- **URL**: `/bank/transfers` -- **Functionality**: Create a transfer in the bank module. -- POST Body: - -```json -{ - "amount": [ - { - "denom": "string", - "amount": 64, - } - ], - "name": "string", - "password": "string", - "chain_id": "string", - "account_number": 64, - "sequence": 64, - "gas": 64, -} -``` - -- Returns on success: - -```json -{ - "rest api":"2.0", - "code":200, - "error":"", - "result":{ - "transaction":"TODO:" - } -} -``` - -## ICS21 - StakingAPI - -The StakingAPI exposes all functionality needed for validation and delegation in Proof-of-Stake. - -### GET /stake/delegators/{delegatorAddr} - -- **URL**: `/stake/delegators/{delegatorAddr}` -- **Functionality**: Get all delegations (delegation, undelegation) from a delegator. -- Returns on success: - -```json -{ - "rest api":"2.1", - "code":200, - "error":"", - "result": { - "atom":1000, - "photon":500, - "ether":20 - } -} -``` - -### GET /stake/delegators/{delegatorAddr}/validators - -- **URL**: `/stake/delegators/{delegatorAddr}/validators` -- **Functionality**: Query all validators that a delegator is bonded to. -- Returns on success: - -```json -{ - "rest api":"2.1", - "code":200, - "error":"", - "result":{} -} -``` - -### GET /stake/delegators/{delegatorAddr}/validators/{validatorAddr} - -- **URL**: `/stake/delegators/{delegatorAddr}/validators/{validatorAddr}` -- **Functionality**: Query a validator that a delegator is bonded to -- Returns on success: - -```json -{ - "rest api":"2.1", - "code":200, - "error":"", - "result":{} -} -``` - -### GET /stake/delegators/{delegatorAddr}/txs - -- **URL**: `/stake/delegators/{delegatorAddr}/txs` -- **Functionality**: Get all staking txs (i.e msgs) from a delegator. -- Returns on success: - -```json -{ - "rest api":"2.1", - "code":200, - "error":"", - "result":{ - "transaction":"TODO" - } -} -``` - -### POST /stake/delegators/{delegatorAddr}/delegations - -- **URL**: `/stake/delegators/{delegatorAddr}/delegations` -- **Functionality**: Submit or edit a delegation. - -- POST Body: - -```json -{ - "name": "string", - "password": "string", - "chain_id": "string", - "account_number": 64, - "sequence": 64, - "gas": 64, - "delegations": [ - { - "delegator_addr": "string", - "validator_addr": "string", - "delegation": { - "denom": "string", - "amount": 1234 - } - } - ], - "begin_unbondings": [ - { - "delegator_addr": "string", - "validator_addr": "string", - "shares": "string", - } - ], - "complete_unbondings": [ - { - "delegator_addr": "string", - "validator_addr": "string", - } - ], - "begin_redelegates": [ - { - "delegator_addr": "string", - "validator_src_addr": "string", - "validator_dst_addr": "string", - "shares": "string", - } - ], - "complete_redelegates": [ - { - "delegator_addr": "string", - "validator_src_addr": "string", - "validator_dst_addr": "string", - } - ] -} - -``` - -- Returns on success: - -```json -{ - "rest api":"2.1", - "code":200, - "error":"", - "result":{ - "transaction":"TODO" - } -} -``` - -### GET /stake/delegators/{delegatorAddr}/delegations/{validatorAddr} - -- **URL**: `/stake/delegators/{delegatorAddr}/delegations/{validatorAddr}` -- **Functionality**: Query the current delegation status between a delegator and a validator. -- Returns on success: - -```json -{ - "rest api":"2.1", - "code":200, - "error":"", - "result":{ - "transaction":"TODO" - } -} -``` - -### GET /stake/delegators/{delegatorAddr}/unbonding_delegations/{validatorAddr} - -- **URL**: `/stake/delegators/{delegatorAddr}/unbonding_delegations/{validatorAddr}` -- **Functionality**: Query all unbonding delegations between a delegator and a validator. -- Returns on success: - -```json -{ - "rest api":"2.1", - "code":200, - "error":"", - "result":{ - "transaction":"TODO" - } -} -``` - -### GET /stake/validators - -- **URL**: `/stake/validators` -- **Functionality**: Get all validator candidates. -- Returns on success: - -```json -{ - "rest api":"2.1", - "code":200, - "error":"", - "result":{ - "transaction":"TODO" - } -} -``` - -### GET /stake/validators/{validatorAddr} - -- **URL**: `/stake/validators/{validatorAddr}` -- **Functionality**: Query the information from a single validator. -- Returns on success: - -```json -{ - "rest api":"2.1", - "code":200, - "error":"", - "result":{ - "transaction":"TODO" - } -} -``` - -### GET /stake/parameters - -- **URL**: `/stake/parameters` -- **Functionality**: Get the current value of staking parameters. -- Returns on success: - -```json -{ - "rest api":"2.1", - "code":200, - "error":"", - "result":{ - "inflation_rate_change": 1300000000, - "inflation_max": 2000000000, - "inflation_min": 700000000, - "goal_bonded": 6700000000, - "unbonding_time": "72h0m0s", - "max_validators": 100, - "bond_denom": "atom" - } -} -``` - -### GET /stake/pool - -- **URL**: `/stake/pool` -- **Functionality**: Get the current value of the dynamic parameters of the current state (*i.e* `Pool`). -- Returns on success: - -```json -{ - "rest api":"2.1", - "code":200, - "error":"", - "result":{ - "loose_tokens": 0, - "bonded_tokens": 0, - "inflation_last_time": "1970-01-01 01:00:00 +0100 CET", - "inflation": 700000000, - "date_last_commission_reset": 0, - "prev_bonded_shares": 0, - } -} -``` - -## ICS22 - GovernanceAPI - -The GovernanceAPI exposes all functionality needed for casting votes on plain text, software upgrades and parameter change proposals. - -### GET /gov/proposals - -- **URL**: `/gov/proposals` -- **Functionality**: Query all submited proposals -- Response on Success: - -```json -{ - "rest api":"2.2", - "code":200, - "error":"", - "result":{ - "proposals":[ - "TODO" - ] - } -} -``` - -### POST /gov/proposals - -- **URL**: `/gov/proposals` -- **Functionality**: Submit a proposal -- POST Body: - -```js -{ - "base_req": { - // Name of key to use - "name": "string", - // Password for that key - "password": "string", - "chain_id": "string", - "account_number": 64, - "sequence": 64, - "gas": 64 - }, - // Title of the proposal - "title": "string", - // Description of the proposal - "description": "string", - // PlainTextProposal supported now. SoftwareUpgradeProposal and other types may be supported soon - "proposal_type": "string", - // A cosmos address - "proposer": "string", - "initial_deposit": [ - { - "denom": "string", - "amount": 64, - } - ] -} -``` - -- Returns on success: - -```json -{ - "rest api":"2.2", - "code":200, - "error":"", - "result":{ - "TODO": "TODO", - } -} -``` - -### GET /gov/proposals/{proposal-id} - -- **URL**: `/gov/proposals/{proposal-id}` -- **Functionality**: Query a proposal -- Response on Success: - -```json -{ - "rest api":"2.2", - "code":200, - "error":"", - "result":{ - "proposal_id": 1, - "title": "Example title", - "description": "a larger description with the details of the proposal", - "proposal_type": "Text", - "proposal_status": "DepositPeriod", - "tally_result": { - "yes": 0, - "abstain": 0, - "no": 0, - "no_with_veto": 0 - }, - "submit_block": 5238512, - "total_deposit": {"atom": 50}, - "voting_start_block": -1 - } -} -``` - -### POST /gov/proposals/{proposal-id}/deposits - -- **URL**: `/gov/proposals/{proposal-id}/deposits` -- **Functionality**: Submit or rise a deposit to a proposal in order to make it active -- POST Body: - -```json -{ - "base_req": { - "name": "string", - "password": "string", - "chain_id": "string", - "account_number": 0, - "sequence": 0, - "gas": "simulate" - }, - "depositer": "string", - "amount": 0, -} -``` - -- Returns on success: - -```json -{ - "rest api":"2.2", - "code":200, - "error":"", - "result":{ - "TODO": "TODO", - } -} -``` - -### GET /gov/proposals/{proposal-id}/deposits/{address} - -- **URL**: `/gov/proposals/{proposal-id}/deposits/{address}` -- **Functionality**: Query a validator's deposit to submit a proposal -- Returns on success: - -```json -{ - "rest api":"2.2", - "code":200, - "error":"", - "result":{ - "amount": {"atom": 150}, - "depositer": "cosmos1fedh326uxqlxs8ph9ej7cf854gz7fd5zlym5pd", - "proposal-id": 16 - } -} -``` - -### GET /gov/proposals/{proposal-id}/tally - -- **URL**: `/gov/proposals/{proposal-id}/tally` -- **Functionality**: Get the tally of a given proposal. -- Returns on success: - -```json -{ - "rest api":"2.2", - "code":200, - "error":"", - "result": { - "yes": 0, - "abstain": 0, - "no": 0, - "no_with_veto": 0 - } -} -``` - - - -### GET /gov/proposals/{proposal-id}/votes - -- **URL**: `/gov/proposals/{proposal-id}/votes` -- **Functionality**: Query all votes from a specific proposal -- Returns on success: - -```json -{ - "rest api":"2.2", - "code":200, - "error":"", - "result": [ - { - "proposal-id": 1, - "voter": "cosmos1fedh326uxqlxs8ph9ej7cf854gz7fd5zlym5pd", - "option": "no_with_veto" - }, - { - "proposal-id": 1, - "voter": "cosmos1849m9wncrqp6v4tkss6a3j8uzvuv0cp7f75lrq", - "option": "yes" - }, - ] -} -``` - - - -### POST /gov/proposals/{proposal-id}/votes - -- **URL**: `/gov/proposals/{proposal-id}/votes` -- **Functionality**: Vote for a specific proposal -- POST Body: - -```js -{ - "base_req": { - "name": "string", - "password": "string", - "chain_id": "string", - "account_number": 0, - "sequence": 0, - "gas": "simulate" - }, - // A cosmos address - "voter": "string", - // Value of the vote option `Yes`, `No` `Abstain`, `NoWithVeto` - "option": "string", -} -``` - -- Returns on success: - -```json -{ - "rest api":"2.2", - "code":200, - "error":"", - "result":{ - "TODO": "TODO", - } -} -``` - -### GET /gov/proposals/{proposal-id}/votes/{address} - -- **URL** : `/gov/proposals/{proposal-id}/votes/{address}` -- **Functionality**: Get the current `Option` submited by an address -- Returns on success: - -```json -{ - "rest api":"2.2", - "code":200, - "error":"", - "result":{ - "proposal-id": 1, - "voter": "cosmos1fedh326uxqlxs8ph9ej7cf854gz7fd5zlym5pd", - "option": "no_with_veto" - } -} -``` - -## ICS23 - SlashingAPI - -The SlashingAPI exposes all functionalities needed to slash (*i.e* penalize) validators and delegators in Proof-of-Stake. The penalization is a fine of the staking coin and jail time, defined by governance parameters. During the jail period, the penalized validator is "jailed". - -### GET /slashing/validator/{validatorAddr}/signing-info - -- **URL**: `/slashing/validator/{validatorAddr}/signing-info` -- **Functionality**: Query the information from a single validator. -- Returns on success: - -```json -{ - "rest api":"2.3", - "code":200, - "error":"", - "result":{ - "transaction":"TODO" - } -} -``` - -### POST /slashing/validators/{validatorAddr}/unjail - -- **URL**: `/slashing/validators/{validatorAddr}/unjail` -- **Functionality**: Submit a message to unjail a validator after it has been penalized. -- POST Body: - -```js -{ - // Name of key to use - "name": "string", - // Password for that key - "password": "string", - "chain_id": "string", - "account_number": 64, - "sequence": 64, - "gas": 64, -} -``` - -- Returns on success: - -```json -{ - "rest api":"2.3", - "code":200, - "error":"", - "result":{ - "transaction":"TODO" - } -} -``` diff --git a/docs/light/load_balancer.md b/docs/light/load_balancer.md deleted file mode 100644 index 0cc280827e..0000000000 --- a/docs/light/load_balancer.md +++ /dev/null @@ -1,203 +0,0 @@ -# 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 -sending a large mount of requests to LCD to query token information. As a result, LCD will send huge -requests to full node to get token information and necessary proof which will cost full node much -computing and bandwidth resource. Too many requests to a single full node may result in some bad -situations: - -```text -1. The full node crash possibility increases. -2. The reply delay increases. -3. The system reliability will decrease. -4. As the full node may belong to other people or associates, they may deny too frequent access from a single client. -``` - -It is very urgent to solve this problems. Here we consider to import load balancing into LCD. By the -help of load balancing, LCD can distribute millions of requests to a set of full nodes. Thus the -load of each full node won't be too heavy and the unavailable full nodes will be wiped out of query -list. In addition, the system reliability will increase. - -## Design - -This module need combine with client to realize the real load balancing. It can embed the -[HTTP Client](https://github.com/tendermint/tendermint/rpc/lib/client/httpclient.go). In other -words，we realise the new httpclient based on `HTTP`. - -```go -type HTTPLoadBalancer struct { - rpcs map[string]*rpcclient.JSONRPCClient - *WSEvents -} -``` - -## The Diagram of LCD RPC WorkFlow with LoadBalance - -![The Diagram of LCD RPC WorkFlow](pics/loadbalanceDiagram.png) - -In the above sequence diagram, application calls the `Request()`, and LCD finally call the -`HTTP.Request()` through the SecureClient `Wrapper`. In every `HTTP.Request()`, `Getclient()` -selects the current working rpcclient by the load balancing algorithm,then run the -`JSONRPCClient.Call()` to request from the Full Node, finally `UpdateClient()` updates the weight of - the current rpcclient according to the status that is returned by the full node. The `GetAddr()` - and `UpdateAddrWeight()` are realized in the load balancing module. - -There are some abilities to do: - -* Add the Remote Address -* Delete the Remote Address -* Update the weights of the addresses - -## Load balancing Strategies - -We can design some strategies like nginx to combine the different load balancing algorithms to get -the final remote. We can also get the status of the remote server to add or delete the addresses and - update weights of the addresses. - -In a word，it can make the entire LCD work more effective in actual conditions. -We are working this module independently in this [Github Repository](https://github.com/MrXJC/GoLoadBalance). - -## Interface And Type - -### Balancer - -This interface `Balancer`is the core of the package. Every load balancing algorithm should realize -it,and it defined two interfaces. - -* `init` initialize the balancer, assigns the variables which `DoBalance` needs. -* `DoBalance` load balance the full node addresses according to the current situation. - -```go -package balance - -type Balancer interface { - init(NodeAddrs) - DoBalance(NodeAddrs) (*NodeAddr,int,error) -} -``` - -### NodeAddr - -* host: ip address -* port: the number of port -* weight: the weight of this full node address,default:1 - -This NodeAddr is the base struct of the address. - -```go -type NodeAddr struct{ - host string - port int - weight int -} - -func (p *NodeAddr) GetHost() string - -func (p *NodeAddr) GetPort() int - -func (p *NodeAddr) GetWeight() int - -func (p *NodeAddr) updateWeight(weight int) -``` - -The `weight` is the important factor that schedules which full node the LCD calls. The weight can be -changed by the information from the full node. So we have the function `updateWegiht`. - -### NodeAddrs - ->in `balance/types.go` - -`NodeAddrs` is the list of the full node address. This is the member variable in the -BalanceManager(`BalancerMgr`). - -```go -type NodeAddrs []*NodeAddr -``` - -## Load Balancing Algorithm - -### Random - ->in `balance/random.go` - -Random algorithm selects a remote address randomly to process the request. The probability of them -being selected is the same. - -### RandomWeight - ->in `balance/random.go` - -RandomWeight Algorithm also selects a remote address randomly to process the request. But the higher -the weight, the greater the probability. - -### RoundRobin - ->in `balance/roundrobin.go` - -RoundRobin Algorithm selects a remote address orderly. Every remote address have the same -probability to be selected. - -### RoundRobinWeight - ->in `balance/roundrobin.go` - -RoundRobinWeight Algorthm selects a remote address orderly. But every remote address have different -probability to be selected which are determined by their weight. - -### Hash - -//TODO - -## Load Balancing Manager - -### BalanceMgr - ->in `balance/manager.go` - -* addrs: the set of the remote full node addresses -* balancers: map the string of balancer name to the specific balancer -* change: record whether the machine reinitialize after the `addrs` changes - -`BalanceMgr` is the manager of many balancer. It is the access of load balancing. Its main function -is to maintain the `NodeAddrs` and to call the specific load balancing algorithm above. - -```go -type BalanceMgr struct{ - addrs NodeAddrs - balancers map[string]Balancer - change map[string]bool -} - -func (p *BalanceMgr) RegisterBalancer(name string,balancer Balancer) - -func (p *BalanceMgr) updateBalancer(name string) - -func (p *BalanceMgr) AddNodeAddr(addr *NodeAddr) - -func (p *BalanceMgr) DeleteNodeAddr(i int) - -func (p *BalanceMgr) UpdateWeightNodeAddr(i int,weight int) - -func (p *BalanceMgr) GetAddr(name string)(*NodeAddr,int,error) { - // if addrs change,update the balancer which we use. - if p.change[name]{ - p.updateBalancer(name) - } - - // get the balancer by name - balancer := p.balancers[name] - - // use the load balancing algorithm - addr,index,err := balancer.DoBalance(p.addrs) - - return addr,index,err -} -``` - -* `RegisterBalancer`: register the basic balancer implementing the `Balancer` interface and initialize them. -* `updateBalancer`: update the specific balancer after the `addrs` change. -* `AddNodeAddr`: add the remote address and set all the values of the `change` to true. -* `DeleteNodeAddr`: delete the remote address and set all the values of the `change` to true. -* `UpdateWeightNodeAddr`: update the weight of the remote address and set all the values of the `change` to true. -* `GetAddr`:select the address by the balancer the `name` decides. diff --git a/docs/light/todo.md b/docs/light/todo.md deleted file mode 100644 index ce1f8508a1..0000000000 --- a/docs/light/todo.md +++ /dev/null @@ -1,16 +0,0 @@ -# TODO - -This document is a place to gather all points for future development. - -## API - -* finalise ICS0 - TendermintAPI - * make sure that the explorer and voyager can use it -* add ICS21 - StakingAPI -* add ICS22 - GovernanceAPI -* split Gaia Light into reusable components that other zones can leverage - * it should be possible to register extra standards on the light client - * the setup should be similar to how the app is currently started -* implement Gaia light and the general light client in Rust - * export the API as a C interface - * write thin wrappers around the C interface in JS, Swift and Kotlin/Java diff --git a/docs/light/getting_started.md b/docs/lite/getting_started.md similarity index 59% rename from docs/light/getting_started.md rename to docs/lite/getting_started.md index 21497477a7..b602bcc476 100644 --- a/docs/light/getting_started.md +++ b/docs/lite/getting_started.md @@ -1,6 +1,7 @@ # Getting Started To start a REST server, we need to specify the following parameters: + | Parameter | Type | Default | Required | Description | | ----------- | --------- | ----------------------- | -------- | ---------------------------------------------------- | | chain-id | string | null | true | chain id of the full node to connect | @@ -9,12 +10,12 @@ To start a REST server, we need to specify the following parameters: | trust-node | bool | "false" | true | Whether this LCD is connected to a trusted full node | | trust-store | DIRECTORY | "$HOME/.lcd" | false | directory for save checkpoints and validator sets | -Sample command: +For example:: ```bash gaiacli rest-server --chain-id=test \ --laddr=tcp://localhost:1317 \ - --node tcp://localhost:46657 \ + --node tcp://localhost:26657 \ --trust-node=false ``` @@ -23,7 +24,7 @@ The server listens on HTTPS by default. You can set the SSL certificate to be us ```bash gaiacli rest-server --chain-id=test \ --laddr=tcp://localhost:1317 \ - --node tcp://localhost:46657 \ + --node tcp://localhost:26657 \ --trust-node=false \ --certfile=mycert.pem --keyfile=mykey.key ``` @@ -31,26 +32,4 @@ gaiacli rest-server --chain-id=test \ If no certificate/keyfile pair is supplied, a self-signed certificate will be generated and its fingerprint printed out. Append `--insecure` to the command line if you want to disable the secure layer and listen on an insecure HTTP port. -## Gaia Light Use Cases - -LCD could be very helpful for related service providers. For a wallet service provider, LCD could -make transaction faster and more reliable in the following cases. - -### Create an account - -![deposit](pics/create-account.png) - -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](api.md#keys---post) - -### Transfer a token - -![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](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](api.md#create_transfer---post) +For more information about the Gaia-Lite RPC, see the [swagger documentation](https://cosmos.network/rpc/) diff --git a/docs/light/pics/C2H.png b/docs/lite/pics/C2H.png similarity index 100% rename from docs/light/pics/C2H.png rename to docs/lite/pics/C2H.png diff --git a/docs/light/pics/H2C.png b/docs/lite/pics/H2C.png similarity index 100% rename from docs/light/pics/H2C.png rename to docs/lite/pics/H2C.png diff --git a/docs/light/pics/MA.png b/docs/lite/pics/MA.png similarity index 100% rename from docs/light/pics/MA.png rename to docs/lite/pics/MA.png diff --git a/docs/light/pics/absence1.png b/docs/lite/pics/absence1.png similarity index 100% rename from docs/light/pics/absence1.png rename to docs/lite/pics/absence1.png diff --git a/docs/light/pics/absence2.png b/docs/lite/pics/absence2.png similarity index 100% rename from docs/light/pics/absence2.png rename to docs/lite/pics/absence2.png diff --git a/docs/light/pics/absence3.png b/docs/lite/pics/absence3.png similarity index 100% rename from docs/light/pics/absence3.png rename to docs/lite/pics/absence3.png diff --git a/docs/light/pics/architecture.png b/docs/lite/pics/architecture.png similarity index 100% rename from docs/light/pics/architecture.png rename to docs/lite/pics/architecture.png diff --git a/docs/light/pics/changeProcess.png b/docs/lite/pics/changeProcess.png similarity index 100% rename from docs/light/pics/changeProcess.png rename to docs/lite/pics/changeProcess.png diff --git a/docs/light/pics/commitValidation.png b/docs/lite/pics/commitValidation.png similarity index 100% rename from docs/light/pics/commitValidation.png rename to docs/lite/pics/commitValidation.png diff --git a/docs/light/pics/create-account.png b/docs/lite/pics/create-account.png similarity index 100% rename from docs/light/pics/create-account.png rename to docs/lite/pics/create-account.png diff --git a/docs/light/pics/deposit.png b/docs/lite/pics/deposit.png similarity index 100% rename from docs/light/pics/deposit.png rename to docs/lite/pics/deposit.png diff --git a/docs/light/pics/existProof.png b/docs/lite/pics/existProof.png similarity index 100% rename from docs/light/pics/existProof.png rename to docs/lite/pics/existProof.png diff --git a/docs/light/pics/high-level.png b/docs/lite/pics/high-level.png similarity index 100% rename from docs/light/pics/high-level.png rename to docs/lite/pics/high-level.png diff --git a/docs/light/pics/light-client-architecture.png b/docs/lite/pics/light-client-architecture.png similarity index 100% rename from docs/light/pics/light-client-architecture.png rename to docs/lite/pics/light-client-architecture.png diff --git a/docs/light/pics/loadbalanceDiagram.png b/docs/lite/pics/loadbalanceDiagram.png similarity index 100% rename from docs/light/pics/loadbalanceDiagram.png rename to docs/lite/pics/loadbalanceDiagram.png diff --git a/docs/light/pics/simpleMerkleTree.png b/docs/lite/pics/simpleMerkleTree.png similarity index 100% rename from docs/light/pics/simpleMerkleTree.png rename to docs/lite/pics/simpleMerkleTree.png diff --git a/docs/light/pics/substoreProof.png b/docs/lite/pics/substoreProof.png similarity index 100% rename from docs/light/pics/substoreProof.png rename to docs/lite/pics/substoreProof.png diff --git a/docs/light/pics/transfer-tokens.png b/docs/lite/pics/transfer-tokens.png similarity index 100% rename from docs/light/pics/transfer-tokens.png rename to docs/lite/pics/transfer-tokens.png diff --git a/docs/light/pics/transfer.png b/docs/lite/pics/transfer.png similarity index 100% rename from docs/light/pics/transfer.png rename to docs/lite/pics/transfer.png diff --git a/docs/light/pics/trustPropagate.png b/docs/lite/pics/trustPropagate.png similarity index 100% rename from docs/light/pics/trustPropagate.png rename to docs/lite/pics/trustPropagate.png diff --git a/docs/light/pics/updateValidatorToHeight.png b/docs/lite/pics/updateValidatorToHeight.png similarity index 100% rename from docs/light/pics/updateValidatorToHeight.png rename to docs/lite/pics/updateValidatorToHeight.png diff --git a/docs/light/pics/validatorSetChange.png b/docs/lite/pics/validatorSetChange.png similarity index 100% rename from docs/light/pics/validatorSetChange.png rename to docs/lite/pics/validatorSetChange.png diff --git a/docs/light/pics/withdraw.png b/docs/lite/pics/withdraw.png similarity index 100% rename from docs/light/pics/withdraw.png rename to docs/lite/pics/withdraw.png diff --git a/docs/light/readme.md b/docs/lite/readme.md similarity index 81% rename from docs/light/readme.md rename to docs/lite/readme.md index 55e0c72ac3..215bc25f71 100644 --- a/docs/light/readme.md +++ b/docs/lite/readme.md @@ -1,30 +1,20 @@ -# Cosmos-Sdk Light Client +# Overview + +**See the Cosmos SDK lite Client RPC documentation [here](https://cosmos.network/rpc/)** ## Introduction -A light client allows clients, such as mobile phones, to receive proofs of the state of the -blockchain from any full node. Light clients do not have to trust any full node, since they are able +A lite client allows clients, such as mobile phones, to receive proofs of the state of the +blockchain from any full node. lite clients do not have to trust any full node, since they are able to verify any proof they receive and hence full nodes cannot lie about the state of the network. -A light client can provide the same security as a full node with the minimal requirements on -bandwidth, computing and storage resource. Besides, it can also provide modular functionality +A lite client can provide the same security as a full node with the minimal requirements on +bandwidth, computing and storage resource. As well, it can also provide modular functionality according to users' configuration. These fantastic features allow developers to build fully secure, efficient and usable mobile apps, websites or any other applications without deploying or maintaining any full blockchain nodes. -LCD will be used in the Cosmos Hub, the first Hub in the Cosmos network. - -## Contents - -1. [**Overview**](##Overview) -2. [**Get Started**](getting_started.md) -3. [**API**](api.md) -4. [**Specifications**](specification.md) -4. [**Update API docs To Swagger-UI**](update_API_docs.md) - -## Overview - -### What is a Light Client +### What is a lite 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 @@ -54,7 +44,7 @@ that offers stability guarantees around the zone API. ### Comparision -A full node of ABCI is different from its light client in the following ways: +A full node of ABCI is different from its lite client in the following ways: || Full Node | LCD | Description| |-| ------------- | ----- | -------------- | @@ -71,22 +61,22 @@ A full node of ABCI is different from its light client in the following ways: 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? +## Achieving Security -### Trusted validator set +### Trusted Validator Set -The base design philosophy of lcd follows the two rules: +The base design philosophy of the LCD follows two rules: 1. **Doesn't trust any blockchain 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 comes from genesis file. During runtime, if LCD detects a different validator set, +it will verify it and save new validated validator set to the trust store. ![validator-set-change](pics/validatorSetChange.png) -### Trust propagation +### 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 @@ -97,5 +87,4 @@ follows: 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. +and merkle proof, all transactions data and ABCI states can be verified too. diff --git a/docs/light/specification.md b/docs/lite/specification.md similarity index 67% rename from docs/light/specification.md rename to docs/lite/specification.md index 15f36b0144..4feac508cc 100644 --- a/docs/light/specification.md +++ b/docs/lite/specification.md @@ -207,150 +207,3 @@ For instance: * Update to 10000,tooMuchChangeErr * Update to 7525, Success * Update to 10000, Success - -## Load Balancing - -To improve LCD reliability and TPS, we recommend to connect LCD to more than one fullnode. But the -complexity will increase a lot. So load balancing module will be imported as the adapter. Please -refer to this link for detailed description: [load balancer](load_balancer.md) - -## ICS1 (KeyAPI) - -### [/keys - GET](api.md#keys---get) - -Load the key store: - -```go -db, err := dbm.NewGoLevelDB(KeyDBName, filepath.Join(rootDir, "keys")) -if err != nil { - return nil, err -} - -keybase = client.GetKeyBase(db) -``` - -Iterate through the key store. - -```go -var res []Info -iter := kb.db.Iterator(nil, nil) -defer iter.Close() - -for ; iter.Valid(); iter.Next() { - // key := iter.Key() - info, err := readInfo(iter.Value()) - if err != nil { - return nil, err - } - res = append(res, info) -} - -return res, nil -``` - -Encode the addresses and public keys in bech32. - -```go -bechAccount, err := sdk.Bech32ifyAcc(sdk.Address(info.PubKey.Address().Bytes())) -if err != nil { - return KeyOutput{}, err -} - -bechPubKey, err := sdk.Bech32ifyAccPub(info.PubKey) -if err != nil { - return KeyOutput{}, err -} - -return KeyOutput{ - Name: info.Name, - Address: bechAccount, - PubKey: bechPubKey, -}, nil -``` - -### [/keys/recover - POST](api.md#keys/recover---get) - -1. Load the key store. -2. Parameter checking. Name, password and seed should not be empty. -3. Check for keys with the same name. -4. Build the key from the name, password and seed. -5. Persist the key to key store. - -### [/keys/create - GET](api.md#keys/create---get)** - -1. Load the key store. -2. Create a new key in the key store. -3. Save the key to disk. -4. Return the seed. - -### [/keys/{name} - GET](api.md#keysname---get) - -1. Load the key store. -2. Iterate the whole key store to find the key by name. -3. Encode address and public key in bech32. - -### [/keys/{name} - PUT](api.md#keysname---put) - -1. Load the key store. -2. Iterate the whole key store to find the key by name. -3. Verify if that the old-password matches the current key password. -4. Re-persist the key with the new password. - -### [/keys/{name} - DELETE](api.md#keysname---delete) - -1. Load the key store. -2. Iterate the whole key store to find the key by name. -3. Verify that the specified password matches the current key password. -4. Delete the key from the key store. - -## ICS20 (TokenAPI) - -### [/bank/balance/{account}](api.md#bankbalanceaccount---get) - -1. Decode the address from bech32 to hex. -2. Send a query request to a full node. Ask for proof if required by Gaia Light. -3. Verify the proof against the root of trust. - -### [/bank/create_transfer](api.md#bankcreate_transfer---post) - -1. Check the parameters. -2. Build the transaction with the specified parameters. -3. Serialise the transaction and return the JSON encoded sign bytes. - -## ICS21 (StakingAPI) - -### [/stake/delegators/{delegatorAddr}](api.md#stakedelegatorsdelegatorAddr---get) - -TODO - -### [/stake/delegators/{delegatorAddr}/validators](api.md#stakedelegatorsdelegatorAddrvalidators---get) - -TODO - -### [/stake/delegators/{delegatorAddr}/validators/{validatorAddr}](api.md#stakedelegatorsdelegatorAddrvalidatorsvalidatorAddr---get) - -TODO - -### [/stake/delegators/{delegatorAddr}/txs](api.md#stakedelegatorsdelegatorAddrtxs---get) - -TODO - -### [/stake/delegators/{delegatorAddr}/delegations](api.md#stakedelegatorsdelegatorAddrdelegations---post) - -TODO - -### [/stake/delegators/{delegatorAddr}/delegations/{validatorAddr}](api.md#stakedelegatorsdelegatorAddrdelegationsvalidatorAddr---get) - -TODO - -### [/stake/delegators/{delegatorAddr}/unbonding_delegations/{validatorAddr}](api.md#stakedelegatorsdelegatorAddrunbonding_delegationsvalidatorAddr---get) - -TODO - -### [/stake/validators](api.md#stakevalidators---get) - -TODO - -### [/stake/validators/{validatorAddr}](api.md#stakevalidatorsvalidatorAddr---get) - -TODO