docs: clean up translations and readme (#9539)

<!--
The default pull request template is for types feat, fix, or refactor.
For other templates, add one of the following parameters to the url:
- template=docs.md
- template=other.md
-->

## Description

Closes: #9479 

<!-- Add a description of the changes that this PR introduces and the files that
are the most critical to review. -->

This pull request removes deprecated documentation written in other languages (still available with semantic versioning) and updates the README for each locale with a note about contributing and a link to the older version. This pull request also updates the information about contributing translations and the configuration for locales to reflect the [VuePress documentation](https://vuepress.vuejs.org/guide/i18n.html).
 
---


### Author Checklist

*All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.*

I have...

- [x] included the correct `docs:` prefix in the PR title
- [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting))
- [x] provided a link to the relevant issue or specification
- [x] followed the [documentation writing guidelines](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOC_WRITING_GUIDELINES.md)
- [x] reviewed "Files changed" and left comments if necessary
- [x] confirmed all CI checks have passed

### Reviewers Checklist

*All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.*

I have...

- [ ] confirmed the correct `docs:` prefix in the PR title
- [ ] confirmed all author checklist items have been addressed 
- [ ] confirmed that this PR only changes documentation
- [ ] reviewed content for consistency
- [ ] reviewed content for thoroughness
- [ ] reviewed content for spelling and grammar
- [ ] tested instructions (if applicable)
This commit is contained in:
Ryan Christoffersen 2021-07-05 03:07:26 -07:00 committed by GitHub
parent 8297f2f312
commit 1b0b8e9997
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
72 changed files with 38 additions and 2903 deletions

View File

@ -5,14 +5,14 @@ module.exports = {
"/": {
lang: "en-US"
},
kr: {
lang: "kr"
},
cn: {
lang: "cn"
ko: {
lang: "ko"
},
ru: {
lang: "ru"
},
zh: {
lang: "zh-CN"
}
},
base: process.env.VUEPRESS_BASE || "/",

View File

@ -1,33 +1,33 @@
# Updating the docs
If you want to open a PR on the Cosmos SDK to update the documentation, please follow the guidelines in the [`CONTRIBUTING.md`](https://github.com/cosmos/cosmos-sdk/tree/master/CONTRIBUTING.md#updating-documentation)
If you want to open a PR in Cosmos SDK to update the documentation, please follow the guidelines in [`CONTRIBUTING.md`](https://github.com/cosmos/cosmos-sdk/tree/master/CONTRIBUTING.md#updating-documentation).
## Translating
## Internationalization
- Docs translations live in a `docs/country-code/` folder, where `country-code` stands for the country code of the language used (`cn` for Chinese, `kr` for Korea, `fr` for France, ...).
- Always translate content living on `master`.
- Only content under `/docs/intro/`, `/docs/basics/`, `/docs/core/`, `/docs/building-modules/` and `docs/run-node/` needs to be translated, as well as `docs/README.md`. It is also nice (but not mandatory) to translate `/docs/spec/`.
- Specify the release/tag of the translation in the README of your translation folder. Update the release/tag each time you update the translation.
- Translations for documentation live in a `docs/<locale>/` folder, where `<locale>` is the language code for a specific language. For example, `zh` for Chinese, `ko` for Korean, `ru` for Russian, etc.
- Each `docs/<locale>/` folder must follow the same folder structure within `docs/`, but only content in the following folders needs to be translated and included in the respective `docs/<locale>/` folder:
- `docs/basics/`
- `docs/building-modules/`
- `docs/core/`
- `docs/ibc/`
- `docs/intro/`
- `docs/migrations/`
- `docs/run-node/`
- Each `docs/<locale>/` folder must also have a `README.md` that includes a translated version of both the layout and content within the root-level [`README.md`](https://github.com/cosmos/cosmos-sdk/tree/master/docs/README.md). The layout defined in the `README.md` is used to build the homepage.
- Always translate content living on `master` unless you are revising documentation for a specific release. Translated documentation like the root-level documentation is semantically versioned.
- For additional configuration options, please see [VuePress Internationalization](https://vuepress.vuejs.org/guide/i18n.html).
## Docs Build Workflow
The documentation for the Cosmos SDK is hosted at https://cosmos.network/docs/
built from the files in this (`/docs`) directory for
[master](https://github.com/cosmos/cosmos-sdk/tree/master/docs).
The documentation for Cosmos SDK is hosted at https://docs.cosmos.network/ and built from the files in the `/docs` directory.
### How It Works
There is a CircleCI job listening for changes in the `/docs` directory, on
the `master` branch. Any updates to files in this directory
on that branch will automatically trigger a website deployment. Under the hood,
the private website repository has a `make build-docs` target consumed by a CircleCI job in that repo.
There is a CircleCI job listening for changes in the `/docs` directory for the `master` branch and each supported version tag (`v0.39` and `v0.42`). Any updates to files in the `/docs` directory will automatically trigger a website deployment. Under the hood, the private website repository has a `make build-docs` target consumed by a CircleCI job within that repository.
## README
The [README.md](./README.md) is also the landing page for the documentation
on the website. During the Jenkins build, the current commit is added to the bottom
of the README.
The [README.md](./README.md) is both the README for the repository and the configuration for the layout of the landing page.
## Config.js

View File

@ -48,24 +48,24 @@ aside: false
## Get Started
- **[SDK Intro](./intro/overview.md)**: High-level overview of the Cosmos SDK.
- **[Starport](https://github.com/tendermint/starport/blob/develop/docs/README.md)**: A developer-friendly interface to the Cosmos SDK to scaffold a standard Cosmos SDK blockchain app.
- **[SDK Application Tutorial](https://github.com/cosmos/sdk-application-tutorial)**: A tutorial that showcases how to build a Cosmos SDK-based blockchain from scratch and explains the basic principles of the SDK in the process.
- **[Starport](https://docs.starport.network/)**: A developer-friendly interface to the Cosmos SDK to scaffold a standard Cosmos SDK blockchain app.
- **[SDK Tutorials](https://tutorials.cosmos.network/)**: Tutorials that showcase how to build Cosmos SDK-based blockchains from scratch and explain the basic principles of the SDK in the process.
## Reference
- **[Basics](./basics/)**: Documentation on the basic concepts of the Cosmos SDK, like the standard anatomy of an application, the transaction lifecycle, and accounts management.
- **[Core](./core/)**: Documentation on the core concepts of the Cosmos SDK, like `baseapp`, the `store`, or the `server`.
- **[Building Modules](./building-modules/)**: Important concepts for module developers like `message`, `keeper`, `handler`, and `querier`.
- **[Building Modules](./building-modules/)**: Important concepts for module developers like `message`, `keeper`, and `querier`.
- **[IBC](./ibc/)**: Documentation for the IBC protocol integration and concepts.
- **[Running a Node, API, CLI](./run-node/)**: Documentation on how to run a node and interact with the node using the CLI and the API.
- **[Migrations](./migrations/)**: Migration guides for updating to Stargate.
- **[Migrations](./migrations/)**: Migration guides for updating to newer versions of the SDK.
## Other Resources
- **[Module Directory](../x/)**: Cosmos SDK module implementations and their respective documentation.
- **[Specifications](./spec/)**: Specifications of modules and other parts of the Cosmos SDK.
- **[SDK API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk)**: Godocs of the Cosmos SDK.
- **[REST API spec](https://cosmos.network/rpc/)**: List of endpoints to interact with a `gaia` full-node through REST.
- **[REST and RPC Endpoints](https://cosmos.network/rpc/)**: List of endpoints to interact with a `gaia` full-node.
## Cosmos Hub
@ -73,11 +73,8 @@ The Cosmos Hub (`gaia`) docs have moved to [github.com/cosmos/gaia](https://gith
## Languages
The Cosmos SDK is written in [Golang](https://golang.org/), though the
framework could be implemented similarly in other languages.
Contact us for information about funding an implementation in another language.
The Cosmos SDK is written in [Golang](https://golang.org/), though the framework could be implemented similarly in other languages. Contact us for information about funding an implementation in another language.
## Contribute
See the [DOCS_README.md](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOCS_README.md) for details of the build process and
considerations when making changes.
See the [DOCS_README.md](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOCS_README.md) for details of the build process and considerations when making changes.

View File

@ -1,43 +0,0 @@
---
parent:
order: false
---
# Cosmos SDK 文档
::: warning
**DEPRECATED**
This documentation is not complete and it's outdated. Please use the English version.
:::
## 开始
- **[SDK 介绍](./intro/README.md)**Cosmos SDK 的总体概览
- **[快速开始](./using-the-sdk/quick-start.md)**:构建一个标准的基于 cosmos sdk 的 app 并启动节点
- **[SDK 开发教程](https://github.com/cosmos/sdk-application-tutorial)**: 一个学习 SDK 的教程。它展示了如何从头开始基于 sdk 构建区块链, 并在此过程中解释了 SDK 的基本原理。
## 索引
- **[基础文档](./basics/)**cosmos sdk 的基础概念文档,例如应用结构、交易的生命周期、账户管理等
- **[核心文档](./core/)**: cosmos sdk 的核心文档,例如`baseapp``store``server`等
- **[构建模块](./building-modules/)**: 对于模块开发者来说的一些重要概念,例如`message``keeper``handler``querier`
- **[接口](./run-node/)**: 为 cosmos 应用设计接口的文档
## 开发资源
- **[模块目录](../../x/)**:模块的实现和文档
- **[规范](./spec/):** Cosmos SDK 的模块及其他规范。
- **[SDK API 参考](https://godoc.org/github.com/cosmos/cosmos-sdk):** Cosmos SDK Godocs 文档 。
- **[REST API 规范](https://cosmos.network/rpc/):** 通过 REST 与 `gaia` 全节点交互的 API 列表。
## Cosmos Hub
Cosmos Hub (名为 `gaia`) 文档已经迁移到[这里](https://github.com/cosmos/gaia/tree/master/docs).
## 开发语言
Cosmos-SDK 目前是用 [Golang](https://golang.org/)编写的, 尽管该框架同样可以在其他语言中实现。请联系我们获取有关资助其他语言实现的信息。
## 贡献
参考 [文档说明](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOCS_README.md) 了解构建细节及更新时注意事项。

View File

@ -1,15 +0,0 @@
# 基础文档
::: warning
**DEPRECATED**
This documentation is not complete and it's outdated. Please use the English version.
:::
此目录包含对 cosmos sdk 的基础概念介绍
1. [SDK 应用解析](./app-anatomy.md)
2. [交易的生命周期](./tx-lifecycle.md)
3. [账户系统](./accounts.md)
4. [Gas 和 Fees](./gas-fees.md)
阅读完基础文档后,可以阅读 [核心文档](../core/README.md) 进一步加深对 cosmos 的理解。

View File

@ -1,132 +0,0 @@
**原文路径:https://github.com/cosmos/cosmos-sdk/blob/master/docs/basics/accounts.md**
# 账户系统
# 必备阅读 {hide}
- [一个 SDK 程序的剖析](./app-anatomy.md) {prereq}
## 账户定义
在 Cosmos SDK 中,一个账户是指定的一个公私钥对。公钥可以用于派生出 `Addresses``Addresses` 可以在程序里面的各个模块间区分不同的用户。`Addresses` 同样可以和[消息](../building-modules/messages-and-queries.md#messages)进行关联用于确定发消息的账户。私钥一般用于生成签名来证明一个消息是被一个 `Addresses`(和私钥关联的`Addresses`) 所发送。
Cosmos SDK 使用一套称之为 [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) 的标准来生成公私钥。这个标准定义了怎么去创建一个 HD 钱包(钱包就是一批账户的集合)。每一个账户的核心,都有一个种子,每一个种子都有一个 12 或 24 个字的助记符。使用这个助记符,使用一种单向的加密方法可以派生出任意数量的私钥。公钥可以通过私钥推导出来。当然,助记符是最敏感的信息,因为可以不停通过助记符来重新生成私钥。
```md
Account 0 Account 1 Account 2
+------------------+ +------------------+ +------------------+
| | | | | |
| Address 0 | | Address 1 | | Address 2 |
| ^ | | ^ | | ^ |
| | | | | | | | |
| | | | | | | | |
| | | | | | | | |
| + | | + | | + |
| Public key 0 | | Public key 1 | | Public key 2 |
| ^ | | ^ | | ^ |
| | | | | | | | |
| | | | | | | | |
| | | | | | | | |
| + | | + | | + |
| Private key 0 | | Private key 1 | | Private key 2 |
| ^ | | ^ | | ^ |
+------------------+ +------------------+ +------------------+
| | |
| | |
| | |
+--------------------------------------------------------------------+
|
|
+---------+---------+
| |
| Master PrivKey |
| |
+-------------------+
|
|
+---------+---------+
| |
| Mnemonic (Seed) |
| |
+-------------------+
```
在 Cosmos SDK 中,账户可以在 [`Keybase`](#keybase) 中作为一个对象来储存和管理。
## Keybase
`Keybase` 是储存和管理账户的对象,在 Cosmos SDK 中,`Keybase` 要实现以下接口
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/crypto/keys/types.go#L13-L86
在 Cosmos SDK 中,`Keybase` 接口的默认实现对象是 `dbKeybase`
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/crypto/keys/keybase.go
`dbKeybase` 上面对 `Keybase` 接口中方法实现的笔记:
- `Sign(name, passphrase string, msg []byte) ([]byte, crypto.PubKey, error)``message` 字节进行签名。需要做一些准备工作将 `message` 编码成 []byte 类型,可以参考 `auth` 模块 `message` 准备的例子。注意SDK 上面没有实现签名的验证,签名验证被推迟到[`anteHandler`](#antehandler)中进行
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/auth/types/txbuilder.go#L176-L209
- `CreateMnemonic(name string, language Language, passwd string, algo SigningAlgo) (info Info, seed string, err error)`创建一个新的助记符并打印在日志里,但是**并不保存在磁盘上**
- `CreateAccount(name, mnemonic, bip39Passwd, encryptPasswd string, account uint32, index uint32) (Info, error)` 基于[`bip44 path`](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)创建一个新的账户并将其保存在磁盘上。注意私钥在[保存前用密码加密](https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/crypto/keys/mintkey/mintkey.go),**永远不会储存未加密的私钥**.在这个方法的上下文中, `account``address` 参数指的是 BIP44 派生路径的段(例如`0`, `1`, `2`, ...)用于从助记符派生出私钥和公钥(注意:给相同的助记符和 `account` 将派生出相同的私钥,给相同的 `account``address` 也会派生出相同的公钥和 `Address`)。最后注意 `CreateAccount` 方法使用在 [Tendermint library](https://github.com/tendermint/tendermint/tree/bc572217c07b90ad9cee851f193aaa8e9557cbc7/crypto/secp256k1) 中的 `secp256k1` 派生出公私钥和 `Address`。总之,这个方法是用来创建用户的钥匙和地址的,并不是共识秘钥,参见[`Addresses`](#addresses) 获取更多信息
`dbKeybase` 的实现是最基本的,并没有根据需求提供锁定功能。锁定功能指如果一个`dbKeybase`实例被创建,底层的`db`就被锁定意味着除了实例化它的程序其他程序无法访问它。这就是 SDK 程序使用另外一套 `Keybase` 接口的实现 `lazyKeybase` 的原因
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/crypto/keys/lazy_keybase.go
`lazyKeybase``dbKeybase` 的一个简单包装,它仅在要执行操作时锁定数据库,并在之后立即将其解锁。使用 `lazyKeybase`[命令行界面](../core/cli.md) 可以在 [rest server](../core/grpc_rest.md)运行时创建新的账户,它也可以同时传递多个 CLI 命令
## 地址和公钥
`Addresses``PubKey` 在程序里面都是标识一个参与者的公共信息。Cosmos SDK 默认提供 3 种类型的 `Addresses``PubKey`
- 基于用户的 `Addresses``PubKey`,用于指定用户(例如 `message` 的发送者)。它们通过 **`secp256k1`** 曲线推导出来
- 基于验证节点的 `Addresses``PubKey` 用于指定验证者的操作员,它们通过 **`secp256k1`** 曲线推导出来
- 基于共识节点的 `Addresses``PubKey` 用于指定参与共识的验证着节点,它们通过 **`ed25519`** 曲线推导出来
| | Address bech32 Prefix | Pubkey bech32 Prefix | Curve | Address byte length | Pubkey byte length |
| ------------------ | --------------------- | -------------------- | ----------- | ------------------- | ------------------ |
| Accounts | cosmos | cosmospub | `secp256k1` | `20` | `33` |
| Validator Operator | cosmosvaloper | cosmosvaloperpub | `secp256k1` | `20` | `33` |
| Consensus Nodes | cosmosvalcons | cosmosvalconspub | `ed25519` | `20` | `32` |
### 公钥
在 Cosmos SDK 里面 `PubKey` 遵循在 tendermint 的 `crypto` 包中定义的 `Pubkey` 接口
+++ https://github.com/tendermint/tendermint/blob/bc572217c07b90ad9cee851f193aaa8e9557cbc7/crypto/crypto.go#L22-L27
对于 `secp256k1` 类型的秘钥,具体的实现可以在[这里](https://github.com/tendermint/tendermint/blob/bc572217c07b90ad9cee851f193aaa8e9557cbc7/crypto/secp256k1/secp256k1.go#L140)找到。对于`ed25519`类型的密钥,具体实现可以在[这里](https://github.com/tendermint/tendermint/blob/bc572217c07b90ad9cee851f193aaa8e9557cbc7/crypto/ed25519/ed25519.go#L135)找到。
请注意,在 Cosmos SDK 中,`Pubkeys` 并非以其原始格式进行操作。它使用 [`Amino`](../core/encoding.md#amino) 和 [`bech32`](https://en.bitcoin.it/wiki/Bech32) 进行 2 次编码。在 SDK 里面,`Pubkeys` 首先调用 `Bytes()` 方法在原始的 `Pubkey` 中(这里面提供 amino 编码),然后使用 `bech32``ConvertAndEncode` 方法
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/address.go#L579-L729
### 地址
在 Cosmos SDK 默认提送 3 种类型的地址
- `AccAddress` 用于账户
- `ValAddress` 用于验证者操作员
- `ConsAddress` 用于验证者节点
这些地址类型都是一种长度为 20 的十六进制编码的 `[]byte` 数组的别名,这里有一种标准方法从`Pubkey pub`中获取到地址`aa`.
```go
aa := sdk.AccAddress(pub.Address().Bytes())
```
这些地址实现了 `Address` 接口
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/address.go#L71-L80
值得注意的是,`Marhsal()` 和 `Bytes()` 方法都返回相同的 `[]byte` 类型的地址,根据 protobuf 的兼容性要求我们需要前者。同样,`String()` 也被用来返回 `bech32` 编码类型的地址,这个应该是用户看到的最终编码形式。下面是一个例子:
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/address.go#L229-L243
## 接下来 {hide}
学习[gas and fees](./gas-fees.md) {hide}

View File

@ -1,235 +0,0 @@
# SDK 应用程序剖析
## Node Client
全节点的核心进程是基于 SDK 包的。网络中的参与者运行此过程以初始化其状态机,与其他全节点连接并在新块进入时更新其状态机。
```
^ +-------------------------------+ ^
| | | |
| | State-machine = Application | |
| | | | Built with Cosmos SDK
| | ^ + | |
| +----------- | ABCI | ----------+ v
| | + v | ^
| | | |
Blockchain Node | | Consensus | |
| | | |
| +-------------------------------+ | Tendermint Core
| | | |
| | Networking | |
| | | |
v +-------------------------------+ v
```
区块链全节点以二进制形式表示,通常以 `-d` 后缀表示`守护程序`(例如,`appd` 表示 `app``gaiad` 表示 `gaia`)。这个二进制文件是通过编译一个简单的代码文件 main.go 构建的,`main.go` 通常位于`./cmd/appd/`中。 此操作通常通过用 Makefile 编译。
编译了二进制文件,就可以通过运行[`start`命令](https://docs.cosmos.network/master/core/node.html#start-command) 来启动节点。 此命令功能主要执行三件事:
1. [`app.go`] 创建了一个状态机实例。
2. 用最新的已知状态初始化状态机,该状态机是从存储在 `~/.app/data` 文件夹中的 db 中提取的。 此时,状态机的高度为:`appBlockHeight`。
3. 创建并启动一个新的 Tendermint 实例。 该节点将与对等节点进行连接交换信息。 它将从他们那里获取最新的 `blockHeight`,如果它大于本地的 `appBlockHeight`,则重播块以同步到该高度。 如果 `appBlockHeight``0`,则该节点从创世开始,并且 Tendermint 通过 ABCI 接口向 `app` 发送 `InitChain` 初始化链命令,从而触发 [`InitChainer`](https://docs.cosmos.network/master/basics/app-anatomy.html#initchainer)。
## Core Application File
通常,状态机的核心是在名为 `app.go` 的文件中定义的。 它主要包含“应用程序的类型定义”和“创建和初始化它”的功能。
### Type Definition of the Application
在 app.go 中重要的一个是应用程序的 type。 它通常由以下部分组成:
- 在 `app.go` 中定义的自定义应用程序是 `baseapp` 的扩展。 当事务由 Tendermint 发送到应用程序时,`app` 使用 `baseapp` 的方法将它们转送到对应的模块。 baseapp 为应用程序实现了大多数核心逻辑,包括所有的 [ABCI 方法](https://tendermint.com/docs/spec/abci/abci.html#overview)和转送消息逻辑。
- 一条 key 链包含整个状态,他是基于 Cosmos SDK 的 multistore 实现的。 每个模块使用 multistore 的一个或多个存储来存储其状态。可以使用在 `app` 类型中声明的特定键来访问这些存储。这些密钥以及 `keepers` 是 Cosmos SDK 的对象功能模型的核心。
- 模块 `keeper` 的列表。 每个模块都会抽象定义一个 keeper该 keeper 实现模块存储的读写。 一个模块的 `keeper` 方法可以从其他模块(如果已授权)中调用,这就是为什么它们在应用程序的类型中声明并作为接口导出到其他模块的原因,以便后者只能访问授权的功能。
- 应用程序的 `codec` 用于序列化和反序列化数据结构以便存储它们,因为存储只能持久化 `[]bytes``编解码器`必须是确定性的。 默认编解码器为 amino
- 模块管理器是一个对象,其中包含应用程序模块的列表。 它简化了与这些模块相关的操作,例如注册 routes 操作query route 操作或设置各种功能的模块之间顺序执行情况,例如 InitChainer 操作BeginBlocke 操作和 EndBlocker 操作
- 请参阅 [gaia](https://github.com/cosmos/gaia) 中的应用程序类型定义示例
+++ https://github.com/cosmos/gaia/blob/5bc422e6868d04747e50b467e8eeb31ae2fe98a3/app/app.go#L87-L115
### Constructor Function
此函数构造了以上部分中定义的类型的新应用程序。在应用程的 start 命令中使用,它必须具有 AppCreator 签名。
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/server/constructors.go#L20
以下是此功能执行的主要操作:
- 创建初始化一个新的 codec 实例,并使用基础模块管理器初始化每个应用程序模块的 `codec`
- 使用 baseapp 实例,编解码器和所有适当的存储键的引用实例化一个新应用程序。
- 使用每个应用程序模块的 `NewKeeper` 功能实例化在应用程序的`类型`中定义的所有 keeper。 注意,所有 keeper 必须以正确的顺序实例化,因为一个模块的 NewKeeper 可能需要引用另一个模块的 `keeper`
- 使用每个应用模块的 AppModule 来实例化应用程序的模块管理器
- 使用模块管理器,初始化应用程序的 routes 和 query route。 当事务由 Tendermint 通过 ABCI 中继到应用程序时,它使用此处定义的路由被路由到相应模块的回调 handler。 同样,当应用程序收到查询时,使用此处定义的查询路由将其路由到适当的模块的 querier。
- 使用模块管理器,注册应用程序的模块的 invariants。 invariants 是在每个块末尾评估的变量(例如 token 的总供应量)。 检查不变式的过程是通过 InvariantsRegistry 的特殊模块完成的。 invariants 应等于模块中定义的预测值。 如果该值与预测的值不同,则将触发不变注册表中定义的特殊逻辑(通常会中断链)。这对于确保不会发现任何严重错误并产生难以修复的长期影响非常有用。
- 使用模块管理器,在每个应用程序的模块 的 InitGenesisBegingBlocker 和 EndBlocker 函数之间设置执行顺序。 请注意,并非所有模块都实现这些功能。
- 模块实现这些功能。
- 设置其余的应用程序参数:
- `InitChainer` 于在应用程序首次启动时对其进行初始化。
- `BeginBlocker``EndBlocker`:在每个块的开始和结尾处调用。
- `anteHandler`:用于处理费用和签名验证。
- 挂载存储.
- 返回应用实例.
请注意,此函数仅创建该应用的一个实例,而如果重新启动节点,则状态将从 `〜/.app/data` 文件夹中保留下来状态加载如果节点是第一次启动则从创世文件生成。See an example of application constructor from [`gaia`](https://github.com/cosmos/gaia):
+++ https://github.com/cosmos/gaia/blob/f41a660cdd5bea173139965ade55bd25d1ee3429/app/app.go#L110-L222
### InitChainer
InitChainer 用于根据创始文件(即创始账户的代币余额)初始化应用程序的状态。 当应用程序从 Tendermint 引擎收到`InitChain`消息时调用该消息,该消息是在节点以`appBlockHeight == 0`(即创世)启动。 应用程序必须通过[`SetInitChainer`](https://godoc.org/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetInitChainer)方法设置其[constructor](https://docs.cosmos.network/master/basics/app-anatomy.html#constructor-function)中的`Initchainer`。
通常,`InitChainer`主要由每个应用程序模块的 InitGenesis 函数组成。 这是通过调用模块管理器的 InitGenesis 函数来完成的,而模块管理器的 InitGenesis 函数将依次调用其包含的每个模块的 InitGenesis 函数。 请注意,必须使用模块管理器的 SetOrderInitGenesis 方法设置模块的 InitGenesis 函数的顺序。 这是在 应用程序的构造函数 application-constructor 中完成的,必须在 SetInitChainer 之前调用 SetOrderInitGenesis。
查看来自[gaia](https://github.com/cosmos/gaia)的 InitChainer 的示例:
See an example of an `InitChainer` from [`gaia`](https://github.com/cosmos/gaia):
查看来自 [`gaia`](https://github.com/cosmos/gaia)的 `InitChainer` 的示例:
+++ https://github.com/cosmos/gaia/blob/f41a660cdd5bea173139965ade55bd25d1ee3429/app/app.go#L235-L239
### BeginBlocker and EndBlocker
该 SDK 为开发人员提供了在其应用程序中实现自定义代码可能性。 这是通过两个名为 `BeginBlocker``EndBlocker` 的函数实现的。当应用程序分别从 Tendermint 引擎接收到 `BeginBlock``EndBlock` 消息时,将调用它们,它们分别在每个块的开始和结尾处发生。应用程序必须通过 [SetBeginBlocker](https://godoc.org/github.com/cosmos/cosmos-sdk/baseapp) 和 [SetEndBlocker](https://godoc.org/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetEndBlocker) 方法在其 constructor 中设置 `BeginBlocker``EndBlocker`
通常,`BeginBlocker` 和 `EndBlocker` 函数主要由每个应用程序模块的 `BeginBlock``EndBlock` 函数组成。 这是通过调用模块管理器的 BeginBlock 和 EndBlock 函数来完成的,而后者又会调用其包含的每个模块的 BeginBLock 和 EndBlock 函数。 请注意,必须分别在模块管理器中使用 SetOrderBeginBlock 和 SetOrderEndBlock 方法来设置模块的 BegingBlock 和 EndBlock 函数必须调用的顺序。这是通过应用程序的构造函数中的模块管理器完成的,必须调用 SetOrderBeginBlock 和 SetOrderEndBlock 方法。 在 SetBeginBlocker 和 SetEndBlocker 函数之前。
附带说明,请记住特定于应用程序的区块链是确定性的,这一点很重要。开发人员必须注意不要在 BeginBlocker 或 EndBlocker 中引入不确定性,还必须注意不要使它们在计算上过于昂贵,因为[gas]不会限制计算代价当调用 BeginBlocker 和 EndBlocker 执行。
请参阅 [gaia](https://github.com/cosmos/gaia)中的 `BeginBlocker``EndBlocker` 函数的示例。
+++ https://github.com/cosmos/gaia/blob/f41a660cdd5bea173139965ade55bd25d1ee3429/app/app.go#L224-L232
### Register Codec
MakeCodec 函数是 app.go 文件的最后一个重要功能。 此函数的目的是使用 RegisterLegacyAminoCodec 函数实例化 codec`cdc`,例如 amino 初始化 SDK 的编解码器以及每个应用程序的模块。
为了注册应用程序的模块,`MakeCodec` 函数在 `ModuleBasics` 上调用 `RegisterLegacyAminoCodec`。`ModuleBasics` 是一个基本管理器,其中列出了应用程序的所有模块。 它在`init()`函数中得到实例化,仅用于注册应用程序模块的非依赖元素(例如编解码器)。 要了解有关基本模块管理器的更多信息,请点击[这里](https://docs.cosmos.network/master/building-modules/module-manager.html#basicmanager)。
请参阅 [gaia](https://github.com/cosmos/gaia) 中的 `MakeCodec` 示例:
+++ https://github.com/cosmos/gaia/blob/f41a660cdd5bea173139965ade55bd25d1ee3429/app/app.go#L64-L70
## Modules
Modules 是 SDK 应用程序的灵魂。它们可以被视为状态机中的状态机。当交易通过 ABCI 从底层的 Tendermint 引擎中继到应用程序时,它由 baseapp 找到对应的模块以便进行处理。这种范例使开发人员可以轻松构建复杂的状态机,因为他们所需的大多数模块通常已经存在。对于开发人员而言,构建 SDK 应用程序所涉及的大部分工作都围绕构建其应用程序尚不存在的自定义模块,并将它们与已经存在的模块集成到一个统一的应用程序中。在应用程序目录中,标准做法是将模块存储在 `x/` 文件夹中(不要与 SDK 的`x/`文件夹混淆,该文件夹包含已构建的模块)。
### Application Module Interface
模块必须实现 Cosmos SDK AppModuleBasic 中的 [interfaces](https://docs.cosmos.network/master/building-modules/module-manager.html#application-module-interfaces) 和 AppModule。 前者实现了模块的基本非依赖性元素,例如`编解码器`,而后者则处理了大部分模块方法(包括需要引用其他模块的`keeper`的方法)。`AppModule` 和 `AppModuleBasic` 类型都在名为 `module.go` 的文件中定义。
AppModule 在模块上公开了一组有用的方法,这些方法有助于将模块组合成一个一致的应用程序。 这些方法是从模块管理器中调用的,该模块管理应用程序的模块集合。
### Message Types
每个 `module` 定义 [messages](https://docs.cosmos.network/master/building-modules/messages-and-queries.html#messages) 接口。 每个 `transaction` 包含一个或多个 `messages`
当全节点接收到有效的交易块时Tendermint 通过 [`DeliverTx`](https://tendermint.com/docs/app-dev/abci-spec.html#delivertx) 将每个交易发到应用程序。然后,应用程序处理事务:
- 收到交易后,应用程序首先从 `[]bytes` 反序列化得到。
- 然后,在提取交易中包含的消息之前,它会验证有关交易的一些信息,例如费用支付和签名。
- 使用 message 的 Type()方法baseapp 可以将其发到对应模块的回调 handler 以便对其进行处理。
- 如果消息已成功处理,则状态将更新。
有关事务生命周期的更多详细信息,请看[这里](./ tx-lifecycle.md)。
模块开发人员在构建自己的模块时会创建自定义消息类型。 通常的做法是在消息的类型声明前加上 `Msg`。 例如,消息类型 `MsgSend` 允许用户传输 tokens
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/bank/internal/types/msgs.go#L10-L15
它由 `bank` 模块的回调 `handler` 处理,最终会调用 `auth` 模块来写 `keeper` 以更新状态。
### Handler
回调 `handler` 是指模块的一部分,负责处理 `baseapp` 传递的 `message` 消息。 仅当通过 ABCI 接口的 DeliverTx 消息从 Tendermint 收到事务时,才执行模块的`处理程序`功能。 如果通过 CheckTx仅执行无状态检查和与费用相关的有状态检查。为了更好地理解 `DeliverTx``CheckTx` 之间的区别以及有状态和无状态检查之间的区别,请看[这里](./tx-lifecycle.md)。
模块的`处理程序`通常在名为 `handler.go` 的文件中定义,并包括:
- NewHandler 将消息发到对应的回调 `handler`。 该函数返回一个 `handler` 函数,此前这个函数在 `AppModule` 中注册,以在应用程序的模块管理器中用于初始化应用程序的路由器。接下来是 [nameservice tutorial](https://github.com/cosmos/sdk-tutorials/tree/master/nameservice) 的一个例子。
+++ https://github.com/cosmos/sdk-tutorials/blob/86a27321cf89cc637581762e953d0c07f8c78ece/nameservice/x/nameservice/internal/keeper/querier.go#L19-L32
- 模块定义的每种消息类型的处理函数。开发人员在这些函数中编写消息处理逻辑。这通常包括进行状态检查以确保消息有效,并调用 [`keeper`](https://docs.cosmos.network/master/basics/app-anatomy.html#keeper) 的方法来更新状态。
处理程序函数返回结果类型为 sdk.Result该结果通知应用程序消息是否已成功处理
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/result.go#L15-L40
### Querier
`Queriers``handlers` 非常相似,除了它们向状态查询用户而不是处理事务。 最终用户从 interface 发起 query最终用户会提供 `queryRoute` 和一些 `data`。 然后使用 `queryRoute` 通过 `baseapp``handleQueryCustom` 方法查询到正确的应用程序的 `querier` 函数
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/baseapp/abci.go#L395-L453
模块的 Querier 是在名为 querier.go 的文件中定义的,包括:
- NewQuerier 将查找到对应 query 函数。 此函数返回一个 `querier` 函数,此前它在 AppModule 中注册,以在应用程序的模块管理器中用于初始化应用程序的查询路由器。请参阅 [nameservice demo]https://github.com/cosmos/sdk-tutorials/tree/master/nameservice中的此类切换示例
+++ https://github.com/cosmos/sdk-tutorials/blob/86a27321cf89cc637581762e953d0c07f8c78ece/nameservice/x/nameservice/internal/keeper/querier.go#L19-L32
- 对于模块定义的每种需要查询的数据类型,都具有一个查询器功能。开发人员在这些函数中编写查询处理逻辑。这通常涉及调用 `keeper` 的方法来查询状态并将其序列化为 JSON。
### Keeper
[`Keepers`](https://docs.cosmos.network/master/building-modules/keeper.html)是其模块存储器件。要在模块的存储区中进行读取或写入,必须使用其 `keeper` 方法之一。这是由 Cosmos SDK 的 object-capabilities 模型确保的。 只有持有存储密钥的对象才能访问它,只有模块的 `keeper` 才应持有该模块存储的密钥。
`Keepers` 通常在名为 `keeper.go` 的文件中定义。 它包含 `keeper` 的类型定义和方法。
`keeper` 类型定义通常包括:
- 多重存储中模块存储的`密钥`。
- 参考**其他模块的`keepers`**。 仅当 `keeper` 需要访问其他模块的存储(从它们读取或写入)时才需要。
- 对应用程序的`编解码器`的引用。 `keeper` 需要它在存储结构之前序列化处理,或在检索它们时将反序列化处理,因为存储仅接受 `[]bytes` 作为值。
与类型定义一起keeper.go 文件的一个重要组成部分是 Keeper 的构造函数 NewKeeper。 该函数实例化上面定义的类型的新 `keeper`,并带有 `codec`,存储 `keys` 以及可能引用其他模块的 `keeper` 作为参数。从应用程序的构造函数中调用 `NewKeeper` 函数。文件的其余部分定义了 `keeper` 的方法,主要是 getter 和 setter。
### Command-Line and REST Interfaces
每个模块都定义了 application-interfaces 向用户公开的命令行命令和 REST routes。 用户可以创建模块中定义的类型的消息,或查询模块管理的状态的子集。
#### CLI
通常,与模块有关的命令在模块文件夹中名为 `client/cli` 的文件夹中定义。CLI 将命令分为交易和查询两类,分别在 `client/cli/tx.go``client/cli/query.go` 中定义。这两个命令基于 [Cobra Library](https://github.com/spf13/cobra)之上:
- Transactions 命令使用户可以生成新的事务,以便可以将它们包含在块中并更新状态。应该为模块中定义的每个消息类型 message-types 创建一个命令。该命令使用户提供的参数调用消息的构造函数并将其包装到事务中。SDK 处理签名和其他事务元数据的添加。
- 用户可以查询模块定义的状态子集。查询命令将查询转发到应用程序的查询路由器,然后将查询路由到提供的`queryRoute`参数的相应 querier。
#### REST
模块的 REST 接口允许用户生成事务并通过对应用程序的 light client daemonLCD 查询状态。 REST 路由在 `client/rest/rest.go` 文件中定义,该文件包括:
- `RegisterRoutes` 函数,用于注册路由。从主应用程序的接口 application-interfaces 中为应用程序内使用的每个模块调用此函数。SDK 中使用的路由器是 [Gorilla's mux](https://github.com/gorilla/mux)。
- 需要公开的每个查询或事务创建功能的自定义请求类型定义。这些自定义请求类型基于 Cosmos SDK 的基本`请求`类型构建:
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/rest/rest.go#L47-L60
- 每个请求的一个处理函数可以找到给定的模块。 这些功能实现了服务请求所需的核心逻辑。
## Application Interface
Interfaces 允许用户与全节点客户端进行交互。 这意味着从全节点查询数据,或者接受全节点中包含在块中的新事务。
通过汇总在应用程序使用的每个模块中定义的 CLI 命令构建 SDK 应用程序的 CLI。 应用程序的 CLI 通常具有后缀-cli例如 appcli并在名为`cmd / appcli / main.go`的文件中定义。 该文件包含:
- main()函数,用于构建 appcli 接口客户端。这个函数准备每个命令,并在构建它们之前将它们添加到`rootCmd`中。在 appCli 的根部,该函数添加了通用命令,例如 statuskeys 和 config查询命令tx 命令和 rest-server。
- 查询命令是通过调用`queryCmd`函数添加的,该函数也在 appcli / main.go 中定义。此函数返回一个 Cobra 命令,其中包含在每个应用程序模块中定义的查询命令(从`main()`函数作为`sdk.ModuleClients`数组传递),以及一些其他较低级别的查询命令,例如阻止或验证器查询。查询命令通过使用 CLI 的命令“ appcli query [query]”来调用。
- 通过调用`txCmd`函数来添加**交易命令**。与`queryCmd`类似,该函数返回一个 Cobra 命令,其中包含在每个应用程序模块中定义的 tx 命令,以及较低级别的 tx 命令,例如事务签名或广播。使用 CLI 的命令`appcli tx [tx]`调用 Tx 命令。
- registerRoutes 函数,在初始化 轻客户端LCD时从 main()函数调用。 “ registerRoutes”调用应用程序每个模块的“ RegisterRoutes”功能从而注册该模块 routes 到 LCD 的查询路由。可以通过运行以下命令“ appcli rest-server”来启动 LCD。
从[nameservice demo](https://github.com/cosmos/sdk-tutorials/tree/master/nameservice)中查看应用程序的主要命令行文件的示例。
+++ https://github.com/cosmos/sdk-tutorials/blob/86a27321cf89cc637581762e953d0c07f8c78ece/nameservice/cmd/nscli/main.go
## Dependencies and Makefile
因为开发人员可以自由选择其依赖项管理器和项目构建方法。 也就是说,当前最常用的版本控制框架是[`go.mod`](https://github.com/golang/go/wiki/Modules)。 它确保在整个应用程序中使用的每个库都以正确的版本导入。 请参阅[demo](https://github.com/cosmos/sdk-tutorials/tree/master/nameservice)中的示例:
+++ https://github.com/cosmos/sdk-tutorials/blob/c6754a1e313eb1ed973c5c91dcc606f2fd288811/go.mod#L1-L18
为了构建应用程序,通常使用[Makefile](https://en.wikipedia.org/wiki/Makefile)。 Makefile 主要确保在构建应用程序的两个入口点 [`appd`](https://docs.cosmos.network/master/basics/app-anatomy.html#node-client) 和 [`appcli`](https://docs.cosmos.network/master/basics/app-anatomy.html#application-interface) 之前运行 `go.mod`。 请参阅 nameservice demo 中的 Makefile 示例
+++ https://github.com/cosmos/sdk-tutorials/blob/86a27321cf89cc637581762e953d0c07f8c78ece/nameservice/Makefile
## Next
了解有关[交易生命周期](./ tx-lifecycle.md)的更多信息

View File

@ -1,84 +0,0 @@
**原文路径:https://github.com/cosmos/cosmos-sdk/blob/master/docs/basics/gas-fees.md**
# Gas and Fees
## 必备阅读 {hide}
- [一个 SDK 程序的剖析](./app-anatomy.md) {prereq}
## `Gas` and `Fees`的介绍
在 Cosmos SDK 中,`gas`是一种特殊的单位,用于跟踪执行期间的资源消耗。每当对储存进行读写操作的时候会消耗`gas`,如果要进行比较复杂的计算的话也会消耗`gas`。它主要有两个目的:
- 确保区块不会消耗太多资源而且能顺利完成。这个默认在 SDK 的 [block gas meter](#block-gas-meter) 中保证
- 防止来自终端用户的垃圾消息和滥用。为此,通常会为 [`message`](../building-modules/messages-and-queries.md#messages) 执行期间的消耗进行定价,并产生 `fee`(`fees = gas * gas-prices`)。`fees` 通常必须由 `message` 的发送者来支付。请注意SDK 并没有强制执行对 `gas` 定价,因为可能会有其他的方法来防止垃圾消息(例如带宽方案)。尽管如此,大多数应用程序仍然会使用`fee` 方式来防止垃圾消息。这个机制通过 [`AnteHandler`](#antehandler) 来完成.
## Gas Meter
在 Cosmos SDK 中 `gas` 是一种简单的 `uint64` 类型,被称之为 `gas meter` 的对象进行管理Gas meters 实现了 `GasMeter` 接口
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/store/types/gas.go#L31-L39
这里:
- `GasConsumed()` 返回 `GasMeter` 实例中消耗的 `gas` 的数量
- `GasConsumedToLimit()` 返回 `GasMeter` 实例消耗的 gas 数量,如果达到上限的话就返回上限
- `Limit()` 返回 `GasMeter` 实例的上限,如果是 0 则表示对 `gas` 的数量没有限制
- `ConsumeGas(amount Gas, descriptor string)` 消耗提供的 `gas`,如果 `gas` 溢出了,使用 `descriptor` 内容进行报错,如果 `gas` 并不是无限的,则超过限制就会报错。
- `IsPastLimit()` 如果 `gas` 消耗超过了 `GasMeter` 的限制则返回 `true`,其它返回 `false`
- `IsOutOfGas()` 如果 `gas` 消耗大于或等于了 `GasMeter` 的限制则返回 `true`,其它返回 `false`
`GasMeter` 通常保存在 [`ctx`](../core/context.md) 中,`gas` 消耗的方式如下:
```go
ctx.GasMeter().ConsumeGas(amount, "description")
```
通常Cosmos SDK 使用两种不同的 `GasMeter`[main gas meter](#main-gas-metter[) 和 [block gas meter](#block-gas-meter)。
### 主 Gas Meter
`ctx.GasMeter()` 是应用程序的主 `GasMeter`,主 `GasMeter` 通过 `BeginBlock` 中的 `setDeliverState` 进行初始化,然后跟踪导致状态转换的执行序列中的 `gas` 消耗。也即是说它的更新由 [`BeginBlock`](../core/baseapp.md#beginblock)[`DeliverTx`](../core/baseapp.md#delivertx) 和 [`EndBlock`](../core/baseapp.md#endblock) 进行操作。主 `GasMeter` 必须在 [`AnteHandler`](#antehandler)中 **设置为 0**,以便它能获取每个 transaction 的 Gas 消耗
`gas`消耗可以手工完成,模块开发者通常在 [`BeginBlocker`,`EndBlocker`](../building-modules/beginblock-endblock.md) 或者 [`handler`](../building-modules/handler.md) 上执行,但大多数情况下,只要对储存区进行了读写,它就会自动完成。这种自动消耗的逻辑在[`GasKv`](../core/store.md#gaskv-store)中完成.
### 块 Gas Meter
`ctx.BlockGasMeter()` 是跟踪每个区块 `gas` 消耗并保证它没有超过限制的 `GasMeter`。每当 [`BeginBlock`](../core/baseapp.md#beginblock) 被调用的时候一个新的 `BlockGasMeter` 实例将会被创建。`BlockGasMeter` 的 `gas` 是有限的,每个块的 `gas` 限制应该在应用程序的共识参数中定义Cosmos SDK 应用程序使用 Tendermint 提供的默认共识参数:
+++ https://github.com/tendermint/tendermint/blob/f323c80cb3b78e123ea6238c8e136a30ff749ccc/types/params.go#L65-L72
当通过 `DeliverTx` 处理新的 [transaction](../core/transactions.md) 的时候,`BlockGasMeter` 的当前值会被校验是否超过上限,如果超过上限,`DeliverTx` 直接返回,由于 `BeginBlock` 会消耗 `gas`,这种情况可能会在第一个 `transaction` 到来时发生,如果没有发生这种情况,`transaction`将会被正常的执行。在 `DeliverTx` 的最后,`ctx.BlockGasMeter()` 会追踪 `gas` 消耗并将它增加到处理 `transaction``gas` 消耗中.
```go
ctx.BlockGasMeter().ConsumeGas(
ctx.GasMeter().GasConsumedToLimit(),
"block gas meter",
)
```
## AnteHandler
`AnteHandler` 是一个特殊的处理程序,它在 `CheckTx``DeliverTx` 期间为每一个 `transaction` 的每个 `message` 处理之前执行。`AnteHandler` 相比 `handler` 有不同的签名:
```go
// AnteHandler authenticates transactions, before their internal messages are handled.
// If newCtx.IsZero(), ctx is used instead.
type AnteHandler func(ctx Context, tx Tx, simulate bool) (newCtx Context, result Result, abort bool)
```
`AnteHandler` 不是在核心 SDK 中实现的,而是在每一个模块中实现的,这使开发者可以使用适合其程序需求的`AnteHandler`版本,也就是说当前大多数应用程序都使用 [`auth` module](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth) 中定义的默认实现。下面是 `AnteHandler` 在普通 Cosmos SDK 程序中的作用:
- 验证事务的类型正确。事务类型在实现 `anteHandler` 的模块中定义,它们遵循事务接口:
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/tx_msg.go#L33-L41
这使开发人员可以使用各种类型的应用程序进行交易。 在默认的 auth 模块中,标准事务类型为 StdTx
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/auth/types/stdtx.go#L22-L29
- 验证交易中包含的每个 [`message`](../building-modules/messages-and-queries.md#messages) 的签名,每个 `message` 应该由一个或多个发送者签名,这些签名必须在 `anteHandler` 中进行验证.
- 在 `CheckTx` 期间,验证 `transaction` 提供的 `gas prices` 是否大于本地配置 `min-gas-prices`(提醒一下,`gas-prices` 可以从以下等式中扣除`fees = gas * gas-prices`)`min-gas-prices` 是每个独立节点的本地配置,在`CheckTx`期间用于丢弃未提供最低费用的交易。这确保了内存池不会被垃圾交易填充.
- 设置 `newCtx.GasMeter` 到 0限制为`GasWanted`。**这一步骤非常重要**,因为它不仅确保交易不会消耗无限的天然气,而且还会在每个 `DeliverTx` 重置 `ctx.GasMeter`(每次 `DeliverTx` 被调用的时候都会执行 `anteHandler``anteHandler` 运行之后 `ctx` 将会被设置为 `newCtx`)
如上所述,`anteHandler` 返回 `transaction` 执行期间所能消耗的最大的 `gas` 数量,称之为 `GasWanted`。最后实际 `gas` 消耗数量记为 `GasUsed`,因此我们必须使 `GasUsed =< GasWanted`。当返回时 `GasWanted``GasUsed` 都会被中继到共识引擎中.

View File

@ -1,162 +0,0 @@
# Transaction 的生命周期
本文档描述了 Transaction 从创建到提交的生命周期Transaction 的定义在[其他文档](https://docs.cosmos.network/master/core/transactions.html)中有详细描述,后文中 Transaction 将统一被称为`Tx`。
## 创建
### Transaction 的创建
命令行界面是主要的应用程序界面之一,`Tx` 可以由用户输入[以下命令](https://docs.cosmos.network/master/core/cli.html)来创建,其中 `[command]``Tx` 的类型,`[args]` 是相关参数,`[flags]` 是相关配置例如 gas price
```bash
[appname] tx [command] [args] [flags]
```
此命令将自动**创建** `Tx`,使用帐户的私钥对其进行**签名**,并将其**广播**到其他节点。
创建 `Tx` 有一些必需的和可选的参数,其中 `--from` 指定该 `Tx` 的发起[账户](https://docs.cosmos.network/master/basics/accounts.html),例如一个发送代币的`Tx`,则将从 `from` 指定的账户提取资产。
#### Gas 和 Fee
此外,用户可以使用这几个[参数](https://docs.cosmos.network/master/core/cli.html)来表明他们愿意支付多少 [fee](https://docs.cosmos.network/master/basics/gas-fees.html)
- `--gas` 指的是 [gas](https://docs.cosmos.network/master/basics/gas-fees.html) 的数量gas 代表 `Tx` 消耗的计算资源,需要消耗多少 gas 取决于具体的 `Tx`,在 `Tx` 执行之前无法被精确计算出来,但可以通过在 `--gas` 后带上参数 `auto` 来进行估算。
- `--gas-adjustment`(可选)可用于适当的增加 `gas`,以避免其被低估。例如,用户可以将 `gas-adjustment` 设为 1.5,那么被指定的 gas 将是被估算 gas 的 1.5 倍。
- `--gas-prices` 指定用户愿意为每单位 gas 支付多少 fee可以是一种或多种代币。例如`--gas-prices=0.025uatom, 0.025upho` 就表明用户愿意为每单位的 gas 支付 0.025uatom 和 0.025upho。
- `--fees` 指定用户总共愿意支付的 fee。
所支付 fee 的最终价值等于 gas 的数量乘以 gas 的价格。换句话说,`fees = ceil(gas * gasPrices)`。由于可以使用 gas 价格来计算 fee也可以使用 fee 来计算 gas 价格,因此用户仅指定两者之一即可。
随后,验证者通过将给定的或计算出的 `gas-prices` 与他们本地的 `min-gas-prices` 进行比较,来决定是否在其区块中写入该 `Tx`。如果 `gas-prices` 不够高,该 `Tx` 将被拒绝,因此鼓励用户支付更多 fee。
#### CLI 示例
应用程序的用户可以在其 CLI 中输入以下命令,用来生成一个将 1000uatom 从 `senderAddress` 发送到 `recipientAddress``Tx`,该命令指定了用户愿意支付的 gas其中 gas 数量为自动估算的 1.5 倍,每单位 gas 价格为 0.025uatom)。
```bash
appcli tx send <recipientAddress> 1000uatom --from <senderAddress> --gas auto --gas-adjustment 1.5 --gas-prices 0.025uatom
```
#### 其他的 Transaction 创建方法
命令行是与应用程序进行交互的一种简便方法,但是 `Tx` 也可以使用 [REST interface](https://docs.cosmos.network/master/core/grpc_rest.html) 或应用程序开发人员定义的某些其他入口点来创建命令行。从用户的角度来看,交互方式取决于他们正在使用的是页面还是钱包(例如, `Tx` 使用 [Lunie.io](https://lunie.io/#/) 创建并使用 Ledger Nano S 对其进行签名)。
## 添加到交易池
每个全节点Tendermint 节点)接收到 `Tx` 后都会发送一个名为 `CheckTx` 的 [ABCI message](https://tendermint.com/docs/spec/abci/abci.html#messages),用来检查 `Tx` 的有效性,`CheckTx` 会返回 `abci.ResponseCheckTx`
如果 `Tx` 通过检查,则将其保留在节点的 [**交易池**](https://tendermint.com/docs/tendermint-core/mempool.html#mempool)(每个节点唯一的内存事务池)中等待出块,`Tx` 如果被发现无效,诚实的节点将丢弃该 `Tx`。在达成共识之前,节点会不断检查传入的 `Tx` 并将其广播出去。
### 检查的类型
全节点在 `CheckTx` 期间对 `Tx` 先执行无状态检查,然后进行有状态检查,目的是尽早识别并拒绝无效 `Tx`,以免浪费计算资源。
**_无状态检查_**不需要知道节点的状态,即轻客户端或脱机节点都可以检查,因此计算开销较小。无状态检查包括确保地址不为空、强制使用非负数、以及定义中指定的其他逻辑。
**_状态检查_**根据提交的状态验证 `Tx``Message`。例如,检查相关值是否存在并能够进行交易,账户是否有足够的资产,发送方是否被授权或拥有正确的交易所有权。在任何时刻,由于不同的原因,全节点通常具有应用程序内部状态的[多种版本](https://docs.cosmos.network/master/core/baseapp.html#volatile-states)。例如,节点将在验证 `Tx` 的过程中执行状态更改,但仍需要最后的提交状态才能响应请求,节点不能使用未提交的状态更改来响应请求。
为了验证 `Tx`,全节点调用的 `CheckTx` 包括无状态检查和有状态检查,进一步的验证将在 [`DeliverTx`](#delivertx) 阶段的后期进行。其中 `CheckTx` 从对 `Tx` 进行解码开始。
### 解码
`Tx` 从应用程序底层的共识引擎(如 Tendermint被接收时其仍处于 `[]byte`[编码](https://docs.cosmos.network/master/core/encoding.html) 形式,需要将其解码才能进行操作。随后,[`runTx`](https://docs.cosmos.network/master/core/baseapp.html#runtx-and-runmsgs) 函数会被调用,并以 `runTxModeCheck` 模式运行,这意味着该函数将运行所有检查,但是会在执行 `Message` 和写入状态更改之前退出。
### ValidateBasic
[Message](https://docs.cosmos.network/master/core/transactions.html#messages) 是由 module 的开发者实现的 `Msg` 接口中的一个方法。它应包括基本的**无状态**完整性检查。例如,如果 `Message` 是要将代币从一个账户发送到另一个账户,则 `ValidateBasic` 会检查账户是否存在,并确认账户中代币金额为正,但不需要了解状态,例如帐户余额。
### AnteHandler
[`AnteHandler`](https://docs.cosmos.network/master/basics/gas-fees.html#antehandler)是可选的,但每个应用程序都需要定义。`AnteHandler` 使用副本为特定的 `Tx` 执行有限的检查,副本可以使对 `Tx` 进行状态检查时无需修改最后的提交状态,如果执行失败,还可以还原为原始状态。
例如,[`auth`](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth/spec) 模块的 `AnteHandler` 检查并增加序列号,检查签名和帐号,并从 `Tx` 的第一个签名者中扣除费用,这个过程中所有状态更改都使用 `checkState`
### Gas
[`Context`](https://docs.cosmos.network/master/core/context.html) 相当于`GasMeter`,会计算出在 `Tx` 的执行过程中多少 `gas` 已被使用。用户提供的 `Tx` 所需的 `gas` 数量称为 `GasWanted`。`Tx` 在实际执行过程中消耗的 `gas` 被称为`GasConsumed`,如果 `GasConsumed` 超过 `GasWanted`,将停止执行,并且对状态副本的修改不会被提交。否则,`CheckTx` 设置 `GasUsed` 等于 `GasConsumed` 并返回结果。在计算完 gas 和 fee 后,验证器节点检查用户指定的值 `gas-prices` 是否小于其本地定义的值 `min-gas-prices`
### 丢弃或添加到交易池
如果在 `CheckTx` 期间有任何失败,`Tx` 将被丢弃,并且 `Tx` 的生命周期结束。如果 `CheckTx` 成功,则 `Tx` 将被广播到其他节点,并会被添加到交易池,以便成为待出区块中的候选 `Tx`
**交易池**保存所有全节点可见的 `Tx`,全节点会将其最近的 `Tx` 保留在**交易池缓存**中,作为防止重放攻击的第一道防线。理想情况下,`mempool.cache_size` 的大小足以容纳整个交易池中的所有 `Tx`。如果交易池缓存太小而无法跟踪所有 `Tx``CheckTx` 会识别出并拒绝重放的 `Tx`
现有的预防措施包括 fee 和`序列号`计数器,用来区分重放 `Tx` 和相同的 `Tx`。如果攻击者尝试向某个节点发送多个相同的 `Tx`,则保留交易池缓存的完整节点将拒绝相同的 `Tx`,而不是在所有 `Tx` 上运行 `CheckTx`。如果 `Tx` 有不同的`序列号`,攻击者会因为需要支付费用而取消攻击。
验证器节点与全节点一样,保留一个交易池以防止重放攻击,但它也用作出块过程中未经验证的交易池。请注意,即使 `Tx` 在此阶段通过了所有检查,仍然可能会被发现无效,因为 `CheckTx` 没有完全验证 `Tx``CheckTx` 实际上并未执行 `message`)。
## 写入区块
共识是验证者节点就接受哪些 `Tx` 达成协议的过程,它是**反复进行**的。每个回合都始于出块节点创建一个包含最近 `Tx` 的区块,并由验证者节点(具有投票权的特殊全节点)负责达成共识,同意接受该区块或出一个空块。验证者节点执行共识算法,例如[Tendermint BFT](https://tendermint.com/docs/spec/consensus/consensus.html#terms),调用 ABCI 请求确认 `Tx`,从而达成共识。
达成共识的第一步是**区块提案**,共识算法从验证者节点中选择一个出块节点来创建和提议一个区块,用来写入 `Tx``Tx` 必须在该提议者的交易池中。
## 状态变更
共识的下一步是执行 `Tx` 以完全验证它们,所有的全节点收到出块节点广播的区块并调用 ABCI 函数[`BeginBlock`](https://docs.cosmos.network/master/basics/app-anatomy.html#beginblocker-and-endblocker)`DeliverTx`,和 [`EndBlock`](https://docs.cosmos.network/master/basics/app-anatomy.html#beginblocker-and-endblocker)。全节点在本地运行的每个过程将产生一个明确的结果,因为 `message` 的状态转换是确定性的,并且 `Tx` 在提案中有明确的顺序。
```
-----------------------------
|Receive Block Proposal|
-----------------------------
|
v
-----------------------------
| BeginBlock |
-----------------------------
|
v
-----------------------------
| DeliverTx(tx0) |
| DeliverTx(tx1) |
| DeliverTx(tx2) |
| DeliverTx(tx3) |
| . |
| . |
| . |
-----------------------------
|
v
-----------------------------
| EndBlock |
-----------------------------
|
v
-----------------------------
| Consensus |
-----------------------------
|
v
-----------------------------
| Commit |
-----------------------------
```
### DeliverTx
[`baseapp`](https://docs.cosmos.network/master/core/baseapp.html) 中定义的 ABCI 函数 `DeliverTx` 会执行大部分状态转换,`DeliverTx` 会针对共识中确定的顺序,对块中的每个 `Tx` 按顺序运行。`DeliverTx` 几乎和 `CheckTx` 相同,但是会以 deliver 模式调用[`runTx`](../core/baseapp.md#runtx)函数而不是 check 模式。全节点不使用 `checkState`,而是使用 `deliverState`
- **解码:** 由于 `DeliverTx` 是通过 ABCI 调用的,因此 `Tx` 会以 `[]byte` 的形式被接收。节点首先会对 `Tx` 进行解码,然后在 `runTxModeDeliver` 中调用 `runTx``runTx` 除了会执行 `CheckTx` 中的检查外,还会执行 `Tx` 和并写入状态的变化。
- **检查:** 全节点会再次调用 `validateBasicMsgs``AnteHandler`。之所以进行第二次检查,是因为在 `Tx` 进交易池的过程中,可能没有相同的 `Tx`,但恶意出块节点的区块可能包括无效 `Tx`。但是这次检查特殊的地方在于,`AnteHandler` 不会将 `gas-prices` 与节点的 `min-gas-prices` 比较,因为每个节点的 `min-gas-prices` 可能都不同,这样比较的话可能会产生不确定的结果。
- **路由和 Handler** `CheckTx` 退出后,`DeliverTx` 会继续运行 [`runMsgs`](https://docs.cosmos.network/master/core/baseapp.html#runtx-and-runmsgs) 来执行 `Tx` 中的每个 `Msg`。由于 `Tx` 可能具有来自不同模块的 `message`,因此 `baseapp` 需要知道哪个模块可以找到适当的 `Handler`。因此,`路由`通过[模块管理器](https://docs.cosmos.network/master/building-modules/module-manager.html)来检索路由名称并找到对应的[`Handler`](https://docs.cosmos.network/master/building-modules/handler.html)。
- **Handler** `handler` 是用来执行 `Tx` 中的每个 `message`,并且使状态转换到从而保持 `deliverTxState`。`handler` 在 `Msg` 的模块中定义,并写入模块中的适当存储区。
- **Gas**`Tx` 被传递的过程中,`GasMeter` 是用来记录有多少 gas 被使用,如果执行完成,`GasUsed` 会被赋值并返回 `abci.ResponseDeliverTx`。如果由于 `BlockGasMeter` 或者 `GasMeter` 耗尽或其他原因导致执行中断,程序则会报出相应的错误。
如果由于 `Tx` 无效或 `GasMeter` 用尽而导致任何状态更改失败,`Tx` 的处理将被终止,并且所有状态更改都将还原。区块提案中无效的 `Tx` 会导致验证者节点拒绝该区块并投票给空块。
### 提交
最后一步是让节点提交区块和状态更改,在重跑了区块中所有的 `Tx` 之后,验证者节点会验证区块的签名以最终确认它。不是验证者节点的全节点不参与共识(即无法投票),而是接受投票信息以了解是否应提交状态更改。
当收到足够的验证者票数2/3+的加权票数)时,完整的节点将提交一个新的区块,以添加到区块链网络中并最终确定应用程序层中的状态转换。此过程会生成一个新的状态根,用作状态转换的默克尔证明。应用程序使用从[Baseapp](https://docs.cosmos.network/master/core/baseapp.html)继承的 ABCI 方法[`Commit`](https://docs.cosmos.network/master/core/baseapp.html#commit)`Commit` 通过将 `deliverState` 写入应用程序的内部状态来同步所有的状态转换。提交状态更改后,`checkState` 从最近提交的状态重新开始,并将 `deliverState` 重置为空以保持一致并反映更改。
请注意,并非所有区块都具有相同数量的 `Tx`,并且共识可能会导致一个空块。在公共区块链网络中,验证者可能是**拜占庭恶意**的,这可能会阻止将 `Tx` 提交到区块链中。可能的恶意行为包括出块节点将某个 `Tx` 排除在区块链之外,或者投票反对某个出块节点。
至此,`Tx`的生命周期结束,节点已验证其有效性,并提交了这些更改。`Tx`本身,以 `[]byte` 的形式被存储在区块上进入了区块链网络。
## 下一节
了解 [accounts](./accounts.md)

View File

@ -1,18 +0,0 @@
# 客户端
本节说明包含区块链 SDK 的客户端的信息。
> _注_:此部分仍在开发中。
## 轻客户端
轻客户端使用户能够与您的应用程序进行交互,且无需下载整个状态历史记录,并且具有良好的安全性。
- [轻客户端概述](./lite/README.md)
- [启动轻客户端服务器](./lite/getting_started.md)
- [轻客户端规范](./lite/specification.md)
## 其他客户端
- [区块链 SDK 的 CLI](./cli.md)
- [服务提供商文档](./service-providers.md)

View File

@ -1,3 +0,0 @@
# CLI
> TODO: Rewrite this section to explain how CLI works for a generic SDK app.

View File

@ -1,60 +0,0 @@
# 轻客户端概览
**点击[这里](https://cosmos.network/rpc/)查看 Cosmos SDK 轻客户端 RPC 文档**
## 简介
轻客户端允许客户端(例如移动电话)从任何全节点接收区块链状态的证明。 轻客户端不必信任任何全节点,因为他们能够验证他们收到的任何证明,因此全节点不能对网络状态撒谎。
轻客户端可以用最低的带宽、计算和存储资源提供与全节点相同的安全性。 同时,它还可以根据用户的配置提供模块化功能。 这些出色的功能允许开发人员构建完全安全、高效且可用的移动应用、网站或任何其他应用程序,而无需部署或维护任何完整的区块链节点。
### 什么是轻节点
Cosmos SDK 轻节点Gaia-lite分为两个独立的组件。 第一个组件对于任何基于 Tendermint 的应用程序都是通用的,它处理区块头相关的安全性和连接性,并验证来自全节点的证明与本地可信验证人集合的对比。 此外,它暴露与任何 Tendermint 核心节点完全相同的 API。 第二个组件专用于 Cosmos Hub`gaiad`),它作为查询端点工作,并公开特定于应用程序的功能,这些功能可以是任意的。 针对应用程序状态的所有查询都必须通过查询端点。 查询端点的优点是它可以验证应用程序返回的证据。
### 高层体系结构
想要为 Cosmos Hub或任何其他 zone构建第三方客户端应用程序的应用程序开发人员应根据其规范 API 构建。 该 API 是多个部分的组合。 所有 zone 都必须暴露 ICS0TendermintAPI。 除此之外,任何 zone 都可以自由选择模块 API 的任意组合,具体取决于状态机使用的模块。 Cosmos Hub 最初将支持[ICS0](https://cosmos.network/rpc/#/ICS0) (TendermintAPI)、 [ICS1](https://cosmos.network/rpc/#/ICS1) (KeyAPI)、 [ICS20](https://cosmos.network/rpc/#/ICS20) (TokenAPI)、 [ICS21](https://cosmos.network/rpc/#/ICS21) (StakingAPI)、 [ICS22](https://cosmos.network/rpc/#/ICS22) (GovernanceAPI) 和 [ICS23](https://cosmos.network/rpc/#/ICS23) (SlashingAPI)。
![high-level](../../../kr/clients/lite/pics/high-level.png)
预计所有应用程序仅依赖于 Gaia-lite 运行。 Gaia-lite 是唯一一款围绕 zone API 提供稳定性保证的软件。
### 对比
ABCI 的全节点与其轻客户端的区别在于以下方面:
| | Full Node | 轻客户端 | Description |
| -------------- | ---------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 执行并验证交易 | Yes | No | 全节点将执行并验证所有交易,而 Gaia-lite 则不会 |
| 验证和存储区块 | Yes | No | 全节点将验证并保存所有块,而 Gaia-lite 则不会 |
| 参与共识 | Yes | No | 只有当全节点是验证人时,它才会参与共识。 Lite 节点永远不会参与共识。 |
| 带宽开销 | 巨大 | 很小 | 全节点将接收所有块。 如果带宽有限,它将落后于主网络。 更重要的是,如果碰巧是验证人,它将减缓共识过程。 轻客户端需要很少的带宽, 只有在提供本地请求时,才会占用带宽。 |
| 计算资源 | 巨大 | 很小 | 全节点将执行所有交易并验证所有块,这需要大量的计算资源 |
| 存储资源 | 巨大 | 很小 | 全节点将保存所有块和 ABCI 状态,而 Gaia-lite 只保存验证人集合和一些检查点。 |
| 电力资源 | 巨大 | 很小 | 全节点必须在具有高性能并能一直运行的机器上部署,因此功耗将是巨大的。 Gaia-lite 可以部署在与用户应用程序相同的机器上,也可以部署在独立但性能较差的机器上。 此外Lite 客户端可以在必要时随时关闭。所以 Gaia-lite 只消耗很少的功率,即使移动设备也能满足功率需求。 |
| 提供的 APIs | 所有 cosmos APIs | 部分模块 APIs | 全节点支持所有 cosmos API。 Gaia-lite 根据用户的配置提供模块化 API。 |
| 安全等级 | 高 | 高 | 全节点将自行验证所有交易和块。 轻型客户端无法执行此操作,但它可以查询来自其他全节点的任何数据并独立验证数据。 因此,全节点和轻型客户端都不需要信任任何第三方节点,它们都可以实现高安全性。 |
根据上表Gaia-lite 可以满足所有用户的功能和安全需求,但只需要很少的带宽、计算、存储和电力资源。
## 安全实现
### 可信验证人集合
Gaia-lite 的基本设计理念遵循两个规则:
1. **不信任任何区块链节点,包括验证人节点和其他全节点**
2. **只信任整个验证人集合**
原始的可信验证人集应该预先放置到其信任库中,通常这个验证人集来自 genesis 文件。 在运行时期间,如果 Gaia-lite 检测到不同的验证人集,它将验证它并将可信的验证人集保存到信任库中。
![validator-set-change](../../../kr/clients/lite/pics/validatorSetChange.png)
### 信任传播
从上面的小节中,我们了解了如何获得可信验证器集以及 LCD 如何跟踪验证人集演化。 验证人集是信任的基础,信任可以传播到其他区块链数据,例如块和交易。 传播架构如下所示:
![change-process](../../../kr/clients/lite/pics/trustPropagate.png)
通常,通过可信验证人集,轻客户端可以验证包含所有预提交数据和块头数据的每个提交块。 此时块哈希、数据哈希和应用哈希是可信的。 基于此和默克尔证明,所有交易数据和 ABCI 状态也可以被验证。

View File

@ -1,20 +0,0 @@
# 入门
要启动 REST 服务器,我们需要指定以下参数:
| 参数 | 类型 | 默认值 | 必填 | 描述 |
| ----------- | --------- | ----------------------- | ----- | ---------------------------- |
| chain-id | string | null | true | 要链接全节点的 chain id |
| node | URL | "tcp://localhost:46657" | true | 要链接全节点的地址和端口号 |
| laddr | URL | "tcp://localhost:1317" | true | 提供 REST 服务的地址和端口号 |
| trust-store | DIRECTORY | "\$HOME/.lcd" | false | 保存检查点和验证人集的目录 |
示例:
```bash
gaiacli rest-server --chain-id=test \
--laddr=tcp://localhost:1317 \
--node tcp://localhost:26657 \
```
有关 Gaia-Lite RPC 的更多信息,请参阅 [swagger documentation](https://cosmos.network/rpc/)

View File

@ -1,183 +0,0 @@
# 规范
该规范描述了如何实现 LCD。 LCD 支持模块化 API。 目前,仅支持 ICS0TendermintAPIICS1密钥 API和 ICS20Key API。 如有必要,后续可以包含更多 API。
## 构建并验证 ABCI 状态的证明
众所周知,基于 cosmos-sdk 的应用程序的存储包含多个子库。 每个子目录由 IAVL 存储实现。 这些子组件由简单的 Merkle 树组成。 创建树时,我们需要从这些子库中提取名字、高度和存储根哈希以构建一组简单的 Merkle 叶节点,然后计算从叶节点到根的哈希。 简单 Merkle 树的根哈希是 AppHash它将包含在块头中。
![Simple Merkle Tree](../../../kr/clients/lite/pics/simpleMerkleTree.png)
正如我们在[LCD 信任传播](https://github.com/irisnet/cosmos-sdk/tree/bianjie/lcd_spec/docs/spec/lcd#trust-propagation)中所讨论的那样,可以通过检查针对可信验证人集的投票权来验证 AppHash。 这里我们只需要建立从 ABCI 状态到 AppHash 的证明。 证据包含两部分:
- IAVL 证明
- 子库到 AppHash 的证明
### IAVL 证明
证明有两种类型:存在证明和缺席证明。 如果查询密钥存在于 IAVL 存储中,则它返回键值及其存在证明。 另一方面,如果密钥不存在,那么它只返回缺席证明,这可以证明密钥肯定不存在。
### IAVL 存在证明
```go
type CommitID struct {
Version int64
Hash []byte
}
type storeCore struct {
CommitID CommitID
}
type MultiStoreCommitID struct {
Name string
Core storeCore
}
type proofInnerNode struct {
Height int8
Size int64
Version int64
Left []byte
Right []byte
}
type KeyExistsProof struct {
MultiStoreCommitInfo []MultiStoreCommitID // 所有子库提交id
StoreName string // 当前子库名字
Height int64 // 当前子库提交高度
RootHash cmn.HexBytes // 此 IAVL 树的根哈希
Version int64 // 此 IAVL 树中 key-value 的版本号
InnerNodes []proofInnerNode // 从根节点到 key-value 叶子节点的路径
}
```
存在证据的数据结构如上所示。 构建和验证存在证明的过程如下所示:
![Exist Proof](../../../kr/clients/lite/pics/existProof.png)
构建证明的步骤:
- 从根节点访问 IAVL 树
- 记录 InnerNodes 中的访问节点
- 找到目标叶节点后,将叶节点版本赋值给证明版本
- 将当前 IAVL 树高赋值给证明高度
- 将当前 IAVL 树根哈希赋值给证明根哈希
- 将当前的子目录名称赋值给证明 StoreName
- 从 multistore 读取指定高度的 commitInfo 并将其赋值给证明 StoreCommitInfo
验证证明的步骤:
- 使用证明版本中的键、值构建叶节点
- 计算叶节点哈希
- 将哈希值分配给第一个 innerNode 的 rightHash然后计算第一个 innerNode 哈希值
- 传播哈希计算过程。 如果先前的 innerNode 是下一个 innerNode 的左子节点,则将先前的 innerNode 散列分配给下一个 innerNode 的左散列。否则,将先前的 innerNode 散列分配给下一个 innerNode 的右散列
- 最后 innerNode 的哈希应该等于此证明的根哈希, 否则证明无效。
### IAVL 缺席证明
众所周知,所有 IAVL 叶节点都按每个叶节点的密钥排序。 因此,我们可以在 IAVL 树的整个密钥集中计算出目标密钥的位置。 如下图所示,我们可以找到左键和右键。 如果我们可以证明左键和右键肯定存在,并且它们是相邻的节点,那么目标密钥肯定不存在。
![Absence Proof1](../../../kr/clients/lite/pics/absence1.png)
如果目标密钥大于最右边的叶节点或小于最左边的叶子节点,则目标密钥肯定不存在。
![Absence Proof2](../../../kr/clients/lite/pics/absence2.png)![Absence Proof3](../../../kr/clients/lite/pics/absence3.png)
```go
type proofLeafNode struct {
KeyBytes cmn.HexBytes
ValueBytes cmn.HexBytes
Version int64
}
type pathWithNode struct {
InnerNodes []proofInnerNode
Node proofLeafNode
}
type KeyAbsentProof struct {
MultiStoreCommitInfo []MultiStoreCommitID
StoreName string
Height int64
RootHash cmn.HexBytes
Left *pathWithNode // Proof the left key exist
Right *pathWithNode //Proof the right key exist
}
```
以上是缺席证明的数据结构。 构建证据的步骤:
- 从根节点访问 IAVL 树
- 获取整个密钥集中密钥的对应索引(标记为 INDEX
- 如果返回的索引等于 0则右索引应为 0且左节点不存在
- 如果返回的索引等于整个密钥集的大小,则左节点索引应为 INDEX-1且右节点不存在
- 否则,右节点索引应为 INDEX左节点索引应为 INDEX-1
- 将当前 IAVL 树高赋值给证明高度
- 将当前 IAVL 树根哈希赋值给证明根哈希
- 将当前的子目录名称赋值给证明 StoreName
- 从 multistore 读取指定高度的 commitInfo 并将其赋值给证明 StoreCommitInfo
验证证明的步骤:
- 如果只存在右节点,请验证其存在的证明,并验证它是否是最左侧的节点
- 如果仅存在左节点,请验证其存在的证据,并验证它是否是最右侧的节点
- 如果右节点和左节点都存在,请验证它们是否相邻
### Substores 到 AppHash 的证明
在验证了 IAVL 证明之后,我们就可以开始验证针对 AppHash 的 substore 证明。 首先,迭代 MultiStoreCommitInfo 并通过证明 StoreName 找到 substore commitID。 验证 commitID 中的哈希是否等于证明根哈希,如果不相等则证明无效。 然后通过 substore name 的哈希对 substore commitInfo 数组进行排序。 最后,使用所有 substore commitInfo 数组构建简单的 Merkle 树,并验证 Merkle 根哈希值是否等于 appHash。
![substore proof](../../../kr/clients/lite/pics/substoreProof.png)
```go
func SimpleHashFromTwoHashes(left []byte, right []byte) []byte {
var hasher = ripemd160.New()
err := encodeByteSlice(hasher, left)
if err != nil {
panic(err)
}
err = encodeByteSlice(hasher, right)
if err != nil {
panic(err)
}
return hasher.Sum(nil)
}
func SimpleHashFromHashes(hashes [][]byte) []byte {
// Recursive impl.
switch len(hashes) {
case 0:
return nil
case 1:
return hashes[0]
default:
left := SimpleHashFromHashes(hashes[:(len(hashes)+1)/2])
right := SimpleHashFromHashes(hashes[(len(hashes)+1)/2:])
return SimpleHashFromTwoHashes(left, right)
}
}
```
## 根据验证人集验证区块头
上面的小节中经常提到 appHash但可信的 appHash 来自哪里? 实际上appHash 存在于区块头中,因此接下来我们需要针对 LCD 可信验证人集验证特定高度的区块头。 验证流程如下所示:
![commit verification](../../../kr/clients/lite/pics/commitValidation.png)
当可信验证人集与区块头不匹配时,我们需要尝试将验证人集更新为此块的高度。 LCD 有一条规则,即每个验证人集的变化不应超过 1/3 投票权。 如果目标验证人集的投票权变化超过 1/3则与可信验证人集进行比较。 我们必须验证,在目标验证人集之前是否存在隐含的验证人集变更。 只有当所有验证人集变更都遵循这条规则时,才能完成验证人集的更新。
例如:
![Update validator set to height](../../../kr/clients/lite/pics/updateValidatorToHeight.png)
- 更新到 10000失败变更太大
- 更新到 5050失败变更太大
- 更新至 2575成功
- 更新至 5050成功
- 更新到 10000失败变更太大
- 更新至 7525成功
- 更新至 10000成功

View File

@ -1,177 +0,0 @@
# 服务提供商Service Providers
我们将“服务提供商”定义为可以为最终用户提供服务的实体,这些实体涉及与基于 Cosmos-SDK 的区块链(包括 Cosmos Hub的某种形式的交互。更具体地说本文档将集中于与 token 的交互。
本节不涉及想要提供[轻客户端](https://docs.tendermint.com/master/tendermint-core/light-client.html)功能的钱包开发者。服务提供商将作为最终用户的区块链的可信接入点。
## 架构的高级描述
有三个主要部分需要考虑:
- 全节点:与区块链交互。
- Rest Server它充当 HTTP 调用的中继者。
- Rest API为 Rest Server 定义可用端点。
## 运行全节点
### 安装和配置
我们将描述为 Cosmos Hub 运行和交互全节点的步骤。对于其他基于 SDK 的区块链,该过程是类似的。
首先,您需要[安装软件](../cosmos-hub/installation.md).
然后,您可以开始[运行全节点](../cosmos-hub/join-testnet.md).
### 命令行界面CLI
接下来,您将用一些 CLI 命令与全节点交互。
#### 创建秘钥对
生成新秘钥(默认使用 secp256k1 椭圆曲线算法):
```bash
gaiacli keys add <your_key_name>
```
系统将要求您为此密钥对输入密码(至少 8 个字符)。该命令返回 4 个信息:
- `NAME`: 秘钥名称。
- `TYPE`:秘钥类型,总是`local`。
- `ADDRESS`:您的地址,用于接收资金。
- `PUBKEY`:您的公钥, 用于验证者.
- `MNEMONIC` 由 24 个单词组成的助记词。 **将这个助记词保存在安全的地方**,它用于在您忘记密码时恢复您的私钥。
您可以输入以下命令查看所有可用密钥:
```bash
gaiacli keys list
```
#### 检查您的余额
收到代币到您的地址后,您可以输入以下命令查看帐户的余额:
```bash
gaiacli account <YOUR_ADDRESS>
```
_注意当您查询没有 token 帐户的余额时,您将得到以下错误:找不到地址为<YOUR_ADDRESS>的帐户。这是预料之中的我们正在努力改进我们的错误提示信息。_
#### 通过 CLI 发送代币
以下是通过 CLI 发送代币的命令:
```bash
gaiacli tx send <from_key_or_address> <to_address> <amount> \
--chain-id=<name_of_testnet_chain>
```
参数:
- `<from_key_or_address>`: 发送账户的名称或地址。
- `<to_address>`: 接收者地址。
- `<amount>`: 接受`<value|coinName>`格式的参数,例如 `10faucetToken`
标识:
- `--chain-id`: 此标志允许您指定链的 ID不同的 testnet 链和主链会有不同的 id。
#### 帮助
如果您需要进行其他操作,最合适的命令是:
```bash
gaiacli
```
它将显示所有可用命令。对于每个命令,您可以使用`--help`标识来获取更多信息。
## 设置 Rest 服务器
Rest 服务器充当前端点和全节点之间的媒介。 Rest 服务器不必与全节点同一台计算机上运行。
要启动 Rest 服务器:
```bash
gaiacli rest-server --node=<full_node_address:full_node_port>
```
Flags:
- `--node`: 全节点的 IP 地址和端口。格式为 `<full_node_address:full_node_port>`。如果全节点在同一台机器上,则地址应为 `tcp// localhost26657`
- `--laddr`: 此标识允许您指定 Rest 服务器的地址和端口默认为“1317”。通常只使用这个标识指定端口此时只需输入 “localhost” 作为地址,格式为`<rest_server_address:port>`。
### 监听入向交易
监听入向交易推荐的方法是通过 LCD 的以下端点定期查询区块链:
<!-- [`/bank/balance/{address}`](https://cosmos.network/rpc/#/ICS20/get_bank_balances__address_) -->
## Rest API
Rest API 记录了可用于与全节点交互的所有可用端点,您可以在[这里](https://cosmos.network/rpc/)查看。
API 针对每种类别的端点归纳为 ICS 标准。例如,[ICS20](https://cosmos.network/rpc/#/ICS20/)描述了 API 与 token 的交互。
为了给开发者提供更大的灵活性,我们提供了生成未签名交易、[签名](https://cosmos.network/rpc/#/ICS20/post_tx_sign)和[广播](https://cosmos.network/rpc/#/ICS20/post_tx_broadcast)等不同的 API 端点。这允许服务提供商使用他们自己的签名机制。
为了生成一个未签名交易(例如 [coin transfer](https://cosmos.network/rpc/#/ICS20/post_bank_accounts__address__transfers)),你需要在 `base_req` 的主体中使用 `generate_only` 字段。
## Cosmos SDK 交易签名
Cosmos SDK 签名是一个相当简单的过程。
每个 Cosmos SDK 交易都有一个规范的 JSON 描述。 `gaiacli`和 REST 接口为交易提供规范的 JSON 描述,“广播”功能将提供紧凑的 Amino类似 protobuf 的格式)编码转换。
签名消息时的注意事项:
格式如下
```json
{
"account_number": XXX,
"chain_id": XXX,
"fee": XXX,
"sequence": XXX,
"memo": XXX,
"msgs": XXX
}
```
签名者必须提供 `"chain_id"``"account number"``"sequence number"`
交易构造接口将生成 `"fee"``"msgs"``"memo"` 等字段.
You can load the mempool of a full node or validator with a sequence of uncommitted transactions with incrementing
sequence numbers and it will mostly do the correct thing.
`"account_number"``"sequence"` 字段可以直接从区块链或本地缓存中查询。 错误的获取了这些数值和 chainId是产生无效签名错误的常见原因。您可以通过加载全节点或验证人中的 mempool 来获取未提交交易的自增序号,这样大大增加成功概率。
您可以使用递增序列号的一系列未提交事务加载完整节点或验证器的 mempool它将主要执行正确的操作。
在签名之前,所有键都要按字典顺序排序,并从 JSON 输出中删除所有空格。
签名编码是 ECDSArands 的 64 字节连结(即`r || s`),其中`s`按字典顺序小于其反转以防止延展性。 这就像以太坊一样,但没有用户公钥恢复的额外字节,因为 Tendermint 假定公钥一定会提供。
已签名交易中的签名和公钥示例:
```json
{
"type": "cosmos-sdk/StdTx",
"value": {
"msg": [...],
"signatures": [
{
"pub_key": {
"type": "tendermint/PubKeySecp256k1",
"value": XXX
},
"signature": XXX
}
],
}
}
```
正确生成签名后,将 JSON 插入生成的交易中,然后调用广播端点进行广播。

View File

@ -1,45 +0,0 @@
# Cosmos SDK Documentation Translation (Chinese)
This document tracks the progress of the Chinese translation of the official Cosmos SDK documentation.
Documentation has been translated for **reference use only** and may contain typos, factual errors and be out-of-date with the latest english documentation.
Please refer to the official english version of the documentation for the latest and accurate information.
## Cosmos SDK 文档翻译
本文档跟踪官方 Cosmos SDK 文档的中文翻译进度。
已翻译的文件**仅供参考**,可能包含拼写错误、翻译不准确,并且可能慢于英文版更新。
有关最新和准确的信息,请参阅文档的官方英文版。
## Progress by directory
### README.md
- Synced until commit [b18bd06a](https://github.com/cosmos/cosmos-sdk/commit/b18bd06a364e6ac15f22423e6b66a9feb3eeae93) (2019-12-10)
### [`concepts`](../concepts/)
- ToDo
### [`spec`](../spec/)
- ToDo
### [`cosmos-hub`](../cosmos-hub/)
- Synced until commit [7558f760](https://github.com/cosmos/cosmos-sdk/commit/7558f7607918b6337a8b58b8f956d6776f503138) (2019-05-13)
### [`intro`](../intro/)
- Synced until commit [be194ca1](https://github.com/cosmos/cosmos-sdk/commit/be194ca1b7d159590a0147da3226b7e09eaa3f61) (2020-07-07)
### [`modules`](../modules/)
- ToDo
### [`clients`](../clients/)
- Synced until Commit [7558f760](https://github.com/cosmos/cosmos-sdk/commit/7558f7607918b6337a8b58b8f956d6776f503138) (2019-05-13)

View File

@ -1,13 +0,0 @@
# 介绍
此目录包含对 cosmos sdk 的相关介绍
1. [概述](./overview.md)
2. [基于特定应用的区块链](./why-app-specific.md)
3. [应用架构](./sdk-app-architecture.md)
4. [Cosmos SDK 设计概述](./sdk-design.md)
了解完成相关介绍后,可以前往 [基础文档](../basics/README.md) 了解更多。

View File

@ -1,49 +0,0 @@
# 对象能力模型Object-Capability Model
## 介绍
在考虑安全性时,最好从特定的威胁模型开始。我们的威胁模型如下:
> 我们假设蓬勃发展的 Cosmos-SDK 模块生态中会包含错误或恶意的模块。
Cosmos SDK 旨在通过以对象能力系统作为基础来解决此威胁。
> 对象能力系统的结构特性有利于代码设计模块化,并确保代码实现的可靠封装。
>
> 这些结构上的特性便于分析一个对象能力程序或操作系统的某些安全属性。其中一些 - 特别是信息流属性 - 可以在对象引用和连接级别进行分析,而不需要依赖于了解或分析(决定对象行为的)代码。
>
> 因此,可以在存在包含未知或(可能)恶意代码的新对象的情况下建立和维护这些安全属性。
>
> 这些结构属性源于管理对已存在对象的访问的两个规则:
>
> 1. 只有在对象 A 持有对象 B 的引用A 才可以向 B 发送一条消息
> 2. 只有对象 A 收到了一条包含对象 C 引用的消息A 才可以获得 C 的引用
>
> 根据这两条规则,一个对象只有通过一条先前存在的引用链获得另一个对象的引用,简而言之,“只有连接才能产生连接”。
关于对象能力object-capabilities可以阅读这边[文章](http://habitatchronicles.com/2017/05/what-are-capabilities/)了解更多。
## 对象能力模式实践
想法就是只暴露完成工作所需要的部分。
比如,下面的代码片段违反了对象能力原则:
```go
type AppAccount struct {...}
var account := &AppAccount{
Address: pub.Address(),
Coins: sdk.Coins{sdk.NewInt64Coin("ATM", 100)},
}
var sumValue := externalModule.ComputeSumValue(account)
```
方法名`ComputeSumValue`暗示了这是一个不修改状态的纯函数,但传入指针值意味着函数可以修改其值。更好的函数定义是使用一个拷贝来替代:
```go
var sumValue := externalModule.ComputeSumValue(*account)
```
在 Cosmos SDK 中,你可以看到[gaia app](https://github.com/cosmos/cosmos-sdk/blob/master/simapp/app.go)中对该原则的实践。
+++ https://github.com/cosmos/gaia/blob/master/app/app.go#L197-L209

View File

@ -1,33 +0,0 @@
# Cosmos SDK 介绍
## 什么是 Cosmos SDK
[Cosmos SDK](https://github.com/cosmos/cosmos-sdk)是开源框架,用于构建类似 Cosmos Hub 等基于 POS 共识算法的多元资产公有区块链,以及基于权威证明共识算法的许可链。使用 Cosmos SDK 构建的区块链通常被称为特定应用区块链专用区块链application-specific blockchains
Cosmos SDK 的目标是让开发者可以快速地构建一条能与其他区块链以原生的方式进行互操作的可定制区块链。在我们的设想中,这套 SDK 就像 Web 应用框架一样,可以让开发者迅速构建出基于[Tendermint](https://github.com/tendermint/tendermint)的安全区块链应用程序。 基于 Cosmos SDK 的区块链由组合式[模块](https://docs.cosmos.network/master/building-modules/intro.html)构建,其中大部分模块都是开源的,且任何开发者均可使用。任何人都能为 Cosmos SDK 创建新的模块集成已经构建的模块就像将他们导入你的区块链应用程序一样简单。还有一点Cosmos SDK 是基于功能capabilities的系统这允许开发者可以更好地考虑模块之间交互的安全性。更深入地了解功能请跳至[本节](https://docs.cosmos.network/master/core/ocap.html)。
## 什么是特定应用区块链
目前在区块链领域中,一种开发模式是通过像以太坊这样的虚拟机区块链展开,即开发者在现有的区块链上通过智能合约的方式去构建去中心化应用。虽然智能合约在单用途应用场景(如 ICO下非常有用但在构建复杂的去中心化平台时无法达到要求。更具体地说智能合约在灵活性、所有权、性能方面会受到限制。
特定应用区块链提供了与虚拟机区块链截然不同的开发模式。特定应用区块链是面向单个具体应用程序的高度定制化区块链:开发者可以完全自由地做出让应用程序可以达到最佳运行状态的设计决策。他们也可以提供更好的主导权、安全性和性能。
了解更多可参考[特定应用区块链](https://docs.cosmos.network/master/intro/why-app-specific.html)。
## 为什么选择 Cosmos SDK
Cosmos SDK 是目前最先进的构建可定制化特定应用区块链的框架。以下是一些可能让你希望通过 Cosmos SDK 构建去中心化应用的原因:
- Cosmos SDK 默认的共识引擎是[Tendermint Core](https://github.com/tendermint/tendermint). Tendermint 是目前最成熟的、唯一的 BFT 共识引擎。它被广泛应用于行业中,被认为是构建 POS 系统的最佳标准共识引擎。
- Cosmos SDK 是开源的,你可以通过组合式[modules](https://docs.cosmos.network/master/x/)轻松地构建出区块链。随着 SDK 生态中各种开源模块的发展,通过 Cosmos SDK 构建复杂的去中心化平台会变得越来越容易。
- Cosmos SDK 受基于功能的安全性所启发,并受益于多年来在区块链状态机领域的经验。这让 Cosmos SDK 成为一个非常安全的构建区块链的环境。
- 最重要的是Cosmos SDK 已经构建出了多个正在运行中的特定应用区块链。例如Cosmos HUBIRIS HUBBinance Chain, Terra 和 Kava。更多基于 Cosmos SDK 构建的区块链参考[这里](https://cosmos.network/ecosystem)。
## 开始使用 Cosmos SDK
了解更多请参考[SDK 应用架构](https://docs.cosmos.network/master/intro/sdk-app-architecture.html)。
了解如何从头建立特定应用区块链,请参考[SDK 教程](https://cosmos.network/docs/tutorial)。

View File

@ -1,91 +0,0 @@
# 区块链架构
## 状态机
区块链的核心是[复制确定状态机](https://en.wikipedia.org/wiki/State_machine_replication)replicated deterministic state machine
状态机是计算机科学领域的一个概念,即一台机器可以具有多个状态,但在任意给定时刻只具有一个确定的状态。我们用 `state` 描述系统当前状态,`transactions` 触发状态转换。
给定一个状态 S 和 Transaction T状态机会返回新的状态 S'。
```
+--------+ +--------+
| | | |
| S +---------------->+ S' |
| | apply(T) | |
+--------+ +--------+
```
在实际中Transaction 集会被打包进区块中,以让处理过程更加高效。给定一个状态 S 和一个包含 Transaction 集 B 的区块,状态机就会返回新的状态 S'。
```
+--------+ +--------+
| | | |
| S +----------------------------> | S' |
| | For each T in B: apply(T) | |
+--------+ +--------+
```
在区块链的上下文环境中,状态机是确定的。这意味着节点从给定状态开始,重放相同的 Transaction 序列,总能得到相同的最终状态。
Cosmos SDK 为开发者提供了最大程度的灵活性去定义应用程序的状态Transaction 类型和状态转换功能。接下来的章节中会更详细地介绍使用 SDK 构建状态机的过程。在此之前,先让我们看看如何使用 Tendermint 复制状态机。
## Tendermint
得益于 Cosmos SDK开发者只需要定义好状态机[Tendermint](https://tendermint.com/docs/introduction/what-is-tendermint.html) 就会处理好状态复制的工作。
```
^ +-------------------------------+ ^
| | | | Built with Cosmos SDK
| | State-machine = Application | |
| | | v
| +-------------------------------+
| | | ^
Blockchain node | | Consensus | |
| | | |
| +-------------------------------+ | Tendermint Core
| | | |
| | Networking | |
| | | |
v +-------------------------------+ v
```
[Tendermint](https://tendermint.com/docs/introduction/what-is-tendermint.html) 是一个与应用程序无关的引擎,负责处理区块链的网络层和共识层。这意味着 Tendermint 负责对 Transaction 字节进行传播和排序。Tendermint Core 通过同名的拜占庭容错算法来达成 Transaction 顺序的共识。
Tendermint[共识算法](https://tendermint.com/docs/introduction/what-is-tendermint.html#consensus-overview)与一组被称为 Validator 的特殊节点共同运作。Validator 负责向区块链中添加包含 transaction 的区块。在任何给定的区块中,都有一组 Validator 集合 V。算法会从集合 V 中选出一个 Validator 作为下一个区块的 Proposer。如果一个区块被集合 V 中超过三分之二的 Validator 签署了 [prevote](https://tendermint.com/docs/spec/consensus/consensus.html#prevote-step-height-h-round-r) 和 [precommit](https://tendermint.com/docs/spec/consensus/consensus.html#precommit-step-height-h-round-r),且区块中所有 Transaction 都是有效的则认为该区块有效。Validator 集合可以按照状态机中写定的规则更改。
## ABCI
Tendermint 通过被称为 [ABCI](https://tendermint.com/docs/spec/abci/) 的接口向应用程序传递 Transactions该接口必须由应用程序实现。
```
+---------------------+
| |
| Application |
| |
+--------+---+--------+
^ |
| | ABCI
| v
+--------+---+--------+
| |
| |
| Tendermint |
| |
| |
+---------------------+
```
需要注意的是Tendermint 仅处理 transaction 字节它并不知道这些字节的含义。Tendermint 所做的只是对 transaction 字节进行确定性地排序。Tendermint 通过 ABCI 向应用程序传递字节,并期望返回状态码以获知包含在 transactions 中的 messages 是否成功处理。
以下是 ABCI 最重要的 Messages
`CheckTx`:当 Tendermint Core 接收到一个 Transaction 时,它会传递给应用程序以检查是否满足一些基本要求。`CheckTx` 用于保护全节点的内存池免受垃圾 transactions 攻击。`AnteHandler` 这一特殊处理程序用于执行一系列验证步骤,例如检查手续费是否足够以及验证签名。如果检查通过,该 transaction 会被添加进[mempool](https://tendermint.com/docs/spec/reactors/mempool/functionality.html#mempool-functionality),并广播给其他共识节点。请注意,此时 transactions 尚未被 `CheckTx` 处理(即未进行状态修改),因为它们还没有被包含在区块中。
`DeliverTx`:当 Tendermint Core 收到一个[有效区块](https://tendermint.com/docs/spec/blockchain/blockchain.html#validation)时,区块中的每一个 Transaction 都会通过 `DeliverTx` 传递给应用程序以进行处理。状态转换会在这个阶段中发生。`AnteHandler` 会与 Transaction 中每个 Message 的实际 [`handlers`](https://docs.cosmos.network/master/building-modules/handler.html) 一起再次执行。
`BeginBlock/EndBlock`:无论区块中是否包含 transactionmessages 都会在每个区块的开头和结尾处执行。触发自动执行的逻辑是很有用的。但需要谨慎使用,因为计算量庞大的循环会严重降低区块链的性能,而无限循环甚至会导致区块链宕机。
获知更多关于 ABCI 的详细内容可以访问 [Tendermint docs](https://tendermint.com/docs/spec/abci/abci.html#overview).
基于 Tendermint 构建的任何程序都需要实现 ABCI 接口,以便和底层的本地 Tendermint 引擎通信。幸运的是,您不需要实现 ABCI 接口Cosmos SDK 以 [baseapp](https://docs.cosmos.network/master/intro/sdk-design.html#baseapp) 的形式提供了样板实现。

View File

@ -1,87 +0,0 @@
# Cosmos SDK 的主要组件
Cosmos SDK 是一个框架,可以促进基于 Tendermint 的安全状态机的开发。SDK 的核心是一个基于 Golang 的[ABCI](https://docs.cosmos.network/master/intro/sdk-app-architecture.html#abci)样板实现。它带有一个用于存储数据的[`multistore`](https://docs.cosmos.network/master/core/store.html#multistore),和一个用于处理 Transaction 的[`router`](https://docs.cosmos.network/master/core/baseapp.html#routing)。
下面的简化视图展示了当通过 `DeliverTx` 从 Tendermint 转移 transactions 时,基于 Cosmos SDK 构建的应用程序如何处理这些 transactions。
1. 解码从 Tendermint 共识引擎中接收到的 `transactions`Tendermint 只能处理 `[]bytes` 类型的数据)
2. 从 `transactions` 中提取 `messages` 并进行基本的健全性检查。
3. 将每个 Message 路由到对应的模块中,以进行相应处理。
4. 提交状态更改。
## BaseApp
`baseapp` 是 Cosmos SDK 应用程序的样本实现,它拥有能够处理和底层共识引擎的连接的 ABCI 实现。通常Cosmos SDK 应用程序通过嵌入[`app.go`](https://docs.cosmos.network/master/basics/app-anatomy.html#core-application-file)来实现拓展。查看示例请参考 SDK 应用教程:
+++ https://github.com/cosmos/sdk-tutorials/blob/c6754a1e313eb1ed973c5c91dcc606f2fd288811/app.go
`baseapp` 的目标是在存储和可拓展状态机之间提供安全的接口,同时尽可能少地定义状态机(对 ABCI 保持不变)。
更多关于`baseapp`的信息,请点击[这里](https://docs.cosmos.network/master/core/baseapp.html)。
## Multistore
Cosmos SDK 为状态持久化提供了 `multistore`。Multistore 允许开发者声明任意数量的 `KVStores`。这些 `KVStores` 只接受 `[]byte` 类型的值,因此任何自定义的结构都需要在存储之前使用[codec](https://docs.cosmos.network/master/core/encoding.html)进行编码。
Multistore 抽象用于区分不同模块的状态,每个都由其自己的模块管理。更多关于 multistore 的信息请点击[这里](https://docs.cosmos.network/master/core/store.html#multistore)。
## Modules
Cosmos SDK 的强大之处在于其模块化开发的理念。SDK 应用程序是通过组合一系列可互操作的模块而构建的。每个模块定义了状态子集,并包含其 Messages 与 Transactions 的处理器,同时 SDK 负责将每个 Message 路由到对应的模块中。
以下的简化视图展示了应用链中的每个全节点如何处理有效区块中的 Transaction。
```md
+
|
| Transaction relayed from the full-node's Tendermint engine
| to the node's application via DeliverTx
|
|
|
+---------------------v--------------------------+
| APPLICATION |
| |
| Using baseapp's methods: Decode the Tx, |
| extract and route the message(s) |
| |
+---------------------+--------------------------+
|
|
|
+---------------------------+
|
|
|
| Message routed to the correct
| module to be processed
|
|
+----------------+ +---------------+ +----------------+ +------v----------+
| | | | | | | |
| AUTH MODULE | | BANK MODULE | | STAKING MODULE | | GOV MODULE |
| | | | | | | |
| | | | | | | Handles message,|
| | | | | | | Updates state |
| | | | | | | |
+----------------+ +---------------+ +----------------+ +------+----------+
|
|
|
|
+--------------------------+
|
| Return result to Tendermint
| (0=Ok, 1=Err)
v
```
每个模块都可以看成是一个小的状态机。开发者需要定义由模块处理的状态子集,同时自定义改变状态的 Message 类型(注意:`messages` 是通过 `baseapp``transactions` 中提取的)。通常,每个模块会在 `multistore` 中声明自己的 `KVStore`,以存储自定义的状态子集。大部分开发者在构建自己的模块时,需要访问其它第三方模块。由于 Cosmos SDK 是一个开放的框架,其中的一些模块可能是恶意的,这意味着需要一套安全原则去考虑模块间的交互。这些原则都基于[object-capabilities](https://docs.cosmos.network/master/core/ocap.html)。事实上,这也意味着,并不是要让每个模块都保留其他模块的访问控制列表,而是每个模块都实现了被称为 `keepers` 的特殊对象,它们可以被传递给其他模块,以授予一组预定义的功能。
SDK 模块被定义在 SDK 的 `x/` 文件夹中,一些核心的模块包括:
- `x/auth`:用于管理账户和签名。
- `x/bank`:用于启动 tokens 和 token 转账。
- `x/staking` + `s/slashing`:用于构建 POS 区块链。
除了 `x/` 文件夹中已经存在的任何人都可以使用的模块SDK 还允许您构建自己自定义的模块,您可以在[教程中查看示例](https://cosmos.network/docs/tutorial/keeper.html)。

View File

@ -1,85 +0,0 @@
# 特定应用区块链
## 概要
本文档解释了什么是特定应用区块链,以及为什么开发者更希望构建特定应用区块链,而不是开发智能合约。
## 什么是特定应用区块链?
特定应用区块链是面向单个具体应用程序的高度定制化区块链。与基于像以太坊这样的底层区块链搭建去中心化应用不同开发者需要从头构建他们自己的区块链。这意味着构建全节点客户端、轻节点客户端和所有必要的接口CLI, REST, 等等)来和节点交互。
```
^ +-------------------------------+ ^
| | | | Built with Cosmos SDK
| | State-machine = Application | |
| | | v
| +-------------------------------+
| | | ^
Blockchain node | | Consensus | |
| | | |
| +-------------------------------+ | Tendermint Core
| | | |
| | Networking | |
| | | |
v +-------------------------------+ v
```
## 智能合约的局限是什么?
早在 2014 年,像 Ethereum 这样的虚拟机区块链就满足了可编程性的需求。当时,开发去中心化应用的选项非常有限。许多开发者只能在复杂且有限制的比特币脚本语言上开发,或者 fork 难以运行和定制化的比特币代码。
虚拟机区块链在当时提出了新的价值主张。他们的状态机集成了虚拟机,从而能够执行被称为智能合约的图灵完备程序。虽然智能合约在一次性事件(如 ICO的应用场景下非常有用但在构建复杂的去中心化平台时无法达到要求。以下是原因
- 智能合约通常由可以被底层虚拟机解释的特定编程语言开发。这些编程语言常常并不成熟,并受限于虚拟机本身。例如,以太坊虚拟机并不允许开发者实现代码的自动执行。开发或者也被限制于 EVM 的账户体系,他们只能从一组有限的功能中进行加密操作。虽然这些只是示例,但它们展现了智能合约环境通常缺少**灵活性**。
- 智能合约都运行在同一台虚拟机上,这意味着它们会相互争夺资源,并严重影响执行效果。即使状态机切分成多个子集(例如通过分片技术),智能合约依然需要由虚拟机解释,比起在状态机上实现的本地应用程序,这依然限制了合约应用的**性能**。(我们的基准测试表明,在删除虚拟机后,应用程序的性能提高了 10 倍。)
- 智能合约共享底层环境带来的另一个问题是**主导权**的最终限制。去中心化应用是一个涉及众多参与者的生态系统如果去中心化应用建立在通用的虚拟机区块链上利益相关者stakeholders对他们的应用程序就只有非常有限的主导权并最终会被底层区块链的治理所取代。如果该应用程序还存在着漏洞那任何人都无能为力。
特定应用区块链的出现,就是要解决上述问题。
## 特定应用区块链的优势
### 灵活性
特定应用区块链赋予了开发者最大的灵活性:
- 在 Cosmos 区块链中,状态机通常通过被称为 [ABCI](https://tendermint.com/docs/spec/abci/) 的接口和底层共识引擎连接。该接口可以被包装为任何编程语言,开发者可以自己决定用哪种编程语言来构建状态机。
- 开发者在构建状态机时有多种选择,目前最常用的是 Cosmos SDK但也有其他的框架如 [Lotion](https://github.com/nomic-io/lotion) 和 [Weave](https://github.com/iov-one/weave) 等。开发者通常都是基于他们使用的编程语言来选择使用哪一种框架Cosmos SDK 和 Weave 基于 GolangLotion 则基于 JavaScript
- ABCI 允许开发者更换特定应用链的共识引擎。目前只有 Tendermint 共识可以投入使用,但在未来还会有更多共识引擎可被使用。
- 即使已经选好了开发框架和共识引擎,但如果他们不能完全符合原始格式的要求,开发者依然可以对其进行调整。
- 开发者可以自由探索出最能满足实际需求的方案(如验证人数量 vs Transaction 吞吐量;安全性 vs 异步可用性等)和链的设计选项(如 DB 存储或 IAVL 树UTXO 或账户模型,等)。
- 开发者可以实现代码的自动执行。在 Cosmos SDK 中,每个块的开头和结尾都可以自动触发逻辑。与虚拟机区块链环境下的合约开发者不同,特定应用区块链的开发者可以自由地选择应用程序所需要的加密库,而不会受到底层环境的功能限制。
上述的列表展示了特定应用区块链给予开发者的充分灵活性。Cosmos 和 Cosmos SDK 的目标是让开发者工具尽可能的通用化、模块化,从而在保持兼容的情况下对堆栈的每个部分进行分叉、调整和优化。随着社区的不断发展,每个核心构建模块都将有更多可替代方案,为开发者提供更多选项。
### 性能
基于智能合约的去中心化应用在性能方面会天然地受到底层环境的限制。如果一个去中心化应用要进行性能优化,就需要将其构建为特定应用区块链。以下是特定应用区块链在性能方面的优势:
- 特定应用区块链开发者可以选择像 Tendermint BFT 这样的新型共识引擎。与目前被大多数虚拟机区块链使用的 POW 共识相比Tendermint BFT 在吞吐量方面有显著提高。
- 一个特定应用区块链只运行单个应用程序,所以该应用程序不需要和其他程序去竞争计算资源和存储资源。这与目前所有非分片虚拟机区块链正好相反,在这些区块链中的智能合约都会争夺计算和存储资源。
- 即使某种虚拟机区块链能够提供基于应用程序的分片和高效的共识算法,其性能也依然会被虚拟机本身所限制。真正的吞吐量瓶颈在于状态机,要求 Transaction 由虚拟机解释会大大增加处理它们的计算复杂度。
### 安全性
安全性很难进行量化,而且不同区块链平台之间存在很大差异。以下是特定应用区块链所能带来的重要优势:
- 与不成熟的智能合约编程语言相反,开发者可以在构建特定应用区块链时选择像 Golang 这种可靠性已被验证的编程语言。
- 开发者不会局限于底层虚拟机所提供的加密功能,他们可以使用自定义的加密技术,也可以依赖经过可靠审核的加密库。
- 开发者无需担心底层虚拟机中潜在的漏洞或可被利用的机制,从而可以更容易地确保应用程序的安全性。
### 主导权
特定应用区块链的一大好处是主导权。去中心化应用是一个涉及众多参与者的生态系统,如用户、开发者、第三方服务,等等。当开发者在多个去中心化应用共存的虚拟机区块链上开发应用程序时,出现的一个问题是围绕应用程序所组成的社区人群和底层链的社区人群并不是一样的,但后者却会在治理的过程中取代前者。如果应用程序中存在一个漏洞,或者需要上线新的功能,应用的 stakeholders 几乎没有任何办法升级代码。如果底层区块链社区拒绝执行,那应用程序就无法升级。
根本问题是应用程序的治理和网络治理并不是统一的,而这个问题可以通过特定应用区块链解决。因为特定应用区块链只专门运行单个应用程序,所以应用的 stakeholders 对整条链有完全的主导权。这能确保社区在漏洞被发现时不会卡住,而且有充分的自由去选择链和应用程序的演化方向。

3
docs/ko/README.md Executable file
View File

@ -0,0 +1,3 @@
# Cosmos SDK Documentation (Korean)
A Korean translation of the Cosmos SDK documentation is not available for this version. If you would like to help with translating, please see [Internationalization](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOCS_README.md#internationalization). A `v0.39` version of the documentation can be found [here](https://docs.cosmos.network/v0.39/kr/).

View File

@ -1,49 +0,0 @@
---
parent:
order: false
---
# 코스모스 SDK 문서에 오신 걸 환영합니다!
::: warning
**DEPRECATED**
This documentation is not complete and it's outdated. Please use the English version.
:::
::: warning
번역된 문서는 **참고용**으로 번역되었습니다. 다수의 오타, 오류가 존재할 수 있으며, 영문 업데이트보다 번역이 느리게 진행될 수 있다는 점을 인지하시기 바랍니다.
코스모스 관련 가장 정확한 정보를 확인하시기 위해서는 영어 원문을 참고하시기 바랍니다.
:::
## 코스모스 SDK 배우기
### SDK 소개
만약 코스모스 SDK가 처음이지만 배우고 싶으시다면 여기에서 시작하시는 것을 추천드립니다.
### SDK 튜토리얼
직접 해보면서 학습하는 방식을 선호하신다면 SDK 애플리케이션 튜토리얼을 따라하실 수 있습니다. 튜토리얼은 **[SDK 기반 블록체인을](https://github.com/cosmos/sdk-application-tutorial)** 만드는 방법을 처음부터 끝까지 가르쳐 드립니다. 이 과정에서 코스모스 SDK의 기본적인 개념 또한 함께 배우실 수 있습니다.
## 코스모스 SDK 사용하기
다음 항목은 실제로 작동하는 SDK 기반 블록체인에 필요한 모든 정보를 포함하고 있습니다.
>*NOTE*: 코스모스 SDK 지원 문서의 완성도와 정확성을 높이기 위해 해당 문서는 꾸준히 업데이트 되고 있습니다. 혹시 오류나 제안사항이 있으시다면 [코스모스 포럼](https://forum.cosmos.network) 또는 [깃허브 이슈를](https://github.com/cosmos/cosmos-sdk/issues/new) 통해서 알려주시면 감사하겠습니다.
- [인트로](./intro/README.md): 코스모스 SDK에 대한 high-level 소개 자료
- [Gaia](https://github.com/cosmos/gaia/blob/master/docs/translations/kr/README.md): Gaia 애플리케이션(현재 코스모스 허브 명칭)에 대한 모든 문서들이 있습니다. Gaia 테스트넷에 참여하는 방법에 대한 정보
- [클라이언트](./clients/README.md): SDK Command-Line Interface 와 SDK 라이트 클라이언트 같은 SDK 클라이언트에 관련한 문서
- [스펙](./spec/README.md): SDK와 모듈들에 대한 스펙 정의
## 코스모스 허브 테스트넷
`gaia` 애플리케이션(코스모스 허브의 애플리케이션)을 설치하고 퍼블릭 테스트넷에 참가하고 싶으시다면 여기를 클릭해주세요.
자체적인 `gaia` 테스트넷을 운영하고 싶으시다면 **[여기](https://github.com/cosmos/gaia/blob/master/docs/translations/kr/join-testnet.md)** 를 클릭해주세요.
자체적인 `gaia` 테스트넷 운영을 원하시는 경우 **[여기](https://github.com/cosmos/gaia/blob/master/docs/translations/kr/deploy-testnet.md)** 를 확인하세요
## 기여하기
코스모스 도큐멘테이션 또는 코드 업데이트 규칙에 관련해서는 [이 파일](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOCS_README.md)을 참고해주세요.

View File

@ -1,18 +0,0 @@
# 클라이언트
이 항목은 SDK 기반 블록체인을 위한 클라이언트에 대한 정보가 포함되어있습니다.
>*참고*: 이 항목은 작업이 진행중입니다.
## 라이트 클라이언트(Light-client)
라이트 클라이언트는 유저가 특정 블록체인 상태 전체를 다운로드 받지 않고도 안전성이 확보될 수 있는 환경에서 블록체인 애플리케이션과 소통할 수 있게 합니다.
- [라이트 클라이언트 개요](./lite/README.md)
- [라이트 클라이언트 서버 구동하기](./lite/getting_started.md)
- [라이트 클라이언트 스펙](./lite/specification.md)
## 다른 클라이언트
- [SDK 기반 블록체인을 위한 커맨드 라인 기반 인터페이스](./cli.md)
- [서비스 제공자 문서](./service-providers.md)

View File

@ -1,3 +0,0 @@
# CLI
> TODO: Rewrite this section to explain how CLI works for a generic SDK app.

View File

@ -1,63 +0,0 @@
# 라이트 클라이언트 개요
**코스모스 SDK 라이트 클라이언트 RPC 문서를 [여기]에서 확인하세요(https://cosmos.network/rpc/)**
## 소개
라이트 클라이언트는 핸드폰 같은 클라이언트에서 블록체인 상태(state)에 대한 증거(proof)를 풀노드로부터 전달받을 수 있게 합니다. 라이트 클라이언트는 전송받은 증거에 대한 검증을 자체적으로 수행할 수 있기 때문에 풀노드를 신뢰하지 않아도 되며, 풀노드의 거짓 정보 전달을 확인할 수 있다.
라이트 클라이언트는 대역폭(bandwidth), 컴퓨터 연산력 그리고 저장공간 측면에서 큰 리소스를 소모하지 않고도 풀노드와 동일한 보안을 제공할 수 있다. 또한 유저의 설정에 따라 모듈화 된 기능성을 제공할 수 있다. 이런 우수한 기능은 개발자들이 풀 블록체인 노드가 없이도 안전하고, 효율적이고, 사용성이 높은 모바일 애플리케이션, 웹사이트 등을 만들 수 있게 한다.
### 라이트 클라이언트란 무엇인가
코스모스 SDK 라이트 클라이언트 (Gaia-lite)는 두 가지 요소로 나뉘어 있다. 첫 번째 요소는 모든 텐더민트 기반 애플리케이션들의 기본적인 컴포넌트다. 해당 컴포넌트는 헤더 체인을 따르면서 풀노드가 제공하는 증거를 신뢰할 수 있는 검증인을 통해 확인하는 방식으로 보안과 연결성 측면을 담당한다. 두 번째 요소는 코스모스 허브(`gaiad`)에 고유한 컴포넌트다. 일종의 쿼리 엔드포인트(query endpoint)로써 애플리케이션 특정 기능을 드러내는 역할을 수행한다. 애플리케이션 상태에 대한 모든 쿼리는 쿼리 엔드포인트(query endpoint)를 통해 이루어진다. 쿼리 엔드포인트를 이용하는 것에 가장 큰 장점은 애플리케이션이 리턴하는 증거를 검증할 수 있다는 것이다.
### 하이레벨 아키텍처(High-level Architecture)
코스모스 허브(또는 다른 존)를 위한 제삼자 클라이언트 애플리케이션을 만드려고 하는 개발자는 기본 규례적(canonical) API를 기반으로 개발을 해야 합니다. API는 여러 가지 부품으로 이루어져 있습니다. 코스모스 생태계의 모든 존은 기본적으로 ICS0(텐더민트API)를 공개해야 하나, 그 외에 모듈들은 선택 사항입니다. 모든 존은 모듈 API를 도입할 여부를 기능에 따라 선택할 권리가 있습니다.
기본적으로 코스모스 허브는 [ICS0](https://cosmos.network/rpc/#/ICS0) (텐더민트API), [ICS1](https://cosmos.network/rpc/#/ICS1) (키API), [ICS20](https://cosmos.network/rpc/#/ICS20) (토큰API), [ICS21](https://cosmos.network/rpc/#/ICS21) (스테이킹API),
[ICS22](https://cosmos.network/rpc/#/ICS22) (거버넌스API) and [ICS23](https://cosmos.network/rpc/#/ICS23) (슬래싱API)를 도입하고 있습니다.
![high-level](./pics/high-level.png)
모든 애플리케이션은 Gaia-lite 클라이언트를 기반으로 운영되는 것을 원칙으로 삼습니다. Gaia-lite 외의 소프트웨어는 특정 존 API에 대한 안정성을 보장하지 않습니다.
### 비교
ABCI 풀노드는 다음과 같은 항목에서 라이트 클라이언트와 다릅니다:
|| 풀노드 | 라이트 클라이언트 | 설명|
|-| ------------- | ----- | -------------- |
| 트랜잭션 검증 및 실행|Yes|No|풀노드는 모든 트랜잭션을 검증하고 실행하지만, 라이트 클라이언트는 모든 트랜잭션을 처리하지 않습니다|
| 검증 및 블록 저장|Yes|No|풀노드는 모든 블록을 검증하고 보관하지만, 라이트 클라이언트는 블록 저장을 하지 않습니다|
| 합의 절차 참여| Yes|No|검증인 세트에 포함된 풀노드는 합의 절차에 참여하지만, 라이트 클라이언트는 절대로 합의 절차에 참여할 수 없습니다|
| 대역폭 사용량|대량|소량|풀노드는 모든 블록을 전달받기 때문에 충분한 대역폭이 확보되지 않는 경우 다른 뒤질 확률이 있습니다. 검증인 풀노드가 낮은 대역폭으로 지연되는 경우 합의 절차 전체가 늦어질 수 있습니다. 라이트 클라이언트는 로컬 호출만을 처리하기 때문에 소량의 대역폭을 사용합니다|
| 연산력 사용량|대량|소량|풀노드는 모든 트랜잭션을 처리하며 모든 블록을 검증해야 하기 때문에 대량의 컴퓨터 연산력을 사용합니다.|
| 저장 공간 사용량|대량|소량|풀노드는 모든 블록과 ABCI 상태를 저장합니다. 라이트 클라이언트는 검증인 세트와 일부 체크포인트만을 저장합니다.|
| 전력 사용량|대량|소량|풀노드는 24시간 돌아가는 고성능 머신 환경이 제공되어야 하기 때문에 대량의 전력을 소모합니다. 라이트 클라이언트의 경우 유저 애플리케이션과 동일한 환경에서 운용될 수 있습니다. 라이트 클라이언트는 모바일 기기 같은 저성능 기기에서도 사용될 수 있습니다. 또한 라이트 클라이언트는 필요에 따라 클라이언트 작동을 출 수 있기 때문에 모바일 기기 같은 저전력 소모를 필요로 하는 환경에서 이용될 수 있습니다.|
| API 제공|모든 코스모스 API|모듈 API|풀노드는 모든 코스모스 API를 지원합니다. 라이트 클라이언트는 유저 설정에 따라 모듈 API를 제공합니다.|
| 보안|높음|높음|풀노드는 자체적으로 모든 트랜잭션과 블록을 검증합니다. 라이트 클라이언트는 모든 트랜잭션을 검증하지 않지만 다른 풀노드를 통해 데이터를 전달받아 자체적인 검증을 할 수 있습니다. 풀노드와 라이트 클라이언트는 둘 다 제삼자 노드를 신뢰할 필요 없이 데이터 검증이 가능하기 때문에 높은 수준의 보안을 제공합니다|
위 표와 같이 가이아 라이트 클라이언트는 소량의 대역폭, 연산력, 저장 공간, 전력을 가지고도 유저가 필요로 하는 모든 기능과 보안을 제공합니다.
## 보안 유지하기
### 신뢰 가능한 검증인 세트
가이아 라이트 클라이언트의 디자인 철학은 다음과 같은 원칙을 따릅니다:
1. **검증인 노드와 다른 풀 노드를 포함한 모든 블록체인 노드를 신뢰하지 않는다**
2. **오직 전체적인 검증인 세트(validator set) 만을 신뢰한다**
초기에 신뢰될 수 있는 검증인 세트(통상 제네시스 파일에 있는 검증인 세트)는 신뢰 저장소(trust store)에 미리 세팅되어야 합니다. 이후, 런타임에서 라이트 클라이언트가 다른 검증인 세트를 발견하게 된다면 클라이언트는 해당 검증인 세트를 별도로 검증한 후 새로운 검증인 세트를 저장소에 보관하게 됩니다.
![validator-set-change](./pics/validatorSetChange.png)
### 신뢰 전파(trust propagation)
위에 항목에 나열된 바와 같이, 라이트 클라이언트(lcd)는 신뢰할 수 있는 검증인 세트를 별도로 검증합니다. 검증인 세트는 일종의 신뢰의 기반이 되며, 이런 신뢰를 기반으로 블록 정보와 트랜잭션 정보 같은 다른 블록체인 데이터에 신뢰를 전파(propogate)하는데 이용됩니다. 신뢰 전파 아키텍처는 다음과 같습니다.
![change-process](./pics/trustPropagate.png)
라이트 클라이언트는 통상 신뢰 가능한 검증인 세트를 통해 모든 프리 커밋 정보와 블록 헤더 정보가 포함된 각 블록의 커밋을 검증할 수 있습니다. 이후 블록 해시 값, 데이터 해시 값 그리고 앱해시(appHash)에 대한 신뢰를 파생합니다. 머클 증거(merkle proof)와 위의 정보를 이용해 모든 트랜잭션 데이터와 ABCI의 상태(state)를 검증할 수 있게 됩니다.

View File

@ -1,20 +0,0 @@
# REST 서버 시작하기
REST 서버를 가동하기 위해서는 다음과 같은 파라미터 값을 정의해야 합니다:
| 파라미터 | 형태 | 기본 값 | 필수/선택 | 설명 |
| ----------- | --------- | ----------------------- | -------- | ---------------------------------------------------- |
| chain-id | string | null | 필수 | 연결할 체인의 chain-id |
| node | URL | "tcp://localhost:46657" | 필수 | 연결할 풀노드의 주소 |
| laddr | URL | "tcp://localhost:1317" | 필수 | REST 서버를 가동할 주소 |
| trust-store | DIRECTORY | "$HOME/.lcd" | 선택 | 체크포인트와 검증인 세트를 저장할 디렉터리 |
예를 들어::
```bash
gaiacli rest-server --chain-id=test \
--laddr=tcp://localhost:1317 \
--node tcp://localhost:26657
```
Gaia-Lite RPC에 대한 추가적인 정보를 원하시면 [Swagger 문서](https://cosmos.network/rpc/)를 확인하세요.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 17 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 20 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 31 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 95 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 31 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 28 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 30 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 8.7 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 63 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 20 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 94 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 11 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 34 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 61 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 18 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 49 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 18 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 35 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 20 KiB

View File

@ -1,183 +0,0 @@
# 라이트 클라이언트 스펙
이 문서는 LCD(Light Client Daemon)을 사용하는 방법을 설명합니다. LCD는 모듈러 API를 지원합니다. 현재 LCD는 ICS0 (텐더민트API), ICS1 (키API)와 ICS20 (토큰API) 만을 지원하는 상태입니다. 추후에 추가 모듈을 지원할 예정입니다.
## ABCI 상태 빌드/검증하기
코스모스 SDK 기반 애플리케이션은 멀티-서브스토어(multi-substore)를 이용해 저장을 합니다. 각 서브스토어는 IAVL 스토어를 응용합니다. 서브스토어는 단순한 머클 트리(Merkle tree) 형태로 정렬됩니다. 머클 트리를 만들기 위해서는 각 서브스토어의 이름, 블록 높이 그리고 스토어 루트 해시(store root hash) 필요하며, 이를 기반으로 간단한 머클 가지 노드(Merkle leaf node)를 만들 수 있습니다. 이후 가지 노드를 이용해 해시값을 머클 뿌리(Merkle root)까지 연산하게 됩니다. 단순 머클 트리(simple Merkle tree)의 루트 해시(Root hash)는 블록 헤더에 포함되는 앱 해시(AppHash)입니다.
![Simple Merkle Tree](./pics/simpleMerkleTree.png)
[LCD 신뢰 전파](https://github.com/irisnet/cosmos-sdk/tree/bianjie/lcd_spec/docs/spec/lcd#trust-propagation)에서 설명했던바와 같이, 앱해시는 신뢰할 수 있는 검증인 세트의 보팅파워(총 스테이킹 수량)를 검증하는 방식으로 확인할 수 있습니다. 이 절차에는 ABCI 상태에서부터 앱해시 증거를 찾으면 됩니다. 증거에는 다음과 같은 정보가 포함되어있습니다:
* IAVL 증거
* 섭스토어에서 앱해시까지의 증거
### IAVL 증거 (IAVL proof)
증거물에는 두 가지의 종류가 있습니다: 존재 증거(existance proof)와 부재 증거(absence proof). 만약 쿼리 키가 IAVL 스토어에 존재하는 경우 키 밸류(key-value)와 존재 증거를 제공하게 됩니다. 반면, 만약 키가 존재하지 않는다면 해당 키가 존재하지 않는 것을 증명할 수 있는 부재 증거를 제공합니다.
### IAVL 존재 증거 (IAVL Existance Proof)
```go
type CommitID struct {
Version int64
Hash []byte
}
type storeCore struct {
CommitID CommitID
}
type MultiStoreCommitID struct {
Name string
Core storeCore
}
type proofInnerNode struct {
Height int8
Size int64
Version int64
Left []byte
Right []byte
}
type KeyExistsProof struct {
MultiStoreCommitInfo []MultiStoreCommitID //All substore commitIDs
StoreName string //Current substore name
Height int64 //The commit height of current substore
RootHash cmn.HexBytes //The root hash of this IAVL tree
Version int64 //The version of the key-value in this IAVL tree
InnerNodes []proofInnerNode //The path from to root node to key-value leaf node
}
```
존재 증거의 데이터 형식은 위와 같이 나열되어 있습니다. 존재 증거를 생성하고 검증하는 방식은 다음과 같습니다:
![Exist Proof](./pics/existProof.png)
증거 생성 절차:
* 루트 노드에서 IAVL 트리를 액세스
* 방문 노드(visited node)를 InnerNodes에 기록
* 타겟 가지 노드(leaf node)를 찾은 경우, 가지 노드 버전을 증거 버전에 할당
* 현재 IAVL 트리 높이(IAVL tree height)를 증거 높이(proof height)에 할당
* 현재 IAVL 트리의 루트해시(rootHash)를 증거 루트해시에 할당
* 현재 서브스토어 이름을 증거 스토어 이름(proof StoreName)에 할당
* db에서 멀티스토어 커밋 정보(multistore commitInfo)를 읽은 후 증거 StoreCommitInfo에 할당
검증 절차:
* 키, 값 그리고 증거 버전(proof version)을 이용해 리프 노드(leaf node)를 생성
* 리프 노드 해시값을 연산
* 해시 값을 innerNoder의 rightHash에 할당한 후, 첫 innnerNode의 해시를 연산
* 해시 연산 절차를 전파. 만약 위의 innerNode가 다음 innerNode의 left child(좌측 자녀)인 경우, 해당 innerNode를 다음 innerNode의 좌측 해시로 배정한다. 이 외의 경우, 위의 innerNode 해시를 다음 innerNode의 우측 해시로 배정한다.
* 마지막 innerNode의 해시값은 해당 증거의 rootHash와 동일해야 한다. 그렇지 않은 경우, 증거는 무효하다.
### IAVL 부재 증거(IAVL Absence Proof)
모든 IAVL 리프 노드는 각 리프노드의 키로 정렬되어있습니다. 그렇기 때문에 IAVL 트리의 전체 키 내의 목표 키 위치를 찾을 수 있습니다. 아래와 같이, 키가 좌측 키 또는 우측 키인지 확인이 가능합니다. 만약 우측 키와 좌측 키의 존재를 증명할 수 있을 경우, 인접 노드(adjecent node) 여부를 증명할 수 있는 것이며 타겟 키가 존재하지 않는다는 것을 증명하게 됩니다.
![Absence Proof1](./pics/absence1.png)
만약 타겟 키가 최우측 리프 노드(right most leaf node) 보다 크거나 또는 최좌측 키(left most key) 보다 작은 경우 타겟 키는 존재하지 않음을 증명합니다.
![Absence Proof2](./pics/absence2.png)![Absence Proof3](./pics/absence3.png)
```go
type proofLeafNode struct {
KeyBytes cmn.HexBytes
ValueBytes cmn.HexBytes
Version int64
}
type pathWithNode struct {
InnerNodes []proofInnerNode
Node proofLeafNode
}
type KeyAbsentProof struct {
MultiStoreCommitInfo []MultiStoreCommitID
StoreName string
Height int64
RootHash cmn.HexBytes
Left *pathWithNode // Proof the left key exist
Right *pathWithNode //Proof the right key exist
}
```
위는 부재 증거의 데이터 구조입니다. 증거를 생성하는 절차는 다음과 같습니다:
* 루트 노드에서 IAVL 트리를 액세스
* 전체 키 세트의 deserved index(INDEX로 표기됨)을 받는다
* 만약 받은 인덱스의 값이 0일 경우, 우측 인덱스의 값은 0이며 좌측 노드는 존재하지 않는다
* 만약 받은 인덱스의 값이 전체 키 세트의 크기와 동일한 경우, 좌측 노드 인덱스는 INDEX-1 이어야 하며 우측 노드는 존재하지 않는다
* 이외의 경우, 우측 노드 인덱스는 INDEX여야 하며 좌측 노드 인덱스는 INDEX-1이다
* 현재 IAVL 트리의 높이를 증거 높이에 할당한다
* 현재 IAVL 트리의 rootHash를 증거 rootHash로 할당한다
* 현재 substore 이름을 증거의 StoreName으로 할당한다
* db에서 multistore commitInfo를 읽은 후 증거의 StoreCommitInfo에 할당한다
증거 검증 절차:
* 만약 우측 노드만 존재하는 경우, 존재 증거(exist proof)를 검증하여 최좌특 노드인지 확인한다
* 만약 우측 노드만 존재하는 경우, 존재 증거(exist proof)를 검증하여 최우측 노드인지 확인한다
* 만약 좌측 노드와 우측 노드가 동시에 존재하는 경우, 두 노드가 인접(adjacent)한지 확인한다
### Substores 증거와 AppHash 증거 확인하기
IAVL 증거를 검증했다면 substore 증거와 AppHash를 비교하여 검증할 수 있습니다. 우선 MultiStoreCommitInfo를 반복(iterate)하여 proof StoreName을 이용해 서브스토어의 commitID를 찾을 수 있습니다. 여기에서 commitID의 해시가 RootHash의 proof와 동일하다는 것을 검증합니다. 만약 동일하지 않을 경우, 증거는 유효하지 않습니다. 이후 서브스토어 commitInfo 어레이를 서브스토어 이름의 해시 값으로 정렬합니다. 마지막으로, 모든 서브스토어 commitInfo 어레이를 기반으로 단순 머클 트리(simple Merkle tree)를 빌드하여 머클 루트 해시가 앱 해시와 동일한지 검증합니다.
![substore proof](./pics/substoreProof.png)
```go
func SimpleHashFromTwoHashes(left []byte, right []byte) []byte {
var hasher = ripemd160.New()
err := encodeByteSlice(hasher, left)
if err != nil {
panic(err)
}
err = encodeByteSlice(hasher, right)
if err != nil {
panic(err)
}
return hasher.Sum(nil)
}
func SimpleHashFromHashes(hashes [][]byte) []byte {
// Recursive impl.
switch len(hashes) {
case 0:
return nil
case 1:
return hashes[0]
default:
left := SimpleHashFromHashes(hashes[:(len(hashes)+1)/2])
right := SimpleHashFromHashes(hashes[(len(hashes)+1)/2:])
return SimpleHashFromTwoHashes(left, right)
}
}
```
## 검증인 세트를 이용한 블록헤더 검증하기
위 항목에서는 appHash를 자주 언급합니다. 그렇다면 appHash는 어디에서 존재하는 것일까요? appHash는 블록 헤더에 존재합니다. 그렇기 때문에 특정 블록 높이의 블록헤더를 LCD가 신뢰하는 검증인 세트에 검증해야 합니다. 검증 절차는 다음과 같습니다:
![commit verification](./pics/commitValidation.png)
만약 신뢰 검증인 세트가 블록 헤더와 일치하지 않는 경우, 해당 블록 높이의 검증인 세트로 업데이트를 해야합니다. LCD는 검증인 세트의 변경이 보팅 파워의 1/3을 초과할 수 없다는 규칙을 따릅니다. 만약 타겟 검증인 세트가 현재 신뢰되는 검증인 세트에서 1/3 보팅파워를 초과하는 변화가 있는 경우, 타겟 검증인 세트 전에 숨겨진 검증인 세트 변경이 있었는지 확인해야 합니다. 모든 검증인 세트 변경이 이 규칙을 따를때 검증인 세트 업데이트가 이루어질 수 있습니다.
예를 들어:
![Update validator set to height](./pics/updateValidatorToHeight.png)
* Update to 10000, tooMuchChangeErr
* Update to 5050, tooMuchChangeErr
* Update to 2575, Success
* Update to 5050, Success
* Update to 10000,tooMuchChangeErr
* Update to 7525, Success
* Update to 10000, Success

View File

@ -1,114 +0,0 @@
# 서비스 제공자(Service Providers)
'서비스 제공자'는 코스모스 SDK 기반 블록체인(코스모스 허브도 포함됩니다)과 교류하는 서비스를 엔드유저에게 제공하는 특정 인원/기관을 뜻합니다. 이 문서는 주로 토큰 인터랙션에 대한 정보를 다룹니다.
다음 항목은 [Light-Client](https://docs.tendermint.com/master/tendermint-core/light-client.html) 기능을 제공하려는 월렛 개발자들에게 해당하지 않습니다. 서비스 제공자는 엔드 유저와 블록체인을 이어주는 신뢰할 수 있는 기관/개인입니다.
## 보편적 아키텍처 설명
다음 세가지 항목을 고려해야 합니다:
- 풀 노드(Full-nodes): 블록체인과의 인터랙션.
- REST 서버(Rest Server): HTTP 콜을 전달하는 역할.
- REST API: REST 서버의 활용 가능한 엔드포인트를 정의.
## 풀노드 운영하기
### 설치 및 설정
다음은 코스모스 허브의 풀노드를 설정하고 운용하는 방법입니다. 다른 코스모스 SDK 기반 블록체인 또한 비슷한 절차를 가집니다.
우선 [소프트웨어를 설치하세요](../getting-started/installation.md).
이후, [풀노드를 운영하세요](../getting-started/join-testnet.md).
### 커맨드 라인 인터페이스
다음은 풀노드를 이용할 수 있는 유용한 CLI 커맨드입니다.
#### 키페어 생성하기
새로운 키를 생성하기 위해서는 (기본적으로 secp256k1 엘립틱 커브 기반):
```bash
gaiacli keys add <your_key_name>
```
이후 해당 키페어에 대한 비밀번호(최소 8글지)를 생성할 것을 요청받습니다. 커맨드는 다음 4개 정보를 리턴합니다:
- `NAME`: 키 이름
- `ADDRESS`: 주소 (토큰 전송을 받을때 이용)
- `PUBKEY`: 퍼블릭 키 (검증인들이 사용합니다)
- `Seed phrase`: 12 단어 백업 시드키 **이 시드는 안전한 곳에 별도로 보관하셔야 합니다**. 이 시드키는 비밀번호를 잊었을 경우, 계정을 복구할때 사용됩니다.
다음 명령어를 통해서 사용 가능한 모든 키를 확인할 수 있습니다:
```bash
gaiacli keys list
```
#### 잔고 조회하기
해당 주소로 토큰을 받으셨다면 다음 명령어로 계정 잔고를 확인하실 수 있습니다:
```bash
gaiacli account <YOUR_ADDRESS>
```
*참고: 토큰이 0인 계정을 조회하실 경우 다음과 같은 에러 메시지가 표시됩니다: 'No account with address <YOUR_ADDRESS> was found in the state'. 해당 에러 메시지는 정상이며 앞으로 에러 메시지 개선이 들어갈 예정입니다.*
#### CLI로 코인 전송하기
다음은 CLI를 이용해 코인을 전송하는 명령어입니다:
```bash
gaiacli send --amount=10faucetToken --chain-id=<name_of_testnet_chain> --from=<key_name> --to=<destination_address>
```
플래그:
- `--amount`: `<value|coinName>` 포맷의 코인 이름/코인 수량입니다.
- `--chain-id`: 이 플래그는 특정 체인의 ID를 설정할 수 있게 합니다. 앞으로 테스트넷 체인과 메인넷 체인은 각자 다른 아이디를 보유하게 됩니다.
- `--from`: 전송하는 계정의 키 이름.
- `--to`: 받는 계정의 주소.
#### Help
이 외의 기능을 이용하시려면 다음 명령어를 사용하세요:
```bash
gaiacli
```
사용 가능한 모든 명령어를 표기하며, 각 명령어 별로 `--help` 플래그를 사용하여 더 자세한 정보를 확인하실 수 있습니다.
## REST 서버 설정하기
REST 서버는 풀노드와 프론트엔드 사이의 중계역할을 합니다. REST 서버는 풀노드와 다른 머신에서도 운영이 가능합니다.
REST 서버를 시작하시려면:
```bash
gaiacli advanced rest-server --node=<full_node_address:full_node_port>
```
플래그:
- `--node`: 플노드의 주소와 포트를 입력하시면 됩니다. 만약 풀노드와 REST 서버가 동일한 머신에서 운영될 경우 주소 값은 `tcp://localhost:26657`로 설정하시면 됩니다.
- `--laddr`: REST 서버의 주소와 포트를 정하는 플래그입니다(기본 값 `1317`). 대다수의 경우에는 포트를 정하기 위해서 사용됩니다, 이 경우 주소는 "localhost"로 입력하시면 됩니다. 포맷은 <rest_server_address:port>입니다.
### 트랜잭션 수신 모니터링
추천하는 수신 트랜잭션을 모니터링하는 방식은 LCD의 다음 엔드포인트를 정기적으로 쿼리하는 것입니다:
[`/bank/balance/{account}`](https://cosmos.network/rpc/#/ICS20/get_bank_balances__address_)
## Rest API
REST API는 풀노드와 인터랙션이 가능한 모든 엔드포인트를 정의합니다. 다음 [링크](https://cosmos.network/rpc/)에서 확인이 가능합니다.
API는 엔드포인트의 카테고리에 따라 ICS 스탠다드로 나뉘어집니다. 예를 들어 [ICS20](https://cosmos.network/rpc/#/ICS20/)은 토큰 인터랙션 관련 API를 정의합니다.
서비스 제공자에게 더 많은 유연성을 제공하기 위해서 미서명 트랜잭션을 생성, [서명](https://cosmos.network/rpc/#/ICS20/post_tx_sign)과 [전달](https://cosmos.network/rpc/#/ICS20/post_tx_broadcast) 등의 다양한 API 엔드포인트가 제공됩니다. 이는 서비스 제공자가 자체 서명 메커니즘을 이용할 수 있게 합니다.
미서명 트랜잭션을 생성하기 위해서는 (예를 들어 [코인 전송](https://cosmos.network/rpc/#/ICS20/post_bank_accounts__address__transfers))을 생성하기 위해서는 `base_req` body에서 `generate_only` 플래그를 이용하셔야 합니다.

View File

@ -1,89 +0,0 @@
# 베이스앱(BaseApp)
베이스앱(BaseApp)은 코스모스 SDK 애플리케이션이 텐더민트 노드와 소통할 수 있게하는 기본적 ABCI 애플리케이션의 기반을 정의합니다.
베이스앱은 다수의 내부 컴포넌트로 구성되어있습니다. 이 중 가장 중요한 컴포넌트는 `CommitMultiStore`와 해당 컴포넌트의 내부 상태(internal state)입니다. 내부 상태는 하위 두 개의 서브스테이트(substate)로 구성되어있으며, 두 서브 스테이트는 각자 트랜잭션 실행 단계의 `CheckTx``DeliverTx` 이용됩니다. 블록 커밋 단계에서는 `DeliverTx`만이 유지됩니다.
베이스앱은 capabilities keys를 통해 스토어에 마운트 되어야 합니다. 핸들러는 키가 부여된 스토어에만 접근할 수 있습니다. 베이스앱은 모든 스토어가 정상적으로 로딩, 캐쉬 그리고 커밋되는 것을 보장합니다. 마운트 된 스토어 중 '메인(`baseApp.MainstoreKey`' 스토어는 최신 블록 헤더 정보를 보관하며, 이를 기반으로 가장 최근 상태(state)를 찾고 불러올 수 있습니다.
베이스앱은 `AnteHandler``MsgHandler` 두 가지의 핸들러 타입을 받습니다. `AnteHandler`는 논스값 확인, 서명 확인, 수수료 지불 가능 잔고 확인 등 모든 모듈에서 이용되는 트랜잭션 기능의 글로벌 유효성 검증(global validity check)을 수행합니다. `MsgHandler`의 경우 상태 변경(full state transition) 기능을 수행합니다.
`CheckTx` 단계에서 상태 변경 기능은 `checkTxState`에만 적용되며, 값비싼 스테이트 변경 작업이 실행되기 전에 리턴을 해야합니다(관련 절차 설계는 각 개발자의 자유입니다). 또한 예상 가스 비용을 리턴해야 합니다.
`DeliverTx` 단계에서는 상태 변경 기능이 블록체인 상태에 적용되며 트랜잭션은 완전하게 실행되어야 합니다.
베이스앱은 핸들러에게 전달되는 컨텍스트(context)를 관리하는 역할을 합니다. 또한 `CheckTx``DeliverTx`에게 할당되는 스토어와 블록헤더 정보를 제공합니다. 베이스앱은 시리얼화 포맷(serialization format)에 불가지론적(agnostic)입니다.
## 트랜잭션 라이프 사이클(Transaction Life Cycle)
트랜잭션은 실행 단계에서 ABCI 스펙 정의에 따라 `CheckTx``DeliverTx`를 거칠 수 있습니다. `CheckTx`는 블록 제안 검증인이 실행하며 모든 풀노드의 텐더민트 멤풀에서 이용됩니다.
`CheckTx``DeliverTx`는 (정의된 경우) 애플리케이션의 안티핸들러(AnteHandler)를 실행합니다. 여기서 안티핸들러는 메시지-전(pre-message) 검증을 수행하여 계정, 서명 검증, 수수료 삭감, 수수료 수금, 시퀀스 번호 추가 등의 기능을 수행합니다.
### CheckTx
`CheckTx`의 실행 단계에서는 안티핸들러(AnteHandler)만이 실행됩니다.
안티핸들러로 발생하는 상태 변경은 안티핸들러가 실패하여 중단되는 경우를 제외하고는 check-tx 상태의 `CheckTx`의 추후 콜(call)까지 지속됩니다.
### DeliverTx
`DeliverTx`의 실행 단계에서는 안티핸들러(AnteHandler)와 핸들러(Handler)가 함께 실행됩니다.
`DeliverTx`의 트랜잭션 실행 절차는 `CheckTx`와 유사하게 진행됩니다. 다만, 안티핸들러로 발생하는 상태 변경은 핸들러의 프로세싱 로직이 실패하여도 지속됩니다.
악의적 제안자(proposer)가 안티핸들러를 통과하지 못하는 트랜잭션을 발생할 수 있는 경우가 발생할 수도 있습니다. 이 경우에는 악의적 트랜잭션의 상태 변경은 버려집니다(무시됩니다).
## 다른 ABCI 메시지
`CheckTx``DeliverTx` 외에도 베이스앱은 다음과 같은 ABCI 메시지를 처리합니다.
### Info
TODO complete description (추후 업데이트 예정)
### SetOption
TODO complete description (추후 업데이트 예정)
### Query
TODO complete description (추후 업데이트 예정)
### InitChain
TODO complete description (추후 업데이트 예정)
체인 시동(chain initialization) 단계에서 `InitChain``CommitMultiStore`에 직접적으로 할당되어 있는 시동 로직을 실행합니다. check state와 deliver state는 정의된 ChainID로 시작됩니다.
참고할 것은 InitChain 이후에 커밋을 실행하지 않습니다. 그렇기 때문에 블록 1의 BeginBlock은 InitChain이 시작한대로 deliver state에서 시작됩니다.
### BeginBlock
TODO complete description (추후 업데이트 예정)
### EndBlock
TODO complete description (추후 업데이트 예정)
### Commit
TODO complete description (추후 업데이트 예정)
## 가스 관리(Gas Management)
### 가스: InitChain
InitChain 실행 단계에서 블록 가스 미터는 제네시스 트랜잭션을 처리하기 위하여 무한대 가스 수량을 기준으로 시작됩니다.
또한, InitChain의 리퀘스트 메시지에는 genesis.json 파일이 정의하는 ConsensusParams가 포함되어있습니다.
### 가스: BeginBlock
블록 가스 미터는 BeginBlock의 deliver state에서 리셋됩니다. 만약 베이스앱에서 최대 블록 가스가 설정되어있지 않은 경우, 가스 미터는 무한으로 설정됩니다. 최대 블록 가스가 설정되었을 경우, 가스 미터는 `ConsensusParam.BlockSize.MaxGas`를 통해 설정됩니다.
### 가스: DeliverTx
특정 트랜잭션이 실행되기 전, `BlockGasMeter`를 우선 확인하여 남은 가스가 있는지 확인합니다. 만약 남은 가스가 없다면 `DeliverTx`는 즉시 에러를 리턴합니다.
트랜잭션이 처리된 후, 사용된 가스는 (설정된 가스 리밋에 따라) `BlockGasMeter`에서 차감됩니다. 만약 잔류 가스가 가스 미터의 한도를 초과할 경우, `DeliverTx`는 에러를 리턴하고 해당 트랜잭션은 커밋되지 않습니다.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 283 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 186 KiB

View File

@ -1,16 +0,0 @@
<!--
order: false
parent:
order: 1
-->
# 소개
이 폴더에는 Cosmos-SDK에 대한 소개 자료가 포함되어 있습니다.
1. [SDK 소개](./overview.md)
2. [애플리케이션 특화 블록체인](./why-app-specific.md)
3. [SDK 애플리케이션의 아키텍쳐](./sdk-app-architecture.md)
4. [코스모스 SDK 디자인 소개](./sdk-design.md)
해당 기본 자료를 읽으신 후 [basics](../basics/README.md) 폴더에 있는 자료를 읽어보시는 것을 추천드립니다.

View File

@ -1,67 +0,0 @@
# 오브젝트-가능성 모델(Object-Capability Model)
## 개요
보안을 검토하기 위해서는 특정 위협 모델(threat model)을 검토하는 것으로 시작하는 것이 좋습니다. 우리가 제시하는 모델은 다음과 같습니다:
> 코스모스-SDK 모듈을 기반으로 만들어진 블록체인 애플리케이션이 활성화된 생태계에는 허점이 있거나 악의적인 모듈이 존재할 수 있다고 전재합니다.
코스모스 SDK는 오브젝트-가능성 시스템의 토대가 됨으로 이런 문제점을 해결할 수 있습니다.
> 오브젝트 가능성 시스템의 구조적 속성은 코드 디자인의 모듈화와 안정적인 캡슐화(encapsulation)를 선호합니다.
>
> 이런 구조적 속성은 오브젝트-가능 프로그램 또는 운영체제의 보안적 속성의 분석을 가능하게 합니다. 정보 플로우 속성(information flow properties) 같은 일부 속성은 특정 오브젝트의 행동을 결정하는 코드의 지식 또는 분석 없이도 오직 오브젝트 레퍼런스와 연결구조만으로 분석이 가능합니다.
>
> 그렇기 때문에, 악의적인 코드가 포함되있을 확률이 있는 새로운 오브젝트가 소개되더라도 보안적 속성은 지켜질 수 있습니다.
>
> 이런 구조적 속성은 해당 오브젝트를 통치하는 두가지 법칙에 의해 지켜질 수 있습니다:
>
> 1. 오브젝트 'A'는 'B'에 대한 레퍼런스를 보유하고 있을 경우에만 메시지를 전송할 수 있다.
> 2. 오브젝트 'A'가 'C'에 대한 레퍼런스를 가지고 싶다면 오브젝트 'A'는 'C'에 대한 레퍼런스가 포함된 메시지를 수신해야 한다.
>
> 이 두 법칙에 따르면 특정 오브젝트는 기존에 존재하는 레퍼런스 체인을 통해서만 다른 오브젝트에 대한 레퍼런스를 받을 수 있는 것입니다. 단순하게 설명하면 "연결성이 연결성을 불러온다"는 것입니다.
오브젝트 가능성에 대한 소개는 [이 글(영문)](http://habitatchronicles.com/2017/05/what-are-capabilities/)을 참고하세요.
원칙적으로 말하면, 다음과 같은 문제점 때문에 Golang은 엄격한 오브젝트 가능성을 도입하지 않는다고 볼 수 있습니다:
- 보편적으로 "unsafe" 또는 "os" 같은 원시적 모듈(primitive module)을 임포트할 수 있음.
- 보편적으로 [모듈 vars 오버라이드(https://github.com/golang/go/issues/23161)]가 가능.
- 2개 이상의 goroutine이 illegal interface value를 만들 수 있는 data-race 허점.
문제점 중 첫번째 문제는 임포트 감사(import audit)과 체계적인 디펜던시 버전 컨트롤 시스템(dependency version control system)을 이용하여 문제점을 사전에 찾을 수 있습니다. 다만, 두번째와 세번째 문제는 다서 불편하기는 하지만 노력을 통해서 감사(audit)가 가능합니다.
현재로써는 [Go2에서 오브젝트 가능성 모델이 도입되는](https://github.com/golang/go/issues/23157)것을 기대하는 상태입니다.
## 실전에서의 오브젝트 가능성 모델(Ocaps)
Ocaps의 핵심 아이디어는 특정 일을 수행하는데 필요한 정보만을 공개하는 것입니다.
예를 들어, 다음의 코드는 오브젝트 가능성 원칙을 위해합니다:
```go
type AppAccount struct {...}
var account := &AppAccount{
Address: pub.Address(),
Coins: sdk.Coins{sdk.NewInt64Coin("ATM", 100)},
}
var sumValue := externalModule.ComputeSumValue(account)
```
위 코드의 `ComputeSumValue` 메소드는 순수한(pure) 함수를 암시하지만, 포인터 밸류를 받아드리는 것의 암시된 가능성(implied capability)은 해당 밸류를 변경할 수 있는 가능성입니다. 서명 메소드는 그대로 포인터 밸류를 받아들이지 않고 해당 밸류의 사본을 사용하는 것이 바람직합니다.
```go
var sumValue := externalModule.ComputeSumValue(*account)
```
코스모스 SDK에서 이 원칙을 응용한 것을 [gaia 앱](../gaia/app/app.go)에서 확인이 가능합니다.
```go
// register message routes
app.Router().
AddRoute(bank.RouterKey, bank.NewHandler(app.bankKeeper)).
AddRoute(staking.RouterKey, staking.NewHandler(app.stakingKeeper)).
AddRoute(distr.RouterKey, distr.NewHandler(app.distrKeeper)).
AddRoute(slashing.RouterKey, slashing.NewHandler(app.slashingKeeper)).
AddRoute(gov.RouterKey, gov.NewHandler(app.govKeeper))
```

View File

@ -1,33 +0,0 @@
---
order: 1
---
# SDK 소개
## 코스모스 SDK는 무엇인가?
[코스모스 SDK](https://github.com/cosmos/cosmos-sdk)는 코스모스 허브와 같은 다수 자산(multi-asset) 퍼블릭 지분증명 블록체인과 권한증명(PoA, Proof-of-Authority) 블록체인을 만들 수 있는 오픈소스 프레임워크입니다. 코스모스 SDK를 사용하여 만들어진 블록체인은 통상 **애플리케이션 특화 블록체인(application-specific blockchain)**이라 불립니다.
코스모스 SDK의 목적은 개발자가 간편하게 처음부터 다른 블록체인과 상호환이 가능한 블록체인을 만들 수 있게 하는 것이 목적입니다. 코스모스 SDK는 npm과 같은 프레임워크로 자리잡으며 [텐더민트](https://github.com/tendermint/tendermint) 상의 안전한 블록체인 애플리케이션을 만들 수 있게 자리잡는 것이 목표입니다. SDK 기반 블록체인은 구성적(composable) 모듈을 기반으로 만들어지며, 대다수의 모듈은 오픈 소스로 모든 개발자가 사용할 수 있습니다. 누구나 코스모스 SDK 모듈을 만들 수 있으며, 단순히 블록체인 애플리케이션에 모듈을 불러와 이미 개발된 모듈을 간편하게 사용할 수 있습니다. 또한, 코스모스 SDK는 능력성 기반(capabilities-based) 시스템으로 모듈 간 인터랙션의 보안성을 더욱 직관적으로 설계할 수 있습니다. 능력성 기반 시스템에 대해 더 알고싶으시다면 [이 항목](./ocap.md)을 참고하세요.
## 애플리케이션 특화 블록체인은 무엇인가?
최근 블록체인 업계의 개발 패러다임 중 하나는 이더리움과 같은 버추얼 머신(virtual-machine) 기반 블록체인입니다. 이런 시스템에서는 기존 블록체인 상위에 스마트 컨트랙트 기반의 탈중앙화 애플리케이션을 만드는 형태로 개발됩니다. 스마트 컨트랙트는 단순 애플리케이션 (예, ICO) 용도로 적합하지만, 복잡한 탈중앙화 플랫폼을 개발하는 목적에는 적합하지 않습니다. 스마트 컨트랙트는 유연성, 존엄성 그리고 성능 측면에서 한계가 존재합니다.
애플리케이션 특화 블록체인은 기존 버추얼 머신 기반 블록체인과는 획기적으로 다른 개발 패러다임을 제공합니다. 애플리케이션 특화 블록체인은 하나의 애플리케이션을 구동하기 위해 특화되며, 개발자는 애플리케이션이 최적한 환경에서 구동될 수 있는 디자인 결정을 내릴 수 있습니다. 또한 애플리케이션 특화 블록체인은 애플리케이션 존엄성, 보안 그리고 성능 측면에서 장점을 가집니다.
애플리케이션 특화 블록체인에 대한 더 자세한 정보는 [여기](./why-app-specific.md)를 참고하세요.
## 왜 코스모스 SDK인가?
코스모스 SDK는 고유 애플리케이션 특화 블록체인을 만들기 위한 가장 우수한 프레임워크입니다. 다음은 코스모스 SDK가 탈중앙화 애플리케이션을 개발하는데 제공하는 장점들입니다:
- 코스모스 SDK가 기본적으로 제공하는 합의 엔진은 [텐더민트 코어](https://github.com/tendermint/tendermint)입니다. 텐더민트는 가장 오랜 기간 증명된 BFT 기반 컨센서스 엔진입니다. 텐더민트 코어는 업계 내의 수 많은 환경에서 지분증명 시스템을 개발하는데 사용되고 있습니다.
- 코스모스 SDK는 오픈소스이며 구성적(composable) 모듈을 기반으로 간편하게 블록체인을 만들 수 있습니다. 블록체인 생태계가 성장하며 더욱 다양한 코스모스 SDK 모듈들이 개발되고 있으며, 이런 모듈들을 기반으로 복잡한 탈중앙화 플랫폼을 개발하는 과정이 간소화됩니다.
- 코스모스 SDK는 능력성 기반(capabilities-based) 보안 아키텍쳐를 기반으로 설계되었습니다. 이런 디자인 결정은 수년간 블록체인 스테이트 머신(state machine)에 대한 고민을 기반으로 설계되었으며, 더욱 안전한 블록체인을 개발할 수 있는 환경을 제공합니다.
- 가장 중요한 것은 바로 코스모스 SDK가 실제 작동하고 있는 다수의 애플리케이션 특화 블록체인을 개발하는데 사용되고 있다는 점입니다. [코스모스 허브](https://hub.cosmos.network), [아이리스 허브](https://irisnet.org), [바이낸스 체인](https://docs.binance.org), [테라](https://terra.money), [Lino](https://lino.network) 등의 프로젝트가 코스모스 SDK 기반으로 개발되었습니다. 코스모스 기반 프로젝트 목록은 [여기](https://cosmos.network/ecosystem)에서 확인하실 수 있습니다.
## 코스모스 SDK 입문하기
- [코스모스 SDK 기반 애플리케이션의 구조](./sdk-app-architecture.md)에 대해서 더 알아보세요
- 애플리케이션 특화 블록체인을 처음부터 개발하는 방법을 [코스모스 SDK 투토리얼](https://cosmos.network/docs/tutorial)을 통해 배워보세요

View File

@ -1,98 +0,0 @@
<!--
order: 3
-->
# SDK 애플리케이션 아키텍쳐
## 상태 기계 (state machine)
블록체인 애플리케이션은 근본적으로 [결정론적 복제 상태 기계(replicated deterministic state machine)](https://ko.wikipedia.org/wiki/%EC%83%81%ED%83%9C_%EA%B8%B0%EA%B3%84_%EB%B3%B5%EC%A0%9C)입니다.
상태 기계는 특정 시점에 오직 하나의 상태를 유지하는 있는 컴퓨터 공학 개념입니다. 여기서 '상태 기계' 개념에는 시스템의 현 상태를 뜻하는 '상태(state)'가 있으며, 상태의 변경을 유발하는
트랜잭션(transaction)'이 있습니다.
`S` 라는 상태와 `T` 라는 트랜잭션이 있는 경우, 상태 기계는 `S'`라는 새로운 상태를 리턴합니다.
```
+--------+ +--------+
| | | |
| S +---------------->+ S' |
| | (T)적용 | |
+--------+ +--------+
```
실질적으로는 트랜잭션은 블록 단위로 묶여 상태 변경 과정을 더 효율적일 수 있게 합니다. `S`라는 상태와 `B`라는 트랜잭션이 있는 경우, 상태 기계는 `S'`라는 새로운 상태를 리턴합니다.
```
+--------+ +--------+
| | | |
| S +----------------------------> | S' |
| | B의 T 수만큼: (T)적용 | |
+--------+ +--------+
```
블록체인 시스템 개념으로 점그할때, 상태 기계는 결정론적(deterministic)입니다. 즉, 노드가 특정 상태에서 시작된 후 동일한 트랜잭션들을 반복할 경우, 결과 상태는 언제나 동일합니다.
코스모스 SDK는 애플리케이션의 상태, 트랜잭션 형태 그리고 상태 변경 기능(state-transition function)을 정의하는데 최대한의 유연성을 제공합니다. 코스모스 SDK를 이용해 상태 기계를 만드는 과정은 이후 항목에서 다루겠습니다. 우선 이 시스템 내에서 어떻게 **텐더민트**를 사용해 '상태'가 복제되는지 알아보겠습니다.
## 텐더민트
개발자는 코스모스 SDK를 사용하여 상태 기계만을 정의하면 되며, 해당 상태를 네트워크에 복제하는 기능은 [*텐더민트*](https://tendermint.com/docs/introduction/introduction.html)가 제공합니다.
```
^ +-------------------------------+ ^
| | | | 코스모스 SDK로 개발
| | 상태 기계 = 애플리케이션 | |
| | | v
| +-------------------------------+
| | | ^
블록체인 노드 | | 컨센서스 | |
| | | |
| +-------------------------------+ | 텐더민트 코어
| | | |
| | 네트워킹 | |
| | | |
v +-------------------------------+ v
```
텐더민트는 오직 블록체인의 *네트워킹*과 *합의(컨센서스)* 계층을 처리하는 애플리케이션-불가지성(application-agnostic) 엔진입니다. 실질적으로 텐더민트는 단순히 트랜잭션의 바이트를 나열하고, 해당 트랜잭션을 네트워크에 전파하는 역할만을 한는 것입니다. 텐더민트 코어는 텐더민트 비잔틴 결함 감내(BFT, Byzantine-fault tolerant) 알고리즘을 사용하여 트랜잭션 순서에 대한 합의를 합니다.
텐더민트 합의 알고리즘은 '검증인(Validators)'이라는 특정 노드 세트를 기반으로 작동합니다. 특정 블록에는 V 검증인 세트 검증인 존재하며, 이 V 검증인 세트 안에 있는 검증인 중 하나의 검증인이 다음 블록 생성자로 알고리즘에 의해 선택됩니다. 만약 블록이 V 검증인 세트 2/3 이상의 [프리보트(prevote)](https://tendermint.com/docs/spec/consensus/consensus.html#prevote-step-height-h-round-r)와 [프리커밋(precommit)](https://tendermint.com/docs/spec/consensus/consensus.html#precommit-step-height-h-round-r)을 받고 내용 트랜잭션이 유효한 경우 해당 블록은 '유효(valid)'한 것으로 간주됩니다. 검증인 세트는 상태 기계에 작성된 규칙에 따라서 바뀔 수 있습니다.
## ABCI
텐더민트는 ABCI라를 인터페이스를 사용해 트랜잭션을 애플리케이션에게 전달합니다. 이는 어플리케이션이 반드시 구현해야하는 부분입니다.
```
+---------------------+
| |
| 애플리케이션 |
| |
+--------+---+--------+
^ |
| | ABCI
| v
+--------+---+--------+
| |
| |
| 텐더민트 |
| |
| |
+---------------------+
```
**텐더민트는 오직 거래의 bytes 값들만 취급하지 실제 그 bytes 들이 어떤 의미를 가지고 있는지는 파악하지 않습니다.** 텐더민트가 하는 일은 이 거래 bytes 들을 결정론적으로 나열하는 것 뿐입니다. 텐더민트는 이 bytes 들을 ABCI 를 통해서 어플리케이션에 넘겨주고, 그 메세지에 담겨있는 거래들이 잘 처리되었는지 안되었는지를 확인해주는 return code 를 기다립니다.
아래에 ABCI 의 메세지들 중 가장 중요한 것들을 나열해놓았습니다:
- `CheckTx`: 텐더민트 코어로부터 거래를 받게 될 때, 이 거래는 어플리케이션에 넘겨져서 몇 가지 기본 요건을 충족하는지 확인합니다. `CheckTx` 는 풀노드의 mempool을 스팸행위로 부터 보호하는데 사용됩니다. "Ante Handler" 라고 불리우는 특별한 handler 는 일련의 검증 과정을 실행하는데 사용됩니다. 예를 들면, 충분한 수수료가 있는지, 그리고 서명이 유효한지 확인합니다. 만약 검사 결과가 유효한 경우 되면, 해당 거래는 [mempool](https://tendermint.com/docs/spec/reactors/mempool/functionality.html#mempool-functionality)에 추가되고 피어 노드에게 전달됩니다. 참고로 트랜잭션이 블록에 추가되기 전까지는 `CheckTx` 과정이 진행되지 않습니다. (즉, 상태의 변경이 일어나지 않습니다.)
- `DeliverTx` : 텐더민트 코어가 [유효한 블록](https://tendermint.com/docs/spec/blockchain/blockchain.html#validation)을 전달받는 경우, 각 블록의 트래잭션은 `DeliverTx`를 통해 애플리케이션에 전달합니다. 이 단계에서 상태 변경이 일어납니다. `AnteHandler`는 트랜잭션에 포함된 각 메세지를 검증하기 위해 다시 실행됩니다.
- `BeginBlock`/`EndBlock` : 해당 메세지는 블록내 트랜잭션 유뮤와는 별개로 블록 시작과 끝 단계에서 실행됩니다. 여기에서 로직의 자동 실행을 설정하는 것이 유용합니다. 하지만 복잡한 연산 또는 루프는 블록체인의 속도를 저하할 수 있으며, 무한 루프의 경우 블록체인을 멈출 수 있습니다.
ABCI 메소드와 타입에 대해서 더 자세하게 싶다면, [텐더민트 문서](https://tendermint.com/docs/spec/abci/abci.html#overview)를 참고하세요.
텐더민트 위에 구현된 모든 어플리케이션은 하위 텐더민트 엔진과 소통하기 위해 ABCI 인터페이스를 구현해야만 합니다. 물론 코스모스 SDK를 사용하는 경우, 코스모스 SDK가 [baseapp](https://cosmos.network/docs/intro/sdk-design.html#baseapp) 의 형태로 일종의 템플릿를 제공합니다.
### 다음은 [SDK 설계 원칙에 대해서 알아보세요](https://cosmos.network/docs/intro/sdk-design.html#baseapp)

View File

@ -1,95 +0,0 @@
<!--
order: 4
-->
# 코스모스 SDK의 주요 구성 요소
코스모스 SDK는 텐더민트 위에서 안전한 상태 기계를 구현하는 프레임워크입니다. 핵심적으로, 코스모스 SDK는 일종의 Go 언어로 구현된 [ABCI](./sdk-app-architecture.md#abci) 구현체 템플릿입니다. 코스모스 SDK에는 데이터를 지속하는 [`multistore`](../core/store.md#multistore)와 트래잭션을 처리하는 [`router`](../core/baseapp.md#routing)가 내장되어 있습니다.
다음은 코스모스 SDK로 만들어진 애플리케이션에서 텐더민트에서 `DeliverTx`로 전달된 트랜잭션이 처리되는 과정을 간소화한 설명입니다:
1. 텐더민트 컨센서스 엔진(텐더민트는 `[]bytes`만을 다룬다는 것을 참고하세요)에서 전달된 `transaction`을 디코딩
2. `transaction`에서 `messages`를 추출한 후 기본적인 타당성 검사를 진행
3. 각 메시지가 처리될 수 있게 올바른 모듈에게 라우팅
4. 상태 변경 실행
## `baseapp`
`baseapp`은 코스모스 SDK 애플리케이션 구현체 템플릿입니다. 하위 컨센서스 엔진과 연결을 처리하기 위한 구현체가 포함 되어있습니다. 통상, 코스모스 SDK 애플리케이션에서는 [`app.go`](../basics/app-anatomy.md#core-application-file)내에 `baseapp`을 임베딩합니다. 이에 대한 예시는 코스모스 SDK 애플리케이션 튜토리얼을 참고하세요:
+++ https://github.com/cosmos/sdk-tutorials/blob/c6754a1e313eb1ed973c5c91dcc606f2fd288811/app.go#L72-L92
`baseapp`의 목표는 스토어와 확장 가능한 상태 기계간의 안전한 인터페이스를 제공함과 동시에 상태 기계를 최소한으로 정의하는(ABCI 디자인 목적에 따라) 것입니다.
`baseapp`에 대한 추가 정보는 [여기](../core/baseapp.md)를 참조하세요.
## 멀티스토어
코스모스 SDK는 지속되는 상태를 위해 [`멀티스토어/multistore`](../core/store.md#multistore)를 제공합니다.멀티스토어는 개발자가 원하는 수량의 [`KVtore`](../core/store.md#base-layer-kvtores)를 선언할 수 있도록 합니다. `KVStore`는 오직 `[]byte` 타입만을 유효한 값으로 받기 때문에 자체 스트럭쳐는 [코덱](../core/encoding.md)을 사용해 마셜된 후 저장되어야 합니다.
멀티스토어를 추상화한 이유는 상태를 구획화하기 위한 목적이 있으며, 각자 해당되는 모듈에 의해 관리됩니다. 멀티스토어 대한 추가 정보는 [여기](../core/store.md#multistore)를 확인하세요.
## 모듈
코스모스 SDK의 강점은 바로 모듈성에 있습니다. SDK 기반 애플리케이션은 다수의 상호 호환되는 모듈을 모아서 개발됩니다. 각 모듈은 상태의 특정 분야를 정의하고 자체적인 메시지/트랜잭션 처리 기능을 가지고 있으며, 코스모스 SDK는 각 메시지를 해당되는 모듈에 라우팅하는 역할을 합니다.
다음은 어떻게 트랜잭션이 각 풀노드가 유효한 블록을 받았을때 애플리케이션에 의해 처리되는지를 설명합니다:
```
+
|
| DeliverTx를 통해 풀노드의 텐더민트에서
| 노드의 애플리케이션으로 전달된 트랜잭션
|
|
|
+---------------------v--------------------------+
| 애플리케이션 |
| |
| 베이스앱의 메서드를 사용해: Tx 디코딩, |
| 메시지 추출 후 라우팅 |
| |
+---------------------+--------------------------+
|
|
|
+---------------------------+
|
|
|
| 처리를 위해 올바른
| 모듈로 라우팅된 메시지
|
|
+----------------+ +---------------+ +----------------+ +------v----------+
| | | | | | | |
| AUTH 모듈 | | BANK 모듈 | | STAKING 모듈 | | GOV 모듈 |
| | | | | | | |
| | | | | | | 메시지 처리, |
| | | | | | | 상태 업데이트 |
| | | | | | | |
+----------------+ +---------------+ +----------------+ +------+----------+
|
|
|
|
+--------------------------+
|
| 결과 값 텐더민트로 전달
| (0=Ok, 1=Err)
v
```
각 모듈은 미니 상태 기계로 볼 쑤 있습니다. 개발자는 각 모듈이 처리하는 상태의 부분과 상태를 바꾸는 고유 메시지 타입을 정의해야합니다(*참고*: 메시지는 트랜잭션에서 `baseapp`을 통해 추출됩니다). 통상적으로, 각 모듈은 각자의 `KVStore``multistore`에 선언하여 해당 모듈이 정의하는 상태의 부분을 지속합니다. 개발자는 본인의 모듈을 만들때 제 삼자의 모듈을 액세스해야할 수 있습니다. 코스모스-SDK는 오픈 프레임워크이기 때문에, 일부 모듈은 악성 모듈일 가능성이 존재하며 이런 인터-모듈 소통에서 보안 원칙이 존재합니다. 이런 원칙은 [오브젝트-가능성(object-capabilities)](../core/ocap.md)를 따릅니다. 실전에서는, 각 모듈이 다른 모듈의 액세스 권한 리스트를 관리하는 것이 아니라, 각 모듈이 `keeper`라는 특별 오브젝트를 구현하여 접근 가능한 권한을 사전에 정의합니다.
SDK의 모듈은 `x/` 폴더 내에 정의되며, 핵심 모듈 중 일부는 다음과 같습니다:
- `x/auth`: 계정과 서명 관리에 사용됨
- `x/bank`: 토큰과 토큰 전송 기능에 사용됨
- `x/staking` + `x/slashing`: 지분증명 블록체인을 만들기 위해 사용됨
모두가 본인의 앱을 만들기 위해 사용할 수 있는 `x/` 내 존재하는 모듈 외에도, 코스모스 SDK는 자체 모듈을 개발할 수 있도록합니다. 이에 대한 예시는 [이 튜토리얼](https://cosmos.network/docs/tutorial/keeper.html)을 참고하세요.
## 다음 {hide}
[코스모스 SDK 애플리케이션 해부학](../basics/app-anatomy.md)에 대해서 알아보세요 {hide}

View File

@ -1,80 +0,0 @@
<!--
order: 2
-->
# 애플리케이션 특화 블록체인
이 문서는 애플리케이션 특화 블록체인(application-specific blockchain)을 정의하고, 왜 개발자들이 스마트 컨트랙트 대신 애플리케이션 특화 블록체인을 사용하는데 장점이 있는지 설명합니다. {synopsis}
## 애플리케이션 특화 블록체인은 무엇인가?
애플리케이션 특화 블록체인은 하나의 애플리케이션을 운영하는데 특화된 블록체인입니다. 이더리움과 같이 하나의 블록체인 플랫폼 위에서 탈중앙화 애플리케이션을 만드는 것이 아니라, 애플리케이션 특화 블록체인은 블록체인의 모든 계층을 직접 만드는 형태입니다. 즉, 풀 노드 클라이언트, 라이트 클라이언트, 필수 인터페이스(CLI, REST, 등)를 노드와 소통하도록 개발하게 됩니다
```
^ +-------------------------------+ ^
| | | | 코스모스 SDK로 개발
| | 상태 기계 = 애플리케이션 | |
| | | v
| +-------------------------------+
| | | ^
블록체인 노드 | | 컨센서스 | |
| | | |
| +-------------------------------+ | 텐더민트 코어
| | | |
| | 네트워킹 | |
| | | |
v +-------------------------------+ v
```
## 스마트 컨트랙트의 한계는 무엇인가?
이더리움과 같은 버추얼 머신(virtual machine) 기반 블록체인은 2014년 당시 블록체인의 프로그램화에 대한 수요를 충족했습니다. 다수의 개발자는 복잡하고 한계가 있는 비트코인 스크립트 언어로 애플리케이션을 개발하거나, 수정하기 어려운 비트코인 코드 포크해야하는 어려움이 있었기 때문입니다.
이런 시기에, 버추얼 머신 기반 블록체인은 새로운 가치 제안을 하게됩니다. 상태 기계(state machine)가 일종의 버추얼 머신을 운용하여 '스마트 컨트랙트'라는 튜링 완전한 프로그램을 실행할 수 있도록 했습니다. 이런 스마트 컨트랙트는 일시적 이벤트에 매우 적절하지만 (예, ICO) 복잡한 탈중앙화 플랫폼을 개발하는대에는 한계가 있습니다. 이유는 다음과 같습니다:
- 스마트 컨트랙트는 통상 해당 버추얼 머신이 이해할 수 있는 특정 언어만으로만 개발될 수 있습니다. 이런 언어들은 다른 언어에 비교해 미숙한 부분이 많으며, 근본적으로 버추얼 머신의 한계에 의해 제한됩니다. 예를 들어, 이더리움 버추얼 머신(Ethereum Virtual Machine, EVM)은 개발자의 코드의 자동 실행을 허용하지 않습니다. 또한 개발자는 EVM의 계정 시스템을 사용해야 하며, 제한된 함수만으로 암호학 연산을 할 수 있습니다. 위 예시들은 통상 스마트 컨트랙트 플랫폼의 근본적인 **유연성의 부족함**을 보여줍니다.
- 모든 스마트 컨트랙트는 동일한 버추얼 머신에서 실행됩니다. 이는 근본적으로 모든 스마트 컨트랙트가 한정된 자원을 위해 경쟁해야하는 구조며 **성능**의 한계를 불러옵니다. 상태 기계가 (샤딩 같은 기술을 통해) 다수의 서브 세트(subset)로 나눈다는 가정에서도, 스마트 컨트랙트는 동일한 버추얼 머신에서 실행되어야 하기 때문에 상태 기계단에서 구현된 네이티브 애플리케이션 보다 많은 성능 제한이 있습니다(내부적인 벤치마크 테스트에 따르면, 버추얼 머신을 제거함으로 약 10배 가량의 성능 증가가 있었습니다).
- 또 다른 문제는 모든 스마트 컨트랙트가 근본적으로 동일한 환경을 공유하기 때문에 **독립성(sovereignty)**에 대한 한계가 존재합니다. 탈중앙화 애플리케이션은 다수의 이해관계자들이 존재하는 생태계입니다. 만약 애플리케이션이 범용적 버추얼 머신 블록체인에서 개발되는 경우, 애플리케이션의 이해관계자는 본인 애플리케이션에 대한 주권이 제한되며 하위 블록체인 거버넌스를 따라야합니다. 만약 애플리케이션에 버그가 존재하는 경우, 조치할 수 있는 방법이 많이 존재하지 않습니다.
애플리케이션 특화 블록체인은 이런 한계점을 극복하기 위해 설계되었습니다.
## 애플리케이션 특화 블록체인의 장점
### 유연성
애플리케이션 특화 블록체인은 개발자에게 최고의 유연성을 제공합니다:
- 코스모스 블록체인의 경우, 상태 기계는 [ABCI](https://tendermint.com/docs/spec/abci/)라는 인터페이스를 통해 하위 컨센서스 엔진과 연결됩니다. 이런 인터페이스는 어떤 프로그램 언어로 구현될 수 있으며, 이는 개발자가 본인이 선호하는 프로그램 언어로 상태 기계를 구현할 수 있다는 것을 의미합니다.
- 개발자는 본인의 상태 기계를 구현하기 위해서 다수의 프레임워크 중 하나를 선택할 수 있습니다. 현재 가장 많이 사용되는 프레임워크는 코스모스 SDK이지만, 다른 프레임워크(예, [Lotion](https://github.com/nomic-io/lotion), [Weave](https://github.com/iov-one/weave), 등)의 프레임워크가 존재합니다. 통상 프레임워크는 개발자가 선호하는 언어에 따라 결정됩니다 (예, 코스모스 SDK와 Weave는 Go언어, Lotion은 자바스크립트 등).
- ABCI는 개발자가 본인의 애플리케이션 특화 블록체인의 컨센서스 엔진을 변경할 수 있게 합니다. 현재로써는 텐더민트만이 검증된 프레임워크이지만, 앞으로 더 많은 컨센서스 엔진이 존재할 것으로 예상됩니다.
- 개발자가 특정 프레임워크와 컨센서스 엔진을 선택하는 경우에도, 해당 개발자는 해당 프레임워크와 엔진을 본인이 필요하는대로 변경할 수 있는 자유가 있습니다.
- 개발자는 다수의 트레이오프(예, 검증인의 숫자 vs 트랜잭션 처리량, 안전성 vs 비동기적 환경에서의 생존성 등)와 디자인 아키텍쳐(스토리지에서 DB 또는 IAVL 트리를 사용할지, UTXO 또는 계정 모델을 사용할지)를 선택할 수 있습니다.
- 개발자는 코드의 자동 실행을 구현할 수 이습니다. 코스모스 SDK에서는 매 블록의 시작과 끝에서 로직이 자동으로 실행될 수 있게 설계할 수 있습니다. 또한 사용하는 버추얼 머신의 환경에 극한되지 않게 애플리케이션에서 사용될 암호학을 직접 선택할 수 있습니다.
위 항목들은 애플리케이션 특화 블록체인이 개발자에게 주는 유연성의 예시를 보여줍니다. 코스모스와 코스모스 SDK의 목표는 개발자 툴링이 최대한 일반적(generic)이고 구성성(composable)있도록 만드는 것에 있기때문에, 스택의 각 컴포넌트가 포크되고, 변경되고, 개선되어도 호환성을 지킬 수 있도록 설계되었습니다. 커뮤니티가 성장할수록 코어 모듈들에 대한 대안이 나올 것으로 기대되며, 이는 개발자들에게 더 많은 선택권을 제공하게 됩니다.
### 성능
스마트 컨트랙트의 형태로 구현되는 탈중앙화 애플리케이션은 하위 환경의 성능에 제한될 수밖에 없습니다. 탈중앙화 애플리케이션이 성능을 최적화하기 위해서는 애플리케이션 특화 블록체인으로 구성되어야 합니다. 다음은 애플리케이션 특화 블록체인의 성능적인 장점을 설명합니다:
- 애플리케이션 특화 블록체인 개발자는 텐더민트 같은 새로운 컨센서스 엔진을 사용할 수 있으며, 이는 작업증명(Proof-of-work, PoW)에 비해서 상당한 성능 개선을 제공합니다.
- 애플리케이션 특화 블록체인은 하나의 애플리케이션만을 실행하기 때문에 해당 애플리케이션은 다른 애플리케이션과 스토리지와 연산력에 대한 경쟁을 하지 않습니다. 이는 연산력과 스토리지를 위해 다른 애플리케이션과 경쟁해야하는 기존 (샤딩을 도입하지 않은) 버추얼 머신 기반 블록체인 시스템과 대치합니다.
- 만약 버추얼 머신 기바의 블록체인이 애플리케이션 기반 샤딩과 효율적인 컨센서스 알고리즘을 제공한다고 해도, 애플리케이션의 성능은 버추얼 머신 자체에 의해 제한됩니다. 처리량(throughput)에 대한 한계는 상태 기계이며, 트랜잭션이 버추얼 머신을 통해 처리되어야 하는 것 자체가 트랜잭션 처리의 연산 복잡성을 인상하게 됩니다.
### 보안
보안을 수치화하는 것은 쉽지 않으며, 플랫폼의 특성마다 다를 수 있습니다. 다만, 애플리케이션 특화 블록체인이 보안적으로 제공하는 특정 장점은 존재합니다:
- 개발자는 Go 언어같은 검증된 언어로 애플리케이션 특화 블록체인을 개발할 수 있는 반면, 스마트 컨트랙트는 보통 미성숙한 언어로 개발해야 합니다.
- 개발자는 하위 버추얼 머신이 제공하는 암호학 함수를 사용해야하는 제한이 없으며, 검증된 암호학 라이브러리를 사용하거나 자체적인 암호학 알고리즘을 적용할 수 있습니다.
- 개발자는 하위 버추얼 머신에서 존재할 수 있는 버그 또는 메커니즘에 대한 걱정을 하지 않아도 되며, 애플리케이션 보안에만 집중할 수 있습니다.
### 독립성
애플리케이션 특화 블록체인이 제공하는 가장 큰 장점 중 하나는 독립성(sovereignty, 존엄성)입니다. 탈중앙화 애플리케이션에는 유저, 개발자, 서비스 제공자 등 다수의 이해 관계자가 존재합니다. 개발자가 다수의 애플리케이션이 공존하는 버추얼 머신 기반 블록체인에서 본인의 애플리케이션을 개발하는 경우 본인 애플리케이션 커뮤니티와 하위 블록체인 플랫폼 커뮤니티가 다를 수 있으며, 하위 블록체인 플랫폼 커뮤니티가 애플리케이션 커뮤니티의 거버넌스를 지배하는 관계가 형성됩니다. 버그가 존재하거나 새로운 기능이 추가되는 경우, 애플리케이션의 이해관계자는 업그레이드를 실행하는데 제한되며 하위 플랫폼의 커뮤니티가 해당 과정을 받아드리지 않는 경우, 할 수 있는 것이 없게됩니다.
여기서 근본적으로 존재하는 문제는 애플리케이션의 거버넌스와 플랫폼의 거버넌스가 일치하지 않는다는 것입니다. 애플리케이션 특화 블록체인에서는 블록체인이 한 애플리케이션을 위해 존재하기 때문에 애플리케이션의 이해관계자가 블록체인 전체에 대한 통제권을 부여받게 됩니다. 이는 커뮤니티가 버그를 발견하는 경우 조치를 할 수 있는 권한을 가질 수 있으며, 자체적으로 진화하는 방향을 정할 수도 있는 장점이 있습니다.
## 다음 {hide}
코스모스 SDK [애플리케이션의 구조](./sdk-app-architecture.md)에 대해 알아보세요{hide}

View File

@ -1,41 +0,0 @@
# Cosmos SDK Documentation Translation (Korean)
This document tracks the progress of the Korean translation of the official Cosmos SDK documentation.
Documentation has been translated for **reference use only** and may contain typos, factual errors and be out-of-date with the latest english documentation.
Please refer to the official english version of the documentation for the latest and accurate information.
## 코스모스 SDK 도큐멘테이션 번역 (한국어)
이 문서는 코스모스 공식 문서의 번역 작업 트래킹을 위한 문서입니다.
번역된 문서는 **참고용**으로 번역되었습니다. 다수의 오타, 오류가 존재할 수 있으며, 영문 업데이트보다 번역이 느리게 진행될 수 있다는 점을 인지하시기 바랍니다.
코스모스 관련 가장 정확한 정보를 확인하시기 위해서는 영어 원문을 참고하시기 바랍니다.
## Progress by directory
### [`concepts`](../concepts/)
- Synced until commit [14ebc65](https://github.com/cosmos/cosmos-sdk/commit/14ebc65daffd63e1adf17995c103aac9380207ef#diff-f874f370376bf359320af0543de53fcf)
### [`spec`](../spec/)
- Redacted from until completion
### [`gaia`](../gaia/)
- Synced until commit [288df6f](https://github.com/cosmos/cosmos-sdk/commit/288df6fe69dcef8fa95aca022039f92ba1e98c11#diff-3302fe357e01f0996ddb0f10adec85f0)
### [`intro`](../intro/)
- Synced until commit [0043912](https://github.com/cosmos/cosmos-sdk/commit/0043912548808b4cfd6ab84ec49ba73bd5f65b5b#diff-e518eaec0d99787e6f75682d54751821)
### [`modules`](../modules/)
- Synced until commit [78a2135](https://github.com/cosmos/cosmos-sdk/commit/78a21353da978d6c2a9b711f29b3874ff9ca14ae#diff-449cc65858e8929d15f4a170950e7758)
### [`clients`](../clients/)
- Synced until Commit [857a65d](https://github.com/cosmos/cosmos-sdk/commit/857a65dc610cd736a47980b5d4778e5123206a3d#diff-93dd988c16d20a1bce170b86ad89425a)

View File

@ -1,37 +0,0 @@
# Bank
`x/bank` 모듈은 계정 간 코인을 이동할때 사용됩니다.
[API 문서](https://godoc.org/github.com/cosmos/cosmos-sdk/x/bank)를 확인하세요.
# Stake
`x/staking` 모듈은 코스모스 위임형 지분증명(Delegated-Proof-of-Stake) 시스템에서 사용됩니다.
[API 문서](https://godoc.org/github.com/cosmos/cosmos-sdk/x/staking)를 확인하세요.
관련 스펙은 [여기](https://github.com/cosmos/cosmos-sdk/tree/master/docs/spec/staking)에서 확인하실 수 있습니다.
# Slashing
`x/slashing` 모듈은 코스모스 위임형 지분증명(Delegated-Proof-of-Stake) 시스템에서 사용됩니다.
[API 문서](https://godoc.org/github.com/cosmos/cosmos-sdk/x/slashing)를 확인하세요.
관련 스펙은 [여기](https://github.com/cosmos/cosmos-sdk/tree/master/docs/spec/slashing)에서 확인하실 수 있습니다.
# Provisions
`x/provisions` 모듈은 수수료 보상 분배와 스테이킹 인플레이션을 조정할때 사용됩니다.
[API 문서](https://godoc.org/github.com/cosmos/cosmos-sdk/x/distribution)를 확인하세요.
관련 스펙은 [여기](https://github.com/cosmos/cosmos-sdk/tree/master/docs/spec/distribution)에서 확인하실 수 있습니다.
# Governance
`x/gov` 모듈은 본딩한 토큰 보유자들이 프로포절을 만들고 투표를 진행할때 사용됩니다.
[API 문서](https://godoc.org/github.com/cosmos/cosmos-sdk/x/gov)를 확인하세요.
관렉 스펙은 [여기](https://github.com/cosmos/cosmos-sdk/tree/master/docs/spec/governance)에서 확인하실 수 있습니다.

3
docs/ru/README.md Executable file
View File

@ -0,0 +1,3 @@
# Cosmos SDK Documentation (Russian)
A Russian translation of the Cosmos SDK documentation is not available for this version. If you would like to help with translating, please see [Internationalization](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOCS_README.md#internationalization). A `v0.39` version of the documentation can be found [here](https://github.com/cosmos/cosmos-sdk/tree/v0.39.3/docs/ru).

View File

@ -1,35 +0,0 @@
---
order: 1
---
# Введение в Cosmos SDK
## Что такое Cosmos SDK?
[Cosmos SDK](https://github.com/cosmos/cosmos-sdk) — это фреймворк для создания публичных Proof-of-Stake (PoS) и закрытых Proof-Of-Authority (PoA) multi-asset блокчейнов. Блокчейны, разработанные с помощью Cosmos SDK, называют application-specific, то есть созданные для конкретного приложения. Исходный код Cosmos SDK находится в свободном доступе и распространяется под лицензией Apache License 2.0.
Цель Cosmos SDK: дать разработчикам инструменты для создания с нуля собственных блокчейнов, которые смогут нативно взаимодействовать с другими блокчейнами. Мы видим SDK как напоминающий NPM фреймворк для разработки безопасных блокчейн-приложений поверх [Tendermint](https://github.com/tendermint/tendermint). Построенные с помощью SDK блокчейны состоят из совместимых друг с другом модулей, и большинство из них находятся в свободном доступе. Создать модуль для Cosmos SDK может любой разработчик, а для интеграции уже существующих модулей достаточно импортировать их в свое приложение. Cosmos SDK построен на системе «разрешений», которая позволяет разработчикам лучше контролировать взаимодействие между модулями. В общем, смарт-контракты ограничивают в отношении гибкости, суверенитета и производительности.
## Почему блокчейн для конкретного приложения?
Общепринятая парадигма в мире блокчейна предполагает существование виртуальной машины блокчейна, например Ethereum, и разработки децентрализованных приложений как набора смарт-контрактов поверх существующего блокчейна. Смарт-контракты могут быть удобны для создания «одноразовых» приложений, например для ICO, но плохо подходят для разработки сложных децентрализованных платформ.
[Блокчейны для конкретных приложений](./why-app-specific.md) работают в совершенно отличной от виртуальных машин парадигме. Такие блокчейны создаются под потребности конкретного приложения и разработчики имеют полную свободу в принятии технических решений для создания блокчейна, который позволит их приложению работать оптимально. Это позволяет избежать ограничений смарт-контрактов.
## Почему именно Cosmos SDK?
Cosmos SDK является наиболее полным фреймворком для создания блокчейнов для приложений. Есть ряд причин, которые помогут сделать выбор в пользу Cosmos SDK:
- В качестве движка консенсуса SDK по умолчанию использует [Tendermint Core](https://github.com/tendermint/tendermint) — проработанный BFT-движок, который пользуется широкой популярностью и фактически является «золотым стандартом» при построении Proof-of-Stake систем
- Исходный код SDK находится в свободном доступе, а модульная система позволяет разрабатывать блокчейн в виде отдельных совместимых друг с другом модулей. По мере роста экосистемы модулей, находящихся в свободном доступе, разработка сложных децентрализованных приложений будет становится еще проще.
- SDK построен на системе «разрешений» и большом опыте работы с вируальными машинами блокчейнов. Это делает Cosmos SDK очень безопасным фреймворком для создания блокчейнов.
- Самое важное: Cosmos SDK уже используется для создания работающих в продакшене блокчейнов. В качестве примеров можно привести [Cosmos Hub](https://hub.cosmos.network), [IRIS Hub](https://irisnet.org), [Binance Chain](https://docs.binance.org/), [Terra](https://terra.money/), [Lino](https://lino.network/) и многие другие проекты, которые находятся в стадии разработки, используют Cosmos SDK. Примеры использования можно посмотреть на [странице экосистемы](https://cosmos.network/ecosystem).
## Начало работы с Cosmos SDK
- Прочитайте об [архитектуре приложения](./sdk-app-architecture.md), разрабатываемого с помощью SDK.
- Узнайте, как с нуля создать блокчейн для вашего приложения в [пошаговом примере](https://cosmos.network/docs/tutorial).

View File

@ -1,97 +0,0 @@
---
order: 3
---
# Архитектура SDK-приложения
## Конечный автомат (state machine)
В ядре блокчейна находится [реплицированный детерминированный конечный автомат](https://en.wikipedia.org/wiki/State_machine_replication).
В информатике конечный автомат — это математическая абстракция, имеющая один вход, один выход и в каждый момент времени находящаяся в одном из множества состояний. **Состояние** описывает текущее состояние автомата, а **транзакции** описывают изменения текущего состояния.
Принимая в качестве входа состояние `S` и транзакцию `T`, автомат вернет новое состояние `S'`.
```
+--------+ +--------+
| | | |
| S +---------------->+ S' |
| | apply(T) | |
+--------+ +--------+
```
На практике транзакции сгруппированы в блоки, что позволяет сделать процесс более эффективным. Принимая в качестве входа состояние `S` и блок транзакций `B`, автомат вернет новое состояние `S'`.
```
+--------+ +--------+
| | | |
| S +----------------------------> | S' |
| | For each T in B: apply(T) | |
+--------+ +--------+
```
В контексте блокчейна, конечный автомат является детерминированным. Детерминированность означает, что применение к одному состоянию одной и той же последовательности транзакций всегда приводит к одному и тому же конечному состоянию.
Cosmos SDK дает максимальную гибкость в определеини состояния разрабатываемого приложения, типов транзакций и функций изменения состояния. Процесс разработки конечного автомата с помощью SDK будет описан в следующих главах. В начале рассмотрим процесс репликации с использованием **Tendermint**.
### Tendermint
Единственное, что нужно сделать разработчику, это описать конечный автомат с помощью Cosmos SDK. Процесс репликации через сеть берет на себя [*Tendermint*](https://tendermint.com/docs/introduction/what-is-tendermint.html).
```
^ +-------------------------------+ ^
| | | | Built with Cosmos SDK
| | Конечный автомат = приложение | |
| | | v
| +-------------------------------+
| | | ^
Нода блокчейна | | Консенсус | |
| | | |
| +-------------------------------+ | Tendermint Core
| | | |
| | Сеть | |
| | | |
v +-------------------------------+ v
```
Tendermint — это независимая от разрабатываемого приложения программа, ответственная за **сетевое взаимодействие** и **консенсус**. На практике это означает, что Tendermint отвечает за передачу и упорядочивание байтов транзакций. [Tendermint Core](https://tendermint.com/docs/introduction/what-is-tendermint.html) основан на алгоритме Byzantine-Fault-Tolerant (BFT) для достижения консенсуса о порядке транзакций.
Алгоритм консенсуса Tendermint работает на множестве специальных нод, называемых **валидаторами**. Валидаторы отвечают за добавление блоков транзакций в блокчейн. В момент работы с каждым блоком существует множество валидаторов `V`. Из этого множества алгоритмом выбирается валидатор, который будет предлагать следующий блок. Блок считается валидным, если более чем две трети валидаторов подписали *[prevote](https://tendermint.com/docs/spec/consensus/consensus.html#prevote-step-height-h-round-r)* и *[precommit](https://tendermint.com/docs/spec/consensus/consensus.html#precommit-step-height-h-round-r)*, и все транзакции в блоке валидны. Множество валидаторов может быть изменено в правилах, по которым работает конечный автомат. Узнать подробнее о работе алгоритма можно на [следующей странице](https://tendermint.com/docs/introduction/what-is-tendermint.html#consensus-overview).
Основной частью приложения, написанного с помощью Cosmos SDK, является фоновая программа (daemon), которая запускается на каждой ноде. Если в множестве валидаторов злоумышленниками являются менее одной трети валидаторов, то при запросе каждая нода должна получить одно и то же состояние в данный момент времени.
## ABCI
Tendermint передает приложению транзакции по сети через интерфейс [ABCI](https://github.com/tendermint/tendermint/tree/master/abci), который приложение должно реализовать.
```
+---------------------+
| |
| Приложение |
| |
+--------+---+--------+
^ |
| | ABCI
| v
+--------+---+--------+
| |
| |
| Tendermint |
| |
| |
+---------------------+
```
**Tendermint работает с байтами транзакций**, но не имеет информации о том, что эти байты означают. Все, что делает Tendermint, — это детерминировано упорядочивает эти байты. Tendermint передает байты приложению через ABCI и ожидает получить код возврата, который содержит сообщение о том, успешно ли были обработаны транзакции.
Наиболее важные типы сообщений ABCI:
- `CheckTx`: после принятия транзации Tendermint Core, транзакция передается приложению для проверки базовых требований. `CheckTx` используется для защиты мемпула (mempool) нод от спама. Предварительный обработчик (Ante Handler) используется для выполнения последовательности валидационных шагов, таких как проверка вознаграждений (fees) и подписей валидаторов. Если транзакция валидна, она добавляется в [mempool](https://tendermint.com/docs/spec/reactors/mempool/functionality.html#mempool-functionality) и транслируется другим нодам. Следует заметить, что `CheckTx` не обрабатывает транзакции, то есть изменения состояния не происходит, потому что транзакции на этом этапе еще не были включены в блок.
- `DeliverTx`: когда Tendermint Core принимает [валидный блок](https://tendermint.com/docs/spec/blockchain/blockchain.html#validation), каждая транзакция в данном блоке передается приложению через `DeliverTx` для обработки. Именно на этом этапе происходит изменение состояния. Обработчик (Ante Handler) выполняется повторно вместе с остальными обработчиками для каждого сообщения в транзакции.
- `BeginBlock` / `EndBlock`: эти сообщения выполняются в начале и конце блока, вне зависимости от того, содержит блок транзакции или нет. Это удобно, если необходимо автоматически выполнить код. Следует заметить, что процессы, требующие больших вычислительных ресурсов, могут замедлить работу блокчейна или вовсе привести к остановке в случае бесконечного цикла.
Более подробный обзор методов и типов ABCI находится на [следующей странице](https://tendermint.com/docs/spec/abci/abci.html#overview).
Построенное на Tendermint приложение должно реализовать интерфейс ABCI для взаимодействия с локально запущенной программой Tendermint. К счастью, реализовывать интерфейс самостоятельно не нужно, потому что в составе Cosmos SDK уже есть его реализация в виде [baseapp](./sdk-design.md#baseapp).

View File

@ -1,98 +0,0 @@
---
order: 4
---
# Обзор дизайна Cosmos SDK
Cosmos SDK - это фреймворк, который облегчает разработку безопасных конечных автоматов поверх движка консенсуса Tendermint. По своей сути, SDK представляет собой реализацию ABCI на языке программирования Go. Он поставляется с хранилищем данных `multistore` и маршрутизатором для обработки транзакций `router`.
Далее представлен алгоритм обработки транзакций в приложении на Cosmos SDK при передаче транзакций из Tendermint через `DeliverTx`:
1. Декодируйте `transactions`, полученные от механизма консенсуса Tendermint (помните, что Tendermint работает только с `[]bytes`).
2. Извлеките `messages` из `transactions` и выполните базовые проверки.
3. Направьте каждое сообщение в соответствующий модуль для его обработки.
4. Сохраните изменения состояния.
Приложение также позволяет генерировать транзакции, кодировать их и передавать их базовому движку Tendermint для их трансляции.
## `baseapp`
`baseApp` — это базовая реализация ABCI в Cosmos SDK. Она поставляется с модулем `router` для маршрутизации транзакций в соответствующий модуль. Файл `app.go` вашего приложения будет определять ваш тип `app`, который будет встраивать `baseapp`. Таким образом, ваш пользовательский тип `app` будет автоматически наследовать все ABCI-методы `baseapp`. Пример этого в [туториале по созданию приложения с помощью SDK] (https://github.com/cosmos/sdk-application-tutorial/blob/master/app.go#L27).
Цель `baseapp`: обеспечить безопасный интерфейс между хранилищем и расширяемым конечным автоматом, в то же время определяя как можно меньше о конечном компьютере (соответствуя ABCI).
УЗнать больше о `baseapp` можно [здесь](../concepts/baseapp.md).
## `multistore`
В составе Cosmos SDK есть хранилище для сохранения состояния. Это хранилище позволяет разработчикам создавать любое количество [`KVStores`](https://github.com/blocklayerhq/chainkit). Эти `KVStores` принимают только `[] byte` в качестве значения, и поэтому любая пользовательская структура должна быть собрана с помощью [go-amin](https://github.com/tendermint/go-amino) перед сохранением.
Абстракция в виде этого хранилища используется для разделения состояния на отдельные части, каждый из которых управляется своим собственным модулем. Получить больше информации о `multistore` можно [здесь](../concepts/store.md).
## Модули
Основное преимуществе Cosmos SDK заключается в его модульности. Приложения SDK создаются путем объединения набора совместимых модулей. Каждый модуль определяет подмножество состояния и содержит свой собственный обработчик сообщений/транзакций, в то время как SDK отвечает за маршрутизацию каждого сообщения в соответствующий модуль.
Вот упрощенное представление о том, как транзакция обрабатывается приложением каждого полной ноды, когда она получена в валидном блоке:
```
+
|
| Транзакция ретранслируется из движка Tendermint
| полной ноды в приложение ноды через DeliverTx
|
|
|
+---------------------v--------------------------+
| Приложение |
| |
| Используя методы baseapp, декодируй Tx, |
| извлеки сообщение и маршрутизируй его |
| |
+---------------------+--------------------------+
|
|
|
+---------------------------+
|
|
| Сообщение отправлено
| в нужный модуль
| для обработки
|
|
+----------------+ +---------------+ +----------------+ +------v----------+
| | | | | | | |
| AUTH MODULE | | BANK MODULE | | STAKING MODULE | | GOV MODULE |
| | | | | | | |
| | | | | | | Обработай сооб.,|
| | | | | | | обнови состояние|
| | | | | | | |
+----------------+ +---------------+ +----------------+ +------+----------+
|
|
|
|
+--------------------------+
|
| Верни результат в Tendermint
| (0=Ok, 1=Err)
v
```
Каждый модуль можно рассматривать как самостоятельный конечный автомат. Разработчикам необходимо определить подмножество состояния, обрабатываемого модулем, а также настраиваемые типы сообщений, которые изменяют состояние (следует отметить, что `messages` извлекаются из `transactions` с использованием `baseapp`). В общем, каждый модуль создает свой собственный `KVStore` в `multistore`, чтобы сохранить подмножество состояния, которое он определяет. Большинству разработчиков потребуется доступ к другим сторонним модулям при создании своих собственных модулей. Учитывая, что Cosmos-SDK является открытой платформой, некоторые модули могут быть вредоносными, что означает необходимость создания правил безопасности для определения межмодульных взаимодействий. Эти правила основаны на [object-capabilities](../core/ocap.md). На практике это означает, что вместо того, чтобы каждый модуль вел список контроля доступа для других модулей, каждый модуль реализует специальные объекты, называемые хранителями, которые могут быть переданы другим модулям для предоставления предварительно определенного набора возможностей.
Модули SDK определены в директории `x/` SDK. Основные модули в составе Cosmos SDK:
- `x/auth`: используется для управления учетными записями и подписями.
- `x/bank`: используется для создания и передачи токенов.
- `x/staking` и `x/slashing`: используется для создания блокчейнов Proof-of-Stake.
В дополнение к уже существующим модулям в `x/`, которые каждый может использовать в своем приложении, SDK позволяет [создавать собственные модули](https://cosmos.network/docs/tutorial/keeper.html).
### Далее, узнайте больше о модели безопасности Cosmos SDK, [ocap](./ocap.md)

View File

@ -1,89 +0,0 @@
---
order: 2
---
# Блокчейн для конкретного приложения
В этом разделе описаны особенности блокчейнов для конкретных приложений и почему разработчики могут сделать выбор в пользу них, а не смарт-контрактов.
## Почему блокчейн для конкретного приложения
Вместо создания децентрализованного приложения поверх существующего блокчейна, такого как Ethereum, разработчики могут написать собственный блокчейн с нуля, который настроен для работы с одним конкретным приложением. Это предполагает создание полного клиента, легкого клиента, необходимых интерфейсов (CLI, REST...) для взаимодействия с нодами.
```
^ +-------------------------------+ ^
| | | | Built with Cosmos SDK
| | Конечный автомат = приложение | |
| | | v
| +-------------------------------+
| | | ^
Нода блокчейна | | Консенсус | |
| | | |
| +-------------------------------+ | Tendermint Core
| | | |
| | Сеть | |
| | | |
v +-------------------------------+ v
```
## Какие недостатки есть у смарт-контрактов?
Блокчейны, основанные на виртуальных машинах, такие как Ethereum реализовали потребность в большей программируемости блокчейнов еще в 2014 году. В то время варианты доступные для создания децентрализованных приложений были ограничены. Большинство разработчиков строили свои приложения, используя сложный и ограниченный в возможностях скриптовый язык Биткоина, или же работая над форком исходного кода Биткоина, модифицировать который под свои потребности было сложно.
Блокчейны, основанные на виртуальных машинах, имели новое ценностное предложение. Их конечный автомат включает в себя виртуальную машину, способную интерпретировать Тьюринг-полные программы, называемые смарт-контрактами. Эти умные контракты хорошо подходили для «одноразовых» программ, таких как ICO, однако плохо для построения сложных децентрализованных платформ:
- Смарт-контракты обычно разрабатываются с использованием языков программирования, которые интерпретирует виртуальная машина. Эти языки часто действуют в рамках ограничений виртуальной машины. К примеру, виртуальная машина Ethereum (EVM) не позволяет разработчикам реализовать автоматическое исполнение кода. Разработчики также ограничены системой счетов EVM, и ограниченным множеством функций, необходимых для криптографии. Это примеры думонстрируют ограниченную **гибкость** смарт-контрактов.
- Все смарт-контракты выполняются на одной и той же виртуальной машине. Это означает, что они конкурируют за ресурсы, что существенного ограничивает производительность. Даже если конечный автомат будет разделен на несколько множеств (например, с помощью шардинга), смарт-контракты все равно выполняются на виртуальной машине. Это ведет к низкой производительности в сравнении с нативным приложением, написанным на уровне самого конечного автомата. Наши тесты показывают 10-и кратное увеличение производительности в ситуациях без виртуальной машины.
- Другая проблема связана с тем, что все смарт-контракты выполняются в одном окружении, что приводит к ограниченному **суверенитету**. Децентрализованное приложение — это экосистема, в которой участвуют несколько игроков. Если приложение построено на виртуальной машины общего блокчейна, эти игроки имеют очень ограниченный суверенитет над ним. Если в приложении есть ошибка, с этим мало что можно сделать.
Специфичные для приложения блокчейны призваны устранить эти недостатки.
### Преимущества специфичных блокчейнов
### Гибкость
Специфичные блокчейны предоставляют максимальную гибкость для разработчиков.
- В блокчейнах, построенных на Cosmos, конечный автомат типично соединен с лежащим в основе движком консенсуса через интерфейс ABCI. Этот интерфейс можно использовать из любого языка программирования, это означает, что разработчик может использовать предпочтительный язык для создания своего приложения.
- ABCI позволяет сменить движок консенсуса для своего блокчейна. На сегодняшний день только Tendermint готов для использования, но в будущем появятся и другие.
- Разработчики имеют полную свободу действий при выборе количества валидаторов, желаемой производительности, безопасности, DB или IAVL-деревьев для хранения, UTXO...
- Разработчики могут реализовать автоматическое исполнение кода. В Cosmos SDK код может автоматически запускаться в начале и конце каждого блока. У разработчика также остается выбор криптографической библиотеки, используемой в приложении.
### Производительность
Производительность децентрализованных приложений, построенных на основе смарт-контрактов, всегда ограничена окружением, в котором они работают. Построение приложения на своем собственном блокчейне позволяет оптимизировать производительность благодаря следующим преимуществам:
- Разработчики могут выбрать более современный движок консенсуса, например, Tendermint BFT. В сравнении с Proof-of-Work, используемым в большинстве виртуальных машин блокчейнов, Tendermint позволяет получить высокую пропускную способность.
- Собственный блокчейн хранит данные одного конкретного приложения, поэтому этому приложению не приходится конкурировать за ресурсы с другими. Это не так на большинстве блокчейнов, в которых смарт-контракты конкурируют за вычислительную мощность и пространство для хранения данных.
- Даже если виртуальная машина блокчейна дает возможность шардинга и имеет эффективный алгоритм консенсуса, производительность будет ограничена самой виртуальной машиной: необходимость интерпретации транзакций виртуальной машиной существенно увеличивает требуюмую вычислительную мощность для из обработки.
### Безопасность
Безопасность сложно охарактеризовать количественно, и степень безопасности системы различается в зависимости от платформы. Тем не менее блокчкейн для конкретного приложения имеет ряд преимуществ:
- Разработчики могут выбрать надежный и современный язык программирования, такой как, например, Go, для создания блокчейна, а не язык смарт-контрактов.
- Разработчики не ограничены набором криптографических функций, доступных виртуальной машине. Они могут использовать свои функции и необходимые им библиотеки, которые прошли аудит.
- Разработчикам не приходится переживать о безопасности самой виртуальной машины, что упрощает работу с безопаностью приложения.
### Независимость
Одно из основных преимуществ собственных блокчейнов заключается в их независимости. Децентрализованное приложение — это экосистема, которая включает множество акторов: пользователей, разработчиков, сторонних сервисов и прочих. Когда разработчики опираются на блокчейн виртуальной машины, где сосуществуют многие децентрализованные приложения, сообщество приложений отличается от сообщества блокчейна. Если появляется ошибка или требуется новая функция, сообщество приложения не имеет достаточных прав, чтобы внести измененения в код блокчейна. Если сообщество блокчейна отказывается самостоятельно исправлять ошибки, ничего не может произойти.
Основная проблема здесь заключается в том, что управление приложением и управление сетью не согласованы. Эта проблема решается с помощью блокчейнов для конкретных приложений. Поскольку специфичные для приложения блокчейны специализируются на работе с одним приложением, сообщество приложения имеет полный контроль над всей системой. Это гарантирует, что действия сообщества не будут заблокированы, если будет обнаружена ошибка, и что оно имеет полную свободу выбора в траектории своего развития.
## Начните создавать свой блокчейн для конкретного приложения уже сегодня
Очевидно, что собственные блокчейны имеют массу преимуществ. Cosmos SDK делает их разработку проще как никогда. Создайте свой блокчейн!
- Узнайте больше об [архитектуре](./ sdk-app-Architecture) приложения, построенного с помощью SDK.
- Узнайте, как создать блокчейн для конкретного приложения с нуля, с помощью [SDK tutorial](https://cosmos.network/docs/tutorial)

View File

@ -1,11 +0,0 @@
---
parent:
order: false
---
# RU
::: warning
**DEPRECATED**
This documentation is not complete and it's outdated. Please use the English version.
:::

3
docs/zh/README.md Normal file
View File

@ -0,0 +1,3 @@
# Cosmos SDK Documentation (Chinese)
A Chinese translation of the Cosmos SDK documentation is not available for this version. If you would like to help with translating, please see [Internationalization](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOCS_README.md#internationalization). A `v0.39` version of the documentation can be found [here](https://docs.cosmos.network/v0.39/cn/).