Merge PR #4353: Documentation Fixes
This commit is contained in:
Marko
Alexander Bezobchuk
parent
ca4363ffb7
commit
c0d8fb8a25
|
|
@ -38,21 +38,21 @@ initially support [ICS0](https://cosmos.network/rpc/#/ICS0) (TendermintAPI), [IC
|
|||
All applications are expected to only run against Gaia-lite. Gaia-lite is the only piece of software
|
||||
that offers stability guarantees around the zone API.
|
||||
|
||||
### Comparision
|
||||
### Comparison
|
||||
|
||||
A full node of ABCI is different from its lite client in the following ways:
|
||||
|
||||
|| Full Node | Gaia-lite | Description|
|
||||
|-| ------------- | ----- | -------------- |
|
||||
| Execute and verify transactions|Yes|No|Full node will execute and verify all transactions while Gaia-lite won't|
|
||||
| Verify and save blocks|Yes|No|Full node will verify and save all blocks while Gaia-lite won't|
|
||||
| Participate consensus| Yes|No|Only when the full node is a validtor, it will participate consensus. Lite 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. Light clients 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. Gaia-lite 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. Gaia-lite can be deployed on the same machines as users' applications, or on independent machines but with poor performance. Besides, lite clients can be shutdown anytime when necessary. So Gaia-lite 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. Gaia-lite provides modular APIs according to users' configuration|
|
||||
| Secuity level| High|High|Full node will verify all transactions and blocks by itself. A light client can't do this, but it can query any data from other full nodes and verify the data independently. So both full nodes and light clients don't need to trust any third nodes, they all can achieve high security|
|
||||
| Execute and verify transactions|Yes|No|A full node will execute and verify all transactions while Gaia-lite won't|
|
||||
| Verify and save blocks|Yes|No|A full node will verify and save all blocks while Gaia-lite won't|
|
||||
| Participate consensus| Yes|No|Only when the full node is a validator, it will participate consensus. Lite nodes never participate in consensus|
|
||||
| Bandwidth cost|Huge|Little|A 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. Light clients requires little bandwidth. Only when serving local request, it will cost bandwidth|
|
||||
| Computing resource|Huge|Little|A full node will execute all transactions and verify all blocks|
|
||||
| Storage resource|Huge|Little|A full node will save all blocks and ABCI states. Gaia-lite just saves validator sets and some checkpoints|
|
||||
| Power consumption|Huge|Little|A full nodes have to be deployed on machines which have high performance and will be running all the time. So power consumption will be huge. Gaia-lite can be deployed on the same machine as user applications, or independently. There is not a requirement to run the lite-client at all times. Due to the lower power requirements of Gaia-lite, you are able to run it on mobile devices.|
|
||||
| Provide APIs|All cosmos APIs|Modular APIs|A full node supports all cosmos APIs. Gaia-lite provides modular APIs according to users' configuration|
|
||||
| Security level| High|High|A full node will verify all transactions and blocks by itself. A light client can't do this, but it can query any data from full nodes and verify the data independently. So both full nodes and light clients don't need to trust any third nodes, they can achieve high security|
|
||||
|
||||
According to the above table, Gaia-lite can meet all users' functionality and security requirements, but
|
||||
only requires little resource on bandwidth, computing, storage and power.
|
||||
|
|
@ -67,20 +67,20 @@ The base design philosophy of Gaia-lite follows two rules:
|
|||
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 runtime, if Gaia-lite detects a different validator set,
|
||||
it will verify it and save new validated validator set to the trust store.
|
||||
validator set comes from the genesis file. During runtime, if Gaia-lite detects a different validator set,
|
||||
it will verify it and save the new validated validator set to the trust store.
|
||||
|
||||
|
||||
|
||||
### 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
|
||||
From the above section, we come to know how to get a trusted validator set and how lcd keeps track of
|
||||
validator set evolution. The validator set is the foundation of trust, and the trust can propagate to
|
||||
other blockchain data, such as blocks and transactions. The propagate architecture is shown as
|
||||
follows:
|
||||
|
||||
|
||||
|
||||
In general, by trusted validator set, a light client can verify each block commit which contains all pre-commit
|
||||
In general, with a trusted validator set, a light client 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.
|
||||
|
|
|
|||
|
|
@ -23,11 +23,11 @@ need to build proof from ABCI state to AppHash. The proof contains two parts:
|
|||
|
||||
### IAVL Proof
|
||||
|
||||
The proof has two types: existance proof and absence proof. If the query key exists in the IAVL
|
||||
store, then it returns key-value and its existance proof. On the other hand, if the key doesn't
|
||||
exist, then it only returns absence proof which can demostrate the key definitely doesn't exist.
|
||||
The proof has two types: existence proof and absence proof. If the query key exists in the IAVL
|
||||
store, then it returns key-value and its existence proof. On the other hand, if the key doesn't
|
||||
exist, then it only returns absence proof which can demonstrate the key definitely doesn't exist.
|
||||
|
||||
### IAVL Existance Proof
|
||||
### IAVL Existence Proof
|
||||
|
||||
```go
|
||||
type CommitID struct {
|
||||
|
|
@ -88,7 +88,7 @@ Steps to verify proof:
|
|||
### IAVL Absence Proof
|
||||
|
||||
As we all know, all IAVL leaf nodes are sorted by the key of each leaf nodes. So we can calculate
|
||||
the postition of the target key in the whole key set of this IAVL tree. As shown below, we can find
|
||||
the position of the target key in the whole key set of this IAVL tree. As shown below, we can find
|
||||
out the left key and the right key. If we can demonstrate that both left key and right key
|
||||
definitely exist, and they are adjacent nodes. Thus the target key definitely doesn't exist.
|
||||
|
||||
|
|
@ -184,16 +184,16 @@ func SimpleHashFromHashes(hashes [][]byte) []byte {
|
|||
## Verify block header against validator set
|
||||
|
||||
Above sections refer appHash frequently. But where does the trusted appHash come from? Actually,
|
||||
appHash exist in block header, so next we need to verify blocks header at specific height against
|
||||
the appHash exist in block header, next we need to verify blocks header at specific height against
|
||||
LCD trusted validator set. The validation flow is shown as follows:
|
||||
|
||||
|
||||
|
||||
When the trusted validator set doesn't match the block header, we need to try to update our
|
||||
validator set to the height of this block. LCD have a rule that each validator set change should not
|
||||
affact more than 1/3 voting power. Compare with the trusted validator set, if the voting power of
|
||||
validator set to the height of this block. LCD has a rule that each validator set change should not
|
||||
affect more than 1/3 voting power. Compare with the trusted validator set, if the voting power of
|
||||
target validator set changes more than 1/3. We have to verify if there are hidden validator set
|
||||
change before the target validator set. Only when all validator set changes obey this rule, can our
|
||||
changes before the target validator set. Only when all validator set changes obey this rule, can our
|
||||
validator set update be accomplished.
|
||||
|
||||
For instance:
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ There are three main pieces to consider:
|
|||
|
||||
### Installation and configuration
|
||||
|
||||
We will describe the steps to run and interract with a full-node for the Cosmos Hub. For other SDK-based blockchain, the process should be similar.
|
||||
We will describe the steps to run and interact with a full-node for the Cosmos Hub. For other SDK-based blockchain, the process should be similar.
|
||||
|
||||
First, you need to [install the software](../cosmos-hub/installation.md).
|
||||
|
||||
|
|
@ -34,7 +34,7 @@ To generate a new key (default secp256k1 elliptic curve):
|
|||
gaiacli keys add <your_key_name>
|
||||
```
|
||||
|
||||
You will be asked to create a passwords (at least 8 characters) for this key-pair. The command returns 5 informations:
|
||||
You will be asked to create a password (at least 8 characters) for this key-pair. This will return the information listed below:
|
||||
|
||||
- `NAME`: Name of your key
|
||||
- `TYPE`: Type of your key, always `local`.
|
||||
|
|
@ -118,7 +118,7 @@ The API is divided into ICS standards for each category of endpoints. For
|
|||
example, the [ICS20](https://cosmos.network/rpc/#/ICS20/) describes the API to
|
||||
interact with tokens.
|
||||
|
||||
To give more flexibility to implementers, we have included the ability to
|
||||
To give more flexibility to developers, we have included the ability to
|
||||
generate unsigned transactions, [sign](https://cosmos.network/rpc/#/ICS20/post_tx_sign)
|
||||
and [broadcast](https://cosmos.network/rpc/#/ICS20/post_tx_broadcast) them with
|
||||
different API endpoints. This allows service providers to use their own signing
|
||||
|
|
|
|||
|
|
@ -89,8 +89,8 @@ uses reserved prefixes solely for this purpose: `cosmosvaloper` and `cosmosvalop
|
|||
|
||||
After a validator is created with a `create-validator` transaction, they can be in three states:
|
||||
|
||||
- `in validator set`: Validator is in the active set and participates in consensus. Validator is earning rewards and can be slashed for misbehaviour.
|
||||
- `jailed`: Validator misbehaved and is in jail, i.e. outisde of the validator set. If the jailing is due to being offline for too long, the validator can send an `unjail` transaction in order to re-enter the validator set. If the jailing is due to double signing, the validator cannot unjail.
|
||||
- `in validator set`: Validator is in the active set and participates in consensus. Validator is earning rewards and can be slashed for misbehavior.
|
||||
- `jailed`: Validator misbehaved and is in jail, i.e. outside of the validator set. If the jailing is due to being offline for too long, the validator can send an `unjail` transaction in order to re-enter the validator set. If the jailing is due to double signing, the validator cannot unjail.
|
||||
- `unbonded`: Validator is not in the active set, and therefore not signing blocs. Validator cannot be slashed, and does not earn any reward. It is still possible to delegate Atoms to this validator. Un-delegating from an `unbonded` validator is immediate.
|
||||
|
||||
|
||||
|
|
@ -107,7 +107,7 @@ The minimum is `1 atom`.
|
|||
Delegators are free to choose validators according to their own subjective criteria. This said, criteria anticipated to be important include:
|
||||
|
||||
* **Amount of self-delegated Atoms:** Number of Atoms a validator self-delegated to themselves. A validator with a higher amount of self-delegated Atoms has more skin in the game, making them more liable for their actions.
|
||||
* **Amount of delegated Atoms:** Total number of Atoms delegated to a validator. A high voting power shows that the community trusts this validator, but it also means that this validator is a bigger target for hackers. Bigger validators also decrease the decentralisation of the network.
|
||||
* **Amount of delegated Atoms:** Total number of Atoms delegated to a validator. A high voting power shows that the community trusts this validator, but it also means that this validator is a bigger target for hackers. Bigger validators also decrease the decentralization of the network.
|
||||
* **Commission rate:** Commission applied on revenue by validators before it is distributed to their delegators.
|
||||
* **Track record:** Delegators will likely look at the track record of the validators they plan to delegate to. This includes seniority, past votes on proposals, historical average uptime and how often the node was compromised.
|
||||
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ foundation of an object capability system.
|
|||
> to another object only through a preexisting chain of references.
|
||||
> In short, "Only connectivity begets connectivity."
|
||||
|
||||
For an introduction to object-capabilities, see [this article](http://habitatchronicles.com/2017/05/what-are-capabilities/).
|
||||
For an introduction to object-capabilities, see [this article](https://en.wikipedia.org/wiki/Object-capability_model).
|
||||
|
||||
Strictly speaking, Golang does not implement object capabilities
|
||||
completely, because of several issues:
|
||||
|
|
|
|||
|
|
@ -1,9 +1,19 @@
|
|||
# Auth
|
||||
|
||||
The `x/auth` modules is used for accounts
|
||||
|
||||
See the [API docs](https://godoc.org/github.com/cosmos/cosmos-sdk/x/auth)
|
||||
|
||||
See the [specification](https://github.com/cosmos/cosmos-sdk/tree/master/docs/spec/auth)
|
||||
|
||||
# Bank
|
||||
|
||||
The `x/bank` module is for transferring coins between accounts.
|
||||
|
||||
See the [API docs](https://godoc.org/github.com/cosmos/cosmos-sdk/x/bank).
|
||||
|
||||
See the [specification](https://github.com/cosmos/cosmos-sdk/tree/master/docs/spec/bank)
|
||||
|
||||
# Stake
|
||||
|
||||
The `x/staking` module is for Cosmos Delegated-Proof-of-Stake.
|
||||
|
|
@ -11,7 +21,7 @@ The `x/staking` module is for Cosmos Delegated-Proof-of-Stake.
|
|||
See the [API docs](https://godoc.org/github.com/cosmos/cosmos-sdk/x/staking).
|
||||
|
||||
See the
|
||||
[specification](https://github.com/cosmos/cosmos-sdk/tree/develop/docs/spec/staking)
|
||||
[specification](https://github.com/cosmos/cosmos-sdk/tree/master/docs/spec/staking)
|
||||
|
||||
# Slashing
|
||||
|
||||
|
|
@ -20,17 +30,17 @@ The `x/slashing` module is for Cosmos Delegated-Proof-of-Stake.
|
|||
See the [API docs](https://godoc.org/github.com/cosmos/cosmos-sdk/x/slashing)
|
||||
|
||||
See the
|
||||
[specification](https://github.com/cosmos/cosmos-sdk/tree/develop/docs/spec/slashing)
|
||||
[specification](https://github.com/cosmos/cosmos-sdk/tree/master/docs/spec/slashing)
|
||||
|
||||
# Provisions
|
||||
# Distribution
|
||||
|
||||
The `x/provisions` module is for distributing fees and inflation across bonded
|
||||
The `x/distribution` module is for distributing fees and inflation across bonded
|
||||
stakeholders.
|
||||
|
||||
See the [API docs](https://godoc.org/github.com/cosmos/cosmos-sdk/x/provisions)
|
||||
See the [API docs](https://godoc.org/github.com/cosmos/cosmos-sdk/x/distribution)
|
||||
|
||||
See the
|
||||
[specification](https://github.com/cosmos/cosmos-sdk/tree/develop/docs/spec/provisions)
|
||||
[specification](https://github.com/cosmos/cosmos-sdk/tree/master/docs/spec/distribution)
|
||||
|
||||
# Governance
|
||||
|
||||
|
|
@ -39,7 +49,7 @@ The `x/gov` module is for bonded stakeholders to make proposals and vote on them
|
|||
See the [API docs](https://godoc.org/github.com/cosmos/cosmos-sdk/x/gov)
|
||||
|
||||
See the
|
||||
[specification](https://github.com/cosmos/cosmos-sdk/tree/develop/docs/spec/governance)
|
||||
[specification](https://github.com/cosmos/cosmos-sdk/tree/master/docs/spec/governance)
|
||||
|
||||
# IBC
|
||||
|
||||
|
|
@ -48,4 +58,30 @@ The `x/ibc` module is for InterBlockchain Communication.
|
|||
See the [API docs](https://godoc.org/github.com/cosmos/cosmos-sdk/x/ibc)
|
||||
|
||||
See the
|
||||
[specification](https://github.com/cosmos/cosmos-sdk/tree/develop/docs/spec/ibc)
|
||||
[specification](https://github.com/cosmos/cosmos-sdk/tree/master/docs/spec/ibc)
|
||||
|
||||
To keep up with the current status of IBC, follow and contribute to [ICS](https://github.com/cosmos/ics)
|
||||
|
||||
# Crisis
|
||||
|
||||
The `x/crisis` module is for halting the blockchain under certain circumstances.
|
||||
|
||||
See the [API Docs](https://godoc.org/github.com/cosmos/cosmos-sdk/x/crisis)
|
||||
|
||||
See the [specification](https://github.com/cosmos/cosmos-sdk/blob/master/docs/spec/crisis)
|
||||
|
||||
# Mint
|
||||
|
||||
The `x/mint` module is for flexible inflation rates and effect a balance between market liquidity and staked supply.
|
||||
|
||||
See the [API Docs](https://godoc.org/github.com/cosmos/cosmos-sdk/x/mint)
|
||||
|
||||
See the [specification](https://github.com/cosmos/cosmos-sdk/blob/master/docs/spec/mint)
|
||||
|
||||
# Params
|
||||
|
||||
The `x/params` module provides a globally available parameter store.
|
||||
|
||||
See the [API Docs](https://godoc.org/github.com/cosmos/cosmos-sdk/x/params)
|
||||
|
||||
See the [specification](https://github.com/cosmos/cosmos-sdk/blob/master/docs/spec/params)
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ block.
|
|||
### SDK specifications:
|
||||
|
||||
- [Store](./store) - The core Merkle store that holds the state.
|
||||
- [Bech32](./other/bech32.md) - Address format for Cosmos SDK applications.
|
||||
- [Bech32](./addresses/bech32.md) - Address format for Cosmos SDK applications.
|
||||
|
||||
### Modules specifications:
|
||||
|
||||
|
|
@ -18,13 +18,15 @@ block.
|
|||
- [Governance](./governance) - Proposals and voting.
|
||||
- [Staking](./staking) - Proof-of-stake bonding, delegation, etc.
|
||||
- [Slashing](./slashing) - Validator punishment mechanisms.
|
||||
- [Distribution](./distribution) - Fee distribution, and staking token provision distribution .
|
||||
- [Inflation](./inflation) - Staking token provision creation
|
||||
- [Distribution](./distribution) - Fee distribution, and staking token provision distribution.
|
||||
- [Crisis](./crisis) - Halting the blockchain under certain circumstances.
|
||||
- [Mint](./mint) - Staking token provision creation.
|
||||
- [Params](./params) - Globally available parameter store.
|
||||
- [IBC](./ibc) - Inter-Blockchain Communication (IBC) protocol.
|
||||
|
||||
### Interchain standards
|
||||
|
||||
- [ICS30](./ics/ics-030-signed-messages.md) - Signed messages standard.
|
||||
- [ICS30](./_ics/ics-030-signed-messages.md) - Signed messages standard.
|
||||
-
|
||||
|
||||
For details on the underlying blockchain and p2p protocols, see
|
||||
|
|
|
|||
|
|
@ -79,8 +79,7 @@ to set up a script to periodically withdraw and rebond rewards.
|
|||
|
||||
1. **[Concepts](01_concepts.md)**
|
||||
- [Reference Counting in F1 Fee Distribution](01_concepts.md#reference-counting-in-f1-fee-distribution)
|
||||
2. **[02_state.md](02_state.md)**
|
||||
- [State](02_state.md#state)
|
||||
2. **[State](02_state.md)**
|
||||
3. **[End Block](03_end_block.md)**
|
||||
4. **[Messages](04_messages.md)**
|
||||
- [MsgWithdrawDelegationRewardsAll](04_messages.md#msgwithdrawdelegationrewardsall)
|
||||
|
|
|
|||
|
|
@ -2,10 +2,11 @@
|
|||
|
||||
## Contents
|
||||
|
||||
1. **[State](01_state.md)**
|
||||
- [Minter](01_state.md#minter)
|
||||
- [Params](01_state.md#params)
|
||||
2. **[Begin-Block](02_begin_block.md)**
|
||||
- [NextInflationRate](02_begin_block.md#nextinflationrate)
|
||||
- [NextAnnualProvisions](02_begin_block.md#nextannualprovisions)
|
||||
- [BlockProvision](02_begin_block.md#blockprovision)
|
||||
1. **[Concept](01_concept.md)**
|
||||
2. **[State](02_state.md)**
|
||||
- [Minter](02_state.md#minter)
|
||||
- [Params](02_state.md#params)
|
||||
3. **[Begin-Block](03_begin_block.md)**
|
||||
- [NextInflationRate](03_begin_block.md#nextinflationrate)
|
||||
- [NextAnnualProvisions](03_begin_block.md#nextannualprovisions)
|
||||
- [BlockProvision](03_begin_block.md#blockprovision)
|
||||
|
|
|
|||
Loading…
Reference in New Issue