certusone
/
cosmos-sdk
mirror of https://github.com/certusone/cosmos-sdk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Improve markdownlint configuration (#11104) 

## Description

Closes: #9404



---

### 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 [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] added `!` to the type prefix if API or client breaking change
- [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
- [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules)
- [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing)
- [ ] added a changelog entry to `CHANGELOG.md`
- [ ] included comments for [documenting Go code](https://blog.golang.org/godoc)
- [ ] updated the relevant documentation or specification
- [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 [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] confirmed `!` in the type prefix if API or client breaking change
- [ ] confirmed all author checklist items have been addressed 
- [ ] reviewed state machine logic
- [ ] reviewed API design and naming
- [ ] reviewed documentation is accurate
- [ ] reviewed tests and test coverage
- [ ] manually tested (if applicable)
This commit is contained in:
Julien Robert 2022-02-10 13:07:01 +01:00 committed by GitHub
parent b1f9a117f7
commit 58597139fa
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
212 changed files with 3792 additions and 3755 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
.markdownlint.json
View File

@ -1,17 +1,11 @@
{
"default": true,
"MD001": false,
"MD004": false,
"MD004": {"style": "asterisk"},
"MD007": { "indent": 4 },
"MD013": false,
"MD024": { "siblings_only": true },
"MD025": false,
"MD026": { "punctuation": ".,;:" },
"MD029": false,
"MD033": false,
"MD034": false,
"MD036": false,
"MD040": false,
"MD041": false,
"no-hard-tabs": false
}
"no-hard-tabs": false,
"whitespace": false
}

2
.markdownlintignore
View File

@ -1,2 +1,2 @@
CHANGELOG.md
docs/node_modules
/README.md

2138
CHANGELOG.md
View File

File diff suppressed because it is too large Load Diff

108
CODING_GUIDELINES.md
View File

@ -4,32 +4,32 @@ This document is an extension to [CONTRIBUTING](./CONTRIBUTING.md) and provides
## API & Design
+ Code must be well structured:
+ packages must have a limited responsibility (different concerns can go to different packages),
+ types must be easy to compose,
+ think about maintainbility and testability.
+ "Depend upon abstractions, [not] concretions".
+ Try to limit the number of methods you are exposing. It's easier to expose something later than to hide it.
+ Take advantage of `internal` package concept.
+ Follow agreed-upon design patterns and naming conventions.
+ publicly-exposed functions are named logically, have forward-thinking arguments and return types.
+ Avoid global variables and global configurators.
+ Favor composable and extensible designs.
+ Minimize code duplication.
+ Limit third-party dependencies.
* Code must be well structured:
* packages must have a limited responsibility (different concerns can go to different packages),
* types must be easy to compose,
* think about maintainbility and testability.
* "Depend upon abstractions, [not] concretions".
* Try to limit the number of methods you are exposing. It's easier to expose something later than to hide it.
* Take advantage of `internal` package concept.
* Follow agreed-upon design patterns and naming conventions.
* publicly-exposed functions are named logically, have forward-thinking arguments and return types.
* Avoid global variables and global configurators.
* Favor composable and extensible designs.
* Minimize code duplication.
* Limit third-party dependencies.
Performance:
+ Avoid unnecessary operations or memory allocations.
* Avoid unnecessary operations or memory allocations.
Security:
+ Pay proper attention to exploits involving:
+ gas usage
+ transaction verification and signatures
+ malleability
+ code must be always deterministic
+ Thread safety. If some functionality is not thread-safe, or uses something that is not thread-safe, then clearly indicate the risk on each level.
* Pay proper attention to exploits involving:
* gas usage
* transaction verification and signatures
* malleability
* code must be always deterministic
* Thread safety. If some functionality is not thread-safe, or uses something that is not thread-safe, then clearly indicate the risk on each level.
## Acceptance tests
@ -43,14 +43,14 @@ UAT should be revisited at each stage of the product development:
![acceptance-tests.png](./docs/assets/acceptance-tests.png)
### Why Acceptance Testing?
### Why Acceptance Testing
- Automated acceptance tests catch serious problems that unit or component test suites could never catch.
- Automated acceptance tests deliver business value the users are expecting as they test user scenarios.
- Automated acceptance tests executed and passed on every build help improve the software delivery process.
- Testers, developers, and customers need to work closely to create suitable automated acceptance test suites.
* Automated acceptance tests catch serious problems that unit or component test suites could never catch.
* Automated acceptance tests deliver business value the users are expecting as they test user scenarios.
* Automated acceptance tests executed and passed on every build help improve the software delivery process.
* Testers, developers, and customers need to work closely to create suitable automated acceptance test suites.
### How to define Acceptance Test?
### How to define Acceptance Test
The best way to define AT is by starting from the user stories and think about all positive and negative scenarios a user can perform.
@ -58,9 +58,9 @@ Product Developers should collaborate with stakeholders to define AT. Functional
A good pattern for defining AT is listing scenarios with [GIVEN-WHEN-THEN](https://martinfowler.com/bliki/GivenWhenThen.html) format where:
- **GIVEN**: A set of initial circumstances (e.g. bank balance)
- **WHEN**: Some event happens (e.g. customer attempts a transfer)
- **THEN**: The expected result as per the defined behavior of the system
* **GIVEN**: A set of initial circumstances (e.g. bank balance)
* **WHEN**: Some event happens (e.g. customer attempts a transfer)
* **THEN**: The expected result as per the defined behavior of the system
In other words: we define a use case input, current state and the expected outcome. Example:
@ -79,9 +79,9 @@ In other words: we define a use case input, current state and the expected outco
*Reference: [writing acceptance tests](https://openclassrooms.com/en/courses/4544611-write-agile-documentation-user-stories-acceptance-tests/4810081-writing-acceptance-tests)*.
### How and where to add acceptance tests?
### How and where to add acceptance tests
Acceptance tests are written in the Markdown format, using the scenario template described above, and be part of the specification (`xx_test.md` file in _spec_ directory). Example: (`eco-credits/spec/06.test.md`)[https://github.com/regen-network/regen-ledger/blob/7297783577e6cd102c5093365b573163680f36a1/x/ecocredit/spec/06_tests.md]
Acceptance tests are written in the Markdown format, using the scenario template described above, and be part of the specification (`xx_test.md` file in *spec* directory). Example: [`eco-credits/spec/06.test.md`](https://github.com/regen-network/regen-ledger/blob/7297783577e6cd102c5093365b573163680f36a1/x/ecocredit/spec/06_tests.md).
Acceptance tests should be defined during the design phase or at an early stage of development. Moreover, they should be defined before writing a module architecture - it will clarify the purpose and usage of the software.
Automated tests should cover all acceptance tests scenarios.
@ -90,11 +90,11 @@ Automated tests should cover all acceptance tests scenarios.
Make sure your code is well tested:
+ Provide unit tests for every unit of your code if possible. Unit tests are expected to comprise 70%-80% of your tests.
+ Describe the test scenarios you are implementing for integration tests.
+ Create integration tests for queries and msgs.
+ Use both test cases and property / fuzzy testing. We use the [rapid](pgregory.net/rapid) Go library for property-based and fuzzy testing.
+ Do not decrease code test coverage. Explain in a PR if test coverage is decreased.
* Provide unit tests for every unit of your code if possible. Unit tests are expected to comprise 70%-80% of your tests.
* Describe the test scenarios you are implementing for integration tests.
* Create integration tests for queries and msgs.
* Use both test cases and property / fuzzy testing. We use the [rapid](pgregory.net/rapid) Go library for property-based and fuzzy testing.
* Do not decrease code test coverage. Explain in a PR if test coverage is decreased.
We expect tests to use `require` or `assert` rather than `t.Skip` or `t.Fail`,
unless there is a reason to do otherwise.
@ -122,24 +122,24 @@ for tcIndex, tc := range cases {
We are forming a QA team that will support the core Cosmos SDK team and collaborators by:
- Improving the Cosmos SDK QA Processes
- Improving automation in QA and testing
- Defining high-quality metrics
- Maintaining and improving testing frameworks (unit tests, integration tests, and functional tests)
- Defining test scenarios.
- Verifying user experience and defining a high quality.
- We want to have **acceptance tests**! Document and list acceptance lists that are implemented and identify acceptance tests that are still missing.
- Acceptance tests should be specified in `acceptance-tests` directory as Markdown files.
- Supporting other teams with testing frameworks, automation, and User Experience testing.
- Testing chain upgrades for every new breaking change.
- Defining automated tests that assure data integrity after an update.
* Improving the Cosmos SDK QA Processes
* Improving automation in QA and testing
* Defining high-quality metrics
* Maintaining and improving testing frameworks (unit tests, integration tests, and functional tests)
* Defining test scenarios.
* Verifying user experience and defining a high quality.
* We want to have **acceptance tests**! Document and list acceptance lists that are implemented and identify acceptance tests that are still missing.
* Acceptance tests should be specified in `acceptance-tests` directory as Markdown files.
* Supporting other teams with testing frameworks, automation, and User Experience testing.
* Testing chain upgrades for every new breaking change.
* Defining automated tests that assure data integrity after an update.
Desired outcomes:
- QA team works with Development Team.
- QA is happening in parallel with Core Cosmos SDK development.
- Releases are more predictable.
- QA reports. Goal is to guide with new tasks and be one of the QA measures.
* QA team works with Development Team.
* QA is happening in parallel with Core Cosmos SDK development.
* Releases are more predictable.
* QA reports. Goal is to guide with new tasks and be one of the QA measures.
As a developer, you must help the QA team by providing instructions for User Experience (UX) and functional testing.
@ -147,6 +147,6 @@ As a developer, you must help the QA team by providing instructions for User Exp
Once the AT are defined, the QA team will have an overview of the behavior a user can expect and:
- validate the user experience will be good
- validate the implementation conforms the acceptance tests
- by having a broader overview of the use cases, QA team should be able to define **test suites** and test data to efficiently automate Acceptance Tests and reuse the work.
* validate the user experience will be good
* validate the implementation conforms the acceptance tests
* by having a broader overview of the use cases, QA team should be able to define **test suites** and test data to efficiently automate Acceptance Tests and reuse the work.

125
CONTRIBUTING.md
View File

@ -1,20 +1,27 @@
# Contributing
- [Contributing](#contributing)
- [Dev Calls](#dev-calls)
- [Architecture Decision Records (ADR)](#architecture-decision-records-adr)
- [Development Procedure](#development-procedure)
- [Testing](#testing)
- [Pull Requests](#pull-requests)
- [Pull Request Templates](#pull-request-templates)
- [Requesting Reviews](#requesting-reviews)
- [Updating Documentation](#updating-documentation)
- [Dependencies](#dependencies)
- [Protobuf](#protobuf)
- [Branching Model and Release](#branching-model-and-release)
- [PR Targeting](#pr-targeting)
- [Code Owner Membership](#code-owner-membership)
- [Concept & Feature Approval Process](#concept--feature-approval-process)
* [Contributing](#contributing)
* [Teams Dev Calls](#teams-dev-calls)
* [Architecture Decision Records (ADR)](#architecture-decision-records-adr)
* [Development Procedure](#development-procedure)
* [Testing](#testing)
* [Pull Requests](#pull-requests)
* [Pull Request Templates](#pull-request-templates)
* [Requesting Reviews](#requesting-reviews)
* [Updating Documentation](#updating-documentation)
* [Dependencies](#dependencies)
* [Protobuf](#protobuf)
* [Branching Model and Release](#branching-model-and-release)
* [PR Targeting](#pr-targeting)
* [Code Owner Membership](#code-owner-membership)
* [Concept & Feature Approval Process](#concept--feature-approval-process)
* [Strategy Discovery](#strategy-discovery)
* [Concept Approval](#concept-approval)
* [Time Bound Period](#time-bound-period)
* [Approval Committee & Decision Making](#approval-committee--decision-making)
* [Committee Members](#committee-members)
* [Committee Criteria](#committee-criteria)
* [Implementation & Release Approval](#implementation--release-approval)
Thank you for considering making contributions to the Cosmos SDK and related repositories!
@ -23,13 +30,11 @@ discussion or proposing code changes. To ensure a smooth workflow for all
contributors, the general procedure for contributing has been established:
1. Start by browsing [new issues](https://github.com/cosmos/cosmos-sdk/issues) and [discussions](https://github.com/cosmos/cosmos-sdk/discussions). If you are looking for something interesting or if you have something in your mind, there is a chance it was has been discussed.
- Looking for a good place to start contributing? How about checking out some [good first issues](https://github.com/cosmos/cosmos-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)?
* Looking for a good place to start contributing? How about checking out some [good first issues](https://github.com/cosmos/cosmos-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)?
2. Determine whether a GitHub issue or discussion is more appropriate for your needs:
1. If want to propose something new that requires specification or an additional design, or you would like to change a process, start with a [new discussion](https://github.com/cosmos/cosmos-sdk/discussions/new). With discussions, we can better handle the design process using discussion threads. A discussion usually leads to one or more issues.
2. If the issue you want addressed is a specific proposal or a bug, then open a [new issue](https://github.com/cosmos/cosmos-sdk/issues/new/choose).
3. Review existing [issues](https://github.com/cosmos/cosmos-sdk/issues) to find an issue you'd like to help with.
1. If want to propose something new that requires specification or an additional design, or you would like to change a process, start with a [new discussion](https://github.com/cosmos/cosmos-sdk/discussions/new). With discussions, we can better handle the design process using discussion threads. A discussion usually leads to one or more issues.
2. If the issue you want addressed is a specific proposal or a bug, then open a [new issue](https://github.com/cosmos/cosmos-sdk/issues/new/choose).
3. Review existing [issues](https://github.com/cosmos/cosmos-sdk/issues) to find an issue you'd like to help with.
3. Participate in thoughtful discussion on that issue.
4. If you would like to contribute:
1. Ensure that the proposal has been accepted.
@ -55,10 +60,10 @@ The important development announcements are shared on [Discord](https://discord.
To synchronize we have few major meetings:
+ Architecture calls: bi-weekly on Fridays at 14:00 UTC (alternating with the grooming meeting below).
+ Grooming / Planning: bi-weekly on Fridays at 14:00 UTC (alternating with the architecture meeting above).
+ Cosmos Community SDK Development Call on the last Wednesday of every month at 17:00 UTC.
+ Cosmos Roadmap Prioritization every 4 weeks on Tuesday at 15:00 UTC (limited participation).
* Architecture calls: bi-weekly on Fridays at 14:00 UTC (alternating with the grooming meeting below).
* Grooming / Planning: bi-weekly on Fridays at 14:00 UTC (alternating with the architecture meeting above).
* Cosmos Community SDK Development Call on the last Wednesday of every month at 17:00 UTC.
* Cosmos Roadmap Prioritization every 4 weeks on Tuesday at 15:00 UTC (limited participation).
If you would like to join one of those calls, then please contact us on [Discord](https://discord.com/invite/cosmosnetwork) or reach out directly to Cory Levinson from Regen Network (cory@regen.network).
@ -68,22 +73,22 @@ When proposing an architecture decision for the Cosmos SDK, please start by open
## Development Procedure
- The latest state of development is on `master`.
- `master` must never fail `make lint test test-race`.
- No `--force` onto `master` (except when reverting a broken commit, which should seldom happen).
- Create a branch to start a wok:
- Fork the repo (core developers must create a branch directly in the Cosmos SDK repo),
* The latest state of development is on `master`.
* `master` must never fail `make lint test test-race`.
* No `--force` onto `master` (except when reverting a broken commit, which should seldom happen).
* Create a branch to start a wok:
* Fork the repo (core developers must create a branch directly in the Cosmos SDK repo),
branch from the HEAD of `master`, make some commits, and submit a PR to `master`.
- For core developers working within the `cosmos-sdk` repo, follow branch name conventions to ensure a clear
* For core developers working within the `cosmos-sdk` repo, follow branch name conventions to ensure a clear
ownership of branches: `{moniker}/{issue#}-branch-name`.
- See [Branching Model](#branching-model-and-release) for more details.
- Be sure to run `make format` before every commit. The easiest way
* See [Branching Model](#branching-model-and-release) for more details.
* Be sure to run `make format` before every commit. The easiest way
to do this is have your editor run it for you upon saving a file (most of the editors
will do it anyway using a pre-configured setup of the programming language mode).
Additionally, be sure that your code is lint compliant by running `make lint-fix`.
A convenience git `pre-commit` hook that runs the formatters automatically
before each commit is available in the `contrib/githooks/` directory.
- Follow the [CODING GUIDELINES](CODING_GUIDELINES.md), which defines criteria for designing and coding a software.
* Follow the [CODING GUIDELINES](CODING_GUIDELINES.md), which defines criteria for designing and coding a software.
Code is merged into master through pull request procedure.
@ -95,8 +100,8 @@ Tests can be executed by running `make test` at the top level of the Cosmos SDK
Before submitting a pull request:
- merge the latest master `git merge origin/master`,
- run `make lint test` to ensure that all checks and tests pass.
* merge the latest master `git merge origin/master`,
* run `make lint test` to ensure that all checks and tests pass.
Then:
@ -120,8 +125,8 @@ NOTE: when merging, GitHub will squash commits and rebase on top of the master.
There are three PR templates. The [default template](./.github/PULL_REQUEST_TEMPLATE.md) is for types `fix`, `feat`, and `refactor`. We also have a [docs template](./.github/PULL_REQUEST_TEMPLATE/docs.md) for documentation changes and an [other template](./.github/PULL_REQUEST_TEMPLATE/other.md) for changes that do not affect production code. When previewing a PR before it has been opened, you can change the template by adding one of the following parameters to the url:
- `template=docs.md`
- `template=other.md`
* `template=docs.md`
* `template=other.md`
### Requesting Reviews
@ -138,24 +143,24 @@ the case of minor changes to [docs](./.github/PULL_REQUEST_TEMPLATE/docs.md) or
for all checked items unless they have indicated otherwise by leaving their handle next to specific
items. In addition, use the following review explanations:
- `LGTM` without an explicit approval means that the changes look good, but you haven't thoroughly reviewed the reviewer checklist items.
- `Approval` means that you have completed some or all of the reviewer checklist items. If you only reviewed selected items, you must add your handle next to the items that you have reviewed. In addition, follow these guidelines:
- You must also think through anything which ought to be included but is not
- You must think through whether any added code could be partially combined (DRYed) with existing code
- You must think through any potential security issues or incentive-compatibility flaws introduced by the changes
- Naming must be consistent with conventions and the rest of the codebase
- Code must live in a reasonable location, considering dependency structures (for example, not importing testing modules in production code, or including example code modules in production code).
- If you approve the PR, you are responsible for any issues mentioned here and any issues that should have been addressed after thoroughly reviewing the reviewer checklist items in the pull request template.
- If you sat down with the PR submitter and did a pairing review, add this information in the `Approval` or your PR comments.
- If you are only making "surface level" reviews, submit notes as a `comment` review.
* `LGTM` without an explicit approval means that the changes look good, but you haven't thoroughly reviewed the reviewer checklist items.
* `Approval` means that you have completed some or all of the reviewer checklist items. If you only reviewed selected items, you must add your handle next to the items that you have reviewed. In addition, follow these guidelines:
* You must also think through anything which ought to be included but is not
* You must think through whether any added code could be partially combined (DRYed) with existing code
* You must think through any potential security issues or incentive-compatibility flaws introduced by the changes
* Naming must be consistent with conventions and the rest of the codebase
* Code must live in a reasonable location, considering dependency structures (for example, not importing testing modules in production code, or including example code modules in production code).
* If you approve the PR, you are responsible for any issues mentioned here and any issues that should have been addressed after thoroughly reviewing the reviewer checklist items in the pull request template.
* If you sat down with the PR submitter and did a pairing review, add this information in the `Approval` or your PR comments.
* If you are only making "surface level" reviews, submit notes as a `comment` review.
### Updating Documentation
If you open a PR on the Cosmos SDK, it is mandatory to update the relevant documentation in `/docs`.
- If your change relates to the core SDK (baseapp, store, ...), be sure to update the content in `docs/basics/`, `docs/core/` and/or `docs/building-modules/` folders.
- If your changes relate to the core of the CLI (not specifically to module's CLI/Rest), then modify the content in the `docs/run-node/` folder.
- If your changes relate to a module, then be sure to update the module's spec in `x/moduleName/docs/spec/`.
* If your change relates to the core SDK (baseapp, store, ...), be sure to update the content in `docs/basics/`, `docs/core/` and/or `docs/building-modules/` folders.
* If your changes relate to the core of the CLI (not specifically to module's CLI/Rest), then modify the content in the `docs/run-node/` folder.
* If your changes relate to a module, then be sure to update the module's spec in `x/moduleName/docs/spec/`.
When writing documentation, follow the [Documentation Writing Guidelines](./docs/DOC_WRITING_GUIDELINES.md).
@ -189,7 +194,7 @@ In order for imports to properly compile in your IDE, you may need to manually s
For example, in vscode your `.vscode/settings.json` should look like:
```
```json
{
"protoc": {
"options": [
@ -202,7 +207,7 @@ For example, in vscode your `.vscode/settings.json` should look like:
## Branching Model and Release
User-facing repos should adhere to the trunk based development branching model: https://trunkbaseddevelopment.com/. User branches should start with a user name, example: `{moniker}/{issue#}-branch-name`.
User-facing repos should adhere to the trunk based development branching model: <https://trunkbaseddevelopment.com/>. User branches should start with a user name, example: `{moniker}/{issue#}-branch-name`.
The Cosmos SDK repository is a [multi Go module](https://github.com/golang/go/wiki/Modules#is-it-possible-to-add-a-module-to-a-multi-module-repository) repository. It means that we have more than one Go module in a single repository.
@ -272,7 +277,7 @@ is broken up into three distinct stages: **Strategy Discovery**, **Concept Appro
* After proposal, a time bound period for Request for Comment (RFC) on ADRs commences
* ADRs are intended to be iterative, and may be merged into `master` while still in a `Proposed` status
**Time Bound Period**
#### Time Bound Period
* Once a PR for an ADR is opened, reviewers are expected to perform a first
review within 1 week of pull request being open
@ -286,20 +291,20 @@ the current state of its discussion.
If an ADR is taking longer than 4 weeks to reach a final conclusion, the **Concept Approval Committee**
should convene to rectify the situation by either:
- unanimously setting a new time bound period for this ADR
- making changes to the Concept Approval Process (as outlined here)
- making changes to the members of the Concept Approval Committee
* unanimously setting a new time bound period for this ADR
* making changes to the Concept Approval Process (as outlined here)
* making changes to the members of the Concept Approval Committee
**Approval Committee & Decision Making**
#### Approval Committee & Decision Making
In absence of general consensus, decision making requires 1/2 vote from the two members
of the **Concept Approval Committee**.
**Committee Members**
#### Committee Members
* Core Members: **Aaron** (Regen), **Bez** (IG)
**Committee Criteria**
#### Committee Criteria
Members must:

80
RELEASE_PROCESS.md
View File

@ -8,36 +8,36 @@ A _major release_ is an increment of the first number (eg: `v1.2` → `v2.0.0`)
Before making a new _major_ release we do beta and release candidate releases. For example, for release 1.0.0:
```
```text
v1.0.0-beta1 → v1.0.0-beta2 → ... → v1.0.0-rc1 → v1.0.0-rc2 → ... → v1.0.0
```
- Release a first beta version on the `master` branch and freeze `master` from receiving any new features. After beta is released, we focus on releasing the release candidate:
- finish audits and reviews
- kick off a large round of simulation testing (e.g. 400 seeds for 2k blocks)
- perform functional tests
- add more tests
- release new beta version as the bugs are discovered and fixed.
- After the team feels that the `master` works fine we create a `release/vY` branch (going forward known a release branch), where `Y` is the version number, with the patch part substituted to `x` (eg: 0.42.x, 1.0.x). Ensure the release branch is protected so that pushes against the release branch are permitted only by the release manager or release coordinator.
- **PRs targeting this branch can be merged _only_ when exceptional circumstances arise**
- update the GitHub mergify integration by adding instructions for automatically backporting commits from `master` to the `release/vY` using the `backport/Y` label.
- In the release branch, prepare a new version section in the `CHANGELOG.md`
- All links must be link-ified: `$ python ./scripts/linkify_changelog.py CHANGELOG.md`
- Copy the entries into a `RELEASE_CHANGELOG.md`, this is needed so the bot knows which entries to add to the release page on GitHub.
- Create a new annotated git tag for a release candidate (eg: `git tag -a v1.1.0-rc1`) in the release branch.
- from this point we unfreeze master.
- the SDK teams collaborate and do their best to run testnets in order to validate the release.
- when bugs are found, create a PR for `master`, and backport fixes to the release branch.
- create new release candidate tags after bugs are fixed.
- After the team feels the release branch is stable and everything works, create a full release:
- update `CHANGELOG.md`.
- create a new annotated git tag (eg `git -a v1.1.0`) in the release branch.
- Create a GitHub release.
* Release a first beta version on the `master` branch and freeze `master` from receiving any new features. After beta is released, we focus on releasing the release candidate:
* finish audits and reviews
* kick off a large round of simulation testing (e.g. 400 seeds for 2k blocks)
* perform functional tests
* add more tests
* release new beta version as the bugs are discovered and fixed.
* After the team feels that the `master` works fine we create a `release/vY` branch (going forward known a release branch), where `Y` is the version number, with the patch part substituted to `x` (eg: 0.42.x, 1.0.x). Ensure the release branch is protected so that pushes against the release branch are permitted only by the release manager or release coordinator.
* **PRs targeting this branch can be merged _only_ when exceptional circumstances arise**
* update the GitHub mergify integration by adding instructions for automatically backporting commits from `master` to the `release/vY` using the `backport/Y` label.
* In the release branch, prepare a new version section in the `CHANGELOG.md`
* All links must be link-ified: `$ python ./scripts/linkify_changelog.py CHANGELOG.md`
* Copy the entries into a `RELEASE_CHANGELOG.md`, this is needed so the bot knows which entries to add to the release page on GitHub.
* Create a new annotated git tag for a release candidate (eg: `git tag -a v1.1.0-rc1`) in the release branch.
* from this point we unfreeze master.
* the SDK teams collaborate and do their best to run testnets in order to validate the release.
* when bugs are found, create a PR for `master`, and backport fixes to the release branch.
* create new release candidate tags after bugs are fixed.
* After the team feels the release branch is stable and everything works, create a full release:
* update `CHANGELOG.md`.
* create a new annotated git tag (eg `git -a v1.1.0`) in the release branch.
* Create a GitHub release.
Following _semver_ philosophy, point releases after `v1.0`:
- must not break API
- can break consensus
* must not break API
* can break consensus
Before `v1.0`, point release can break both point API and consensus.
@ -57,9 +57,9 @@ Point Release must follow the [Stable Release Policy](#stable-release-policy).
After the release branch has all commits required for the next patch release:
- update `CHANGELOG.md`.
- create a new annotated git tag (eg `git -a v1.1.0`) in the release branch.
- Create a GitHub release.
* update `CHANGELOG.md`.
* create a new annotated git tag (eg `git -a v1.1.0`) in the release branch.
* Create a GitHub release.
## Major Release Maintenance
@ -78,7 +78,7 @@ Only the following major release series have a stable release status:
### Patch Releases
Once a Cosmos-SDK release has been completed and published, updates for it are released under certain circumstances
and must follow the [Patch Release Procedure](CONTRIBUTING.md#patch-release-procedure)[Point Release Procedure].
and must follow the [Patch Release Procedure][CONTRIBUTING.md#patch-release-procedure](Point Release Procedure).
### Rationale
@ -109,11 +109,11 @@ ways in stable releases and `master` branch.
To smoothen the update to the latest stable release, the SDK includes a set of CLI commands for managing migrations between SDK versions, under the `migrate` subcommand. Only migration scripts between stable releases are included. For the current major release, and later, migrations are supported.
### What qualifies as a Stable Release Update (SRU)?
### What qualifies as a Stable Release Update (SRU)
* **High-impact bugs**
* Bugs that may directly cause a security vulnerability.
* *Severe regressions* from a Cosmos-SDK's previous release. This includes all sort of issues
* _Severe regressions_ from a Cosmos-SDK's previous release. This includes all sort of issues
that may cause the core packages or the `x/` modules unusable.
* Bugs that may cause **loss of user's data**.
* Other safe cases:
@ -123,7 +123,7 @@ To smoothen the update to the latest stable release, the SDK includes a set of C
features to smoothen the migration to successive releases.
* Relatively small yet strictly non-breaking CLI improvements.
### What does not qualify as SRU?
### What does not qualify as SRU
* State machine changes.
* Breaking changes in Protobuf definitions, as specified in [ADR-044](./docs/architecture/adr-044-protobuf-updates-guidelines.md).
@ -132,7 +132,7 @@ To smoothen the update to the latest stable release, the SDK includes a set of C
* CLI-breaking changes.
* Cosmetic fixes, such as formatting or linter warning fixes.
### What pull requests will be included in stable point-releases?
### What pull requests will be included in stable point-releases
Pull requests that fix bugs and add features that fall in the following categories do not require a **Stable Release Exception** to be granted to be included in a stable point-release:
@ -143,32 +143,32 @@ Pull requests that fix bugs and add features that fall in the following categori
* Non-breaking features that are strongly requested by the community.
* Non-breaking CLI improvements that are strongly requested by the community.
### What pull requests will NOT be automatically included in stable point-releases?
### What pull requests will NOT be automatically included in stable point-releases
As rule of thumb, the following changes will **NOT** be automatically accepted into stable point-releases:
* **State machine changes**.
* **Protobug-breaking changes**, as specified in [ADR-044](./docs/architecture/adr-044-protobuf-updates- guidelines.md).
* **Client-breaking changes**, i.e. changes that prevent gRPC, HTTP and RPC clients to continue interacting with the node without any change.
* **API-breaking changes**, i.e. changes that prevent client applications to *build without modifications* to the client application's source code.
* **API-breaking changes**, i.e. changes that prevent client applications to _build without modifications_ to the client application's source code.
* **CLI-breaking changes**, i.e. changes that require usage changes for CLI users.
In some circumstances, PRs that don't meet the aforementioned criteria might be raised and asked to be granted a *Stable Release Exception*.
In some circumstances, PRs that don't meet the aforementioned criteria might be raised and asked to be granted a _Stable Release Exception_.
### Stable Release Exception - Procedure
1. Check that the bug is either fixed or not reproducible in `master`. It is, in general, not appropriate to release bug fixes for stable releases without first testing them in `master`. Please apply the label [v0.43](https://github.com/cosmos/cosmos-sdk/milestone/26) to the issue.
2. Add a comment to the issue and ensure it contains the following information (see the bug template below):
* **[Impact]** An explanation of the bug on users and justification for backporting the fix to the stable release.
* A **[Test Case]** section containing detailed instructions on how to reproduce the bug.
* A **[Regression Potential]** section with a clear assessment on how regressions are most likely to manifest as a result of the pull request that aims to fix the bug in the target stable release.
* **[Impact]** An explanation of the bug on users and justification for backporting the fix to the stable release.
* A **[Test Case]** section containing detailed instructions on how to reproduce the bug.
* A **[Regression Potential]** section with a clear assessment on how regressions are most likely to manifest as a result of the pull request that aims to fix the bug in the target stable release.
3. **Stable Release Managers** will review and discuss the PR. Once *consensus* surrounding the rationale has been reached and the technical review has successfully concluded, the pull request will be merged in the respective point-release target branch (e.g. `release/v0.43.x`) and the PR included in the point-release's respective milestone (e.g. `v0.43.5`).
3. **Stable Release Managers** will review and discuss the PR. Once _consensus_ surrounding the rationale has been reached and the technical review has successfully concluded, the pull request will be merged in the respective point-release target branch (e.g. `release/v0.43.x`) and the PR included in the point-release's respective milestone (e.g. `v0.43.5`).
#### Stable Release Exception - Bug template
```
```md
#### Impact
Brief xplanation of the effects of the bug on users and a justification for backporting the fix to the stable release.

44
SECURITY.md
View File

@ -17,23 +17,23 @@ in for Tendermint and other lower-level libraries (eg. [IAVL](https://github.com
### Core packages
- [`/baseapp`](https://github.com/cosmos/cosmos-sdk/tree/master/baseapp)
- [`/crypto`](https://github.com/cosmos/cosmos-sdk/tree/master/crypto)
- [`/types`](https://github.com/cosmos/cosmos-sdk/tree/master/types)
- [`/store`](https://github.com/cosmos/cosmos-sdk/tree/master/store)
* [`/baseapp`](https://github.com/cosmos/cosmos-sdk/tree/master/baseapp)
* [`/crypto`](https://github.com/cosmos/cosmos-sdk/tree/master/crypto)
* [`/types`](https://github.com/cosmos/cosmos-sdk/tree/master/types)
* [`/store`](https://github.com/cosmos/cosmos-sdk/tree/master/store)
### Modules
- [`x/auth`](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth)
- [`x/bank`](https://github.com/cosmos/cosmos-sdk/tree/master/x/bank)
- [`x/capability`](https://github.com/cosmos/cosmos-sdk/tree/master/x/capability)
- [`x/staking`](https://github.com/cosmos/cosmos-sdk/tree/master/x/staking)
- [`x/slashing`](https://github.com/cosmos/cosmos-sdk/tree/master/x/slashing)
- [`x/evidence`](https://github.com/cosmos/cosmos-sdk/tree/master/x/evidence)
- [`x/distribution`](https://github.com/cosmos/cosmos-sdk/tree/master/x/distribution)
- [`x/ibc`](https://github.com/cosmos/cosmos-sdk/tree/master/x/ibc)
- [`x/ibc-transfer`](https://github.com/cosmos/cosmos-sdk/tree/master/x/ibc-transfer)
- [`x/mint`](https://github.com/cosmos/cosmos-sdk/tree/master/x/mint)
* [`x/auth`](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth)
* [`x/bank`](https://github.com/cosmos/cosmos-sdk/tree/master/x/bank)
* [`x/capability`](https://github.com/cosmos/cosmos-sdk/tree/master/x/capability)
* [`x/staking`](https://github.com/cosmos/cosmos-sdk/tree/master/x/staking)
* [`x/slashing`](https://github.com/cosmos/cosmos-sdk/tree/master/x/slashing)
* [`x/evidence`](https://github.com/cosmos/cosmos-sdk/tree/master/x/evidence)
* [`x/distribution`](https://github.com/cosmos/cosmos-sdk/tree/master/x/distribution)
* [`x/ibc`](https://github.com/cosmos/cosmos-sdk/tree/master/x/ibc)
* [`x/ibc-transfer`](https://github.com/cosmos/cosmos-sdk/tree/master/x/ibc-transfer)
* [`x/mint`](https://github.com/cosmos/cosmos-sdk/tree/master/x/mint)
We are interested in bugs in other modules, however the above are most likely to
have significant vulnerabilities, due to the complexity / nuance involved. We
@ -42,16 +42,16 @@ the code.
### How we process Tx parameters
- Integer operations on tx parameters, especially `sdk.Int` / `sdk.Dec`
- Gas calculation & parameter choices
- Tx signature verification (see [`x/auth/ante`](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth/ante))
- Possible Node DoS vectors (perhaps due to gas weighting / non constant timing)
* Integer operations on tx parameters, especially `sdk.Int` / `sdk.Dec`
* Gas calculation & parameter choices
* Tx signature verification (see [`x/auth/ante`](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth/ante))
* Possible Node DoS vectors (perhaps due to gas weighting / non constant timing)
### Handling private keys
- HD key derivation, local and Ledger, and all key-management functionality
- Side-channel attack vectors with our implementations
- e.g. key exfiltration based on time or memory-access patterns when decrypting privkey
* HD key derivation, local and Ledger, and all key-management functionality
* Side-channel attack vectors with our implementations
* e.g. key exfiltration based on time or memory-access patterns when decrypting privkey
## Disclosure Process
@ -83,7 +83,7 @@ Communications to partners usually include the following details:
An example notice looks like:
```
```text
Dear Cosmos SDK partners,
A critical security vulnerability has been identified in Cosmos SDK vX.X.X.

4
contrib/githooks/README.md
View File

@ -2,7 +2,7 @@
Installation:
```
```sh
git config core.hooksPath contrib/githooks
```
@ -13,7 +13,7 @@ to correctly format the `.go` files included in the commit, provided
that all the aforementioned commands are installed and available
in the user's search `$PATH` environment variable:
```
```sh
go get golang.org/x/tools/cmd/goimports
go get github.com/golangci/misspell/cmd/misspell@master
```

3
contrib/images/simd-dlv/README.md
View File

@ -15,14 +15,17 @@ Both `simd-env` and `simd-dlv` work and run the same, except that `simd-dlv` use
## How to use
The command to start a local network in debug mode is:
```shell
# make localnet-debug
```
The command to stop the local network and destroy its containers is:
```shell
# make localnet-stop
```
__note: this works the same for both `localnet-start` and `localnet-debug`__
Now, by default only `simdnode0` is run in debug mode, but you can run any of the other nodes in debug mode by changing the `DEBUG` environment variable to `1` in `docker-compose.yml`.

12
contrib/rosetta/README.md
View File

@ -6,10 +6,10 @@ This directory contains the files required to run the rosetta CI. It builds `sim
Builds:
- cosmos-sdk simapp node, with prefixed data directory, keys etc. This is required to test historical balances.
- faucet is required so we can test construction API, it was literally impossible to put there a deterministic address to request funds for
- rosetta is the rosetta node used by rosetta-cli to interact with the cosmos-sdk app
- test_rosetta runs the rosetta-cli test against construction API and data API
* cosmos-sdk simapp node, with prefixed data directory, keys etc. This is required to test historical balances.
* faucet is required so we can test construction API, it was literally impossible to put there a deterministic address to request funds for
* rosetta is the rosetta node used by rosetta-cli to interact with the cosmos-sdk app
* test_rosetta runs the rosetta-cli test against construction API and data API
## configuration
@ -25,5 +25,5 @@ The docker image for ./rosetta-cli/Dockerfile is on [docker hub](https://hub.doc
## Notes
- Keyring password is 12345678
- data.sh creates node data, it's required in case consensus breaking changes are made to quickly recreate replicable node data for rosetta
* Keyring password is 12345678
* data.sh creates node data, it's required in case consensus breaking changes are made to quickly recreate replicable node data for rosetta

28
cosmovisor/CHANGELOG.md
View File

@ -38,37 +38,39 @@ Ref: https://keepachangelog.com/en/1.0.0/
### Features
+ [\#10285](https://github.com/cosmos/cosmos-sdk/pull/10316) Added `run` action.
+ [\#10533](https://github.com/cosmos/cosmos-sdk/pull/10649) Added environmental variable `DAEMON_BACKUP_DIR` to allow node to set a custom backup directory.
* [\#10285](https://github.com/cosmos/cosmos-sdk/pull/10316) Added `run` action.
* [\#10533](https://github.com/cosmos/cosmos-sdk/pull/10649) Added environmental variable `DAEMON_BACKUP_DIR` to allow node to set a custom backup directory.
### Deprecated
+ [\#10285](https://github.com/cosmos/cosmos-sdk/pull/10316) Running `cosmovisor` without the `run` argument.
* [\#10285](https://github.com/cosmos/cosmos-sdk/pull/10316) Running `cosmovisor` without the `run` argument.
### Bug Fixes
+ [\#10458](https://github.com/cosmos/cosmos-sdk/pull/10458) Fix version when using 'go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@v1.0.0' to install cosmovisor.
* [\#10458](https://github.com/cosmos/cosmos-sdk/pull/10458) Fix version when using 'go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@v1.0.0' to install cosmovisor.
## v1.0.0 2021-09-30
### Features
+ [\#8590](https://github.com/cosmos/cosmos-sdk/pull/8590) File watcher for cosmovisor. Instead of parsing logs from stdin and stderr, we watch the `<DAEMON_HOME>/data/upgrade-info.json` file updates using polling mechanism.
+ [\#9999](https://github.com/cosmos/cosmos-sdk/pull/10103) Added `version` command that returns the cosmovisor version and the application version.
+ [\#9973](https://github.com/cosmos/cosmos-sdk/pull/10056) Added support for pre-upgrade command in Cosmovisor to be called before the binary is upgraded. Added new environmental variable `DAEMON_PREUPGRADE_MAX_RETRIES` that holds the maximum number of times to reattempt pre-upgrade before failing.
+ [\#10126](https://github.com/cosmos/cosmos-sdk/pull/10229) Added `help`.
* [\#8590](https://github.com/cosmos/cosmos-sdk/pull/8590) File watcher for cosmovisor. Instead of parsing logs from stdin and stderr, we watch the `<DAEMON_HOME>/data/upgrade-info.json` file updates using polling mechanism.
* [\#9999](https://github.com/cosmos/cosmos-sdk/pull/10103) Added `version` command that returns the cosmovisor version and the application version.
* [\#9973](https://github.com/cosmos/cosmos-sdk/pull/10056) Added support for pre-upgrade command in Cosmovisor to be called before the binary is upgraded. Added new environmental variable `DAEMON_PREUPGRADE_MAX_RETRIES` that holds the maximum number of times to reattempt pre-upgrade before failing.
* [\#10126](https://github.com/cosmos/cosmos-sdk/pull/10229) Added `help`.
### Improvements
+ [\#10018](https://github.com/cosmos/cosmos-sdk/pull/10018) Strict boolean argument parsing: cosmovisor will fail if user will not set correctly a boolean variable. Correct values are: "true", "false", "" (not setting) - all case not sensitive.
+ [\#10036](https://github.com/cosmos/cosmos-sdk/pull/10036) Improve logs when downloading the binary.
+ [\#10217](https://github.com/cosmos/cosmos-sdk/pull/10217) Replacing logging to use zerolog.
* [\#10018](https://github.com/cosmos/cosmos-sdk/pull/10018) Strict boolean argument parsing: cosmovisor will fail if user will not set correctly a boolean variable. Correct values are: "true", "false", "" (not setting) - all case not sensitive.
* [\#10036](https://github.com/cosmos/cosmos-sdk/pull/10036) Improve logs when downloading the binary.
* [\#10217](https://github.com/cosmos/cosmos-sdk/pull/10217) Replacing logging to use zerolog.
### CLI Breaking
+ [\#10128](https://github.com/cosmos/cosmos-sdk/pull/10128) Change default value of `DAEMON_RESTART_AFTER_UPGRADE` to `true`.
* [\#10128](https://github.com/cosmos/cosmos-sdk/pull/10128) Change default value of `DAEMON_RESTART_AFTER_UPGRADE` to `true`.
## v0.1 2021-08-06
This is the first release and we started this changelog on 2021-07-01. See the (README)[https://github.com/cosmos/cosmos-sdk/blob/release/cosmovisor/v0.1.x/cosmovisor/CHANGELOG.md] file for the full list of features.
This is the first release and we started this changelog on 2021-07-01. See the [README](https://github.com/cosmos/cosmos-sdk/blob/release/cosmovisor/v0.1.x/cosmovisor/CHANGELOG.md) file for the full list of features.
## Features

138
cosmovisor/README.md
View File

@ -2,7 +2,7 @@
`cosmovisor` is a small process manager for Cosmos SDK application binaries that monitors the governance module for incoming chain upgrade proposals. If it sees a proposal that gets approved, `cosmovisor` can automatically download the new binary, stop the current binary, switch from the old binary to the new one, and finally restart the node with the new binary.
#### Design
## Design
Cosmovisor is designed to be used as a wrapper for a `Cosmos SDK` app:
@ -27,13 +27,13 @@ Release branches have the following format `release/cosmovisor/vA.B.x`, where A
To install the latest version of `cosmovisor`, run the following command:
```
```sh
go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@latest
```
To install a previous version, you can specify the version. IMPORTANT: Chains that use Cosmos-SDK v0.44.3 or earlier (eg v0.44.2) and want to use auto-download feature MUST use Cosmovisor v0.1.0
```
```sh
go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@v0.1.0
```
@ -41,7 +41,7 @@ You can run `cosmovisor --version` to check the Cosmovisor version (works only w
You can also install from source by pulling the cosmos-sdk repository and switching to the correct version and building as follows:
```
```sh
git clone git@github.com:cosmos/cosmos-sdk
cd cosmos-sdk
git checkout cosmovisor/vx.x.x
@ -50,7 +50,7 @@ make cosmovisor
This will build cosmovisor in `/cosmovisor` directory. Afterwards you may want to put it into your machine's PATH like as follows:
```
```sh
cp cosmovisor/cosmovisor ~/go/bin/cosmovisor
```
@ -82,7 +82,7 @@ All arguments passed to `cosmovisor run` will be passed to the application binar
`$DAEMON_HOME/cosmovisor` is expected to belong completely to `cosmovisor` and the subprocesses that are controlled by it. The folder content is organized as follows:
```
```text
.
├── current -> genesis or upgrades/<name>
├── genesis
@ -99,7 +99,7 @@ The `cosmovisor/` directory incudes a subdirectory for each version of the appli
Please note that `$DAEMON_HOME/cosmovisor` only stores the *application binaries*. The `cosmovisor` binary itself can be stored in any typical location (e.g. `/usr/local/bin`). The application will continue to store its data in the default data directory (e.g. `$HOME/.gaiad`) or the data directory specified with the `--home` flag. `$DAEMON_HOME` is independent of the data directory and can be set to any location. If you set `$DAEMON_HOME` to the same directory as the data directory, you will end up with a configuation like the following:
```
```text
.gaiad
├── config
├── data
@ -110,11 +110,11 @@ Please note that `$DAEMON_HOME/cosmovisor` only stores the *application binaries
The system administrator is responsible for:
- installing the `cosmovisor` binary
- configuring the host's init system (e.g. `systemd`, `launchd`, etc.)
- appropriately setting the environmental variables
- manually installing the `genesis` folder
- manually installing the `upgrades/<name>` folders
* installing the `cosmovisor` binary
* configuring the host's init system (e.g. `systemd`, `launchd`, etc.)
* appropriately setting the environmental variables
* manually installing the `genesis` folder
* manually installing the `upgrades/<name>` folders
`cosmovisor` will set the `current` link to point to `genesis` at first start (i.e. when no `current` link exists) and then handle switching binaries at the correct points in time so that the system administrator can prepare days in advance and relax at upgrade time.
@ -127,10 +127,10 @@ The `DAEMON` specific code and operations (e.g. tendermint config, the applicati
`cosmovisor` is polling the `$DAEMON_HOME/data/upgrade-info.json` file for new upgrade instructions. The file is created by the x/upgrade module in `BeginBlocker` when an upgrade is detected and the blockchain reaches the upgrade height.
The following heuristic is applied to detect the upgrade:
+ When starting, `cosmovisor` doesn't know much about currently running upgrade, except the binary which is `current/bin/`. It tries to read the `current/update-info.json` file to get information about the current upgrade name.
+ If neither `cosmovisor/current/upgrade-info.json` nor `data/upgrade-info.json` exist, then `cosmovisor` will wait for `data/upgrade-info.json` file to trigger an upgrade.
+ If `cosmovisor/current/upgrade-info.json` doesn't exist but `data/upgrade-info.json` exists, then `cosmovisor` assumes that whatever is in `data/upgrade-info.json` is a valid upgrade request. In this case `cosmovisor` tries immediately to make an upgrade according to the `name` attribute in `data/upgrade-info.json`.
+ Otherwise, `cosmovisor` waits for changes in `upgrade-info.json`. As soon as a new upgrade name is recorded in the file, `cosmovisor` will trigger an upgrade mechanism.
* When starting, `cosmovisor` doesn't know much about currently running upgrade, except the binary which is `current/bin/`. It tries to read the `current/update-info.json` file to get information about the current upgrade name.
* If neither `cosmovisor/current/upgrade-info.json` nor `data/upgrade-info.json` exist, then `cosmovisor` will wait for `data/upgrade-info.json` file to trigger an upgrade.
* If `cosmovisor/current/upgrade-info.json` doesn't exist but `data/upgrade-info.json` exists, then `cosmovisor` assumes that whatever is in `data/upgrade-info.json` is a valid upgrade request. In this case `cosmovisor` tries immediately to make an upgrade according to the `name` attribute in `data/upgrade-info.json`.
* Otherwise, `cosmovisor` waits for changes in `upgrade-info.json`. As soon as a new upgrade name is recorded in the file, `cosmovisor` will trigger an upgrade mechanism.
When the upgrade mechanism is triggered, `cosmovisor` will:
@ -147,48 +147,48 @@ If `DAEMON_ALLOW_DOWNLOAD_BINARIES` is set to `true`, and no local binary can be
1. Store an os/architecture -> binary URI map in the upgrade plan info field as JSON under the `"binaries"` key. For example:
```json
{
"binaries": {
"linux/amd64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f"
}
}
```
You can include multiple binaries at once to ensure more than one environment will receive the correct binaries:
```json
{
"binaries": {
"linux/amd64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f",
"linux/arm64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f",
"darwin/amd64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f"
```json
{
"binaries": {
"linux/amd64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f"
}
}
}
```
```
When submitting this as a proposal ensure there are no spaces. An example command using `gaiad` could look like:
You can include multiple binaries at once to ensure more than one environment will receive the correct binaries:
```
> gaiad tx gov submit-proposal software-upgrade Vega \
--title Vega \
--deposit 100uatom \
--upgrade-height 7368420 \
--upgrade-info '{"binaries":{"linux/amd64":"https://github.com/cosmos/gaia/releases/download/v6.0.0-rc1/gaiad-v6.0.0-rc1-linux-amd64","linux/arm64":"https://github.com/cosmos/gaia/releases/download/v6.0.0-rc1/gaiad-v6.0.0-rc1-linux-arm64","darwin/amd64":"https://github.com/cosmos/gaia/releases/download/v6.0.0-rc1/gaiad-v6.0.0-rc1-darwin-amd64"}}' \
--description "upgrade to Vega" \
--gas 400000 \
--from user \
--chain-id test \
--home test/val2 \
--node tcp://localhost:36657 \
--yes
```
```json
{
"binaries": {
"linux/amd64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f",
"linux/arm64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f",
"darwin/amd64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f"
}
}
```
When submitting this as a proposal ensure there are no spaces. An example command using `gaiad` could look like:
```sh
> gaiad tx gov submit-proposal software-upgrade Vega \
--title Vega \
--deposit 100uatom \
--upgrade-height 7368420 \
--upgrade-info '{"binaries":{"linux/amd64":"https://github.com/cosmos/gaia/releases/download/v6.0.0-rc1/gaiad-v6.0.0-rc1-linux-amd64","linux/arm64":"https://github.com/cosmos/gaia/releases/download/v6.0.0-rc1/gaiad-v6.0.0-rc1-linux-arm64","darwin/amd64":"https://github.com/cosmos/gaia/releases/download/v6.0.0-rc1/gaiad-v6.0.0-rc1-darwin-amd64"}}' \
--description "upgrade to Vega" \
--gas 400000 \
--from user \
--chain-id test \
--home test/val2 \
--node tcp://localhost:36657 \
--yes
```
2. Store a link to a file that contains all information in the above format (e.g. if you want to specify lots of binaries, changelog info, etc. without filling up the blockchain). For example:
```
https://example.com/testnet-1001-info.json?checksum=sha256:deaaa99fda9407c4dbe1d04bd49bab0cc3c1dd76fa392cd55a9425be074af01e
```
```text
https://example.com/testnet-1001-info.json?checksum=sha256:deaaa99fda9407c4dbe1d04bd49bab0cc3c1dd76fa392cd55a9425be074af01e
```
When `cosmovisor` is triggered to download the new binary, `cosmovisor` will parse the `"binaries"` field, download the new binary with [go-getter](https://github.com/hashicorp/go-getter), and unpack the new binary in the `upgrades/<name>` folder so that it can be run as if it was installed manually.
@ -196,7 +196,7 @@ Note that for this mechanism to provide strong security guarantees, all URLs sho
To properly create a sha256 checksum on linux, you can use the `sha256sum` utility. For example:
```
```sh
sha256sum ./testdata/repo/zip_directory/autod.zip
```
@ -208,24 +208,25 @@ You can also use `sha512sum` if you would prefer to use longer hashes, or `md5su
The following instructions provide a demonstration of `cosmovisor` using the simulation application (`simapp`) shipped with the Cosmos SDK's source code. The following commands are to be run from within the `cosmos-sdk` repository.
#### Chain Setup
### Chain Setup
Let's create a new chain using the `v0.44` version of simapp (the Cosmos SDK demo app):
```
```sh
git checkout v0.44.6
make build
```
Clean `~/.simapp` (never do this in a production environment):
```
```sh
./build/simd unsafe-reset-all
```
Set up app config:
```
```sh
./build/simd config chain-id test
./build/simd config keyring-backend test
./build/simd config broadcast-mode block
@ -235,19 +236,19 @@ Initialize the node and overwrite any previous genesis file (never do this in a
<!-- TODO: init does not read chain-id from config -->
```
```sh
./build/simd init test --chain-id test --overwrite
```
Set the minimum gas price to `0stake` in `~/.simapp/config/app.toml`:
```
```sh
minimum-gas-prices = "0stake"
```
For the sake of this demonstration, amend `voting_period` in `genesis.json` to a reduced time of 20 seconds (`20s`):
```
```sh
cat <<< $(jq '.app_state.gov.voting_params.voting_period = "20s"' $HOME/.simapp/config/genesis.json) > $HOME/.simapp/config/genesis.json
```
@ -256,7 +257,7 @@ Create a validator, and setup genesis transaction:
<!-- TODO: add-genesis-account does not read keyring-backend from config -->
<!-- TODO: gentx does not read chain-id from config -->
```
```sh
./build/simd keys add validator
./build/simd add-genesis-account validator 1000000000stake --keyring-backend test
./build/simd gentx validator 1000000stake --chain-id test
@ -267,27 +268,28 @@ Create a validator, and setup genesis transaction:
Set the required environment variables:
```
```sh
export DAEMON_NAME=simd
export DAEMON_HOME=$HOME/.simapp
```
Set the optional environment variable to trigger an automatic app restart:
```
```sh
export DAEMON_RESTART_AFTER_UPGRADE=true
```
Create the folder for the genesis binary and copy the `simd` binary:
```
```sh
mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin
cp ./build/simd $DAEMON_HOME/cosmovisor/genesis/bin
```
Now you can run cosmovisor with simapp v0.44:
```
```sh
cosmovisor run start
```
@ -300,13 +302,13 @@ Next, we can add a migration - which is defined using `x/upgrade` [upgrade plan]
Build the new version `simd` binary:
```
```sh
make build
```
Create the folder for the upgrade binary and copy the `simd` binary:
```
```sh
mkdir -p $DAEMON_HOME/cosmovisor/upgrades/test1/bin
cp ./build/simd $DAEMON_HOME/cosmovisor/upgrades/test1/bin
```
@ -314,7 +316,7 @@ cp ./build/simd $DAEMON_HOME/cosmovisor/upgrades/test1/bin
Open a new terminal window and submit an upgrade proposal along with a deposit and a vote (these commands must be run within 20 seconds of each other):
```
```sh
./build/simd tx gov submit-proposal software-upgrade test1 --title upgrade --description upgrade --upgrade-height 200 --from validator --yes
./build/simd tx gov deposit 1 10000000stake --from validator --yes
./build/simd tx gov vote 1 yes --from validator --yes

6
cosmovisor/RELEASE_NOTES.md
View File

@ -26,8 +26,8 @@ verification command which can potentially solve this issue.
## Other updates
+ Changed default value of `DAEMON_RESTART_AFTER_UPGRADE` to `true`.
+ Added `version` command, which prints both the Cosmovisor and the associated app version.
+ Added `help` command, which prints the Cosmovisor help without passing it to the associated version. This is an exception, because normally, Cosmovisor passes all arguments to the associated app.
* Changed default value of `DAEMON_RESTART_AFTER_UPGRADE` to `true`.
* Added `version` command, which prints both the Cosmovisor and the associated app version.
* Added `help` command, which prints the Cosmovisor help without passing it to the associated version. This is an exception, because normally, Cosmovisor passes all arguments to the associated app.
For more details, please see the [CHANGELOG](https://github.com/cosmos/cosmos-sdk/blob/cosmovisor/v1.0.0/cosmovisor/CHANGELOG.md).

6
crypto/bcrypt_readme.md
View File

@ -1,5 +1,4 @@
Security parameter choice
-------------------------
# Security parameter choice
The present Bcrypt security parameter used is 12, which should take about a quarter of a second on midrange consumer hardware (see [Benchmarking](#benchmarking) section below).
@ -7,8 +6,7 @@ For some background into security parameter considerations, see [here](https://a
Given our security model, where an attacker would need to already have access to a victim's computer and copy the `~/.gaiacli` directory (as opposed to e.g. web authentication), this parameter choice seems sufficient for the time being. Bcrypt always generates a 448-bit key, so the security in practice is determined by the length & complexity of a user's password and the time taken to generate a Bcrypt key from their password (which we can choose with the security parameter). Users would be well-advised to use difficult-to-guess passwords.
Benchmarking
------------
## Benchmarking
To run Bcrypt benchmarks:

4
crypto/keys/secp256k1/internal/secp256k1/README.md
View File

@ -1,3 +1,5 @@
This package is copied from https://github.com/ethereum/go-ethereum/tree/729bf365b5f17325be9107b63b233da54100eec6/crypto/secp256k1
# secp256k1
This package is copied from <https://github.com/ethereum/go-ethereum/tree/729bf365b5f17325be9107b63b233da54100eec6/crypto/secp256k1>
Unlike the rest of go-ethereum it is MIT licensed so compatible with our Apache2.0 license. We opt to copy in here rather than depend on go-ethereum to avoid issues with vendoring of the GPL parts of that repository by downstream.

14
doc/proto-docs.md
View File

@ -1,16 +1,14 @@
<!-- This file is auto-generated. Please do not modify it yourself. -->
# Protobuf Documentation
<a name="top"></a>
## Table of Contents
- [cosmos/base/query/v1beta1/pagination.proto](#cosmos/base/query/v1beta1/pagination.proto)
- [PageRequest](#cosmos.base.query.v1beta1.PageRequest)
- [PageResponse](#cosmos.base.query.v1beta1.PageResponse)
- [Scalar Value Types](#scalar-value-types)
* [cosmos/base/query/v1beta1/pagination.proto](#cosmosbasequeryv1beta1paginationproto)
* [PageRequest](#pagerequest)
* [PageResponse](#pageresponse)
* [Scalar Value Types](#scalar-value-types)
<a name="cosmos/base/query/v1beta1/pagination.proto"></a>
<p align="right"><a href="#top">Top</a></p>
@ -22,6 +20,7 @@
<a name="cosmos.base.query.v1beta1.PageRequest"></a>
### PageRequest
PageRequest is to be embedded in gRPC request messages for efficient
pagination. Ex:
@ -49,6 +48,7 @@ Since: cosmos-sdk 0.43 |
<a name="cosmos.base.query.v1beta1.PageResponse"></a>
### PageResponse
PageResponse is to be embedded in gRPC response messages where the
corresponding request message has used PageRequest.

40
docs/DOCS_README.md
View File

@ -4,22 +4,22 @@ If you want to open a PR in Cosmos SDK to update the documentation, please follo
## Internationalization
- 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).
* 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 Cosmos SDK is hosted at https://docs.cosmos.network/ and built from the files in the `/docs` directory.
The documentation for Cosmos SDK is hosted at <https://docs.cosmos.network/> and built from the files in the `/docs` directory.
### How It Works
@ -47,17 +47,17 @@ Relative links should be used nearly everywhere, having discovered and weighed t
Where is the other file, relative to the current one?
- works both on GitHub and for the VuePress build
- confusing / annoying to have things like: `../../../../myfile.md`
- requires more updates when files are re-shuffled
* works both on GitHub and for the VuePress build
* confusing / annoying to have things like: `../../../../myfile.md`
* requires more updates when files are re-shuffled
### Absolute
Where is the other file, given the root of the repo?
- works on GitHub, doesn't work for the VuePress build
- this is much nicer: `/docs/hereitis/myfile.md`
- if you move that file around, the links inside it are preserved (but not to it, of course)
* works on GitHub, doesn't work for the VuePress build
* this is much nicer: `/docs/hereitis/myfile.md`
* if you move that file around, the links inside it are preserved (but not to it, of course)
### Full
@ -84,7 +84,7 @@ Install the theme and all dependencies.
npm run serve
```
Run `pre` and `post` hooks and start a hot-reloading web-server. See output of this command for the URL (it is often https://localhost:8080).
Run `pre` and `post` hooks and start a hot-reloading web-server. See output of this command for the URL (it is often <https://localhost:8080>).
To build documentation as a static website run `npm run build`. You will find the website in `.vuepress/dist` directory.

14
docs/DOC_WRITING_GUIDELINES.md
View File

@ -2,13 +2,13 @@
## Best Practices
+ Check the spelling and grammar, even if you have to copy and paste from an external source.
+ Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share.
+ Try to express your thoughts in a concise and clean way.
+ Don't abuse `code` format when writing in plain English.
+ Follow Google developer documentation [style guide](https://developers.google.com/style).
+ Check the meaning of words in Microsoft's [A-Z word list and term collections](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms) (use the search input!).
+ RFC keywords should be used in technical documents (uppercase) and we recommend to use them in user documentation (lowercase). The RFC keywords are: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
* Check the spelling and grammar, even if you have to copy and paste from an external source.
* Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share.
* Try to express your thoughts in a concise and clean way.
* Don't abuse `code` format when writing in plain English.
* Follow Google developer documentation [style guide](https://developers.google.com/style).
* Check the meaning of words in Microsoft's [A-Z word list and term collections](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms) (use the search input!).
* RFC keywords should be used in technical documents (uppercase) and we recommend to use them in user documentation (lowercase). The RFC keywords are: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
## Technical Writing Course

28
docs/README.md
View File

@ -47,26 +47,26 @@ aside: false
## Get Started
- **[Cosmos SDK Intro](./intro/overview.md)**: High-level overview of the Cosmos SDK.
- **[Starport](https://docs.starport.network/)**: A developer-friendly interface to the Cosmos SDK to scaffold, launch, and maintain any crypto application on a sovereign and secured blockchain.
- **[SDK Tutorials](https://tutorials.cosmos.network/)**: Tutorials that showcase how to build Cosmos SDK-based blockchains from scratch and explain the basic Cosmos SDK principles in the process.
* **[Cosmos SDK Intro](./intro/overview.md)**: High-level overview of the Cosmos SDK.
* **[Starport](https://docs.starport.network/)**: A developer-friendly interface to the Cosmos SDK to scaffold, launch, and maintain any crypto application on a sovereign and secured blockchain.
* **[SDK Tutorials](https://tutorials.cosmos.network/)**: Tutorials that showcase how to build Cosmos SDK-based blockchains from scratch and explain the basic Cosmos SDK principles in the process.
## Reference Docs
- **[Basics](./basics/)**: Basic concepts of the Cosmos SDK, including the standard anatomy of an application, the transaction lifecycle, and accounts management.
- **[Core](./core/)**: Core concepts of the Cosmos SDK, including `baseapp`, the `store`, or the `server`.
- **[Building Modules](./building-modules/)**: Important concepts for module developers like `message`, `keeper`, and `querier`.
- **[IBC](./ibc/)**: IBC protocol integration and concepts.
- **[Running a Node, API, CLI](./run-node/)**: How to run a node and interact with the node using the CLI and the API.
- **[Migrations](./migrations/)**: Migration guides for updating to newer versions of Cosmos SDK.
* **[Basics](./basics/)**: Basic concepts of the Cosmos SDK, including the standard anatomy of an application, the transaction lifecycle, and accounts management.
* **[Core](./core/)**: Core concepts of the Cosmos SDK, including `baseapp`, the `store`, or the `server`.
* **[Building Modules](./building-modules/)**: Important concepts for module developers like `message`, `keeper`, and `querier`.
* **[IBC](./ibc/)**: IBC protocol integration and concepts.
* **[Running a Node, API, CLI](./run-node/)**: How to run a node and interact with the node using the CLI and the API.
* **[Migrations](./migrations/)**: Migration guides for updating to newer versions of Cosmos 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.
- **[Cosmos SDK API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk)**: Godocs of the Cosmos SDK.
- **[REST and RPC Endpoints](https://cosmos.network/rpc/)**: List of endpoints to interact with a `gaia` full-node.
- **[Rosetta API](./run-node/rosetta.md)**: Rosetta API integration.
* **[Module Directory](../x/)**: Cosmos SDK module implementations and their respective documentation.
* **[Specifications](./spec/)**: Specifications of modules and other parts of the Cosmos SDK.
* **[Cosmos SDK API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk)**: Godocs of the Cosmos SDK.
* **[REST and RPC Endpoints](https://cosmos.network/rpc/)**: List of endpoints to interact with a `gaia` full-node.
* **[Rosetta API](./run-node/rosetta.md)**: Rosetta API integration.
## Cosmos Hub

22
docs/architecture/PROCESS.md
View File

@ -26,7 +26,7 @@ ADR creation is an **iterative** process. Instead of trying to solve all decisio
Status has two components:
```
```text
{CONSENSUS STATUS} {IMPLEMENTATION STATUS}
```
@ -34,7 +34,7 @@ IMPLEMENTATION STATUS is either `Implemented` or `Not Implemented`.
#### Consensus Status
```
```text
DRAFT -> PROPOSED -> LAST CALL yyyy-mm-dd -> ACCEPTED | REJECTED -> SUPERSEDED by ADR-xxx
\ |
\ |
@ -42,15 +42,15 @@ DRAFT -> PROPOSED -> LAST CALL yyyy-mm-dd -> ACCEPTED | REJECTED -> SUPERSEDED b
ABANDONED
```
+ `DRAFT`: [optional] an ADR which is work in progress, not being ready for a general review. This is to present an early work and get an early feedback in a Draft Pull Request form.
+ `PROPOSED`: an ADR covering a full solution architecture and still in the review - project stakeholders haven't reached an agreed yet.
+ `LAST CALL <date for the last call>`: [optional] clear notify that we are close to accept updates. Changing a status to `LAST CALL` means that social consensus (of Cosmos SDK maintainers) has been reached and we still want to give it a time to let the community react or analyze.
+ `ACCEPTED`: ADR which will represent a currently implemented or to be implemented architecture design.
+ `REJECTED`: ADR can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders will decide so.
+ `SUPERSEEDED by ADR-xxx`: ADR which has been superseded by a new ADR.
+ `ABANDONED`: the ADR is no longer pursued by the original authors.
* `DRAFT`: [optional] an ADR which is work in progress, not being ready for a general review. This is to present an early work and get an early feedback in a Draft Pull Request form.
* `PROPOSED`: an ADR covering a full solution architecture and still in the review - project stakeholders haven't reached an agreed yet.
* `LAST CALL <date for the last call>`: [optional] clear notify that we are close to accept updates. Changing a status to `LAST CALL` means that social consensus (of Cosmos SDK maintainers) has been reached and we still want to give it a time to let the community react or analyze.
* `ACCEPTED`: ADR which will represent a currently implemented or to be implemented architecture design.
* `REJECTED`: ADR can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders will decide so.
* `SUPERSEEDED by ADR-xxx`: ADR which has been superseded by a new ADR.
* `ABANDONED`: the ADR is no longer pursued by the original authors.
## Language used in ADR
+ The context/background should be written in the present tense.
+ Avoid using a first, personal form.
* The context/background should be written in the present tense.
* Avoid using a first, personal form.

76
docs/architecture/README.md
View File

@ -19,11 +19,11 @@ You can read more about the ADR concept in this [blog post](https://product.reve
ADRs are intended to be the primary mechanism for proposing new feature designs and new processes, for collecting community input on an issue, and for documenting the design decisions.
An ADR should provide:
- Context on the relevant goals and the current state
- Proposed changes to achieve the goals
- Summary of pros and cons
- References
- Changelog
* Context on the relevant goals and the current state
* Proposed changes to achieve the goals
* Summary of pros and cons
* References
* Changelog
Note the distinction between an ADR and a spec. The ADR provides the context, intuition, reasoning, and
justification for a change in architecture, or for the architecture of something
@ -36,7 +36,7 @@ If recorded decisions turned out to be lacking, convene a discussion, record the
Read about the [PROCESS](./PROCESS.md).
#### Use RFC 2119 Keywords
### Use RFC 2119 Keywords
When writing ADRs, follow the same best practices for writing RFCs. When writing RFCs, key words are used to signify the requirements in the specification. These words are often capitalized: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
@ -44,41 +44,41 @@ When writing ADRs, follow the same best practices for writing RFCs. When writing
### Accepted
- [ADR 002: SDK Documentation Structure](./adr-002-docs-structure.md)
- [ADR 004: Split Denomination Keys](./adr-004-split-denomination-keys.md)
- [ADR 006: Secret Store Replacement](./adr-006-secret-store-replacement.md)
- [ADR 009: Evidence Module](./adr-009-evidence-module.md)
- [ADR 010: Modular AnteHandler](./adr-010-modular-antehandler.md)
- [ADR 019: Protocol Buffer State Encoding](./adr-019-protobuf-state-encoding.md)
- [ADR 020: Protocol Buffer Transaction Encoding](./adr-020-protobuf-transaction-encoding.md)
- [ADR 021: Protocol Buffer Query Encoding](./adr-021-protobuf-query-encoding.md)
- [ADR 023: Protocol Buffer Naming and Versioning](./adr-023-protobuf-naming.md)
- [ADR 029: Fee Grant Module](./adr-029-fee-grant-module.md)
- [ADR 030: Message Authorization Module](./adr-030-authz-module.md)
- [ADR 031: Protobuf Msg Services](./adr-031-msg-service.md)
* [ADR 002: SDK Documentation Structure](./adr-002-docs-structure.md)
* [ADR 004: Split Denomination Keys](./adr-004-split-denomination-keys.md)
* [ADR 006: Secret Store Replacement](./adr-006-secret-store-replacement.md)
* [ADR 009: Evidence Module](./adr-009-evidence-module.md)
* [ADR 010: Modular AnteHandler](./adr-010-modular-antehandler.md)
* [ADR 019: Protocol Buffer State Encoding](./adr-019-protobuf-state-encoding.md)
* [ADR 020: Protocol Buffer Transaction Encoding](./adr-020-protobuf-transaction-encoding.md)
* [ADR 021: Protocol Buffer Query Encoding](./adr-021-protobuf-query-encoding.md)
* [ADR 023: Protocol Buffer Naming and Versioning](./adr-023-protobuf-naming.md)
* [ADR 029: Fee Grant Module](./adr-029-fee-grant-module.md)
* [ADR 030: Message Authorization Module](./adr-030-authz-module.md)
* [ADR 031: Protobuf Msg Services](./adr-031-msg-service.md)
### Proposed
- [ADR 003: Dynamic Capability Store](./adr-003-dynamic-capability-store.md)
- [ADR 011: Generalize Genesis Accounts](./adr-011-generalize-genesis-accounts.md)
- [ADR 012: State Accessors](./adr-012-state-accessors.md)
- [ADR 013: Metrics](./adr-013-metrics.md)
- [ADR 016: Validator Consensus Key Rotation](./adr-016-validator-consensus-key-rotation.md)
- [ADR 017: Historical Header Module](./adr-017-historical-header-module.md)
- [ADR 018: Extendable Voting Periods](./adr-018-extendable-voting-period.md)
- [ADR 022: Custom baseapp panic handling](./adr-022-custom-panic-handling.md)
- [ADR 024: Coin Metadata](./adr-024-coin-metadata.md)
- [ADR 027: Deterministic Protobuf Serialization](./adr-027-deterministic-protobuf-serialization.md)
- [ADR 028: Public Key Addresses](./adr-028-public-key-addresses.md)
- [ADR 032: Typed Events](./adr-032-typed-events.md)
- [ADR 033: Inter-module RPC](./adr-033-protobuf-inter-module-comm.md)
- [ADR 035: Rosetta API Support](./adr-035-rosetta-api-support.md)
- [ADR 037: Governance Split Votes](./adr-037-gov-split-vote.md)
- [ADR 038: State Listening](./adr-038-state-listening.md)
- [ADR 039: Epoched Staking](./adr-039-epoched-staking.md)
- [ADR 040: Storage and SMT State Commitments](./adr-040-storage-and-smt-state-commitments.md)
- [ADR 046: Module Params](./adr-046-module-params.md)
* [ADR 003: Dynamic Capability Store](./adr-003-dynamic-capability-store.md)
* [ADR 011: Generalize Genesis Accounts](./adr-011-generalize-genesis-accounts.md)
* [ADR 012: State Accessors](./adr-012-state-accessors.md)
* [ADR 013: Metrics](./adr-013-metrics.md)
* [ADR 016: Validator Consensus Key Rotation](./adr-016-validator-consensus-key-rotation.md)
* [ADR 017: Historical Header Module](./adr-017-historical-header-module.md)
* [ADR 018: Extendable Voting Periods](./adr-018-extendable-voting-period.md)
* [ADR 022: Custom baseapp panic handling](./adr-022-custom-panic-handling.md)
* [ADR 024: Coin Metadata](./adr-024-coin-metadata.md)
* [ADR 027: Deterministic Protobuf Serialization](./adr-027-deterministic-protobuf-serialization.md)
* [ADR 028: Public Key Addresses](./adr-028-public-key-addresses.md)
* [ADR 032: Typed Events](./adr-032-typed-events.md)
* [ADR 033: Inter-module RPC](./adr-033-protobuf-inter-module-comm.md)
* [ADR 035: Rosetta API Support](./adr-035-rosetta-api-support.md)
* [ADR 037: Governance Split Votes](./adr-037-gov-split-vote.md)
* [ADR 038: State Listening](./adr-038-state-listening.md)
* [ADR 039: Epoched Staking](./adr-039-epoched-staking.md)
* [ADR 040: Storage and SMT State Commitments](./adr-040-storage-and-smt-state-commitments.md)
* [ADR 046: Module Params](./adr-046-module-params.md)
### Draft
- [ADR 044: Guidelines for Updating Protobuf Definitions](./adr-044-protobuf-updates-guidelines.md)
* [ADR 044: Guidelines for Updating Protobuf Definitions](./adr-044-protobuf-updates-guidelines.md)

56
docs/architecture/adr-002-docs-structure.md
View File

@ -6,14 +6,14 @@ There is a need for a scalable structure of the Cosmos SDK documentation. Curren
Ideally, we would have:
- All docs related to dev frameworks or tools live in their respective github repos (sdk repo would contain sdk docs, hub repo would contain hub docs, lotion repo would contain lotion docs, etc.)
- All other docs (faqs, whitepaper, high-level material about Cosmos) would live on the website.
* All docs related to dev frameworks or tools live in their respective github repos (sdk repo would contain sdk docs, hub repo would contain hub docs, lotion repo would contain lotion docs, etc.)
* All other docs (faqs, whitepaper, high-level material about Cosmos) would live on the website.
## Decision
Re-structure the `/docs` folder of the Cosmos SDK github repo as follows:
```
```text
docs/
├── README
├── intro/
@ -39,21 +39,21 @@ docs/
The files in each sub-folders do not matter and will likely change. What matters is the sectioning:
- `README`: Landing page of the docs.
- `intro`: Introductory material. Goal is to have a short explainer of the Cosmos SDK and then channel people to the resource they need. The [Cosmos SDK tutorial](https://github.com/cosmos/sdk-application-tutorial/) will be highlighted, as well as the `godocs`.
- `concepts`: Contains high-level explanations of the abstractions of the Cosmos SDK. It does not contain specific code implementation and does not need to be updated often. **It is not an API specification of the interfaces**. API spec is the `godoc`.
- `clients`: Contains specs and info about the various Cosmos SDK clients.
- `spec`: Contains specs of modules, and others.
- `modules`: Contains links to `godocs` and the spec of the modules.
- `architecture`: Contains architecture-related docs like the present one.
- `translations`: Contains different translations of the documentation.
* `README`: Landing page of the docs.
* `intro`: Introductory material. Goal is to have a short explainer of the Cosmos SDK and then channel people to the resource they need. The [Cosmos SDK tutorial](https://github.com/cosmos/sdk-application-tutorial/) will be highlighted, as well as the `godocs`.
* `concepts`: Contains high-level explanations of the abstractions of the Cosmos SDK. It does not contain specific code implementation and does not need to be updated often. **It is not an API specification of the interfaces**. API spec is the `godoc`.
* `clients`: Contains specs and info about the various Cosmos SDK clients.
* `spec`: Contains specs of modules, and others.
* `modules`: Contains links to `godocs` and the spec of the modules.
* `architecture`: Contains architecture-related docs like the present one.
* `translations`: Contains different translations of the documentation.
Website docs sidebar will only include the following sections:
- `README`
- `intro`
- `concepts`
- `clients`
* `README`
* `intro`
* `concepts`
* `clients`
`architecture` need not be displayed on the website.
@ -65,22 +65,22 @@ Accepted
### Positive
- Much clearer organisation of the Cosmos SDK docs.
- The `/docs` folder now only contains Cosmos SDK and gaia related material. Later, it will only contain Cosmos SDK related material.
- Developers only have to update `/docs` folder when they open a PR (and not `/examples` for example).
- Easier for developers to find what they need to update in the docs thanks to reworked architecture.
- Cleaner vuepress build for website docs.
- Will help build an executable doc (cf https://github.com/cosmos/cosmos-sdk/issues/2611)
* Much clearer organisation of the Cosmos SDK docs.
* The `/docs` folder now only contains Cosmos SDK and gaia related material. Later, it will only contain Cosmos SDK related material.
* Developers only have to update `/docs` folder when they open a PR (and not `/examples` for example).
* Easier for developers to find what they need to update in the docs thanks to reworked architecture.
* Cleaner vuepress build for website docs.
* Will help build an executable doc (cf <https://github.com/cosmos/cosmos-sdk/issues/2611>)
### Neutral
- We need to move a bunch of deprecated stuff to `/_attic` folder.
- We need to integrate content in `docs/sdk/docs/core` in `concepts`.
- We need to move all the content that currently lives in `docs` and does not fit in new structure (like `lotion`, intro material, whitepaper) to the website repository.
- Update `DOCS_README.md`
* We need to move a bunch of deprecated stuff to `/_attic` folder.
* We need to integrate content in `docs/sdk/docs/core` in `concepts`.
* We need to move all the content that currently lives in `docs` and does not fit in new structure (like `lotion`, intro material, whitepaper) to the website repository.
* Update `DOCS_README.md`
## References
- https://github.com/cosmos/cosmos-sdk/issues/1460
- https://github.com/cosmos/cosmos-sdk/pull/2695
- https://github.com/cosmos/cosmos-sdk/issues/2611
* <https://github.com/cosmos/cosmos-sdk/issues/1460>
* <https://github.com/cosmos/cosmos-sdk/pull/2695>
* <https://github.com/cosmos/cosmos-sdk/issues/2611>

16
docs/architecture/adr-003-dynamic-capability-store.md
View File

@ -2,8 +2,8 @@
## Changelog
- 12 December 2019: Initial version
- 02 April 2020: Memory Store Revisions
* 12 December 2019: Initial version
* 02 April 2020: Memory Store Revisions
## Context
@ -326,14 +326,14 @@ Proposed.
### Positive
- Dynamic capability support.
- Allows CapabilityKeeper to return same capability pointer from go-map while reverting any writes to the persistent `KVStore` and in-memory `MemoryStore` on tx failure.
* Dynamic capability support.
* Allows CapabilityKeeper to return same capability pointer from go-map while reverting any writes to the persistent `KVStore` and in-memory `MemoryStore` on tx failure.
### Negative
- Requires an additional keeper.
- Some overlap with existing `StoreKey` system (in the future they could be combined, since this is a superset functionality-wise).
- Requires an extra level of indirection in the reverse mapping, since MemoryStore must map to index which must then be used as key in a go map to retrieve the actual capability
* Requires an additional keeper.
* Some overlap with existing `StoreKey` system (in the future they could be combined, since this is a superset functionality-wise).
* Requires an extra level of indirection in the reverse mapping, since MemoryStore must map to index which must then be used as key in a go map to retrieve the actual capability
### Neutral
@ -341,4 +341,4 @@ Proposed.
## References
- [Original discussion](https://github.com/cosmos/cosmos-sdk/pull/5230#discussion_r343978513)
* [Original discussion](https://github.com/cosmos/cosmos-sdk/pull/5230#discussion_r343978513)

28
docs/architecture/adr-004-split-denomination-keys.md
View File

@ -2,10 +2,10 @@
## Changelog
- 2020-01-08: Initial version
- 2020-01-09: Alterations to handle vesting accounts
- 2020-01-14: Updates from review feedback
- 2020-01-30: Updates from implementation
* 2020-01-08: Initial version
* 2020-01-09: Alterations to handle vesting accounts
* 2020-01-14: Updates from review feedback
* 2020-01-30: Updates from implementation
### Glossary
@ -38,11 +38,11 @@ vesting coins (which is safe since these cannot contain arbitrary denominations)
The following APIs will be added to the `x/bank` keeper:
- `GetAllBalances(ctx Context, addr AccAddress) Coins`
- `GetBalance(ctx Context, addr AccAddress, denom string) Coin`
- `SetBalance(ctx Context, addr AccAddress, coin Coin)`
- `LockedCoins(ctx Context, addr AccAddress) Coins`
- `SpendableCoins(ctx Context, addr AccAddress) Coins`
* `GetAllBalances(ctx Context, addr AccAddress) Coins`
* `GetBalance(ctx Context, addr AccAddress, denom string) Coin`
* `SetBalance(ctx Context, addr AccAddress, coin Coin)`
* `LockedCoins(ctx Context, addr AccAddress) Coins`
* `SpendableCoins(ctx Context, addr AccAddress) Coins`
Additional APIs may be added to facilitate iteration and auxiliary functionality not essential to
core functionality or persistence.
@ -100,13 +100,13 @@ Accepted.
### Positive
- O(1) reads & writes of balances (with respect to the number of denominations for
* O(1) reads & writes of balances (with respect to the number of denominations for
which an account has non-zero balances). Note, this does not relate to the actual
I/O cost, rather the total number of direct reads needed.
### Negative
- Slightly less efficient reads/writes when reading & writing all balances of a
* Slightly less efficient reads/writes when reading & writing all balances of a
single account in a transaction.
### Neutral
@ -115,6 +115,6 @@ None in particular.
## References
- Ref: https://github.com/cosmos/cosmos-sdk/issues/4982
- Ref: https://github.com/cosmos/cosmos-sdk/issues/5467
- Ref: https://github.com/cosmos/cosmos-sdk/issues/5492
* Ref: <https://github.com/cosmos/cosmos-sdk/issues/4982>
* Ref: <https://github.com/cosmos/cosmos-sdk/issues/5467>
* Ref: <https://github.com/cosmos/cosmos-sdk/issues/5492>

18
docs/architecture/adr-006-secret-store-replacement.md
View File

@ -2,10 +2,10 @@
## Changelog
- July 29th, 2019: Initial draft
- September 11th, 2019: Work has started
- November 4th: Cosmos SDK changes merged in
- November 18th: Gaia changes merged in
* July 29th, 2019: Initial draft
* September 11th, 2019: Work has started
* November 4th: Cosmos SDK changes merged in
* November 18th: Gaia changes merged in
## Context
@ -47,8 +47,8 @@ Running tests locally on a Mac require numerous repetitive password entries.
## References
- #4754 Switch secret store to the keyring secret store (original PR by @poldsam) [__CLOSED__]
- #5029 Add support for github.com/99designs/keyring-backed keybases [__MERGED__]
- #5097 Add keys migrate command [__MERGED__]
- #5180 Drop on-disk keybase in favor of keyring [_PENDING_REVIEW_]
- cosmos/gaia#164 Drop on-disk keybase in favor of keyring (gaia's changes) [_PENDING_REVIEW_]
* #4754 Switch secret store to the keyring secret store (original PR by @poldsam) [__CLOSED__]
* #5029 Add support for github.com/99designs/keyring-backed keybases [__MERGED__]
* #5097 Add keys migrate command [__MERGED__]
* #5180 Drop on-disk keybase in favor of keyring [_PENDING_REVIEW_]
* cosmos/gaia#164 Drop on-disk keybase in favor of keyring (gaia's changes) [_PENDING_REVIEW_]

38
docs/architecture/adr-007-specialization-groups.md
View File

@ -2,7 +2,7 @@
## Changelog
- 2019 Jul 31: Initial Draft
* 2019 Jul 31: Initial Draft
## Context
@ -26,22 +26,22 @@ governance proposals include a field for issue type.
A specialization group can be broadly broken down into the following functions
(herein containing examples):
- Membership Admittance
- Membership Acceptance
- Membership Revocation
- (probably) Without Penalty
- member steps down (self-Revocation)
- replaced by new member from governance
- (probably) With Penalty
- due to breach of soft-agreement (determined through governance)
- due to breach of hard-agreement (determined by code)
- Execution of Duties
- Special transactions which only execute for members of a specialization
* Membership Admittance
* Membership Acceptance
* Membership Revocation
* (probably) Without Penalty
* member steps down (self-Revocation)
* replaced by new member from governance
* (probably) With Penalty
* due to breach of soft-agreement (determined through governance)
* due to breach of hard-agreement (determined by code)
* Execution of Duties
* Special transactions which only execute for members of a specialization
group (for example, dCERT members voting to turn off transaction routes in
an emergency scenario)
- Compensation
- Group compensation (further distribution decided by the specialization group)
- Individual compensation for all constituents of a group from the
* Compensation
* Group compensation (further distribution decided by the specialization group)
* Individual compensation for all constituents of a group from the
greater community
Membership admittance to a specialization group could take place over a wide
@ -163,15 +163,15 @@ type SpecializationGroup interface {
### Positive
- increases specialization capabilities of a blockchain
- improve abstractions in `x/gov/` such that they can be used with specialization groups
* increases specialization capabilities of a blockchain
* improve abstractions in `x/gov/` such that they can be used with specialization groups
### Negative
- could be used to increase centralization within a community
* could be used to increase centralization within a community
### Neutral
## References
- [dCERT ADR](./adr-008-dCERT-group.md)
* [dCERT ADR](./adr-008-dCERT-group.md)

54
docs/architecture/adr-008-dCERT-group.md
View File

@ -2,7 +2,7 @@
## Changelog
- 2019 Jul 31: Initial Draft
* 2019 Jul 31: Initial Draft
## Context
@ -35,22 +35,22 @@ The dCERT group is proposed to include an implementation of a `SpecializationGro
as defined in [ADR 007](./adr-007-specialization-groups.md). This will include the
implementation of:
- continuous voting
- slashing due to breach of soft contract
- revoking a member due to breach of soft contract
- emergency disband of the entire dCERT group (ex. for colluding maliciously)
- compensation stipend from the community pool or other means decided by
* continuous voting
* slashing due to breach of soft contract
* revoking a member due to breach of soft contract
* emergency disband of the entire dCERT group (ex. for colluding maliciously)
* compensation stipend from the community pool or other means decided by
governance
This system necessitates the following new parameters:
- blockly stipend allowance per dCERT member
- maximum number of dCERT members
- required staked slashable tokens for each dCERT member
- quorum for suspending a particular member
- proposal wager for disbanding the dCERT group
- stabilization period for dCERT member transition
- circuit break dCERT privileges enabled
* blockly stipend allowance per dCERT member
* maximum number of dCERT members
* required staked slashable tokens for each dCERT member
* quorum for suspending a particular member
* proposal wager for disbanding the dCERT group
* stabilization period for dCERT member transition
* circuit break dCERT privileges enabled
These parameters are expected to be implemented through the param keeper such
that governance may change them at any given point.
@ -60,27 +60,27 @@ that governance may change them at any given point.
An `Electionator` object is to be implemented as continuous voting and with the
following specifications:
- All delegation addresses may submit votes at any point which updates their
* All delegation addresses may submit votes at any point which updates their
preferred representation on the dCERT group.
- Preferred representation may be arbitrarily split between addresses (ex. 50%
* Preferred representation may be arbitrarily split between addresses (ex. 50%
to John, 25% to Sally, 25% to Carol)
- In order for a new member to be added to the dCERT group they must
* In order for a new member to be added to the dCERT group they must
send a transaction accepting their admission at which point the validity of
their admission is to be confirmed.
- A sequence number is assigned when a member is added to dCERT group.
* A sequence number is assigned when a member is added to dCERT group.
If a member leaves the dCERT group and then enters back, a new sequence number
is assigned.
- Addresses which control the greatest amount of preferred-representation are
* Addresses which control the greatest amount of preferred-representation are
eligible to join the dCERT group (up the _maximum number of dCERT members_).
If the dCERT group is already full and new member is admitted, the existing
dCERT member with the lowest amount of votes is kicked from the dCERT group.
- In the split situation where the dCERT group is full but a vying candidate
* In the split situation where the dCERT group is full but a vying candidate
has the same amount of vote as an existing dCERT member, the existing
member should maintain its position.
- In the split situation where somebody must be kicked out but the two
* In the split situation where somebody must be kicked out but the two
addresses with the smallest number of votes have the same number of votes,
the address with the smallest sequence number maintains its position.
- A stabilization period can be optionally included to reduce the
* A stabilization period can be optionally included to reduce the
"flip-flopping" of the dCERT membership tail members. If a stabilization
period is provided which is greater than 0, when members are kicked due to
insufficient support, a queue entry is created which documents which member is
@ -128,9 +128,9 @@ capable of shutting down the exploitable message routes.
Active dCERT members
- change of the description of the dCERT group
- circuit break a message route
- vote to suspend a dCERT member.
* change of the description of the dCERT group
* circuit break a message route
* vote to suspend a dCERT member.
Here circuit-breaking refers to the capability to disable a groups of messages,
This could for instance mean: "disable all staking-delegation messages", or
@ -157,12 +157,12 @@ they should all be severely slashed.
### Positive
- Potential to reduces the number of parties to coordinate with during an emergency
- Reduction in possibility of disclosing sensitive information to malicious parties
* Potential to reduces the number of parties to coordinate with during an emergency
* Reduction in possibility of disclosing sensitive information to malicious parties
### Negative
- Centralization risks
* Centralization risks
### Neutral

28
docs/architecture/adr-009-evidence-module.md
View File

@ -2,8 +2,8 @@
## Changelog
- 2019 July 31: Initial draft
- 2019 October 24: Initial implementation
* 2019 July 31: Initial draft
* 2019 October 24: Initial implementation
## Status
@ -27,14 +27,14 @@ chain so that the equivocating validator(s) can be slashed.
We will implement an evidence module in the Cosmos SDK supporting the following
functionality:
- Provide developers with the abstractions and interfaces necessary to define
* Provide developers with the abstractions and interfaces necessary to define
custom evidence messages, message handlers, and methods to slash and penalize
accordingly for misbehavior.
- Support the ability to route evidence messages to handlers in any module to
* Support the ability to route evidence messages to handlers in any module to
determine the validity of submitted misbehavior.
- Support the ability, through governance, to modify slashing penalties of any
* Support the ability, through governance, to modify slashing penalties of any
evidence type.
- Querier implementation to support querying params, evidence types, params, and
* Querier implementation to support querying params, evidence types, params, and
all submitted valid misbehavior.
### Types
@ -160,23 +160,23 @@ type GenesisState struct {
### Positive
- Allows the state machine to process misbehavior submitted on-chain and penalize
* Allows the state machine to process misbehavior submitted on-chain and penalize
validators based on agreed upon slashing parameters.
- Allows evidence types to be defined and handled by any module. This further allows
* Allows evidence types to be defined and handled by any module. This further allows
slashing and jailing to be defined by more complex mechanisms.
- Does not solely rely on Tendermint to submit evidence.
* Does not solely rely on Tendermint to submit evidence.
### Negative
- No easy way to introduce new evidence types through governance on a live chain
* No easy way to introduce new evidence types through governance on a live chain
due to the inability to introduce the new evidence type's corresponding handler
### Neutral
- Should we persist infractions indefinitely? Or should we rather rely on events?
* Should we persist infractions indefinitely? Or should we rather rely on events?
## References
- [ICS](https://github.com/cosmos/ics)
- [IBC Architecture](https://github.com/cosmos/ics/blob/master/ibc/1_IBC_ARCHITECTURE.md)
- [Tendermint Fork Accountability](https://github.com/tendermint/spec/blob/7b3138e69490f410768d9b1ffc7a17abc23ea397/spec/consensus/fork-accountability.md)
* [ICS](https://github.com/cosmos/ics)
* [IBC Architecture](https://github.com/cosmos/ics/blob/master/ibc/1_IBC_ARCHITECTURE.md)
* [Tendermint Fork Accountability](https://github.com/tendermint/spec/blob/7b3138e69490f410768d9b1ffc7a17abc23ea397/spec/consensus/fork-accountability.md)

12
docs/architecture/adr-010-modular-antehandler.md
View File

@ -2,8 +2,8 @@
## Changelog
- 2019 Aug 31: Initial draft
- 2021 Sep 14: Superseded by ADR-045
* 2019 Aug 31: Initial draft
* 2021 Sep 14: Superseded by ADR-045
## Status
@ -284,7 +284,7 @@ Since pros and cons are written for each approach, it is omitted from this secti
## References
- [#4572](https://github.com/cosmos/cosmos-sdk/issues/4572): Modular AnteHandler Issue
- [#4582](https://github.com/cosmos/cosmos-sdk/pull/4583): Initial Implementation of Per-Module AnteHandler Approach
- [Weave Decorator Code](https://github.com/iov-one/weave/blob/master/handler.go#L35)
- [Weave Design Videos](https://vimeo.com/showcase/6189877)
* [#4572](https://github.com/cosmos/cosmos-sdk/issues/4572): Modular AnteHandler Issue
* [#4582](https://github.com/cosmos/cosmos-sdk/pull/4583): Initial Implementation of Per-Module AnteHandler Approach
* [Weave Decorator Code](https://github.com/iov-one/weave/blob/master/handler.go#L35)
* [Weave Design Videos](https://vimeo.com/showcase/6189877)

14
docs/architecture/adr-011-generalize-genesis-accounts.md
View File

@ -2,7 +2,7 @@
## Changelog
- 2019-08-30: initial draft
* 2019-08-30: initial draft
## Context
@ -145,8 +145,8 @@ This will be moved to `auth`. We will leave it to projects to write their own co
Under the new scheme, module and vesting account types need some minor updates:
- Type registration on `auth`'s codec (shown above)
- A `Validate` method for each `Account` concrete type
* Type registration on `auth`'s codec (shown above)
* A `Validate` method for each `Account` concrete type
## Status
@ -156,15 +156,15 @@ Proposed
### Positive
- custom accounts can be used without needing to fork `genaccounts`
- reduction in lines of code
* custom accounts can be used without needing to fork `genaccounts`
* reduction in lines of code
### Negative
### Neutral
- `genaccounts` module no longer exists
- accounts in genesis files are stored under `accounts` in `auth` rather than in the `genaccounts` module.
* `genaccounts` module no longer exists
* accounts in genesis files are stored under `accounts` in `auth` rather than in the `genaccounts` module.
-`add-genesis-account` cli command now in `auth`
## References

24
docs/architecture/adr-012-state-accessors.md
View File

@ -2,7 +2,7 @@
## Changelog
- 2019 Sep 04: Initial draft
* 2019 Sep 04: Initial draft
## Context
@ -125,9 +125,9 @@ Where the `key` argument in core method is typed.
Some of the properties of the accessor types are:
- State access happens only when a function which takes a `Context` as an argument is invoked
- Accessor type structs give rights to access the state only that the struct is referring, no other
- Marshalling/Unmarshalling happens implicitly within the core methods
* State access happens only when a function which takes a `Context` as an argument is invoked
* Accessor type structs give rights to access the state only that the struct is referring, no other
* Marshalling/Unmarshalling happens implicitly within the core methods
## Status
@ -137,19 +137,19 @@ Proposed
### Positive
- Serialization will be done automatically
- Shorter code size, less boilerplate, better UX
- References to the state can be transferred safely
- Explicit scope of accessing
* Serialization will be done automatically
* Shorter code size, less boilerplate, better UX
* References to the state can be transferred safely
* Explicit scope of accessing
### Negative
- Serialization format will be hidden
- Different architecture from the current, but the use of accessor types can be opt-in
- Type-specific types (e.g. `Boolean` and `Integer`) have to be defined manually
* Serialization format will be hidden
* Different architecture from the current, but the use of accessor types can be opt-in
* Type-specific types (e.g. `Boolean` and `Integer`) have to be defined manually
### Neutral
## References
- [#4554](https://github.com/cosmos/cosmos-sdk/issues/4554)
* [#4554](https://github.com/cosmos/cosmos-sdk/issues/4554)

4
docs/architecture/adr-013-metrics.md
View File

@ -2,7 +2,7 @@
## Changelog
- 20-01-2020: Initial Draft
* 20-01-2020: Initial Draft
## Status
@ -148,7 +148,7 @@ func (k BaseKeeper) MintCoins(ctx sdk.Context, moduleName string, amt sdk.Coins)
### Positive
- Exposure into the performance and behavior of an application
* Exposure into the performance and behavior of an application
### Negative

22
docs/architecture/adr-014-proportional-slashing.md
View File

@ -2,9 +2,9 @@
## Changelog
- 2019-10-15: Initial draft
- 2020-05-25: Removed correlation root slashing
- 2020-07-01: Updated to include S-curve function instead of linear
* 2019-10-15: Initial draft
* 2020-05-25: Removed correlation root slashing
* 2020-07-01: Updated to include S-curve function instead of linear
## Context
@ -16,13 +16,13 @@ In Proof of Stake-based chains, centralization of consensus power amongst a smal
To solve this problem, we will implement a procedure called Proportional Slashing. The desire is that the larger a validator is, the more they should be slashed. The first naive attempt is to make a validator's slash percent proportional to their share of consensus voting power.
```
```text
slash_amount = k * power // power is the faulting validator's voting power and k is some on-chain constant
```
However, this will incentivize validators with large amounts of stake to split up their voting power amongst accounts (sybil attack), so that if they fault, they all get slashed at a lower percent. The solution to this is to take into account not just a validator's own voting percentage, but also the voting percentage of all the other validators who get slashed in a specified time frame.
```
```text
slash_amount = k * (power_1 + power_2 + ... + power_n) // where power_i is the voting power of the ith validator faulting in the specified time frame and k is some on-chain constant
```
@ -51,7 +51,7 @@ Griefing, the act of intentionally getting oneself slashed in order to make anot
In the slashing module, we will add two queues that will track all of the recent slash events. For double sign faults, we will define "recent slashes" as ones that have occurred within the last `unbonding period`. For liveness faults, we will define "recent slashes" as ones that have occurred withing the last `jail period`.
```
```go
type SlashEvent struct {
Address sdk.ValAddress
ValidatorVotingPercent sdk.Dec
@ -75,11 +75,11 @@ Proposed
### Positive
- Increases decentralization by disincentivizing delegating to large validators
- Incentivizes Decorrelation of Validators
- More severely punishes attacks than accidental faults
- More flexibility in slashing rates parameterization
* Increases decentralization by disincentivizing delegating to large validators
* Incentivizes Decorrelation of Validators
* More severely punishes attacks than accidental faults
* More flexibility in slashing rates parameterization
### Negative
- More computationally expensive than current implementation. Will require more data about "recent slashing events" to be stored on chain.
* More computationally expensive than current implementation. Will require more data about "recent slashing events" to be stored on chain.

94
docs/architecture/adr-016-validator-consensus-key-rotation.md
View File

@ -2,12 +2,12 @@
## Changelog
- 2019 Oct 23: Initial draft
- 2019 Nov 28: Add key rotation fee
* 2019 Oct 23: Initial draft
* 2019 Nov 28: Add key rotation fee
## Context
Validator consensus key rotation feature has been discussed and requested for a long time, for the sake of safer validator key management policy (e.g. https://github.com/tendermint/tendermint/issues/1136). So, we suggest one of the simplest form of validator consensus key rotation implementation mostly onto Cosmos SDK.
Validator consensus key rotation feature has been discussed and requested for a long time, for the sake of safer validator key management policy (e.g. <https://github.com/tendermint/tendermint/issues/1136>). So, we suggest one of the simplest form of validator consensus key rotation implementation mostly onto Cosmos SDK.
We don't need to make any update on consensus logic in Tendermint because Tendermint does not have any mapping information of consensus key and validator operator key, meaning that from Tendermint point of view, a consensus key rotation of a validator is simply a replacement of a consensus key to another.
@ -17,37 +17,37 @@ Also, it should be noted that this ADR includes only the simplest form of consen
### Pseudo procedure for consensus key rotation
- create new random consensus key.
- create and broadcast a transaction with a `MsgRotateConsPubKey` that states the new consensus key is now coupled with the validator operator with signature from the validator's operator key.
- old consensus key becomes unable to participate on consensus immediately after the update of key mapping state on-chain.
- start validating with new consensus key.
- validators using HSM and KMS should update the consensus key in HSM to use the new rotated key after the height `h` when `MsgRotateConsPubKey` committed to the blockchain.
* create new random consensus key.
* create and broadcast a transaction with a `MsgRotateConsPubKey` that states the new consensus key is now coupled with the validator operator with signature from the validator's operator key.
* old consensus key becomes unable to participate on consensus immediately after the update of key mapping state on-chain.
* start validating with new consensus key.
* validators using HSM and KMS should update the consensus key in HSM to use the new rotated key after the height `h` when `MsgRotateConsPubKey` committed to the blockchain.
### Considerations
- consensus key mapping information management strategy
- store history of each key mapping changes in the kvstore.
- the state machine can search corresponding consensus key paired with given validator operator for any arbitrary height in a recent unbonding period.
- the state machine does not need any historical mapping information which is past more than unbonding period.
- key rotation costs related to LCD and IBC
- LCD and IBC will have traffic/computation burden when there exists frequent power changes
- In current Tendermint design, consensus key rotations are seen as power changes from LCD or IBC perspective
- Therefore, to minimize unnecessary frequent key rotation behavior, we limited maximum number of rotation in recent unbonding period and also applied exponentially increasing rotation fee
- limits
- a validator cannot rotate its consensus key more than `MaxConsPubKeyRotations` time for any unbonding period, to prevent spam.
- parameters can be decided by governance and stored in genesis file.
- key rotation fee
- a validator should pay `KeyRotationFee` to rotate the consensus key which is calculated as below
- `KeyRotationFee` = (max(`VotingPowerPercentage` *100, 1)* `InitialKeyRotationFee`) * 2^(number of rotations in `ConsPubKeyRotationHistory` in recent unbonding period)
- evidence module
- evidence module can search corresponding consensus key for any height from slashing keeper so that it can decide which consensus key is supposed to be used for given height.
- abci.ValidatorUpdate
- tendermint already has ability to change a consensus key by ABCI communication(`ValidatorUpdate`).
- validator consensus key update can be done via creating new + delete old by change the power to zero.
- therefore, we expect we even do not need to change tendermint codebase at all to implement this feature.
- new genesis parameters in `staking` module
- `MaxConsPubKeyRotations` : maximum number of rotation can be executed by a validator in recent unbonding period. default value 10 is suggested(11th key rotation will be rejected)
- `InitialKeyRotationFee` : the initial key rotation fee when no key rotation has happened in recent unbonding period. default value 1atom is suggested(1atom fee for the first key rotation in recent unbonding period)
* consensus key mapping information management strategy
* store history of each key mapping changes in the kvstore.
* the state machine can search corresponding consensus key paired with given validator operator for any arbitrary height in a recent unbonding period.
* the state machine does not need any historical mapping information which is past more than unbonding period.
* key rotation costs related to LCD and IBC
* LCD and IBC will have traffic/computation burden when there exists frequent power changes
* In current Tendermint design, consensus key rotations are seen as power changes from LCD or IBC perspective
* Therefore, to minimize unnecessary frequent key rotation behavior, we limited maximum number of rotation in recent unbonding period and also applied exponentially increasing rotation fee
* limits
* a validator cannot rotate its consensus key more than `MaxConsPubKeyRotations` time for any unbonding period, to prevent spam.
* parameters can be decided by governance and stored in genesis file.
* key rotation fee
* a validator should pay `KeyRotationFee` to rotate the consensus key which is calculated as below
* `KeyRotationFee` = (max(`VotingPowerPercentage` *100, 1)* `InitialKeyRotationFee`) * 2^(number of rotations in `ConsPubKeyRotationHistory` in recent unbonding period)
* evidence module
* evidence module can search corresponding consensus key for any height from slashing keeper so that it can decide which consensus key is supposed to be used for given height.
* abci.ValidatorUpdate
* tendermint already has ability to change a consensus key by ABCI communication(`ValidatorUpdate`).
* validator consensus key update can be done via creating new + delete old by change the power to zero.
* therefore, we expect we even do not need to change tendermint codebase at all to implement this feature.
* new genesis parameters in `staking` module
* `MaxConsPubKeyRotations` : maximum number of rotation can be executed by a validator in recent unbonding period. default value 10 is suggested(11th key rotation will be rejected)
* `InitialKeyRotationFee` : the initial key rotation fee when no key rotation has happened in recent unbonding period. default value 1atom is suggested(1atom fee for the first key rotation in recent unbonding period)
### Workflow
@ -63,14 +63,14 @@ Also, it should be noted that this ADR includes only the simplest form of consen
3. `handleMsgRotateConsPubKey` gets `MsgRotateConsPubKey`, calls `RotateConsPubKey` with emits event
4. `RotateConsPubKey`
- checks if `NewPubKey` is not duplicated on `ValidatorsByConsAddr`
- checks if the validator is does not exceed parameter `MaxConsPubKeyRotations` by iterating `ConsPubKeyRotationHistory`
- checks if the signing account has enough balance to pay `KeyRotationFee`
- pays `KeyRotationFee` to community fund
- overwrites `NewPubKey` in `validator.ConsPubKey`
- deletes old `ValidatorByConsAddr`
- `SetValidatorByConsAddr` for `NewPubKey`
- Add `ConsPubKeyRotationHistory` for tracking rotation
* checks if `NewPubKey` is not duplicated on `ValidatorsByConsAddr`
* checks if the validator is does not exceed parameter `MaxConsPubKeyRotations` by iterating `ConsPubKeyRotationHistory`
* checks if the signing account has enough balance to pay `KeyRotationFee`
* pays `KeyRotationFee` to community fund
* overwrites `NewPubKey` in `validator.ConsPubKey`
* deletes old `ValidatorByConsAddr`
* `SetValidatorByConsAddr` for `NewPubKey`
* Add `ConsPubKeyRotationHistory` for tracking rotation
```go
type ConsPubKeyRotationHistory struct {
@ -98,7 +98,7 @@ Also, it should be noted that this ADR includes only the simplest form of consen
6. at `previousVotes` Iteration logic of `AllocateTokens`, `previousVote` using `OldConsPubKey` match up with `ConsPubKeyRotationHistory`, and replace validator for token allocation
7. Migrate `ValidatorSigningInfo` and `ValidatorMissedBlockBitArray` from `OldConsPubKey` to `NewConsPubKey`
- Note : All above features shall be implemented in `staking` module.
* Note : All above features shall be implemented in `staking` module.
## Status
@ -108,18 +108,18 @@ Proposed
### Positive
- Validators can immediately or periodically rotate their consensus key to have better security policy
- improved security against Long-Range attacks (https://nearprotocol.com/blog/long-range-attacks-and-a-new-fork-choice-rule) given a validator throws away the old consensus key(s)
* Validators can immediately or periodically rotate their consensus key to have better security policy
* improved security against Long-Range attacks (<https://nearprotocol.com/blog/long-range-attacks-and-a-new-fork-choice-rule>) given a validator throws away the old consensus key(s)
### Negative
- Slash module needs more computation because it needs to lookup corresponding consensus key of validators for each height
- frequent key rotations will make light client bisection less efficient
* Slash module needs more computation because it needs to lookup corresponding consensus key of validators for each height
* frequent key rotations will make light client bisection less efficient
### Neutral
## References
- on tendermint repo : https://github.com/tendermint/tendermint/issues/1136
- on cosmos-sdk repo : https://github.com/cosmos/cosmos-sdk/issues/5231
- about multiple consensus keys : https://github.com/tendermint/tendermint/issues/1758#issuecomment-545291698
* on tendermint repo : <https://github.com/tendermint/tendermint/issues/1136>
* on cosmos-sdk repo : <https://github.com/cosmos/cosmos-sdk/issues/5231>
* about multiple consensus keys : <https://github.com/tendermint/tendermint/issues/1758#issuecomment-545291698>

14
docs/architecture/adr-017-historical-header-module.md
View File

@ -2,8 +2,8 @@
## Changelog
- 26 November 2019: Start of first version
- 2 December 2019: Final draft of first version
* 26 November 2019: Start of first version
* 2 December 2019: Final draft of first version
## Context
@ -44,13 +44,13 @@ Implementation of this ADR will require changes to the Cosmos SDK. It will not r
### Positive
- Easy retrieval of headers & state roots for recent past heights by modules anywhere in the Cosmos SDK.
- No RPC calls to Tendermint required.
- No ABCI alterations required.
* Easy retrieval of headers & state roots for recent past heights by modules anywhere in the Cosmos SDK.
* No RPC calls to Tendermint required.
* No ABCI alterations required.
### Negative
- Duplicates `n` headers data in Tendermint & the application (additional disk usage) - in the long term, an approach such as [this](https://github.com/tendermint/tendermint/issues/4210) might be preferable.
* Duplicates `n` headers data in Tendermint & the application (additional disk usage) - in the long term, an approach such as [this](https://github.com/tendermint/tendermint/issues/4210) might be preferable.
### Neutral
@ -58,4 +58,4 @@ Implementation of this ADR will require changes to the Cosmos SDK. It will not r
## References
- [ICS 2: "Consensus state introspection"](https://github.com/cosmos/ibc/tree/master/spec/core/ics-002-client-semantics#consensus-state-introspection)
* [ICS 2: "Consensus state introspection"](https://github.com/cosmos/ibc/tree/master/spec/core/ics-002-client-semantics#consensus-state-introspection)

16
docs/architecture/adr-018-extendable-voting-period.md
View File

@ -2,7 +2,7 @@
## Changelog
- 1 January 2020: Start of first version
* 1 January 2020: Start of first version
## Context
@ -18,8 +18,8 @@ Thus, we propose the following mechanism:
### Params
- The current gov param `VotingPeriod` is to be replaced by a `MinVotingPeriod` param. This is the the default voting period that all governance proposal voting periods start with.
- There is a new gov param called `MaxVotingPeriodExtension`.
* The current gov param `VotingPeriod` is to be replaced by a `MinVotingPeriod` param. This is the the default voting period that all governance proposal voting periods start with.
* There is a new gov param called `MaxVotingPeriodExtension`.
### Mechanism
@ -50,17 +50,17 @@ Proposed
### Positive
- More complex/contentious governance proposals will have more time to properly digest and deliberate
* More complex/contentious governance proposals will have more time to properly digest and deliberate
### Negative
- Governance process becomes more complex and requires more understanding to interact with effectively
- Can no longer predict when a governance proposal will end. Can't assume order in which governance proposals will end.
* Governance process becomes more complex and requires more understanding to interact with effectively
* Can no longer predict when a governance proposal will end. Can't assume order in which governance proposals will end.
### Neutral
- The minimum voting period can be made shorter
* The minimum voting period can be made shorter
## References
- [Cosmos Forum post where idea first originated](https://forum.cosmos.network/t/proposal-draft-reduce-governance-voting-period-to-7-days/3032/9)
* [Cosmos Forum post where idea first originated](https://forum.cosmos.network/t/proposal-draft-reduce-governance-voting-period-to-7-days/3032/9)

56
docs/architecture/adr-019-protobuf-state-encoding.md
View File

@ -2,12 +2,12 @@
## Changelog
- 2020 Feb 15: Initial Draft
- 2020 Feb 24: Updates to handle messages with interface fields
- 2020 Apr 27: Convert usages of `oneof` for interfaces to `Any`
- 2020 May 15: Describe `cosmos_proto` extensions and amino compatibility
- 2020 Dec 4: Move and rename `MarshalAny` and `UnmarshalAny` into the `codec.Codec` interface.
- 2021 Feb 24: Remove mentions of `HybridCodec`, which has been abandoned in [#6843](https://github.com/cosmos/cosmos-sdk/pull/6843).
* 2020 Feb 15: Initial Draft
* 2020 Feb 24: Updates to handle messages with interface fields
* 2020 Apr 27: Convert usages of `oneof` for interfaces to `Any`
* 2020 May 15: Describe `cosmos_proto` extensions and amino compatibility
* 2020 Dec 4: Move and rename `MarshalAny` and `UnmarshalAny` into the `codec.Codec` interface.
* 2021 Feb 24: Remove mentions of `HybridCodec`, which has been abandoned in [#6843](https://github.com/cosmos/cosmos-sdk/pull/6843).
## Status
@ -28,9 +28,9 @@ From the Amino docs:
Amino also aims to have the following goals (not a complete list):
- Binary bytes must be decode-able with a schema.
- Schema must be upgradeable.
- The encoder and decoder logic must be reasonably simple.
* Binary bytes must be decode-able with a schema.
* Schema must be upgradeable.
* The encoder and decoder logic must be reasonably simple.
However, we believe that Amino does not fulfill these goals completely and does not fully meet the
needs of a truly flexible cross-language and multi-client compatible encoding protocol in the Cosmos SDK.
@ -42,13 +42,13 @@ largely reflected in the performance of simulations and application transaction
Thus, we need to adopt an encoding protocol that meets the following criteria for state serialization:
- Language agnostic
- Platform agnostic
- Rich client support and thriving ecosystem
- High performance
- Minimal encoded message size
- Codegen-based over reflection-based
- Supports backward and forward compatibility
* Language agnostic
* Platform agnostic
* Rich client support and thriving ecosystem
* High performance
* Minimal encoded message size
* Codegen-based over reflection-based
* Supports backward and forward compatibility
Note, migrating away from Amino should be viewed as a two-pronged approach, state and client encoding.
This ADR focuses on state serialization in the Cosmos SDK state machine. A corresponding ADR will be
@ -62,8 +62,8 @@ applications wishing to continue to use Amino. We will provide this mechanism by
accept a codec interface, `Marshaler`, instead of a concrete Amino codec. Furthermore, the Cosmos SDK
will provide two concrete implementations of the `Marshaler` interface: `AminoCodec` and `ProtoCodec`.
- `AminoCodec`: Uses Amino for both binary and JSON encoding.
- `ProtoCodec`: Uses Protobuf for both binary and JSON encoding.
* `AminoCodec`: Uses Amino for both binary and JSON encoding.
* `ProtoCodec`: Uses Protobuf for both binary and JSON encoding.
Modules will use whichever codec that is instantiated in the app. By default, the Cosmos SDK's `simapp`
instantiates a `ProtoCodec` as the concrete implementation of `Marshaler`, inside the `MakeTestEncodingConfig`
@ -320,11 +320,11 @@ have been registered properly with Amino).
In order for this functionality to work:
- **all legacy code must use `*codec.LegacyAmino` instead of `*amino.Codec` which is
* **all legacy code must use `*codec.LegacyAmino` instead of `*amino.Codec` which is
now a wrapper which properly handles `Any`**
- **all new code should use `Marshaler` which is compatible with both amino and
* **all new code should use `Marshaler` which is compatible with both amino and
protobuf**
- Also, before v0.39, `codec.LegacyAmino` will be renamed to `codec.LegacyAmino`.
* Also, before v0.39, `codec.LegacyAmino` will be renamed to `codec.LegacyAmino`.
### Why Wasn't X Chosen Instead
@ -361,19 +361,19 @@ seamless.
### Positive
- Significant performance gains.
- Supports backward and forward type compatibility.
- Better support for cross-language clients.
* Significant performance gains.
* Supports backward and forward type compatibility.
* Better support for cross-language clients.
### Negative
- Learning curve required to understand and implement Protobuf messages.
- Slightly larger message size due to use of `Any`, although this could be offset
* Learning curve required to understand and implement Protobuf messages.
* Slightly larger message size due to use of `Any`, although this could be offset
by a compression layer in the future
### Neutral
## References
1. https://github.com/cosmos/cosmos-sdk/issues/4977
2. https://github.com/cosmos/cosmos-sdk/issues/5444
1. <https://github.com/cosmos/cosmos-sdk/issues/4977>
2. <https://github.com/cosmos/cosmos-sdk/issues/5444>

108
docs/architecture/adr-020-protobuf-transaction-encoding.md
View File

@ -2,19 +2,19 @@
## Changelog
- 2020 March 06: Initial Draft
- 2020 March 12: API Updates
- 2020 April 13: Added details on interface `oneof` handling
- 2020 April 30: Switch to `Any`
- 2020 May 14: Describe public key encoding
- 2020 June 08: Store `TxBody` and `AuthInfo` as bytes in `SignDoc`; Document `TxRaw` as broadcast and storage type.
- 2020 August 07: Use ADR 027 for serializing `SignDoc`.
- 2020 August 19: Move sequence field from `SignDoc` to `SignerInfo`, as discussed in [#6966](https://github.com/cosmos/cosmos-sdk/issues/6966).
- 2020 September 25: Remove `PublicKey` type in favor of `secp256k1.PubKey`, `ed25519.PubKey` and `multisig.LegacyAminoPubKey`.
- 2020 October 15: Add `GetAccount` and `GetAccountWithHeight` methods to the `AccountRetriever` interface.
- 2021 Feb 24: The Cosmos SDK does not use Tendermint's `PubKey` interface anymore, but its own `cryptotypes.PubKey`. Updates to reflect this.
- 2021 May 3: Rename `clientCtx.JSONMarshaler` to `clientCtx.JSONCodec`.
- 2021 June 10: Add `clientCtx.Codec: codec.Codec`.
* 2020 March 06: Initial Draft
* 2020 March 12: API Updates
* 2020 April 13: Added details on interface `oneof` handling
* 2020 April 30: Switch to `Any`
* 2020 May 14: Describe public key encoding
* 2020 June 08: Store `TxBody` and `AuthInfo` as bytes in `SignDoc`; Document `TxRaw` as broadcast and storage type.
* 2020 August 07: Use ADR 027 for serializing `SignDoc`.
* 2020 August 19: Move sequence field from `SignDoc` to `SignerInfo`, as discussed in [#6966](https://github.com/cosmos/cosmos-sdk/issues/6966).
* 2020 September 25: Remove `PublicKey` type in favor of `secp256k1.PubKey`, `ed25519.PubKey` and `multisig.LegacyAminoPubKey`.
* 2020 October 15: Add `GetAccount` and `GetAccountWithHeight` methods to the `AccountRetriever` interface.
* 2021 Feb 24: The Cosmos SDK does not use Tendermint's `PubKey` interface anymore, but its own `cryptotypes.PubKey`. Updates to reflect this.
* 2021 May 3: Rename `clientCtx.JSONMarshaler` to `clientCtx.JSONCodec`.
* 2021 June 10: Add `clientCtx.Codec: codec.Codec`.
## Status
@ -168,9 +168,9 @@ attempt to upstream important improvements to `Tx`.
All of the signing modes below aim to provide the following guarantees:
- **No Malleability**: `TxBody` and `AuthInfo` cannot change once the transaction
* **No Malleability**: `TxBody` and `AuthInfo` cannot change once the transaction
is signed
- **Predictable Gas**: if I am signing a transaction where I am paying a fee,
* **Predictable Gas**: if I am signing a transaction where I am paying a fee,
the final gas is fully dependent on what I am signing
These guarantees give the maximum amount confidence to message signers that
@ -181,9 +181,9 @@ manipulation of `Tx`s by intermediaries can't result in any meaningful changes.
The "direct" signing behavior is to sign the raw `TxBody` bytes as broadcast over
the wire. This has the advantages of:
- requiring the minimum additional client capabilities beyond a standard protocol
* requiring the minimum additional client capabilities beyond a standard protocol
buffers implementation
- leaving effectively zero holes for transaction malleability (i.e. there are no
* leaving effectively zero holes for transaction malleability (i.e. there are no
subtle differences between the signing and encoding formats which could
potentially be exploited by an attacker)
@ -219,10 +219,10 @@ Signature verifiers do:
1. Deserialize a `TxRaw` and pull out `body` and `auth_info`.
2. Create a list of required signer addresses from the messages.
3. For each required signer:
- Pull account number and sequence from the state.
- Obtain the public key either from state or `AuthInfo`'s `signer_infos`.
- Create a `SignDoc` and serialize it using [ADR 027](./adr-027-deterministic-protobuf-serialization.md).
- Verify the signature at the the same list position against the serialized `SignDoc`.
* Pull account number and sequence from the state.
* Obtain the public key either from state or `AuthInfo`'s `signer_infos`.
* Create a `SignDoc` and serialize it using [ADR 027](./adr-027-deterministic-protobuf-serialization.md).
* Verify the signature at the the same list position against the serialized `SignDoc`.
#### `SIGN_MODE_LEGACY_AMINO`
@ -263,14 +263,14 @@ by `SIGN_MODE_TEXTUAL` when it is implemented.
Unknown fields in protobuf messages should generally be rejected by transaction
processors because:
- important data may be present in the unknown fields, that if ignored, will
* important data may be present in the unknown fields, that if ignored, will
cause unexpected behavior for clients
- they present a malleability vulnerability where attackers can bloat tx size
* they present a malleability vulnerability where attackers can bloat tx size
by adding random uninterpreted data to unsigned content (i.e. the master `Tx`,
not `TxBody`)
There are also scenarios where we may choose to safely ignore unknown fields
(https://github.com/cosmos/cosmos-sdk/issues/6078#issuecomment-624400188) to
(<https://github.com/cosmos/cosmos-sdk/issues/6078#issuecomment-624400188>) to
provide graceful forwards compatibility with newer clients.
We propose that field numbers with bit 11 set (for most use cases this is
@ -279,9 +279,9 @@ ignored if unknown.
To handle this we will need a unknown field filter that:
- always rejects unknown fields in unsigned content (i.e. top-level `Tx` and
* always rejects unknown fields in unsigned content (i.e. top-level `Tx` and
unsigned parts of `AuthInfo` if present based on the signing mode)
- rejects unknown fields in all messages (including nested `Any`s) other than
* rejects unknown fields in all messages (including nested `Any`s) other than
fields with bit 11 set
This will likely need to be a custom protobuf parser pass that takes message bytes
@ -379,7 +379,7 @@ can gracefully transition away from Amino JSON.
### `SIGN_MODE_DIRECT_AUX`
(\*Documented as option (3) in https://github.com/cosmos/cosmos-sdk/issues/6078#issuecomment-628026933)
(\*Documented as option (3) in <https://github.com/cosmos/cosmos-sdk/issues/6078#issuecomment-628026933>)
We could add a mode `SIGN_MODE_DIRECT_AUX`
to support scenarios where multiple signatures
@ -408,27 +408,27 @@ To generate a signature in `SIGN_MODE_DIRECT_AUX` these steps would be followed:
1. Encode `SignDocAux` (with the same requirement that fields must be serialized
in order):
```proto
// types/types.proto
message SignDocAux {
bytes body_bytes = 1;
// PublicKey is included in SignDocAux :
// 1. as a special case for multisig public keys. For multisig public keys,
// the signer should use the top-level multisig public key they are signing
// against, not their own public key. This is to prevent against a form
// of malleability where a signature could be taken out of context of the
// multisig key that was intended to be signed for
// 2. to guard against scenario where configuration information is encoded
// in public keys (it has been proposed) such that two keys can generate
// the same signature but have different security properties
//
// By including it here, the composer of AuthInfo cannot reference the
// a public key variant the signer did not intend to use
PublicKey public_key = 2;
string chain_id = 3;
uint64 account_number = 4;
}
```
```proto
// types/types.proto
message SignDocAux {
bytes body_bytes = 1;
// PublicKey is included in SignDocAux :
// 1. as a special case for multisig public keys. For multisig public keys,
// the signer should use the top-level multisig public key they are signing
// against, not their own public key. This is to prevent against a form
// of malleability where a signature could be taken out of context of the
// multisig key that was intended to be signed for
// 2. to guard against scenario where configuration information is encoded
// in public keys (it has been proposed) such that two keys can generate
// the same signature but have different security properties
//
// By including it here, the composer of AuthInfo cannot reference the
// a public key variant the signer did not intend to use
PublicKey public_key = 2;
string chain_id = 3;
uint64 account_number = 4;
}
```
2. Sign the encoded `SignDocAux` bytes
3. Send their signature and `SignerInfo` to primary signer who will then
@ -437,7 +437,7 @@ message SignDocAux {
### `SIGN_MODE_DIRECT_RELAXED`
(_Documented as option (1)(a) in https://github.com/cosmos/cosmos-sdk/issues/6078#issuecomment-628026933_)
(_Documented as option (1)(a) in <https://github.com/cosmos/cosmos-sdk/issues/6078#issuecomment-628026933>_)
This is a variation of `SIGN_MODE_DIRECT` where multiple signers wouldn't need to
coordinate public keys and signing modes in advance. It would involve an alternate
@ -449,14 +449,14 @@ too burdensome.
### Positive
- Significant performance gains.
- Supports backward and forward type compatibility.
- Better support for cross-language clients.
- Multiple signing modes allow for greater protocol evolution
* Significant performance gains.
* Supports backward and forward type compatibility.
* Better support for cross-language clients.
* Multiple signing modes allow for greater protocol evolution
### Negative
- `google.protobuf.Any` type URLs increase transaction size although the effect
* `google.protobuf.Any` type URLs increase transaction size although the effect
may be negligible or compression may be able to mitigate it.
### Neutral

2
docs/architecture/adr-021-protobuf-query-encoding.md
View File

@ -2,7 +2,7 @@
## Changelog
- 2020 March 27: Initial Draft
* 2020 March 27: Initial Draft
## Status

20
docs/architecture/adr-022-custom-panic-handling.md
View File

@ -2,8 +2,8 @@
## Changelog
- 2020 Apr 24: Initial Draft
- 2021 Sep 14: Superseded by ADR-045
* 2020 Apr 24: Initial Draft
* 2021 Sep 14: Superseded by ADR-045
## Status
@ -196,23 +196,23 @@ This method would prepend handlers to an existing chain.
### Positive
- Developers of Cosmos SDK based projects can add custom panic handlers to:
* Developers of Cosmos SDK based projects can add custom panic handlers to:
* add error context for custom panic sources (panic inside of custom keepers);
* emit `panic()`: passthrough recovery object to the Tendermint core;
* other necessary handling;
- Developers can use standard Cosmos SDK `BaseApp` implementation, rather that rewriting it in their projects;
- Proposed solution doesn't break the current "standard" `runTx()` flow;
* Developers can use standard Cosmos SDK `BaseApp` implementation, rather that rewriting it in their projects;
* Proposed solution doesn't break the current "standard" `runTx()` flow;
### Negative
- Introduces changes to the execution model design.
* Introduces changes to the execution model design.
### Neutral
- `OutOfGas` error handler becomes one of the middlewares;
- Default panic handler becomes one of the middlewares;
* `OutOfGas` error handler becomes one of the middlewares;
* Default panic handler becomes one of the middlewares;
## References
- [PR-6053 with proposed solution](https://github.com/cosmos/cosmos-sdk/pull/6053)
- [Similar solution. ADR-010 Modular AnteHandler](https://github.com/cosmos/cosmos-sdk/blob/v0.38.3/docs/architecture/adr-010-modular-antehandler.md)
* [PR-6053 with proposed solution](https://github.com/cosmos/cosmos-sdk/pull/6053)
* [Similar solution. ADR-010 Modular AnteHandler](https://github.com/cosmos/cosmos-sdk/blob/v0.38.3/docs/architecture/adr-010-modular-antehandler.md)

12
docs/architecture/adr-023-protobuf-naming.md
View File

@ -2,8 +2,8 @@
## Changelog
- 2020 April 27: Initial Draft
- 2020 August 5: Update guidelines
* 2020 April 27: Initial Draft
* 2020 August 5: Update guidelines
## Status
@ -132,13 +132,13 @@ The following guidelines are recommended for marking packages as alpha or beta:
* marking something as `alpha` or `beta` should be a last resort and just putting something in the
stable package (i.e. `v1` or `v2`) should be preferred
* a package *should* be marked as `alpha` *if and only if* there are active discussions to remove
* a package _should_ be marked as `alpha` _if and only if_ there are active discussions to remove
or significantly alter the package in the near future
* a package *should* be marked as `beta` *if and only if* there is an active discussion to
* a package _should_ be marked as `beta` _if and only if_ there is an active discussion to
significantly refactor/rework the functionality in the near future but not remove it
* modules *can and should* have types in both stable (i.e. `v1` or `v2`) and unstable (`alpha` or `beta`) packages.
* modules _can and should_ have types in both stable (i.e. `v1` or `v2`) and unstable (`alpha` or `beta`) packages.
*`alpha` and `beta` should not be used to avoid responsibility for maintaining compatibility.*
_`alpha` and `beta` should not be used to avoid responsibility for maintaining compatibility._
Whenever code is released into the wild, especially on a blockchain, there is a high cost to changing things. In some
cases, for instance with immutable smart contracts, a breaking change may be impossible to fix.

12
docs/architecture/adr-024-coin-metadata.md
View File

@ -2,7 +2,7 @@
## Changelog
- 05/19/2020: Initial draft
* 05/19/2020: Initial draft
## Status
@ -93,9 +93,9 @@ As an example, the ATOM's metadata can be defined as follows:
Given the above metadata, a client may infer the following things:
- 4.3atom = 4.3 * (10^6) = 4,300,000uatom
- The string "atom" can be used as a display name in a list of tokens.
- The balance 4300000 can be displayed as 4,300,000uatom or 4,300matom or 4.3atom.
* 4.3atom = 4.3 * (10^6) = 4,300,000uatom
* The string "atom" can be used as a display name in a list of tokens.
* The balance 4300000 can be displayed as 4,300,000uatom or 4,300matom or 4.3atom.
The `display` denomination 4.3atom is a good default if the authors of the client don't make
an explicit decision to choose a different representation.
@ -124,13 +124,13 @@ via an endpoint, we may consider supporting automatic conversion of a given unit
### Positive
- Provides clients, wallet providers and block explorers with additional data on
* Provides clients, wallet providers and block explorers with additional data on
asset denomination to improve UX and remove any need to make assumptions on
denomination units.
### Negative
- A small amount of required additional storage in the `x/bank` module. The amount
* A small amount of required additional storage in the `x/bank` module. The amount
of additional storage should be minimal as the amount of total assets should not
be large.

56
docs/architecture/adr-027-deterministic-protobuf-serialization.md
View File

@ -2,8 +2,8 @@
## Changelog
- 2020-08-07: Initial Draft
- 2020-09-01: Further clarify rules
* 2020-08-07: Initial Draft
* 2020-09-01: Further clarify rules
## Status
@ -126,12 +126,12 @@ default value).
There are three main implementation strategies, ordered from the least to the
most custom development:
- **Use a protobuf serializer that follows the above rules by default.** E.g.
* **Use a protobuf serializer that follows the above rules by default.** E.g.
[gogoproto](https://pkg.go.dev/github.com/gogo/protobuf/gogoproto) is known to
be compliant by in most cases, but not when certain annotations such as
`nullable = false` are used. It might also be an option to configure an
existing serializer accordingly.
- **Normalize default values before encoding them.** If your serializer follows
* **Normalize default values before encoding them.** If your serializer follows
rule 1. and 2. and allows you to explicitly unset fields for serialization,
you can normalize default values to unset. This can be done when working with
[protobuf.js](https://www.npmjs.com/package/protobufjs):
@ -146,7 +146,7 @@ most custom development:
}).finish();
```
- **Use a hand-written serializer for the types you need.** If none of the above
* **Use a hand-written serializer for the types you need.** If none of the above
ways works for you, you can write a serializer yourself. For SignDoc this
would look something like this in Go, building on existing protobuf utilities:
@ -231,14 +231,14 @@ backlinks: []
must result in the serialization
```
```text
0a1b54686520776f726c64206e65656473206368616e676520f09f8cb318e8bebec8bc2e280138024a084e696365206f6e654a095468616e6b20796f75
```
When inspecting the serialized document, you see that every second field is
omitted:
```
```sh
$ echo 0a1b54686520776f726c64206e65656473206368616e676520f09f8cb318e8bebec8bc2e280138024a084e696365206f6e654a095468616e6b20796f75 | xxd -r -p | protoc --decode_raw
1: "The world needs change \360\237\214\263"
3: 1596806111080
@ -255,20 +255,20 @@ for all protobuf documents we need in the context of Cosmos SDK signing.
### Positive
- Well defined rules that can be verified independent of a reference
* Well defined rules that can be verified independent of a reference
implementation
- Simple enough to keep the barrier to implement transaction signing low
- It allows us to continue to use 0 and other empty values in SignDoc, avoiding
* Simple enough to keep the barrier to implement transaction signing low
* It allows us to continue to use 0 and other empty values in SignDoc, avoiding
the need to work around 0 sequences. This does not imply the change from
https://github.com/cosmos/cosmos-sdk/pull/6949 should not be merged, but not
<https://github.com/cosmos/cosmos-sdk/pull/6949> should not be merged, but not
too important anymore.
### Negative
- When implementing transaction signing, the encoding rules above must be
* When implementing transaction signing, the encoding rules above must be
understood and implemented.
- The need for rule number 3. adds some complexity to implementations.
- Some data structures may require custom code for serialization. Thus
* The need for rule number 3. adds some complexity to implementations.
* Some data structures may require custom code for serialization. Thus
the code is not very portable - it will require additional work for each
client implementing serialization to properly handle custom data structures.
@ -283,32 +283,32 @@ the need of implementing a custom serializer that adheres to this standard (and
## References
- <sup>1</sup> _When a message is serialized, there is no guaranteed order for
* <sup>1</sup> _When a message is serialized, there is no guaranteed order for
how its known or unknown fields should be written. Serialization order is an
implementation detail and the details of any particular implementation may
change in the future. Therefore, protocol buffer parsers must be able to parse
fields in any order._ from
https://developers.google.com/protocol-buffers/docs/encoding#order
- <sup>2</sup> https://developers.google.com/protocol-buffers/docs/encoding#signed_integers
- <sup>3</sup> _Note that for scalar message fields, once a message is parsed
<https://developers.google.com/protocol-buffers/docs/encoding#order>
* <sup>2</sup> <https://developers.google.com/protocol-buffers/docs/encoding#signed_integers>
* <sup>3</sup> _Note that for scalar message fields, once a message is parsed
there's no way of telling whether a field was explicitly set to the default
value (for example whether a boolean was set to false) or just not set at all:
you should bear this in mind when defining your message types. For example,
don't have a boolean that switches on some behavior when set to false if you
don't want that behavior to also happen by default._ from
https://developers.google.com/protocol-buffers/docs/proto3#default
- <sup>4</sup> _When a message is parsed, if the encoded message does not
<https://developers.google.com/protocol-buffers/docs/proto3#default>
* <sup>4</sup> _When a message is parsed, if the encoded message does not
contain a particular singular element, the corresponding field in the parsed
object is set to the default value for that field._ from
https://developers.google.com/protocol-buffers/docs/proto3#default
- <sup>5</sup> _Also note that if a scalar message field is set to its default,
<https://developers.google.com/protocol-buffers/docs/proto3#default>
* <sup>5</sup> _Also note that if a scalar message field is set to its default,
the value will not be serialized on the wire._ from
https://developers.google.com/protocol-buffers/docs/proto3#default
- <sup>6</sup> _For enums, the default value is the first defined enum value,
<https://developers.google.com/protocol-buffers/docs/proto3#default>
* <sup>6</sup> _For enums, the default value is the first defined enum value,
which must be 0._ from
https://developers.google.com/protocol-buffers/docs/proto3#default
- <sup>7</sup> _For message fields, the field is not set. Its exact value is
<https://developers.google.com/protocol-buffers/docs/proto3#default>
* <sup>7</sup> _For message fields, the field is not set. Its exact value is
language-dependent._ from
https://developers.google.com/protocol-buffers/docs/proto3#default
- Encoding rules and parts of the reasoning taken from
<https://developers.google.com/protocol-buffers/docs/proto3#default>
* Encoding rules and parts of the reasoning taken from
[canonical-proto3 Aaron Craelius](https://github.com/regen-network/canonical-proto3)

98
docs/architecture/adr-028-public-key-addresses.md
View File

@ -2,8 +2,8 @@
## Changelog
- 2020/08/18: Initial version
- 2021/01/15: Analysis and algorithm update
* 2020/08/18: Initial version
* 2021/01/15: Analysis and algorithm update
## Status
@ -29,12 +29,12 @@ a security break of one account type shouldn't impact the security of other acco
One initial proposal was extending the address length and
adding prefixes for different types of addresses.
@ethanfrey explained an alternate approach originally used in https://github.com/iov-one/weave:
@ethanfrey explained an alternate approach originally used in <https://github.com/iov-one/weave>:
> I spent quite a bit of time thinking about this issue while building weave... The other cosmos Sdk.
> Basically I define a condition to be a type and format as human readable string with some binary data appended. This condition is hashed into an Address (again at 20 bytes). The use of this prefix makes it impossible to find a preimage for a given address with a different condition (eg ed25519 vs secp256k1).
> This is explained in depth here https://weave.readthedocs.io/en/latest/design/permissions.html
> And the code is here, look mainly at the top where we process conditions. https://github.com/iov-one/weave/blob/master/conditions.go
> This is explained in depth here <https://weave.readthedocs.io/en/latest/design/permissions.html>
> And the code is here, look mainly at the top where we process conditions. <https://github.com/iov-one/weave/blob/master/conditions.go>
And explained how this approach should be sufficiently collision resistant:
@ -53,15 +53,15 @@ This disqualifies the initial proposal.
In the issue we discussed various modifications:
+ Choice of the hash function.
+ Move the prefix out of the hash function: `keyTypePrefix + sha256(keybytes)[:20]` [post-hash-prefix-proposal].
+ Use double hashing: `sha256(keyTypePrefix + sha256(keybytes)[:20])`.
+ Increase to keybytes hash slice from 20 byte to 32 or 40 bytes. We concluded that 32 bytes, produced by a good hash functions is future secure.
* Choice of the hash function.
* Move the prefix out of the hash function: `keyTypePrefix + sha256(keybytes)[:20]` [post-hash-prefix-proposal].
* Use double hashing: `sha256(keyTypePrefix + sha256(keybytes)[:20])`.
* Increase to keybytes hash slice from 20 byte to 32 or 40 bytes. We concluded that 32 bytes, produced by a good hash functions is future secure.
### Requirements
+ Support currently used tools - we don't want to break an ecosystem, or add a long adaptation period. Ref: https://github.com/cosmos/cosmos-sdk/issues/8041
+ Try to keep the address length small - addresses are widely used in state, both as part of a key and object value.
* Support currently used tools - we don't want to break an ecosystem, or add a long adaptation period. Ref: <https://github.com/cosmos/cosmos-sdk/issues/8041>
* Try to keep the address length small - addresses are widely used in state, both as part of a key and object value.
### Scope
@ -82,8 +82,8 @@ We define the following account types, for which we define the address function:
Currently (Jan 2021), the only officially supported Cosmos SDK user accounts are `secp256k1` basic accounts and legacy amino multisig.
They are used in existing Cosmos SDK zones. They use the following address formats:
- secp256k1: `ripemd160(sha256(pk_bytes))[:20]`
- legacy amino multisig: `sha256(aminoCdc.Marshal(pk))[:20]`
* secp256k1: `ripemd160(sha256(pk_bytes))[:20]`
* legacy amino multisig: `sha256(aminoCdc.Marshal(pk))[:20]`
We don't want to change existing addresses. So the addresses for these two key types will remain the same.
@ -118,8 +118,8 @@ We use the `address.Hash` function for generating addresses for all accounts rep
* simple public keys: `address.Hash(keyType, pubkey)`
+ aggregated keys (eg: BLS): `address.Hash(keyType, aggregatedPubKey)`
+ modules: `address.Hash("module", moduleName)`
* aggregated keys (eg: BLS): `address.Hash(keyType, aggregatedPubKey)`
* modules: `address.Hash("module", moduleName)`
### Composed Addresses
@ -196,13 +196,13 @@ func Module(moduleName string, key []byte) []byte{
**Example** A lending BTC pool address would be:
```
```go
btcPool := address.Module("lending", btc.Addrress()})
```
If we want to create an address for a module account depending on more than one key, we can concatenate them:
```
```go
btcAtomAMM := address.Module("amm", btc.Addrress() + atom.Address()})
```
@ -220,7 +220,7 @@ Note: `Module` is a special case of the more general _derived_ address, where we
**Example** For a cosmwasm smart-contract address we could use the following construction:
```
```go
smartContractAddr := Derived(Module("cosmwasm", smartContractsNamespace), []{smartContractKey})
```
@ -252,21 +252,21 @@ This ADR is compatible with what was committed and directly supported in the Cos
### Positive
- a simple algorithm for generating addresses for new public keys, complex accounts and modules
- the algorithm generalizes _native composed keys_
- increased security and collision resistance of addresses
- the approach is extensible for future use-cases - one can use other address types, as long as they don't conflict with the address length specified here (20 or 32 bytes).
- support new account types.
* a simple algorithm for generating addresses for new public keys, complex accounts and modules
* the algorithm generalizes _native composed keys_
* increased security and collision resistance of addresses
* the approach is extensible for future use-cases - one can use other address types, as long as they don't conflict with the address length specified here (20 or 32 bytes).
* support new account types.
### Negative
- addresses do not communicate key type, a prefixed approach would have done this
- addresses are 60% longer and will consume more storage space
- requires a refactor of KVStore store keys to handle variable length addresses
* addresses do not communicate key type, a prefixed approach would have done this
* addresses are 60% longer and will consume more storage space
* requires a refactor of KVStore store keys to handle variable length addresses
### Neutral
- protobuf message names are used as key type prefixes
* protobuf message names are used as key type prefixes
## Further Discussions
@ -280,50 +280,50 @@ End of Dec 2020 we had a session with [Alan Szepieniec](https://scholar.google.b
Alan general observations:
+ we don’t need 2-preimage resistance
+ we need 32bytes address space for collision resistance
+ when an attacker can control an input for object with an address then we have a problem with birthday attack
+ there is an issue with smart-contracts for hashing
+ sha2 mining can be use to breaking address pre-image
* we don’t need 2-preimage resistance
* we need 32bytes address space for collision resistance
* when an attacker can control an input for object with an address then we have a problem with birthday attack
* there is an issue with smart-contracts for hashing
* sha2 mining can be use to breaking address pre-image
Hashing algorithm
+ any attack breaking blake3 will break blake2
+ Alan is pretty confident about the current security analysis of the blake hash algorithm. It was a finalist, and the author is well known in security analysis.
* any attack breaking blake3 will break blake2
* Alan is pretty confident about the current security analysis of the blake hash algorithm. It was a finalist, and the author is well known in security analysis.
Algorithm:
+ Alan recommends to hash the prefix: `address(pub_key) = hash(hash(key_type) + pub_key)[:32]`, main benefits:
+ we are free to user arbitrary long prefix names
+ we still don’t risk collisions
+ switch tables
+ discussion about penalization -> about adding prefix post hash
+ Aaron asked about post hash prefixes (`address(pub_key) = key_type + hash(pub_key)`) and differences. Alan noted that this approach has longer address space and it’s stronger.
* Alan recommends to hash the prefix: `address(pub_key) = hash(hash(key_type) + pub_key)[:32]`, main benefits:
* we are free to user arbitrary long prefix names
* we still don’t risk collisions
* switch tables
* discussion about penalization -> about adding prefix post hash
* Aaron asked about post hash prefixes (`address(pub_key) = key_type + hash(pub_key)`) and differences. Alan noted that this approach has longer address space and it’s stronger.
Algorithm for complex / composed keys:
+ merging tree like addresses with same algorithm are fine
* merging tree like addresses with same algorithm are fine
Module addresses: Should module addresses have different size to differentiate it?
+ we will need to set a pre-image prefix for module addresse to keept them in 32-byte space: `hash(hash('module') + module_key)`
+ Aaron observation: we already need to deal with variable length (to not break secp256k1 keys).
* we will need to set a pre-image prefix for module addresse to keept them in 32-byte space: `hash(hash('module') + module_key)`
* Aaron observation: we already need to deal with variable length (to not break secp256k1 keys).
Discssion about arithmetic hash function for ZKP
+ Posseidon / Rescue
+ Problem: much bigger risk because we don’t know much techniques and history of crypto-analysis of arithmetic constructions. It’s still a new ground and area of active research.
* Posseidon / Rescue
* Problem: much bigger risk because we don’t know much techniques and history of crypto-analysis of arithmetic constructions. It’s still a new ground and area of active research.
Post quantum signature size
+ Alan suggestion: Falcon: speed / size ration - very good.
+ Aaron - should we think about it?
* Alan suggestion: Falcon: speed / size ration - very good.
* Aaron - should we think about it?
Alan: based on early extrapolation this thing will get able to break EC cryptography in 2050 . But that’s a lot of uncertainty. But there is magic happening with recurions / linking / simulation and that can speedup the progress.
Other ideas
+ Let’s say we use same key and two different address algorithms for 2 different use cases. Is it still safe to use it? Alan: if we want to hide the public key (which is not our use case), then it’s less secure but there are fixes.
* Let’s say we use same key and two different address algorithms for 2 different use cases. Is it still safe to use it? Alan: if we want to hide the public key (which is not our use case), then it’s less secure but there are fixes.
### References
+ [Notes](https://hackmd.io/_NGWI4xZSbKzj1BkCqyZMw)
* [Notes](https://hackmd.io/_NGWI4xZSbKzj1BkCqyZMw)

14
docs/architecture/adr-029-fee-grant-module.md
View File

@ -2,8 +2,8 @@
## Changelog
- 2020/08/18: Initial Draft
- 2021/05/05: Removed height based expiration support and simplified naming.
* 2020/08/18: Initial Draft
* 2021/05/05: Removed height based expiration support and simplified naming.
## Status
@ -137,17 +137,17 @@ set and correctly deduct fees based on fee allowances.
### Positive
- improved UX for use cases where it is cumbersome to maintain an account balance just for fees
* improved UX for use cases where it is cumbersome to maintain an account balance just for fees
### Negative
### Neutral
- a new field must be added to the transaction `Fee` message and a new `AnteDecorator` must be
* a new field must be added to the transaction `Fee` message and a new `AnteDecorator` must be
created to use it
## References
- Blog article describing initial work: https://medium.com/regen-network/hacking-the-cosmos-cosmwasm-and-key-management-a08b9f561d1b
- Initial public specification: https://gist.github.com/aaronc/b60628017352df5983791cad30babe56
- Original subkeys proposal from B-harvest which influenced this design: https://github.com/cosmos/cosmos-sdk/issues/4480
* Blog article describing initial work: <https://medium.com/regen-network/hacking-the-cosmos-cosmwasm-and-key-management-a08b9f561d1b>
* Initial public specification: <https://gist.github.com/aaronc/b60628017352df5983791cad30babe56>
* Original subkeys proposal from B-harvest which influenced this design: <https://github.com/cosmos/cosmos-sdk/issues/4480>

22
docs/architecture/adr-030-authz-module.md
View File

@ -2,10 +2,10 @@
## Changelog
- 2019-11-06: Initial Draft
- 2020-10-12: Updated Draft
- 2020-11-13: Accepted
- 2020-05-06: proto API updates, use `sdk.Msg` instead of `sdk.ServiceMsg` (the latter concept was removed from Cosmos SDK)
* 2019-11-06: Initial Draft
* 2020-10-12: Updated Draft
* 2020-11-13: Accepted
* 2020-05-06: proto API updates, use `sdk.Msg` instead of `sdk.ServiceMsg` (the latter concept was removed from Cosmos SDK)
## Status
@ -20,9 +20,9 @@ on behalf of that account to other accounts.
The concrete use cases which motivated this module include:
- the desire to delegate the ability to vote on proposals to other accounts besides the account which one has
* the desire to delegate the ability to vote on proposals to other accounts besides the account which one has
delegated stake
- "sub-keys" functionality, as originally proposed in [\#4480](https://github.com/cosmos/cosmos-sdk/issues/4480) which
* "sub-keys" functionality, as originally proposed in [\#4480](https://github.com/cosmos/cosmos-sdk/issues/4480) which
is a term used to describe the functionality provided by this module together with
the `fee_grant` module from [ADR 029](./adr-029-fee-grant-module.md) and the [group module](https://github.com/regen-network/cosmos-modules/tree/master/incubator/group).
@ -232,9 +232,9 @@ message GenericAuthorization {
### Positive
- Users will be able to authorize arbitrary actions on behalf of their accounts to other
* Users will be able to authorize arbitrary actions on behalf of their accounts to other
users, improving key management for many use cases
- The solution is more generic than previously considered approaches and the
* The solution is more generic than previously considered approaches and the
`Authorization` interface approach can be extended to cover other use cases by
SDK users
@ -244,6 +244,6 @@ SDK users
## References
- Initial Hackatom implementation: https://github.com/cosmos-gaians/cosmos-sdk/tree/hackatom/x/delegation
- Post-Hackatom spec: https://gist.github.com/aaronc/b60628017352df5983791cad30babe56#delegation-module
- B-Harvest subkeys spec: https://github.com/cosmos/cosmos-sdk/issues/4480
* Initial Hackatom implementation: <https://github.com/cosmos-gaians/cosmos-sdk/tree/hackatom/x/delegation>
* Post-Hackatom spec: <https://gist.github.com/aaronc/b60628017352df5983791cad30babe56#delegation-module>
* B-Harvest subkeys spec: <https://github.com/cosmos/cosmos-sdk/issues/4480>

28
docs/architecture/adr-031-msg-service.md
View File

@ -2,8 +2,8 @@
## Changelog
- 2020-10-05: Initial Draft
- 2021-04-21: Remove `ServiceMsg`s to follow Protobuf `Any`'s spec, see [#9063](https://github.com/cosmos/cosmos-sdk/issues/9063).
* 2020-10-05: Initial Draft
* 2021-04-21: Remove `ServiceMsg`s to follow Protobuf `Any`'s spec, see [#9063](https://github.com/cosmos/cosmos-sdk/issues/9063).
## Status
@ -41,7 +41,7 @@ This isn’t really documented anywhere and clients would need to know the inter
of the Cosmos SDK to parse that value and return it to users.
Also, there may be cases where we want to use these return values programatically.
For instance, https://github.com/cosmos/cosmos-sdk/issues/7093 proposes a method for
For instance, <https://github.com/cosmos/cosmos-sdk/issues/7093> proposes a method for
doing inter-module Ocaps using the `Msg` router. A well-defined return type would
improve the developer UX for this approach.
@ -183,20 +183,20 @@ Finally, closing a module to client API opens desirable OCAP patterns discussed
### Pros
- communicates return type clearly
- manual handler registration and return type marshaling is no longer needed, just implement the interface and register it
- communication interface is automatically generated, the developer can now focus only on the state transition methods - this would improve the UX of [\#7093](https://github.com/cosmos/cosmos-sdk/issues/7093) approach (1) if we chose to adopt that
- generated client code could be useful for clients and tests
- dramatically reduces and simplifies the code
* communicates return type clearly
* manual handler registration and return type marshaling is no longer needed, just implement the interface and register it
* communication interface is automatically generated, the developer can now focus only on the state transition methods - this would improve the UX of [\#7093](https://github.com/cosmos/cosmos-sdk/issues/7093) approach (1) if we chose to adopt that
* generated client code could be useful for clients and tests
* dramatically reduces and simplifies the code
### Cons
- using `service` definitions outside the context of gRPC could be confusing (but doesn’t violate the proto3 spec)
* using `service` definitions outside the context of gRPC could be confusing (but doesn’t violate the proto3 spec)
## References
- [Initial Github Issue \#7122](https://github.com/cosmos/cosmos-sdk/issues/7122)
- [proto 3 Language Guide: Defining Services](https://developers.google.com/protocol-buffers/docs/proto3#services)
- [Initial pre-`Any` `Msg` designs](https://docs.google.com/document/d/1eEgYgvgZqLE45vETjhwIw4VOqK-5hwQtZtjVbiXnIGc)
- [ADR 020](./adr-020-protobuf-transaction-encoding.md)
- [ADR 021](./adr-021-protobuf-query-encoding.md)
* [Initial Github Issue \#7122](https://github.com/cosmos/cosmos-sdk/issues/7122)
* [proto 3 Language Guide: Defining Services](https://developers.google.com/protocol-buffers/docs/proto3#services)
* [Initial pre-`Any` `Msg` designs](https://docs.google.com/document/d/1eEgYgvgZqLE45vETjhwIw4VOqK-5hwQtZtjVbiXnIGc)
* [ADR 020](./adr-020-protobuf-transaction-encoding.md)
* [ADR 021](./adr-021-protobuf-query-encoding.md)

20
docs/architecture/adr-032-typed-events.md
View File

@ -2,13 +2,13 @@
## Changelog
- 28-Sept-2020: Initial Draft
* 28-Sept-2020: Initial Draft
## Authors
- Anil Kumar (@anilcse)
- Jack Zampolin (@jackzampolin)
- Adam Bozanich (@boz)
* Anil Kumar (@anilcse)
* Jack Zampolin (@jackzampolin)
* Adam Bozanich (@boz)
## Status
@ -34,7 +34,7 @@ This proposal is specifically about how to consume these events as a client of t
## Decision
__Step-1__: Implement additional functionality in the `types` package: `EmitTypedEvent` and `ParseTypedEvent` functions
**Step-1**: Implement additional functionality in the `types` package: `EmitTypedEvent` and `ParseTypedEvent` functions
```go
// types/events.go
@ -111,7 +111,7 @@ Here, the `EmitTypedEvent` is a method on `EventManager` which takes typed event
When we subscribe to emitted events on the tendermint websocket, they are emitted in the form of an `abci.Event`. `ParseTypedEvent` parses the event back to it's original proto message.
__Step-2__: Add proto definitions for typed events for msgs in each module:
**Step-2**: Add proto definitions for typed events for msgs in each module:
For example, let's take `MsgSubmitProposal` of `gov` module and implement this event's type.
@ -128,7 +128,7 @@ message EventSubmitProposal {
}
```
__Step-3__: Refactor event emission to use the typed event created and emit using `sdk.EmitTypedEvent`:
**Step-3**: Refactor event emission to use the typed event created and emit using `sdk.EmitTypedEvent`:
```go
// x/gov/handler.go
@ -145,7 +145,7 @@ func handleMsgSubmitProposal(ctx sdk.Context, keeper keeper.Keeper, msg types.Ms
}
```
#### How to subscribe to these typed events in `Client`
### How to subscribe to these typed events in `Client`
> NOTE: Full code example below
@ -315,5 +315,5 @@ func PublishChainTxEvents(ctx context.Context, client tmclient.EventsClient, bus
## References
- [Publish Custom Events via a bus](https://github.com/ovrclk/akash/blob/90d258caeb933b611d575355b8df281208a214f8/events/publish.go#L19-L58)
- [Consuming the events in `Client`](https://github.com/ovrclk/deploy/blob/bf6c633ab6c68f3026df59efd9982d6ca1bf0561/cmd/event-handlers.go#L57)
* [Publish Custom Events via a bus](https://github.com/ovrclk/akash/blob/90d258caeb933b611d575355b8df281208a214f8/events/publish.go#L19-L58)
* [Consuming the events in `Client`](https://github.com/ovrclk/deploy/blob/bf6c633ab6c68f3026df59efd9982d6ca1bf0561/cmd/event-handlers.go#L57)

34
docs/architecture/adr-033-protobuf-inter-module-comm.md
View File

@ -2,7 +2,7 @@
## Changelog
- 2020-10-05: Initial Draft
* 2020-10-05: Initial Draft
## Status
@ -14,9 +14,9 @@ This ADR introduces a system for permissioned inter-module communication leverag
service definitions defined in [ADR 021](./adr-021-protobuf-query-encoding.md) and
[ADR 031](./adr-031-msg-service.md) which provides:
- stable protobuf based module interfaces to potentially later replace the keeper paradigm
- stronger inter-module object capabilities (OCAPs) guarantees
- module accounts and sub-account authorization
* stable protobuf based module interfaces to potentially later replace the keeper paradigm
* stronger inter-module object capabilities (OCAPs) guarantees
* module accounts and sub-account authorization
## Context
@ -99,8 +99,8 @@ transaction
This mechanism has the added benefits of:
- reducing boilerplate through code generation, and
- allowing for modules in other languages either via a VM like CosmWasm or sub-processes using gRPC
* reducing boilerplate through code generation, and
* allowing for modules in other languages either via a VM like CosmWasm or sub-processes using gRPC
### Inter-module Communication
@ -376,16 +376,16 @@ replacing `Keeper` interfaces altogether.
### Positive
- an alternative to keepers which can more easily lead to stable inter-module interfaces
- proper inter-module OCAPs
- improved module developer DevX, as commented on by several particpants on
* an alternative to keepers which can more easily lead to stable inter-module interfaces
* proper inter-module OCAPs
* improved module developer DevX, as commented on by several particpants on
[Architecture Review Call, Dec 3](https://hackmd.io/E0wxxOvRQ5qVmTf6N_k84Q)
- lays the groundwork for what can be a greatly simplified `app.go`
- router can be setup to enforce atomic transactions for module-to-module calls
* lays the groundwork for what can be a greatly simplified `app.go`
* router can be setup to enforce atomic transactions for module-to-module calls
### Negative
- modules which adopt this will need significant refactoring
* modules which adopt this will need significant refactoring
### Neutral
@ -393,8 +393,8 @@ replacing `Keeper` interfaces altogether.
## References
- [ADR 021](./adr-021-protobuf-query-encoding.md)
- [ADR 031](./adr-031-msg-service.md)
- [ADR 028](./adr-028-public-key-addresses.md)
- [ADR 030 draft](https://github.com/cosmos/cosmos-sdk/pull/7105)
- [Object-Capability Model](../docs/core/ocap.md)
* [ADR 021](./adr-021-protobuf-query-encoding.md)
* [ADR 031](./adr-031-msg-service.md)
* [ADR 028](./adr-028-public-key-addresses.md)
* [ADR 030 draft](https://github.com/cosmos/cosmos-sdk/pull/7105)
* [Object-Capability Model](../docs/core/ocap.md)

4
docs/architecture/adr-034-account-rekeying.md
View File

@ -2,7 +2,7 @@
## Changelog
- 30-09-2020: Initial Draft
* 30-09-2020: Initial Draft
## Status
@ -73,4 +73,4 @@ Breaks the current assumed relationship between address and pubkeys as H(pubkey)
## References
+ https://www.algorand.com/resources/blog/announcing-rekeying
* <https://www.algorand.com/resources/blog/announcing-rekeying>

16
docs/architecture/adr-035-rosetta-api-support.md
View File

@ -2,14 +2,14 @@
## Authors
- Jonathan Gimeno (@jgimeno)
- David Grierson (@senormonito)
- Alessio Treglia (@alessio)
- Frojdy Dymylja (@fdymylja)
* Jonathan Gimeno (@jgimeno)
* David Grierson (@senormonito)
* Alessio Treglia (@alessio)
* Frojdy Dymylja (@fdymylja)
## Changelog
- 2021-05-12: the external library [cosmos-rosetta-gateway](https://github.com/tendermint/cosmos-rosetta-gateway) has been moved within the Cosmos SDK.
* 2021-05-12: the external library [cosmos-rosetta-gateway](https://github.com/tendermint/cosmos-rosetta-gateway) has been moved within the Cosmos SDK.
## Context
@ -203,9 +203,9 @@ Proposed
### Positive
- Out-of-the-box Rosetta API support within Cosmos SDK.
- Blockchain interface standardisation
* Out-of-the-box Rosetta API support within Cosmos SDK.
* Blockchain interface standardisation
## References
- https://www.rosetta-api.org/
* <https://www.rosetta-api.org/>

42
docs/architecture/adr-036-arbitrary-signature.md
View File

@ -2,14 +2,14 @@
## Changelog
- 28/10/2020 - Initial draft
* 28/10/2020 - Initial draft
## Authors
- Antoine Herzog (@antoineherzog)
- Zaki Manian (@zmanian)
- Aleksandr Bezobchuk (alexanderbez) [1]
- Frojdi Dymylja (@fdymylja)
* Antoine Herzog (@antoineherzog)
* Zaki Manian (@zmanian)
* Aleksandr Bezobchuk (alexanderbez) [1]
* Frojdi Dymylja (@fdymylja)
## Status
@ -41,11 +41,11 @@ Create the `offchain` proto definitions, we extend the auth module with `offchai
An offchain transaction follows these rules:
- the memo must be empty
- nonce, sequence number must be equal to 0
- chain-id must be equal to “”
- fee gas must be equal to 0
- fee amount must be an empty array
* the memo must be empty
* nonce, sequence number must be equal to 0
* chain-id must be equal to “”
* fee gas must be equal to 0
* fee amount must be an empty array
Verification of an offchain transaction follows the same rules as an onchain one, except for the spec differences highlighted above.
@ -110,23 +110,23 @@ Backwards compatibility is maintained as this is a new message spec definition.
### Positive
- A common format that can be used by multiple applications to sign and verify off-chain messages.
- The specification is primitive which means it can cover every use case without limiting what is possible to fit inside it.
- It gives room for other off-chain messages specifications that aim to target more specific and common use cases such as off-chain-based authN/authZ layers [2].
* A common format that can be used by multiple applications to sign and verify off-chain messages.
* The specification is primitive which means it can cover every use case without limiting what is possible to fit inside it.
* It gives room for other off-chain messages specifications that aim to target more specific and common use cases such as off-chain-based authN/authZ layers [2].
### Negative
- Current proposal requires a fixed relationship between an account address and a public key.
- Doesn't work with multisig accounts.
* Current proposal requires a fixed relationship between an account address and a public key.
* Doesn't work with multisig accounts.
## Further discussion
- Regarding security in `MsgSignData`, the developer using `MsgSignData` is in charge of making the content laying in `Data` non-replayable when, and if, needed.
- the offchain package will be further extended with extra messages that target specific use cases such as, but not limited to, authentication in applications, payment channels, L2 solutions in general.
* Regarding security in `MsgSignData`, the developer using `MsgSignData` is in charge of making the content laying in `Data` non-replayable when, and if, needed.
* the offchain package will be further extended with extra messages that target specific use cases such as, but not limited to, authentication in applications, payment channels, L2 solutions in general.
## References
1. https://github.com/cosmos/ics/pull/33
2. https://github.com/cosmos/cosmos-sdk/pull/7727#discussion_r515668204
3. https://github.com/cosmos/cosmos-sdk/pull/7727#issuecomment-722478477
4. https://github.com/cosmos/cosmos-sdk/pull/7727#issuecomment-721062923
1. <https://github.com/cosmos/ics/pull/33>
2. <https://github.com/cosmos/cosmos-sdk/pull/7727#discussion_r515668204>
3. <https://github.com/cosmos/cosmos-sdk/pull/7727#issuecomment-722478477>
4. <https://github.com/cosmos/cosmos-sdk/pull/7727#issuecomment-721062923>

22
docs/architecture/adr-037-gov-split-vote.md
View File

@ -2,7 +2,7 @@
## Changelog
- 2020/10/28: Intial draft
* 2020/10/28: Intial draft
## Status
@ -22,7 +22,7 @@ However, often times the entity owning that address might not be a single indivi
We modify the vote structs to be
```
```go
type WeightedVoteOption struct {
Option string
Weight sdk.Dec
@ -37,7 +37,7 @@ type Vote struct {
And for backwards compatibility, we introduce `MsgVoteWeighted` while keeping `MsgVote`.
```
```go
type MsgVote struct {
ProposalID int64
Voter sdk.Address
@ -58,7 +58,7 @@ The `ValidateBasic` of a `MsgVoteWeighted` struct would require that
The governance tally function will iterate over all the options in a vote and add to the tally the result of the voter's voting power * the rate for that option.
```
```go
tally() {
results := map[types.VoteOption]sdk.Dec
@ -78,7 +78,7 @@ simd tx gov vote 1 "yes=0.6,no=0.3,abstain=0.05,no_with_veto=0.05" --from mykey
To create a single-option vote a user can do either
```
```sh
simd tx gov vote 1 "yes=1" --from mykey
```
@ -94,18 +94,18 @@ to maintain backwards compatibility.
### Backwards Compatibility
- Previous VoteMsg types will remain the same and so clients will not have to update their procedure unless they want to support the WeightedVoteMsg feature.
- When querying a Vote struct from state, its structure will be different, and so clients wanting to display all voters and their respective votes will have to handle the new format and the fact that a single voter can have split votes.
- The result of querying the tally function should have the same API for clients.
* Previous VoteMsg types will remain the same and so clients will not have to update their procedure unless they want to support the WeightedVoteMsg feature.
* When querying a Vote struct from state, its structure will be different, and so clients wanting to display all voters and their respective votes will have to handle the new format and the fact that a single voter can have split votes.
* The result of querying the tally function should have the same API for clients.
### Positive
- Can make the voting process more accurate for addresses representing multiple stakeholders, often some of the largest addresses.
* Can make the voting process more accurate for addresses representing multiple stakeholders, often some of the largest addresses.
### Negative
- Is more complex than simple voting, and so may be harder to explain to users. However, this is mostly mitigated because the feature is opt-in.
* Is more complex than simple voting, and so may be harder to explain to users. However, this is mostly mitigated because the feature is opt-in.
### Neutral
- Relatively minor change to governance tally function.
* Relatively minor change to governance tally function.

12
docs/architecture/adr-038-state-listening.md
View File

@ -2,7 +2,7 @@
## Changelog
- 11/23/2020: Initial draft
* 11/23/2020: Initial draft
## Status
@ -535,17 +535,17 @@ These changes will provide a means of subscribing to KVStore state changes in re
### Backwards Compatibility
- This ADR changes the `MultiStore`, `CacheWrap`, and `CacheWrapper` interfaces, implementations supporting the previous version of these interfaces will not support the new ones
* This ADR changes the `MultiStore`, `CacheWrap`, and `CacheWrapper` interfaces, implementations supporting the previous version of these interfaces will not support the new ones
### Positive
- Ability to listen to KVStore state changes in real time and expose these events to external consumers
* Ability to listen to KVStore state changes in real time and expose these events to external consumers
### Negative
- Changes `MultiStore`, `CacheWrap`, and `CacheWrapper` interfaces
* Changes `MultiStore`, `CacheWrap`, and `CacheWrapper` interfaces
### Neutral
- Introduces additional- but optional- complexity to configuring and running a cosmos application
- If an application developer opts to use these features to expose data, they need to be aware of the ramifications/risks of that data exposure as it pertains to the specifics of their application
* Introduces additional- but optional- complexity to configuring and running a cosmos application
* If an application developer opts to use these features to expose data, they need to be aware of the ramifications/risks of that data exposure as it pertains to the specifics of their application

36
docs/architecture/adr-039-epoched-staking.md
View File

@ -2,12 +2,12 @@
## Changelog
- 10-Feb-2021: Initial Draft
* 10-Feb-2021: Initial Draft
## Authors
- Dev Ojha (@valardragon)
- Sunny Aggarwal (@sunnya97)
* Dev Ojha (@valardragon)
* Sunny Aggarwal (@sunnya97)
## Status
@ -43,10 +43,10 @@ There is a design consideration for whether to apply a slash immediately or at t
Applying it immediately can be viewed as offering greater consensus layer security, at potential costs to the aforementioned usecases. The benefits of immediate slashing for consensus layer security can be all be obtained by executing the validator jailing immediately (thus removing it from the validator set), and delaying the actual slash change to the validator's weight until the epoch boundary. For the use cases mentioned above, workarounds can be integrated to avoid problems, as follows:
- For threshold based cryptography, this setting will have the threshold cryptography use the original epoch weights, while consensus has an update that lets it more rapidly benefit from additional security. If the threshold based cryptography blocks liveness of the chain, then we have effectively raised the liveness threshold of the remaining validators for the rest of the epoch. (Alternatively, jailed nodes could still contribute shares) This plan will fail in the extreme case that more than 1/3rd of the validators have been jailed within a single epoch. For such an extreme scenario, the chain already have its own custom incident response plan, and defining how to handle the threshold cryptography should be a part of that.
- For light client efficiency, there can be a bit included in the header indicating an intra-epoch slash (ala https://github.com/tendermint/spec/issues/199).
- For fairness of deterministic leader election, applying a slash or jailing within an epoch would break the guarantee we were seeking to provide. This then re-introduces a new (but significantly simpler) problem for trying to provide fairness guarantees. Namely, that validators can adversarially elect to remove themself from the set of proposers. From a security perspective, this could potentially be handled by two different mechanisms (or prove to still be too difficult to achieve). One is making a security statement acknowledging the ability for an adversary to force an ahead-of-time fixed threshold of users to drop out of the proposer set within an epoch. The second method would be to parameterize such that the cost of a slash within the epoch far outweights benefits due to being a proposer. However, this latter criterion is quite dubious, since being a proposer can have many advantageous side-effects in chains with complex state machines. (Namely, DeFi games such as Fomo3D)
- For staking derivative design, there is no issue introduced. This does not increase the state size of staking records, since whether a slash has occured is fully queryable given the validator address.
* For threshold based cryptography, this setting will have the threshold cryptography use the original epoch weights, while consensus has an update that lets it more rapidly benefit from additional security. If the threshold based cryptography blocks liveness of the chain, then we have effectively raised the liveness threshold of the remaining validators for the rest of the epoch. (Alternatively, jailed nodes could still contribute shares) This plan will fail in the extreme case that more than 1/3rd of the validators have been jailed within a single epoch. For such an extreme scenario, the chain already have its own custom incident response plan, and defining how to handle the threshold cryptography should be a part of that.
* For light client efficiency, there can be a bit included in the header indicating an intra-epoch slash (ala <https://github.com/tendermint/spec/issues/199>).
* For fairness of deterministic leader election, applying a slash or jailing within an epoch would break the guarantee we were seeking to provide. This then re-introduces a new (but significantly simpler) problem for trying to provide fairness guarantees. Namely, that validators can adversarially elect to remove themself from the set of proposers. From a security perspective, this could potentially be handled by two different mechanisms (or prove to still be too difficult to achieve). One is making a security statement acknowledging the ability for an adversary to force an ahead-of-time fixed threshold of users to drop out of the proposer set within an epoch. The second method would be to parameterize such that the cost of a slash within the epoch far outweights benefits due to being a proposer. However, this latter criterion is quite dubious, since being a proposer can have many advantageous side-effects in chains with complex state machines. (Namely, DeFi games such as Fomo3D)
* For staking derivative design, there is no issue introduced. This does not increase the state size of staking records, since whether a slash has occured is fully queryable given the validator address.
### Token lockup
@ -73,36 +73,36 @@ Until an ABCI mechanism for variable block times is introduced, it is ill-advise
## Decision
__Step-1__: Implement buffering of all staking and slashing messages.
**Step-1**: Implement buffering of all staking and slashing messages.
First we create a pool for storing tokens that are being bonded, but should be applied at the epoch boundary called the `EpochDelegationPool`. Then, we have two separate queues, one for staking, one for slashing. We describe what happens on each message being delivered below:
### Staking messages
- **MsgCreateValidator**: Move user's self-bond to `EpochDelegationPool` immediately. Queue a message for the epoch boundary to handle the self-bond, taking the funds from the `EpochDelegationPool`. If Epoch execution fail, return back funds from `EpochDelegationPool` to user's account.
- **MsgEditValidator**: Validate message and if valid queue the message for execution at the end of the Epoch.
- **MsgDelegate**: Move user's funds to `EpochDelegationPool` immediately. Queue a message for the epoch boundary to handle the delegation, taking the funds from the `EpochDelegationPool`. If Epoch execution fail, return back funds from `EpochDelegationPool` to user's account.
- **MsgBeginRedelegate**: Validate message and if valid queue the message for execution at the end of the Epoch.
- **MsgUndelegate**: Validate message and if valid queue the message for execution at the end of the Epoch.
* **MsgCreateValidator**: Move user's self-bond to `EpochDelegationPool` immediately. Queue a message for the epoch boundary to handle the self-bond, taking the funds from the `EpochDelegationPool`. If Epoch execution fail, return back funds from `EpochDelegationPool` to user's account.
* **MsgEditValidator**: Validate message and if valid queue the message for execution at the end of the Epoch.
* **MsgDelegate**: Move user's funds to `EpochDelegationPool` immediately. Queue a message for the epoch boundary to handle the delegation, taking the funds from the `EpochDelegationPool`. If Epoch execution fail, return back funds from `EpochDelegationPool` to user's account.
* **MsgBeginRedelegate**: Validate message and if valid queue the message for execution at the end of the Epoch.
* **MsgUndelegate**: Validate message and if valid queue the message for execution at the end of the Epoch.
### Slashing messages
- **MsgUnjail**: Validate message and if valid queue the message for execution at the end of the Epoch.
- **Slash Event**: Whenever a slash event is created, it gets queued in the slashing module to apply at the end of the epoch. The queues should be setup such that this slash applies immediately.
* **MsgUnjail**: Validate message and if valid queue the message for execution at the end of the Epoch.
* **Slash Event**: Whenever a slash event is created, it gets queued in the slashing module to apply at the end of the epoch. The queues should be setup such that this slash applies immediately.
### Evidence Messages
- **MsgSubmitEvidence**: This gets executed immediately, and the validator gets jailed immediately. However in slashing, the actual slash event gets queued.
* **MsgSubmitEvidence**: This gets executed immediately, and the validator gets jailed immediately. However in slashing, the actual slash event gets queued.
Then we add methods to the end blockers, to ensure that at the epoch boundary the queues are cleared and delegation updates are applied.
__Step-2__: Implement querying of queued staking txs.
**Step-2**: Implement querying of queued staking txs.
When querying the staking activity of a given address, the status should return not only the amount of tokens staked, but also if there are any queued stake events for that address. This will require more work to be done in the querying logic, to trace the queued upcoming staking events.
As an initial implementation, this can be implemented as a linear search over all queued staking events. However, for chains that need long epochs, they should eventually build additional support for nodes that support querying to be able to produce results in constant time. (This is do-able by maintaining an auxilliary hashmap for indexing upcoming staking events by address)
__Step-3__: Adjust gas
**Step-3**: Adjust gas
Currently gas represents the cost of executing a transaction when its done immediately. (Merging together costs of p2p overhead, state access overhead, and computational overhead) However, now a transaction can cause computation in a future block, namely at the epoch boundary.

77
docs/architecture/adr-040-storage-and-smt-state-commitments.md
View File

@ -2,7 +2,7 @@
## Changelog
- 2020-01-15: Draft
* 2020-01-15: Draft
## Status
@ -19,11 +19,11 @@ Currently, Cosmos SDK uses IAVL for both state [commitments](https://cryptograph
IAVL has effectively become an orphaned project within the Cosmos ecosystem and it's proven to be an inefficient state commitment data structure.
In the current design, IAVL is used for both data storage and as a Merkle Tree for state commitments. IAVL is meant to be a standalone Merkelized key/value database, however it's using a KV DB engine to store all tree nodes. So, each node is stored in a separate record in the KV DB. This causes many inefficiencies and problems:
+ Each object query requires a tree traversal from the root. Subsequent queries for the same object are cached on the Cosmos SDK level.
+ Each edge traversal requires a DB query.
+ Creating snapshots is [expensive](https://github.com/cosmos/cosmos-sdk/issues/7215#issuecomment-684804950). It takes about 30 seconds to export less than 100 MB of state (as of March 2020).
+ Updates in IAVL may trigger tree reorganization and possible O(log(n)) hashes re-computation, which can become a CPU bottleneck.
+ The node structure is pretty expensive - it contains a standard tree node elements (key, value, left and right element) and additional metadata such as height, version (which is not required by the Cosmos SDK). The entire node is hashed, and that hash is used as the key in the underlying database, [ref](https://github.com/cosmos/iavl/blob/master/docs/node/node.md
* Each object query requires a tree traversal from the root. Subsequent queries for the same object are cached on the Cosmos SDK level.
* Each edge traversal requires a DB query.
* Creating snapshots is [expensive](https://github.com/cosmos/cosmos-sdk/issues/7215#issuecomment-684804950). It takes about 30 seconds to export less than 100 MB of state (as of March 2020).
* Updates in IAVL may trigger tree reorganization and possible O(log(n)) hashes re-computation, which can become a CPU bottleneck.
* The node structure is pretty expensive - it contains a standard tree node elements (key, value, left and right element) and additional metadata such as height, version (which is not required by the Cosmos SDK). The entire node is hashed, and that hash is used as the key in the underlying database, [ref](https://github.com/cosmos/iavl/blob/master/docs/node/node.md
).
Moreover, the IAVL project lacks support and a maintainer and we already see better and well-established alternatives. Instead of optimizing the IAVL, we are looking into other solutions for both storage and state commitments.
@ -54,18 +54,18 @@ We propose to use a KV database for both `SS` and `SC`. The store interface will
State Storage requirements:
+ range queries
+ quick (key, value) access
+ creating a snapshot
+ historical versioning
+ pruning (garbage collection)
* range queries
* quick (key, value) access
* creating a snapshot
* historical versioning
* pruning (garbage collection)
State Commitment requirements:
+ fast updates
+ tree path should be short
+ query historical commitment proofs using ICS-23 standard
+ pruning (garbage collection)
* fast updates
* tree path should be short
* query historical commitment proofs using ICS-23 standard
* pruning (garbage collection)
### SMT for State Commitment
@ -192,9 +192,9 @@ The presented workaround can be used until the IBC module is fully upgraded to s
We consider a compression of prefix keys by creating a mapping from module key to an integer, and serializing the integer using varint coding. Varint coding assures that different values don't have common byte prefix. For Merkle Proofs we can't use prefix compression - so it should only apply for the `SS` keys. Moreover, the prefix compression should be only applied for the module namespace. More precisely:
+ each module has it's own namespace;
+ when accessing a module namespace we create a KVStore with embedded prefix;
+ that prefix will be compressed only when accessing and managing `SS`.
* each module has it's own namespace;
* when accessing a module namespace we create a KVStore with embedded prefix;
* that prefix will be compressed only when accessing and managing `SS`.
We need to assure that the codes won't change. We can fix the mapping in a static variable (provided by an app) or SS state under a special key.
@ -209,10 +209,11 @@ TODO: finalize this or move to another ADR.
## Migration
Using the new store will require a migration. 2 Migrations are proposed:
1. Genesis export -- it will reset the blockchain history.
2. In place migration: we can reuse `UpgradeKeeper.SetUpgradeHandler` to provide the migration logic:
```go
```go
app.UpgradeKeeper.SetUpgradeHandler("adr-40", func(ctx sdk.Context, plan upgradetypes.Plan, vm module.VersionMap) (module.VersionMap, error) {
storev2.Migrate(iavlstore, v2.store)
@ -221,7 +222,7 @@ app.UpgradeKeeper.SetUpgradeHandler("adr-40", func(ctx sdk.Context, plan upgrade
// with the updated module ConsensusVersions
return app.mm.RunMigrations(ctx, vm)
})
```
```
The `Migrate` function will read all entries from a store/v1 DB and save them to the AD-40 combined KV store.
Cache layer should not be used and the operation must finish with a single Commit call.
@ -239,21 +240,21 @@ We change the storage layout of the state machine, a storage hard fork and netwo
### Positive
+ Decoupling state from state commitment introduce better engineering opportunities for further optimizations and better storage patterns.
+ Performance improvements.
+ Joining SMT based camp which has wider and proven adoption than IAVL. Example projects which decided on SMT: Ethereum2, Diem (Libra), Trillan, Tezos, Celestia.
+ Multistore removal fixes a longstanding issue with the current MultiStore design.
+ Simplifies merkle proofs - all modules, except IBC, have only one pass for merkle proof.
* Decoupling state from state commitment introduce better engineering opportunities for further optimizations and better storage patterns.
* Performance improvements.
* Joining SMT based camp which has wider and proven adoption than IAVL. Example projects which decided on SMT: Ethereum2, Diem (Libra), Trillan, Tezos, Celestia.
* Multistore removal fixes a longstanding issue with the current MultiStore design.
* Simplifies merkle proofs - all modules, except IBC, have only one pass for merkle proof.
### Negative
+ Storage migration
+ LL SMT doesn't support pruning - we will need to add and test that functionality.
+ `SS` keys will have an overhead of a key prefix. This doesn't impact `SC` because all keys in `SC` have same size (they are hashed).
* Storage migration
* LL SMT doesn't support pruning - we will need to add and test that functionality.
* `SS` keys will have an overhead of a key prefix. This doesn't impact `SC` because all keys in `SC` have same size (they are hashed).
### Neutral
+ Deprecating IAVL, which is one of the core proposals of Cosmos Whitepaper.
* Deprecating IAVL, which is one of the core proposals of Cosmos Whitepaper.
## Alternative designs
@ -277,12 +278,12 @@ We were discussing use case where modules can use a support database, which is n
## References
+ [IAVL What's Next?](https://github.com/cosmos/cosmos-sdk/issues/7100)
+ [IAVL overview](https://docs.google.com/document/d/16Z_hW2rSAmoyMENO-RlAhQjAG3mSNKsQueMnKpmcBv0/edit#heading=h.yd2th7x3o1iv) of it's state v0.15
+ [State commitments and storage report](https://paper.dropbox.com/published/State-commitments-and-storage-review--BDvA1MLwRtOx55KRihJ5xxLbBw-KeEB7eOd11pNrZvVtqUgL3h)
+ [Celestia (LazyLedger) SMT](https://github.com/lazyledger/smt)
+ Facebook Diem (Libra) SMT [design](https://developers.diem.com/papers/jellyfish-merkle-tree/2021-01-14.pdf)
+ [Trillian Revocation Transparency](https://github.com/google/trillian/blob/master/docs/papers/RevocationTransparency.pdf), [Trillian Verifiable Data Structures](https://github.com/google/trillian/blob/master/docs/papers/VerifiableDataStructures.pdf).
+ Design and implementation [discussion](https://github.com/cosmos/cosmos-sdk/discussions/8297).
+ [How to Upgrade IBC Chains and their Clients](https://github.com/cosmos/ibc-go/blob/main/docs/ibc/upgrades/quick-guide.md)
+ [ADR-40 Effect on IBC](https://github.com/cosmos/ibc-go/discussions/256)
* [IAVL What's Next?](https://github.com/cosmos/cosmos-sdk/issues/7100)
* [IAVL overview](https://docs.google.com/document/d/16Z_hW2rSAmoyMENO-RlAhQjAG3mSNKsQueMnKpmcBv0/edit#heading=h.yd2th7x3o1iv) of it's state v0.15
* [State commitments and storage report](https://paper.dropbox.com/published/State-commitments-and-storage-review--BDvA1MLwRtOx55KRihJ5xxLbBw-KeEB7eOd11pNrZvVtqUgL3h)
* [Celestia (LazyLedger) SMT](https://github.com/lazyledger/smt)
* Facebook Diem (Libra) SMT [design](https://developers.diem.com/papers/jellyfish-merkle-tree/2021-01-14.pdf)
* [Trillian Revocation Transparency](https://github.com/google/trillian/blob/master/docs/papers/RevocationTransparency.pdf), [Trillian Verifiable Data Structures](https://github.com/google/trillian/blob/master/docs/papers/VerifiableDataStructures.pdf).
* Design and implementation [discussion](https://github.com/cosmos/cosmos-sdk/discussions/8297).
* [How to Upgrade IBC Chains and their Clients](https://github.com/cosmos/ibc-go/blob/main/docs/ibc/upgrades/quick-guide.md)
* [ADR-40 Effect on IBC](https://github.com/cosmos/ibc-go/discussions/256)

36
docs/architecture/adr-041-in-place-store-migrations.md
View File

@ -2,7 +2,7 @@
## Changelog
- 17.02.2021: Initial Draft
* 17.02.2021: Initial Draft
## Status
@ -18,8 +18,8 @@ When a chain upgrade introduces state-breaking changes inside modules, the curre
This procedure is cumbersome for multiple reasons:
- The procedure takes time. It can take hours to run the `export` command, plus some additional hours to run `InitChain` on the fresh chain using the migrated JSON.
- The exported JSON file can be heavy (~100MB-1GB), making it difficult to view, edit and transfer, which in turn introduces additional work to solve these problems (such as [streaming genesis](https://github.com/cosmos/cosmos-sdk/issues/6936)).
* The procedure takes time. It can take hours to run the `export` command, plus some additional hours to run `InitChain` on the fresh chain using the migrated JSON.
* The exported JSON file can be heavy (~100MB-1GB), making it difficult to view, edit and transfer, which in turn introduces additional work to solve these problems (such as [streaming genesis](https://github.com/cosmos/cosmos-sdk/issues/6936)).
## Decision
@ -81,7 +81,7 @@ Each module's migration functions are specific to the module's store evolutions,
We introduce a new prefix store in `x/upgrade`'s store. This store will track each module's current version, it can be modelized as a `map[string]uint64` of module name to module ConsensusVersion, and will be used when running the migrations (see next section for details). The key prefix used is `0x1`, and the key/value format is:
```
```text
0x2 | {bytes(module_name)} => BigEndian(module_consensus_version)
```
@ -116,10 +116,10 @@ A gRPC query endpoint to query the `VersionMap` stored in `x/upgrade`'s state wi
Once all the migration handlers are registered inside the configurator (which happens at startup), running migrations can happen by calling the `RunMigrations` method on `module.Manager`. This function will loop through all modules, and for each module:
- Get the old ConsensusVersion of the module from its `VersionMap` argument (let's call it `M`).
- Fetch the new ConsensusVersion of the module from the `ConsensusVersion()` method on `AppModule` (call it `N`).
- If `N>M`, run all registered migrations for the module sequentially `M -> M+1 -> M+2...` until `N`.
- There is a special case where there is no ConsensusVersion for the module, as this means that the module has been newly added during the upgrade. In this case, no migration function is run, and the module's current ConsensusVersion is saved to `x/upgrade`'s store.
* Get the old ConsensusVersion of the module from its `VersionMap` argument (let's call it `M`).
* Fetch the new ConsensusVersion of the module from the `ConsensusVersion()` method on `AppModule` (call it `N`).
* If `N>M`, run all registered migrations for the module sequentially `M -> M+1 -> M+2...` until `N`.
* There is a special case where there is no ConsensusVersion for the module, as this means that the module has been newly added during the upgrade. In this case, no migration function is run, and the module's current ConsensusVersion is saved to `x/upgrade`'s store.
If a required migration is missing (e.g. if it has not been registered in the `Configurator`), then the `RunMigrations` function will error.
@ -133,8 +133,8 @@ app.UpgradeKeeper.SetUpgradeHandler("my-plan", func(ctx sdk.Context, plan upgrad
Assuming a chain upgrades at block `n`, the procedure should run as follows:
- the old binary will halt in `BeginBlock` when starting block `N`. In its store, the ConsensusVersions of the old binary's modules are stored.
- the new binary will start at block `N`. The UpgradeHandler is set in the new binary, so will run at `BeginBlock` of the new binary. Inside `x/upgrade`'s `ApplyUpgrade`, the `VersionMap` will be retrieved from the (old binary's) store, and passed into the `RunMigrations` functon, migrating all module stores in-place before the modules' own `BeginBlock`s.
* the old binary will halt in `BeginBlock` when starting block `N`. In its store, the ConsensusVersions of the old binary's modules are stored.
* the new binary will start at block `N`. The UpgradeHandler is set in the new binary, so will run at `BeginBlock` of the new binary. Inside `x/upgrade`'s `ApplyUpgrade`, the `VersionMap` will be retrieved from the (old binary's) store, and passed into the `RunMigrations` functon, migrating all module stores in-place before the modules' own `BeginBlock`s.
## Consequences
@ -146,22 +146,22 @@ While modules MUST register their migration functions when bumping ConsensusVers
### Positive
- Perform chain upgrades without manipulating JSON files.
- While no benchmark has been made yet, it is probable that in-place store migrations will take less time than JSON migrations. The main reason supporting this claim is that both the `simd export` command on the old binary and the `InitChain` function on the new binary will be skipped.
* Perform chain upgrades without manipulating JSON files.
* While no benchmark has been made yet, it is probable that in-place store migrations will take less time than JSON migrations. The main reason supporting this claim is that both the `simd export` command on the old binary and the `InitChain` function on the new binary will be skipped.
### Negative
- Module developers MUST correctly track consensus-breaking changes in their modules. If a consensus-breaking change is introduced in a module without its corresponding `ConsensusVersion()` bump, then the `RunMigrations` function won't detect the migration, and the chain upgrade might be unsuccessful. Documentation should clearly reflect this.
* Module developers MUST correctly track consensus-breaking changes in their modules. If a consensus-breaking change is introduced in a module without its corresponding `ConsensusVersion()` bump, then the `RunMigrations` function won't detect the migration, and the chain upgrade might be unsuccessful. Documentation should clearly reflect this.
### Neutral
- The Cosmos SDK will continue to support JSON migrations via the existing `simd export` and `simd migrate` commands.
- The current ADR does not allow creating, renaming or deleting stores, only modifying existing store keys and values. The Cosmos SDK already has the `StoreLoader` for those operations.
* The Cosmos SDK will continue to support JSON migrations via the existing `simd export` and `simd migrate` commands.
* The current ADR does not allow creating, renaming or deleting stores, only modifying existing store keys and values. The Cosmos SDK already has the `StoreLoader` for those operations.
## Further Discussions
## References
- Initial discussion: https://github.com/cosmos/cosmos-sdk/discussions/8429
- Implementation of `ConsensusVersion` and `RunMigrations`: https://github.com/cosmos/cosmos-sdk/pull/8485
- Issue discussing `x/upgrade` design: https://github.com/cosmos/cosmos-sdk/issues/8514
* Initial discussion: <https://github.com/cosmos/cosmos-sdk/discussions/8429>
* Implementation of `ConsensusVersion` and `RunMigrations`: <https://github.com/cosmos/cosmos-sdk/pull/8485>
* Issue discussing `x/upgrade` design: <https://github.com/cosmos/cosmos-sdk/issues/8514>

42
docs/architecture/adr-042-group-module.md
View File

@ -2,7 +2,7 @@
## Changelog
- 2020/04/09: Initial Draft
* 2020/04/09: Initial Draft
## Status
@ -16,15 +16,15 @@ This ADR defines the `x/group` module which allows the creation and management o
The legacy amino multi-signature mechanism of the Cosmos SDK has certain limitations:
- Key rotation is not possible, although this can be solved with [account rekeying](adr-034-account-rekeying.md).
- Thresholds can't be changed.
- UX is cumbersome for non-technical users ([#5661](https://github.com/cosmos/cosmos-sdk/issues/5661)).
- It requires `legacy_amino` sign mode ([#8141](https://github.com/cosmos/cosmos-sdk/issues/8141)).
* Key rotation is not possible, although this can be solved with [account rekeying](adr-034-account-rekeying.md).
* Thresholds can't be changed.
* UX is cumbersome for non-technical users ([#5661](https://github.com/cosmos/cosmos-sdk/issues/5661)).
* It requires `legacy_amino` sign mode ([#8141](https://github.com/cosmos/cosmos-sdk/issues/8141)).
While the group module is not meant to be a total replacement for the current multi-signature accounts, it provides a solution to the limitations described above, with a more flexible key management system where keys can be added, updated or removed, as well as configurable thresholds.
It's meant to be used with other access control modules such as [`x/feegrant`](./adr-029-fee-grant-module.md) ans [`x/authz`](adr-030-authz-module.md) to simplify key management for individuals and organizations.
The proof of concept of the group module can be found in https://github.com/regen-network/regen-ledger/tree/master/proto/regen/group/v1alpha1 and https://github.com/regen-network/regen-ledger/tree/master/x/group.
The proof of concept of the group module can be found in <https://github.com/regen-network/regen-ledger/tree/master/proto/regen/group/v1alpha1> and <https://github.com/regen-network/regen-ledger/tree/master/x/group>.
## Decision
@ -187,9 +187,9 @@ passes as well as any metadata associated with the proposal. These `sdk.Msg`s ge
Internally, a proposal also tracks:
- its current `Status`: submitted, closed or aborted
- its `Result`: unfinalized, accepted or rejected
- its `VoteState` in the form of a `Tally`, which is calculated on new votes and when executing the proposal.
* its current `Status`: submitted, closed or aborted
* its `Result`: unfinalized, accepted or rejected
* its `VoteState` in the form of a `Tally`, which is calculated on new votes and when executing the proposal.
```proto
// Tally represents the sum of weighted votes.
@ -254,26 +254,26 @@ Inter-module communication introduced by [ADR-033](adr-033-protobuf-inter-module
### Positive
- Improved UX for multi-signature accounts allowing key rotation and custom decision policies.
* Improved UX for multi-signature accounts allowing key rotation and custom decision policies.
### Negative
### Neutral
- It uses ADR 033 so it will need to be implemented within the Cosmos SDK, but this doesn't imply necessarily any large refactoring of existing Cosmos SDK modules.
- The current implementation of the group module uses the ORM package.
* It uses ADR 033 so it will need to be implemented within the Cosmos SDK, but this doesn't imply necessarily any large refactoring of existing Cosmos SDK modules.
* The current implementation of the group module uses the ORM package.
## Further Discussions
- Convergence of `/group` and `x/gov` as both support proposals and voting: https://github.com/cosmos/cosmos-sdk/discussions/9066
- `x/group` possible future improvements:
- Execute proposals on submission (https://github.com/regen-network/regen-ledger/issues/288)
- Withdraw a proposal (https://github.com/regen-network/cosmos-modules/issues/41)
- Make `Tally` more flexible and support non-binary choices
* Convergence of `/group` and `x/gov` as both support proposals and voting: <https://github.com/cosmos/cosmos-sdk/discussions/9066>
* `x/group` possible future improvements:
* Execute proposals on submission (<https://github.com/regen-network/regen-ledger/issues/288>)
* Withdraw a proposal (<https://github.com/regen-network/cosmos-modules/issues/41>)
* Make `Tally` more flexible and support non-binary choices
## References
- Initial specification:
- https://gist.github.com/aaronc/b60628017352df5983791cad30babe56#group-module
- [#5236](https://github.com/cosmos/cosmos-sdk/pull/5236)
- Proposal to add `x/group` into the Cosmos SDK: [#7633](https://github.com/cosmos/cosmos-sdk/issues/7633)
* Initial specification:
* <https://gist.github.com/aaronc/b60628017352df5983791cad30babe56#group-module>
* [#5236](https://github.com/cosmos/cosmos-sdk/pull/5236)
* Proposal to add `x/group` into the Cosmos SDK: [#7633](https://github.com/cosmos/cosmos-sdk/issues/7633)

87
docs/architecture/adr-043-nft-module.md
View File

@ -2,8 +2,8 @@
## Changelog
- 2021-05-01: Initial Draft
- 2021-07-02: Review updates
* 2021-05-01: Initial Draft
* 2021-07-02: Review updates
## Status
@ -13,22 +13,22 @@ PROPOSED
This ADR defines the `x/nft` module which is a generic implementation of NFTs, roughly "compatible" with ERC721. **Applications using the `x/nft` module must implement the following functions**:
- `MsgNewClass` - Receive the user's request to create a class, and call the `NewClass` of the `x/nft` module.
- `MsgUpdateClass` - Receive the user's request to update a class, and call the `UpdateClass` of the `x/nft` module.
- `MsgMintNFT` - Receive the user's request to mint a nft, and call the `MintNFT` of the `x/nft` module.
- `BurnNFT` - Receive the user's request to burn a nft, and call the `BurnNFT` of the `x/nft` module.
- `UpdateNFT` - Receive the user's request to update a nft, and call the `UpdateNFT` of the `x/nft` module.
* `MsgNewClass` - Receive the user's request to create a class, and call the `NewClass` of the `x/nft` module.
* `MsgUpdateClass` - Receive the user's request to update a class, and call the `UpdateClass` of the `x/nft` module.
* `MsgMintNFT` - Receive the user's request to mint a nft, and call the `MintNFT` of the `x/nft` module.
* `BurnNFT` - Receive the user's request to burn a nft, and call the `BurnNFT` of the `x/nft` module.
* `UpdateNFT` - Receive the user's request to update a nft, and call the `UpdateNFT` of the `x/nft` module.
## Context
NFTs are more than just crypto art, which is very helpful for accruing value to the Cosmos ecosystem. As a result, Cosmos Hub should implement NFT functions and enable a unified mechanism for storing and sending the ownership representative of NFTs as discussed in https://github.com/cosmos/cosmos-sdk/discussions/9065.
NFTs are more than just crypto art, which is very helpful for accruing value to the Cosmos ecosystem. As a result, Cosmos Hub should implement NFT functions and enable a unified mechanism for storing and sending the ownership representative of NFTs as discussed in <https://github.com/cosmos/cosmos-sdk/discussions/9065>.
As discussed in [#9065](https://github.com/cosmos/cosmos-sdk/discussions/9065), several potential solutions can be considered:
- irismod/nft and modules/incubator/nft
- CW721
- DID NFTs
- interNFT
* irismod/nft and modules/incubator/nft
* CW721
* DID NFTs
* interNFT
Since functions/use cases of NFTs are tightly connected with their logic, it is almost impossible to support all the NFTs' use cases in one Cosmos SDK module by defining and implementing different transaction types.
@ -41,10 +41,10 @@ The current design is based on the work done by [IRISnet team](https://github.co
We create a `x/nft` module, which contains the following functionality:
- Store NFTs and track their ownership.
- Expose `Keeper` interface for composing modules to transfer, mint and burn NFTs.
- Expose external `Message` interface for users to transfer ownership of their NFTs.
- Query NFTs and their supply information.
* Store NFTs and track their ownership.
* Expose `Keeper` interface for composing modules to transfer, mint and burn NFTs.
* Expose external `Message` interface for users to transfer ownership of their NFTs.
* Query NFTs and their supply information.
The proposed module is a base module for NFT app logic. It's goal it to provide a common layer for storage, basic transfer functionality and IBC. The module should not be used as a standalone.
Instead an app should create a specialized module to handle app specific logic (eg: NFT ID construction, royalty), user level minting and burning. Moreover an app specialized module should handle auxiliary data to support the app logic (eg indexes, ORM, business data).
@ -54,8 +54,9 @@ All data carried over IBC must be part of the `NFT` or `Class` type described be
### Types
We propose two main types:
+ `Class` -- describes NFT class. We can think about it as a smart contract address.
+ `NFT` -- object representing unique, non fungible asset. Each NFT is associated with a Class.
* `Class` -- describes NFT class. We can think about it as a smart contract address.
* `NFT` -- object representing unique, non fungible asset. Each NFT is associated with a Class.
#### Class
@ -73,13 +74,13 @@ message Class {
}
```
- `id` is an alphanumeric identifier of the NFT class; it is used as the primary index for storing the class; _required_
- `name` is a descriptive name of the NFT class; _optional_
- `symbol` is the symbol usually shown on exchanges for the NFT class; _optional_
- `description` is a detailed description of the NFT class; _optional_
- `uri` is a URI for the class metadata stored off chain. It should be a JSON file that contains metadata about the NFT class and NFT data schema ([OpenSea example](https://docs.opensea.io/docs/contract-level-metadata)); _optional_
- `uri_hash` is a hash of the document pointed by uri; _optional_
- `data` is app specific metadata of the class; _optional_
* `id` is an alphanumeric identifier of the NFT class; it is used as the primary index for storing the class; _required_
* `name` is a descriptive name of the NFT class; _optional_
* `symbol` is the symbol usually shown on exchanges for the NFT class; _optional_
* `description` is a detailed description of the NFT class; _optional_
* `uri` is a URI for the class metadata stored off chain. It should be a JSON file that contains metadata about the NFT class and NFT data schema ([OpenSea example](https://docs.opensea.io/docs/contract-level-metadata)); _optional_
* `uri_hash` is a hash of the document pointed by uri; _optional_
* `data` is app specific metadata of the class; _optional_
#### NFT
@ -95,16 +96,16 @@ message NFT {
}
```
- `class_id` is the identifier of the NFT class where the NFT belongs; _required_,`[a-zA-Z][a-zA-Z0-9/:-]{2,100}`
- `id` is an alphanumeric identifier of the NFT, unique within the scope of its class. It is specified by the creator of the NFT and may be expanded to use DID in the future. `class_id` combined with `id` uniquely identifies an NFT and is used as the primary index for storing the NFT; _required_,`[a-zA-Z][a-zA-Z0-9/:-]{2,100}`
* `class_id` is the identifier of the NFT class where the NFT belongs; _required_,`[a-zA-Z][a-zA-Z0-9/:-]{2,100}`
* `id` is an alphanumeric identifier of the NFT, unique within the scope of its class. It is specified by the creator of the NFT and may be expanded to use DID in the future. `class_id` combined with `id` uniquely identifies an NFT and is used as the primary index for storing the NFT; _required_,`[a-zA-Z][a-zA-Z0-9/:-]{2,100}`
```
```text
{class_id}/{id} --> NFT (bytes)
```
- `uri` is a URI for the NFT metadata stored off chain. Should point to a JSON file that contains metadata about this NFT (Ref: [ERC721 standard and OpenSea extension](https://docs.opensea.io/docs/metadata-standards)); _required_
- `uri_hash` is a hash of the document pointed by uri; _optional_
- `data` is an app specific data of the NFT. CAN be used by composing modules to specify additional properties of the NFT; _optional_
* `uri` is a URI for the NFT metadata stored off chain. Should point to a JSON file that contains metadata about this NFT (Ref: [ERC721 standard and OpenSea extension](https://docs.opensea.io/docs/metadata-standards)); _required_
* `uri_hash` is a hash of the document pointed by uri; _optional_
* `data` is an app specific data of the NFT. CAN be used by composing modules to specify additional properties of the NFT; _optional_
This ADR doesn't specify values that `data` can take; however, best practices recommend upper-level NFT modules clearly specify their contents. Although the value of this field doesn't provide the additional context required to manage NFT records, which means that the field can technically be removed from the specification, the field's existence allows basic informational/UI functionality.
@ -309,31 +310,31 @@ This specification conforms to the ERC-721 smart contract specification for NFT
### Positive
- NFT identifiers available on Cosmos Hub.
- Ability to build different NFT modules for the Cosmos Hub, e.g., ERC-721.
- NFT module which supports interoperability with IBC and other cross-chain infrastructures like Gravity Bridge
* NFT identifiers available on Cosmos Hub.
* Ability to build different NFT modules for the Cosmos Hub, e.g., ERC-721.
* NFT module which supports interoperability with IBC and other cross-chain infrastructures like Gravity Bridge
### Negative
+ New IBC app is required for x/nft
+ CW721 adapter is required
* New IBC app is required for x/nft
* CW721 adapter is required
### Neutral
- Other functions need more modules. For example, a custody module is needed for NFT trading function, a collectible module is needed for defining NFT properties.
* Other functions need more modules. For example, a custody module is needed for NFT trading function, a collectible module is needed for defining NFT properties.
## Further Discussions
For other kinds of applications on the Hub, more app-specific modules can be developed in the future:
- `x/nft/custody`: custody of NFTs to support trading functionality.
- `x/nft/marketplace`: selling and buying NFTs using sdk.Coins.
- `x/fractional`: a module to split an ownership of an asset (NFT or other assets) for multiple stakeholder. `x/group` should work for most of the cases.
* `x/nft/custody`: custody of NFTs to support trading functionality.
* `x/nft/marketplace`: selling and buying NFTs using sdk.Coins.
* `x/fractional`: a module to split an ownership of an asset (NFT or other assets) for multiple stakeholder. `x/group` should work for most of the cases.
Other networks in the Cosmos ecosystem could design and implement their own NFT modules for specific NFT applications and use cases.
## References
- Initial discussion: https://github.com/cosmos/cosmos-sdk/discussions/9065
- x/nft: initialize module: https://github.com/cosmos/cosmos-sdk/pull/9174
- [ADR 033](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-033-protobuf-inter-module-comm.md)
* Initial discussion: <https://github.com/cosmos/cosmos-sdk/discussions/9065>
* x/nft: initialize module: <https://github.com/cosmos/cosmos-sdk/pull/9174>
* [ADR 033](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-033-protobuf-inter-module-comm.md)

42
docs/architecture/adr-044-protobuf-updates-guidelines.md
View File

@ -2,8 +2,8 @@
## Changelog
- 28.06.2021: Initial Draft
- 02.12.2021: Add `Since:` comment for new fields
* 28.06.2021: Initial Draft
* 02.12.2021: Add `Since:` comment for new fields
## Status
@ -19,8 +19,8 @@ The Cosmos SDK maintains a set of [Protobuf definitions](https://github.com/cosm
When making changes to these Protobuf definitions, the Cosmos SDK currently only follows [Buf's](https://docs.buf.build/) recommendations. We noticed however that Buf's recommendations might still result in breaking changes in the SDK in some cases. For example:
- Adding fields to `Msg`s. Adding fields is a not a Protobuf spec-breaking operation. However, when adding new fields to `Msg`s, the unknown field rejection will throw an error when sending the new `Msg` to an older node.
- Marking fields as `reserved`. Protobuf proposes the `reserved` keyword for removing fields without the need to bump the package version. However, by doing so, client backwards compatibility is broken as Protobuf doesn't generate anything for `reserved` fields. See [#9446](https://github.com/cosmos/cosmos-sdk/issues/9446) for more details on this issue.
* Adding fields to `Msg`s. Adding fields is a not a Protobuf spec-breaking operation. However, when adding new fields to `Msg`s, the unknown field rejection will throw an error when sending the new `Msg` to an older node.
* Marking fields as `reserved`. Protobuf proposes the `reserved` keyword for removing fields without the need to bump the package version. However, by doing so, client backwards compatibility is broken as Protobuf doesn't generate anything for `reserved` fields. See [#9446](https://github.com/cosmos/cosmos-sdk/issues/9446) for more details on this issue.
Moreover, module developers often face other questions around Protobuf definitions such as "Can I rename a field?" or "Can I deprecate a field?" This ADR aims to answer all these questions by providing clear guidelines about allowed updates for Protobuf definitions.
@ -28,11 +28,11 @@ Moreover, module developers often face other questions around Protobuf definitio
We decide to keep [Buf's](https://docs.buf.build/) recommendations with the following exceptions:
- `UNARY_RPC`: the Cosmos SDK currently does not support streaming RPCs.
- `COMMENT_FIELD`: the Cosmos SDK allows fields with no comments.
- `SERVICE_SUFFIX`: we use the `Query` and `Msg` service naming convention, which doesn't use the `-Service` suffix.
- `PACKAGE_VERSION_SUFFIX`: some packages, such as `cosmos.crypto.ed25519`, don't use a version suffix.
- `RPC_REQUEST_STANDARD_NAME`: Requests for the `Msg` service don't have the `-Request` suffix to keep backwards compatibility.
* `UNARY_RPC`: the Cosmos SDK currently does not support streaming RPCs.
* `COMMENT_FIELD`: the Cosmos SDK allows fields with no comments.
* `SERVICE_SUFFIX`: we use the `Query` and `Msg` service naming convention, which doesn't use the `-Service` suffix.
* `PACKAGE_VERSION_SUFFIX`: some packages, such as `cosmos.crypto.ed25519`, don't use a version suffix.
* `RPC_REQUEST_STANDARD_NAME`: Requests for the `Msg` service don't have the `-Request` suffix to keep backwards compatibility.
On top of Buf's recommendations we add the following guidelines that are specific to the Cosmos SDK.
@ -86,8 +86,8 @@ Protobuf supports the [`deprecated` field option](https://developers.google.com/
As an example, the Cosmos SDK v0.42 to v0.43 update contained two Protobuf-breaking changes, listed below. Instead of bumping the package versions from `v1beta1` to `v1`, the SDK team decided to follow this guideline, by reverting the breaking changes, marking those changes as deprecated, and modifying the node implementation when processing messages with deprecated fields. More specifically:
- The Cosmos SDK recently removed support for [time-based software upgrades](https://github.com/cosmos/cosmos-sdk/pull/8849). As such, the `time` field has been marked as deprecated in `cosmos.upgrade.v1beta1.Plan`. Moreover, the node will reject any proposal containing an upgrade Plan whose `time` field is non-empty.
- The Cosmos SDK now supports [governance split votes](./adr-037-gov-split-vote.md). When querying for votes, the returned `cosmos.gov.v1beta1.Vote` message has its `option` field (used for 1 vote option) deprecated in favor of its `options` field (allowing multiple vote options). Whenever possible, the SDK still populates the deprecated `option` field, that is, if and only if the `len(options) == 1` and `options[0].Weight == 1.0`.
* The Cosmos SDK recently removed support for [time-based software upgrades](https://github.com/cosmos/cosmos-sdk/pull/8849). As such, the `time` field has been marked as deprecated in `cosmos.upgrade.v1beta1.Plan`. Moreover, the node will reject any proposal containing an upgrade Plan whose `time` field is non-empty.
* The Cosmos SDK now supports [governance split votes](./adr-037-gov-split-vote.md). When querying for votes, the returned `cosmos.gov.v1beta1.Vote` message has its `option` field (used for 1 vote option) deprecated in favor of its `options` field (allowing multiple vote options). Whenever possible, the SDK still populates the deprecated `option` field, that is, if and only if the `len(options) == 1` and `options[0].Weight == 1.0`.
#### 4. Fields MUST NOT be renamed
@ -97,10 +97,10 @@ Whereas the official Protobuf recommendations do not prohibit renaming fields, a
TODO, needs architecture review. Some topics:
- Bumping versions frequency
- When bumping versions, should the Cosmos SDK support both versions?
- i.e. v1beta1 -> v1, should we have two folders in the Cosmos SDK, and handlers for both versions?
- mention ADR-023 Protobuf naming
* Bumping versions frequency
* When bumping versions, should the Cosmos SDK support both versions?
* i.e. v1beta1 -> v1, should we have two folders in the Cosmos SDK, and handlers for both versions?
* mention ADR-023 Protobuf naming
## Consequences
@ -112,9 +112,9 @@ TODO, needs architecture review. Some topics:
### Positive
- less pain to tool developers
- more compatibility in the ecosystem
- ...
* less pain to tool developers
* more compatibility in the ecosystem
* ...
### Negative
@ -122,7 +122,7 @@ TODO, needs architecture review. Some topics:
### Neutral
- more rigor in Protobuf review
* more rigor in Protobuf review
## Further Discussions
@ -134,5 +134,5 @@ Test cases for an implementation are mandatory for ADRs that are affecting conse
## References
- [#9445](https://github.com/cosmos/cosmos-sdk/issues/9445) Release proto definitions v1
- [#9446](https://github.com/cosmos/cosmos-sdk/issues/9446) Address v1beta1 proto breaking changes
* [#9445](https://github.com/cosmos/cosmos-sdk/issues/9445) Release proto definitions v1
* [#9446](https://github.com/cosmos/cosmos-sdk/issues/9446) Address v1beta1 proto breaking changes

40
docs/architecture/adr-045-check-delivertx-middlewares.md
View File

@ -2,8 +2,8 @@
## Changelog
- 20.08.2021: Initial draft.
- 07.12.2021: Update `tx.Handler` interface ([\#10693](https://github.com/cosmos/cosmos-sdk/pull/10693)).
* 20.08.2021: Initial draft.
* 07.12.2021: Update `tx.Handler` interface ([\#10693](https://github.com/cosmos/cosmos-sdk/pull/10693)).
## Status
@ -186,7 +186,7 @@ While BaseApp simply holds a reference to a `tx.Handler`, this `tx.Handler` itse
Then, the app developer can compose multiple middlewares on top on the base `tx.Handler`. Each middleware can run pre-and-post-processing logic around its next middleware, as described in the section above. Conceptually, as an example, given the middlewares `A`, `B`, and `C` and the base `tx.Handler` `H` the stack looks like:
```
```text
A.pre
B.pre
C.pre
@ -232,17 +232,17 @@ The middleware-based design builds upon the existing antehandlers design describ
#### Similarities with Antehandlers
- Designed as chaining/composing small modular pieces.
- Allow code reuse for `{Check,Deliver}Tx` and for `Simulate`.
- Set up in `app.go`, and easily customizable by app developers.
- Order is important.
* Designed as chaining/composing small modular pieces.
* Allow code reuse for `{Check,Deliver}Tx` and for `Simulate`.
* Set up in `app.go`, and easily customizable by app developers.
* Order is important.
#### Differences with Antehandlers
- The Antehandlers are run before `Msg` execution, whereas middlewares can run before and after.
- The middleware approach uses separate methods for `{Check,Deliver,Simulate}Tx`, whereas the antehandlers pass a `simulate bool` flag and uses the `sdkCtx.Is{Check,Recheck}Tx()` flags to determine in which transaction mode we are.
- The middleware design lets each middleware hold a reference to the next middleware, whereas the antehandlers pass a `next` argument in the `AnteHandle` method.
- The middleware design use Go's standard `context.Context`, whereas the antehandlers use `sdk.Context`.
* The Antehandlers are run before `Msg` execution, whereas middlewares can run before and after.
* The middleware approach uses separate methods for `{Check,Deliver,Simulate}Tx`, whereas the antehandlers pass a `simulate bool` flag and uses the `sdkCtx.Is{Check,Recheck}Tx()` flags to determine in which transaction mode we are.
* The middleware design lets each middleware hold a reference to the next middleware, whereas the antehandlers pass a `next` argument in the `AnteHandle` method.
* The middleware design use Go's standard `context.Context`, whereas the antehandlers use `sdk.Context`.
## Consequences
@ -281,14 +281,14 @@ This ADR does not introduce any state-machine-, client- or CLI-breaking changes.
### Positive
- Allow custom logic to be run before an after `Msg` execution. This enables the [tips](https://github.com/cosmos/cosmos-sdk/issues/9406) and [gas refund](https://github.com/cosmos/cosmos-sdk/issues/2150) uses cases, and possibly other ones.
- Make BaseApp more lightweight, and defer complex logic to small modular components.
- Separate paths for `{Check,Deliver,Simulate}Tx` with different returns types. This allows for improved readability (replace `if sdkCtx.IsRecheckTx() && !simulate {...}` with separate methods) and more flexibility (e.g. returning a `priority` in `ResponseCheckTx`).
* Allow custom logic to be run before an after `Msg` execution. This enables the [tips](https://github.com/cosmos/cosmos-sdk/issues/9406) and [gas refund](https://github.com/cosmos/cosmos-sdk/issues/2150) uses cases, and possibly other ones.
* Make BaseApp more lightweight, and defer complex logic to small modular components.
* Separate paths for `{Check,Deliver,Simulate}Tx` with different returns types. This allows for improved readability (replace `if sdkCtx.IsRecheckTx() && !simulate {...}` with separate methods) and more flexibility (e.g. returning a `priority` in `ResponseCheckTx`).
### Negative
- It is hard to understand at first glance the state updates that would occur after a middleware runs given the `sdk.Context` and `tx`. A middleware can have an arbitrary number of nested middleware being called within its function body, each possibly doing some pre- and post-processing before calling the next middleware on the chain. Thus to understand what a middleware is doing, one must also understand what every other middleware further along the chain is also doing, and the order of middlewares matters. This can get quite complicated to understand.
- API-breaking changes for app developers.
* It is hard to understand at first glance the state updates that would occur after a middleware runs given the `sdk.Context` and `tx`. A middleware can have an arbitrary number of nested middleware being called within its function body, each possibly doing some pre- and post-processing before calling the next middleware on the chain. Thus to understand what a middleware is doing, one must also understand what every other middleware further along the chain is also doing, and the order of middlewares matters. This can get quite complicated to understand.
* API-breaking changes for app developers.
### Neutral
@ -296,8 +296,8 @@ No neutral consequences.
## Further Discussions
- [#9934](https://github.com/cosmos/cosmos-sdk/discussions/9934) Decomposing BaseApp's other ABCI methods into middlewares.
- Replace `sdk.Tx` interface with the concrete protobuf Tx type in the `tx.Handler` methods signature.
* [#9934](https://github.com/cosmos/cosmos-sdk/discussions/9934) Decomposing BaseApp's other ABCI methods into middlewares.
* Replace `sdk.Tx` interface with the concrete protobuf Tx type in the `tx.Handler` methods signature.
## Test Cases
@ -307,5 +307,5 @@ For new middlewares, we introduce unit tests. Since middlewares are purposefully
## References
- Initial discussion: https://github.com/cosmos/cosmos-sdk/issues/9585
- Implementation: [#9920 BaseApp refactor](https://github.com/cosmos/cosmos-sdk/pull/9920) and [#10028 Antehandlers migration](https://github.com/cosmos/cosmos-sdk/pull/10028)
* Initial discussion: <https://github.com/cosmos/cosmos-sdk/issues/9585>
* Implementation: [#9920 BaseApp refactor](https://github.com/cosmos/cosmos-sdk/pull/9920) and [#10028 Antehandlers migration](https://github.com/cosmos/cosmos-sdk/pull/10028)

22
docs/architecture/adr-046-module-params.md
View File

@ -2,7 +2,7 @@
## Changelog
- Sep 22, 2021: Initial Draft
* Sep 22, 2021: Initial Draft
## Status
@ -156,20 +156,20 @@ module may be removed entirely in a future release.
### Positive
- Module parameters are serialized more efficiently
- Modules are able to react on parameters changes and perform additional actions.
- Special events can be emitted, allowing hooks to be triggered.
* Module parameters are serialized more efficiently
* Modules are able to react on parameters changes and perform additional actions.
* Special events can be emitted, allowing hooks to be triggered.
### Negative
- Module parameters becomes slightly more burdensome for module developers:
- Modules are now responsible for persisting and retrieving parameter state
- Modules are now required to have unique message handlers to handle parameter
* Module parameters becomes slightly more burdensome for module developers:
* Modules are now responsible for persisting and retrieving parameter state
* Modules are now required to have unique message handlers to handle parameter
changes per unique parameter data structure.
### Neutral
- Requires [#9810](https://github.com/cosmos/cosmos-sdk/pull/9810) to be reviewed
* Requires [#9810](https://github.com/cosmos/cosmos-sdk/pull/9810) to be reviewed
and merged.
<!-- ## Further Discussions
@ -179,6 +179,6 @@ Later, this section can optionally list ideas or improvements the author or revi
## References
- https://github.com/cosmos/cosmos-sdk/pull/9810
- https://github.com/cosmos/cosmos-sdk/issues/9438
- https://github.com/cosmos/cosmos-sdk/discussions/9913
* <https://github.com/cosmos/cosmos-sdk/pull/9810>
* <https://github.com/cosmos/cosmos-sdk/issues/9438>
* <https://github.com/cosmos/cosmos-sdk/discussions/9913>

4
docs/architecture/adr-template.md
View File

@ -2,7 +2,7 @@
## Changelog
- {date}: {changelog}
* {date}: {changelog}
## Status
@ -57,4 +57,4 @@ Test cases for an implementation are mandatory for ADRs that are affecting conse
## References
- {reference link}
* {reference link}

52
docs/basics/accounts.md
View File

@ -6,9 +6,9 @@ order: 4
This document describes the in-built account and public key system of the Cosmos SDK. {synopsis}
### Pre-requisite Readings
## Pre-requisite Readings
- [Anatomy of a Cosmos SDK Application](./app-anatomy.md) {prereq}
* [Anatomy of a Cosmos SDK Application](./app-anatomy.md) {prereq}
## Account Definition
@ -16,7 +16,7 @@ In the Cosmos SDK, an _account_ designates a pair of _public key_ `PubKey` and _
For HD key derivation the Cosmos SDK uses a standard called [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki). The BIP32 allows users to create an HD wallet (as specified in [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)) - a set of accounts derived from an initial secret seed. A seed is usually created from a 12- or 24-word mnemonic. A single seed can derive any number of `PrivKey`s using a one-way cryptographic function. Then, a `PubKey` can be derived from the `PrivKey`. Naturally, the mnemonic is the most sensitive information, as private keys can always be re-generated if the mnemonic is preserved.
```
```text
Account 0 Account 1 Account 2
+------------------+ +------------------+ +------------------+
@ -66,15 +66,15 @@ In the node, all data is stored using Protocol Buffers serialization.
The Cosmos SDK supports the following digital key schemes for creating digital signatures:
- `secp256k1`, as implemented in the [Cosmos SDK's `crypto/keys/secp256k1` package](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/keys/secp256k1/secp256k1.go).
- `secp256r1`, as implemented in the [Cosmos SDK's `crypto/keys/secp256r1` package](https://github.com/cosmos/cosmos-sdk/blob/master/crypto/keys/secp256r1/pubkey.go),
- `tm-ed25519`, as implemented in the [Cosmos SDK `crypto/keys/ed25519` package](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/keys/ed25519/ed25519.go). This scheme is supported only for the consensus validation.
* `secp256k1`, as implemented in the [Cosmos SDK's `crypto/keys/secp256k1` package](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/keys/secp256k1/secp256k1.go).
* `secp256r1`, as implemented in the [Cosmos SDK's `crypto/keys/secp256r1` package](https://github.com/cosmos/cosmos-sdk/blob/master/crypto/keys/secp256r1/pubkey.go),
* `tm-ed25519`, as implemented in the [Cosmos SDK `crypto/keys/ed25519` package](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/keys/ed25519/ed25519.go). This scheme is supported only for the consensus validation.
| | Address length in bytes | Public key length in bytes | Used for transaction authentication | Used for consensus (tendermint) |
|:------------:|:-----------------------:|:--------------------------:|:-----------------------------------:|:-------------------------------:|
| `secp256k1` | 20 | 33 | yes | no |
| `secp256r1` | 32 | 33 | yes | no |
| `tm-ed25519` | -- not used -- | 32 | no | yes |
| :----------: | :---------------------: | :------------------------: | :---------------------------------: | :-----------------------------: |
| `secp256k1` | 20 | 33 | yes | no |
| `secp256r1` | 32 | 33 | yes | no |
| `tm-ed25519` | -- not used -- | 32 | no | yes |
## Addresses
@ -82,13 +82,13 @@ The Cosmos SDK supports the following digital key schemes for creating digital s
Each account is identified using `Address` which is a sequence of bytes derived from a public key. In the Cosmos SDK, we define 3 types of addresses that specify a context where an account is used:
- `AccAddress` identifies users (the sender of a `message`).
- `ValAddress` identifies validator operators.
- `ConsAddress` identifies validator nodes that are participating in consensus. Validator nodes are derived using the **`ed25519`** curve.
* `AccAddress` identifies users (the sender of a `message`).
* `ValAddress` identifies validator operators.
* `ConsAddress` identifies validator nodes that are participating in consensus. Validator nodes are derived using the **`ed25519`** curve.
These types implement the `Address` interface:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/address.go#L71-L90
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/address.go#L71-L90>
Address construction algorithm is defined in [ADR-28](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-028-public-key-addresses.md).
Here is the standard way to obtain an account address from a `pub` public key:
@ -101,7 +101,7 @@ Of note, the `Marshal()` and `Bytes()` method both return the same raw `[]byte`
For user interaction, addresses are formatted using [Bech32](https://en.bitcoin.it/wiki/Bech32) and implemented by the `String` method. The Bech32 method is the only supported format to use when interacting with a blockchain. The Bech32 human-readable part (Bech32 prefix) is used to denote an address type. Example:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/address.go#L230-L244
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/address.go#L230-L244>
| | Address Bech32 Prefix |
| ------------------ | --------------------- |
@ -113,39 +113,39 @@ For user interaction, addresses are formatted using [Bech32](https://en.bitcoin.
Public keys in Cosmos SDK are defined by `cryptotypes.PubKey` interface. Since public keys are saved in a store, `cryptotypes.PubKey` extends the `proto.Message` interface:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/types/types.go#L8-L17
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/types/types.go#L8-L17>
A compressed format is used for `secp256k1` and `secp256r1` serialization.
- The first byte is a `0x02` byte if the `y`-coordinate is the lexicographically largest of the two associated with the `x`-coordinate.
- Otherwise the first byte is a `0x03`.
* The first byte is a `0x02` byte if the `y`-coordinate is the lexicographically largest of the two associated with the `x`-coordinate.
* Otherwise the first byte is a `0x03`.
This prefix is followed by the `x`-coordinate.
Public Keys are not used to reference accounts (or users) and in general are not used when composing transaction messages (with few exceptions: `MsgCreateValidator`, `Validator` and `Multisig` messages).
For user interactions, `PubKey` is formatted using Protobufs JSON ([ProtoMarshalJSON](https://github.com/cosmos/cosmos-sdk/blob/release/v0.42.x/codec/json.go#L12) function). Example:
+++ https://github.com/cosmos/cosmos-sdk/blob/7568b66/crypto/keyring/output.go#L23-L39
+++ <https://github.com/cosmos/cosmos-sdk/blob/7568b66/crypto/keyring/output.go#L23-L39>
## Keyring
A `Keyring` is an object that stores and manages accounts. In the Cosmos SDK, a `Keyring` implementation follows the `Keyring` interface:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/keyring/keyring.go#L51-L89
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/keyring/keyring.go#L51-L89>
The default implementation of `Keyring` comes from the third-party [`99designs/keyring`](https://github.com/99designs/keyring) library.
A few notes on the `Keyring` methods:
- `Sign(uid string, payload []byte) ([]byte, sdkcrypto.PubKey, error)` strictly deals with the signature of the `payload` bytes. You must prepare and encode the transaction into a canonical `[]byte` form. Because protobuf is not deterministic, it has been decided in [ADR-020](../architecture/adr-020-protobuf-transaction-encoding.md) that the canonical `payload` to sign is the `SignDoc` struct, deterministically encoded using [ADR-027](../architecture/adr-027-deterministic-protobuf-serialization.md). Note that signature verification is not implemented in the Cosmos SDK by default, it is deferred to the [`anteHandler`](../core/baseapp.md#antehandler).
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/proto/cosmos/tx/v1beta1/tx.proto#L47-L64
* `Sign(uid string, payload []byte) ([]byte, sdkcrypto.PubKey, error)` strictly deals with the signature of the `payload` bytes. You must prepare and encode the transaction into a canonical `[]byte` form. Because protobuf is not deterministic, it has been decided in [ADR-020](../architecture/adr-020-protobuf-transaction-encoding.md) that the canonical `payload` to sign is the `SignDoc` struct, deterministically encoded using [ADR-027](../architecture/adr-027-deterministic-protobuf-serialization.md). Note that signature verification is not implemented in the Cosmos SDK by default, it is deferred to the [`anteHandler`](../core/baseapp.md#antehandler).
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/proto/cosmos/tx/v1beta1/tx.proto#L47-L64>
- `NewAccount(uid, mnemonic, bip39Passwd, hdPath string, algo SignatureAlgo) (Info, error)` creates a new account based on the [`bip44 path`](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) and persists it on disk. The `PrivKey` is **never stored unencrypted**, instead it is [encrypted with a passphrase](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/crypto/armor.go) before being persisted. In the context of this method, the key type and sequence number refer to the segment of the BIP44 derivation path (for example, `0`, `1`, `2`, ...) that is used to derive a private and a public key from the mnemonic. Using the same mnemonic and derivation path, the same `PrivKey`, `PubKey` and `Address` is generated. The following keys are supported by the keyring:
* `NewAccount(uid, mnemonic, bip39Passwd, hdPath string, algo SignatureAlgo) (Info, error)` creates a new account based on the [`bip44 path`](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) and persists it on disk. The `PrivKey` is **never stored unencrypted**, instead it is [encrypted with a passphrase](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/crypto/armor.go) before being persisted. In the context of this method, the key type and sequence number refer to the segment of the BIP44 derivation path (for example, `0`, `1`, `2`, ...) that is used to derive a private and a public key from the mnemonic. Using the same mnemonic and derivation path, the same `PrivKey`, `PubKey` and `Address` is generated. The following keys are supported by the keyring:
- `secp256k1`
- `ed25519`
* `secp256k1`
* `ed25519`
- `ExportPrivKeyArmor(uid, encryptPassphrase string) (armor string, err error)` exports a private key in ASCII-armored encrypted format using the given passphrase. You can then either import the private key again into the keyring using the `ImportPrivKey(uid, armor, passphrase string)` function or decrypt it into a raw private key using the `UnarmorDecryptPrivKey(armorStr string, passphrase string)` function.
* `ExportPrivKeyArmor(uid, encryptPassphrase string) (armor string, err error)` exports a private key in ASCII-armored encrypted format using the given passphrase. You can then either import the private key again into the keyring using the `ImportPrivKey(uid, armor, passphrase string)` function or decrypt it into a raw private key using the `UnarmorDecryptPrivKey(armorStr string, passphrase string)` function.
## Next {hide}

96
docs/basics/app-anatomy.md
View File

@ -10,7 +10,7 @@ This document describes the core parts of a Cosmos SDK application. Throughout t
The Daemon, or [Full-Node Client](../core/node.md), is the core process of a Cosmos SDK-based blockchain. Participants in the network run this process to initialize their state-machine, connect with other full-nodes and update their state-machine as new blocks come in.
```
```text
^ +-------------------------------+ ^
| | | |
| | State-machine = Application | |
@ -44,44 +44,44 @@ In general, the core of the state-machine is defined in a file called `app.go`.
The first thing defined in `app.go` is the `type` of the application. It is generally comprised of the following parts:
- **A reference to [`baseapp`](../core/baseapp.md).** The custom application defined in `app.go` is an extension of `baseapp`. When a transaction is relayed by Tendermint to the application, `app` uses `baseapp`'s methods to route them to the appropriate module. `baseapp` implements most of the core logic for the application, including all the [ABCI methods](https://tendermint.com/docs/spec/abci/abci.html#overview) and the [routing logic](../core/baseapp.md#routing).
- **A list of store keys**. The [store](../core/store.md), which contains the entire state, is implemented as a [`multistore`](../core/store.md#multistore) (i.e. a store of stores) in the Cosmos SDK. Each module uses one or multiple stores in the multistore to persist their part of the state. These stores can be accessed with specific keys that are declared in the `app` type. These keys, along with the `keepers`, are at the heart of the [object-capabilities model](../core/ocap.md) of the Cosmos SDK.
- **A list of module's `keeper`s.** Each module defines an abstraction called [`keeper`](../building-modules/keeper.md), which handles reads and writes for this module's store(s). The `keeper`'s methods of one module can be called from other modules (if authorized), which is why they are declared in the application's type and exported as interfaces to other modules so that the latter can only access the authorized functions.
- **A reference to an [`appCodec`](../core/encoding.md).** The application's `appCodec` is used to serialize and deserialize data structures in order to store them, as stores can only persist `[]bytes`. The default codec is [Protocol Buffers](../core/encoding.md).
- **A reference to a [`legacyAmino`](../core/encoding.md) codec.** Some parts of the Cosmos SDK have not been migrated to use the `appCodec` above, and are still hardcoded to use Amino. Other parts explicity use Amino for backwards compatibility. For these reasons, the application still holds a reference to the legacy Amino codec. Please note that the Amino codec will be removed from the SDK in the upcoming releases.
- **A reference to a [module manager](../building-modules/module-manager.md#manager)** and a [basic module manager](../building-modules/module-manager.md#basicmanager). The module manager is an object that contains a list of the application's module. It facilitates operations related to these modules, like registering their [`Msg` service](../core/baseapp.md#msg-services) and [gRPC `Query` service](../core/baseapp.md#grpc-query-services), or setting the order of execution between modules for various functions like [`InitChainer`](#initchainer), [`BeginBlocker` and `EndBlocker`](#beginblocker-and-endblocker).
* **A reference to [`baseapp`](../core/baseapp.md).** The custom application defined in `app.go` is an extension of `baseapp`. When a transaction is relayed by Tendermint to the application, `app` uses `baseapp`'s methods to route them to the appropriate module. `baseapp` implements most of the core logic for the application, including all the [ABCI methods](https://tendermint.com/docs/spec/abci/abci.html#overview) and the [routing logic](../core/baseapp.md#routing).
* **A list of store keys**. The [store](../core/store.md), which contains the entire state, is implemented as a [`multistore`](../core/store.md#multistore) (i.e. a store of stores) in the Cosmos SDK. Each module uses one or multiple stores in the multistore to persist their part of the state. These stores can be accessed with specific keys that are declared in the `app` type. These keys, along with the `keepers`, are at the heart of the [object-capabilities model](../core/ocap.md) of the Cosmos SDK.
* **A list of module's `keeper`s.** Each module defines an abstraction called [`keeper`](../building-modules/keeper.md), which handles reads and writes for this module's store(s). The `keeper`'s methods of one module can be called from other modules (if authorized), which is why they are declared in the application's type and exported as interfaces to other modules so that the latter can only access the authorized functions.
* **A reference to an [`appCodec`](../core/encoding.md).** The application's `appCodec` is used to serialize and deserialize data structures in order to store them, as stores can only persist `[]bytes`. The default codec is [Protocol Buffers](../core/encoding.md).
* **A reference to a [`legacyAmino`](../core/encoding.md) codec.** Some parts of the Cosmos SDK have not been migrated to use the `appCodec` above, and are still hardcoded to use Amino. Other parts explicity use Amino for backwards compatibility. For these reasons, the application still holds a reference to the legacy Amino codec. Please note that the Amino codec will be removed from the SDK in the upcoming releases.
* **A reference to a [module manager](../building-modules/module-manager.md#manager)** and a [basic module manager](../building-modules/module-manager.md#basicmanager). The module manager is an object that contains a list of the application's module. It facilitates operations related to these modules, like registering their [`Msg` service](../core/baseapp.md#msg-services) and [gRPC `Query` service](../core/baseapp.md#grpc-query-services), or setting the order of execution between modules for various functions like [`InitChainer`](#initchainer), [`BeginBlocker` and `EndBlocker`](#beginblocker-and-endblocker).
See an example of application type definition from `simapp`, the Cosmos SDK's own app used for demo and testing purposes:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L145-L187
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L145-L187>
### Constructor Function
This function constructs a new application of the type defined in the section above. It must fulfill the `AppCreator` signature in order to be used in the [`start` command](../core/node.md#start-command) of the application's daemon command.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/types/app.go#L48-L50
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/types/app.go#L48-L50>
Here are the main actions performed by this function:
- Instantiate a new [`codec`](../core/encoding.md) and initialize the `codec` of each of the application's module using the [basic manager](../building-modules/module-manager.md#basicmanager)
- Instantiate a new application with a reference to a `baseapp` instance, a codec and all the appropriate store keys.
- Instantiate all the [`keeper`s](#keeper) defined in the application's `type` using the `NewKeeper` function of each of the application's modules. Note that `keepers` must be instantiated in the correct order, as the `NewKeeper` of one module might require a reference to another module's `keeper`.
- Instantiate the application's [module manager](../building-modules/module-manager.md#manager) with the [`AppModule`](#application-module-interface) object of each of the application's modules.
- With the module manager, initialize the application's [`Msg` services](../core/baseapp.md#msg-services), [gRPC `Query` services](../core/baseapp.md#grpc-query-services), [legacy `Msg` routes](../core/baseapp.md#routing) and [legacy query routes](../core/baseapp.md#query-routing). When a transaction is relayed to the application by Tendermint via the ABCI, it is routed to the appropriate module's [`Msg` service](#msg-services) using the routes defined here. Likewise, when a gRPC query request is received by the application, it is routed to the appropriate module's [`gRPC query service`](#grpc-query-services) using the gRPC routes defined here. The Cosmos SDK still supports legacy `Msg`s and legacy Tendermint queries, which are routed using respectively the legacy `Msg` routes and the legacy query routes.
- With the module manager, register the [application's modules' invariants](../building-modules/invariants.md). Invariants are variables (e.g. total supply of a token) that are evaluated at the end of each block. The process of checking invariants is done via a special module called the [`InvariantsRegistry`](../building-modules/invariants.md#invariant-registry). The value of the invariant should be equal to a predicted value defined in the module. Should the value be different than the predicted one, special logic defined in the invariant registry will be triggered (usually the chain is halted). This is useful to make sure no critical bug goes unnoticed and produces long-lasting effects that would be hard to fix.
- With the module manager, set the order of execution between the `InitGenesis`, `BeginBlocker` and `EndBlocker` functions of each of the [application's modules](#application-module-interface). Note that not all modules implement these functions.
- Set the remainder of application's parameters:
- [`InitChainer`](#initchainer): used to initialize the application when it is first started.
- [`BeginBlocker`, `EndBlocker`](#beginblocker-and-endlbocker): called at the beginning and the end of every block).
- [`anteHandler`](../core/baseapp.md#antehandler): used to handle fees and signature verification.
- Mount the stores.
- Return the application.
* Instantiate a new [`codec`](../core/encoding.md) and initialize the `codec` of each of the application's module using the [basic manager](../building-modules/module-manager.md#basicmanager)
* Instantiate a new application with a reference to a `baseapp` instance, a codec and all the appropriate store keys.
* Instantiate all the [`keeper`s](#keeper) defined in the application's `type` using the `NewKeeper` function of each of the application's modules. Note that `keepers` must be instantiated in the correct order, as the `NewKeeper` of one module might require a reference to another module's `keeper`.
* Instantiate the application's [module manager](../building-modules/module-manager.md#manager) with the [`AppModule`](#application-module-interface) object of each of the application's modules.
* With the module manager, initialize the application's [`Msg` services](../core/baseapp.md#msg-services), [gRPC `Query` services](../core/baseapp.md#grpc-query-services), [legacy `Msg` routes](../core/baseapp.md#routing) and [legacy query routes](../core/baseapp.md#query-routing). When a transaction is relayed to the application by Tendermint via the ABCI, it is routed to the appropriate module's [`Msg` service](#msg-services) using the routes defined here. Likewise, when a gRPC query request is received by the application, it is routed to the appropriate module's [`gRPC query service`](#grpc-query-services) using the gRPC routes defined here. The Cosmos SDK still supports legacy `Msg`s and legacy Tendermint queries, which are routed using respectively the legacy `Msg` routes and the legacy query routes.
* With the module manager, register the [application's modules' invariants](../building-modules/invariants.md). Invariants are variables (e.g. total supply of a token) that are evaluated at the end of each block. The process of checking invariants is done via a special module called the [`InvariantsRegistry`](../building-modules/invariants.md#invariant-registry). The value of the invariant should be equal to a predicted value defined in the module. Should the value be different than the predicted one, special logic defined in the invariant registry will be triggered (usually the chain is halted). This is useful to make sure no critical bug goes unnoticed and produces long-lasting effects that would be hard to fix.
* With the module manager, set the order of execution between the `InitGenesis`, `BeginBlocker` and `EndBlocker` functions of each of the [application's modules](#application-module-interface). Note that not all modules implement these functions.
* Set the remainder of application's parameters:
* [`InitChainer`](#initchainer): used to initialize the application when it is first started.
* [`BeginBlocker`, `EndBlocker`](#beginblocker-and-endlbocker): called at the beginning and the end of every block).
* [`anteHandler`](../core/baseapp.md#antehandler): used to handle fees and signature verification.
* Mount the stores.
* Return the application.
Note that this function only creates an instance of the app, while the actual state is either carried over from the `~/.app/data` folder if the node is restarted, or generated from the genesis file if the node is started for the first time.
See an example of application constructor from `simapp`:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L198-L441
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L198-L441>
### InitChainer
@ -91,7 +91,7 @@ In general, the `InitChainer` is mostly composed of the [`InitGenesis`](../build
See an example of an `InitChainer` from `simapp`:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L464-L471
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L464-L471>
### BeginBlocker and EndBlocker
@ -103,29 +103,29 @@ As a sidenote, it is important to remember that application-specific blockchains
See an example of `BeginBlocker` and `EndBlocker` functions from `simapp`
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L454-L462
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L454-L462>
### Register Codec
The `EncodingConfig` structure is the last important part of the `app.go` file. The goal of this structure is to define the codecs that will be used throughout the app.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/params/encoding.go#L9-L16
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/params/encoding.go#L9-L16>
Here are descriptions of what each of the four fields means:
- `InterfaceRegistry`: The `InterfaceRegistry` is used by the Protobuf codec to handle interfaces that are encoded and decoded (we also say "unpacked") using [`google.protobuf.Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto). `Any` could be thought as a struct that contains a `type_url` (name of a concrete type implementing the interface) and a `value` (its encoded bytes). `InterfaceRegistry` provides a mechanism for registering interfaces and implementations that can be safely unpacked from `Any`. Each of the application's modules implements the `RegisterInterfaces` method that can be used to register the module's own interfaces and implementations.
- You can read more about Any in [ADR-19](../architecture/adr-019-protobuf-state-encoding.md#usage-of-any-to-encode-interfaces).
- To go more into details, the Cosmos SDK uses an implementation of the Protobuf specification called [`gogoprotobuf`](https://github.com/gogo/protobuf). By default, the [gogo protobuf implementation of `Any`](https://godoc.org/github.com/gogo/protobuf/types) uses [global type registration](https://github.com/gogo/protobuf/blob/master/proto/properties.go#L540) to decode values packed in `Any` into concrete Go types. This introduces a vulnerability where any malicious module in the dependency tree could registry a type with the global protobuf registry and cause it to be loaded and unmarshaled by a transaction that referenced it in the `type_url` field. For more information, please refer to [ADR-019](../architecture/adr-019-protobuf-state-encoding.md).
- `Marshaler`: the default codec used throughout the Cosmos SDK. It is composed of a `BinaryCodec` used to encode and decode state, and a `JSONCodec` used to output data to the users (for example in the [CLI](#cli)). By default, the SDK uses Protobuf as `Marshaler`.
- `TxConfig`: `TxConfig` defines an interface a client can utilize to generate an application-defined concrete transaction type. Currently, the SDK handles two transaction types: `SIGN_MODE_DIRECT` (which uses Protobuf binary as over-the-wire encoding) and `SIGN_MODE_LEGACY_AMINO_JSON` (which depends on Amino). Read more about transactions [here](../core/transactions.md).
- `Amino`: Some legacy parts of the Cosmos SDK still use Amino for backwards-compatibility. Each module exposes a `RegisterLegacyAmino` method to register the module's specific types within Amino. This `Amino` codec should not be used by app developers anymore, and will be removed in future releases.
* `InterfaceRegistry`: The `InterfaceRegistry` is used by the Protobuf codec to handle interfaces that are encoded and decoded (we also say "unpacked") using [`google.protobuf.Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto). `Any` could be thought as a struct that contains a `type_url` (name of a concrete type implementing the interface) and a `value` (its encoded bytes). `InterfaceRegistry` provides a mechanism for registering interfaces and implementations that can be safely unpacked from `Any`. Each of the application's modules implements the `RegisterInterfaces` method that can be used to register the module's own interfaces and implementations.
* You can read more about Any in [ADR-19](../architecture/adr-019-protobuf-state-encoding.md#usage-of-any-to-encode-interfaces).
* To go more into details, the Cosmos SDK uses an implementation of the Protobuf specification called [`gogoprotobuf`](https://github.com/gogo/protobuf). By default, the [gogo protobuf implementation of `Any`](https://godoc.org/github.com/gogo/protobuf/types) uses [global type registration](https://github.com/gogo/protobuf/blob/master/proto/properties.go#L540) to decode values packed in `Any` into concrete Go types. This introduces a vulnerability where any malicious module in the dependency tree could registry a type with the global protobuf registry and cause it to be loaded and unmarshaled by a transaction that referenced it in the `type_url` field. For more information, please refer to [ADR-019](../architecture/adr-019-protobuf-state-encoding.md).
* `Marshaler`: the default codec used throughout the Cosmos SDK. It is composed of a `BinaryCodec` used to encode and decode state, and a `JSONCodec` used to output data to the users (for example in the [CLI](#cli)). By default, the SDK uses Protobuf as `Marshaler`.
* `TxConfig`: `TxConfig` defines an interface a client can utilize to generate an application-defined concrete transaction type. Currently, the SDK handles two transaction types: `SIGN_MODE_DIRECT` (which uses Protobuf binary as over-the-wire encoding) and `SIGN_MODE_LEGACY_AMINO_JSON` (which depends on Amino). Read more about transactions [here](../core/transactions.md).
* `Amino`: Some legacy parts of the Cosmos SDK still use Amino for backwards-compatibility. Each module exposes a `RegisterLegacyAmino` method to register the module's specific types within Amino. This `Amino` codec should not be used by app developers anymore, and will be removed in future releases.
The Cosmos SDK exposes a `MakeTestEncodingConfig` function used to create a `EncodingConfig` for the app constructor (`NewApp`). It uses Protobuf as a default `Marshaler`.
NOTE: this function is marked deprecated and should only be used to create an app or in tests. We are working on refactoring codec management in a post Stargate release.
See an example of a `MakeTestEncodingConfig` from `simapp`:
+++ https://github.com/cosmos/cosmos-sdk/blob/590358652cc1cbc13872ea1659187e073ea38e75/simapp/encoding.go#L8-L19
+++ <https://github.com/cosmos/cosmos-sdk/blob/590358652cc1cbc13872ea1659187e073ea38e75/simapp/encoding.go#L8-L19>
## Modules
@ -154,7 +154,7 @@ For a more details look at a transaction [lifecycle](./tx-lifecycle.md).
Module developers create custom `Msg` services when they build their own module. The general practice is to define the `Msg` Protobuf service in a `tx.proto` file. For example, the `x/bank` module defines a service with two methods to transfer tokens:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/bank/v1beta1/tx.proto#L10-L17
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/bank/v1beta1/tx.proto#L10-L17>
Service methods use `keeper` in order to update the module state.
@ -178,9 +178,9 @@ Finally, each module should also implement the `RegisterServices` method as part
The `keeper` type definition generally consists of:
- **Key(s)** to the module's store(s) in the multistore.
- Reference to **other module's `keepers`**. Only needed if the `keeper` needs to access other module's store(s) (either to read or write from them).
- A reference to the application's **codec**. The `keeper` needs it to marshal structs before storing them, or to unmarshal them when it retrieves them, because stores only accept `[]bytes` as value.
* **Key(s)** to the module's store(s) in the multistore.
* Reference to **other module's `keepers`**. Only needed if the `keeper` needs to access other module's store(s) (either to read or write from them).
* A reference to the application's **codec**. The `keeper` needs it to marshal structs before storing them, or to unmarshal them when it retrieves them, because stores only accept `[]bytes` as value.
Along with the type definition, the next important component of the `keeper.go` file is the `keeper`'s constructor function, `NewKeeper`. This function instantiates a new `keeper` of the type defined above, with a `codec`, store `keys` and potentially references to other modules' `keeper`s as parameters. The `NewKeeper` function is called from the [application's constructor](#constructor-function). The rest of the file defines the `keeper`'s methods, primarily getters and setters.
@ -192,8 +192,8 @@ Each module defines command-line commands, gRPC services and REST routes to be e
Generally, the [commands related to a module](../building-modules/module-interfaces.md#cli) are defined in a folder called `client/cli` in the module's folder. The CLI divides commands in two category, transactions and queries, defined in `client/cli/tx.go` and `client/cli/query.go` respectively. Both commands are built on top of the [Cobra Library](https://github.com/spf13/cobra):
- Transactions commands let users generate new transactions so that they can be included in a block and eventually update the state. One command should be created for each [message type](#message-types) defined in the module. The command calls the constructor of the message with the parameters provided by the end-user, and wraps it into a transaction. The Cosmos SDK handles signing and the addition of other transaction metadata.
- Queries let users query the subset of the state defined by the module. Query commands forward queries to the [application's query router](../core/baseapp.md#query-routing), which routes them to the appropriate [querier](#querier) the `queryRoute` parameter supplied.
* Transactions commands let users generate new transactions so that they can be included in a block and eventually update the state. One command should be created for each [message type](#message-types) defined in the module. The command calls the constructor of the message with the parameters provided by the end-user, and wraps it into a transaction. The Cosmos SDK handles signing and the addition of other transaction metadata.
* Queries let users query the subset of the state defined by the module. Query commands forward queries to the [application's query router](../core/baseapp.md#query-routing), which routes them to the appropriate [querier](#querier) the `queryRoute` parameter supplied.
#### gRPC
@ -201,8 +201,8 @@ Generally, the [commands related to a module](../building-modules/module-interfa
Each module can expose gRPC endpoints, called [service methods](https://grpc.io/docs/what-is-grpc/core-concepts/#service-definition) and are defined in the [module's Protobuf `query.proto` file](#grpc-query-services). A service method is defined by its name, input arguments and output response. The module then needs to:
- define a `RegisterGRPCGatewayRoutes` method on `AppModuleBasic` to wire the client gRPC requests to the correct handler inside the module.
- for each service method, define a corresponding handler. The handler implements the core logic necessary to serve the gRPC request, and is located in the `keeper/grpc_query.go` file.
* define a `RegisterGRPCGatewayRoutes` method on `AppModuleBasic` to wire the client gRPC requests to the correct handler inside the module.
* for each service method, define a corresponding handler. The handler implements the core logic necessary to serve the gRPC request, and is located in the `keeper/grpc_query.go` file.
#### gRPC-gateway REST Endpoints
@ -218,13 +218,13 @@ The Cosmos SDK also provides a development endpoint to generate [Swagger](https:
The main interface is the [Command-Line Interface](../core/cli.md). The CLI of a Cosmos SDK application is built by aggregating [CLI commands](#cli) defined in each of the modules used by the application. The CLI of an application is the same as the daemon (e.g. `appd`), and defined in a file called `appd/main.go`. The file contains:
- **A `main()` function**, which is executed to build the `appd` interface client. This function prepares each command and adds them to the `rootCmd` before building them. At the root of `appd`, the function adds generic commands like `status`, `keys` and `config`, query commands, tx commands and `rest-server`.
- **Query commands** are added by calling the `queryCmd` function. This function returns a Cobra command that contains the query commands defined in each of the application's modules (passed as an array of `sdk.ModuleClients` from the `main()` function), as well as some other lower level query commands such as block or validator queries. Query command are called by using the command `appd query [query]` of the CLI.
- **Transaction commands** are added by calling the `txCmd` function. Similar to `queryCmd`, the function returns a Cobra command that contains the tx commands defined in each of the application's modules, as well as lower level tx commands like transaction signing or broadcasting. Tx commands are called by using the command `appd tx [tx]` of the CLI.
* **A `main()` function**, which is executed to build the `appd` interface client. This function prepares each command and adds them to the `rootCmd` before building them. At the root of `appd`, the function adds generic commands like `status`, `keys` and `config`, query commands, tx commands and `rest-server`.
* **Query commands** are added by calling the `queryCmd` function. This function returns a Cobra command that contains the query commands defined in each of the application's modules (passed as an array of `sdk.ModuleClients` from the `main()` function), as well as some other lower level query commands such as block or validator queries. Query command are called by using the command `appd query [query]` of the CLI.
* **Transaction commands** are added by calling the `txCmd` function. Similar to `queryCmd`, the function returns a Cobra command that contains the tx commands defined in each of the application's modules, as well as lower level tx commands like transaction signing or broadcasting. Tx commands are called by using the command `appd tx [tx]` of the CLI.
See an example of an application's main command-line file from the [nameservice tutorial](https://github.com/cosmos/sdk-tutorials/tree/master/nameservice)
+++ https://github.com/cosmos/sdk-tutorials/blob/86a27321cf89cc637581762e953d0c07f8c78ece/nameservice/cmd/nscli/main.go
+++ <https://github.com/cosmos/sdk-tutorials/blob/86a27321cf89cc637581762e953d0c07f8c78ece/nameservice/cmd/nscli/main.go>
## Dependencies and Makefile
@ -233,7 +233,7 @@ A patch introduced in `go-grpc v1.34.0` made gRPC incompatible with the `gogopro
To make sure that gRPC is working properly, it is **highly recommended** to add the following line in your application's `go.mod`:
```
```go
replace google.golang.org/grpc => google.golang.org/grpc v1.33.2
```
@ -242,11 +242,11 @@ Please see [issue #8392](https://github.com/cosmos/cosmos-sdk/issues/8392) for m
This section is optional, as developers are free to choose their dependency manager and project building method. That said, the current most used framework for versioning control is [`go.mod`](https://github.com/golang/go/wiki/Modules). It ensures each of the libraries used throughout the application are imported with the correct version. See an example from the [nameservice tutorial](https://github.com/cosmos/sdk-tutorials/tree/master/nameservice):
+++ https://github.com/cosmos/sdk-tutorials/blob/c6754a1e313eb1ed973c5c91dcc606f2fd288811/go.mod#L1-L18
+++ <https://github.com/cosmos/sdk-tutorials/blob/c6754a1e313eb1ed973c5c91dcc606f2fd288811/go.mod#L1-L18>
For building the application, a [Makefile](https://en.wikipedia.org/wiki/Makefile) is generally used. The Makefile primarily ensures that the `go.mod` is run before building the two entrypoints to the application, [`appd`](#node-client) and [`appd`](#application-interface). See an example of Makefile from the [nameservice tutorial](https://tutorials.cosmos.network/nameservice/tutorial/00-intro.html)
+++ https://github.com/cosmos/sdk-tutorials/blob/86a27321cf89cc637581762e953d0c07f8c78ece/nameservice/Makefile
+++ <https://github.com/cosmos/sdk-tutorials/blob/86a27321cf89cc637581762e953d0c07f8c78ece/nameservice/Makefile>
## Next {hide}

38
docs/basics/gas-fees.md
View File

@ -6,31 +6,31 @@ order: 5
This document describes the default strategies to handle gas and fees within a Cosmos SDK application. {synopsis}
### Pre-requisite Readings
## Pre-requisite Readings
- [Anatomy of a Cosmos SDK Application](./app-anatomy.md) {prereq}
* [Anatomy of a Cosmos SDK Application](./app-anatomy.md) {prereq}
## Introduction to `Gas` and `Fees`
In the Cosmos SDK, `gas` is a special unit that is used to track the consumption of resources during execution. `gas` is typically consumed whenever read and writes are made to the store, but it can also be consumed if expensive computation needs to be done. It serves two main purposes:
- Make sure blocks are not consuming too many resources and will be finalized. This is implemented by default in the Cosmos SDK via the [block gas meter](#block-gas-meter).
- Prevent spam and abuse from end-user. To this end, `gas` consumed during [`message`](../building-modules/messages-and-queries.md#messages) execution is typically priced, resulting in a `fee` (`fees = gas * gas-prices`). `fees` generally have to be paid by the sender of the `message`. Note that the Cosmos SDK does not enforce `gas` pricing by default, as there may be other ways to prevent spam (e.g. bandwidth schemes). Still, most applications will implement `fee` mechanisms to prevent spam. This is done via the [`AnteHandler`](#antehandler).
* Make sure blocks are not consuming too many resources and will be finalized. This is implemented by default in the Cosmos SDK via the [block gas meter](#block-gas-meter).
* Prevent spam and abuse from end-user. To this end, `gas` consumed during [`message`](../building-modules/messages-and-queries.md#messages) execution is typically priced, resulting in a `fee` (`fees = gas * gas-prices`). `fees` generally have to be paid by the sender of the `message`. Note that the Cosmos SDK does not enforce `gas` pricing by default, as there may be other ways to prevent spam (e.g. bandwidth schemes). Still, most applications will implement `fee` mechanisms to prevent spam. This is done via the [`AnteHandler`](#antehandler).
## Gas Meter
In the Cosmos SDK, `gas` is a simple alias for `uint64`, and is managed by an object called a _gas meter_. Gas meters implement the `GasMeter` interface
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/store/types/gas.go#L34-L43
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/store/types/gas.go#L34-L43>
where:
- `GasConsumed()` returns the amount of gas that was consumed by the gas meter instance.
- `GasConsumedToLimit()` returns the amount of gas that was consumed by gas meter instance, or the limit if it is reached.
- `Limit()` returns the limit of the gas meter instance. `0` if the gas meter is infinite.
- `ConsumeGas(amount Gas, descriptor string)` consumes the amount of `gas` provided. If the `gas` overflows, it panics with the `descriptor` message. If the gas meter is not infinite, it panics if `gas` consumed goes above the limit.
- `IsPastLimit()` returns `true` if the amount of gas consumed by the gas meter instance is strictly above the limit, `false` otherwise.
- `IsOutOfGas()` returns `true` if the amount of gas consumed by the gas meter instance is above or equal to the limit, `false` otherwise.
* `GasConsumed()` returns the amount of gas that was consumed by the gas meter instance.
* `GasConsumedToLimit()` returns the amount of gas that was consumed by gas meter instance, or the limit if it is reached.
* `Limit()` returns the limit of the gas meter instance. `0` if the gas meter is infinite.
* `ConsumeGas(amount Gas, descriptor string)` consumes the amount of `gas` provided. If the `gas` overflows, it panics with the `descriptor` message. If the gas meter is not infinite, it panics if `gas` consumed goes above the limit.
* `IsPastLimit()` returns `true` if the amount of gas consumed by the gas meter instance is strictly above the limit, `false` otherwise.
* `IsOutOfGas()` returns `true` if the amount of gas consumed by the gas meter instance is above or equal to the limit, `false` otherwise.
The gas meter is generally held in [`ctx`](../core/context.md), and consuming gas is done with the following pattern:
@ -50,7 +50,7 @@ Gas consumption can be done manually, generally by the module developer in the [
`ctx.BlockGasMeter()` is the gas meter used to track gas consumption per block and make sure it does not go above a certain limit. A new instance of the `BlockGasMeter` is created each time [`BeginBlock`](../core/baseapp.md#beginblock) is called. The `BlockGasMeter` is finite, and the limit of gas per block is defined in the application's consensus parameters. By default Cosmos SDK applications use the default consensus parameters provided by Tendermint:
+++ https://github.com/tendermint/tendermint/blob/v0.34.0-rc6/types/params.go#L34-L41
+++ <https://github.com/tendermint/tendermint/blob/v0.34.0-rc6/types/params.go#L34-L41>
When a new [transaction](../core/transactions.md) is being processed via `DeliverTx`, the current value of `BlockGasMeter` is checked to see if it is above the limit. If it is, `DeliverTx` returns immediately. This can happen even with the first transaction in a block, as `BeginBlock` itself can consume gas. If not, the transaction is processed normally. At the end of `DeliverTx`, the gas tracked by `ctx.BlockGasMeter()` is increased by the amount consumed to process the transaction:
@ -73,14 +73,14 @@ type AnteHandler func(ctx Context, tx Tx, simulate bool) (newCtx Context, result
The `anteHandler` is not implemented in the core Cosmos SDK but in a module. This gives the possibility to developers to choose which version of `AnteHandler` fits their application's needs. That said, most applications today use the default implementation defined in the [`auth` module](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth). Here is what the `anteHandler` is intended to do in a normal Cosmos SDK application:
- Verify that the transaction are of the correct type. Transaction types are defined in the module that implements the `anteHandler`, and they follow the transaction interface:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/tx_msg.go#L49-L57
* Verify that the transaction are of the correct type. Transaction types are defined in the module that implements the `anteHandler`, and they follow the transaction interface:
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/tx_msg.go#L49-L57>
This enables developers to play with various types for the transaction of their application. In the default `auth` module, the default transaction type is `Tx`:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/tx.proto#L12-L25
- Verify signatures for each [`message`](../building-modules/messages-and-queries.md#messages) contained in the transaction. Each `message` should be signed by one or multiple sender(s), and these signatures must be verified in the `anteHandler`.
- During `CheckTx`, verify that the gas prices provided with the transaction is greater than the local `min-gas-prices` (as a reminder, gas-prices can be deducted from the following equation: `fees = gas * gas-prices`). `min-gas-prices` is a parameter local to each full-node and used during `CheckTx` to discard transactions that do not provide a minimum amount of fees. This ensure that the mempool cannot be spammed with garbage transactions.
- Verify that the sender of the transaction has enough funds to cover for the `fees`. When the end-user generates a transaction, they must indicate 2 of the 3 following parameters (the third one being implicit): `fees`, `gas` and `gas-prices`. This signals how much they are willing to pay for nodes to execute their transaction. The provided `gas` value is stored in a parameter called `GasWanted` for later use.
- Set `newCtx.GasMeter` to 0, with a limit of `GasWanted`. **This step is extremely important**, as it not only makes sure the transaction cannot consume infinite gas, but also that `ctx.GasMeter` is reset in-between each `DeliverTx` (`ctx` is set to `newCtx` after `anteHandler` is run, and the `anteHandler` is run each time `DeliverTx` is called).
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/tx.proto#L12-L25>
* Verify signatures for each [`message`](../building-modules/messages-and-queries.md#messages) contained in the transaction. Each `message` should be signed by one or multiple sender(s), and these signatures must be verified in the `anteHandler`.
* During `CheckTx`, verify that the gas prices provided with the transaction is greater than the local `min-gas-prices` (as a reminder, gas-prices can be deducted from the following equation: `fees = gas * gas-prices`). `min-gas-prices` is a parameter local to each full-node and used during `CheckTx` to discard transactions that do not provide a minimum amount of fees. This ensure that the mempool cannot be spammed with garbage transactions.
* Verify that the sender of the transaction has enough funds to cover for the `fees`. When the end-user generates a transaction, they must indicate 2 of the 3 following parameters (the third one being implicit): `fees`, `gas` and `gas-prices`. This signals how much they are willing to pay for nodes to execute their transaction. The provided `gas` value is stored in a parameter called `GasWanted` for later use.
* Set `newCtx.GasMeter` to 0, with a limit of `GasWanted`. **This step is extremely important**, as it not only makes sure the transaction cannot consume infinite gas, but also that `ctx.GasMeter` is reset in-between each `DeliverTx` (`ctx` is set to `newCtx` after `anteHandler` is run, and the `anteHandler` is run each time `DeliverTx` is called).
As explained above, the `anteHandler` returns a maximum limit of `gas` the transaction can consume during execution called `GasWanted`. The actual amount consumed in the end is denominated `GasUsed`, and we must therefore have `GasUsed =< GasWanted`. Both `GasWanted` and `GasUsed` are relayed to the underlying consensus engine when [`DeliverTx`](../core/baseapp.md#delivertx) returns.

26
docs/basics/query-lifecycle.md
View File

@ -8,7 +8,7 @@ This document describes the lifecycle of a query in a Cosmos SDK application, fr
## Pre-requisite Readings
- [Transaction Lifecycle](./tx-lifecycle.md) {prereq}
* [Transaction Lifecycle](./tx-lifecycle.md) {prereq}
## Query Creation
@ -43,7 +43,7 @@ A patch introduced in `go-grpc v1.34.0` made gRPC incompatible with the `gogopro
To make sure that gRPC is working properly, it is **highly recommended** to add the following line in your application's `go.mod`:
```
```go
replace google.golang.org/grpc => google.golang.org/grpc v1.33.2
```
@ -82,16 +82,16 @@ The examples above show how an external user can interact with a node by queryin
The first thing that is created in the execution of a CLI command is a `client.Context`. A `client.Context` is an object that stores all the data needed to process a request on the user side. In particular, a `client.Context` stores the following:
- **Codec**: The [encoder/decoder](../core/encoding.md) used by the application, used to marshal the parameters and query before making the Tendermint RPC request and unmarshal the returned response into a JSON object. The default codec used by the CLI is Protobuf.
- **Account Decoder**: The account decoder from the [`auth`](../..//x/auth/spec/README.md) module, which translates `[]byte`s into accounts.
- **RPC Client**: The Tendermint RPC Client, or node, to which the request will be relayed to.
- **Keyring**: A [Key Manager](../basics/accounts.md#keyring) used to sign transactions and handle other operations with keys.
- **Output Writer**: A [Writer](https://golang.org/pkg/io/#Writer) used to output the response.
- **Configurations**: The flags configured by the user for this command, including `--height`, specifying the height of the blockchain to query and `--indent`, which indicates to add an indent to the JSON response.
* **Codec**: The [encoder/decoder](../core/encoding.md) used by the application, used to marshal the parameters and query before making the Tendermint RPC request and unmarshal the returned response into a JSON object. The default codec used by the CLI is Protobuf.
* **Account Decoder**: The account decoder from the [`auth`](../..//x/auth/spec/README.md) module, which translates `[]byte`s into accounts.
* **RPC Client**: The Tendermint RPC Client, or node, to which the request will be relayed to.
* **Keyring**: A [Key Manager](../basics/accounts.md#keyring) used to sign transactions and handle other operations with keys.
* **Output Writer**: A [Writer](https://golang.org/pkg/io/#Writer) used to output the response.
* **Configurations**: The flags configured by the user for this command, including `--height`, specifying the height of the blockchain to query and `--indent`, which indicates to add an indent to the JSON response.
The `client.Context` also contains various functions such as `Query()` which retrieves the RPC Client and makes an ABCI call to relay a query to a full-node.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/context.go#L20-L50
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/context.go#L20-L50>
The `client.Context`'s primary role is to store data used during interactions with the end-user and provide methods to interact with this data - it is used before and after the query is processed by the full-node. Specifically, in handling `MyQuery`, the `client.Context` is utilized to encode the query parameters, retrieve the full-node, and write the output. Prior to being relayed to a full-node, the query needs to be encoded into a `[]byte` form, as full-nodes are application-agnostic and do not understand specific types. The full-node (RPC Client) itself is retrieved using the `client.Context`, which knows which node the user CLI is connected to. The query is relayed to this full-node to be processed. Finally, the `client.Context` contains a `Writer` to write output when the response is returned. These steps are further described in later sections.
@ -105,19 +105,19 @@ In our case (querying an address's delegations), `MyQuery` contains an [address]
Here is what the code looks like for the CLI command:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/staking/client/cli/query.go#L324-L327
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/staking/client/cli/query.go#L324-L327>
#### gRPC Query Client Creation
The Cosmos SDK leverages code generated from Protobuf services to make queries. The `staking` module's `MyQuery` service generates a `queryClient`, which the CLI will use to make queries. Here is the relevant code:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/staking/client/cli/query.go#L318-L342
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/staking/client/cli/query.go#L318-L342>
Under the hood, the `client.Context` has a `Query()` function used to retrieve the pre-configured node and relay a query to it; the function takes the query fully-qualified service method name as path (in our case: `/cosmos.staking.v1beta1.Query/Delegations`), and arguments as parameters. It first retrieves the RPC Client (called the [**node**](../core/node.md)) configured by the user to relay this query to, and creates the `ABCIQueryOptions` (parameters formatted for the ABCI call). The node is then used to make the ABCI call, `ABCIQueryWithOptions()`.
Here is what the code looks like:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/query.go#L65-L91
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/query.go#L65-L91>
## RPC
@ -143,7 +143,7 @@ Since `Query()` is an ABCI function, `baseapp` returns the response as an [`abci
The application [`codec`](../core/encoding.md) is used to unmarshal the response to a JSON and the `client.Context` prints the output to the command line, applying any configurations such as the output type (text, JSON or YAML).
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/context.go#L248-L283
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/context.go#L248-L283>
And that's a wrap! The result of the query is outputted to the console by the CLI.

26
docs/basics/tx-lifecycle.md
View File

@ -6,9 +6,9 @@ order: 2
This document describes the lifecycle of a transaction from creation to committed state changes. Transaction definition is described in a [different doc](../core/transactions.md). The transaction will be referred to as `Tx`. {synopsis}
### Pre-requisite Readings
## Pre-requisite Readings
- [Anatomy of a Cosmos SDK Application](./app-anatomy.md) {prereq}
* [Anatomy of a Cosmos SDK Application](./app-anatomy.md) {prereq}
## Creation
@ -28,11 +28,11 @@ There are several required and optional flags for transaction creation. The `--f
Additionally, there are several [flags](../core/cli.md) users can use to indicate how much they are willing to pay in [fees](./gas-fees.md):
- `--gas` refers to how much [gas](./gas-fees.md), which represents computational resources, `Tx` consumes. Gas is dependent on the transaction and is not precisely calculated until execution, but can be estimated by providing `auto` as the value for `--gas`.
- `--gas-adjustment` (optional) can be used to scale `gas` up in order to avoid underestimating. For example, users can specify their gas adjustment as 1.5 to use 1.5 times the estimated gas.
- `--gas-prices` specifies how much the user is willing pay per unit of gas, which can be one or multiple denominations of tokens. For example, `--gas-prices=0.025uatom, 0.025upho` means the user is willing to pay 0.025uatom AND 0.025upho per unit of gas.
- `--fees` specifies how much in fees the user is willing to pay in total.
- `--timeout-height` specifies a block timeout height to prevent the tx from being committed past a certain height.
* `--gas` refers to how much [gas](./gas-fees.md), which represents computational resources, `Tx` consumes. Gas is dependent on the transaction and is not precisely calculated until execution, but can be estimated by providing `auto` as the value for `--gas`.
* `--gas-adjustment` (optional) can be used to scale `gas` up in order to avoid underestimating. For example, users can specify their gas adjustment as 1.5 to use 1.5 times the estimated gas.
* `--gas-prices` specifies how much the user is willing pay per unit of gas, which can be one or multiple denominations of tokens. For example, `--gas-prices=0.025uatom, 0.025upho` means the user is willing to pay 0.025uatom AND 0.025upho per unit of gas.
* `--fees` specifies how much in fees the user is willing to pay in total.
* `--timeout-height` specifies a block timeout height to prevent the tx from being committed past a certain height.
The ultimate value of the fees paid is equal to the gas multiplied by the gas prices. In other words, `fees = ceil(gas * gasPrices)`. Thus, since fees can be calculated using gas prices and vice versa, the users specify only one of the two.
@ -153,7 +153,7 @@ and [`EndBlock`](./app-anatomy.md#beginblocker-and-endblocker). While each full-
locally, this process yields a single, unambiguous result, since the messages' state transitions are deterministic and transactions are
explicitly ordered in the block proposal.
```
```text
-----------------------
|Receive Block Proposal|
-----------------------
@ -198,25 +198,25 @@ to during consensus. Under the hood, `DeliverTx` is almost identical to `CheckTx
[`runTx`](../core/baseapp.md#runtx) function in deliver mode instead of check mode.
Instead of using their `checkState`, full-nodes use `deliverState`:
- **Decoding:** Since `DeliverTx` is an ABCI call, `Tx` is received in the encoded `[]byte` form.
* **Decoding:** Since `DeliverTx` is an ABCI call, `Tx` is received in the encoded `[]byte` form.
Nodes first unmarshal the transaction, using the [`TxConfig`](./app-anatomy#register-codec) defined in the app, then call `runTx` in `runTxModeDeliver`, which is very similar to `CheckTx` but also executes and writes state changes.
- **Checks:** Full-nodes call `validateBasicMsgs` and the `AnteHandler` again. This second check
* **Checks:** Full-nodes call `validateBasicMsgs` and the `AnteHandler` again. This second check
happens because they may not have seen the same transactions during the addition to Mempool stage\
and a malicious proposer may have included invalid ones. One difference here is that the
`AnteHandler` will not compare `gas-prices` to the node's `min-gas-prices` since that value is local
to each node - differing values across nodes would yield nondeterministic results.
- **`MsgServiceRouter`:** While `CheckTx` would have exited, `DeliverTx` continues to run
* **`MsgServiceRouter`:** While `CheckTx` would have exited, `DeliverTx` continues to run
[`runMsgs`](../core/baseapp.md#runtx-and-runmsgs) to fully execute each `Msg` within the transaction.
Since the transaction may have messages from different modules, `BaseApp` needs to know which module
to find the appropriate handler. This is achieved using `BaseApp`'s `MsgServiceRouter` so that it can be processed by the module's Protobuf [`Msg` service](../building-modules/msg-services.md).
For `LegacyMsg` routing, the `Route` function is called via the [module manager](../building-modules/module-manager.md) to retrieve the route name and find the legacy [`Handler`](../building-modules/msg-services.md#handler-type) within the module.
- **`Msg` service:** a Protobuf `Msg` service, a step up from `AnteHandler`, is responsible for executing each
* **`Msg` service:** a Protobuf `Msg` service, a step up from `AnteHandler`, is responsible for executing each
message in the `Tx` and causes state transitions to persist in `deliverTxState`.
- **Gas:** While a `Tx` is being delivered, a `GasMeter` is used to keep track of how much
* **Gas:** While a `Tx` is being delivered, a `GasMeter` is used to keep track of how much
gas is being used; if execution completes, `GasUsed` is set and returned in the
`abci.ResponseDeliverTx`. If execution halts because `BlockGasMeter` or `GasMeter` has run out or something else goes
wrong, a deferred function at the end appropriately errors or panics.

12
docs/building-modules/beginblock-endblock.md
View File

@ -8,7 +8,7 @@ order: 6
## Pre-requisite Readings
- [Module Manager](./module-manager.md) {prereq}
* [Module Manager](./module-manager.md) {prereq}
## BeginBlocker and EndBlocker
@ -18,9 +18,9 @@ When needed, `BeginBlocker` and `EndBlocker` are implemented as part of the [`Ap
The actual implementation of `BeginBlocker` and `EndBlocker` in `abci.go` are very similar to that of a [`Msg` service](./msg-services.md):
- They generally use the [`keeper`](./keeper.md) and [`ctx`](../core/context.md) to retrieve information about the latest state.
- If needed, they use the `keeper` and `ctx` to trigger state-transitions.
- If needed, they can emit [`events`](../core/events.md) via the `ctx`'s `EventManager`.
* They generally use the [`keeper`](./keeper.md) and [`ctx`](../core/context.md) to retrieve information about the latest state.
* If needed, they use the `keeper` and `ctx` to trigger state-transitions.
* If needed, they can emit [`events`](../core/events.md) via the `ctx`'s `EventManager`.
A specificity of the `EndBlocker` is that it can return validator updates to the underlying consensus engine in the form of an [`[]abci.ValidatorUpdates`](https://tendermint.com/docs/app-dev/abci-spec.html#validatorupdate). This is the preferred way to implement custom validator changes.
@ -28,11 +28,11 @@ It is possible for developers to define the order of execution between the `Begi
See an example implementation of `BeginBlocker` from the `distr` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/f33749263f4ecc796115ad6e789cb0f7cddf9148/x/distribution/abci.go#L14-L38
+++ <https://github.com/cosmos/cosmos-sdk/blob/f33749263f4ecc796115ad6e789cb0f7cddf9148/x/distribution/abci.go#L14-L38>
and an example implementation of `EndBlocker` from the `staking` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/f33749263f4ecc796115ad6e789cb0f7cddf9148/x/staking/abci.go#L22-L27
+++ <https://github.com/cosmos/cosmos-sdk/blob/f33749263f4ecc796115ad6e789cb0f7cddf9148/x/staking/abci.go#L22-L27>
## Next {hide}

4
docs/building-modules/errors.md
View File

@ -18,7 +18,7 @@ of errors is handled via the `types/errors` package.
Example:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0/x/distribution/types/errors.go#L1-L21
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0/x/distribution/types/errors.go#L1-L21>
Each custom module error must provide the codespace, which is typically the module name
(e.g. "distribution") and is unique per module, and a uint32 code. Together, the codespace and code
@ -38,7 +38,7 @@ execution.
Example:
+++ https://github.com/cosmos/cosmos-sdk/blob/b2d48a9e815fe534a7faeec6ca2adb0874252b81/x/bank/keeper/keeper.go#L85-L122
+++ <https://github.com/cosmos/cosmos-sdk/blob/b2d48a9e815fe534a7faeec6ca2adb0874252b81/x/bank/keeper/keeper.go#L85-L122>
Regardless if an error is wrapped or not, the Cosmos SDK's `errors` package provides an API to determine if
an error is of a particular kind via `Is`.

14
docs/building-modules/genesis.md
View File

@ -8,8 +8,8 @@ Modules generally handle a subset of the state and, as such, they need to define
## Pre-requisite Readings
- [Module Manager](./module-manager.md) {prereq}
- [Keepers](./keeper.md) {prereq}
* [Module Manager](./module-manager.md) {prereq}
* [Keepers](./keeper.md) {prereq}
## Type Definition
@ -17,7 +17,7 @@ The subset of the genesis state defined from a given module is generally defined
See an example of `GenesisState` protobuf message definition from the `auth` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/a9547b54ffac9729fe1393651126ddfc0d236cff/proto/cosmos/auth/v1beta1/genesis.proto
+++ <https://github.com/cosmos/cosmos-sdk/blob/a9547b54ffac9729fe1393651126ddfc0d236cff/proto/cosmos/auth/v1beta1/genesis.proto>
Next we present the main genesis-related methods that need to be implemented by module developers in order for their module to be used in Cosmos SDK applications.
@ -25,13 +25,13 @@ Next we present the main genesis-related methods that need to be implemented by
The `DefaultGenesis()` method is a simple method that calls the constructor function for `GenesisState` with the default value for each parameter. See an example from the `auth` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/module.go#L48-L52
+++ <https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/module.go#L48-L52>
### `ValidateGenesis`
The `ValidateGenesis(genesisState GenesisState)` method is called to verify that the provided `genesisState` is correct. It should perform validity checks on each of the parameters listed in `GenesisState`. See an example from the `auth` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/types/genesis.go#L57-L70
+++ <https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/types/genesis.go#L57-L70>
## Other Genesis Methods
@ -45,7 +45,7 @@ The [module manager](./module-manager.md#manager) of the application is responsi
See an example of `InitGenesis` from the `auth` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/genesis.go#L13-L28
+++ <https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/genesis.go#L13-L28>
### `ExportGenesis`
@ -53,7 +53,7 @@ The `ExportGenesis` method is executed whenever an export of the state is made.
See an example of `ExportGenesis` from the `auth` module.
+++ https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/genesis.go#L31-L42
+++ <https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/genesis.go#L31-L42>
## Next {hide}

20
docs/building-modules/intro.md
View File

@ -8,8 +8,8 @@ Modules define most of the logic of Cosmos SDK applications. Developers compose
## Pre-requisite Readings
- [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
- [Lifecycle of a Cosmos SDK transaction](../basics/tx-lifecycle.md) {prereq}
* [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
* [Lifecycle of a Cosmos SDK transaction](../basics/tx-lifecycle.md) {prereq}
## Role of Modules in a Cosmos SDK Application
@ -19,7 +19,7 @@ On top of this core, the Cosmos SDK enables developers to build modules that imp
Cosmos SDK modules can be seen as little state-machines within the state-machine. They generally define a subset of the state using one or more `KVStore`s in the [main multistore](../core/store.md), as well as a subset of [message types](./messages-and-queries.md#messages). These messages are routed by one of the main components of Cosmos SDK core, [`BaseApp`](../core/baseapp.md), to a module Protobuf [`Msg` service](./msg-services.md) that defines them.
```
```text
+
|
| Transaction relayed from the full-node's consensus engine
@ -70,18 +70,18 @@ As a result of this architecture, building a Cosmos SDK application usually revo
While there are no definitive guidelines for writing modules, here are some important design principles developers should keep in mind when building them:
- **Composability**: Cosmos SDK applications are almost always composed of multiple modules. This means developers need to carefully consider the integration of their module not only with the core of the Cosmos SDK, but also with other modules. The former is achieved by following standard design patterns outlined [here](#main-components-of-sdk-modules), while the latter is achieved by properly exposing the store(s) of the module via the [`keeper`](./keeper.md).
- **Specialization**: A direct consequence of the **composability** feature is that modules should be **specialized**. Developers should carefully establish the scope of their module and not batch multiple functionalities into the same module. This separation of concerns enables modules to be re-used in other projects and improves the upgradability of the application. **Specialization** also plays an important role in the [object-capabilities model](../core/ocap.md) of the Cosmos SDK.
- **Capabilities**: Most modules need to read and/or write to the store(s) of other modules. However, in an open-source environment, it is possible for some modules to be malicious. That is why module developers need to carefully think not only about how their module interacts with other modules, but also about how to give access to the module's store(s). The Cosmos SDK takes a capabilities-oriented approach to inter-module security. This means that each store defined by a module is accessed by a `key`, which is held by the module's [`keeper`](./keeper.md). This `keeper` defines how to access the store(s) and under what conditions. Access to the module's store(s) is done by passing a reference to the module's `keeper`.
* **Composability**: Cosmos SDK applications are almost always composed of multiple modules. This means developers need to carefully consider the integration of their module not only with the core of the Cosmos SDK, but also with other modules. The former is achieved by following standard design patterns outlined [here](#main-components-of-sdk-modules), while the latter is achieved by properly exposing the store(s) of the module via the [`keeper`](./keeper.md).
* **Specialization**: A direct consequence of the **composability** feature is that modules should be **specialized**. Developers should carefully establish the scope of their module and not batch multiple functionalities into the same module. This separation of concerns enables modules to be re-used in other projects and improves the upgradability of the application. **Specialization** also plays an important role in the [object-capabilities model](../core/ocap.md) of the Cosmos SDK.
* **Capabilities**: Most modules need to read and/or write to the store(s) of other modules. However, in an open-source environment, it is possible for some modules to be malicious. That is why module developers need to carefully think not only about how their module interacts with other modules, but also about how to give access to the module's store(s). The Cosmos SDK takes a capabilities-oriented approach to inter-module security. This means that each store defined by a module is accessed by a `key`, which is held by the module's [`keeper`](./keeper.md). This `keeper` defines how to access the store(s) and under what conditions. Access to the module's store(s) is done by passing a reference to the module's `keeper`.
## Main Components of Cosmos SDK Modules
Modules are by convention defined in the `./x/` subfolder (e.g. the `bank` module will be defined in the `./x/bank` folder). They generally share the same core components:
- A [`keeper`](./keeper.md), used to access the module's store(s) and update the state.
- A [`Msg` service](./messages-and-queries.md#messages), used to process messages when they are routed to the module by [`BaseApp`](../core/baseapp.md#message-routing) and trigger state-transitions.
- A [query service](./query-services.md), used to process user queries when they are routed to the module by [`BaseApp`](../core/baseapp.md#query-routing).
- Interfaces, for end users to query the subset of the state defined by the module and create `message`s of the custom types defined in the module.
* A [`keeper`](./keeper.md), used to access the module's store(s) and update the state.
* A [`Msg` service](./messages-and-queries.md#messages), used to process messages when they are routed to the module by [`BaseApp`](../core/baseapp.md#message-routing) and trigger state-transitions.
* A [query service](./query-services.md), used to process user queries when they are routed to the module by [`BaseApp`](../core/baseapp.md#query-routing).
* Interfaces, for end users to query the subset of the state defined by the module and create `message`s of the custom types defined in the module.
In addition to these components, modules implement the `AppModule` interface in order to be managed by the [`module manager`](./module-manager.md).

10
docs/building-modules/invariants.md
View File

@ -8,13 +8,13 @@ An invariant is a property of the application that should always be true. In the
## Pre-requisite Readings
- [Keepers](./keeper.md) {prereq}
* [Keepers](./keeper.md) {prereq}
## Implementing `Invariant`s
An `Invariant` is a function that checks for a particular invariant within a module. Module `Invariant`s must follow the `Invariant` type:
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/invariant.go#L9
+++ <https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/invariant.go#L9>
The `string` return value is the invariant message, which can be used when printing logs, and the `bool` return value is the actual result of the invariant check.
@ -69,17 +69,17 @@ The `InvariantRegistry` is a registry where the `Invariant`s of all the modules
At its core, the `InvariantRegistry` is defined in the Cosmos SDK as an interface:
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/invariant.go#L14-L17
+++ <https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/invariant.go#L14-L17>
Typically, this interface is implemented in the `keeper` of a specific module. The most used implementation of an `InvariantRegistry` can be found in the `crisis` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/crisis/keeper/keeper.go#L50-L54
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/crisis/keeper/keeper.go#L50-L54>
The `InvariantRegistry` is therefore typically instantiated by instantiating the `keeper` of the `crisis` module in the [application's constructor function](../basics/app-anatomy.md#constructor-function).
`Invariant`s can be checked manually via [`message`s](./messages-and-queries.md), but most often they are checked automatically at the end of each block. Here is an example from the `crisis` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/crisis/abci.go#L7-L14
+++ <https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/crisis/abci.go#L7-L14>
In both cases, if one of the `Invariant`s returns false, the `InvariantRegistry` can trigger special logic (e.g. have the application panic and print the `Invariant`s message in the log).

12
docs/building-modules/keeper.md
View File

@ -8,7 +8,7 @@ order: 7
## Pre-requisite Readings
- [Introduction to Cosmos SDK Modules](./intro.md) {prereq}
* [Introduction to Cosmos SDK Modules](./intro.md) {prereq}
## Motivation
@ -34,13 +34,13 @@ type Keeper struct {
For example, here is the type definition of the `keeper` from the `staking` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/3bafd8255a502e5a9cee07391cf8261538245dfd/x/staking/keeper/keeper.go#L23-L33
+++ <https://github.com/cosmos/cosmos-sdk/blob/3bafd8255a502e5a9cee07391cf8261538245dfd/x/staking/keeper/keeper.go#L23-L33>
Let us go through the different parameters:
- An expected `keeper` is a `keeper` external to a module that is required by the internal `keeper` of said module. External `keeper`s are listed in the internal `keeper`'s type definition as interfaces. These interfaces are themselves defined in an `expected_keepers.go` file in the root of the module's folder. In this context, interfaces are used to reduce the number of dependencies, as well as to facilitate the maintenance of the module itself.
- `storeKey`s grant access to the store(s) of the [multistore](../core/store.md) managed by the module. They should always remain unexposed to external modules.
- `cdc` is the [codec](../core/encoding.md) used to marshall and unmarshall structs to/from `[]byte`. The `cdc` can be any of `codec.BinaryCodec`, `codec.JSONCodec` or `codec.Codec` based on your requirements. It can be either a proto or amino codec as long as they implement these interfaces.
* An expected `keeper` is a `keeper` external to a module that is required by the internal `keeper` of said module. External `keeper`s are listed in the internal `keeper`'s type definition as interfaces. These interfaces are themselves defined in an `expected_keepers.go` file in the root of the module's folder. In this context, interfaces are used to reduce the number of dependencies, as well as to facilitate the maintenance of the module itself.
* `storeKey`s grant access to the store(s) of the [multistore](../core/store.md) managed by the module. They should always remain unexposed to external modules.
* `cdc` is the [codec](../core/encoding.md) used to marshall and unmarshall structs to/from `[]byte`. The `cdc` can be any of `codec.BinaryCodec`, `codec.JSONCodec` or `codec.Codec` based on your requirements. It can be either a proto or amino codec as long as they implement these interfaces.
Of course, it is possible to define different types of internal `keeper`s for the same module (e.g. a read-only `keeper`). Each type of `keeper` comes with its own constructor function, which is called from the [application's constructor function](../basics/app-anatomy.md). This is where `keeper`s are instantiated, and where developers make sure to pass correct instances of modules' `keeper`s to other modules that require them.
@ -78,7 +78,7 @@ The [module `KVStore`](../core/store.md#kvstore-and-commitkvstore-interfaces) al
This is an example from the `auth` module to iterate accounts:
+++ https://github.com/cosmos/cosmos-sdk/blob/bf8809ef9840b4f5369887a38d8345e2380a567f/x/auth/keeper/account.go#L70-L83
+++ <https://github.com/cosmos/cosmos-sdk/blob/bf8809ef9840b4f5369887a38d8345e2380a567f/x/auth/keeper/account.go#L70-L83>
## Next {hide}

42
docs/building-modules/messages-and-queries.md
View File

@ -8,7 +8,7 @@ order: 3
## Pre-requisite Readings
- [Introduction to Cosmos SDK Modules](./intro.md) {prereq}
* [Introduction to Cosmos SDK Modules](./intro.md) {prereq}
## Messages
@ -22,11 +22,11 @@ Starting from v0.40, defining Protobuf `Msg` services is the recommended way to
See an example of a `Msg` service definition from `x/bank` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/proto/cosmos/bank/v1beta1/tx.proto#L10-L17
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/proto/cosmos/bank/v1beta1/tx.proto#L10-L17>
Each `Msg` service method must have exactly one argument, which must implement the `sdk.Msg` interface, and a Protobuf response. The naming convention is to call the RPC argument `Msg<service-rpc-name>` and the RPC response `Msg<service-rpc-name>Response`. For example:
```
```protobuf
rpc Send(MsgSend) returns (MsgSendResponse);
```
@ -49,19 +49,19 @@ Amino `LegacyMsg`s can be defined as protobuf messages. The messages definition
A `LegacyMsg` is typically accompanied by a standard constructor function, that is called from one of the [module's interface](./module-interfaces.md). `message`s also need to implement the `sdk.Msg` interface:
+++ https://github.com/cosmos/cosmos-sdk/blob/4a1b2fba43b1052ca162b3a1e0b6db6db9c26656/types/tx_msg.go#L10-L33
+++ <https://github.com/cosmos/cosmos-sdk/blob/4a1b2fba43b1052ca162b3a1e0b6db6db9c26656/types/tx_msg.go#L10-L33>
It extends `proto.Message` and contains the following methods:
- `Route() string`: Name of the route for this message. Typically all `message`s in a module have the same route, which is most often the module's name.
- `Type() string`: Type of the message, used primarly in [events](../core/events.md). This should return a message-specific `string`, typically the denomination of the message itself.
- [`ValidateBasic() error`](../basics/tx-lifecycle.md#ValidateBasic).
- `GetSignBytes() []byte`: Return the canonical byte representation of the message. Used to generate a signature.
- `GetSigners() []AccAddress`: Return the list of signers. The Cosmos SDK will make sure that each `message` contained in a transaction is signed by all the signers listed in the list returned by this method.
* `Route() string`: Name of the route for this message. Typically all `message`s in a module have the same route, which is most often the module's name.
* `Type() string`: Type of the message, used primarly in [events](../core/events.md). This should return a message-specific `string`, typically the denomination of the message itself.
* [`ValidateBasic() error`](../basics/tx-lifecycle.md#ValidateBasic).
* `GetSignBytes() []byte`: Return the canonical byte representation of the message. Used to generate a signature.
* `GetSigners() []AccAddress`: Return the list of signers. The Cosmos SDK will make sure that each `message` contained in a transaction is signed by all the signers listed in the list returned by this method.
See an example implementation of a `message` from the `gov` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/x/gov/types/msgs.go#L77-L125
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/x/gov/types/msgs.go#L77-L125>
## Queries
@ -73,7 +73,7 @@ Starting from v0.40, the prefered way to define queries is by using [Protobuf se
Here's an example of such a `Query` service definition:
+++ https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/proto/cosmos/auth/v1beta1/query.proto#L12-L23
+++ <https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/proto/cosmos/auth/v1beta1/query.proto#L12-L23>
As `proto.Message`s, generated `Response` types implement by default `String()` method of [`fmt.Stringer`](https://golang.org/pkg/fmt/#Stringer).
@ -83,22 +83,22 @@ A `RegisterQueryServer` method is also generated and should be used to register
Before the introduction of Protobuf and gRPC in the Cosmos SDK, there was usually no specific `query` object defined by module developers, contrary to `message`s. Instead, the Cosmos SDK took the simpler approach of using a simple `path` to define each `query`. The `path` contains the `query` type and all the arguments needed in order to process it. For most module queries, the `path` should look like the following:
```
```text
queryCategory/queryRoute/queryType/arg1/arg2/...
```
where:
- `queryCategory` is the category of the `query`, typically `custom` for module queries. It is used to differentiate between different kinds of queries within `BaseApp`'s [`Query` method](../core/baseapp.md#query).
- `queryRoute` is used by `BaseApp`'s [`queryRouter`](../core/baseapp.md#query-routing) to map the `query` to its module. Usually, `queryRoute` should be the name of the module.
- `queryType` is used by the module's [`querier`](./query-services.md#legacy-queriers) to map the `query` to the appropriate `querier function` within the module.
- `args` are the actual arguments needed to process the `query`. They are filled out by the end-user. Note that for bigger queries, you might prefer passing arguments in the `Data` field of the request `req` instead of the `path`.
* `queryCategory` is the category of the `query`, typically `custom` for module queries. It is used to differentiate between different kinds of queries within `BaseApp`'s [`Query` method](../core/baseapp.md#query).
* `queryRoute` is used by `BaseApp`'s [`queryRouter`](../core/baseapp.md#query-routing) to map the `query` to its module. Usually, `queryRoute` should be the name of the module.
* `queryType` is used by the module's [`querier`](./query-services.md#legacy-queriers) to map the `query` to the appropriate `querier function` within the module.
* `args` are the actual arguments needed to process the `query`. They are filled out by the end-user. Note that for bigger queries, you might prefer passing arguments in the `Data` field of the request `req` instead of the `path`.
The `path` for each `query` must be defined by the module developer in the module's [command-line interface file](./module-interfaces.md#query-commands).Overall, there are 3 mains components module developers need to implement in order to make the subset of the state defined by their module queryable:
- A [`querier`](./query-services.md#legacy-queriers), to process the `query` once it has been [routed to the module](../core/baseapp.md#query-routing).
- [Query commands](./module-interfaces.md#query-commands) in the module's CLI file, where the `path` for each `query` is specified.
- `query` return types. Typically defined in a file `types/querier.go`, they specify the result type of each of the module's `queries`. These custom types must implement the `String()` method of [`fmt.Stringer`](https://golang.org/pkg/fmt/#Stringer).
* A [`querier`](./query-services.md#legacy-queriers), to process the `query` once it has been [routed to the module](../core/baseapp.md#query-routing).
* [Query commands](./module-interfaces.md#query-commands) in the module's CLI file, where the `path` for each `query` is specified.
* `query` return types. Typically defined in a file `types/querier.go`, they specify the result type of each of the module's `queries`. These custom types must implement the `String()` method of [`fmt.Stringer`](https://golang.org/pkg/fmt/#Stringer).
### Store Queries
@ -106,9 +106,9 @@ Store queries query directly for store keys. They use `clientCtx.QueryABCI(req a
See following examples:
+++ https://github.com/cosmos/cosmos-sdk/blob/080fcf1df25ccdf97f3029b6b6f83caaf5a235e4/x/ibc/core/client/query.go#L36-L46
+++ <https://github.com/cosmos/cosmos-sdk/blob/080fcf1df25ccdf97f3029b6b6f83caaf5a235e4/x/ibc/core/client/query.go#L36-L46>
+++ https://github.com/cosmos/cosmos-sdk/blob/080fcf1df25ccdf97f3029b6b6f83caaf5a235e4/baseapp/abci.go#L722-L749
+++ <https://github.com/cosmos/cosmos-sdk/blob/080fcf1df25ccdf97f3029b6b6f83caaf5a235e4/baseapp/abci.go#L722-L749>
## Next {hide}

66
docs/building-modules/module-interfaces.md
View File

@ -8,7 +8,7 @@ This document details how to build CLI and REST interfaces for a module. Example
## Prerequisite Readings
- [Building Modules Intro](./intro.md) {prereq}
* [Building Modules Intro](./intro.md) {prereq}
## CLI
@ -22,61 +22,61 @@ One of the main interfaces for an application is the [command-line interface](..
Here is an example from the `x/bank` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/client/cli/tx.go#L28-L63
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/client/cli/tx.go#L28-L63>
In the example, `NewSendTxCmd()` creates and returns the transaction command for a transaction that wraps and delivers `MsgSend`. `MsgSend` is the message used to send tokens from one account to another.
In general, the getter function does the following:
- **Constructs the command:** Read the [Cobra Documentation](https://godoc.org/github.com/spf13/cobra) for more detailed information on how to create commands.
- **Use:** Specifies the format of the user input required to invoke the command. In the example above, `send` is the name of the transaction command and `[from_key_or_address]`, `[to_address]`, and `[amount]` are the arguments.
- **Args:** The number of arguments the user provides. In this case, there are exactly three: `[from_key_or_address]`, `[to_address]`, and `[amount]`.
- **Short and Long:** Descriptions for the command. A `Short` description is expected. A `Long` description can be used to provide additional information that is displayed when a user adds the `--help` flag.
- **RunE:** Defines a function that can return an error. This is the function that is called when the command is executed. This function encapsulates all of the logic to create a new transaction.
- The function typically starts by getting the `clientCtx`, which can be done with `client.GetClientTxContext(cmd)`. The `clientCtx` contains information relevant to transaction handling, including information about the user. In this example, the `clientCtx` is used to retrieve the address of the sender by calling `clientCtx.GetFromAddress()`.
- If applicable, the command's arguments are parsed. In this example, the arguments `[to_address]` and `[amount]` are both parsed.
- A [message](./messages-and-queries.md) is created using the parsed arguments and information from the `clientCtx`. The constructor function of the message type is called directly. In this case, `types.NewMsgSend(fromAddr, toAddr, amount)`. Its good practice to call [`msg.ValidateBasic()`](../basics/tx-lifecycle.md#ValidateBasic) and other validation methods before broadcasting the message.
- Depending on what the user wants, the transaction is either generated offline or signed and broadcasted to the preconfigured node using `tx.GenerateOrBroadcastTxCLI(clientCtx, flags, msg)`.
- **Adds transaction flags:** All transaction commands must add a set of transaction [flags](#flags). The transaction flags are used to collect additional information from the user (e.g. the amount of fees the user is willing to pay). The transaction flags are added to the constructed command using `AddTxFlagsToCmd(cmd)`.
- **Returns the command:** Finally, the transaction command is returned.
* **Constructs the command:** Read the [Cobra Documentation](https://godoc.org/github.com/spf13/cobra) for more detailed information on how to create commands.
* **Use:** Specifies the format of the user input required to invoke the command. In the example above, `send` is the name of the transaction command and `[from_key_or_address]`, `[to_address]`, and `[amount]` are the arguments.
* **Args:** The number of arguments the user provides. In this case, there are exactly three: `[from_key_or_address]`, `[to_address]`, and `[amount]`.
* **Short and Long:** Descriptions for the command. A `Short` description is expected. A `Long` description can be used to provide additional information that is displayed when a user adds the `--help` flag.
* **RunE:** Defines a function that can return an error. This is the function that is called when the command is executed. This function encapsulates all of the logic to create a new transaction.
* The function typically starts by getting the `clientCtx`, which can be done with `client.GetClientTxContext(cmd)`. The `clientCtx` contains information relevant to transaction handling, including information about the user. In this example, the `clientCtx` is used to retrieve the address of the sender by calling `clientCtx.GetFromAddress()`.
* If applicable, the command's arguments are parsed. In this example, the arguments `[to_address]` and `[amount]` are both parsed.
* A [message](./messages-and-queries.md) is created using the parsed arguments and information from the `clientCtx`. The constructor function of the message type is called directly. In this case, `types.NewMsgSend(fromAddr, toAddr, amount)`. Its good practice to call [`msg.ValidateBasic()`](../basics/tx-lifecycle.md#ValidateBasic) and other validation methods before broadcasting the message.
* Depending on what the user wants, the transaction is either generated offline or signed and broadcasted to the preconfigured node using `tx.GenerateOrBroadcastTxCLI(clientCtx, flags, msg)`.
* **Adds transaction flags:** All transaction commands must add a set of transaction [flags](#flags). The transaction flags are used to collect additional information from the user (e.g. the amount of fees the user is willing to pay). The transaction flags are added to the constructed command using `AddTxFlagsToCmd(cmd)`.
* **Returns the command:** Finally, the transaction command is returned.
Each module must implement `NewTxCmd()`, which aggregates all of the transaction commands of the module. Here is an example from the `x/bank` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/client/cli/tx.go#L13-L26
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/client/cli/tx.go#L13-L26>
Each module must also implement the `GetTxCmd()` method for `AppModuleBasic` that simply returns `NewTxCmd()`. This allows the root command to easily aggregate all of the transaction commands for each module. Here is an example:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/module.go#L75-L78
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/module.go#L75-L78>
### Query Commands
[Queries](./messages-and-queries.md#queries) allow users to gather information about the application or network state; they are routed by the application and processed by the module in which they are defined. Query commands typically have their own `query.go` file in the module's `./client/cli` folder. Like transaction commands, they are specified in getter functions. Here is an example of a query command from the `x/auth` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/auth/client/cli/query.go#L75-L105
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/auth/client/cli/query.go#L75-L105>
In the example, `GetAccountCmd()` creates and returns a query command that returns the state of an account based on the provided account address.
In general, the getter function does the following:
- **Constructs the command:** Read the [Cobra Documentation](https://godoc.org/github.com/spf13/cobra) for more detailed information on how to create commands.
- **Use:** Specifies the format of the user input required to invoke the command. In the example above, `account` is the name of the query command and `[address]` is the argument.
- **Args:** The number of arguments the user provides. In this case, there is exactly one: `[address]`.
- **Short and Long:** Descriptions for the command. A `Short` description is expected. A `Long` description can be used to provide additional information that is displayed when a user adds the `--help` flag.
- **RunE:** Defines a function that can return an error. This is the function that is called when the command is executed. This function encapsulates all of the logic to create a new query.
- The function typically starts by getting the `clientCtx`, which can be done with `client.GetClientQueryContext(cmd)`. The `clientCtx` contains information relevant to query handling.
- If applicable, the command's arguments are parsed. In this example, the argument `[address]` is parsed.
- A new `queryClient` is initialized using `NewQueryClient(clientCtx)`. The `queryClient` is then used to call the appropriate [query](./messages-and-queries.md#grpc-queries).
- The `clientCtx.PrintProto` method is used to format the `proto.Message` object so that the results can be printed back to the user.
- **Adds query flags:** All query commands must add a set of query [flags](#flags). The query flags are added to the constructed command using `AddQueryFlagsToCmd(cmd)`.
- **Returns the command:** Finally, the query command is returned.
* **Constructs the command:** Read the [Cobra Documentation](https://godoc.org/github.com/spf13/cobra) for more detailed information on how to create commands.
* **Use:** Specifies the format of the user input required to invoke the command. In the example above, `account` is the name of the query command and `[address]` is the argument.
* **Args:** The number of arguments the user provides. In this case, there is exactly one: `[address]`.
* **Short and Long:** Descriptions for the command. A `Short` description is expected. A `Long` description can be used to provide additional information that is displayed when a user adds the `--help` flag.
* **RunE:** Defines a function that can return an error. This is the function that is called when the command is executed. This function encapsulates all of the logic to create a new query.
* The function typically starts by getting the `clientCtx`, which can be done with `client.GetClientQueryContext(cmd)`. The `clientCtx` contains information relevant to query handling.
* If applicable, the command's arguments are parsed. In this example, the argument `[address]` is parsed.
* A new `queryClient` is initialized using `NewQueryClient(clientCtx)`. The `queryClient` is then used to call the appropriate [query](./messages-and-queries.md#grpc-queries).
* The `clientCtx.PrintProto` method is used to format the `proto.Message` object so that the results can be printed back to the user.
* **Adds query flags:** All query commands must add a set of query [flags](#flags). The query flags are added to the constructed command using `AddQueryFlagsToCmd(cmd)`.
* **Returns the command:** Finally, the query command is returned.
Each module must implement `GetQueryCmd()`, which aggregates all of the query commands of the module. Here is an example from the `x/auth` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/auth/client/cli/query.go#L25-L42
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/auth/client/cli/query.go#L25-L42>
Each module must also implement the `GetQueryCmd()` method for `AppModuleBasic` that returns the `GetQueryCmd()` function. This allows for the root command to easily aggregate all of the query commands for each module. Here is an example:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/auth/module.go#L80-L83
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/auth/module.go#L80-L83>
### Flags
@ -102,13 +102,13 @@ For more detailed information on creating flags, visit the [Cobra Documentation]
As mentioned in [transaction commands](#transaction-commands), there is a set of flags that all transaction commands must add. This is done with the `AddTxFlagsToCmd` method defined in the Cosmos SDK's `./client/flags` package.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/client/flags/flags.go#L94-L120
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/client/flags/flags.go#L94-L120>
Since `AddTxFlagsToCmd(cmd *cobra.Command)` includes all of the basic flags required for a transaction command, module developers may choose not to add any of their own (specifying arguments instead may often be more appropriate).
Similarly, there is a `AddQueryFlagsToCmd(cmd *cobra.Command)` to add common flags to a module query command.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/client/flags/flags.go#L85-L92
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/client/flags/flags.go#L85-L92>
## gRPC
@ -120,7 +120,7 @@ In order to do that, modules must implement `RegisterGRPCGatewayRoutes(clientCtx
Here's an example from the `x/auth` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/auth/module.go#L68-L73
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/auth/module.go#L68-L73>
## gRPC-gateway REST
@ -128,7 +128,7 @@ Applications need to support web services that use HTTP requests (e.g. a web wal
Modules that want to expose REST queries should add `google.api.http` annotations to their `rpc` methods, such as in the example below from the `x/auth` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/auth/v1beta1/query.proto#L13-L29
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/auth/v1beta1/query.proto#L13-L29>
gRPC gateway is started in-process along with the application and Tendermint. It can be enabled or disabled by setting gRPC Configuration `enable` in [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml).

98
docs/building-modules/module-manager.md
View File

@ -8,15 +8,15 @@ Cosmos SDK modules need to implement the [`AppModule` interfaces](#application-m
## Pre-requisite Readings
- [Introduction to Cosmos SDK Modules](./intro.md) {prereq}
* [Introduction to Cosmos SDK Modules](./intro.md) {prereq}
## Application Module Interfaces
Application module interfaces exist to facilitate the composition of modules together to form a functional Cosmos SDK application. There are 3 main application module interfaces:
- [`AppModuleBasic`](#appmodulebasic) for independent module functionalities.
- [`AppModule`](#appmodule) for inter-dependent module functionalities (except genesis-related functionalities).
- [`AppModuleGenesis`](#appmodulegenesis) for inter-dependent genesis-related module functionalities.
* [`AppModuleBasic`](#appmodulebasic) for independent module functionalities.
* [`AppModule`](#appmodule) for inter-dependent module functionalities (except genesis-related functionalities).
* [`AppModuleGenesis`](#appmodulegenesis) for inter-dependent genesis-related module functionalities.
The `AppModuleBasic` interface exists to define independent methods of the module, i.e. those that do not depend on other modules in the application. This allows for the construction of the basic application structure early in the application definition, generally in the `init()` function of the [main application file](../basics/app-anatomy.md#core-application-file).
@ -29,19 +29,19 @@ are only used for genesis can take advantage of the `Module` patterns without ha
The `AppModuleBasic` interface defines the independent methods modules need to implement.
+++ https://github.com/cosmos/cosmos-sdk/blob/325be6ff215db457c6fc7668109640cd7fdac461/types/module/module.go#L49-L63
+++ <https://github.com/cosmos/cosmos-sdk/blob/325be6ff215db457c6fc7668109640cd7fdac461/types/module/module.go#L49-L63>
Let us go through the methods:
- `Name()`: Returns the name of the module as a `string`.
- `RegisterLegacyAminoCodec(*codec.LegacyAmino)`: Registers the `amino` codec for the module, which is used to marshal and unmarshal structs to/from `[]byte` in order to persist them in the module's `KVStore`.
- `RegisterInterfaces(codectypes.InterfaceRegistry)`: Registers a module's interface types and their concrete implementations as `proto.Message`.
- `DefaultGenesis(codec.JSONCodec)`: Returns a default [`GenesisState`](./genesis.md#genesisstate) for the module, marshalled to `json.RawMessage`. The default `GenesisState` need to be defined by the module developer and is primarily used for testing.
- `ValidateGenesis(codec.JSONCodec, client.TxEncodingConfig, json.RawMessage)`: Used to validate the `GenesisState` defined by a module, given in its `json.RawMessage` form. It will usually unmarshall the `json` before running a custom [`ValidateGenesis`](./genesis.md#validategenesis) function defined by the module developer.
- `RegisterRESTRoutes(client.Context, *mux.Router)`: Registers the REST routes for the module. These routes will be used to map REST request to the module in order to process them. See [gRPC and REST](../core/grpc_rest.md) for more.
- `RegisterGRPCGatewayRoutes(client.Context, *runtime.ServeMux)`: Registers gRPC routes for the module.
- `GetTxCmd()`: Returns the root [`Tx` command](./module-interfaces.md#tx) for the module. The subcommands of this root command are used by end-users to generate new transactions containing [`message`s](./messages-and-queries.md#queries) defined in the module.
- `GetQueryCmd()`: Return the root [`query` command](./module-interfaces.md#query) for the module. The subcommands of this root command are used by end-users to generate new queries to the subset of the state defined by the module.
* `Name()`: Returns the name of the module as a `string`.
* `RegisterLegacyAminoCodec(*codec.LegacyAmino)`: Registers the `amino` codec for the module, which is used to marshal and unmarshal structs to/from `[]byte` in order to persist them in the module's `KVStore`.
* `RegisterInterfaces(codectypes.InterfaceRegistry)`: Registers a module's interface types and their concrete implementations as `proto.Message`.
* `DefaultGenesis(codec.JSONCodec)`: Returns a default [`GenesisState`](./genesis.md#genesisstate) for the module, marshalled to `json.RawMessage`. The default `GenesisState` need to be defined by the module developer and is primarily used for testing.
* `ValidateGenesis(codec.JSONCodec, client.TxEncodingConfig, json.RawMessage)`: Used to validate the `GenesisState` defined by a module, given in its `json.RawMessage` form. It will usually unmarshall the `json` before running a custom [`ValidateGenesis`](./genesis.md#validategenesis) function defined by the module developer.
* `RegisterRESTRoutes(client.Context, *mux.Router)`: Registers the REST routes for the module. These routes will be used to map REST request to the module in order to process them. See [gRPC and REST](../core/grpc_rest.md) for more.
* `RegisterGRPCGatewayRoutes(client.Context, *runtime.ServeMux)`: Registers gRPC routes for the module.
* `GetTxCmd()`: Returns the root [`Tx` command](./module-interfaces.md#tx) for the module. The subcommands of this root command are used by end-users to generate new transactions containing [`message`s](./messages-and-queries.md#queries) defined in the module.
* `GetQueryCmd()`: Return the root [`query` command](./module-interfaces.md#query) for the module. The subcommands of this root command are used by end-users to generate new queries to the subset of the state defined by the module.
All the `AppModuleBasic` of an application are managed by the [`BasicManager`](#basicmanager).
@ -49,12 +49,12 @@ All the `AppModuleBasic` of an application are managed by the [`BasicManager`](#
The `AppModuleGenesis` interface is a simple embedding of the `AppModuleBasic` interface with two added methods.
+++ https://github.com/cosmos/cosmos-sdk/blob/325be6ff215db457c6fc7668109640cd7fdac461/types/module/module.go#L152-L158
+++ <https://github.com/cosmos/cosmos-sdk/blob/325be6ff215db457c6fc7668109640cd7fdac461/types/module/module.go#L152-L158>
Let us go through the two added methods:
- `InitGenesis(sdk.Context, codec.JSONCodec, json.RawMessage)`: Initializes the subset of the state managed by the module. It is called at genesis (i.e. when the chain is first started).
- `ExportGenesis(sdk.Context, codec.JSONCodec)`: Exports the latest subset of the state managed by the module to be used in a new genesis file. `ExportGenesis` is called for each module when a new chain is started from the state of an existing chain.
* `InitGenesis(sdk.Context, codec.JSONCodec, json.RawMessage)`: Initializes the subset of the state managed by the module. It is called at genesis (i.e. when the chain is first started).
* `ExportGenesis(sdk.Context, codec.JSONCodec)`: Exports the latest subset of the state managed by the module to be used in a new genesis file. `ExportGenesis` is called for each module when a new chain is started from the state of an existing chain.
It does not have its own manager, and exists separately from [`AppModule`](#appmodule) only for modules that exist only to implement genesis functionalities, so that they can be managed without having to implement all of `AppModule`'s methods. If the module is not only used during genesis, `InitGenesis(sdk.Context, codec.JSONCodec, json.RawMessage)` and `ExportGenesis(sdk.Context, codec.JSONCodec)` will generally be defined as methods of the concrete type implementing the `AppModule` interface.
@ -62,19 +62,19 @@ It does not have its own manager, and exists separately from [`AppModule`](#appm
The `AppModule` interface defines the inter-dependent methods that modules need to implement.
+++ https://github.com/cosmos/cosmos-sdk/blob/b4cce159bcc6a32ac78245c6866dd87c73f3720d/types/module/module.go#L160-L182
+++ <https://github.com/cosmos/cosmos-sdk/blob/b4cce159bcc6a32ac78245c6866dd87c73f3720d/types/module/module.go#L160-L182>
`AppModule`s are managed by the [module manager](#manager). This interface embeds the `AppModuleGenesis` interface so that the manager can access all the independent and genesis inter-dependent methods of the module. This means that a concrete type implementing the `AppModule` interface must either implement all the methods of `AppModuleGenesis` (and by extension `AppModuleBasic`), or include a concrete type that does as parameter.
Let us go through the methods of `AppModule`:
- `RegisterInvariants(sdk.InvariantRegistry)`: Registers the [`invariants`](./invariants.md) of the module. If an invariant deviates from its predicted value, the [`InvariantRegistry`](./invariants.md#registry) triggers appropriate logic (most often the chain will be halted).
- `Route()`: Returns the route for [`message`s](./messages-and-queries.md#messages) to be routed to the module by [`BaseApp`](../core/baseapp.md#message-routing).
- `QuerierRoute()` (deprecated): Returns the name of the module's query route, for [`queries`](./messages-and-queries.md#queries) to be routes to the module by [`BaseApp`](../core/baseapp.md#query-routing).
- `LegacyQuerierHandler(*codec.LegacyAmino)` (deprecated): Returns a [`querier`](./query-services.md#legacy-queriers) given the query `path`, in order to process the `query`.
- `RegisterServices(Configurator)`: Allows a module to register services.
- `BeginBlock(sdk.Context, abci.RequestBeginBlock)`: This method gives module developers the option to implement logic that is automatically triggered at the beginning of each block. Implement empty if no logic needs to be triggered at the beginning of each block for this module.
- `EndBlock(sdk.Context, abci.RequestEndBlock)`: This method gives module developers the option to implement logic that is automatically triggered at the end of each block. This is also where the module can inform the underlying consensus engine of validator set changes (e.g. the `staking` module). Implement empty if no logic needs to be triggered at the end of each block for this module.
* `RegisterInvariants(sdk.InvariantRegistry)`: Registers the [`invariants`](./invariants.md) of the module. If an invariant deviates from its predicted value, the [`InvariantRegistry`](./invariants.md#registry) triggers appropriate logic (most often the chain will be halted).
* `Route()`: Returns the route for [`message`s](./messages-and-queries.md#messages) to be routed to the module by [`BaseApp`](../core/baseapp.md#message-routing).
* `QuerierRoute()` (deprecated): Returns the name of the module's query route, for [`queries`](./messages-and-queries.md#queries) to be routes to the module by [`BaseApp`](../core/baseapp.md#query-routing).
* `LegacyQuerierHandler(*codec.LegacyAmino)` (deprecated): Returns a [`querier`](./query-services.md#legacy-queriers) given the query `path`, in order to process the `query`.
* `RegisterServices(Configurator)`: Allows a module to register services.
* `BeginBlock(sdk.Context, abci.RequestBeginBlock)`: This method gives module developers the option to implement logic that is automatically triggered at the beginning of each block. Implement empty if no logic needs to be triggered at the beginning of each block for this module.
* `EndBlock(sdk.Context, abci.RequestEndBlock)`: This method gives module developers the option to implement logic that is automatically triggered at the end of each block. This is also where the module can inform the underlying consensus engine of validator set changes (e.g. the `staking` module). Implement empty if no logic needs to be triggered at the end of each block for this module.
### Implementing the Application Module Interfaces
@ -106,44 +106,44 @@ Module managers are used to manage collections of `AppModuleBasic` and `AppModul
The `BasicManager` is a structure that lists all the `AppModuleBasic` of an application:
+++ https://github.com/cosmos/cosmos-sdk/blob/325be6ff215db457c6fc7668109640cd7fdac461/types/module/module.go#L65-L66
+++ <https://github.com/cosmos/cosmos-sdk/blob/325be6ff215db457c6fc7668109640cd7fdac461/types/module/module.go#L65-L66>
It implements the following methods:
- `NewBasicManager(modules ...AppModuleBasic)`: Constructor function. It takes a list of the application's `AppModuleBasic` and builds a new `BasicManager`. This function is generally called in the `init()` function of [`app.go`](../basics/app-anatomy.md#core-application-file) to quickly initialize the independent elements of the application's modules (click [here](https://github.com/cosmos/gaia/blob/master/app/app.go#L59-L74) to see an example).
- `RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)`: Registers the [`codec.LegacyAmino`s](../core/encoding.md#amino) of each of the application's `AppModuleBasic`. This function is usually called early on in the [application's construction](../basics/app-anatomy.md#constructor).
- `RegisterInterfaces(registry codectypes.InterfaceRegistry)`: Registers interface types and implementations of each of the application's `AppModuleBasic`.
- `DefaultGenesis(cdc codec.JSONCodec)`: Provides default genesis information for modules in the application by calling the [`DefaultGenesis(cdc codec.JSONCodec)`](./genesis.md#defaultgenesis) function of each module. It is used to construct a default genesis file for the application.
- `ValidateGenesis(cdc codec.JSONCodec, txEncCfg client.TxEncodingConfig, genesis map[string]json.RawMessage)`: Validates the genesis information modules by calling the [`ValidateGenesis(codec.JSONCodec, client.TxEncodingConfig, json.RawMessage)`](./genesis.md#validategenesis) function of each module.
- `RegisterRESTRoutes(ctx client.Context, rtr *mux.Router)`: Registers REST routes for modules by calling the [`RegisterRESTRoutes`](./module-interfaces.md#register-routes) function of each module. This function is usually called function from the `main.go` function of the [application's command-line interface](../core/cli.md).
- `RegisterGRPCGatewayRoutes(clientCtx client.Context, rtr *runtime.ServeMux)`: Registers gRPC routes for modules.
- `AddTxCommands(rootTxCmd *cobra.Command)`: Adds modules' transaction commands to the application's [`rootTxCommand`](../core/cli.md#transaction-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../core/cli.md).
- `AddQueryCommands(rootQueryCmd *cobra.Command)`: Adds modules' query commands to the application's [`rootQueryCommand`](../core/cli.md#query-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../core/cli.md).
* `NewBasicManager(modules ...AppModuleBasic)`: Constructor function. It takes a list of the application's `AppModuleBasic` and builds a new `BasicManager`. This function is generally called in the `init()` function of [`app.go`](../basics/app-anatomy.md#core-application-file) to quickly initialize the independent elements of the application's modules (click [here](https://github.com/cosmos/gaia/blob/master/app/app.go#L59-L74) to see an example).
* `RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)`: Registers the [`codec.LegacyAmino`s](../core/encoding.md#amino) of each of the application's `AppModuleBasic`. This function is usually called early on in the [application's construction](../basics/app-anatomy.md#constructor).
* `RegisterInterfaces(registry codectypes.InterfaceRegistry)`: Registers interface types and implementations of each of the application's `AppModuleBasic`.
* `DefaultGenesis(cdc codec.JSONCodec)`: Provides default genesis information for modules in the application by calling the [`DefaultGenesis(cdc codec.JSONCodec)`](./genesis.md#defaultgenesis) function of each module. It is used to construct a default genesis file for the application.
* `ValidateGenesis(cdc codec.JSONCodec, txEncCfg client.TxEncodingConfig, genesis map[string]json.RawMessage)`: Validates the genesis information modules by calling the [`ValidateGenesis(codec.JSONCodec, client.TxEncodingConfig, json.RawMessage)`](./genesis.md#validategenesis) function of each module.
* `RegisterRESTRoutes(ctx client.Context, rtr *mux.Router)`: Registers REST routes for modules by calling the [`RegisterRESTRoutes`](./module-interfaces.md#register-routes) function of each module. This function is usually called function from the `main.go` function of the [application's command-line interface](../core/cli.md).
* `RegisterGRPCGatewayRoutes(clientCtx client.Context, rtr *runtime.ServeMux)`: Registers gRPC routes for modules.
* `AddTxCommands(rootTxCmd *cobra.Command)`: Adds modules' transaction commands to the application's [`rootTxCommand`](../core/cli.md#transaction-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../core/cli.md).
* `AddQueryCommands(rootQueryCmd *cobra.Command)`: Adds modules' query commands to the application's [`rootQueryCommand`](../core/cli.md#query-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../core/cli.md).
### `Manager`
The `Manager` is a structure that holds all the `AppModule` of an application, and defines the order of execution between several key components of these modules:
+++ https://github.com/cosmos/cosmos-sdk/blob/325be6ff215db457c6fc7668109640cd7fdac461/types/module/module.go#L223-L231
+++ <https://github.com/cosmos/cosmos-sdk/blob/325be6ff215db457c6fc7668109640cd7fdac461/types/module/module.go#L223-L231>
The module manager is used throughout the application whenever an action on a collection of modules is required. It implements the following methods:
- `NewManager(modules ...AppModule)`: Constructor function. It takes a list of the application's `AppModule`s and builds a new `Manager`. It is generally called from the application's main [constructor function](../basics/app-anatomy.md#constructor-function).
- `SetOrderInitGenesis(moduleNames ...string)`: Sets the order in which the [`InitGenesis`](./genesis.md#initgenesis) function of each module will be called when the application is first started. This function is generally called from the application's main [constructor function](../basics/app-anatomy.md#constructor-function).
- `SetOrderExportGenesis(moduleNames ...string)`: Sets the order in which the [`ExportGenesis`](./genesis.md#exportgenesis) function of each module will be called in case of an export. This function is generally called from the application's main [constructor function](../basics/app-anatomy.md#constructor-function).
- `SetOrderBeginBlockers(moduleNames ...string)`: Sets the order in which the `BeginBlock()` function of each module will be called at the beginning of each block. This function is generally called from the application's main [constructor function](../basics/app-anatomy.md#constructor-function).
- `SetOrderEndBlockers(moduleNames ...string)`: Sets the order in which the `EndBlock()` function of each module will be called at the end of each block. This function is generally called from the application's main [constructor function](../basics/app-anatomy.md#constructor-function).
- `RegisterInvariants(ir sdk.InvariantRegistry)`: Registers the [invariants](./invariants.md) of each module.
- `RegisterRoutes(router sdk.Router, queryRouter sdk.QueryRouter, legacyQuerierCdc *codec.LegacyAmino)`: Registers legacy [`Msg`](./messages-and-queries.md#messages) and [`querier`](./query-services.md#legacy-queriers) routes.
- `RegisterServices(cfg Configurator)`: Registers all module services.
- `InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, genesisData map[string]json.RawMessage)`: Calls the [`InitGenesis`](./genesis.md#initgenesis) function of each module when the application is first started, in the order defined in `OrderInitGenesis`. Returns an `abci.ResponseInitChain` to the underlying consensus engine, which can contain validator updates.
- `ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec)`: Calls the [`ExportGenesis`](./genesis.md#exportgenesis) function of each module, in the order defined in `OrderExportGenesis`. The export constructs a genesis file from a previously existing state, and is mainly used when a hard-fork upgrade of the chain is required.
- `BeginBlock(ctx sdk.Context, req abci.RequestBeginBlock)`: At the beginning of each block, this function is called from [`BaseApp`](../core/baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./beginblock-endblock.md) function of each module, in the order defined in `OrderBeginBlockers`. It creates a child [context](../core/context.md) with an event manager to aggregate [events](../core/events.md) emitted from all modules. The function returns an `abci.ResponseBeginBlock` which contains the aforementioned events.
- `EndBlock(ctx sdk.Context, req abci.RequestEndBlock)`: At the end of each block, this function is called from [`BaseApp`](../core/baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./beginblock-endblock.md) function of each module, in the order defined in `OrderEndBlockers`. It creates a child [context](../core/context.md) with an event manager to aggregate [events](../core/events.md) emitted from all modules. The function returns an `abci.ResponseEndBlock` which contains the aforementioned events, as well as validator set updates (if any).
* `NewManager(modules ...AppModule)`: Constructor function. It takes a list of the application's `AppModule`s and builds a new `Manager`. It is generally called from the application's main [constructor function](../basics/app-anatomy.md#constructor-function).
* `SetOrderInitGenesis(moduleNames ...string)`: Sets the order in which the [`InitGenesis`](./genesis.md#initgenesis) function of each module will be called when the application is first started. This function is generally called from the application's main [constructor function](../basics/app-anatomy.md#constructor-function).
* `SetOrderExportGenesis(moduleNames ...string)`: Sets the order in which the [`ExportGenesis`](./genesis.md#exportgenesis) function of each module will be called in case of an export. This function is generally called from the application's main [constructor function](../basics/app-anatomy.md#constructor-function).
* `SetOrderBeginBlockers(moduleNames ...string)`: Sets the order in which the `BeginBlock()` function of each module will be called at the beginning of each block. This function is generally called from the application's main [constructor function](../basics/app-anatomy.md#constructor-function).
* `SetOrderEndBlockers(moduleNames ...string)`: Sets the order in which the `EndBlock()` function of each module will be called at the end of each block. This function is generally called from the application's main [constructor function](../basics/app-anatomy.md#constructor-function).
* `RegisterInvariants(ir sdk.InvariantRegistry)`: Registers the [invariants](./invariants.md) of each module.
* `RegisterRoutes(router sdk.Router, queryRouter sdk.QueryRouter, legacyQuerierCdc *codec.LegacyAmino)`: Registers legacy [`Msg`](./messages-and-queries.md#messages) and [`querier`](./query-services.md#legacy-queriers) routes.
* `RegisterServices(cfg Configurator)`: Registers all module services.
* `InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, genesisData map[string]json.RawMessage)`: Calls the [`InitGenesis`](./genesis.md#initgenesis) function of each module when the application is first started, in the order defined in `OrderInitGenesis`. Returns an `abci.ResponseInitChain` to the underlying consensus engine, which can contain validator updates.
* `ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec)`: Calls the [`ExportGenesis`](./genesis.md#exportgenesis) function of each module, in the order defined in `OrderExportGenesis`. The export constructs a genesis file from a previously existing state, and is mainly used when a hard-fork upgrade of the chain is required.
* `BeginBlock(ctx sdk.Context, req abci.RequestBeginBlock)`: At the beginning of each block, this function is called from [`BaseApp`](../core/baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./beginblock-endblock.md) function of each module, in the order defined in `OrderBeginBlockers`. It creates a child [context](../core/context.md) with an event manager to aggregate [events](../core/events.md) emitted from all modules. The function returns an `abci.ResponseBeginBlock` which contains the aforementioned events.
* `EndBlock(ctx sdk.Context, req abci.RequestEndBlock)`: At the end of each block, this function is called from [`BaseApp`](../core/baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./beginblock-endblock.md) function of each module, in the order defined in `OrderEndBlockers`. It creates a child [context](../core/context.md) with an event manager to aggregate [events](../core/events.md) emitted from all modules. The function returns an `abci.ResponseEndBlock` which contains the aforementioned events, as well as validator set updates (if any).
Here's an example of a concrete integration within an application:
+++ https://github.com/cosmos/cosmos-sdk/blob/2323f1ac0e9a69a0da6b43693061036134193464/simapp/app.go#L315-L362
+++ <https://github.com/cosmos/cosmos-sdk/blob/2323f1ac0e9a69a0da6b43693061036134193464/simapp/app.go#L315-L362>
## Next {hide}

30
docs/building-modules/msg-services.md
View File

@ -8,8 +8,8 @@ A Protobuf `Msg` service processes [messages](./messages-and-queries.md#messages
## Pre-requisite Readings
- [Module Manager](./module-manager.md) {prereq}
- [Messages and Queries](./messages-and-queries.md) {prereq}
* [Module Manager](./module-manager.md) {prereq}
* [Messages and Queries](./messages-and-queries.md) {prereq}
## Implementation of a module `Msg` service
@ -19,15 +19,15 @@ As further described in [ADR 031](../architecture/adr-031-msg-service.md), this
Protobuf generates a `MsgServer` interface based on a definition of `Msg` service. It is the role of the module developer to implement this interface, by implementing the state transition logic that should happen upon receival of each `sdk.Msg`. As an example, here is the generated `MsgServer` interface for `x/bank`, which exposes two `sdk.Msg`s:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/bank/types/tx.pb.go#L285-L291
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/bank/types/tx.pb.go#L285-L291>
When possible, the existing module's [`Keeper`](keeper.md) should implement `MsgServer`, otherwise a `msgServer` struct that embeds the `Keeper` can be created, typically in `./keeper/msg_server.go`:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/x/bank/keeper/msg_server.go#L14-L16
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/x/bank/keeper/msg_server.go#L14-L16>
`msgServer` methods can retrieve the `sdk.Context` from the `context.Context` parameter method using the `sdk.UnwrapSDKContext`:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/x/bank/keeper/msg_server.go#L27-L28
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/x/bank/keeper/msg_server.go#L27-L28>
`sdk.Msg` processing usually follows these 3 steps:
@ -56,7 +56,7 @@ After the validation is successful, the `msgServer` method uses the [`keeper`](.
Before returning, `msgServer` methods generally emit one or more [events](../core/events.md) by using the `EventManager` held in the `ctx`. Use the new `EmitTypedEvent` function that uses protobuf-based event types:
```
```go
ctx.EventManager().EmitTypedEvent(
&group.EventABC{Key1: Value1, Key2, Value2})
```
@ -77,11 +77,11 @@ These events are relayed back to the underlying consensus engine and can be used
The invoked `msgServer` method returns a `proto.Message` response and an `error`. These return values are then wrapped into an `*sdk.Result` or an `error` using `sdk.WrapServiceResult(ctx sdk.Context, res proto.Message, err error)`:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc2/baseapp/msg_service_router.go#L104-L104
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc2/baseapp/msg_service_router.go#L104-L104>
This method takes care of marshaling the `res` parameter to protobuf and attaching any events on the `ctx.EventManager()` to the `sdk.Result`.
+++ https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/proto/cosmos/base/abci/v1beta1/abci.proto#L81-L95
+++ <https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/proto/cosmos/base/abci/v1beta1/abci.proto#L81-L95>
This diagram shows a typical structure of a Protobuf `Msg` service, and how the message propagates through the module.
@ -95,25 +95,25 @@ The `handler` type defined in the Cosmos SDK will be deprecated in favor of [`Ms
Here is the typical structure of a `handler` function:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc2/types/handler.go#L4-L4
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc2/types/handler.go#L4-L4>
Let us break it down:
- The [`LegacyMsg`](./messages-and-queries.md#messages) is the actual object being processed.
- The [`Context`](../core/context.md) contains all the necessary information needed to process the `msg`, as well as a branch of the latest state. If the `msg` is successfully processed, the branched version of the state contained in the `ctx` will be written to the main state (branch).
- The `*Result` returned to `BaseApp` contains (among other things) information on the execution of the `handler` and [events](../core/events.md).
* The [`LegacyMsg`](./messages-and-queries.md#messages) is the actual object being processed.
* The [`Context`](../core/context.md) contains all the necessary information needed to process the `msg`, as well as a branch of the latest state. If the `msg` is successfully processed, the branched version of the state contained in the `ctx` will be written to the main state (branch).
* The `*Result` returned to `BaseApp` contains (among other things) information on the execution of the `handler` and [events](../core/events.md).
Module `handler`s are typically implemented in a `./handler.go` file inside the module's folder. The [module manager](./module-manager.md) is used to add the module's `handler`s to the
[application's `router`](../core/baseapp.md#message-routing) via the `Route()` method. Typically,
the manager's `Route()` method simply constructs a Route that calls a `NewHandler()` method defined in `handler.go`.
+++ https://github.com/cosmos/cosmos-sdk/blob/228728cce2af8d494c8b4e996d011492139b04ab/x/gov/module.go#L143-L146
+++ <https://github.com/cosmos/cosmos-sdk/blob/228728cce2af8d494c8b4e996d011492139b04ab/x/gov/module.go#L143-L146>
### Implementation
`NewHandler` function dispatches a `LegacyMsg` to appropriate handler function, usually by using a switch statement:
+++ https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/x/bank/handler.go#L13-L29
+++ <https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/x/bank/handler.go#L13-L29>
First, `NewHandler` function sets a new `EventManager` to the context to isolate events per `msg`.
Then, a simple switch calls the appropriate `handler` based on the `LegacyMsg` type.
@ -127,7 +127,7 @@ New [telemetry metrics](../core/telemetry.md) can be created from `msgServer` me
This is an example from the `x/auth/vesting` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/x/auth/vesting/msg_server.go#L73-L85
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/x/auth/vesting/msg_server.go#L73-L85>
## Next {hide}

16
docs/building-modules/query-services.md
View File

@ -8,21 +8,21 @@ A Protobuf Query service processes [`queries`](./messages-and-queries.md#queries
## Pre-requisite Readings
- [Module Manager](./module-manager.md) {prereq}
- [Messages and Queries](./messages-and-queries.md) {prereq}
* [Module Manager](./module-manager.md) {prereq}
* [Messages and Queries](./messages-and-queries.md) {prereq}
## `Querier` type
The `querier` type defined in the Cosmos SDK will be deprecated in favor of [gRPC Services](#grpc-service). It specifies the typical structure of a `querier` function:
+++ https://github.com/cosmos/cosmos-sdk/blob/9a183ffbcc0163c8deb71c7fd5f8089a83e58f05/types/queryable.go#L9
+++ <https://github.com/cosmos/cosmos-sdk/blob/9a183ffbcc0163c8deb71c7fd5f8089a83e58f05/types/queryable.go#L9>
Let us break it down:
- The `path` is an array of `string`s that contains the type of the query, and that can also contain `query` arguments. See [`queries`](./messages-and-queries.md#queries) for more information.
- The `req` itself is primarily used to retrieve arguments if they are too large to fit in the `path`. This is done using the `Data` field of `req`.
- The [`Context`](../core/context.md) contains all the necessary information needed to process the `query`, as well as a branch of the latest state. It is primarily used by the [`keeper`](./keeper.md) to access the state.
- The result `res` returned to `BaseApp`, marshalled using the application's [`codec`](../core/encoding.md).
* The `path` is an array of `string`s that contains the type of the query, and that can also contain `query` arguments. See [`queries`](./messages-and-queries.md#queries) for more information.
* The `req` itself is primarily used to retrieve arguments if they are too large to fit in the `path`. This is done using the `Data` field of `req`.
* The [`Context`](../core/context.md) contains all the necessary information needed to process the `query`, as well as a branch of the latest state. It is primarily used by the [`keeper`](./keeper.md) to access the state.
* The result `res` returned to `BaseApp`, marshalled using the application's [`codec`](../core/encoding.md).
## Implementation of a module query service
@ -43,7 +43,7 @@ from the store. Therefore, the Cosmos SDK provides a function `sdk.UnwrapSDKCont
Here's an example implementation for the bank module:
+++ https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/x/bank/keeper/grpc_query.go
+++ <https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/x/bank/keeper/grpc_query.go>
### Legacy Queriers

13
docs/building-modules/simulator.md
View File

@ -12,12 +12,11 @@ integrated with the application `SimulationManager`.
* [Simulation package](#simulation-package)
* [Store decoders](#store-decoders)
* [Randomized genesis](#randomized-genesis)
* [Randomized parameters](#randomized-parameters)
* [Randomized parameter changes](#randomized-parameter-changes)
* [Random weighted operations](#random-weighted-operations)
* [Random proposal contents](#random-proposal-contents)
* [Registering the module simulation functions](#registering-simulation-functions)
* [App simulator manager](#app-simulator-manager)
* [Simulation tests](#simulation-tests)
* [Registering simulation functions](#registering-simulation-functions)
* [App Simulator manager](#app-simulator-manager)
## Simulation package
@ -63,13 +62,13 @@ Operations on the simulation are simulated using the full [transaction cycle](..
Shown below is how weights are set:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/staking/simulation/operations.go#L18-L68
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/staking/simulation/operations.go#L18-L68>
As you can see, the weights are predefined in this case. Options exist to override this behavior with different weights. One option is to use `*rand.Rand` to define a random weight for the operation, or you can inject your own predefined weights.
Here is how one can override the above package `simappparams`.
+++ https://github.com/cosmos/gaia/blob/master/sims.mk#L9-L22
+++ <https://github.com/cosmos/gaia/blob/master/sims.mk#L9-L22>
For the last test a tool called runsim <!-- # TODO: add link to runsim readme when its created --> is used, this is used to parallelize go test instances, provide info to Github and slack integrations to provide information to your team on how the simulations are running.
@ -83,7 +82,7 @@ them to be used on the parameters.
Now that all the required functions are defined, we need to integrate them into the module pattern within the `module.go`:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.0/x/distribution/module.go
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.42.0/x/distribution/module.go>
## App Simulator manager

44
docs/building-modules/structure.md
View File

@ -22,11 +22,11 @@ proto
      └── tx.proto
```
- `{module_name}.proto`: The module's common message type definitions.
- `event.proto`: The module's message type definitions related to events.
- `genesis.proto`: The module's message type definitions related to genesis state.
- `query.proto`: The module's Query service and related message type definitions.
- `tx.proto`: The module's Msg service and related message type definitions.
* `{module_name}.proto`: The module's common message type definitions.
* `event.proto`: The module's message type definitions related to events.
* `genesis.proto`: The module's message type definitions related to genesis state.
* `query.proto`: The module's Query service and related message type definitions.
* `tx.proto`: The module's Msg service and related message type definitions.
```shell
x/{module_name}
@ -76,23 +76,23 @@ x/{module_name}
└── tx.pb.go
```
- `client/`: The module's CLI client functionality implementation and the module's integration testing suite.
- `exported/`: The module's exported types - typically interface types. If a module relies on keepers from another module, it is expected to receive the keepers as interface contracts through the `expected_keepers.go` file (see below) in order to avoid a direct dependency on the module implementing the keepers. However, these interface contracts can define methods that operate on and/or return types that are specific to the module that is implementing the keepers and this is where `exported/` comes into play. The interface types that are defined in `exported/` use canonical types, allowing for the module to receive the keepers as interface contracts through the `expected_keepers.go` file. This pattern allows for code to remain DRY and also alleviates import cycle chaos.
- `keeper/`: The module's `Keeper` and `MsgServer` implementation.
- `module/`: The module's `AppModule` and `AppModuleBasic` implementation.
- `simulation/`: The module's [simulation](./simulator.html) package defines functions used by the blockchain simulator application (`simapp`).
- `spec/`: The module's specification documents outlining important concepts, state storage structure, and message and event type definitions.
- The root directory includes type definitions for messages, events, and genesis state, including the type definitions generated by Protocol Buffers.
- `abci.go`: The module's `BeginBlocker` and `EndBlocker` implementations (this file is only required if `BeginBlocker` and/or `EndBlocker` need to be defined).
- `codec.go`: The module's registry methods for interface types.
- `errors.go`: The module's sentinel errors.
- `events.go`: The module's event types and constructors.
- `expected_keepers.go`: The module's [expected keeper](./keeper.html#type-definition) interfaces.
- `genesis.go`: The module's genesis state methods and helper functions.
- `keys.go`: The module's store keys and associated helper functions.
- `msgs.go`: The module's message type definitions and associated methods.
- `params.go`: The module's parameter type definitions and associated methods.
- `*.pb.go`: The module's type definitions generated by Protocol Buffers (as defined in the respective `*.proto` files above).
* `client/`: The module's CLI client functionality implementation and the module's integration testing suite.
* `exported/`: The module's exported types - typically interface types. If a module relies on keepers from another module, it is expected to receive the keepers as interface contracts through the `expected_keepers.go` file (see below) in order to avoid a direct dependency on the module implementing the keepers. However, these interface contracts can define methods that operate on and/or return types that are specific to the module that is implementing the keepers and this is where `exported/` comes into play. The interface types that are defined in `exported/` use canonical types, allowing for the module to receive the keepers as interface contracts through the `expected_keepers.go` file. This pattern allows for code to remain DRY and also alleviates import cycle chaos.
* `keeper/`: The module's `Keeper` and `MsgServer` implementation.
* `module/`: The module's `AppModule` and `AppModuleBasic` implementation.
* `simulation/`: The module's [simulation](./simulator.html) package defines functions used by the blockchain simulator application (`simapp`).
* `spec/`: The module's specification documents outlining important concepts, state storage structure, and message and event type definitions.
* The root directory includes type definitions for messages, events, and genesis state, including the type definitions generated by Protocol Buffers.
* `abci.go`: The module's `BeginBlocker` and `EndBlocker` implementations (this file is only required if `BeginBlocker` and/or `EndBlocker` need to be defined).
* `codec.go`: The module's registry methods for interface types.
* `errors.go`: The module's sentinel errors.
* `events.go`: The module's event types and constructors.
* `expected_keepers.go`: The module's [expected keeper](./keeper.html#type-definition) interfaces.
* `genesis.go`: The module's genesis state methods and helper functions.
* `keys.go`: The module's store keys and associated helper functions.
* `msgs.go`: The module's message type definitions and associated methods.
* `params.go`: The module's parameter type definitions and associated methods.
* `*.pb.go`: The module's type definitions generated by Protocol Buffers (as defined in the respective `*.proto` files above).
## Next {hide}

8
docs/building-modules/upgrade.md
View File

@ -8,14 +8,14 @@ order: 13
## Prerequisite Readings
- [In-Place Store Migration](../core/upgrade.md) {prereq}
* [In-Place Store Migration](../core/upgrade.md) {prereq}
## Consensus Version
Successful upgrades of existing modules require each `AppModule` to implement the function `ConsensusVersion() uint64`.
- The versions must be hard-coded by the module developer.
- The initial version **must** be set to 1.
* The versions must be hard-coded by the module developer.
* The initial version **must** be set to 1.
Consensus versions serve as state-breaking versions of app modules and must be incremented when the module introduces breaking changes.
@ -41,7 +41,7 @@ func (am AppModule) RegisterServices(cfg module.Configurator) {
Since these migrations are functions that need access to a Keeper's store, use a wrapper around the keepers called `Migrator` as shown in this example:
+++ https://github.com/cosmos/cosmos-sdk/blob/6ac8898fec9bd7ea2c1e5c79e0ed0c3f827beb55/x/bank/keeper/migrations.go#L8-L21
+++ <https://github.com/cosmos/cosmos-sdk/blob/6ac8898fec9bd7ea2c1e5c79e0ed0c3f827beb55/x/bank/keeper/migrations.go#L8-L21>
## Writing Migration Scripts

112
docs/core/baseapp.md
View File

@ -8,16 +8,16 @@ This document describes `BaseApp`, the abstraction that implements the core func
## Pre-requisite Readings
- [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
- [Lifecycle of a Cosmos SDK transaction](../basics/tx-lifecycle.md) {prereq}
* [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
* [Lifecycle of a Cosmos SDK transaction](../basics/tx-lifecycle.md) {prereq}
## Introduction
`BaseApp` is a base type that implements the core of a Cosmos SDK application, namely:
- The [Application Blockchain Interface](#abci), for the state-machine to communicate with the underlying consensus engine (e.g. Tendermint).
- [Service Routers](#service-routers), to route messages and queries to the appropriate module.
- Different [states](#states), as the state-machine can have different volatile states updated based on the ABCI message received.
* The [Application Blockchain Interface](#abci), for the state-machine to communicate with the underlying consensus engine (e.g. Tendermint).
* [Service Routers](#service-routers), to route messages and queries to the appropriate module.
* Different [states](#states), as the state-machine can have different volatile states updated based on the ABCI message received.
The goal of `BaseApp` is to provide the fundamental layer of a Cosmos SDK application
that developers can easily extend to build their own custom application. Usually,
@ -45,7 +45,7 @@ management logic.
The `BaseApp` type holds many important parameters for any Cosmos SDK based application.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/baseapp/baseapp.go#L46-L131
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/baseapp/baseapp.go#L46-L131>
Let us go through the most important components.
@ -54,50 +54,50 @@ Let us go through the most important components.
First, the important parameters that are initialized during the bootstrapping of the application:
- [`CommitMultiStore`](./store.md#commitmultistore): This is the main store of the application,
* [`CommitMultiStore`](./store.md#commitmultistore): This is the main store of the application,
which holds the canonical state that is committed at the [end of each block](#commit). This store
is **not** cached, meaning it is not used to update the application's volatile (un-committed) states.
The `CommitMultiStore` is a multi-store, meaning a store of stores. Each module of the application
uses one or multiple `KVStores` in the multi-store to persist their subset of the state.
- Database: The `db` is used by the `CommitMultiStore` to handle data persistence.
- [`Msg` Service Router](#msg-service-router): The `msgServiceRouter` facilitates the routing of `sdk.Msg` requests to the appropriate
* Database: The `db` is used by the `CommitMultiStore` to handle data persistence.
* [`Msg` Service Router](#msg-service-router): The `msgServiceRouter` facilitates the routing of `sdk.Msg` requests to the appropriate
module `Msg` service for processing. Here a `sdk.Msg` refers to the transaction component that needs to be
processed by a service in order to update the application state, and not to ABCI message which implements
the interface between the application and the underlying consensus engine.
- [gRPC Query Router](#grpc-query-router): The `grpcQueryRouter` facilitates the routing of gRPC queries to the
* [gRPC Query Router](#grpc-query-router): The `grpcQueryRouter` facilitates the routing of gRPC queries to the
appropriate module for it to be processed. These queries are not ABCI messages themselves, but they
are relayed to the relevant module's gRPC `Query` service.
- [`TxDecoder`](https://godoc.org/github.com/cosmos/cosmos-sdk/types#TxDecoder): It is used to decode
* [`TxDecoder`](https://godoc.org/github.com/cosmos/cosmos-sdk/types#TxDecoder): It is used to decode
raw transaction bytes relayed by the underlying Tendermint engine.
- [`ParamStore`](#paramstore): The parameter store used to get and set application consensus parameters.
- [`AnteHandler`](#antehandler): This handler is used to handle signature verification, fee payment,
* [`ParamStore`](#paramstore): The parameter store used to get and set application consensus parameters.
* [`AnteHandler`](#antehandler): This handler is used to handle signature verification, fee payment,
and other pre-message execution checks when a transaction is received. It's executed during
[`CheckTx/RecheckTx`](#checktx) and [`DeliverTx`](#delivertx).
- [`InitChainer`](../basics/app-anatomy.md#initchainer),
* [`InitChainer`](../basics/app-anatomy.md#initchainer),
[`BeginBlocker` and `EndBlocker`](../basics/app-anatomy.md#beginblocker-and-endblocker): These are
the functions executed when the application receives the `InitChain`, `BeginBlock` and `EndBlock`
ABCI messages from the underlying Tendermint engine.
Then, parameters used to define [volatile states](#volatile-states) (i.e. cached states):
- `checkState`: This state is updated during [`CheckTx`](#checktx), and reset on [`Commit`](#commit).
- `deliverState`: This state is updated during [`DeliverTx`](#delivertx), and set to `nil` on
* `checkState`: This state is updated during [`CheckTx`](#checktx), and reset on [`Commit`](#commit).
* `deliverState`: This state is updated during [`DeliverTx`](#delivertx), and set to `nil` on
[`Commit`](#commit) and gets re-initialized on BeginBlock.
Finally, a few more important parameterd:
- `voteInfos`: This parameter carries the list of validators whose precommit is missing, either
* `voteInfos`: This parameter carries the list of validators whose precommit is missing, either
because they did not vote or because the proposer did not include their vote. This information is
carried by the [Context](#context) and can be used by the application for various things like
punishing absent validators.
- `minGasPrices`: This parameter defines the minimum gas prices accepted by the node. This is a
* `minGasPrices`: This parameter defines the minimum gas prices accepted by the node. This is a
**local** parameter, meaning each full-node can set a different `minGasPrices`. It is used in the
`AnteHandler` during [`CheckTx`](#checktx), mainly as a spam protection mechanism. The transaction
enters the [mempool](https://tendermint.com/docs/tendermint-core/mempool.html#transaction-ordering)
only if the gas prices of the transaction are greater than one of the minimum gas price in
`minGasPrices` (e.g. if `minGasPrices == 1uatom,1photon`, the `gas-price` of the transaction must be
greater than `1uatom` OR `1photon`).
- `appVersion`: Version of the application. It is set in the
* `appVersion`: Version of the application. It is set in the
[application's constructor function](../basics/app-anatomy.md#constructor-function).
## Constructor
@ -209,8 +209,8 @@ The [Application-Blockchain Interface](https://tendermint.com/docs/spec/abci/) (
The consensus engine handles two main tasks:
- The networking logic, which mainly consists in gossiping block parts, transactions and consensus votes.
- The consensus logic, which results in the deterministic ordering of transactions in the form of blocks.
* The networking logic, which mainly consists in gossiping block parts, transactions and consensus votes.
* The consensus logic, which results in the deterministic ordering of transactions in the form of blocks.
It is **not** the role of the consensus engine to define the state or the validity of transactions. Generally, transactions are handled by the consensus engine in the form of `[]bytes`, and relayed to the application via the ABCI to be decoded and processed. At keys moments in the networking and consensus processes (e.g. beginning of a block, commit of a block, reception of an unconfirmed transaction, ...), the consensus engine emits ABCI messages for the state-machine to act on.
@ -257,15 +257,15 @@ is actually included in a block, because `checkState` never gets committed to th
`CheckTx` returns a response to the underlying consensus engine of type [`abci.ResponseCheckTx`](https://tendermint.com/docs/spec/abci/abci.html#messages).
The response contains:
- `Code (uint32)`: Response Code. `0` if successful.
- `Data ([]byte)`: Result bytes, if any.
- `Log (string):` The output of the application's logger. May be non-deterministic.
- `Info (string):` Additional information. May be non-deterministic.
- `GasWanted (int64)`: Amount of gas requested for transaction. It is provided by users when they generate the transaction.
- `GasUsed (int64)`: Amount of gas consumed by transaction. During `CheckTx`, this value is computed by multiplying the standard cost of a transaction byte by the size of the raw transaction. Next is an example:
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/auth/ante/basic.go#L104-L105
- `Events ([]cmn.KVPair)`: Key-Value tags for filtering and indexing transactions (eg. by account). See [`event`s](./events.md) for more.
- `Codespace (string)`: Namespace for the Code.
* `Code (uint32)`: Response Code. `0` if successful.
* `Data ([]byte)`: Result bytes, if any.
* `Log (string):` The output of the application's logger. May be non-deterministic.
* `Info (string):` Additional information. May be non-deterministic.
* `GasWanted (int64)`: Amount of gas requested for transaction. It is provided by users when they generate the transaction.
* `GasUsed (int64)`: Amount of gas consumed by transaction. During `CheckTx`, this value is computed by multiplying the standard cost of a transaction byte by the size of the raw transaction. Next is an example:
+++ <https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/auth/ante/basic.go#L104-L105>
* `Events ([]cmn.KVPair)`: Key-Value tags for filtering and indexing transactions (eg. by account). See [`event`s](./events.md) for more.
* `Codespace (string)`: Namespace for the Code.
#### RecheckTx
@ -289,20 +289,20 @@ Before the first transaction of a given block is processed, a [volatile state](#
During the additional fifth step outlined in (2), each read/write to the store increases the value of `GasConsumed`. You can find the default cost of each operation:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/store/types/gas.go#L164-L175
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/store/types/gas.go#L164-L175>
At any point, if `GasConsumed > GasWanted`, the function returns with `Code != 0` and `DeliverTx` fails.
`DeliverTx` returns a response to the underlying consensus engine of type [`abci.ResponseDeliverTx`](https://tendermint.com/docs/spec/abci/abci.html#delivertx). The response contains:
- `Code (uint32)`: Response Code. `0` if successful.
- `Data ([]byte)`: Result bytes, if any.
- `Log (string):` The output of the application's logger. May be non-deterministic.
- `Info (string):` Additional information. May be non-deterministic.
- `GasWanted (int64)`: Amount of gas requested for transaction. It is provided by users when they generate the transaction.
- `GasUsed (int64)`: Amount of gas consumed by transaction. During `DeliverTx`, this value is computed by multiplying the standard cost of a transaction byte by the size of the raw transaction, and by adding gas each time a read/write to the store occurs.
- `Events ([]cmn.KVPair)`: Key-Value tags for filtering and indexing transactions (eg. by account). See [`event`s](./events.md) for more.
- `Codespace (string)`: Namespace for the Code.
* `Code (uint32)`: Response Code. `0` if successful.
* `Data ([]byte)`: Result bytes, if any.
* `Log (string):` The output of the application's logger. May be non-deterministic.
* `Info (string):` Additional information. May be non-deterministic.
* `GasWanted (int64)`: Amount of gas requested for transaction. It is provided by users when they generate the transaction.
* `GasUsed (int64)`: Amount of gas consumed by transaction. During `DeliverTx`, this value is computed by multiplying the standard cost of a transaction byte by the size of the raw transaction, and by adding gas each time a read/write to the store occurs.
* `Events ([]cmn.KVPair)`: Key-Value tags for filtering and indexing transactions (eg. by account). See [`event`s](./events.md) for more.
* `Codespace (string)`: Namespace for the Code.
## RunTx, AnteHandler and RunMsgs
@ -316,7 +316,7 @@ After that, `RunTx()` calls `ValidateBasic()` on each `sdk.Msg`in the `Tx`, whic
Then, the [`anteHandler`](#antehandler) of the application is run (if it exists). In preparation of this step, both the `checkState`/`deliverState`'s `context` and `context`'s `CacheMultiStore` are branched using the `cacheTxContext()` function.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/baseapp/baseapp.go#L623-L630
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/baseapp/baseapp.go#L623-L630>
This allows `RunTx` not to commit the changes made to the state during the execution of `anteHandler` if it ends up failing. It also prevents the module implementing the `anteHandler` from writing to state, which is an important part of the [object-capabilities](./ocap.md) of the Cosmos SDK.
@ -326,13 +326,13 @@ Finally, the [`RunMsgs()`](#runmsgs) function is called to process the `sdk.Msg`
The `AnteHandler` is a special handler that implements the `AnteHandler` interface and is used to authenticate the transaction before the transaction's internal messages are processed.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/handler.go#L6-L8
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/handler.go#L6-L8>
The `AnteHandler` is theoretically optional, but still a very important component of public blockchain networks. It serves 3 primary purposes:
- Be a primary line of defense against spam and second line of defense (the first one being the mempool) against transaction replay with fees deduction and [`sequence`](./transactions.md#transaction-generation) checking.
- Perform preliminary _stateful_ validity checks like ensuring signatures are valid or that the sender has enough funds to pay for fees.
- Play a role in the incentivisation of stakeholders via the collection of transaction fees.
* Be a primary line of defense against spam and second line of defense (the first one being the mempool) against transaction replay with fees deduction and [`sequence`](./transactions.md#transaction-generation) checking.
* Perform preliminary _stateful_ validity checks like ensuring signatures are valid or that the sender has enough funds to pay for fees.
* Play a role in the incentivisation of stakeholders via the collection of transaction fees.
`BaseApp` holds an `anteHandler` as parameter that is initialized in the [application's constructor](../basics/app-anatomy.md#application-constructor). The most widely used `anteHandler` is the [`auth` module](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/auth/ante/ante.go).
@ -350,9 +350,9 @@ First, it retrieves the `sdk.Msg`'s fully-qualified type name, by checking the `
The [`InitChain` ABCI message](https://tendermint.com/docs/app-dev/abci-spec.html#initchain) is sent from the underlying Tendermint engine when the chain is first started. It is mainly used to **initialize** parameters and state like:
- [Consensus Parameters](https://tendermint.com/docs/spec/abci/apps.html#consensus-parameters) via `setConsensusParams`.
- [`checkState` and `deliverState`](#volatile-states) via `setCheckState` and `setDeliverState`.
- The [block gas meter](../basics/gas-fees.md#block-gas-meter), with infinite gas to process genesis transactions.
* [Consensus Parameters](https://tendermint.com/docs/spec/abci/apps.html#consensus-parameters) via `setConsensusParams`.
* [`checkState` and `deliverState`](#volatile-states) via `setCheckState` and `setDeliverState`.
* The [block gas meter](../basics/gas-fees.md#block-gas-meter), with infinite gas to process genesis transactions.
Finally, the `InitChain(req abci.RequestInitChain)` method of `BaseApp` calls the [`initChainer()`](../basics/app-anatomy.md#initchainer) of the application in order to initialize the main state of the application from the `genesis file` and, if defined, call the [`InitGenesis`](../building-modules/genesis.md#initgenesis) function of each of the application's modules.
@ -360,12 +360,12 @@ Finally, the `InitChain(req abci.RequestInitChain)` method of `BaseApp` calls th
The [`BeginBlock` ABCI message](#https://tendermint.com/docs/app-dev/abci-spec.html#beginblock) is sent from the underlying Tendermint engine when a block proposal created by the correct proposer is received, before [`DeliverTx`](#delivertx) is run for each transaction in the block. It allows developers to have logic be executed at the beginning of each block. In the Cosmos SDK, the `BeginBlock(req abci.RequestBeginBlock)` method does the following:
- Initialize [`deliverState`](#volatile-states) with the latest header using the `req abci.RequestBeginBlock` passed as parameter via the `setDeliverState` function.
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/baseapp/baseapp.go#L387-L397
* Initialize [`deliverState`](#volatile-states) with the latest header using the `req abci.RequestBeginBlock` passed as parameter via the `setDeliverState` function.
+++ <https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/baseapp/baseapp.go#L387-L397>
This function also resets the [main gas meter](../basics/gas-fees.md#main-gas-meter).
- Initialize the [block gas meter](../basics/gas-fees.md#block-gas-meter) with the `maxGas` limit. The `gas` consumed within the block cannot go above `maxGas`. This parameter is defined in the application's consensus parameters.
- Run the application's [`beginBlocker()`](../basics/app-anatomy.md#beginblocker-and-endblock), which mainly runs the [`BeginBlocker()`](../building-modules/beginblock-endblock.md#beginblock) method of each of the application's modules.
- Set the [`VoteInfos`](https://tendermint.com/docs/app-dev/abci-spec.html#voteinfo) of the application, i.e. the list of validators whose _precommit_ for the previous block was included by the proposer of the current block. This information is carried into the [`Context`](./context.md) so that it can be used during `DeliverTx` and `EndBlock`.
* Initialize the [block gas meter](../basics/gas-fees.md#block-gas-meter) with the `maxGas` limit. The `gas` consumed within the block cannot go above `maxGas`. This parameter is defined in the application's consensus parameters.
* Run the application's [`beginBlocker()`](../basics/app-anatomy.md#beginblocker-and-endblock), which mainly runs the [`BeginBlocker()`](../building-modules/beginblock-endblock.md#beginblock) method of each of the application's modules.
* Set the [`VoteInfos`](https://tendermint.com/docs/app-dev/abci-spec.html#voteinfo) of the application, i.e. the list of validators whose _precommit_ for the previous block was included by the proposer of the current block. This information is carried into the [`Context`](./context.md) so that it can be used during `DeliverTx` and `EndBlock`.
### EndBlock
@ -389,10 +389,10 @@ The [`Query` ABCI message](https://tendermint.com/docs/app-dev/abci-spec.html#qu
Each Tendermint `query` comes with a `path`, which is a `string` which denotes what to query. If the `path` matches a gRPC fully-qualified service method, then `BaseApp` will defer the query to the `grpcQueryRouter` and let it handle it like explained [above](#grpc-query-router). Otherwise, the `path` represents a query that is not (yet) handled by the gRPC router. `BaseApp` splits the `path` string with the `/` delimiter. By convention, the first element of the splitted string (`splitted[0]`) contains the category of `query` (`app`, `p2p`, `store` or `custom` ). The `BaseApp` implementation of the `Query(req abci.RequestQuery)` method is a simple dispatcher serving these 4 main categories of queries:
- Application-related queries like querying the application's version, which are served via the `handleQueryApp` method.
- Direct queries to the multistore, which are served by the `handlerQueryStore` method. These direct queries are different from custom queries which go through `app.queryRouter`, and are mainly used by third-party service provider like block explorers.
- P2P queries, which are served via the `handleQueryP2P` method. These queries return either `app.addrPeerFilter` or `app.ipPeerFilter` that contain the list of peers filtered by address or IP respectively. These lists are first initialized via `options` in `BaseApp`'s [constructor](#constructor).
- Custom queries, which encompass legacy queries (before the introduction of gRPC queries), are served via the `handleQueryCustom` method. The `handleQueryCustom` branches the multistore before using the `queryRoute` obtained from `app.queryRouter` to map the query to the appropriate module's [legacy `querier`](../building-modules/query-services.md#legacy-queriers).
* Application-related queries like querying the application's version, which are served via the `handleQueryApp` method.
* Direct queries to the multistore, which are served by the `handlerQueryStore` method. These direct queries are different from custom queries which go through `app.queryRouter`, and are mainly used by third-party service provider like block explorers.
* P2P queries, which are served via the `handleQueryP2P` method. These queries return either `app.addrPeerFilter` or `app.ipPeerFilter` that contain the list of peers filtered by address or IP respectively. These lists are first initialized via `options` in `BaseApp`'s [constructor](#constructor).
* Custom queries, which encompass legacy queries (before the introduction of gRPC queries), are served via the `handleQueryCustom` method. The `handleQueryCustom` branches the multistore before using the `queryRoute` obtained from `app.queryRouter` to map the query to the appropriate module's [legacy `querier`](../building-modules/query-services.md#legacy-queriers).
## Next {hide}

62
docs/core/cli.md
View File

@ -20,10 +20,10 @@ simd tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake --gas auto --gas-pr
The first four strings specify the command:
- The root command for the entire application `simd`.
- The subcommand `tx`, which contains all commands that let users create transactions.
- The subcommand `bank` to indicate which module to route the command to ([`x/bank`](../../x/bank/spec/README.md) module in this case).
- The type of transaction `send`.
* The root command for the entire application `simd`.
* The subcommand `tx`, which contains all commands that let users create transactions.
* The subcommand `bank` to indicate which module to route the command to ([`x/bank`](../../x/bank/spec/README.md) module in this case).
* The type of transaction `send`.
The next two strings are arguments: the `from_address` the user wishes to send from, the `to_address` of the recipient, and the `amount` they want to send. Finally, the last few strings of the command are optional flags to indicate how much the user is willing to pay in fees (calculated using the amount of gas used to execute the transaction and the gas prices provided by the user).
@ -33,14 +33,14 @@ The CLI interacts with a [node](../core/node.md) to handle this command. The int
The `main.go` file needs to have a `main()` function that creates a root command, to which all the application commands will be added as subcommands. The root command additionally handles:
- **setting configurations** by reading in configuration files (e.g. the Cosmos SDK config file).
- **adding any flags** to it, such as `--chain-id`.
- **instantiating the `codec`** by calling the application's `MakeCodec()` function (called `MakeTestEncodingConfig` in `simapp`). The [`codec`](../core/encoding.md) is used to encode and decode data structures for the application - stores can only persist `[]byte`s so the developer must define a serialization format for their data structures or use the default, Protobuf.
- **adding subcommand** for all the possible user interactions, including [transaction commands](#transaction-commands) and [query commands](#query-commands).
* **setting configurations** by reading in configuration files (e.g. the Cosmos SDK config file).
* **adding any flags** to it, such as `--chain-id`.
* **instantiating the `codec`** by calling the application's `MakeCodec()` function (called `MakeTestEncodingConfig` in `simapp`). The [`codec`](../core/encoding.md) is used to encode and decode data structures for the application - stores can only persist `[]byte`s so the developer must define a serialization format for their data structures or use the default, Protobuf.
* **adding subcommand** for all the possible user interactions, including [transaction commands](#transaction-commands) and [query commands](#query-commands).
The `main()` function finally creates an executor and [execute](https://godoc.org/github.com/spf13/cobra#Command.Execute) the root command. See an example of `main()` function from the `simapp` application:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/main.go#L12-L24
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/main.go#L12-L24>
The rest of the document will detail what needs to be implemented for each step and include smaller portions of code from the `simapp` CLI files.
@ -52,25 +52,25 @@ Every application CLI first constructs a root command, then adds functionality b
The root command (called `rootCmd`) is what the user first types into the command line to indicate which application they wish to interact with. The string used to invoke the command (the "Use" field) is typically the name of the application suffixed with `-d`, e.g. `simd` or `gaiad`. The root command typically includes the following commands to support basic functionality in the application.
- **Status** command from the Cosmos SDK rpc client tools, which prints information about the status of the connected [`Node`](../core/node.md). The Status of a node includes `NodeInfo`,`SyncInfo` and `ValidatorInfo`.
- **Keys** [commands](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/keys) from the Cosmos SDK client tools, which includes a collection of subcommands for using the key functions in the Cosmos SDK crypto tools, including adding a new key and saving it to the keyring, listing all public keys stored in the keyring, and deleting a key. For example, users can type `simd keys add <name>` to add a new key and save an encrypted copy to the keyring, using the flag `--recover` to recover a private key from a seed phrase or the flag `--multisig` to group multiple keys together to create a multisig key. For full details on the `add` key command, see the code [here](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/keys/add.go). For more details about usage of `--keyring-backend` for storage of key credentials look at the [keyring docs](../run-node/keyring.md).
- **Server** commands from the Cosmos SDK server package. These commands are responsible for providing the mechanisms necessary to start an ABCI Tendermint application and provides the CLI framework (based on [cobra](github.com/spf13/cobra)) necessary to fully bootstrap an application. The package exposes two core functions: `StartCmd` and `ExportCmd` which creates commands to start the application and export state respectively. Click [here](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/server) to learn more.
- [**Transaction**](#transaction-commands) commands.
- [**Query**](#query-commands) commands.
* **Status** command from the Cosmos SDK rpc client tools, which prints information about the status of the connected [`Node`](../core/node.md). The Status of a node includes `NodeInfo`,`SyncInfo` and `ValidatorInfo`.
* **Keys** [commands](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/keys) from the Cosmos SDK client tools, which includes a collection of subcommands for using the key functions in the Cosmos SDK crypto tools, including adding a new key and saving it to the keyring, listing all public keys stored in the keyring, and deleting a key. For example, users can type `simd keys add <name>` to add a new key and save an encrypted copy to the keyring, using the flag `--recover` to recover a private key from a seed phrase or the flag `--multisig` to group multiple keys together to create a multisig key. For full details on the `add` key command, see the code [here](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/keys/add.go). For more details about usage of `--keyring-backend` for storage of key credentials look at the [keyring docs](../run-node/keyring.md).
* **Server** commands from the Cosmos SDK server package. These commands are responsible for providing the mechanisms necessary to start an ABCI Tendermint application and provides the CLI framework (based on [cobra](github.com/spf13/cobra)) necessary to fully bootstrap an application. The package exposes two core functions: `StartCmd` and `ExportCmd` which creates commands to start the application and export state respectively. Click [here](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/server) to learn more.
* [**Transaction**](#transaction-commands) commands.
* [**Query**](#query-commands) commands.
Next is an example `rootCmd` function from the `simapp` application. It instantiates the root command, adds a [_persistent_ flag](#flags) and `PreRun` function to be run before every execution, and adds all of the necessary subcommands.
+++ https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/simapp/simd/cmd/root.go#L37-L150
+++ <https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/simapp/simd/cmd/root.go#L37-L150>
`rootCmd` has a function called `initAppConfig()` which is useful for setting the application's custom configs.
By default app uses Tendermint app config template from Cosmos SDK, which can be over-written via `initAppConfig()`.
Here's an example code to override default `app.toml` template.
+++ https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/simapp/simd/cmd/root.go#L84-L117
+++ <https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/simapp/simd/cmd/root.go#L84-L117>
The `initAppConfig()` also allows overriding the default Cosmos SDK's [server config](https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/server/config/config.go#L199). One example is the `min-gas-prices` config, which defines the minimum gas prices a validator is willing to accept for processing a transaction. By default, the Cosmos SDK sets this parameter to `""` (empty string), which forces all validators to tweak their own `app.toml` and set a non-empty value, or else the node will halt on startup. This might not be the best UX for validators, so the chain developer can set a default `app.toml` value for validators inside this `initAppConfig()` function.
+++ https://github.com/cosmos/cosmos-sdk/blob/aa9b055ddb46aacd4737335a92d0b8a82d577341/simapp/simd/cmd/root.go#L101-L116
+++ <https://github.com/cosmos/cosmos-sdk/blob/aa9b055ddb46aacd4737335a92d0b8a82d577341/simapp/simd/cmd/root.go#L101-L116>
The root-level `status` and `keys` subcommands are common across most applications and do not interact with application state. The bulk of an application's functionality - what users can actually _do_ with it - is enabled by its `tx` and `query` commands.
@ -78,35 +78,35 @@ The root-level `status` and `keys` subcommands are common across most applicatio
[Transactions](./transactions.md) are objects wrapping [`Msg`s](../building-modules/messages-and-queries.md#messages) that trigger state changes. To enable the creation of transactions using the CLI interface, a function `txCmd` is generally added to the `rootCmd`:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L86-L92
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L86-L92>
This `txCmd` function adds all the transaction available to end-users for the application. This typically includes:
- **Sign command** from the [`auth`](../../x/auth/spec/README.md) module that signs messages in a transaction. To enable multisig, add the `auth` module's `MultiSign` command. Since every transaction requires some sort of signature in order to be valid, the signing command is necessary for every application.
- **Broadcast command** from the Cosmos SDK client tools, to broadcast transactions.
- **All [module transaction commands](../building-modules/module-interfaces.md#transaction-commands)** the application is dependent on, retrieved by using the [basic module manager's](../building-modules/module-manager.md#basic-manager) `AddTxCommands()` function.
* **Sign command** from the [`auth`](../../x/auth/spec/README.md) module that signs messages in a transaction. To enable multisig, add the `auth` module's `MultiSign` command. Since every transaction requires some sort of signature in order to be valid, the signing command is necessary for every application.
* **Broadcast command** from the Cosmos SDK client tools, to broadcast transactions.
* **All [module transaction commands](../building-modules/module-interfaces.md#transaction-commands)** the application is dependent on, retrieved by using the [basic module manager's](../building-modules/module-manager.md#basic-manager) `AddTxCommands()` function.
Here is an example of a `txCmd` aggregating these subcommands from the `simapp` application:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L123-L149
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L123-L149>
### Query Commands
[**Queries**](../building-modules/messages-and-queries.md#queries) are objects that allow users to retrieve information about the application's state. To enable the creation of transactions using the CLI interface, a function `txCmd` is generally added to the `rootCmd`:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L86-L92
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L86-L92>
This `queryCmd` function adds all the queries available to end-users for the application. This typically includes:
- **QueryTx** and/or other transaction query commands] from the `auth` module which allow the user to search for a transaction by inputting its hash, a list of tags, or a block height. These queries allow users to see if transactions have been included in a block.
- **Account command** from the `auth` module, which displays the state (e.g. account balance) of an account given an address.
- **Validator command** from the Cosmos SDK rpc client tools, which displays the validator set of a given height.
- **Block command** from the Cosmos SDK rpc client tools, which displays the block data for a given height.
- **All [module query commands](../building-modules/module-interfaces.md#query-commands)** the application is dependent on, retrieved by using the [basic module manager's](../building-modules/module-manager.md#basic-manager) `AddQueryCommands()` function.
* **QueryTx** and/or other transaction query commands] from the `auth` module which allow the user to search for a transaction by inputting its hash, a list of tags, or a block height. These queries allow users to see if transactions have been included in a block.
* **Account command** from the `auth` module, which displays the state (e.g. account balance) of an account given an address.
* **Validator command** from the Cosmos SDK rpc client tools, which displays the validator set of a given height.
* **Block command** from the Cosmos SDK rpc client tools, which displays the block data for a given height.
* **All [module query commands](../building-modules/module-interfaces.md#query-commands)** the application is dependent on, retrieved by using the [basic module manager's](../building-modules/module-manager.md#basic-manager) `AddQueryCommands()` function.
Here is an example of a `queryCmd` aggregating subcommands from the `simapp` application:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L99-L121
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L99-L121>
## Flags
@ -116,7 +116,7 @@ A _persistent_ flag (as opposed to a _local_ flag) added to a command transcends
Flags are added to commands directly (generally in the [module's CLI file](../building-modules/module-interfaces.md#flags) where module commands are defined) and no flag except for the `rootCmd` persistent flags has to be added at application level. It is common to add a _persistent_ flag for `--chain-id`, the unique identifier of the blockchain the application pertains to, to the root command. Adding this flag can be done in the `main()` function. Adding this flag makes sense as the chain ID should not be changing across commands in this application CLI. Here is an example from the `simapp` application:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L118-L119
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L118-L119>
## Environment variables
@ -145,7 +145,7 @@ It is vital that the root command of an application uses `PersistentPreRun()` co
Here is an example of an `PersistentPreRun()` function from `simapp``:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L54-L60
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L54-L60>
The `SetCmdClientContextHandler` call reads persistent flags via `ReadPersistentCommandFlags` which creates a `client.Context` and sets that on the root command's `Context`.

30
docs/core/context.md
View File

@ -8,27 +8,27 @@ The `context` is a data structure intended to be passed from function to functio
## Pre-requisites Readings
- [Anatomy of a Cosmos SDK Application](../basics/app-anatomy.md) {prereq}
- [Lifecycle of a Transaction](../basics/tx-lifecycle.md) {prereq}
* [Anatomy of a Cosmos SDK Application](../basics/app-anatomy.md) {prereq}
* [Lifecycle of a Transaction](../basics/tx-lifecycle.md) {prereq}
## Context Definition
The Cosmos SDK `Context` is a custom data structure that contains Go's stdlib [`context`](https://golang.org/pkg/context) as its base, and has many additional types within its definition that are specific to the Cosmos SDK. The `Context` is integral to transaction processing in that it allows modules to easily access their respective [store](./store.md#base-layer-kvstores) in the [`multistore`](./store.md#multistore) and retrieve transactional context such as the block header and gas meter.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/context.go#L16-L39
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/context.go#L16-L39>
- **Context:** The base type is a Go [Context](https://golang.org/pkg/context), which is explained further in the [Go Context Package](#go-context-package) section below.
- **Multistore:** Every application's `BaseApp` contains a [`CommitMultiStore`](./store.md#multistore) which is provided when a `Context` is created. Calling the `KVStore()` and `TransientStore()` methods allows modules to fetch their respective [`KVStore`](./store.md#base-layer-kvstores) using their unique `StoreKey`.
- **ABCI Header:** The [header](https://tendermint.com/docs/spec/abci/abci.html#header) is an ABCI type. It carries important information about the state of the blockchain, such as block height and proposer of the current block.
- **Chain ID:** The unique identification number of the blockchain a block pertains to.
- **Transaction Bytes:** The `[]byte` representation of a transaction being processed using the context. Every transaction is processed by various parts of the Cosmos SDK and consensus engine (e.g. Tendermint) throughout its [lifecycle](../basics/tx-lifecycle.md), some of which to not have any understanding of transaction types. Thus, transactions are marshaled into the generic `[]byte` type using some kind of [encoding format](./encoding.md) such as [Amino](./encoding.md).
- **Logger:** A `logger` from the Tendermint libraries. Learn more about logs [here](https://tendermint.com/docs/tendermint-core/how-to-read-logs.html#how-to-read-logs). Modules call this method to create their own unique module-specific logger.
- **VoteInfo:** A list of the ABCI type [`VoteInfo`](https://tendermint.com/docs/spec/abci/abci.html#voteinfo), which includes the name of a validator and a boolean indicating whether they have signed the block.
- **Gas Meters:** Specifically, a [`gasMeter`](../basics/gas-fees.md#main-gas-meter) for the transaction currently being processed using the context and a [`blockGasMeter`](../basics/gas-fees.md#block-gas-meter) for the entire block it belongs to. Users specify how much in fees they wish to pay for the execution of their transaction; these gas meters keep track of how much [gas](../basics/gas-fees.md) has been used in the transaction or block so far. If the gas meter runs out, execution halts.
- **CheckTx Mode:** A boolean value indicating whether a transaction should be processed in `CheckTx` or `DeliverTx` mode.
- **Min Gas Price:** The minimum [gas](../basics/gas-fees.md) price a node is willing to take in order to include a transaction in its block. This price is a local value configured by each node individually, and should therefore **not be used in any functions used in sequences leading to state-transitions**.
- **Consensus Params:** The ABCI type [Consensus Parameters](https://tendermint.com/docs/spec/abci/apps.html#consensus-parameters), which specify certain limits for the blockchain, such as maximum gas for a block.
- **Event Manager:** The event manager allows any caller with access to a `Context` to emit [`Events`](./events.md). Modules may define module specific
* **Context:** The base type is a Go [Context](https://golang.org/pkg/context), which is explained further in the [Go Context Package](#go-context-package) section below.
* **Multistore:** Every application's `BaseApp` contains a [`CommitMultiStore`](./store.md#multistore) which is provided when a `Context` is created. Calling the `KVStore()` and `TransientStore()` methods allows modules to fetch their respective [`KVStore`](./store.md#base-layer-kvstores) using their unique `StoreKey`.
* **ABCI Header:** The [header](https://tendermint.com/docs/spec/abci/abci.html#header) is an ABCI type. It carries important information about the state of the blockchain, such as block height and proposer of the current block.
* **Chain ID:** The unique identification number of the blockchain a block pertains to.
* **Transaction Bytes:** The `[]byte` representation of a transaction being processed using the context. Every transaction is processed by various parts of the Cosmos SDK and consensus engine (e.g. Tendermint) throughout its [lifecycle](../basics/tx-lifecycle.md), some of which to not have any understanding of transaction types. Thus, transactions are marshaled into the generic `[]byte` type using some kind of [encoding format](./encoding.md) such as [Amino](./encoding.md).
* **Logger:** A `logger` from the Tendermint libraries. Learn more about logs [here](https://tendermint.com/docs/tendermint-core/how-to-read-logs.html#how-to-read-logs). Modules call this method to create their own unique module-specific logger.
* **VoteInfo:** A list of the ABCI type [`VoteInfo`](https://tendermint.com/docs/spec/abci/abci.html#voteinfo), which includes the name of a validator and a boolean indicating whether they have signed the block.
* **Gas Meters:** Specifically, a [`gasMeter`](../basics/gas-fees.md#main-gas-meter) for the transaction currently being processed using the context and a [`blockGasMeter`](../basics/gas-fees.md#block-gas-meter) for the entire block it belongs to. Users specify how much in fees they wish to pay for the execution of their transaction; these gas meters keep track of how much [gas](../basics/gas-fees.md) has been used in the transaction or block so far. If the gas meter runs out, execution halts.
* **CheckTx Mode:** A boolean value indicating whether a transaction should be processed in `CheckTx` or `DeliverTx` mode.
* **Min Gas Price:** The minimum [gas](../basics/gas-fees.md) price a node is willing to take in order to include a transaction in its block. This price is a local value configured by each node individually, and should therefore **not be used in any functions used in sequences leading to state-transitions**.
* **Consensus Params:** The ABCI type [Consensus Parameters](https://tendermint.com/docs/spec/abci/apps.html#consensus-parameters), which specify certain limits for the blockchain, such as maximum gas for a block.
* **Event Manager:** The event manager allows any caller with access to a `Context` to emit [`Events`](./events.md). Modules may define module specific
`Events` by defining various `Types` and `Attributes` or use the common definitions found in `types/`. Clients can subscribe or query for these `Events`. These `Events` are collected throughout `DeliverTx`, `BeginBlock`, and `EndBlock` and are returned to Tendermint for indexing. For example:
```go

54
docs/core/encoding.md
View File

@ -8,7 +8,7 @@ While encoding in the Cosmos SDK used to be mainly handled by `go-amino` codec,
## Pre-requisite Readings
- [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
* [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
## Encoding
@ -75,10 +75,10 @@ Modules are encouraged to utilize Protobuf encoding for their respective types.
In addition to [following official Protocol Buffer guidelines](https://developers.google.com/protocol-buffers/docs/proto3#simple), we recommend using these annotations in .proto files when dealing with interfaces:
- use `cosmos_proto.accepts_interface` to annote fields that accept interfaces
- pass the same fully qualified name as `protoName` to `InterfaceRegistry.RegisterInterface`
- annotate interface implementations with `cosmos_proto.implements_interface`
- pass the same fully qualified name as `protoName` to `InterfaceRegistry.RegisterInterface`
* use `cosmos_proto.accepts_interface` to annote fields that accept interfaces
* pass the same fully qualified name as `protoName` to `InterfaceRegistry.RegisterInterface`
* annotate interface implementations with `cosmos_proto.implements_interface`
* pass the same fully qualified name as `protoName` to `InterfaceRegistry.RegisterInterface`
### Transaction Encoding
@ -88,16 +88,16 @@ the Cosmos SDK but are then passed to the underlying consensus engine to be rela
other peers. Since the underlying consensus engine is agnostic to the application,
the consensus engine accepts only transactions in the form of raw bytes.
- The `TxEncoder` object performs the encoding.
- The `TxDecoder` object performs the decoding.
* The `TxEncoder` object performs the encoding.
* The `TxDecoder` object performs the decoding.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/types/tx_msg.go#L83-L87
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/types/tx_msg.go#L83-L87>
A standard implementation of both these objects can be found in the [`auth` module](../../x/auth/spec/README.md):
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/x/auth/tx/decoder.go
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/x/auth/tx/decoder.go>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/x/auth/tx/encoder.go
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/x/auth/tx/encoder.go>
See [ADR-020](../architecture/adr-020-protobuf-transaction-encoding.md) for details of how a transaction is encoded.
@ -116,7 +116,7 @@ message Profile {
In this `Profile` example, we hardcoded `account` as a `BaseAccount`. However, there are several other types of [user accounts related to vesting](../../x/auth/spec/05_vesting.md), such as `BaseVestingAccount` or `ContinuousVestingAccount`. All of these accounts are different, but they all implement the `AccountI` interface. How would you create a `Profile` that allows all these types of accounts with an `account` field that accepts an `AccountI` interface?
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/auth/types/account.go#L307-L330
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/auth/types/account.go#L307-L330>
In [ADR-019](../architecture/adr-019-protobuf-state-encoding.md), it has been decided to use [`Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto)s to encode interfaces in protobuf. An `Any` contains an arbitrary serialized message as bytes, along with a URL that acts as a globally unique identifier for and resolves to that message's type. This strategy allows us to pack arbitrary Go types inside protobuf messages. Our new `Profile` then looks like:
@ -193,36 +193,36 @@ For more information about interface encoding, and especially on `UnpackInterfac
The above `Profile` example is a fictive example used for educational purposes. In the Cosmos SDK, we use `Any` encoding in several places (non-exhaustive list):
- the `cryptotypes.PubKey` interface for encoding different types of public keys,
- the `sdk.Msg` interface for encoding different `Msg`s in a transaction,
- the `AccountI` interface for encodinig different types of accounts (similar to the above example) in the x/auth query responses,
- the `Evidencei` interface for encoding different types of evidences in the x/evidence module,
- the `AuthorizationI` interface for encoding different types of x/authz authorizations,
- the [`Validator`](https://github.com/cosmos/cosmos-sdk/blob/v0.42.5/x/staking/types/staking.pb.go#L306-L337) struct that contains information about a validator.
* the `cryptotypes.PubKey` interface for encoding different types of public keys,
* the `sdk.Msg` interface for encoding different `Msg`s in a transaction,
* the `AccountI` interface for encodinig different types of accounts (similar to the above example) in the x/auth query responses,
* the `Evidencei` interface for encoding different types of evidences in the x/evidence module,
* the `AuthorizationI` interface for encoding different types of x/authz authorizations,
* the [`Validator`](https://github.com/cosmos/cosmos-sdk/blob/v0.42.5/x/staking/types/staking.pb.go#L306-L337) struct that contains information about a validator.
A real-life example of encoding the pubkey as `Any` inside the Validator struct in x/staking is shown in the following example:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/staking/types/validator.go#L40-L61
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/staking/types/validator.go#L40-L61>
## FAQ
1. How to create modules using protobuf encoding?
### How to create modules using protobuf encoding
**Defining module types**
#### Defining module types
Protobuf types can be defined to encode:
- state
- [`Msg`s](../building-modules/messages-and-queries.md#messages)
- [Query services](../building-modules/query-services.md)
- [genesis](../building-modules/genesis.md)
* state
* [`Msg`s](../building-modules/messages-and-queries.md#messages)
* [Query services](../building-modules/query-services.md)
* [genesis](../building-modules/genesis.md)
**Naming and conventions**
#### Naming and conventions
We encourage developers to follow industry guidelines: [Protocol Buffers style guide](https://developers.google.com/protocol-buffers/docs/style)
and [Buf](https://buf.build/docs/style-guide), see more details in [ADR 023](../architecture/adr-023-protobuf-naming.md)
2. How to update modules to protobuf encoding?
### How to update modules to protobuf encoding
If modules do not contain any interfaces (e.g. `Account` or `Content`), then they
may simply migrate any existing types that
@ -246,7 +246,7 @@ The Cosmos SDK `codec.Codec` interface provides support methods `MarshalInterfac
Module should register interfaces using `InterfaceRegistry` which provides a mechanism for registering interfaces: `RegisterInterface(protoName string, iface interface{})` and implementations: `RegisterImplementations(iface interface{}, impls ...proto.Message)` that can be safely unpacked from Any, similarly to type registration with Amino:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/codec/types/interface_registry.go#L25-L66
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/codec/types/interface_registry.go#L25-L66>
In addition, an `UnpackInterfaces` phase should be introduced to deserialization to unpack interfaces before they're needed. Protobuf types that contain a protobuf `Any` either directly or via one of their members should implement the `UnpackInterfacesMessage` interface:

28
docs/core/events.md
View File

@ -8,20 +8,20 @@ order: 9
## Pre-requisite Readings
- [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
- [Tendermint Documentation on Events](https://docs.tendermint.com/master/spec/abci/abci.html#events) {prereq}
* [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
* [Tendermint Documentation on Events](https://docs.tendermint.com/master/spec/abci/abci.html#events) {prereq}
## Events
Events are implemented in the Cosmos SDK as an alias of the ABCI `Event` type and
take the form of: `{eventType}.{attributeKey}={attributeValue}`.
+++ https://github.com/tendermint/tendermint/blob/v0.34.8/proto/tendermint/abci/types.proto#L304-L313
+++ <https://github.com/tendermint/tendermint/blob/v0.34.8/proto/tendermint/abci/types.proto#L304-L313>
An Event contains:
- A `type` to categorize the Event at a high-level; for example, the Cosmos SDK uses the `"message"` type to filter Events by `Msg`s.
- A list of `attributes` are key-value pairs that give more information about the categorized Event. For example, for the `"message"` type, we can filter Events by key-value pairs using `message.action={some_action}`, `message.module={some_module}` or `message.sender={some_sender}`.
* A `type` to categorize the Event at a high-level; for example, the Cosmos SDK uses the `"message"` type to filter Events by `Msg`s.
* A list of `attributes` are key-value pairs that give more information about the categorized Event. For example, for the `"message"` type, we can filter Events by key-value pairs using `message.action={some_action}`, `message.module={some_module}` or `message.sender={some_sender}`.
::: tip
To parse the attribute values as strings, make sure to add `'` (single quotes) around each attribute value.
@ -34,10 +34,10 @@ by using the [`EventManager`](#eventmanager). In addition, each module documents
Events are returned to the underlying consensus engine in the response of the following ABCI messages:
- [`BeginBlock`](./baseapp.md#beginblock)
- [`EndBlock`](./baseapp.md#endblock)
- [`CheckTx`](./baseapp.md#checktx)
- [`DeliverTx`](./baseapp.md#delivertx)
* [`BeginBlock`](./baseapp.md#beginblock)
* [`EndBlock`](./baseapp.md#endblock)
* [`CheckTx`](./baseapp.md#checktx)
* [`DeliverTx`](./baseapp.md#delivertx)
### Examples
@ -57,13 +57,13 @@ In Cosmos SDK applications, Events are managed by an abstraction called the `Eve
Internally, the `EventManager` tracks a list of Events for the entire execution flow of a
transaction or `BeginBlock`/`EndBlock`.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/events.go#L17-L25
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/events.go#L17-L25>
The `EventManager` comes with a set of useful methods to manage Events. The method
that is used most by module and application developers is `EmitEvent` that tracks
an Event in the `EventManager`.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/events.go#L33-L37
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/events.go#L33-L37>
Module developers should handle Event emission via the `EventManager#EmitEvent` in each message
`Handler` and in each `BeginBlock`/`EndBlock` handler. The `EventManager` is accessed via
@ -104,9 +104,9 @@ You can use Tendermint's [Websocket](https://docs.tendermint.com/master/tendermi
The main `eventCategory` you can subscribe to are:
- `NewBlock`: Contains Events triggered during `BeginBlock` and `EndBlock`.
- `Tx`: Contains Events triggered during `DeliverTx` (i.e. transaction processing).
- `ValidatorSetUpdates`: Contains validator set updates for the block.
* `NewBlock`: Contains Events triggered during `BeginBlock` and `EndBlock`.
* `Tx`: Contains Events triggered during `DeliverTx` (i.e. transaction processing).
* `ValidatorSetUpdates`: Contains validator set updates for the block.
These Events are triggered from the `state` package after a block is committed. You can get the
full list of Event categories [on the Tendermint Godoc page](https://godoc.org/github.com/tendermint/tendermint/types#pkg-constants).

38
docs/core/grpc_rest.md
View File

@ -10,9 +10,9 @@ This document presents an overview of all the endpoints a node exposes: gRPC, RE
Each node exposes the following endpoints for users to interact with a node, each endpoint is served on a different port. Details on how to configure each endpoint is provided in the endpoint's own section.
- the gRPC server (default port: `9090`),
- the REST server (default port: `1317`),
- the Tendermint RPC endpoint (default port: `26657`).
* the gRPC server (default port: `9090`),
* the REST server (default port: `1317`),
* the Tendermint RPC endpoint (default port: `26657`).
::: tip
The node also exposes some other endpoints, such as the Tendermint P2P endpoint, or the [Prometheus endpoint](https://docs.tendermint.com/master/nodes/metrics.html#metrics), which are not directly related to the Cosmos SDK. Please refer to the [Tendermint documentation](https://docs.tendermint.com/master/tendermint-core/using-tendermint.html#configuration) for more information about these endpoints.
@ -25,7 +25,7 @@ A patch introduced in `go-grpc v1.34.0` made gRPC incompatible with the `gogopro
To make sure that gRPC is working properly, it is **highly recommended** to add the following line in your application's `go.mod`:
```
```go
replace google.golang.org/grpc => google.golang.org/grpc v1.33.2
```
@ -36,14 +36,14 @@ Cosmos SDK v0.40 introduced Protobuf as the main [encoding](./encoding) library,
Each module exposes a [Protobuf `Query` service](../building-modules/messages-and-queries.md#queries) that defines state queries. The `Query` services and a transaction service used to broadcast transactions are hooked up to the gRPC server via the following function inside the application:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-rc0/server/types/app.go#L39-L41
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-rc0/server/types/app.go#L39-L41>
Note: It is not possible to expose any [Protobuf `Msg` service](../building-modules/messages-and-queries.md#messages) endpoints via gRPC. Transactions must be generated and signed using the CLI or programmatically before they can be broadcasted using gRPC. See [Generating, Signing, and Broadcasting Transactions](../run-node/txs.html) for more information.
The `grpc.Server` is a concrete gRPC server, which spawns and serves all gRPC query requests and a broadcast transaction request. This server can be configured inside `~/.simapp/config/app.toml`:
- `grpc.enable = true|false` field defines if the gRPC server should be enabled. Defaults to `true`.
- `grpc.address = {string}` field defines the address (really, the port, since the host should be kept at `0.0.0.0`) the server should bind to. Defaults to `0.0.0.0:9090`.
* `grpc.enable = true|false` field defines if the gRPC server should be enabled. Defaults to `true`.
* `grpc.address = {string}` field defines the address (really, the port, since the host should be kept at `0.0.0.0`) the server should bind to. Defaults to `0.0.0.0:9090`.
:::tip
`~/.simapp` is the directory where the node's configuration and databases are stored. By default, it's set to `~/.{app_name}`.
@ -59,9 +59,9 @@ Cosmos SDK supports REST routes via gRPC-gateway.
All routes are configured under the following fields in `~/.simapp/config/app.toml`:
- `api.enable = true|false` field defines if the REST server should be enabled. Defaults to `false`.
- `api.address = {string}` field defines the address (really, the port, since the host should be kept at `0.0.0.0`) the server should bind to. Defaults to `tcp://0.0.0.0:1317`.
- some additional API configuration options are defined in `~/.simapp/config/app.toml`, along with comments, please refer to that file directly.
* `api.enable = true|false` field defines if the REST server should be enabled. Defaults to `false`.
* `api.address = {string}` field defines the address (really, the port, since the host should be kept at `0.0.0.0`) the server should bind to. Defaults to `tcp://0.0.0.0:1317`.
* some additional API configuration options are defined in `~/.simapp/config/app.toml`, along with comments, please refer to that file directly.
### gRPC-gateway REST Routes
@ -69,7 +69,7 @@ If, for various reasons, you cannot use gRPC (for example, you are building a we
[gRPC-gateway](https://grpc-ecosystem.github.io/grpc-gateway/) is a tool to expose gRPC endpoints as REST endpoints. For each gRPC endpoint defined in a Protobuf `Query` service, the Cosmos SDK offers a REST equivalent. For instance, querying a balance could be done via the `/cosmos.bank.v1beta1.QueryAllBalances` gRPC endpoint, or alternatively via the gRPC-gateway `"/cosmos/bank/v1beta1/balances/{address}"` REST endpoint: both will return the same result. For each RPC method defined in a Protobuf `Query` service, the corresponding REST endpoint is defined as an option:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.41.0/proto/cosmos/bank/v1beta1/query.proto#L19-L22
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.41.0/proto/cosmos/bank/v1beta1/query.proto#L19-L22>
For application developers, gRPC-gateway REST routes needs to be wired up to the REST server, this is done by calling the `RegisterGRPCGatewayRoutes` function on the ModuleManager.
@ -87,14 +87,14 @@ Independently from the Cosmos SDK, Tendermint also exposes a RPC server. This RP
Some Tendermint RPC endpoints are directly related to the Cosmos SDK:
- `/abci_query`: this endpoint will query the application for state. As the `path` parameter, you can send the following strings:
- any Protobuf fully-qualified service method, such as `/cosmos.bank.v1beta1.QueryAllBalances`. The `data` field should then include the method's request parameter(s) encoded as bytes using Protobuf.
- `/app/simulate`: this will simulate a transaction, and return some information such as gas used.
- `/app/version`: this will return the application's version.
- `/store/{path}`: this will query the store directly.
- `/p2p/filter/addr/{port}`: this will return a filtered list of the node's P2P peers by address port.
- `/p2p/filter/id/{id}`: this will return a filtered list of the node's P2P peers by ID.
- `/broadcast_tx_{aync,async,commit}`: these 3 endpoint will broadcast a transaction to other peers. CLI, gRPC and REST expose [a way to broadcast transations](./transactions.md#broadcasting-the-transaction), but they all use these 3 Tendermint RPCs under the hood.
* `/abci_query`: this endpoint will query the application for state. As the `path` parameter, you can send the following strings:
* any Protobuf fully-qualified service method, such as `/cosmos.bank.v1beta1.QueryAllBalances`. The `data` field should then include the method's request parameter(s) encoded as bytes using Protobuf.
* `/app/simulate`: this will simulate a transaction, and return some information such as gas used.
* `/app/version`: this will return the application's version.
* `/store/{path}`: this will query the store directly.
* `/p2p/filter/addr/{port}`: this will return a filtered list of the node's P2P peers by address port.
* `/p2p/filter/id/{id}`: this will return a filtered list of the node's P2P peers by ID.
* `/broadcast_tx_{aync,async,commit}`: these 3 endpoint will broadcast a transaction to other peers. CLI, gRPC and REST expose [a way to broadcast transations](./transactions.md#broadcasting-the-transaction), but they all use these 3 Tendermint RPCs under the hood.
## Comparison Table

28
docs/core/node.md
View File

@ -8,7 +8,7 @@ The main endpoint of a Cosmos SDK application is the daemon client, otherwise kn
## Pre-requisite Readings
- [Anatomy of an SDK application](../basics/app-anatomy.md) {prereq}
* [Anatomy of an SDK application](../basics/app-anatomy.md) {prereq}
## `main` function
@ -16,17 +16,17 @@ The full-node client of any Cosmos SDK application is built by running a `main`
In general, developers will implement the `main.go` function with the following structure:
- First, an [`appCodec`](./encoding.md) is instantiated for the application.
- Then, the `config` is retrieved and config parameters are set. This mainly involves setting the Bech32 prefixes for [addresses](../basics/accounts.md#addresses).
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/config.go#L13-L24
- Using [cobra](https://github.com/spf13/cobra), the root command of the full-node client is created. After that, all the custom commands of the application are added using the `AddCommand()` method of `rootCmd`.
- Add default server commands to `rootCmd` using the `server.AddCommands()` method. These commands are separated from the ones added above since they are standard and defined at Cosmos SDK level. They should be shared by all Cosmos SDK-based applications. They include the most important command: the [`start` command](#start-command).
- Prepare and execute the `executor`.
+++ https://github.com/tendermint/tendermint/blob/v0.34.0-rc6/libs/cli/setup.go#L74-L78
* First, an [`appCodec`](./encoding.md) is instantiated for the application.
* Then, the `config` is retrieved and config parameters are set. This mainly involves setting the Bech32 prefixes for [addresses](../basics/accounts.md#addresses).
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/config.go#L13-L24>
* Using [cobra](https://github.com/spf13/cobra), the root command of the full-node client is created. After that, all the custom commands of the application are added using the `AddCommand()` method of `rootCmd`.
* Add default server commands to `rootCmd` using the `server.AddCommands()` method. These commands are separated from the ones added above since they are standard and defined at Cosmos SDK level. They should be shared by all Cosmos SDK-based applications. They include the most important command: the [`start` command](#start-command).
* Prepare and execute the `executor`.
+++ <https://github.com/tendermint/tendermint/blob/v0.34.0-rc6/libs/cli/setup.go#L74-L78>
See an example of `main` function from the `simapp` application, the Cosmos SDK's application for demo purposes:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/simd/main.go
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/simd/main.go>
## `start` command
@ -46,24 +46,24 @@ The flow of the `start` command is pretty straightforward. First, it retrieves t
With the `db`, the `start` command creates a new instance of the application using an `appCreator` function:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/start.go#L227-L228
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/start.go#L227-L228>
Note that an `appCreator` is a function that fulfills the `AppCreator` signature:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/types/app.go#L48-L50
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/types/app.go#L48-L50>
In practice, the [constructor of the application](../basics/app-anatomy.md#constructor-function) is passed as the `appCreator`.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/simd/cmd/root.go#L170-L215
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/simd/cmd/root.go#L170-L215>
Then, the instance of `app` is used to instanciate a new Tendermint node:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/start.go#L235-L244
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/start.go#L235-L244>
The Tendermint node can be created with `app` because the latter satisfies the [`abci.Application` interface](https://github.com/tendermint/tendermint/blob/v0.34.0/abci/types/application.go#L7-L32) (given that `app` extends [`baseapp`](./baseapp.md)). As part of the `NewNode` method, Tendermint makes sure that the height of the application (i.e. number of blocks since genesis) is equal to the height of the Tendermint node. The difference between these two heights should always be negative or null. If it is strictly negative, `NewNode` will replay blocks until the height of the application reaches the height of the Tendermint node. Finally, if the height of the application is `0`, the Tendermint node will call [`InitChain`](./baseapp.md#initchain) on the application to initialize the state from the genesis file.
Once the Tendermint node is instanciated and in sync with the application, the node can be started:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/start.go#L250-L252
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/start.go#L250-L252>
Upon starting, the node will bootstrap its RPC and P2P server and start dialing peers. During handshake with its peers, if the node realizes they are ahead, it will query all the blocks sequentially in order to catch up. Then, it will wait for new block proposals and block signatures from validators in order to make progress.

2
docs/core/ocap.md
View File

@ -68,7 +68,7 @@ sumValue := externalModule.ComputeSumValue(*account)
In the Cosmos SDK, you can see the application of this principle in the
gaia app.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.41.4/simapp/app.go#L249-L273
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.41.4/simapp/app.go#L249-L273>
The following diagram shows the current dependencies between keepers.

1
docs/core/proto-docs.md
View File

@ -1,6 +1,7 @@
<!--
order: 14
-->
# Protobuf Documentation
This file has been replaced by [Cosmos-SDK Buf Proto-docs](https://buf.build/cosmos/cosmos-sdk/docs/main)

4
docs/core/runtx_middleware.md
View File

@ -22,8 +22,8 @@ type RecoveryHandler func(recoveryObj interface{}) error
**Contract:**
- RecoveryHandler returns `nil` if `recoveryObj` wasn't handled and should be passed to the next recovery middleware;
- RecoveryHandler returns a non-nil `error` if `recoveryObj` was handled;
* RecoveryHandler returns `nil` if `recoveryObj` wasn't handled and should be passed to the next recovery middleware;
* RecoveryHandler returns a non-nil `error` if `recoveryObj` was handled;
## Custom RecoveryHandler register

32
docs/core/simulation.md
View File

@ -30,14 +30,14 @@ provided operations (randomized or not).
The simulation app has different commands, each of which tests a different
failure type:
- `AppImportExport`: The simulator exports the initial app state and then it
* `AppImportExport`: The simulator exports the initial app state and then it
creates a new app with the exported `genesis.json` as an input, checking for
inconsistencies between the stores.
- `AppSimulationAfterImport`: Queues two simulations together. The first one provides the app state (_i.e_ genesis) to the second. Useful to test software upgrades or hard-forks from a live chain.
- `AppStateDeterminism`: Checks that all the nodes return the same values, in the same order.
- `BenchmarkInvariants`: Analysis of the performance of running all modules' invariants (_i.e_ sequentially runs a [benchmark](https://golang.org/pkg/testing/#hdr-Benchmarks) test). An invariant checks for
* `AppSimulationAfterImport`: Queues two simulations together. The first one provides the app state (_i.e_ genesis) to the second. Useful to test software upgrades or hard-forks from a live chain.
* `AppStateDeterminism`: Checks that all the nodes return the same values, in the same order.
* `BenchmarkInvariants`: Analysis of the performance of running all modules' invariants (_i.e_ sequentially runs a [benchmark](https://golang.org/pkg/testing/#hdr-Benchmarks) test). An invariant checks for
differences between the values that are on the store and the passive tracker. Eg: total coins held by accounts vs total supply tracker.
- `FullAppSimulation`: General simulation mode. Runs the chain and the specified operations for a given number of blocks. Tests that there're no `panics` on the simulation. It does also run invariant checks on every `Period` but they are not benchmarked.
* `FullAppSimulation`: General simulation mode. Runs the chain and the specified operations for a given number of blocks. Tests that there're no `panics` on the simulation. It does also run invariant checks on every `Period` but they are not benchmarked.
Each simulation must receive a set of inputs (_i.e_ flags) such as the number of
blocks that the simulation is run, seed, block size, etc.
@ -76,26 +76,26 @@ check the Cosmos SDK [Makefile](https://github.com/cosmos/cosmos-sdk/blob/v0.40.
Here are some suggestions when encountering a simulation failure:
- Export the app state at the height were the failure was found. You can do this
* Export the app state at the height were the failure was found. You can do this
by passing the `-ExportStatePath` flag to the simulator.
- Use `-Verbose` logs. They could give you a better hint on all the operations
* Use `-Verbose` logs. They could give you a better hint on all the operations
involved.
- Reduce the simulation `-Period`. This will run the invariants checks more
* Reduce the simulation `-Period`. This will run the invariants checks more
frequently.
- Print all the failed invariants at once with `-PrintAllInvariants`.
- Try using another `-Seed`. If it can reproduce the same error and if it fails
* Print all the failed invariants at once with `-PrintAllInvariants`.
* Try using another `-Seed`. If it can reproduce the same error and if it fails
sooner you will spend less time running the simulations.
- Reduce the `-NumBlocks` . How's the app state at the height previous to the
* Reduce the `-NumBlocks` . How's the app state at the height previous to the
failure?
- Run invariants on every operation with `-SimulateEveryOperation`. _Note_: this
* Run invariants on every operation with `-SimulateEveryOperation`. _Note_: this
will slow down your simulation **a lot**.
- Try adding logs to operations that are not logged. You will have to define a
* Try adding logs to operations that are not logged. You will have to define a
[Logger](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/staking/keeper/keeper.go#L66-L69) on your `Keeper`.
## Use simulation in your Cosmos SDK-based application
Learn how you can integrate the simulation into your Cosmos SDK-based application:
- Application Simulation Manager
- [Building modules: Simulator](../building-modules/simulator.md)
- Simulator tests
* Application Simulation Manager
* [Building modules: Simulator](../building-modules/simulator.md)
* Simulator tests

70
docs/core/store.md
View File

@ -8,13 +8,13 @@ A store is a data structure that holds the state of the application. {synopsis}
## Pre-requisite Readings
- [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
* [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
## Introduction to Cosmos SDK Stores
The Cosmos SDK comes with a large set of stores to persist the state of applications. By default, the main store of Cosmos SDK applications is a `multistore`, i.e. a store of stores. Developers can add any number of key-value stores to the multistore, depending on their application needs. The multistore exists to support the modularity of the Cosmos SDK, as it lets each module declare and manage their own subset of the state. Key-value stores in the multistore can only be accessed with a specific capability `key`, which is typically held in the [`keeper`](../building-modules/keeper.md) of the module that declared the store.
```
```text
+-----------------------------------------------------+
| |
| +--------------------------------------------+ |
@ -58,11 +58,11 @@ The Cosmos SDK comes with a large set of stores to persist the state of applicat
At its very core, a Cosmos SDK `store` is an object that holds a `CacheWrapper` and has a `GetStoreType()` method:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L15-L18
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L15-L18>
The `GetStoreType` is a simple method that returns the type of store, whereas a `CacheWrapper` is a simple interface that implements store read caching and write branching through `Write` method:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L240-L264
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L240-L264>
Branching and cache is used ubiquitously in the Cosmos SDK and required to be implemented on every store type. A storage branch creates an isolated, ephemeral branch of a store that can be passed around and updated without affecting the main underlying store. This is used to trigger temporary state-transitions that may be reverted later should an error occur. Read more about it in [context](./context.md#Store-branching)
@ -70,11 +70,11 @@ Branching and cache is used ubiquitously in the Cosmos SDK and required to be im
A commit store is a store that has the ability to commit changes made to the underlying tree or db. The Cosmos SDK differentiates simple stores from commit stores by extending the basic store interfaces with a `Committer`:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L29-L33
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L29-L33>
The `Committer` is an interface that defines methods to persist changes to disk:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L20-L27
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L20-L27>
The `CommitID` is a deterministic commit of the state tree. Its hash is returned to the underlying consensus engine and stored in the block header. Note that commit store interfaces exist for various purposes, one of which is to make sure not every object can commit the store. As part of the [object-capabilities model](./ocap.md) of the Cosmos SDK, only `baseapp` should have the ability to commit stores. For example, this is the reason why the `ctx.KVStore()` method by which modules typically access stores returns a `KVStore` and not a `CommitKVStore`.
@ -86,7 +86,7 @@ The Cosmos SDK comes with many types of stores, the most used being [`CommitMult
Each Cosmos SDK application holds a multistore at its root to persist its state. The multistore is a store of `KVStores` that follows the `Multistore` interface:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L104-L133
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L104-L133>
If tracing is enabled, then branching the multistore will firstly wrap all the underlying `KVStore` in [`TraceKv.Store`](#tracekv-store).
@ -94,11 +94,11 @@ If tracing is enabled, then branching the multistore will firstly wrap all the u
The main type of `Multistore` used in the Cosmos SDK is `CommitMultiStore`, which is an extension of the `Multistore` interface:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L141-L184
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L141-L184>
As for concrete implementation, the [`rootMulti.Store`] is the go-to implementation of the `CommitMultiStore` interface.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/rootmulti/store.go#L43-L61
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/rootmulti/store.go#L43-L61>
The `rootMulti.Store` is a base-layer multistore built around a `db` on top of which multiple `KVStores` can be mounted, and is the default multistore store used in [`baseapp`](./baseapp.md).
@ -106,7 +106,7 @@ The `rootMulti.Store` is a base-layer multistore built around a `db` on top of w
Whenever the `rootMulti.Store` needs to be branched, a [`cachemulti.Store`](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/store/cachemulti/store.go) is used.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/cachemulti/store.go#L17-L28
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/cachemulti/store.go#L17-L28>
`cachemulti.Store` branches all substores (creates a virtual store for each substore) in its constructor and hold them in `Store.stores`. Moreover caches all read queries. `Store.GetKVStore()` returns the store from `Store.stores`, and `Store.Write()` recursively calls `CacheWrap.Write()` on all the substores.
@ -120,23 +120,23 @@ Individual `KVStore`s are used by modules to manage a subset of the global state
`CommitKVStore`s are declared by proxy of their respective `key` and mounted on the application's [multistore](#multistore) in the [main application file](../basics/app-anatomy.md#core-application-file). In the same file, the `key` is also passed to the module's `keeper` that is responsible for managing the store.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L189-L219
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L189-L219>
Apart from the traditional `Get` and `Set` methods, a `KVStore` must provide an `Iterator(start, end)` method which returns an `Iterator` object. It is used to iterate over a range of keys, typically keys that share a common prefix. Below is an example from the bank's module keeper, used to iterate over all account balances:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/x/bank/keeper/view.go#L115-L134
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/x/bank/keeper/view.go#L115-L134>
### `IAVL` Store
The default implementation of `KVStore` and `CommitKVStore` used in `baseapp` is the `iavl.Store`.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/iavl/store.go#L37-L40
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/iavl/store.go#L37-L40>
`iavl` stores are based around an [IAVL Tree](https://github.com/tendermint/iavl), a self-balancing binary tree which guarantees that:
- `Get` and `Set` operations are O(log n), where n is the number of elements in the tree.
- Iteration efficiently returns the sorted elements within the range.
- Each tree version is immutable and can be retrieved even after a commit (depending on the pruning settings).
* `Get` and `Set` operations are O(log n), where n is the number of elements in the tree.
* Iteration efficiently returns the sorted elements within the range.
* Each tree version is immutable and can be retrieved even after a commit (depending on the pruning settings).
The documentation on the IAVL Tree is located [here](https://github.com/cosmos/iavl/blob/v0.15.0-rc5/docs/overview.md).
@ -144,7 +144,7 @@ The documentation on the IAVL Tree is located [here](https://github.com/cosmos/i
`dbadapter.Store` is a adapter for `dbm.DB` making it fulfilling the `KVStore` interface.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/dbadapter/store.go#L13-L16
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/dbadapter/store.go#L13-L16>
`dbadapter.Store` embeds `dbm.DB`, meaning most of the `KVStore` interface functions are implemented. The other functions (mostly miscellaneous) are manually implemented. This store is primarily used within [Transient Stores](#transient-stores)
@ -152,17 +152,17 @@ The documentation on the IAVL Tree is located [here](https://github.com/cosmos/i
`Transient.Store` is a base-layer `KVStore` which is automatically discarded at the end of the block.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/transient/store.go#L13-L16
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/transient/store.go#L13-L16>
`Transient.Store` is a `dbadapter.Store` with a `dbm.NewMemDB()`. All `KVStore` methods are reused. When `Store.Commit()` is called, a new `dbadapter.Store` is assigned, discarding previous reference and making it garbage collected.
This type of store is useful to persist information that is only relevant per-block. One example would be to store parameter changes (i.e. a bool set to `true` if a parameter changed in a block).
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/x/params/types/subspace.go#L20-L30
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/x/params/types/subspace.go#L20-L30>
Transient stores are typically accessed via the [`context`](./context.md) via the `TransientStore()` method:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/types/context.go#L232-L235
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/types/context.go#L232-L235>
## KVStore Wrappers
@ -170,7 +170,7 @@ Transient stores are typically accessed via the [`context`](./context.md) via th
`cachekv.Store` is a wrapper `KVStore` which provides buffered writing / cached reading functionalities over the underlying `KVStore`.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/cachekv/store.go#L27-L34
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/cachekv/store.go#L27-L34>
This is the type used whenever an IAVL Store needs to be branched to create an isolated store (typically when we need to mutate a state that might be reverted later).
@ -190,25 +190,25 @@ This is the type used whenever an IAVL Store needs to be branched to create an i
Cosmos SDK applications use [`gas`](../basics/gas-fees.md) to track resources usage and prevent spam. [`GasKv.Store`](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/gaskv/store.go) is a `KVStore` wrapper that enables automatic gas consumption each time a read or write to the store is made. It is the solution of choice to track storage usage in Cosmos SDK applications.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/gaskv/store.go#L13-L19
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/gaskv/store.go#L13-L19>
When methods of the parent `KVStore` are called, `GasKv.Store` automatically consumes appropriate amount of gas depending on the `Store.gasConfig`:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/gas.go#L153-L162
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/gas.go#L153-L162>
By default, all `KVStores` are wrapped in `GasKv.Stores` when retrieved. This is done in the `KVStore()` method of the [`context`](./context.md):
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/types/context.go#L227-L230
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/types/context.go#L227-L230>
In this case, the default gas configuration is used:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/gas.go#L164-L175
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/gas.go#L164-L175>
### `TraceKv` Store
`tracekv.Store` is a wrapper `KVStore` which provides operation tracing functionalities over the underlying `KVStore`. It is applied automatically by the Cosmos SDK on all `KVStore` if tracing is enabled on the parent `MultiStore`.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/tracekv/store.go#L20-L43
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/tracekv/store.go#L20-L43>
When each `KVStore` methods are called, `tracekv.Store` automatically logs `traceOperation` to the `Store.writer`. `traceOperation.Metadata` is filled with `Store.context` when it is not nil. `TraceContext` is a `map[string]interface{}`.
@ -216,7 +216,7 @@ When each `KVStore` methods are called, `tracekv.Store` automatically logs `trac
`prefix.Store` is a wrapper `KVStore` which provides automatic key-prefixing functionalities over the underlying `KVStore`.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/prefix/store.go#L15-L21
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/prefix/store.go#L15-L21>
When `Store.{Get, Set}()` is called, the store forwards the call to its parent, with the key prefixed with the `Store.prefix`.
@ -228,7 +228,7 @@ When `Store.Iterator()` is called, it does not simply prefix the `Store.prefix`,
It is applied automatically by the Cosmos SDK on any `KVStore` whose `StoreKey` is specified during state streaming configuration.
Additional information about state streaming configuration can be found in the [store/streaming/README.md](../../store/streaming/README.md).
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.44.1/store/listenkv/store.go#L11-L18
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.44.1/store/listenkv/store.go#L11-L18>
When `KVStore.Set` or `KVStore.Delete` methods are called, `listenkv.Store` automatically writes the operations to the set of `Store.listeners`.
@ -247,16 +247,18 @@ An interface providing only the basic CRUD functionality (`Get`, `Set`, `Has`, a
## MultiStore
This is the new interface (or, set of interfaces) for the main client store, replacing the role of `store/types.MultiStore` (v1). There are a few significant differences in behavior compared with v1:
* Commits are atomic and are performed on the entire store state; individual substores cannot be committed separately and cannot have different version numbers.
* The store's current version and version history track that of the backing `db.DBConnection`. Past versions are accessible read-only.
* The set of valid substores is defined at initialization and cannot be updated dynamically in an existing store instance.
* Commits are atomic and are performed on the entire store state; individual substores cannot be committed separately and cannot have different version numbers.
* The store's current version and version history track that of the backing `db.DBConnection`. Past versions are accessible read-only.
* The set of valid substores is defined at initialization and cannot be updated dynamically in an existing store instance.
### `CommitMultiStore`
This is the main interface for persisent application state, analogous to the original `CommitMultiStore`.
* Past version views are accessed with `GetVersion`, which returns a `BasicMultiStore`.
* Substores are accessed with `GetKVStore`. Trying to get a substore that was not defined at initialization will cause a panic.
* `Close` must be called to release the DB resources being used by the store.
* Past version views are accessed with `GetVersion`, which returns a `BasicMultiStore`.
* Substores are accessed with `GetKVStore`. Trying to get a substore that was not defined at initialization will cause a panic.
* `Close` must be called to release the DB resources being used by the store.
### `BasicMultiStore`

44
docs/core/transactions.md
View File

@ -8,7 +8,7 @@ order: 2
## Pre-requisite Readings
- [Anatomy of a Cosmos SDK Application](../basics/app-anatomy.md) {prereq}
* [Anatomy of a Cosmos SDK Application](../basics/app-anatomy.md) {prereq}
## Transactions
@ -20,12 +20,12 @@ When users want to interact with an application and make state changes (e.g. sen
Transaction objects are Cosmos SDK types that implement the `Tx` interface
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/tx_msg.go#L49-L57
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/tx_msg.go#L49-L57>
It contains the following methods:
- **GetMsgs:** unwraps the transaction and returns a list of contained `sdk.Msg`s - one transaction may have one or multiple messages, which are defined by module developers.
- **ValidateBasic:** lightweight, [_stateless_](../basics/tx-lifecycle.md#types-of-checks) checks used by ABCI messages [`CheckTx`](./baseapp.md#checktx) and [`DeliverTx`](./baseapp.md#delivertx) to make sure transactions are not invalid. For example, the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth) module's `StdTx` `ValidateBasic` function checks that its transactions are signed by the correct number of signers and that the fees do not exceed what the user's maximum. Note that this function is to be distinct from `sdk.Msg` [`ValidateBasic`](../basics/tx-lifecycle.md#ValidateBasic) methods, which perform basic validity checks on messages only. When [`runTx`](./baseapp.md#runtx) is checking a transaction created from the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth/spec) module, it first runs `ValidateBasic` on each message, then runs the `auth` module AnteHandler which calls `ValidateBasic` for the transaction itself.
* **GetMsgs:** unwraps the transaction and returns a list of contained `sdk.Msg`s - one transaction may have one or multiple messages, which are defined by module developers.
* **ValidateBasic:** lightweight, [_stateless_](../basics/tx-lifecycle.md#types-of-checks) checks used by ABCI messages [`CheckTx`](./baseapp.md#checktx) and [`DeliverTx`](./baseapp.md#delivertx) to make sure transactions are not invalid. For example, the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth) module's `StdTx` `ValidateBasic` function checks that its transactions are signed by the correct number of signers and that the fees do not exceed what the user's maximum. Note that this function is to be distinct from `sdk.Msg` [`ValidateBasic`](../basics/tx-lifecycle.md#ValidateBasic) methods, which perform basic validity checks on messages only. When [`runTx`](./baseapp.md#runtx) is checking a transaction created from the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth/spec) module, it first runs `ValidateBasic` on each message, then runs the `auth` module AnteHandler which calls `ValidateBasic` for the transaction itself.
As a developer, you should rarely manipulate `Tx` directly, as `Tx` is really an intermediate type used for transaction generation. Instead, developers should prefer the `TxBuilder` interface, which you can learn more about [below](#transaction-generation).
@ -37,11 +37,11 @@ Every message in a transaction must be signed by the addresses specified by its
The most used implementation of the `Tx` interface is the Protobuf `Tx` message, which is used in `SIGN_MODE_DIRECT`:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/tx.proto#L12-L25
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/tx.proto#L12-L25>
Because Protobuf serialization is not deterministic, the Cosmos SDK uses an additional `TxRaw` type to denote the pinned bytes over which a transaction is signed. Any user can generate a valid `body` and `auth_info` for a transaction, and serialize these two messages using Protobuf. `TxRaw` then pins the user's exact binary representation of `body` and `auth_info`, called respectively `body_bytes` and `auth_info_bytes`. The document that is signed by all signers of the transaction is `SignDoc` (deterministically serialized using [ADR-027](../architecture/adr-027-deterministic-protobuf-serialization.md)):
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/tx.proto#L47-L64
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/tx.proto#L47-L64>
Once signed by all signers, the `body_bytes`, `auth_info_bytes` and `signatures` are gathered into `TxRaw`, whose serialized bytes are broadcasted over the network.
@ -49,11 +49,11 @@ Once signed by all signers, the `body_bytes`, `auth_info_bytes` and `signatures`
The legacy implemention of the `Tx` interface is the `StdTx` struct from `x/auth`:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/auth/legacy/legacytx/stdtx.go#L120-L130
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/auth/legacy/legacytx/stdtx.go#L120-L130>
The document signed by all signers is `StdSignDoc`:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/auth/legacy/legacytx/stdsign.go#L20-L33
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/auth/legacy/legacytx/stdsign.go#L20-L33>
which is encoded into bytes using Amino JSON. Once all signatures are gathered into `StdTx`, `StdTx` is serialized using Amino JSON, and these bytes are broadcasted over the network.
@ -65,9 +65,9 @@ Other sign modes, most notably `SIGN_MODE_TEXTUAL`, are being discussed. If you
The process of an end-user sending a transaction is:
- decide on the messages to put into the transaction,
- generate the transaction using the Cosmos SDK's `TxBuilder`,
- broadcast the transaction using one of the available interfaces.
* decide on the messages to put into the transaction,
* generate the transaction using the Cosmos SDK's `TxBuilder`,
* broadcast the transaction using one of the available interfaces.
The next paragraphs will describe each of these components, in this order.
@ -90,23 +90,23 @@ While messages contain the information for state transition logic, a transaction
The `TxBuilder` interface contains data closely related with the generation of transactions, which an end-user can freely set to generate the desired transaction:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/client/tx_config.go#L32-L45
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/client/tx_config.go#L32-L45>
- `Msg`s, the array of [messages](#messages) included in the transaction.
- `GasLimit`, option chosen by the users for how to calculate how much gas they will need to pay.
- `Memo`, a note or comment to send with the transaction.
- `FeeAmount`, the maximum amount the user is willing to pay in fees.
- `TimeoutHeight`, block height until which the transaction is valid.
- `Signatures`, the array of signatures from all signers of the transaction.
* `Msg`s, the array of [messages](#messages) included in the transaction.
* `GasLimit`, option chosen by the users for how to calculate how much gas they will need to pay.
* `Memo`, a note or comment to send with the transaction.
* `FeeAmount`, the maximum amount the user is willing to pay in fees.
* `TimeoutHeight`, block height until which the transaction is valid.
* `Signatures`, the array of signatures from all signers of the transaction.
As there are currently two sign modes for signing transactions, there are also two implementations of `TxBuilder`:
- [wrapper](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/auth/tx/builder.go#L19-L33) for creating transactions for `SIGN_MODE_DIRECT`,
- [StdTxBuilder](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/auth/legacy/legacytx/stdtx_builder.go#L14-L20) for `SIGN_MODE_LEGACY_AMINO_JSON`.
* [wrapper](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/auth/tx/builder.go#L19-L33) for creating transactions for `SIGN_MODE_DIRECT`,
* [StdTxBuilder](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/auth/legacy/legacytx/stdtx_builder.go#L14-L20) for `SIGN_MODE_LEGACY_AMINO_JSON`.
However, the two implementation of `TxBuilder` should be hidden away from end-users, as they should prefer using the overarching `TxConfig` interface:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/client/tx_config.go#L21-L30
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/client/tx_config.go#L21-L30>
`TxConfig` is an app-wide configuration for managing transactions. Most importantly, it holds the information about whether to sign each transaction with `SIGN_MODE_DIRECT` or `SIGN_MODE_LEGACY_AMINO_JSON`. By calling `txBuilder := txConfig.NewTxBuilder()`, a new `TxBuilder` will be created with the appropriate sign mode.
@ -138,7 +138,7 @@ simd tx send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake
[gRPC](https://grpc.io) is introduced in Cosmos SDK 0.40 as the main component for the Cosmos SDK's RPC layer. The principal usage of gRPC is in the context of modules' [`Query` services](../building-modules). However, the Cosmos SDK also exposes a few other module-agnostic gRPC services, one of them being the `Tx` service:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/service.proto
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/service.proto>
The `Tx` service exposes a handful of utility functions, such as simulating a transaction or querying a transaction, and also one method to broadcast transactions.

4
docs/core/upgrade.md
View File

@ -12,9 +12,9 @@ Upgrade your app modules smoothly with custom in-place store migration logic. {s
The Cosmos SDK uses two methods to perform upgrades.
- Exporting the entire application state to a JSON file using the `export` CLI command, making changes, and then starting a new binary with the changed JSON file as the genesis file. See [Chain Upgrade Guide to v0.42](https://docs.cosmos.network/v0.42/migrations/chain-upgrade-guide-040.html).
* Exporting the entire application state to a JSON file using the `export` CLI command, making changes, and then starting a new binary with the changed JSON file as the genesis file. See [Chain Upgrade Guide to v0.42](https://docs.cosmos.network/v0.42/migrations/chain-upgrade-guide-040.html).
- Version v0.44 and later can perform upgrades in place to significantly decrease the upgrade time for chains with a larger state. Use the [Module Upgrade Guide](../building-modules/upgrade.md) to set up your application modules to take advantage of in-place upgrades.
* Version v0.44 and later can perform upgrades in place to significantly decrease the upgrade time for chains with a larger state. Use the [Module Upgrade Guide](../building-modules/upgrade.md) to set up your application modules to take advantage of in-place upgrades.
This document provides steps to use the In-Place Store Migrations upgrade method.

4
docs/ibc/custom.md
View File

@ -23,8 +23,8 @@ module correctly.
## Pre-requisites Readings
- [IBC Overview](./overview.md)) {prereq}
- [IBC default integration](./integration.md) {prereq}
* [IBC Overview](./overview.md)) {prereq}
* [IBC default integration](./integration.md) {prereq}
## Create a custom IBC application module

14
docs/ibc/integration.md
View File

@ -14,13 +14,13 @@ send fungible token transfers to other chains.
Integrating the IBC module to your Cosmos SDK-based application is straighforward. The general changes can be summarized in the following steps:
- Add required modules to the `module.BasicManager`
- Define additional `Keeper` fields for the new modules on the `App` type
- Add the module's `StoreKeys` and initialize their `Keepers`
- Set up corresponding routers and routes for the `ibc` and `evidence` modules
- Add the modules to the module `Manager`
- Add modules to `Begin/EndBlockers` and `InitGenesis`
- Update the module `SimulationManager` to enable simulations
* Add required modules to the `module.BasicManager`
* Define additional `Keeper` fields for the new modules on the `App` type
* Add the module's `StoreKeys` and initialize their `Keepers`
* Set up corresponding routers and routes for the `ibc` and `evidence` modules
* Add the modules to the module `Manager`
* Add modules to `Begin/EndBlockers` and `InitGenesis`
* Update the module `SimulationManager` to enable simulations
### Module `BasicManager` and `ModuleAccount` permissions

48
docs/ibc/overview.md
View File

@ -6,7 +6,7 @@ order: 1
Learn what IBC is, its components, and use cases. {synopsis}
## What is the Inter-Blockchain Communication Protocol (IBC)?
## What is the Inter-Blockchain Communication Protocol (IBC)
The Inter-Blockchain Communication protocol (IBC) allows blockchains to talk to each other. The backbone of the Cosmos ecosystem, IBC handles transport across different sovereign blockchains. This end-to-end, connection-oriented, stateful protocol provides reliable, ordered, and authenticated communication between heterogeneous blockchains.
@ -18,13 +18,13 @@ The abstraction layer details on channels and ports are relevant for app develop
The following requirements must be met for a module to interact over IBC:
- Bind to one or more ports
* Bind to one or more ports
- Define the packet data
* Define the packet data
- Define optional acknowledgement structures and methods to encode and decode them
* Define optional acknowledgement structures and methods to encode and decode them
- Implement the IBCModule interface
* Implement the IBCModule interface
## Components Overview
@ -34,9 +34,9 @@ This section describes the IBC components and links to the repos.
IBC clients are light clients that are identified by a unique client id. IBC clients track the consensus states of other blockchains and the proof specs of those blockchains that are required to properly verify proofs against the client's consensus state. A client can be associated with any number of connections to multiple chains. The supported IBC clients are:
- [Solo Machine light client](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/06-solomachine): devices such as phones, browsers, or laptops.
- [Tendermint light client](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/07-tendermint): The default for Cosmos SDK-based chains.
- [Localhost (loopback) client](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/09-localhost): Useful for testing, simulation, and relaying packets to modules on the same application.
* [Solo Machine light client](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/06-solomachine): devices such as phones, browsers, or laptops.
* [Tendermint light client](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/07-tendermint): The default for Cosmos SDK-based chains.
* [Localhost (loopback) client](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/09-localhost): Useful for testing, simulation, and relaying packets to modules on the same application.
### [Connections](https://github.com/cosmos/ibc-go/blob/main/modules/core/03-connection)
@ -46,13 +46,13 @@ Connections encapsulate two `ConnectionEnd` objects on two separate blockchains.
In IBC, blockchains do not directly pass messages to each other over the network.
- To communicate, a blockchain commits some state to a precisely defined path reserved for a specific message type and a specific counterparty. For example, a blockchain that stores a specific connectionEnd as part of a handshake or a packet intended to be relayed to a module on the counterparty chain.
* To communicate, a blockchain commits some state to a precisely defined path reserved for a specific message type and a specific counterparty. For example, a blockchain that stores a specific connectionEnd as part of a handshake or a packet intended to be relayed to a module on the counterparty chain.
- A relayer process monitors for updates to these paths and relays messages by submitting the data stored under the path along with a proof of that data to the counterparty chain.
* A relayer process monitors for updates to these paths and relays messages by submitting the data stored under the path along with a proof of that data to the counterparty chain.
- The paths that all IBC implementations must support for committing IBC messages are defined in [ICS-24 host requirements](https://github.com/cosmos/ics/tree/master/spec/core/ics-024-host-requirements).
* The paths that all IBC implementations must support for committing IBC messages are defined in [ICS-24 host requirements](https://github.com/cosmos/ics/tree/master/spec/core/ics-024-host-requirements).
- The proof format that all implementations must produce and verify is defined in [ICS-23 implementation](https://github.com/confio/ics23).
* The proof format that all implementations must produce and verify is defined in [ICS-23 implementation](https://github.com/confio/ics23).
### [Capabilities](./ocap.md)
@ -74,9 +74,9 @@ IBC modules are responsible for claiming the capability that is returned on `Bin
An IBC channel can be established between two IBC ports. A port is exclusively owned by a single module. IBC packets are sent over channels. Just as IP packets contain the destination IP address, IP port, the source IP address, and source IP port, IBC packets contain the destination portID, channelID, the source portID, and channelID. The IBC packets enable IBC to correctly route the packets to the destination module, while also allowing modules receiving packets to know the sender module.
- A channel can be `ORDERED` so that packets from a sending module must be processed by the receiving module in the order they were sent.
* A channel can be `ORDERED` so that packets from a sending module must be processed by the receiving module in the order they were sent.
- Recommended, a channel may be `UNORDERED` so that packets from a sending module are processed in the order they arrive, which may not be the order the packets were sent.
* Recommended, a channel may be `UNORDERED` so that packets from a sending module are processed in the order they arrive, which may not be the order the packets were sent.
Modules may choose which channels they wish to communicate over with. IBC expects modules to implement callbacks that are called during the channel handshake. These callbacks may do custom channel initialization logic. If an error is returned, the channel handshake fails. By returning errors on callbacks, modules can programmatically reject and accept channels.
@ -95,19 +95,19 @@ Just as ports came with dynamic capabilities, channel initialization returns a d
Modules communicate with each other by sending packets over IBC channels. All IBC packets contain:
- Destination `portID`
* Destination `portID`
- Destination `channelID`
* Destination `channelID`
- Source `portID`
* Source `portID`
- Source `channelID`
* Source `channelID`
These port and channels allow the modules to know the sender module of a given packet.
- A sequence to optionally enforce ordering
* A sequence to optionally enforce ordering
- `TimeoutTimestamp` and `TimeoutHeight`
* `TimeoutTimestamp` and `TimeoutHeight`
When non-zero, these timeout values determine the deadline before which the receiving module must process a packet.
@ -131,9 +131,9 @@ For this reason, most modules that use UNORDERED channels are recommended as the
Modules also write application-specific acknowledgements when processing a packet. Acknowledgements can be done:
- Synchronously on `OnRecvPacket` if the module processes packets as soon as they are received from IBC module.
* Synchronously on `OnRecvPacket` if the module processes packets as soon as they are received from IBC module.
- Asynchronously if module processes packets at some later point after receiving the packet.
* Asynchronously if module processes packets at some later point after receiving the packet.
This acknowledgement data is opaque to IBC much like the packet `Data` and is treated by IBC as a simple byte string `[]byte`. The receiver modules must encode their acknowledgement so that the sender module can decode it correctly. How the acknowledgement is encoded should be decided through version negotiation during the channel handshake.
@ -147,8 +147,8 @@ After an acknowledgement is received successfully on the original sender the cha
To learn more about IBC, check out the following specifications:
- [IBC specs](https://github.com/cosmos/ibc/tree/master/spec)
- [IBC protocol on the Cosmos SDK](https://github.com/cosmos/ibc-go/tree/main/docs)
* [IBC specs](https://github.com/cosmos/ibc/tree/master/spec)
* [IBC protocol on the Cosmos SDK](https://github.com/cosmos/ibc-go/tree/main/docs)
## Next {hide}

10
docs/ibc/relayer.md
View File

@ -6,8 +6,8 @@ order: 4
## Prerequisites Readings
- [IBC Overview](./overview.md) {prereq}
- [Events](https://github.com/cosmos/cosmos-sdk/blob/master/docs/core/events.md) {prereq}
* [IBC Overview](./overview.md) {prereq}
* [Events](https://github.com/cosmos/cosmos-sdk/blob/master/docs/core/events.md) {prereq}
## Events
@ -42,6 +42,6 @@ piece of information needed to relay a packet.
## Example Implementations
- [Golang Relayer](https://github.com/iqlusioninc/relayer)
- [Hermes](https://github.com/informalsystems/ibc-rs/tree/master/relayer)
- [Typescript Relayer](https://github.com/confio/ts-relayer)
* [Golang Relayer](https://github.com/iqlusioninc/relayer)
* [Hermes](https://github.com/informalsystems/ibc-rs/tree/master/relayer)
* [Typescript Relayer](https://github.com/confio/ts-relayer)

Some files were not shown because too many files have changed in this diff Show More