LaconicNetwork/cosmos-sdk
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity

feat: migrate to docusaurus (#13471)

Browse Source
This commit is contained in:
Julien Robert 2022-10-10 16:01:53 +02:00 committed by GitHub
parent 7167371f87
commit a74989ddf4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
226 changed files with 30164 additions and 9948 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/workflows/build-docs.yml vendored
View File

@ -13,7 +13,7 @@ permissions:
jobs:
check-docs-build:
if: ${{ github.event.label.name == 'docs' }}
if: ${{ contains(github.event.label.name, 'docs') }}
name: Check docs build
runs-on: ubuntu-latest
@ -26,4 +26,4 @@ jobs:
- name: Build docs
run: |
make build-docs LEDGER_ENABLED=false
make build-docs

10
.github/workflows/deploy-docs.yml vendored
View File

@ -19,8 +19,6 @@ jobs:
permissions:
contents: write # for JamesIves/github-pages-deploy-action to push changes in repo
runs-on: ubuntu-latest
container:
image: ghcr.io/cosmos/website-deployment
steps:
- name: Checkout 🛎️
uses: actions/checkout@v3
@ -29,10 +27,14 @@ jobs:
fetch-depth: 0
path: "."
- name: Use Node.js
uses: actions/setup-node@v3
with:
node-version: "16.x"
- name: Build 🔧
run: |
git config --global --add safe.directory /__w/cosmos-sdk/cosmos-sdk
make build-docs LEDGER_ENABLED=false
make build-docs
- name: Deploy 🚀
uses: JamesIves/github-pages-deploy-action@v4.4.0

2
CHANGELOG.md
View File

@ -359,7 +359,7 @@ Ref: https://keepachangelog.com/en/1.0.0/
### Client Breaking Changes
* [#11797](https://github.com/cosmos/cosmos-sdk/pull/11797) Remove all RegisterRESTRoutes (previously deprecated)
* [#11089](https://github.com/cosmos/cosmos-sdk/pull/11089]) interacting with the node through `grpc.Dial` requires clients to pass a codec refer to [doc](docs/run-node/interact-node.md).
* [#11089](https://github.com/cosmos/cosmos-sdk/pull/11089]) interacting with the node through `grpc.Dial` requires clients to pass a codec refer to [doc](docs/docs/run-node/02-interact-node.md).
* [#9594](https://github.com/cosmos/cosmos-sdk/pull/9594) Remove legacy REST API. Please see the [REST Endpoints Migration guide](https://docs.cosmos.network/v0.45/migrations/rest.html) to migrate to the new REST endpoints.
* [#9995](https://github.com/cosmos/cosmos-sdk/pull/9995) Increased gas cost for creating proposals.
* [#11029](https://github.com/cosmos/cosmos-sdk/pull/11029) The deprecated Vote Option field is removed in gov v1beta2 and nil in v1beta1. Use Options instead.

2
CODING_GUIDELINES.md
View File

@ -41,7 +41,7 @@ and API.
UAT should be revisited at each stage of the product development:
![acceptance-tests.png](./docs/assets/acceptance-tests.png)
![acceptance-tests.png](./docs/static/img/acceptance-tests.png)
### Why Acceptance Testing

29
Makefile
View File

@ -188,22 +188,23 @@ godocs:
@echo "--> Wait a few seconds and visit http://localhost:6060/pkg/github.com/cosmos/cosmos-sdk/types"
godoc -http=:6060
# This builds a docs site for each branch/tag in `./docs/versions`
# and copies each site to a version prefixed path. The last entry inside
# the `versions` file will be the default root index.html (and it should be main).
# Only redirects that are built into the "redirects" folder of each of
# the branches will be copied out to the root of the build at the end.
# This builds the docs.cosmos.network docs using docusaurus.
# Old documentation, which have not been migrated to docusaurus are generated with vuepress.
build-docs:
@echo "building docusaurus docs"
@cd docs && npm ci && npm run build
mv docs/build ~/output
@echo "building old docs"
@cd docs && \
while read -r branch path_prefix; do \
echo "building branch $${branch}" ; \
(git clean -fdx && git reset --hard && git checkout $${branch} && npm install && VUEPRESS_BASE="/$${path_prefix}/" npm run build) ; \
mkdir -p ~/output/$${path_prefix} ; \
cp -r .vuepress/dist/* ~/output/$${path_prefix}/ ; \
cp ~/output/$${path_prefix}/index.html ~/output ; \
cp ~/output/$${path_prefix}/404.html ~/output ; \
cp -r ~/output/$${path_prefix}/redirects/* ~/output || true ; \
done < versions ;
while read -r branch path_prefix; do \
echo "building vuepress $${branch} docs" ; \
(git clean -fdx && git reset --hard && git checkout $${branch} && npm install && VUEPRESS_BASE="/$${path_prefix}/" npm run build) ; \
mkdir -p ~/output/$${path_prefix} ; \
cp -r .vuepress/dist/* ~/output/$${path_prefix}/ ; \
done < vuepress_versions ;
@echo "setup domain"
@echo $(DOCS_DOMAIN) > ~/output/CNAME
.PHONY: build-docs

7
README.md
View File

@ -1,13 +1,8 @@
<!--
parent:
order: false
-->
<div align="center">
<h1> Cosmos SDK </h1>
</div>
![banner](docs/assets/banner.jpg)
![banner](docs/static/img/banner.jpg)
<div align="center">
<a href="https://github.com/cosmos/cosmos-sdk/blob/main/LICENSE">

2
core/README.md
View File

@ -8,4 +8,4 @@ package and composing apps using the [appconfig](https://pkg.go.dev/cosmossdk.io
package is provided.
In the future core functionality for building Cosmos SDK app modules will be
provided in this go module.
provided in this go module.

4
cosmovisor/README.md
View File

@ -1,3 +1,7 @@
---
sidebar_position: 1
---
# Cosmovisor
`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.

4
depinject/README.md
View File

@ -1,3 +1,7 @@
---
sidebar_position: 1
---
# Cosmos SDK Dependency Injection `depinject` Module
## Overview

20
docs/.gitignore vendored Normal file
View File

@ -0,0 +1,20 @@
# Dependencies
/node_modules
# Production
/build
# Generated files
.docusaurus
.cache-loader
# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local
npm-debug.log*
yarn-debug.log*
yarn-error.log*

245
docs/.vuepress/config.js
View File

@ -1,245 +0,0 @@
module.exports = {
theme: "cosmos",
title: "Cosmos SDK",
locales: {
"/": {
lang: "en-US",
},
},
base: process.env.VUEPRESS_BASE || "/",
head: [
[
"link",
{
rel: "apple-touch-icon",
sizes: "180x180",
href: "/apple-touch-icon.png",
},
],
[
"link",
{
rel: "icon",
type: "image/png",
sizes: "32x32",
href: "/favicon-32x32.png",
},
],
[
"link",
{
rel: "icon",
type: "image/png",
sizes: "16x16",
href: "/favicon-16x16.png",
},
],
["link", { rel: "manifest", href: "/site.webmanifest" }],
["meta", { name: "msapplication-TileColor", content: "#2e3148" }],
["meta", { name: "theme-color", content: "#ffffff" }],
["link", { rel: "icon", type: "image/svg+xml", href: "/favicon-svg.svg" }],
[
"link",
{
rel: "apple-touch-icon-precomposed",
href: "/apple-touch-icon-precomposed.png",
},
],
],
themeConfig: {
repo: "cosmos/cosmos-sdk",
docsRepo: "cosmos/cosmos-sdk",
docsBranch: "main",
docsDir: "docs",
editLinks: true,
label: "sdk",
algolia: {
id: "BH4D9OD16A",
key: "ac317234e6a42074175369b2f42e9754",
index: "cosmos-sdk",
},
versions: [
{
label: "v0.45",
key: "v0.45",
},
{
label: "v0.46",
key: "v0.46",
},
{
label: "v0.47 - Twilight",
key: "v0.47",
},
{
label: "main",
key: "main",
},
],
topbar: {
banner: false,
},
sidebar: {
auto: true,
nav: [
{
title: "Using the SDK",
children: [
{
title: "Modules",
directory: true,
path: "/modules",
},
],
},
{
title: "Resources",
children: [
{
title: "Tutorials",
path: "https://tutorials.cosmos.network",
},
{
title: "SDK API Reference",
path: "https://pkg.go.dev/github.com/cosmos/cosmos-sdk",
},
{
title: "REST API Spec",
path: "https://cosmos.network/rpc/",
},
],
},
],
},
gutter: {
title: "Help & Support",
editLink: true,
chat: {
title: "Discord",
text: "Chat with Cosmos developers on Discord.",
url: "https://discordapp.com/channels/669268347736686612",
bg: "linear-gradient(225.11deg, #2E3148 0%, #161931 95.68%)",
},
forum: {
title: "Cosmos SDK Forum",
text: "Join the SDK Developer Forum to learn more.",
url: "https://forum.cosmos.network/",
bg: "linear-gradient(225deg, #46509F -1.08%, #2F3564 95.88%)",
logo: "cosmos",
},
github: {
title: "Found an Issue?",
text: "Help us improve this page by suggesting edits on GitHub.",
},
},
footer: {
question: {
text:
"Chat with Cosmos developers in <a href='https://discord.gg/cosmosnetwork' target='_blank'>Discord</a> or reach out on the <a href='https://forum.cosmos.network/c/tendermint' target='_blank'>SDK Developer Forum</a> to learn more.",
},
logo: "/logo-bw.svg",
textLink: {
text: "cosmos.network",
url: "https://cosmos.network",
},
services: [
{
service: "medium",
url: "https://blog.cosmos.network/",
},
{
service: "twitter",
url: "https://twitter.com/cosmos",
},
{
service: "linkedin",
url: "https://www.linkedin.com/company/interchain-gmbh/",
},
{
service: "reddit",
url: "https://reddit.com/r/cosmosnetwork",
},
{
service: "telegram",
url: "https://t.me/cosmosproject",
},
{
service: "youtube",
url: "https://www.youtube.com/c/CosmosProject",
},
],
smallprint:
"The development of the Cosmos SDK is led primarily by [Interchain Core Teams](https://interchain.io/ecosystem). Funding for this development comes primarily from the Interchain Foundation, a Swiss non-profit.",
links: [
{
title: "Documentation",
children: [
{
title: "Cosmos Hub",
url: "https://hub.cosmos.network",
},
{
title: "Tendermint Core",
url: "https://docs.tendermint.com",
},
{
title: "IBC Go",
url: "https://ibc.cosmos.network",
},
],
},
{
title: "Community",
children: [
{
title: "Cosmos blog",
url: "https://blog.cosmos.network",
},
{
title: "Forum",
url: "https://forum.cosmos.network",
},
{
title: "Chat",
url: "https://discord.gg/cosmosnetwork",
},
],
},
{
title: "Contributing",
children: [
{
title: "Contributing to the docs",
url:
"https://github.com/cosmos/cosmos-sdk/blob/main/docs/DOCS_README.md",
},
{
title: "Source code on GitHub",
url: "https://github.com/cosmos/cosmos-sdk/",
},
],
},
],
},
},
plugins: [
[
"@vuepress/google-analytics",
{
ga: "UA-51029217-2",
},
],
[
"@vuepress/html-redirect",
{
countdown: 0,
},
],
[
"sitemap",
{
hostname: "https://docs.cosmos.network",
},
],
],
};

BIN
docs/.vuepress/public/apple-touch-icon-precomposed.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.4 KiB

9
docs/.vuepress/public/browserconfig.xml
View File

@ -1,9 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<browserconfig>
<msapplication>
<tile>
<square150x150logo src="/mstile-150x150.png"/>
<TileColor>#da532c</TileColor>
</tile>
</msapplication>
</browserconfig>

BIN
docs/.vuepress/public/mstile-150x150.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 3.0 KiB

25
docs/.vuepress/public/safari-pinned-tab.svg
View File

@ -1,25 +0,0 @@
<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
"http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
<svg version="1.0" xmlns="http://www.w3.org/2000/svg"
width="260.000000pt" height="260.000000pt" viewBox="0 0 260.000000 260.000000"
preserveAspectRatio="xMidYMid meet">
<metadata>
Created by potrace 1.11, written by Peter Selinger 2001-2013
</metadata>
<g transform="translate(0.000000,260.000000) scale(0.100000,-0.100000)"
fill="#000000" stroke="none">
<path d="M2111 2328 l-274 -272 -76 41 c-161 86 -286 114 -491 108 -110 -2
-163 -8 -219 -25 -322 -93 -555 -327 -643 -645 -18 -67 -22 -105 -21 -240 0
-143 3 -169 26 -245 27 -90 73 -195 107 -245 11 -16 20 -33 20 -37 0 -5 -121
-129 -270 -278 l-270 -270 105 -105 c57 -58 108 -105 112 -105 5 0 129 121
277 269 l269 269 71 -38 c149 -81 270 -112 444 -115 170 -4 310 27 447 97 256
131 424 355 480 640 13 69 15 291 2 343 -3 11 -8 34 -12 50 -19 80 -59 177
-111 268 l-28 48 272 272 272 272 -107 107 -108 107 -274 -271z m-668 -417
c50 -12 167 -66 167 -78 0 -3 -187 -192 -416 -420 -308 -307 -419 -412 -425
-402 -13 19 -47 135 -57 189 -8 47 -8 177 1 220 39 194 154 360 304 438 123
64 292 85 426 53z m403 -353 c9 -24 18 -47 19 -53 2 -5 8 -30 15 -55 18 -63
16 -231 -4 -313 -57 -239 -252 -424 -479 -454 -143 -19 -302 11 -397 76 -12 9
64 90 400 426 228 228 418 415 421 415 4 0 15 -19 25 -42z"/>
</g>
</svg>
Side by Side

Before

Width:  |  Height:  |  Size: 1.4 KiB

19
docs/.vuepress/public/site.webmanifest
View File

@ -1,19 +0,0 @@
{
"name": "Cosmos SDK Documentation",
"short_name": "Cosmos SDK",
"icons": [
{
"src": "/android-chrome-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "/android-chrome-256x256.png",
"sizes": "256x256",
"type": "image/png"
}
],
"theme_color": "#ffffff",
"background_color": "#ffffff",
"display": "standalone"
}

98
docs/.vuepress/redirects
View File

@ -1,98 +0,0 @@
/redirects/master https://docs.cosmos.network/main/
/redirects/main/spec/governance/ https://docs.cosmos.network/main/modules/gov/
/redirects/v0.43 https://docs.cosmos.network/main/
/redirects/v0.44 https://docs.cosmos.network/main/
/redirects/main/modules/auth/01_concepts.html https://docs.cosmos.network/main/modules/auth/
/redirects/main/modules/auth/02_state.html https://docs.cosmos.network/main/modules/auth/
/redirects/main/modules/auth/03_antehandlers.html https://docs.cosmos.network/main/modules/auth/
/redirects/main/modules/auth/04_keepers.html https://docs.cosmos.network/main/modules/auth/
/redirects/main/modules/auth/05_vesting.html https://docs.cosmos.network/main/modules/vesting/
/redirects/main/modules/auth/06_params.html https://docs.cosmos.network/main/modules/auth/
/redirects/main/modules/auth/07_client.html https://docs.cosmos.network/main/modules/auth/
/redirects/main/modules/authz/01_concepts.html https://docs.cosmos.network/main/modules/authz/
/redirects/main/modules/authz/02_state.html https://docs.cosmos.network/main/modules/authz/
/redirects/main/modules/authz/03_messages.html https://docs.cosmos.network/main/modules/authz/
/redirects/main/modules/authz/04_events.html https://docs.cosmos.network/main/modules/authz/
/redirects/main/modules/authz/05_client.html https://docs.cosmos.network/main/modules/authz/
/redirects/main/modules/bank/01_state.html https://docs.cosmos.network/main/modules/bank/
/redirects/main/modules/bank/02_keepers.html https://docs.cosmos.network/main/modules/bank/
/redirects/main/modules/bank/04_events.html https://docs.cosmos.network/main/modules/bank/
/redirects/main/modules/bank/05_params.html https://docs.cosmos.network/main/modules/bank/
/redirects/main/modules/bank/06_client.html https://docs.cosmos.network/main/modules/bank/
/redirects/main/modules/capability/01_concepts.html https://docs.cosmos.network/main/modules/capability/
/redirects/main/modules/capability/02_state.html https://docs.cosmos.network/main/modules/capability/
/redirects/main/modules/crisis/01_state.html https://docs.cosmos.network/main/modules/crisis/
/redirects/main/modules/crisis/02_messages.html https://docs.cosmos.network/main/modules/crisis/
/redirects/main/modules/crisis/03_events.html https://docs.cosmos.network/main/modules/crisis/
/redirects/main/modules/crisis/04_params.html https://docs.cosmos.network/main/modules/crisis/
/redirects/main/modules/crisis/05_client.html https://docs.cosmos.network/main/modules/crisis/
/redirects/main/modules/distribution/01_concepts.html https://docs.cosmos.network/main/modules/distribution/
/redirects/main/modules/distribution/02_state.html https://docs.cosmos.network/main/modules/distribution/
/redirects/main/modules/distribution/03_begin_block.html https://docs.cosmos.network/main/modules/distribution/
/redirects/main/modules/distribution/04_messages.html https://docs.cosmos.network/main/modules/distribution/
/redirects/main/modules/distribution/05_hooks.html https://docs.cosmos.network/main/modules/distribution/
/redirects/main/modules/distribution/06_events.html https://docs.cosmos.network/main/modules/distribution/
/redirects/main/modules/distribution/07_params.html https://docs.cosmos.network/main/modules/distribution/
/redirects/main/modules/distribution/08_client.html https://docs.cosmos.network/main/modules/distribution/
/redirects/main/modules/epoching/01_state.html https://docs.cosmos.network/main/modules/epoching/
/redirects/main/modules/epoching/03_to_improve.html https://docs.cosmos.network/main/modules/epoching/
/redirects/main/modules/evidence/01_concepts.html https://docs.cosmos.network/main/modules/evidence/
/redirects/main/modules/evidence/02_state.html https://docs.cosmos.network/main/modules/evidence/
/redirects/main/modules/evidence/03_messages.html https://docs.cosmos.network/main/modules/evidence/
/redirects/main/modules/evidence/04_events.html https://docs.cosmos.network/main/modules/evidence/
/redirects/main/modules/evidence/05_params.html https://docs.cosmos.network/main/modules/evidence/
/redirects/main/modules/evidence/06_begin_block.html https://docs.cosmos.network/main/modules/evidence/
/redirects/main/modules/evidence/07_client.html https://docs.cosmos.network/main/modules/evidence/
/redirects/main/modules/feegrant/01_concepts.html https://docs.cosmos.network/main/modules/feegrant/
/redirects/main/modules/feegrant/02_state.html https://docs.cosmos.network/main/modules/feegrant/
/redirects/main/modules/feegrant/03_messages.html https://docs.cosmos.network/main/modules/feegrant/
/redirects/main/modules/feegrant/04_events.html https://docs.cosmos.network/main/modules/feegrant/
/redirects/main/modules/feegrant/05_client.html https://docs.cosmos.network/main/modules/feegrant/
/redirects/main/modules/gov/01_concepts.html https://docs.cosmos.network/main/modules/gov/
/redirects/main/modules/gov/02_state.html https://docs.cosmos.network/main/modules/gov/
/redirects/main/modules/gov/03_messages.html https://docs.cosmos.network/main/modules/gov/
/redirects/main/modules/gov/04_events.html https://docs.cosmos.network/main/modules/gov/
/redirects/main/modules/gov/05_future_improvements.html https://docs.cosmos.network/main/modules/gov/
/redirects/main/modules/gov/06_params.html https://docs.cosmos.network/main/modules/gov/
/redirects/main/modules/gov/07_client.html https://docs.cosmos.network/main/modules/gov/
/redirects/main/modules/gov/08_metadata.html https://docs.cosmos.network/main/modules/gov/
/redirects/main/modules/group/01_concepts.html https://docs.cosmos.network/main/modules/group/
/redirects/main/modules/group/02_state.html https://docs.cosmos.network/main/modules/group/
/redirects/main/modules/group/03_messages.html https://docs.cosmos.network/main/modules/group/
/redirects/main/modules/group/04_events.html https://docs.cosmos.network/main/modules/group/
/redirects/main/modules/group/05_client.html https://docs.cosmos.network/main/modules/group/
/redirects/main/modules/group/06_metadata.html https://docs.cosmos.network/main/modules/group/
/redirects/main/modules/mint/01_concepts.html https://docs.cosmos.network/main/modules/mint/
/redirects/main/modules/mint/02_state.html https://docs.cosmos.network/main/modules/mint/
/redirects/main/modules/mint/03_begin_block.html https://docs.cosmos.network/main/modules/mint/
/redirects/main/modules/mint/04_params.html https://docs.cosmos.network/main/modules/mint/
/redirects/main/modules/mint/05_events.html https://docs.cosmos.network/main/modules/mint/
/redirects/main/modules/mint/06_client.html https://docs.cosmos.network/main/modules/mint/
/redirects/main/modules/nft/01_concepts.html https://docs.cosmos.network/main/modules/nft/
/redirects/main/modules/nft/02_state.html https://docs.cosmos.network/main/modules/nft/
/redirects/main/modules/nft/03_messages.html https://docs.cosmos.network/main/modules/nft/
/redirects/main/modules/nft/04_events.html https://docs.cosmos.network/main/modules/nft/
/redirects/main/modules/params/01_keeper.html https://docs.cosmos.network/main/modules/params/
/redirects/main/modules/params/02_subspace.html https://docs.cosmos.network/main/modules/params/
/redirects/main/modules/slashing/01_concepts.html https://docs.cosmos.network/main/modules/slashing/
/redirects/main/modules/slashing/02_state.html https://docs.cosmos.network/main/modules/slashing/
/redirects/main/modules/slashing/03_messages.html https://docs.cosmos.network/main/modules/slashing/
/redirects/main/modules/slashing/04_begin_block.html https://docs.cosmos.network/main/modules/slashing/
/redirects/main/modules/slashing/05_hooks.html https://docs.cosmos.network/main/modules/slashing/
/redirects/main/modules/slashing/06_events.html https://docs.cosmos.network/main/modules/slashing/
/redirects/main/modules/slashing/07_tombstone.html https://docs.cosmos.network/main/modules/slashing/
/redirects/main/modules/slashing/08_params.html https://docs.cosmos.network/main/modules/slashing/
/redirects/main/modules/slashing/09_client.html https://docs.cosmos.network/main/modules/slashing/
/redirects/main/modules/staking/01_state.html https://docs.cosmos.network/main/modules/staking/
/redirects/main/modules/staking/02_state_transitions.html https://docs.cosmos.network/main/modules/staking/
/redirects/main/modules/staking/03_messages.html https://docs.cosmos.network/main/modules/staking/
/redirects/main/modules/staking/04_begin_block.html https://docs.cosmos.network/main/modules/staking/
/redirects/main/modules/staking/05_end_block.html https://docs.cosmos.network/main/modules/staking/
/redirects/main/modules/staking/06_hooks.html https://docs.cosmos.network/main/modules/staking/
/redirects/main/modules/staking/07_events.html https://docs.cosmos.network/main/modules/staking/
/redirects/main/modules/staking/08_params.html https://docs.cosmos.network/main/modules/staking/
/redirects/main/modules/staking/09_client.html https://docs.cosmos.network/main/modules/staking/
/redirects/main/modules/upgrade/01_concepts.html https://docs.cosmos.network/main/modules/upgrade/
/redirects/main/modules/upgrade/02_state.html https://docs.cosmos.network/main/modules/upgrade/
/redirects/main/modules/upgrade/03_events.html https://docs.cosmos.network/main/modules/upgrade/
/redirects/main/modules/upgrade/04_client.html https://docs.cosmos.network/main/modules/upgrade/

3
docs/.vuepress/styles/index.styl
View File

@ -1,3 +0,0 @@
:root
--color-primary #5064fb
--color-link #5064fb

47
docs/404.md
View File

@ -1,47 +0,0 @@
<!--
permalink: /404.html
layout: homepage
title: 404 Lost in Space!
description: You've been lost in space
sections:
- title: Introduction
desc: High-level overview of the Cosmos SDK.
url: /intro/overview.html
icon: introduction
- title: Basics
desc: Anatomy of a blockchain, transaction lifecycle, accounts and more.
icon: basics
url: /basics/app-anatomy.html
- title: Core Concepts
desc: Read about the core concepts like baseapp, the store, or the server.
icon: core
url: /core/baseapp.html
- title: Building Modules
desc: Discover how to build modules for the Cosmos SDK.
icon: modules
url: /building-modules/intro.html
- title: Running a Node
desc: Running and interacting with nodes using the CLI and API.
icon: interfaces
url: /run-node/
- title: Modules
desc: Explore existing modules to build your application with.
icon: specifications
url: /modules/
stack:
- title: Cosmos Hub
desc: The first of thousands of interconnected blockchains on the Cosmos Network.
color: "#BA3FD9"
label: hub
url: http://hub.cosmos.network
- title: Tendermint Core
desc: The leading BFT engine for building blockchains, powering Cosmos SDK.
color: "#00BB00"
label: core
url: http://docs.tendermint.com
footer:
newsletter: false
aside: false
-->
# 404 - Lost in space, this is just an empty void

109
docs/DOCS_README.md
View File

@ -1,109 +0,0 @@
# Updating the docs
If you want to open a PR in Cosmos SDK to update the documentation, please follow the guidelines in [`CONTRIBUTING.md`](https://github.com/cosmos/cosmos-sdk/tree/main/CONTRIBUTING.md#updating-documentation).
## Docs Build Workflow
The documentation for Cosmos SDK is hosted at https://docs.cosmos.network and built from the files in the `/docs` directory.
### How It Works
There is a GitHub Action listening for changes in the `/docs` directory for the `main` branch and each supported version branch (e.g. `release/v0.46.x`). Any updates to files in the `/docs` directory will automatically trigger a website deployment. Under the hood, the private website repository has a `make build-docs` target consumed by a Github Action within that repository.
## README
The [README.md](./README.md) is both the README for the repository and the configuration for the layout of the landing page.
## Config.js
The [config.js](./.vuepress/config.js) generates the sidebar and Table of Contents
on the website docs. Note the use of relative links and the omission of
file extensions. Additional features are available to improve the look
of the sidebar.
## Links
**NOTE:** Strongly consider the existing links - both within this directory
and to the website docs - when moving or deleting files.
Relative links should be used nearly everywhere, having discovered and weighed the following:
### Relative
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
### 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)
### Full
The full GitHub URL to a file or directory. Used occasionally when it makes sense
to send users to the GitHub.
## Building Locally
Make sure you are in the `docs` directory and run the following commands:
```sh
rm -rf node_modules
```
This command will remove old version of the visual theme and required packages. This step is optional.
```sh
npm install
```
Install the theme and all dependencies.
```sh
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).
To build documentation as a static website run `npm run build`. You will find the website in `.vuepress/dist` directory.
## Build RPC Docs
First, run `make tools` from the root of repo, to install the swagger-ui tool.
Then, edit the `swagger.yaml` manually; it is found [here](https://github.com/cosmos/cosmos-sdk/blob/main/client/lcd/swagger-ui/swagger.yaml)
Finally, run `make update_gaia_lite_docs` from the root of the repo.
## Search
We are using [Algolia](https://www.algolia.com) to power full-text search. This uses a public API search-only key in the `config.js` as well as a [cosmos_network.json](https://github.com/algolia/docsearch-configs/blob/master/configs/cosmos_network.json) configuration file that we can update with PRs.
## Consistency
Because the build processes are identical (as is the information contained herein), this file should be kept in sync as
much as possible with its [counterpart in the Tendermint Core repo](https://github.com/tendermint/tendermint/blob/master/docs/DOCS_README.md).
### Update and Build the RPC docs
1. Execute the following command at the root directory to install the swagger-ui generate tool.
```bash
make tools
```
2. Edit API docs
1. Directly Edit API docs manually: `client/lcd/swagger-ui/swagger.yaml`.
2. Edit API docs within the [Swagger Editor](https://editor.swagger.io/). Please refer to this [document](https://swagger.io/docs/specification/2-0/basic-structure/) for the correct structure in `.yaml`.
3. Download `swagger.yaml` and replace the old `swagger.yaml` under fold `client/lcd/swagger-ui`.
4. Compile gaiacli
```bash
make install
```

112
docs/README.md
View File

@ -1,81 +1,57 @@
<!--
layout: homepage
title: Cosmos SDK Documentation
description: Cosmos SDK is the world’s most popular framework for building application-specific blockchains.
sections:
- title: Introduction
desc: High-level overview of the Cosmos SDK.
url: /intro/overview.html
icon: introduction
- title: Basics
desc: Anatomy of a blockchain, transaction lifecycle, accounts and more.
icon: basics
url: /basics/app-anatomy.html
- title: Core Concepts
desc: Read about the core concepts like baseapp, the store, or the server.
icon: core
url: /core/baseapp.html
- title: Building Modules
desc: Discover how to build modules for the Cosmos SDK.
icon: modules
url: /building-modules/intro.html
- title: Running a Node
desc: Running and interacting with nodes using the CLI and API.
icon: interfaces
url: /run-node/
- title: Modules
desc: Explore existing modules to build your application with.
icon: specifications
url: /modules/
stack:
- title: Cosmos Hub
desc: The first of thousands of interconnected blockchains on the Cosmos Network.
color: "#BA3FD9"
label: hub
url: http://hub.cosmos.network
- title: Tendermint Core
desc: The leading BFT engine for building blockchains, powering Cosmos SDK.
color: "#00BB00"
label: core
url: http://docs.tendermint.com
footer:
newsletter: false
aside: false
-->
# Updating the docs
# Cosmos SDK Documentation
If you want to open a PR in Cosmos SDK to update the documentation, please follow the guidelines in [`CONTRIBUTING.md`](https://github.com/cosmos/cosmos-sdk/tree/main/CONTRIBUTING.md#updating-documentation).
## Get Started
## Docs Build Workflow
* **[Cosmos SDK Intro](./intro/overview.md)**: High-level overview of the Cosmos SDK.
* **[Ignite CLI](https://docs.ignite.com)**: 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.
The documentation for Cosmos SDK is hosted at https://docs.cosmos.network and built from the files in the `/docs` directory.
It is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
## Reference Docs
### How It Works
* **[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](https://ibc.cosmos.network/)**: 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.
There is a GitHub Action listening for changes in the `/docs` directory for the `main` branch and each supported version branch (e.g. `release/v0.46.x`). Any updates to files in the `/docs` directory will automatically trigger a website deployment. Under the hood, the private website repository has a `make build-docs` target consumed by a Github Action within that repository.
## Other Resources
## README
* **[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://pkg.go.dev/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.
The [README.md](./README.md) is both the README for the repository and the configuration for the layout of the landing page.
## Cosmos Hub
## Links
The Cosmos Hub (`gaia`) docs have moved to [github.com/cosmos/gaia](https://github.com/cosmos/gaia/tree/main/docs).
**NOTE:** Strongly consider the existing links - both within this directory
and to the website docs - when moving or deleting files.
## Languages
Relative links should be used nearly everywhere, due to versionning.
Note that in case of page reshufling, you must update all links references.
The Cosmos SDK is written in [Golang](https://golang.org/), though the framework could be implemented similarly in other languages. Contact us for information about funding an implementation in another language.
### Full
## Contribute
The full GitHub URL to a file or directory. Used occasionally when it makes sense
to send users to the GitHub.
See the [DOCS_README.md](https://github.com/cosmos/cosmos-sdk/blob/main/docs/DOCS_README.md) for details of the build process and considerations when making changes.
## Building Locally
Make sure you are in the `docs` directory and run the following commands:
```sh
rm -rf node_modules
```
This command will remove old version of the visual theme and required packages. This step is optional.
```sh
npm install
```
Install the theme and all dependencies.
```sh
npm start
```
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:3000).
To build documentation as a static website run `npm run build`.
## Search
We are using [Algolia](https://www.algolia.com) to power full-text search. This uses a public API search-only key in the `config.js` as well as a [cosmos_network.json](https://github.com/algolia/docsearch-configs/blob/master/configs/cosmos_network.json) configuration file that we can update with PRs.

4
docs/architecture/README.md
View File

@ -1,7 +1,5 @@
---
order: false
parent:
order: false
sidebar_position: 1
---
# Architecture Decision Records (ADR)

5
docs/architecture/_category_.json Normal file
View File

@ -0,0 +1,5 @@
{
"label": "ADRs",
"position": 10,
"link": null
}

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

@ -12,10 +12,10 @@ Accepted
This ADR is a continuation of the motivation, design, and context established in
[ADR 019](./adr-019-protobuf-state-encoding.md) and
[ARD 020](./adr-019-protobuf-transaction-encoding.md), namely, we aim to design the
[ADR 020](./adr-020-protobuf-transaction-encoding.md), namely, we aim to design the
Protocol Buffer migration path for the client-side of the Cosmos SDK.
This ADR continues from [ARD 020](./adr-020-protobuf-transaction-encoding.md)
This ADR continues from [ADD 020](./adr-020-protobuf-transaction-encoding.md)
to specify the encoding of queries.
## Decision

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

@ -20,7 +20,7 @@ service definitions defined in [ADR 021](./adr-021-protobuf-query-encoding.md) a
## Context
In the current Cosmos SDK documentation on the [Object-Capability Model](../core/ocap.md), it is stated that:
In the current Cosmos SDK documentation on the [Object-Capability Model](../core/10-ocap.md), it is stated that:
> We assume that a thriving ecosystem of Cosmos SDK modules that are easy to compose into a blockchain application will contain faulty or malicious modules.
@ -397,4 +397,4 @@ replacing `Keeper` interfaces altogether.
* [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)
* [Object-Capability Model](https://docs.network.com/main/core/ocap)

3
docs/babel.config.js Normal file
View File

@ -0,0 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};

17
docs/basics/README.md
View File

@ -1,17 +0,0 @@
<!--
order: false
parent:
order: 2
-->
# Basics
This repository contains reference documentation on the basic concepts of the Cosmos SDK.
1. [Anatomy of a Cosmos SDK Application](./app-anatomy.md)
2. [Lifecycle of a transaction](./tx-lifecycle.md)
3. [Lifecycle of a query](./query-lifecycle.md)
4. [Accounts](./accounts.md)
5. [Gas and Fees](./gas-fees.md)
After reading the basics, head on to the [Core Reference](../core/README.md) for more advanced material.

12
docs/building-apps/README.md
View File

@ -1,12 +0,0 @@
<!--
order: false
parent:
order: 5
-->
# Building Apps
This repository contains documentation on concepts developers need to know in order to build a Cosmos SDK applications.
1. [Overview of `app.go` and how to wire it up](./app-go.md)
2. [Dependency Injection in the SDK](./depinject.md)

23
docs/building-modules/README.md
View File

@ -1,23 +0,0 @@
<!--
order: false
parent:
order: 4
-->
# Building Modules
This repository contains documentation on concepts developers need to know in order to build modules for Cosmos SDK applications.
1. [Introduction to Cosmos SDK Modules](./intro.md)
2. [`AppModule` Interface and Module Manager](./module-manager.md)
3. [Messages and Queries](./messages-and-queries.md)
4. [`Msg` services - Processing Messages](./msg-services.md)
5. [Query Services - Processing Queries](./query-services.md)
6. [BeginBlocker and EndBlocker](./beginblock-endblock.md)
7. [`Keeper`s](./keeper.md)
8. [Invariants](./invariants.md)
9. [Genesis](./genesis.md)
10. [Module Interfaces](./module-interfaces.md)
11. [Standard Module Structure](./structure.md)
12. [Errors](./errors.md)
13. [In-Place Store Migrations](./upgrade.md)

28
docs/core/README.md
View File

@ -1,28 +0,0 @@
<!--
order: false
parent:
order: 3
-->
# Core Concepts
This repository contains reference documentation on the core concepts of the Cosmos SDK.
1. [`BaseApp`](./baseapp.md)
2. [Transaction](./transactions.md)
3. [Context](./context.md)
4. [Node Client](./node.md)
5. [Store](./store.md)
6. [Encoding](./encoding.md)
7. [gRPC, REST and Tendermint Endpoints](./grpc_rest.md)
8. [Command-Line Interface](./cli.md)
9. [Events](./events.md)
10. [Telemetry](./telemetry.md)
11. [Object-Capabilities](./ocap.md)
12. [RunTx recovery middleware](./runtx_middleware.md)
13. [Simulation](./simulation.md)
14. [Protobuf documentation](./proto-docs.md)
15. [In-Place Store Migrations](./upgrade.md)
After reading about the core concepts, check the [IBC documentation](../ibc/README.md) to learn more
about the IBC core concepts and how to integrate IBC in your application.

37
docs/docs/README.md Normal file
View File

@ -0,0 +1,37 @@
---
title: Cosmos SDK Documentation
sidebar_position: 0
---
Cosmos SDK is the world’s most popular framework for building application-specific blockchains.
## Getting Started
Read all about the SDK or dive straight into the code with tutorials.
* [**Introductions to the Cosmos SDK**](./intro/00-overview.md) - Learn about all the parts of the Cosmos SDK.
* [**SDK Tutorials**](https://tutorials.cosmos.network) - Build a complete blockchain application from scratch.
## Explore the SDK
Get familiar with the SDK and explore its main concepts.
* [**Introduction**](./intro/00-overview.md) - High-level overview of the Cosmos SDK.
* [**Basics**](./basics/00-app-anatomy.md) - Anatomy of a blockchain, transaction lifecycle, accounts and more.
* [**Core Concepts**](./core/00-baseapp.md) - Read about the core concepts like baseapp, the store, or the server.
* [**Building Modules**](./building-modules/01-intro.md) - Discover how to build modules for the Cosmos SDK.
* [**Running a Node**](./run-node/00-keyring.md) - Running and interacting with nodes using the CLI and API.
* [**Modules**](./modules/README.md) - Explore existing modules to build your application with.
## Explore the Stack
Check out the docs for the various parts of the Cosmos stack.
* [**Cosmos Hub**](https://hub.cosmos.network) - The first of thousands of interconnected blockchains on the Cosmos Network.
* [**Tendermint Core**](https://docs.tendermint.com) - The leading BFT engine for building blockchains, powering Cosmos SDK.
## Help & Support
* [**Discord**](https://discord.gg/cosmosnetwork) - Chat with Cosmos developers on Discord.
* [**GitHub Discussions**](https://github.com/cosmos/cosmos-sdk/discussions) - Ask questions and discuss SDK development on GitHub.
* [**Found an issue?**](https://github.com/cosmos/cosmos-sdk/edit/main/docs/docs/README.md) - Help us improve this page by suggesting edits on GitHub.

80
docs/basics/app-anatomy.md → docs/docs/basics/00-app-anatomy.md
View File

@ -1,14 +1,16 @@
<!--
order: 1
-->
---
sidebar_position: 1
---
# Anatomy of a Cosmos SDK Application
This document describes the core parts of a Cosmos SDK application. Throughout the document, a placeholder application named `app` will be used. {synopsis}
:::note Synopsis
This document describes the core parts of a Cosmos SDK application. Throughout the document, a placeholder application named `app` will be used.
:::
## Node Client
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.
The Daemon, or [Full-Node Client](../core/03-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
^ +-------------------------------+ ^
@ -28,9 +30,9 @@ Blockchain Node | | Consensus | |
v +-------------------------------+ v
```
The blockchain full-node presents itself as a binary, generally suffixed by `-d` for "daemon" (e.g. `appd` for `app` or `gaiad` for `gaia`). This binary is built by running a simple [`main.go`](../core/node.md#main-function) function placed in `./cmd/appd/`. This operation usually happens through the [Makefile](#dependencies-and-makefile).
The blockchain full-node presents itself as a binary, generally suffixed by `-d` for "daemon" (e.g. `appd` for `app` or `gaiad` for `gaia`). This binary is built by running a simple [`main.go`](../core/03-node.md#main-function) function placed in `./cmd/appd/`. This operation usually happens through the [Makefile](#dependencies-and-makefile).
Once the main binary is built, the node can be started by running the [`start` command](../core/node.md#start-command). This command function primarily does three things:
Once the main binary is built, the node can be started by running the [`start` command](../core/03-node.md#start-command). This command function primarily does three things:
1. Create an instance of the state-machine defined in [`app.go`](#core-application-file).
2. Initialize the state-machine with the latest known state, extracted from the `db` stored in the `~/.app/data` folder. At this point, the state-machine is at height `appBlockHeight`.
@ -44,12 +46,12 @@ 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://docs.tendermint.com/master/spec/abci/abci.html) 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/00-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://docs.tendermint.com/master/spec/abci/abci.html) and the [routing logic](../core/00-baseapp.md#routing).
* **A list of store keys**. The [store](../core/04-store.md), which contains the entire state, is implemented as a [`multistore`](../core/04-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/10-ocap.md) of the Cosmos SDK.
* **A list of module's `keeper`s.** Each module defines an abstraction called [`keeper`](../building-modules/06-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/05-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/05-encoding.md).
* **A reference to a [`legacyAmino`](../core/05-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/01-module-manager.md#manager)** and a [basic module manager](../building-modules/01-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/00-baseapp.md#msg-services) and [gRPC `Query` service](../core/00-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:
@ -57,23 +59,23 @@ See an example of application type definition from `simapp`, the Cosmos SDK's ow
### 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.
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/03-node.md#start-command) of the application's daemon command.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/server/types/app.go#L57-L59
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 [`codec`](../core/05-encoding.md) and initialize the `codec` of each of the application's module using the [basic manager](../building-modules/01-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.
* Instantiate the application's [module manager](../building-modules/01-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/00-baseapp.md#msg-services), [gRPC `Query` services](../core/00-baseapp.md#grpc-query-services), [legacy `Msg` routes](../core/00-baseapp.md#routing) and [legacy query routes](../core/00-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/07-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/07-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.
* [`anteHandler`](../core/00-baseapp.md#antehandler): used to handle fees and signature verification.
* Mount the stores.
* Return the application.
@ -87,7 +89,7 @@ See an example of application constructor from `simapp`:
The `InitChainer` is a function that initializes the state of the application from a genesis file (i.e. token balances of genesis accounts). It is called when the application receives the `InitChain` message from the Tendermint engine, which happens when the node is started at `appBlockHeight == 0` (i.e. on genesis). The application must set the `InitChainer` in its [constructor](#constructor-function) via the [`SetInitChainer`](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetInitChainer) method.
In general, the `InitChainer` is mostly composed of the [`InitGenesis`](../building-modules/genesis.md#initgenesis) function of each of the application's modules. This is done by calling the `InitGenesis` function of the module manager, which in turn will call the `InitGenesis` function of each of the modules it contains. Note that the order in which the modules' `InitGenesis` functions must be called has to be set in the module manager using the [module manager's](../building-modules/module-manager.md) `SetOrderInitGenesis` method. This is done in the [application's constructor](#application-constructor), and the `SetOrderInitGenesis` has to be called before the `SetInitChainer`.
In general, the `InitChainer` is mostly composed of the [`InitGenesis`](../building-modules/08-genesis.md#initgenesis) function of each of the application's modules. This is done by calling the `InitGenesis` function of the module manager, which in turn will call the `InitGenesis` function of each of the modules it contains. Note that the order in which the modules' `InitGenesis` functions must be called has to be set in the module manager using the [module manager's](../building-modules/01-module-manager.md) `SetOrderInitGenesis` method. This is done in the [application's constructor](#application-constructor), and the `SetOrderInitGenesis` has to be called before the `SetInitChainer`.
See an example of an `InitChainer` from `simapp`:
@ -97,9 +99,9 @@ See an example of an `InitChainer` from `simapp`:
The Cosmos SDK offers developers the possibility to implement automatic execution of code as part of their application. This is implemented through two function called `BeginBlocker` and `EndBlocker`. They are called when the application receives respectively the `BeginBlock` and `EndBlock` messages from the Tendermint engine, which happens at the beginning and at the end of each block. The application must set the `BeginBlocker` and `EndBlocker` in its [constructor](#constructor-function) via the [`SetBeginBlocker`](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetBeginBlocker) and [`SetEndBlocker`](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetEndBlocker) methods.
In general, the `BeginBlocker` and `EndBlocker` functions are mostly composed of the [`BeginBlock` and `EndBlock`](../building-modules/beginblock-endblock.md) functions of each of the application's modules. This is done by calling the `BeginBlock` and `EndBlock` functions of the module manager, which in turn will call the `BeginBlock` and `EndBlock` functions of each of the modules it contains. Note that the order in which the modules' `BeginBlock` and `EndBlock` functions must be called has to be set in the module manager using the `SetOrderBeginBlockers` and `SetOrderEndBlockers` methods respectively. This is done via the [module manager](../building-modules/module-manager.md) in the [application's constructor](#application-constructor), and the `SetOrderBeginBlockers` and `SetOrderEndBlockers` methods have to be called before the `SetBeginBlocker` and `SetEndBlocker` functions.
In general, the `BeginBlocker` and `EndBlocker` functions are mostly composed of the [`BeginBlock` and `EndBlock`](../building-modules/05-beginblock-endblock.md) functions of each of the application's modules. This is done by calling the `BeginBlock` and `EndBlock` functions of the module manager, which in turn will call the `BeginBlock` and `EndBlock` functions of each of the modules it contains. Note that the order in which the modules' `BeginBlock` and `EndBlock` functions must be called has to be set in the module manager using the `SetOrderBeginBlockers` and `SetOrderEndBlockers` methods respectively. This is done via the [module manager](../building-modules/01-module-manager.md) in the [application's constructor](#application-constructor), and the `SetOrderBeginBlockers` and `SetOrderEndBlockers` methods have to be called before the `SetBeginBlocker` and `SetEndBlocker` functions.
As a sidenote, it is important to remember that application-specific blockchains are deterministic. Developers must be careful not to introduce non-determinism in `BeginBlocker` or `EndBlocker`, and must also be careful not to make them too computationally expensive, as [gas](./gas-fees.md) does not constrain the cost of `BeginBlocker` and `EndBlocker` execution.
As a sidenote, it is important to remember that application-specific blockchains are deterministic. Developers must be careful not to introduce non-determinism in `BeginBlocker` or `EndBlocker`, and must also be careful not to make them too computationally expensive, as [gas](./04-gas-fees.md) does not constrain the cost of `BeginBlocker` and `EndBlocker` execution.
See an example of `BeginBlocker` and `EndBlocker` functions from `simapp`
@ -114,10 +116,10 @@ The `EncodingConfig` structure is the last important part of the `app.go` file.
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).
* You can read more about Any in [ADR-19](../architecture/adr-019-protobuf-state-encoding.md).
* To go more into details, the Cosmos SDK uses an implementation of the Protobuf specification called [`gogoprotobuf`](https://github.com/cosmos/gogoproto). By default, the [gogo protobuf implementation of `Any`](https://pkg.go.dev/github.com/cosmos/gogoproto/types) uses [global type registration](https://github.com/cosmos/gogoproto/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 register 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).
* `Codec`: 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 `Codec`.
* `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).
* `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/01-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 `Codec`.
@ -130,28 +132,28 @@ See an example of a `MakeTestEncodingConfig` from `simapp`:
## Modules
[Modules](../building-modules/intro.md) are the heart and soul of Cosmos SDK applications. They can be considered as state-machines nested within the state-machine. When a transaction is relayed from the underlying Tendermint engine via the ABCI to the application, it is routed by [`baseapp`](../core/baseapp.md) to the appropriate module in order to be processed. This paradigm enables developers to easily build complex state-machines, as most of the modules they need often already exist. **For developers, most of the work involved in building a Cosmos SDK application revolves around building custom modules required by their application that do not exist yet, and integrating them with modules that do already exist into one coherent application**. In the application directory, the standard practice is to store modules in the `x/` folder (not to be confused with the Cosmos SDK's `x/` folder, which contains already-built modules).
[Modules](../building-modules/01-intro.md) are the heart and soul of Cosmos SDK applications. They can be considered as state-machines nested within the state-machine. When a transaction is relayed from the underlying Tendermint engine via the ABCI to the application, it is routed by [`baseapp`](../core/00-baseapp.md) to the appropriate module in order to be processed. This paradigm enables developers to easily build complex state-machines, as most of the modules they need often already exist. **For developers, most of the work involved in building a Cosmos SDK application revolves around building custom modules required by their application that do not exist yet, and integrating them with modules that do already exist into one coherent application**. In the application directory, the standard practice is to store modules in the `x/` folder (not to be confused with the Cosmos SDK's `x/` folder, which contains already-built modules).
### Application Module Interface
Modules must implement [interfaces](../building-modules/module-manager.md#application-module-interfaces) defined in the Cosmos SDK, [`AppModuleBasic`](../building-modules/module-manager.md#appmodulebasic) and [`AppModule`](../building-modules/module-manager.md#appmodule). The former implements basic non-dependent elements of the module, such as the `codec`, while the latter handles the bulk of the module methods (including methods that require references to other modules' `keeper`s). Both the `AppModule` and `AppModuleBasic` types are, by convention, defined in a file called `module.go`.
Modules must implement [interfaces](../building-modules/01-module-manager.md#application-module-interfaces) defined in the Cosmos SDK, [`AppModuleBasic`](../building-modules/01-module-manager.md#appmodulebasic) and [`AppModule`](../building-modules/01-module-manager.md#appmodule). The former implements basic non-dependent elements of the module, such as the `codec`, while the latter handles the bulk of the module methods (including methods that require references to other modules' `keeper`s). Both the `AppModule` and `AppModuleBasic` types are, by convention, defined in a file called `module.go`.
`AppModule` exposes a collection of useful methods on the module that facilitates the composition of modules into a coherent application. These methods are called from the [`module manager`](../building-modules/module-manager.md#manager), which manages the application's collection of modules.
`AppModule` exposes a collection of useful methods on the module that facilitates the composition of modules into a coherent application. These methods are called from the [`module manager`](../building-modules/01-module-manager.md#manager), which manages the application's collection of modules.
### `Msg` Services
Each module defines two [Protobuf services](https://developers.google.com/protocol-buffers/docs/proto#services): one `Msg` service to handle messages, and one gRPC `Query` service to handle queries. If we consider the module as a state-machine, then a `Msg` service is a set of state transition RPC methods.
Each Protobuf `Msg` service method is 1:1 related to a Protobuf request type, which must implement `sdk.Msg` interface.
Note that `sdk.Msg`s are bundled in [transactions](../core/transactions.md), and each transaction contains one or multiple messages.
Note that `sdk.Msg`s are bundled in [transactions](../core/01-transactions.md), and each transaction contains one or multiple messages.
When a valid block of transactions is received by the full-node, Tendermint relays each one to the application via [`DeliverTx`](https://docs.tendermint.com/master/spec/abci/apps.html#delivertx). Then, the application handles the transaction:
1. Upon receiving the transaction, the application first unmarshalls it from `[]byte`.
2. Then, it verifies a few things about the transaction like [fee payment and signatures](./gas-fees.md#antehandler) before extracting the `Msg`(s) contained in the transaction.
2. Then, it verifies a few things about the transaction like [fee payment and signatures](./04-gas-fees.md#antehandler) before extracting the `Msg`(s) contained in the transaction.
3. `sdk.Msg`s are encoded using Protobuf [`Any`s](#register-codec). By analyzing each `Any`'s `type_url`, baseapp's `msgServiceRouter` routes the `sdk.Msg` to the corresponding module's `Msg` service.
4. If the message is successfully processed, the state is updated.
For a more details look at a transaction [lifecycle](./tx-lifecycle.md).
For a more details look at a transaction [lifecycle](./01-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:
@ -163,7 +165,7 @@ Each module should also implement the `RegisterServices` method as part of the [
### gRPC `Query` Services
gRPC `Query` services allows users to query the state using [gRPC](https://grpc.io). They are enabled by default, and can be configured under the `grpc.enable` and `grpc.address` fields inside [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml).
gRPC `Query` services allows users to query the state using [gRPC](https://grpc.io). They are enabled by default, and can be configured under the `grpc.enable` and `grpc.address` fields inside [`app.toml`](../run-node/02-interact-node.md#configuring-the-node-using-apptoml).
gRPC `Query` services are defined in the module's Protobuf definition files, specifically inside `query.proto`. The `query.proto` definition file exposes a single `Query` [Protobuf service](https://developers.google.com/protocol-buffers/docs/proto#services). Each gRPC query endpoint corresponds to a service method, starting with the `rpc` keyword, inside the `Query` service.
@ -173,7 +175,7 @@ Finally, each module should also implement the `RegisterServices` method as part
### Keeper
[`Keepers`](../building-modules/keeper.md) are the gatekeepers of their module's store(s). To read or write in a module's store, it is mandatory to go through one of its `keeper`'s methods. This is ensured by the [object-capabilities](../core/ocap.md) model of the Cosmos SDK. Only objects that hold the key to a store can access it, and only the module's `keeper` should hold the key(s) to the module's store(s).
[`Keepers`](../building-modules/06-keeper.md) are the gatekeepers of their module's store(s). To read or write in a module's store, it is mandatory to go through one of its `keeper`'s methods. This is ensured by the [object-capabilities](../core/10-ocap.md) model of the Cosmos SDK. Only objects that hold the key to a store can access it, and only the module's `keeper` should hold the key(s) to the module's store(s).
`Keepers` are generally defined in a file called `keeper.go`. It contains the `keeper`'s type definition and methods.
@ -191,10 +193,10 @@ Each module defines command-line commands, gRPC services and REST routes to be e
#### CLI
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):
Generally, the [commands related to a module](../building-modules/09-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.
* Queries let users query the subset of the state defined by the module. Query commands forward queries to the [application's query router](../core/00-baseapp.md#query-routing), which routes them to the appropriate [querier](#querier) the `queryRoute` parameter supplied.
#### gRPC
@ -211,13 +213,13 @@ Some external clients may not wish to use gRPC. The Cosmos SDK provides in this
The REST endpoints are defined in the Protobuf files, along with the gRPC services, using Protobuf annotations. Modules that want to expose REST queries should add `google.api.http` annotations to their `rpc` methods. By default, all REST endpoints defined in the SDK have an URL starting with the `/cosmos/` prefix.
The Cosmos SDK also provides a development endpoint to generate [Swagger](https://swagger.io/) definition files for these REST endpoints. This endpoint can be enabled inside the [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml) config file, under the `api.swagger` key.
The Cosmos SDK also provides a development endpoint to generate [Swagger](https://swagger.io/) definition files for these REST endpoints. This endpoint can be enabled inside the [`app.toml`](../run-node/01-run-node.md#configuring-the-node-using-apptoml) config file, under the `api.swagger` key.
## Application Interface
[Interfaces](#command-line-grpc-services-and-rest-interfaces) let end-users interact with full-node clients. This means querying data from the full-node or creating and sending new transactions to be relayed by the full-node and eventually included in a block.
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:
The main interface is the [Command-Line Interface](../core/07-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.
@ -229,7 +231,7 @@ See an example of an application's main command-line file from the [Cosmos Hub](
## Dependencies and Makefile
::: warning
:::warning
A patch introduced in `go-grpc v1.34.0` made gRPC incompatible with the `gogoproto` library, making some [gRPC queries](https://github.com/cosmos/cosmos-sdk/issues/8426) panic. As such, the Cosmos SDK requires that `go-grpc <=v1.33.2` is installed in your `go.mod`.
To make sure that gRPC is working properly, it is **highly recommended** to add the following line in your application's `go.mod`:
@ -250,7 +252,3 @@ Below, the `go.mod` of the [Cosmos Hub](https://github.com/cosmos/gaia) is provi
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).
Here is an example of the [Cosmos Hub Makefile](https://github.com/cosmos/gaia/blob/Theta-main/Makefile).
## Next {hide}
Learn more about the [Lifecycle of a transaction](./tx-lifecycle.md) {hide}

62
docs/basics/tx-lifecycle.md → docs/docs/basics/01-tx-lifecycle.md
View File

@ -1,20 +1,24 @@
<!--
order: 2
-->
---
sidebar_position: 1
---
# Transaction Lifecycle
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}
:::note Synopsis
This document describes the lifecycle of a transaction from creation to committed state changes. Transaction definition is described in a [different doc](../core/01-transactions.md). The transaction will be referred to as `Tx`.
:::
## Pre-requisite Readings
:::note
### Pre-requisite Readings
* [Anatomy of a Cosmos SDK Application](./app-anatomy.md) {prereq}
* [Anatomy of a Cosmos SDK Application](./00-app-anatomy.md)
:::
## Creation
### Transaction Creation
One of the main application interfaces is the command-line interface. The transaction `Tx` can be created by the user inputting a command in the following format from the [command-line](../core/cli.md), providing the type of transaction in `[command]`, arguments in `[args]`, and configurations such as gas prices in `[flags]`:
One of the main application interfaces is the command-line interface. The transaction `Tx` can be created by the user inputting a command in the following format from the [command-line](../core/07-cli.md), providing the type of transaction in `[command]`, arguments in `[args]`, and configurations such as gas prices in `[flags]`:
```bash
[appname] tx [command] [args] [flags]
@ -22,13 +26,13 @@ One of the main application interfaces is the command-line interface. The transa
This command will automatically **create** the transaction, **sign** it using the account's private key, and **broadcast** it to the specified peer node.
There are several required and optional flags for transaction creation. The `--from` flag specifies which [account](./accounts.md) the transaction is originating from. For example, if the transaction is sending coins, the funds will be drawn from the specified `from` address.
There are several required and optional flags for transaction creation. The `--from` flag specifies which [account](./03-accounts.md) the transaction is originating from. For example, if the transaction is sending coins, the funds will be drawn from the specified `from` address.
#### Gas and Fees
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):
Additionally, there are several [flags](../core/07-cli.md) users can use to indicate how much they are willing to pay in [fees](./04-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` refers to how much [gas](./04-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 to 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.
@ -48,7 +52,7 @@ appd tx send <recipientAddress> 1000uatom --from <senderAddress> --gas auto --ga
#### Other Transaction Creation Methods
The command-line is an easy way to interact with an application, but `Tx` can also be created using a [gRPC or REST interface](../core/grpc_rest.md) or some other entry point defined by the application developer. From the user's perspective, the interaction depends on the web interface or wallet they are using (e.g. creating `Tx` using [Lunie.io](https://lunie.io/#/) and signing it with a Ledger Nano S).
The command-line is an easy way to interact with an application, but `Tx` can also be created using a [gRPC or REST interface](../core/06-grpc_rest.md) or some other entry point defined by the application developer. From the user's perspective, the interaction depends on the web interface or wallet they are using (e.g. creating `Tx` using [Lunie.io](https://lunie.io/#/) and signing it with a Ledger Nano S).
## Addition to Mempool
@ -68,7 +72,7 @@ are not empty, enforcing nonnegative numbers, and other logic specified in the d
**_Stateful_** checks validate transactions and messages based on a committed state. Examples
include checking that the relevant values exist and can be transacted with, the address
has sufficient funds, and the sender is authorized or has the correct ownership to transact.
At any given moment, full-nodes typically have [multiple versions](../core/baseapp.md#state-updates)
At any given moment, full-nodes typically have [multiple versions](../core/00-baseapp.md#state-updates)
of the application's internal state for different purposes. For example, nodes will execute state
changes while in the process of verifying transactions, but still need a copy of the last committed
state in order to answer queries - they should not respond using state with uncommitted changes.
@ -79,12 +83,12 @@ through several steps, beginning with decoding `Tx`.
### Decoding
When `Tx` is received by the application from the underlying consensus engine (e.g. Tendermint), it is still in its [encoded](../core/encoding.md) `[]byte` form and needs to be unmarshaled in order to be processed. Then, the [`runTx`](../core/baseapp.md#runtx-antehandler-runmsgs-posthandler) function is called to run in `runTxModeCheck` mode, meaning the function will run all checks but exit before executing messages and writing state changes.
When `Tx` is received by the application from the underlying consensus engine (e.g. Tendermint), it is still in its [encoded](../core/05-encoding.md) `[]byte` form and needs to be unmarshaled in order to be processed. Then, the [`runTx`](../core/00-baseapp.md#runtx-antehandler-runmsgs-posthandler) function is called to run in `runTxModeCheck` mode, meaning the function will run all checks but exit before executing messages and writing state changes.
### ValidateBasic
Messages ([`sdk.Msg`](../core/transactions.md#messages)) are extracted from transactions (`Tx`). The `ValidateBasic` method of the `sdk.Msg` interface implemented by the module developer is run for each transaction.
To discard obviously invalid messages, the `BaseApp` type calls the `ValidateBasic` method very early in the processing of the message in the [`CheckTx`](../core/baseapp.md#checktx) and [`DeliverTx`](../core/baseapp.md#delivertx) transactions.
Messages ([`sdk.Msg`](../core/01-transactions.md#messages)) are extracted from transactions (`Tx`). The `ValidateBasic` method of the `sdk.Msg` interface implemented by the module developer is run for each transaction.
To discard obviously invalid messages, the `BaseApp` type calls the `ValidateBasic` method very early in the processing of the message in the [`CheckTx`](../core/00-baseapp.md#checktx) and [`DeliverTx`](../core/00-baseapp.md#delivertx) transactions.
`ValidateBasic` can include only **stateless** checks (the checks that do not require access to the state).
#### Guideline
@ -94,7 +98,7 @@ Other validation operations must be performed when [handling a message](../build
Example, if the message is to send coins from one address to another, `ValidateBasic` likely checks for non-empty addresses and a non-negative coin amount, but does not require knowledge of state such as the account balance of an address.
See also [Msg Service Validation](../building-modules/msg-services.md#Validation).
See also [Msg Service Validation](../building-modules/03-msg-services.md#Validation).
### AnteHandler
@ -106,7 +110,7 @@ For example, the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth/
### Gas
The [`Context`](../core/context.md), which keeps a `GasMeter` that will track how much gas has been used during the execution of `Tx`, is initialized. The user-provided amount of gas for `Tx` is known as `GasWanted`. If `GasConsumed`, the amount of gas consumed so during execution, ever exceeds `GasWanted`, the execution will stop and the changes made to the cached copy of the state won't be committed. Otherwise, `CheckTx` sets `GasUsed` equal to `GasConsumed` and returns it in the result. After calculating the gas and fee values, validator-nodes check that the user-specified `gas-prices` is greater than their locally defined `min-gas-prices`.
The [`Context`](../core/02-context.md), which keeps a `GasMeter` that will track how much gas has been used during the execution of `Tx`, is initialized. The user-provided amount of gas for `Tx` is known as `GasWanted`. If `GasConsumed`, the amount of gas consumed so during execution, ever exceeds `GasWanted`, the execution will stop and the changes made to the cached copy of the state won't be committed. Otherwise, `CheckTx` sets `GasUsed` equal to `GasConsumed` and returns it in the result. After calculating the gas and fee values, validator-nodes check that the user-specified `gas-prices` is greater than their locally defined `min-gas-prices`.
### Discard or Addition to Mempool
@ -148,8 +152,8 @@ must be in this proposer's mempool.
The next step of consensus is to execute the transactions to fully validate them. All full-nodes
that receive a block proposal from the correct proposer execute the transactions by calling the ABCI functions
[`BeginBlock`](./app-anatomy.md#beginblocker-and-endblocker), `DeliverTx` for each transaction,
and [`EndBlock`](./app-anatomy.md#beginblocker-and-endblocker). While each full-node runs everything
[`BeginBlock`](./00-app-anatomy.md#beginblocker-and-endblocker), `DeliverTx` for each transaction,
and [`EndBlock`](./00-app-anatomy.md#beginblocker-and-endblocker). While each full-node runs everything
locally, this process yields a single, unambiguous result, since the messages' state transitions are deterministic and transactions are
explicitly ordered in the block proposal.
@ -192,10 +196,10 @@ explicitly ordered in the block proposal.
### DeliverTx
The `DeliverTx` ABCI function defined in [`BaseApp`](../core/baseapp.md) does the bulk of the
The `DeliverTx` ABCI function defined in [`BaseApp`](../core/00-baseapp.md) does the bulk of the
state transitions: it is run for each transaction in the block in sequential order as committed
to during consensus. Under the hood, `DeliverTx` is almost identical to `CheckTx` but calls the
[`runTx`](../core/baseapp.md#runtx) function in deliver mode instead of check mode.
[`runTx`](../core/00-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.
@ -208,14 +212,14 @@ Instead of using their `checkState`, full-nodes use `deliverState`:
to each node - differing values across nodes would yield nondeterministic results.
* **`MsgServiceRouter`:** While `CheckTx` would have exited, `DeliverTx` continues to run
[`runMsgs`](../core/baseapp.md#runtx-antehandler-runmsgs-posthandler) to fully execute each `Msg` within the transaction.
[`runMsgs`](../core/00-baseapp.md#runtx-antehandler-runmsgs-posthandler) 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.
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/03-msg-services.md).
For `LegacyMsg` routing, the `Route` function is called via the [module manager](../building-modules/01-module-manager.md) to retrieve the route name and find the legacy [`Handler`](../building-modules/03-msg-services.md#handler-type) within the module.
* **`Msg` service:** Protobuf `Msg` service is responsible for executing each message in the `Tx` and causes state transitions to persist in `deliverTxState`.
* **PostHandlers:** [`PostHandler`](../core/baseapp.md#posthandler)s run after the execution of the message. If they fail, the state change of `runMsgs`, as well of `PostHandlers` are both reverted.
* **PostHandlers:** [`PostHandler`](../core/00-baseapp.md#posthandler)s run after the execution of the message. If they fail, the state change of `runMsgs`, as well of `PostHandlers` are both reverted.
* **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
@ -236,8 +240,8 @@ not they should commit the state changes.
When they receive enough validator votes (2/3+ _precommits_ weighted by voting power), full nodes commit to a new block to be added to the blockchain and
finalize the state transitions in the application layer. A new state root is generated to serve as
a merkle proof for the state transitions. Applications use the [`Commit`](../core/baseapp.md#commit)
ABCI method inherited from [Baseapp](../core/baseapp.md); it syncs all the state transitions by
a merkle proof for the state transitions. Applications use the [`Commit`](../core/00-baseapp.md#commit)
ABCI method inherited from [Baseapp](../core/00-baseapp.md); it syncs all the state transitions by
writing the `deliverState` into the application's internal state. As soon as the state changes are
committed, `checkState` start afresh from the most recently committed state and `deliverState`
resets to `nil` in order to be consistent and reflect the changes.
@ -251,7 +255,3 @@ excluding it from the block or a validator voting against the block.
At this point, the transaction lifecycle of a `Tx` is over: nodes have verified its validity,
delivered it by executing its state changes, and committed those changes. The `Tx` itself,
in `[]byte` form, is stored in a block and appended to the blockchain.
## Next {hide}
Learn about [accounts](./accounts.md) {hide}

53
docs/basics/query-lifecycle.md → docs/docs/basics/02-query-lifecycle.md
View File

@ -1,20 +1,25 @@
<!--
order: 3
-->
---
sidebar_position: 1
---
# Query Lifecycle
This document describes the lifecycle of a query in a Cosmos SDK application, from the user interface to application stores and back. {synopsis}
:::note Synopsis
This document describes the lifecycle of a query in a Cosmos SDK application, from the user interface to application stores and back.
:::
## Pre-requisite Readings
:::note
* [Transaction Lifecycle](./tx-lifecycle.md) {prereq}
### Pre-requisite Readings
* [Transaction Lifecycle](./01-tx-lifecycle.md)
:::
## Query Creation
A [**query**](../building-modules/messages-and-queries.md#queries) is a request for information made by end-users of applications through an interface and processed by a full-node. Users can query information about the network, the application itself, and application state directly from the application's stores or modules. Note that queries are different from [transactions](../core/transactions.md) (view the lifecycle [here](./tx-lifecycle.md)), particularly in that they do not require consensus to be processed (as they do not trigger state-transitions); they can be fully handled by one full-node.
A [**query**](../building-modules/02-messages-and-queries.md#queries) is a request for information made by end-users of applications through an interface and processed by a full-node. Users can query information about the network, the application itself, and application state directly from the application's stores or modules. Note that queries are different from [transactions](../core/01-transactions.md) (view the lifecycle [here](./01-tx-lifecycle.md)), particularly in that they do not require consensus to be processed (as they do not trigger state-transitions); they can be fully handled by one full-node.
For the purpose of explaining the query lifecycle, let's say `MyQuery` is requesting a list of delegations made by a certain delegator address in the application called `simapp`. As to be expected, the [`staking`](../../x/staking/spec/README.md) module handles this query. But first, there are a few ways `MyQuery` can be created by users.
For the purpose of explaining the query lifecycle, let's say `MyQuery` is requesting a list of delegations made by a certain delegator address in the application called `simapp`. As to be expected, the [`staking`](../modules/staking/README.md) module handles this query. But first, there are a few ways `MyQuery` can be created by users.
### CLI
@ -24,7 +29,7 @@ The main interface for an application is the command-line interface. Users conne
simd query staking delegations <delegatorAddress>
```
This query command was defined by the [`staking`](../../x/staking/spec/README.md) module developer and added to the list of subcommands by the application developer when creating the CLI.
This query command was defined by the [`staking`](../modules/staking/README.md) module developer and added to the list of subcommands by the application developer when creating the CLI.
Note that the general format is as follows:
@ -32,11 +37,11 @@ Note that the general format is as follows:
simd query [moduleName] [command] <arguments> --flag <flagArg>
```
To provide values such as `--node` (the full-node the CLI connects to), the user can use the [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml) config file to set them or provide them as flags.
To provide values such as `--node` (the full-node the CLI connects to), the user can use the [`app.toml`](../run-node/02-interact-node.md#configuring-the-node-using-apptoml) config file to set them or provide them as flags.
The CLI understands a specific set of commands, defined in a hierarchical structure by the application developer: from the [root command](../core/cli.md#root-command) (`simd`), the type of command (`Myquery`), the module that contains the command (`staking`), and command itself (`delegations`). Thus, the CLI knows exactly which module handles this command and directly passes the call there.
The CLI understands a specific set of commands, defined in a hierarchical structure by the application developer: from the [root command](../core/07-cli.md#root-command) (`simd`), the type of command (`Myquery`), the module that contains the command (`staking`), and command itself (`delegations`). Thus, the CLI knows exactly which module handles this command and directly passes the call there.
Another interface through which users can make queries is [gRPC](https://grpc.io) requests to a [gRPC server](../core/grpc_rest.md#grpc-server). The endpoints are defined as [Protocol Buffers](https://developers.google.com/protocol-buffers) service methods inside `.proto` files, written in Protobuf's own language-agnostic interface definition language (IDL). The Protobuf ecosystem developed tools for code-generation from `*.proto` files into various languages. These tools allow to build gRPC clients easily.
Another interface through which users can make queries is [gRPC](https://grpc.io) requests to a [gRPC server](../core/06-grpc_rest.md#grpc-server). The endpoints are defined as [Protocol Buffers](https://developers.google.com/protocol-buffers) service methods inside `.proto` files, written in Protobuf's own language-agnostic interface definition language (IDL). The Protobuf ecosystem developed tools for code-generation from `*.proto` files into various languages. These tools allow to build gRPC clients easily.
One such tool is [grpcurl](https://github.com/fullstorydev/grpcurl), and a gRPC request for `MyQuery` using this client looks like:
@ -52,7 +57,7 @@ grpcurl \
### REST
Another interface through which users can make queries is through HTTP Requests to a [REST server](../core/grpc_rest.md#rest-server). The REST server is fully auto-generated from Protobuf services, using [gRPC-gateway](https://github.com/grpc-ecosystem/grpc-gateway).
Another interface through which users can make queries is through HTTP Requests to a [REST server](../core/06-grpc_rest.md#rest-server). The REST server is fully auto-generated from Protobuf services, using [gRPC-gateway](https://github.com/grpc-ecosystem/grpc-gateway).
An example HTTP request for `MyQuery` looks like:
@ -68,10 +73,10 @@ 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.
* **Codec**: The [encoder/decoder](../core/05-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`](../modules/auth/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.
* **Keyring**: A [Key Manager](../basics/03-accounts.md#keyring) used to sign transactions and handle other operations with keys.
* **Output Writer**: A [Writer](https://pkg.go.dev/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.
@ -87,7 +92,7 @@ At this point in the lifecycle, the user has created a CLI command with all of t
#### Encoding
In our case (querying an address's delegations), `MyQuery` contains an [address](./accounts.md#addresses) `delegatorAddress` as its only argument. However, the request can only contain `[]byte`s, as it will be relayed to a consensus engine (e.g. Tendermint Core) of a full-node that has no inherent knowledge of the application types. Thus, the `codec` of `client.Context` is used to marshal the address.
In our case (querying an address's delegations), `MyQuery` contains an [address](./03-accounts.md#addresses) `delegatorAddress` as its only argument. However, the request can only contain `[]byte`s, as it will be relayed to a consensus engine (e.g. Tendermint Core) of a full-node that has no inherent knowledge of the application types. Thus, the `codec` of `client.Context` is used to marshal the address.
Here is what the code looks like for the CLI command:
@ -99,7 +104,7 @@ The Cosmos SDK leverages code generated from Protobuf services to make queries.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/staking/client/cli/query.go#L317-L341
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()`.
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/03-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:
@ -107,15 +112,15 @@ Here is what the code looks like:
## RPC
With a call to `ABCIQueryWithOptions()`, `MyQuery` is received by a [full-node](../core/encoding.md) which will then process the request. Note that, while the RPC is made to the consensus engine (e.g. Tendermint Core) of a full-node, queries are not part of consensus and will not be broadcasted to the rest of the network, as they do not require anything the network needs to agree upon.
With a call to `ABCIQueryWithOptions()`, `MyQuery` is received by a [full-node](../core/05-encoding.md) which will then process the request. Note that, while the RPC is made to the consensus engine (e.g. Tendermint Core) of a full-node, queries are not part of consensus and will not be broadcasted to the rest of the network, as they do not require anything the network needs to agree upon.
Read more about ABCI Clients and Tendermint RPC in the [Tendermint documentation](https://docs.tendermint.com/master/rpc/).
## Application Query Handling
When a query is received by the full-node after it has been relayed from the underlying consensus engine, it is now being handled within an environment that understands application-specific types and has a copy of the state. [`baseapp`](../core/baseapp.md) implements the ABCI [`Query()`](../core/baseapp.md#query) function and handles gRPC queries. The query route is parsed, and it matches the fully-qualified service method name of an existing service method (most likely in one of the modules), then `baseapp` will relay the request to the relevant module.
When a query is received by the full-node after it has been relayed from the underlying consensus engine, it is now being handled within an environment that understands application-specific types and has a copy of the state. [`baseapp`](../core/00-baseapp.md) implements the ABCI [`Query()`](../core/00-baseapp.md#query) function and handles gRPC queries. The query route is parsed, and it matches the fully-qualified service method name of an existing service method (most likely in one of the modules), then `baseapp` will relay the request to the relevant module.
Since `MyQuery` has a Protobuf fully-qualified service method name from the `staking` module (recall `/cosmos.staking.v1beta1.Query/Delegations`), `baseapp` first parses the path, then uses its own internal `GRPCQueryRouter` to retrieve the corresponding gRPC handler, and routes the query to the module. The gRPC handler is responsible for recognizing this query, retrieving the appropriate values from the application's stores, and returning a response. Read more about query services [here](../building-modules/query-services.md).
Since `MyQuery` has a Protobuf fully-qualified service method name from the `staking` module (recall `/cosmos.staking.v1beta1.Query/Delegations`), `baseapp` first parses the path, then uses its own internal `GRPCQueryRouter` to retrieve the corresponding gRPC handler, and routes the query to the module. The gRPC handler is responsible for recognizing this query, retrieving the appropriate values from the application's stores, and returning a response. Read more about query services [here](../building-modules/04-query-services.md).
Once a result is received from the querier, `baseapp` begins the process of returning a response to the user.
@ -125,12 +130,8 @@ Since `Query()` is an ABCI function, `baseapp` returns the response as an [`abci
### CLI Response
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).
The application [`codec`](../core/05-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.46.0/client/context.go#L315-L343
And that's a wrap! The result of the query is outputted to the console by the CLI.
## Next {hide}
Read more about [accounts](./accounts.md). {hide}

26
docs/basics/accounts.md → docs/docs/basics/03-accounts.md
View File

@ -1,18 +1,24 @@
<!--
order: 4
-->
---
sidebar_position: 1
---
# Accounts
This document describes the in-built account and public key system of the Cosmos SDK. {synopsis}
:::note Synopsis
This document describes the in-built account and public key system of the Cosmos SDK.
:::
## Pre-requisite Readings
:::note
* [Anatomy of a Cosmos SDK Application](./app-anatomy.md) {prereq}
### Pre-requisite Readings
* [Anatomy of a Cosmos SDK Application](./00-app-anatomy.md)
:::
## Account Definition
In the Cosmos SDK, an _account_ designates a pair of _public key_ `PubKey` and _private key_ `PrivKey`. The `PubKey` can be derived to generate various `Addresses`, which are used to identify users (among other parties) in the application. `Addresses` are also associated with [`message`s](../building-modules/messages-and-queries.md#messages) to identify the sender of the `message`. The `PrivKey` is used to generate [digital signatures](#signatures) to prove that an `Address` associated with the `PrivKey` approved of a given `message`.
In the Cosmos SDK, an _account_ designates a pair of _public key_ `PubKey` and _private key_ `PrivKey`. The `PubKey` can be derived to generate various `Addresses`, which are used to identify users (among other parties) in the application. `Addresses` are also associated with [`message`s](../building-modules/02-messages-and-queries.md#messages) to identify the sender of the `message`. The `PrivKey` is used to generate [digital signatures](#signatures) to prove that an `Address` associated with the `PrivKey` approved of a given `message`.
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.
@ -137,7 +143,7 @@ The default implementation of `Keyring` comes from the third-party [`99designs/k
A few notes on the `Keyring` methods:
* `Sign(uid string, msg []byte) ([]byte, types.PubKey, error)` strictly deals with the signature of the `msg` 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).
* `Sign(uid string, msg []byte) ([]byte, types.PubKey, error)` strictly deals with the signature of the `msg` 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/00-baseapp.md#antehandler).
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/tx/v1beta1/tx.proto#L48-L65
* `NewAccount(uid, mnemonic, bip39Passphrase, hdPath string, algo SignatureAlgo) (*Record, 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.46.0/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:
@ -146,7 +152,3 @@ A few notes on the `Keyring` methods:
* `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.
## Next {hide}
Learn about [gas and fees](./gas-fees.md) {hide}

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

@ -1,21 +1,27 @@
<!--
order: 5
-->
---
sidebar_position: 1
---
# Gas and Fees
This document describes the default strategies to handle gas and fees within a Cosmos SDK application. {synopsis}
:::note Synopsis
This document describes the default strategies to handle gas and fees within a Cosmos SDK application.
:::
## Pre-requisite Readings
:::note
* [Anatomy of a Cosmos SDK Application](./app-anatomy.md) {prereq}
### Pre-requisite Readings
* [Anatomy of a Cosmos SDK Application](./00-app-anatomy.md)
:::
## 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).
* Prevent spam and abuse from end-user. To this end, `gas` consumed during [`message`](../building-modules/02-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
@ -34,7 +40,7 @@ where:
* `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:
The gas meter is generally held in [`ctx`](../core/02-context.md), and consuming gas is done with the following pattern:
```go
ctx.GasMeter().ConsumeGas(amount, "description")
@ -44,17 +50,17 @@ By default, the Cosmos SDK makes use of two different gas meters, the [main gas
### Main Gas Meter
`ctx.GasMeter()` is the main gas meter of the application. The main gas meter is initialized in `BeginBlock` via `setDeliverState`, and then tracks gas consumption during execution sequences that lead to state-transitions, i.e. those originally triggered by [`BeginBlock`](../core/baseapp.md#beginblock), [`DeliverTx`](../core/baseapp.md#delivertx) and [`EndBlock`](../core/baseapp.md#endblock). At the beginning of each `DeliverTx`, the main gas meter **must be set to 0** in the [`AnteHandler`](#antehandler), so that it can track gas consumption per-transaction.
`ctx.GasMeter()` is the main gas meter of the application. The main gas meter is initialized in `BeginBlock` via `setDeliverState`, and then tracks gas consumption during execution sequences that lead to state-transitions, i.e. those originally triggered by [`BeginBlock`](../core/00-baseapp.md#beginblock), [`DeliverTx`](../core/00-baseapp.md#delivertx) and [`EndBlock`](../core/00-baseapp.md#endblock). At the beginning of each `DeliverTx`, the main gas meter **must be set to 0** in the [`AnteHandler`](#antehandler), so that it can track gas consumption per-transaction.
Gas consumption can be done manually, generally by the module developer in the [`BeginBlocker`, `EndBlocker`](../building-modules/beginblock-endblock.md) or [`Msg` service](../building-modules/msg-services.md), but most of the time it is done automatically whenever there is a read or write to the store. This automatic gas consumption logic is implemented in a special store called [`GasKv`](../core/store.md#gaskv-store).
Gas consumption can be done manually, generally by the module developer in the [`BeginBlocker`, `EndBlocker`](../building-modules/05-beginblock-endblock.md) or [`Msg` service](../building-modules/03-msg-services.md), but most of the time it is done automatically whenever there is a read or write to the store. This automatic gas consumption logic is implemented in a special store called [`GasKv`](../core/04-store.md#gaskv-store).
### Block Gas Meter
`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:
`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/00-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.21/types/params.go#L24-L65
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:
When a new [transaction](../core/01-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:
```go
ctx.BlockGasMeter().ConsumeGas(
@ -73,13 +79,9 @@ The anteHandler is not implemented in the core Cosmos SDK but in a module. That
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/types/tx_msg.go#L38-L46
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.46.0/proto/cosmos/tx/v1beta1/tx.proto#L13-L26
* 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`.
* Verify signatures for each [`message`](../building-modules/02-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 ensures 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 crucial**, 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.
## Next {hide}
Learn about [baseapp](../core/baseapp.md) {hide}
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/00-baseapp.md#delivertx) returns.

5
docs/docs/basics/_category_.json Normal file
View File

@ -0,0 +1,5 @@
{
"label": "Basics",
"position": 1,
"link": null
}

8
docs/building-apps/app-go.md → docs/docs/building-apps/00-app-go.md
View File

@ -1,6 +1,6 @@
<!--
order: 0
-->
---
sidebar_position: 1
---
# Overview of `app.go` and how to wire it up
@ -17,4 +17,4 @@ Since `v0.47.0` the Cosmos SDK have made easier wiring an `app.go` thanks to dep
## `app_legacy.go`
+++ https://github.com/cosmos/cosmos-sdk/blob/main/simapp/app_legacy.go
+++ https://github.com/cosmos/cosmos-sdk/blob/main/simapp/app_legacy.go

5
docs/docs/building-apps/_category_.json Normal file
View File

@ -0,0 +1,5 @@
{
"label": "Building Apps",
"position": 4,
"link": null
}

44
docs/building-modules/intro.md → docs/docs/building-modules/01-intro.md
View File

@ -1,23 +1,29 @@
<!--
order: 1
-->
---
sidebar_position: 1
---
# Introduction to Cosmos SDK Modules
Modules define most of the logic of Cosmos SDK applications. Developers compose modules together using the Cosmos SDK to build their custom application-specific blockchains. This document outlines the basic concepts behind SDK modules and how to approach module management. {synopsis}
:::note Synopsis
Modules define most of the logic of Cosmos SDK applications. Developers compose modules together using the Cosmos SDK to build their custom application-specific blockchains. This document outlines the basic concepts behind SDK modules and how to approach module management.
:::
## Pre-requisite Readings
:::note
* [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
* [Lifecycle of a Cosmos SDK transaction](../basics/tx-lifecycle.md) {prereq}
### Pre-requisite Readings
* [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md)
* [Lifecycle of a Cosmos SDK transaction](../basics/01-tx-lifecycle.md)
:::
## Role of Modules in a Cosmos SDK Application
The Cosmos SDK can be thought of as the Ruby-on-Rails of blockchain development. It comes with a core that provides the basic functionalities every blockchain application needs, like a [boilerplate implementation of the ABCI](../core/baseapp.md) to communicate with the underlying consensus engine, a [`multistore`](../core/store.md#multistore) to persist state, a [server](../core/node.md) to form a full-node and [interfaces](./module-interfaces.md) to handle queries.
The Cosmos SDK can be thought of as the Ruby-on-Rails of blockchain development. It comes with a core that provides the basic functionalities every blockchain application needs, like a [boilerplate implementation of the ABCI](../core/00-baseapp.md) to communicate with the underlying consensus engine, a [`multistore`](../core/04-store.md#multistore) to persist state, a [server](../core/03-node.md) to form a full-node and [interfaces](./09-module-interfaces.md) to handle queries.
On top of this core, the Cosmos SDK enables developers to build modules that implement the business logic of their application. In other words, SDK modules implement the bulk of the logic of applications, while the core does the wiring and enables modules to be composed together. The end goal is to build a robust ecosystem of open-source Cosmos SDK modules, making it increasingly easier to build complex blockchain applications.
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.
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/04-store.md), as well as a subset of [message types](./02-messages-and-queries.md#messages). These messages are routed by one of the main components of Cosmos SDK core, [`BaseApp`](../core/00-baseapp.md), to a module Protobuf [`Msg` service](./03-msg-services.md) that defines them.
```text
+
@ -70,23 +76,19 @@ 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`](./06-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/10-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`](./06-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).
* A [`keeper`](./06-keeper.md), used to access the module's store(s) and update the state.
* A [`Msg` service](./02-messages-and-queries.md#messages), used to process messages when they are routed to the module by [`BaseApp`](../core/00-baseapp.md#message-routing) and trigger state-transitions.
* A [query service](./04-query-services.md), used to process user queries when they are routed to the module by [`BaseApp`](../core/00-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).
In addition to these components, modules implement the `AppModule` interface in order to be managed by the [`module manager`](./01-module-manager.md).
Please refer to the [structure document](./structure.md) to learn about the recommended structure of a module's directory.
## Next {hide}
Read more on the [`AppModule` interface and the `module manager`](./module-manager.md) {hide}
Please refer to the [structure document](./10-structure.md) to learn about the recommended structure of a module's directory.

68
docs/building-modules/module-manager.md → docs/docs/building-modules/01-module-manager.md
View File

@ -1,14 +1,16 @@
<!--
order: 2
-->
---
sidebar_position: 1
---
# Module Manager
Cosmos SDK modules need to implement the [`AppModule` interfaces](#application-module-interfaces), in order to be managed by the application's [module manager](#module-manager). The module manager plays an important role in [`message` and `query` routing](../core/baseapp.md#routing), and allows application developers to set the order of execution of a variety of functions like [`BeginBlocker` and `EndBlocker`](../basics/app-anatomy.md#begingblocker-and-endblocker). {synopsis}
:::note Synopsis
Cosmos SDK modules need to implement the [`AppModule` interfaces](#application-module-interfaces), in order to be managed by the application's [module manager](#module-manager). The module manager plays an important role in [`message` and `query` routing](../core/00-baseapp.md#routing), and allows application developers to set the order of execution of a variety of functions like [`BeginBlocker` and `EndBlocker`](../basics/00-app-anatomy.md#begingblocker-and-endblocker).
:::
## Pre-requisite Readings
### Pre-requisite Readings
* [Introduction to Cosmos SDK Modules](./intro.md)
* [Introduction to Cosmos SDK Modules](./01-intro.md)
## Application Module Interfaces
@ -18,9 +20,9 @@ Application module interfaces exist to facilitate the composition of modules tog
* [`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).
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/00-app-anatomy.md#core-application-file).
The `AppModule` interface exists to define inter-dependent module methods. Many modules need to interact with other modules, typically through [`keeper`s](./keeper.md), which means there is a need for an interface where modules list their `keeper`s and other methods that require a reference to another module's object. `AppModule` interface also enables the module manager to set the order of execution between module's methods like `BeginBlock` and `EndBlock`, which is important in cases where the order of execution between modules matters in the context of the application.
The `AppModule` interface exists to define inter-dependent module methods. Many modules need to interact with other modules, typically through [`keeper`s](./06-keeper.md), which means there is a need for an interface where modules list their `keeper`s and other methods that require a reference to another module's object. `AppModule` interface also enables the module manager to set the order of execution between module's methods like `BeginBlock` and `EndBlock`, which is important in cases where the order of execution between modules matters in the context of the application.
Lastly the interface for genesis functionality `AppModuleGenesis` is separated out from full module functionality `AppModule` so that modules which
are only used for genesis can take advantage of the `Module` patterns without having to define many placeholder functions.
@ -36,11 +38,11 @@ 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.
* `DefaultGenesis(codec.JSONCodec)`: Returns a default [`GenesisState`](./08-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`](./08-genesis.md#validategenesis) function defined by the module developer.
* `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.
* `GetTxCmd()`: Returns the root [`Tx` command](./09-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](./02-messages-and-queries.md#queries) defined in the module.
* `GetQueryCmd()`: Return the root [`query` command](./09-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).
@ -67,7 +69,7 @@ The `AppModule` interface defines the inter-dependent methods that modules need
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).
* `RegisterInvariants(sdk.InvariantRegistry)`: Registers the [`invariants`](./07-invariants.md) of the module. If an invariant deviates from its predicted value, the [`InvariantRegistry`](./07-invariants.md#registry) triggers appropriate logic (most often the chain will be halted).
* `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.
@ -76,7 +78,7 @@ Let us go through the methods of `AppModule`:
Typically, the various application module interfaces are implemented in a file called `module.go`, located in the module's folder (e.g. `./x/module/module.go`).
Almost every module needs to implement the `AppModuleBasic` and `AppModule` interfaces. If the module is only used for genesis, it will implement `AppModuleGenesis` instead of `AppModule`. The concrete type that implements the interface can add parameters that are required for the implementation of the various methods of the interface. For example, the `Route()` function often calls a `NewMsgServerImpl(k keeper)` function defined in `keeper/msg_server.go` and therefore needs to pass the module's [`keeper`](./keeper.md) as a parameter.
Almost every module needs to implement the `AppModuleBasic` and `AppModule` interfaces. If the module is only used for genesis, it will implement `AppModuleGenesis` instead of `AppModule`. The concrete type that implements the interface can add parameters that are required for the implementation of the various methods of the interface. For example, the `Route()` function often calls a `NewMsgServerImpl(k keeper)` function defined in `keeper/msg_server.go` and therefore needs to pass the module's [`keeper`](./06-keeper.md) as a parameter.
```go
// example
@ -106,14 +108,14 @@ The `BasicManager` is a structure that lists all the `AppModuleBasic` of an appl
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/main/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).
* `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/00-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/main/app/app.go#L59-L74) to see an example).
* `RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)`: Registers the [`codec.LegacyAmino`s](../core/05-encoding.md#amino) of each of the application's `AppModuleBasic`. This function is usually called early on in the [application's construction](../basics/00-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.
* `DefaultGenesis(cdc codec.JSONCodec)`: Provides default genesis information for modules in the application by calling the [`DefaultGenesis(cdc codec.JSONCodec)`](./08-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)`](./08-genesis.md#validategenesis) function of each module.
* `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).
* `AddTxCommands(rootTxCmd *cobra.Command)`: Adds modules' transaction commands to the application's [`rootTxCommand`](../core/07-cli.md#transaction-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../core/07-cli.md).
* `AddQueryCommands(rootQueryCmd *cobra.Command)`: Adds modules' query commands to the application's [`rootQueryCommand`](../core/07-cli.md#query-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../core/07-cli.md).
### `Manager`
@ -123,26 +125,22 @@ The `Manager` is a structure that holds all the `AppModule` of an application, a
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).
* `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/00-app-anatomy.md#constructor-function).
* `SetOrderInitGenesis(moduleNames ...string)`: Sets the order in which the [`InitGenesis`](./08-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/00-app-anatomy.md#constructor-function).
To initialize modules successfully, module dependencies should be considered. For example, the `genutil` module must occur after `staking` module so that the pools are properly initialized with tokens from genesis accounts, the `genutils` module must also occur after `auth` so that it can access the params from auth, `capability` module should be initialized before all other modules so that it can initialize any capabilities.
* `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).
* `SetOrderExportGenesis(moduleNames ...string)`: Sets the order in which the [`ExportGenesis`](./08-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/00-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/00-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/00-app-anatomy.md#constructor-function).
* `SetOrderMigrations(moduleNames ...string)`: Sets the order of migrations to be run. If not set then migrations will be run with an order defined in `DefaultMigrationsOrder`.
* `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.
* `RegisterInvariants(ir sdk.InvariantRegistry)`: Registers the [invariants](./07-invariants.md) of each module.
* `RegisterRoutes(router sdk.Router, queryRouter sdk.QueryRouter, legacyQuerierCdc *codec.LegacyAmino)`: Registers legacy [`Msg`](./02-messages-and-queries.md#messages) and [`querier`](./04-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).
* `InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, genesisData map[string]json.RawMessage)`: Calls the [`InitGenesis`](./08-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`](./08-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/00-baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./05-beginblock-endblock.md) function of each module, in the order defined in `OrderBeginBlockers`. It creates a child [context](../core/02-context.md) with an event manager to aggregate [events](../core/08-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/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./05-beginblock-endblock.md) function of each module, in the order defined in `OrderEndBlockers`. It creates a child [context](../core/02-context.md) with an event manager to aggregate [events](../core/08-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/v0.46.0/simapp/app.go#L342-L409
## Next {hide}
Learn more about [`message`s and `queries`](./messages-and-queries.md) {hide}

56
docs/building-modules/messages-and-queries.md → docs/docs/building-modules/02-messages-and-queries.md
View File

@ -1,24 +1,30 @@
<!--
order: 3
-->
---
sidebar_position: 1
---
# Messages and Queries
`Msg`s and `Queries` are the two primary objects handled by modules. Most of the core components defined in a module, like `Msg` services, `keeper`s and `Query` services, exist to process `message`s and `queries`. {synopsis}
:::note Synopsis
`Msg`s and `Queries` are the two primary objects handled by modules. Most of the core components defined in a module, like `Msg` services, `keeper`s and `Query` services, exist to process `message`s and `queries`.
:::
## Pre-requisite Readings
:::note
* [Introduction to Cosmos SDK Modules](./intro.md) {prereq}
### Pre-requisite Readings
* [Introduction to Cosmos SDK Modules](./01-intro.md)
:::
## Messages
`Msg`s are objects whose end-goal is to trigger state-transitions. They are wrapped in [transactions](../core/transactions.md), which may contain one or more of them.
`Msg`s are objects whose end-goal is to trigger state-transitions. They are wrapped in [transactions](../core/01-transactions.md), which may contain one or more of them.
When a transaction is relayed from the underlying consensus engine to the Cosmos SDK application, it is first decoded by [`BaseApp`](../core/baseapp.md). Then, each message contained in the transaction is extracted and routed to the appropriate module via `BaseApp`'s `MsgServiceRouter` so that it can be processed by the module's [`Msg` service](./msg-services.md). For a more detailed explanation of the lifecycle of a transaction, click [here](../basics/tx-lifecycle.md).
When a transaction is relayed from the underlying consensus engine to the Cosmos SDK application, it is first decoded by [`BaseApp`](../core/00-baseapp.md). Then, each message contained in the transaction is extracted and routed to the appropriate module via `BaseApp`'s `MsgServiceRouter` so that it can be processed by the module's [`Msg` service](./03-msg-services.md). For a more detailed explanation of the lifecycle of a transaction, click [here](../basics/01-tx-lifecycle.md).
### `Msg` Services
Defining Protobuf `Msg` services is the recommended way to handle messages. A Protobuf `Msg` service should be created for each module, typically in `tx.proto` (see more info about [conventions and naming](../core/encoding.md#faq)). It must have an RPC service method defined for each message in the module.
Defining Protobuf `Msg` services is the recommended way to handle messages. A Protobuf `Msg` service should be created for each module, typically in `tx.proto` (see more info about [conventions and naming](../core/05-encoding.md#faq)). It must have an RPC service method defined for each message in the module.
See an example of a `Msg` service definition from `x/bank` module:
@ -34,12 +40,12 @@ Each `Msg` service method must have exactly one argument, which must implement t
The Cosmos SDK uses Protobuf definitions to generate client and server code:
* `MsgServer` interface defines the server API for the `Msg` service and its implementation is described as part of the [`Msg` services](./msg-services.md) documentation.
* `MsgServer` interface defines the server API for the `Msg` service and its implementation is described as part of the [`Msg` services](./03-msg-services.md) documentation.
* Structures are generated for all RPC request and response types.
A `RegisterMsgServer` method is also generated and should be used to register the module's `MsgServer` implementation in `RegisterServices` method from the [`AppModule` interface](./module-manager.md#appmodule).
A `RegisterMsgServer` method is also generated and should be used to register the module's `MsgServer` implementation in `RegisterServices` method from the [`AppModule` interface](./01-module-manager.md#appmodule).
In order for clients (CLI and grpc-gateway) to have these URLs registered, the Cosmos SDK provides the function `RegisterMsgServiceDesc(registry codectypes.InterfaceRegistry, sd *grpc.ServiceDesc)` that should be called inside module's [`RegisterInterfaces`](module-manager.md#appmodulebasic) method, using the proto-generated `&_Msg_serviceDesc` as `*grpc.ServiceDesc` argument.
In order for clients (CLI and grpc-gateway) to have these URLs registered, the Cosmos SDK provides the function `RegisterMsgServiceDesc(registry codectypes.InterfaceRegistry, sd *grpc.ServiceDesc)` that should be called inside module's [`RegisterInterfaces`](01-module-manager.md#appmodulebasic) method, using the proto-generated `&_Msg_serviceDesc` as `*grpc.ServiceDesc` argument.
### Legacy Amino `LegacyMsg`s
@ -47,15 +53,15 @@ The following way of defining messages is deprecated and using [`Msg` services](
Amino `LegacyMsg`s can be defined as protobuf messages. The messages definition usually includes a list of parameters needed to process the message that will be provided by end-users when they want to create a new transaction containing said message.
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:
A `LegacyMsg` is typically accompanied by a standard constructor function, that is called from one of the [module's interface](./09-module-interfaces.md). `message`s also need to implement the `sdk.Msg` interface:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/types/tx_msg.go#L10-L22
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 primarily 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).
* `Type() string`: Type of the message, used primarily in [events](../core/08-events.md). This should return a message-specific `string`, typically the denomination of the message itself.
* [`ValidateBasic() error`](../basics/01-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.
@ -67,7 +73,7 @@ See an example implementation of a `message` from the `gov` module:
## Queries
A `query` is a request for information made by end-users of applications through an interface and processed by a full-node. A `query` is received by a full-node through its consensus engine and relayed to the application via the ABCI. It is then routed to the appropriate module via `BaseApp`'s `QueryRouter` so that it can be processed by the module's query service (./query-services.md). For a deeper look at the lifecycle of a `query`, click [here](../basics/query-lifecycle.md).
A `query` is a request for information made by end-users of applications through an interface and processed by a full-node. A `query` is received by a full-node through its consensus engine and relayed to the application via the ABCI. It is then routed to the appropriate module via `BaseApp`'s `QueryRouter` so that it can be processed by the module's query service (./04-query-services.md). For a deeper look at the lifecycle of a `query`, click [here](../basics/02-query-lifecycle.md).
### gRPC Queries
@ -79,7 +85,7 @@ Here's an example of such a `Query` service definition:
As `proto.Message`s, generated `Response` types implement by default `String()` method of [`fmt.Stringer`](https://pkg.go.dev/fmt#Stringer).
A `RegisterQueryServer` method is also generated and should be used to register the module's query server in the `RegisterServices` method from the [`AppModule` interface](./module-manager.md#appmodule).
A `RegisterQueryServer` method is also generated and should be used to register the module's query server in the `RegisterServices` method from the [`AppModule` interface](./01-module-manager.md#appmodule).
### Legacy Queries
@ -91,15 +97,15 @@ 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.
* `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/00-baseapp.md#query).
* `queryRoute` is used by `BaseApp`'s [`queryRouter`](../core/00-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`](./04-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:
The `path` for each `query` must be defined by the module developer in the module's [command-line interface file](./09-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.
* A [`querier`](./04-query-services.md#legacy-queriers), to process the `query` once it has been [routed to the module](../core/00-baseapp.md#query-routing).
* [Query commands](./09-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://pkg.go.dev/fmt#Stringer).
### Store Queries
@ -109,7 +115,3 @@ Store queries query directly for store keys. They use `clientCtx.QueryABCI(req a
See following examples:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/baseapp/abci.go#L756-L777
## Next {hide}
Learn about [`Msg` services](./msg-services.md) {hide}

38
docs/building-modules/msg-services.md → docs/docs/building-modules/03-msg-services.md
View File

@ -1,15 +1,21 @@
<!--
order: 4
-->
---
sidebar_position: 1
---
# `Msg` Services
A Protobuf `Msg` service processes [messages](./messages-and-queries.md#messages). Protobuf `Msg` services are specific to the module in which they are defined, and only process messages defined within the said module. They are called from `BaseApp` during [`DeliverTx`](../core/baseapp.md#delivertx). {synopsis}
:::note Synopsis
A Protobuf `Msg` service processes [messages](./02-messages-and-queries.md#messages). Protobuf `Msg` services are specific to the module in which they are defined, and only process messages defined within the said module. They are called from `BaseApp` during [`DeliverTx`](../core/00-baseapp.md#delivertx).
:::
## Pre-requisite Readings
:::note
* [Module Manager](./module-manager.md) {prereq}
* [Messages and Queries](./messages-and-queries.md) {prereq}
### Pre-requisite Readings
* [Module Manager](./01-module-manager.md)
* [Messages and Queries](./02-messages-and-queries.md)
:::
## Implementation of a module `Msg` service
@ -21,7 +27,7 @@ Protobuf generates a `MsgServer` interface based on a definition of `Msg` servic
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/bank/types/tx.pb.go#L288-L294
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`:
When possible, the existing module's [`Keeper`](06-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.46.0/x/bank/keeper/msg_server.go#L14-L16
@ -33,7 +39,7 @@ When possible, the existing module's [`Keeper`](keeper.md) should implement `Msg
### Validation
Before a `msgServer` method is executed, the message's [`ValidateBasic()`](../basics/tx-lifecycle.md#ValidateBasic) method has already been called. Since `msg.ValidateBasic()` performs only the most basic checks, this stage must perform all other validation (both *stateful* and *stateless*) to make sure the `message` is valid. Checks performed in the `msgServer` method can be more expensive and the signer is charged gas for these operations.
Before a `msgServer` method is executed, the message's [`ValidateBasic()`](../basics/01-tx-lifecycle.md#ValidateBasic) method has already been called. Since `msg.ValidateBasic()` performs only the most basic checks, this stage must perform all other validation (both *stateful* and *stateless*) to make sure the `message` is valid. Checks performed in the `msgServer` method can be more expensive and the signer is charged gas for these operations.
For example, a `msgServer` method for a `transfer` message might check that the sending account has enough funds to actually perform the transfer.
It is recommended to implement all validation checks in a separate function that passes state values as arguments. This implementation simplifies testing. As expected, expensive validation functions charge additional gas. Example:
@ -50,11 +56,11 @@ ValidateMsgA(msg MsgA, now Time, gm GasMeter) error {
### State Transition
After the validation is successful, the `msgServer` method uses the [`keeper`](./keeper.md) functions to access the state and perform a state transition.
After the validation is successful, the `msgServer` method uses the [`keeper`](./06-keeper.md) functions to access the state and perform a state transition.
### Events
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:
Before returning, `msgServer` methods generally emit one or more [events](../core/08-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(
@ -73,7 +79,7 @@ ctx.EventManager().EmitEvent(
)
```
These events are relayed back to the underlying consensus engine and can be used by service providers to implement services around the application. Click [here](../core/events.md) to learn more about events.
These events are relayed back to the underlying consensus engine and can be used by service providers to implement services around the application. Click [here](../core/08-events.md) to learn more about events.
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)`:
@ -85,16 +91,12 @@ This method takes care of marshaling the `res` parameter to protobuf and attachi
This diagram shows a typical structure of a Protobuf `Msg` service, and how the message propagates through the module.
![Transaction flow](../uml/svg/transaction_flow.svg)
![Transaction flow](https://raw.githubusercontent.com/cosmos/cosmos-sdk/release/v0.46.x/docs/uml/svg/transaction_flow.svg)
## Telemetry
New [telemetry metrics](../core/telemetry.md) can be created from `msgServer` methods when handling messages.
New [telemetry metrics](../core/09-telemetry.md) can be created from `msgServer` methods when handling messages.
This is an example from the `x/auth/vesting` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/auth/vesting/msg_server.go#L73-L85
## Next {hide}
Learn about [query services](./query-services.md) {hide}

30
docs/building-modules/query-services.md → docs/docs/building-modules/04-query-services.md
View File

@ -1,15 +1,21 @@
<!--
order: 5
-->
---
sidebar_position: 1
---
# Query Services
A Protobuf Query service processes [`queries`](./messages-and-queries.md#queries). Query services are specific to the module in which they are defined, and only process `queries` defined within said module. They are called from `BaseApp`'s [`Query` method](../core/baseapp.md#query). {synopsis}
:::note Synopsis
A Protobuf Query service processes [`queries`](./02-messages-and-queries.md#queries). Query services are specific to the module in which they are defined, and only process `queries` defined within said module. They are called from `BaseApp`'s [`Query` method](../core/00-baseapp.md#query).
:::
## Pre-requisite Readings
:::note
* [Module Manager](./module-manager.md) {prereq}
* [Messages and Queries](./messages-and-queries.md) {prereq}
### Pre-requisite Readings
* [Module Manager](./01-module-manager.md)
* [Messages and Queries](./02-messages-and-queries.md)
:::
## `Querier` type
@ -19,10 +25,10 @@ The `querier` type defined in the Cosmos SDK will be deprecated in favor of [gRP
Let us break it down:
* 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 `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 [`Context`](../core/02-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`](./06-keeper.md) to access the state.
* The `path` is an array of `string`s that contains the type of the query, and that can also contain `query` arguments. See [`queries`](./02-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 result in `[]byte` returned to `BaseApp`, marshalled using the application's [`codec`](../core/encoding.md).
* The result in `[]byte` returned to `BaseApp`, marshalled using the application's [`codec`](../core/05-encoding.md).
## Implementation of a module query service
@ -44,7 +50,3 @@ 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/v0.46.0/x/bank/keeper/grpc_query.go
## Next {hide}
Learn about [`BeginBlocker` and `EndBlocker`](./beginblock-endblock.md) {hide}

32
docs/building-modules/beginblock-endblock.md → docs/docs/building-modules/05-beginblock-endblock.md
View File

@ -1,30 +1,36 @@
<!--
order: 6
-->
---
sidebar_position: 1
---
# BeginBlocker and EndBlocker
`BeginBlocker` and `EndBlocker` are optional methods module developers can implement in their module. They will be triggered at the beginning and at the end of each block respectively, when the [`BeginBlock`](../core/baseapp.md#beginblock) and [`EndBlock`](../core/baseapp.md#endblock) ABCI messages are received from the underlying consensus engine. {synopsis}
:::note Synopsis
`BeginBlocker` and `EndBlocker` are optional methods module developers can implement in their module. They will be triggered at the beginning and at the end of each block respectively, when the [`BeginBlock`](../core/00-baseapp.md#beginblock) and [`EndBlock`](../core/00-baseapp.md#endblock) ABCI messages are received from the underlying consensus engine.
:::
## Pre-requisite Readings
:::note
* [Module Manager](./module-manager.md) {prereq}
### Pre-requisite Readings
* [Module Manager](./01-module-manager.md)
:::
## BeginBlocker and EndBlocker
`BeginBlocker` and `EndBlocker` are a way for module developers to add automatic execution of logic to their module. This is a powerful tool that should be used carefully, as complex automatic functions can slow down or even halt the chain.
When needed, `BeginBlocker` and `EndBlocker` are implemented as part of the [`AppModule` interface](./module-manager.md#appmodule). The `BeginBlock` and `EndBlock` methods of the interface implemented in `module.go` generally defer to `BeginBlocker` and `EndBlocker` methods respectively, which are usually implemented in `abci.go`.
When needed, `BeginBlocker` and `EndBlocker` are implemented as part of the [`AppModule` interface](./01-module-manager.md#appmodule). The `BeginBlock` and `EndBlock` methods of the interface implemented in `module.go` generally defer to `BeginBlocker` and `EndBlocker` methods respectively, which are usually implemented in `abci.go`.
The actual implementation of `BeginBlocker` and `EndBlocker` in `abci.go` are very similar to that of a [`Msg` service](./msg-services.md):
The actual implementation of `BeginBlocker` and `EndBlocker` in `abci.go` are very similar to that of a [`Msg` service](./03-msg-services.md):
* They generally use the [`keeper`](./keeper.md) and [`ctx`](../core/context.md) to retrieve information about the latest state.
* They generally use the [`keeper`](./06-keeper.md) and [`ctx`](../core/02-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`.
* If needed, they can emit [`events`](../core/08-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://docs.tendermint.com/master/spec/abci/abci.html#validatorupdate). This is the preferred way to implement custom validator changes.
It is possible for developers to define the order of execution between the `BeginBlocker`/`EndBlocker` functions of each of their application's modules via the module's manager `SetOrderBeginBlocker`/`SetOrderEndBlocker` methods. For more on the module manager, click [here](./module-manager.md#manager).
It is possible for developers to define the order of execution between the `BeginBlocker`/`EndBlocker` functions of each of their application's modules via the module's manager `SetOrderBeginBlocker`/`SetOrderEndBlocker` methods. For more on the module manager, click [here](./01-module-manager.md#manager).
See an example implementation of `BeginBlocker` from the `distribution` module:
@ -33,7 +39,3 @@ See an example implementation of `BeginBlocker` from the `distribution` module:
and an example implementation of `EndBlocker` from the `staking` module:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/staking/abci.go#L22-L27
## Next {hide}
Learn about [`keeper`s](./keeper.md) {hide}

36
docs/building-modules/keeper.md → docs/docs/building-modules/06-keeper.md
View File

@ -1,22 +1,28 @@
<!--
order: 7
-->
---
sidebar_position: 1
---
# Keepers
`Keeper`s refer to a Cosmos SDK abstraction whose role is to manage access to the subset of the state defined by various modules. `Keeper`s are module-specific, i.e. the subset of state defined by a module can only be accessed by a `keeper` defined in said module. If a module needs to access the subset of state defined by another module, a reference to the second module's internal `keeper` needs to be passed to the first one. This is done in `app.go` during the instantiation of module keepers. {synopsis}
:::note Synopsis
`Keeper`s refer to a Cosmos SDK abstraction whose role is to manage access to the subset of the state defined by various modules. `Keeper`s are module-specific, i.e. the subset of state defined by a module can only be accessed by a `keeper` defined in said module. If a module needs to access the subset of state defined by another module, a reference to the second module's internal `keeper` needs to be passed to the first one. This is done in `app.go` during the instantiation of module keepers.
:::
## Pre-requisite Readings
:::note
* [Introduction to Cosmos SDK Modules](./intro.md) {prereq}
### Pre-requisite Readings
* [Introduction to Cosmos SDK Modules](./01-intro.md)
:::
## Motivation
The Cosmos SDK is a framework that makes it easy for developers to build complex decentralized applications from scratch, mainly by composing modules together. As the ecosystem of open-source modules for the Cosmos SDK expands, it will become increasingly likely that some of these modules contain vulnerabilities, as a result of the negligence or malice of their developer.
The Cosmos SDK adopts an [object-capabilities-based approach](../core/ocap.md) to help developers better protect their application from unwanted inter-module interactions, and `keeper`s are at the core of this approach. A `keeper` can be considered quite literally to be the gatekeeper of a module's store(s). Each store (typically an [`IAVL` Store](../core/store.md#iavl-store)) defined within a module comes with a `storeKey`, which grants unlimited access to it. The module's `keeper` holds this `storeKey` (which should otherwise remain unexposed), and defines [methods](#implementing-methods) for reading and writing to the store(s).
The Cosmos SDK adopts an [object-capabilities-based approach](../core/10-ocap.md) to help developers better protect their application from unwanted inter-module interactions, and `keeper`s are at the core of this approach. A `keeper` can be considered quite literally to be the gatekeeper of a module's store(s). Each store (typically an [`IAVL` Store](../core/04-store.md#iavl-store)) defined within a module comes with a `storeKey`, which grants unlimited access to it. The module's `keeper` holds this `storeKey` (which should otherwise remain unexposed), and defines [methods](#implementing-methods) for reading and writing to the store(s).
The core idea behind the object-capabilities approach is to only reveal what is necessary to get the work done. In practice, this means that instead of handling permissions of modules through access-control lists, module `keeper`s are passed a reference to the specific instance of the other modules' `keeper`s that they need to access (this is done in the [application's constructor function](../basics/app-anatomy.md#constructor-function)). As a consequence, a module can only interact with the subset of state defined in another module via the methods exposed by the instance of the other module's `keeper`. This is a great way for developers to control the interactions that their own module can have with modules developed by external developers.
The core idea behind the object-capabilities approach is to only reveal what is necessary to get the work done. In practice, this means that instead of handling permissions of modules through access-control lists, module `keeper`s are passed a reference to the specific instance of the other modules' `keeper`s that they need to access (this is done in the [application's constructor function](../basics/00-app-anatomy.md#constructor-function)). As a consequence, a module can only interact with the subset of state defined in another module via the methods exposed by the instance of the other module's `keeper`. This is a great way for developers to control the interactions that their own module can have with modules developed by external developers.
## Type Definition
@ -41,14 +47,14 @@ For example, here is the type definition of the `keeper` from the `staking` modu
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. The authority listed is a module account or user account that has the right to change module level parameters. Previously this was handled by the param module, which has been deprecated.
* `storeKey`s grant access to the store(s) of the [multistore](../core/04-store.md) managed by the module. They should always remain unexposed to external modules.
* `cdc` is the [codec](../core/05-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. The authority listed is a module account or user account that has the right to change module level parameters. Previously this was handled by the param module, which has been deprecated.
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.
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/00-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.
## Implementing Methods
`Keeper`s primarily expose getter and setter methods for the store(s) managed by their module. These methods should remain as simple as possible and strictly be limited to getting or setting the requested value, as validity checks should have already been performed via the `ValidateBasic()` method of the [`message`](./messages-and-queries.md#messages) and the [`Msg` server](./msg-services.md) when `keeper`s' methods are called.
`Keeper`s primarily expose getter and setter methods for the store(s) managed by their module. These methods should remain as simple as possible and strictly be limited to getting or setting the requested value, as validity checks should have already been performed via the `ValidateBasic()` method of the [`message`](./02-messages-and-queries.md#messages) and the [`Msg` server](./03-msg-services.md) when `keeper`s' methods are called.
Typically, a *getter* method will have the following signature
@ -76,12 +82,8 @@ and the method will go through the following steps:
For more, see an example of `keeper`'s [methods implementation from the `staking` module](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/staking/keeper/keeper.go).
The [module `KVStore`](../core/store.md#kvstore-and-commitkvstore-interfaces) also provides an `Iterator()` method which returns an `Iterator` object to iterate over a domain of keys.
The [module `KVStore`](../core/04-store.md#kvstore-and-commitkvstore-interfaces) also provides an `Iterator()` method which returns an `Iterator` object to iterate over a domain of keys.
This is an example from the `auth` module to iterate accounts:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/auth/keeper/account.go#L76-L90
## Next {hide}
Learn about [invariants](./invariants.md) {hide}

28
docs/building-modules/invariants.md → docs/docs/building-modules/07-invariants.md
View File

@ -1,14 +1,20 @@
<!--
order: 8
-->
---
sidebar_position: 1
---
# Invariants
An invariant is a property of the application that should always be true. In the context of the Cosmos SDK, an `Invariant` is a function that checks for a particular invariant. These functions are useful to detect bugs early on and act upon them to limit their potential consequences (e.g. by halting the chain). They are also useful in the development process of the application to detect bugs via simulations. {synopsis}
:::note Synopsis
An invariant is a property of the application that should always be true. In the context of the Cosmos SDK, an `Invariant` is a function that checks for a particular invariant. These functions are useful to detect bugs early on and act upon them to limit their potential consequences (e.g. by halting the chain). They are also useful in the development process of the application to detect bugs via simulations.
:::
## Pre-requisite Readings
:::note
* [Keepers](./keeper.md) {prereq}
### Pre-requisite Readings
* [Keepers](./06-keeper.md)
:::
## Implementing `Invariant`s
@ -49,7 +55,7 @@ func AllInvariants(k Keeper) sdk.Invariant {
}
```
Finally, module developers need to implement the `RegisterInvariants` method as part of the [`AppModule` interface](./module-manager.md#appmodule). Indeed, the `RegisterInvariants` method of the module, implemented in the `module/module.go` file, typically only defers the call to a `RegisterInvariants` method implemented in the `keeper/invariants.go` file. The `RegisterInvariants` method registers a route for each `Invariant` function in the [`InvariantRegistry`](#invariant-registry):
Finally, module developers need to implement the `RegisterInvariants` method as part of the [`AppModule` interface](./01-module-manager.md#appmodule). Indeed, the `RegisterInvariants` method of the module, implemented in the `module/module.go` file, typically only defers the call to a `RegisterInvariants` method implemented in the `keeper/invariants.go` file. The `RegisterInvariants` method registers a route for each `Invariant` function in the [`InvariantRegistry`](#invariant-registry):
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/staking/keeper/invariants.go#L12-L21
@ -67,14 +73,10 @@ Typically, this interface is implemented in the `keeper` of a specific module. T
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/crisis/keeper/keeper.go#L49-L53
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).
The `InvariantRegistry` is therefore typically instantiated by instantiating the `keeper` of the `crisis` module in the [application's constructor function](../basics/00-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:
`Invariant`s can be checked manually via [`message`s](./02-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/v0.46.0/x/crisis/abci.go#L12-L21
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).
## Next {hide}
Learn about [genesis functionalities](./genesis.md) {hide}

32
docs/building-modules/genesis.md → docs/docs/building-modules/08-genesis.md
View File

@ -1,19 +1,25 @@
<!--
order: 9
-->
---
sidebar_position: 1
---
# Module Genesis
Modules generally handle a subset of the state and, as such, they need to define the related subset of the genesis file as well as methods to initialize, verify and export it. {synopsis}
:::note Synopsis
Modules generally handle a subset of the state and, as such, they need to define the related subset of the genesis file as well as methods to initialize, verify and export it.
:::
## Pre-requisite Readings
:::note
* [Module Manager](./module-manager.md) {prereq}
* [Keepers](./keeper.md) {prereq}
### Pre-requisite Readings
* [Module Manager](./01-module-manager.md)
* [Keepers](./06-keeper.md)
:::
## Type Definition
The subset of the genesis state defined from a given module is generally defined in a `genesis.proto` file ([more info](../core/encoding.md#gogoproto) on how to define protobuf messages). The struct defining the module's subset of the genesis state is usually called `GenesisState` and contains all the module-related values that need to be initialized during the genesis process.
The subset of the genesis state defined from a given module is generally defined in a `genesis.proto` file ([more info](../core/05-encoding.md#gogoproto) on how to define protobuf messages). The struct defining the module's subset of the genesis state is usually called `GenesisState` and contains all the module-related values that need to be initialized during the genesis process.
See an example of `GenesisState` protobuf message definition from the `auth` module:
@ -35,13 +41,13 @@ The `ValidateGenesis(data GenesisState)` method is called to verify that the pro
## Other Genesis Methods
Other than the methods related directly to `GenesisState`, module developers are expected to implement two other methods as part of the [`AppModuleGenesis` interface](./module-manager.md#appmodulegenesis) (only if the module needs to initialize a subset of state in genesis). These methods are [`InitGenesis`](#initgenesis) and [`ExportGenesis`](#exportgenesis).
Other than the methods related directly to `GenesisState`, module developers are expected to implement two other methods as part of the [`AppModuleGenesis` interface](./01-module-manager.md#appmodulegenesis) (only if the module needs to initialize a subset of state in genesis). These methods are [`InitGenesis`](#initgenesis) and [`ExportGenesis`](#exportgenesis).
### `InitGenesis`
The `InitGenesis` method is executed during [`InitChain`](../core/baseapp.md#initchain) when the application is first started. Given a `GenesisState`, it initializes the subset of the state managed by the module by using the module's [`keeper`](./keeper.md) setter function on each parameter within the `GenesisState`.
The `InitGenesis` method is executed during [`InitChain`](../core/00-baseapp.md#initchain) when the application is first started. Given a `GenesisState`, it initializes the subset of the state managed by the module by using the module's [`keeper`](./06-keeper.md) setter function on each parameter within the `GenesisState`.
The [module manager](./module-manager.md#manager) of the application is responsible for calling the `InitGenesis` method of each of the application's modules in order. This order is set by the application developer via the manager's `SetOrderGenesisMethod`, which is called in the [application's constructor function](../basics/app-anatomy.md#constructor-function).
The [module manager](./01-module-manager.md#manager) of the application is responsible for calling the `InitGenesis` method of each of the application's modules in order. This order is set by the application developer via the manager's `SetOrderGenesisMethod`, which is called in the [application's constructor function](../basics/00-app-anatomy.md#constructor-function).
See an example of `InitGenesis` from the `auth` module:
@ -54,7 +60,3 @@ 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/v0.46.0/x/auth/keeper/genesis.go#L29-L41
## Next {hide}
Learn about [modules interfaces](module-interfaces.md) {hide}

36
docs/building-modules/module-interfaces.md → docs/docs/building-modules/09-module-interfaces.md
View File

@ -1,22 +1,28 @@
<!--
order: 11
-->
---
sidebar_position: 1
---
# Module Interfaces
This document details how to build CLI and REST interfaces for a module. Examples from various Cosmos SDK modules are included. {synopsis}
:::note Synopsis
This document details how to build CLI and REST interfaces for a module. Examples from various Cosmos SDK modules are included.
:::
:::note
## Prerequisite Readings
* [Building Modules Intro](./intro.md) {prereq}
* [Building Modules Intro](./01-intro.md)
:::
## CLI
One of the main interfaces for an application is the [command-line interface](../core/cli.md). This entrypoint adds commands from the application's modules enabling end-users to create [**messages**](./messages-and-queries.md#messages) wrapped in transactions and [**queries**](./messages-and-queries.md#queries). The CLI files are typically found in the module's `./client/cli` folder.
One of the main interfaces for an application is the [command-line interface](../core/07-cli.md). This entrypoint adds commands from the application's modules enabling end-users to create [**messages**](./02-messages-and-queries.md#messages) wrapped in transactions and [**queries**](./02-messages-and-queries.md#queries). The CLI files are typically found in the module's `./client/cli` folder.
### Transaction Commands
In order to create messages that trigger state changes, end-users must create [transactions](../core/transactions.md) that wrap and deliver the messages. A transaction command creates a transaction that includes one or more messages.
In order to create messages that trigger state changes, end-users must create [transactions](../core/01-transactions.md) that wrap and deliver the messages. A transaction command creates a transaction that includes one or more messages.
Transaction commands typically have their own `tx.go` file that lives within the module's `./client/cli` folder. The commands are specified in getter functions and the name of the function should include the name of the command.
@ -35,7 +41,7 @@ In general, the getter function does the following:
* **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.
* A [message](./02-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/01-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.
@ -50,7 +56,7 @@ Each module must also implement the `GetTxCmd()` method for `AppModuleBasic` tha
### 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:
[Queries](./02-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.46.0/x/auth/client/cli/query.go#L83-L125
@ -65,7 +71,7 @@ In general, the getter function does the following:
* **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).
* A new `queryClient` is initialized using `NewQueryClient(clientCtx)`. The `queryClient` is then used to call the appropriate [query](./02-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.
@ -80,7 +86,7 @@ Each module must also implement the `GetQueryCmd()` method for `AppModuleBasic`
### Flags
[Flags](../core/cli.md#flags) allow users to customize commands. `--fees` and `--gas-prices` are examples of flags that allow users to set the [fees](../basics/gas-fees.md) and gas prices for their transactions.
[Flags](../core/07-cli.md#flags) allow users to customize commands. `--fees` and `--gas-prices` are examples of flags that allow users to set the [fees](../basics/04-gas-fees.md) and gas prices for their transactions.
Flags that are specific to a module are typically created in a `flags.go` file in the module's `./client/cli` folder. When creating a flag, developers set the value type, the name of the flag, the default value, and a description about the flag. Developers also have the option to mark flags as _required_ so that an error is thrown if the user does not include a value for the flag.
@ -130,10 +136,6 @@ Modules that want to expose REST queries should add `google.api.http` annotation
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/auth/v1beta1/query.proto#L13-L59
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).
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/02-interact-node.md#configuring-the-node-using-apptoml).
The Cosmos SDK provides a command for generating [Swagger](https://swagger.io/) documentation (`protoc-gen-swagger`). Setting `swagger` in [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml) defines if swagger documentation should be automatically registered.
## Next {hide}
Read about the recommended [module structure](./structure.md) {hide}
The Cosmos SDK provides a command for generating [Swagger](https://swagger.io/) documentation (`protoc-gen-swagger`). Setting `swagger` in [`app.toml`](../run-node/02-interact-node.md#configuring-the-node-using-apptoml) defines if swagger documentation should be automatically registered.

19
docs/building-modules/structure.md → docs/docs/building-modules/10-structure.md
View File

@ -1,11 +1,12 @@
<!--
order: 12
-->
---
sidebar_position: 1
---
# Recommended Folder Structure
This document outlines the recommended structure of Cosmos SDK modules. These ideas are meant to be applied as suggestions. Application developers are encouraged to improve upon and contribute to module structure and development design. {synopsis}
:::note Synopsis
This document outlines the recommended structure of Cosmos SDK modules. These ideas are meant to be applied as suggestions. Application developers are encouraged to improve upon and contribute to module structure and development design.
:::
## Structure
A typical Cosmos SDK module can be structured as follows:
@ -80,20 +81,16 @@ x/{module_name}
* `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`).
* `simulation/`: The module's [simulation](./13-simulator.md) 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.
* `expected_keepers.go`: The module's [expected keeper](./06-keeper.md#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}
Learn about [Errors](./errors.md) {hide}

10
docs/building-modules/errors.md → docs/docs/building-modules/11-errors.md
View File

@ -1,10 +1,12 @@
<!--
order: 13
-->
---
sidebar_position: 1
---
# Errors
This document outlines the recommended usage and APIs for error handling in Cosmos SDK modules. {synopsis}
:::note Synopsis
This document outlines the recommended usage and APIs for error handling in Cosmos SDK modules.
:::
Modules are encouraged to define and register their own errors to provide better
context on failed message or handler execution. Typically, these errors should be

16
docs/building-modules/upgrade.md → docs/docs/building-modules/12-upgrade.md
View File

@ -1,14 +1,20 @@
<!--
order: 13
-->
---
sidebar_position: 1
---
# Upgrading Modules
[In-Place Store Migrations](../core/upgrade.md) allow your modules to upgrade to new versions that include breaking changes. This document outlines how to build modules to take advantage of this functionality. {synopsis}
:::note Synopsis
[In-Place Store Migrations](../core/15-upgrade.md) allow your modules to upgrade to new versions that include breaking changes. This document outlines how to build modules to take advantage of this functionality.
:::
:::note
## Prerequisite Readings
* [In-Place Store Migration](../core/upgrade.md) {prereq}
* [In-Place Store Migration](../core/15-upgrade.md)
:::
## Consensus Version

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

@ -1,18 +1,20 @@
<!--
order: 14
-->
---
sidebar_position: 1
---
# Module Simulation
## Prerequisites
:::note
### Pre-requisite Readings
* [Cosmos Blockchain Simulator](./../core/simulation.md)
* [Cosmos Blockchain Simulator](../core/12-simulation.md)
:::
## Synopsis
This document details how to define each module simulation functions to be
integrated with the application `SimulationManager`.
* [Simulation package](#simulation-package)
* [Store decoders](#store-decoders)
* [Randomized genesis](#randomized-genesis)
@ -61,7 +63,7 @@ Operations are one of the crucial parts of the Cosmos SDK simulation. They are t
(`Msg`) that are simulated with random field values. The sender of the operation
is also assigned randomly.
Operations on the simulation are simulated using the full [transaction cycle](../core/transactions.md) of a
Operations on the simulation are simulated using the full [transaction cycle](../core/01-transactions.md) of a
`ABCI` application that exposes the `BaseApp`.
Shown below is how weights are set:

12
docs/building-modules/testing.md → docs/docs/building-modules/14-testing.md
View File

@ -1,6 +1,6 @@
<!--
order: 16
-->
---
sidebar_position: 1
---
# Module & App Testing
@ -47,13 +47,13 @@ We can test then create unit tests using the newly created `Keeper` instance.
Integration tests are at the second level of the [test pyramid](https://martinfowler.com/articles/practical-test-pyramid.html).
In the SDK, we locate our integration tests under [`/tests/integrations`](https://github.com/cosmos/cosmos-sdk/tree/main/tests/integration).
The goal of these integration tests is to test a component with a minimal application (i.e. not `simapp`). The minimal application is defined with the help of [`depinject`](../building-chain/depinject.md) – the SDK dependency injection framework, and includes all necessary modules to test the component. With the helps of the SDK testing package, we can easily create a minimal application and start the application with a set of genesis transactions: <https://github.com/cosmos/cosmos-sdk/blob/main/testutil/sims/app_helpers.go>.
The goal of these integration tests is to test a component with a minimal application (i.e. not `simapp`). The minimal application is defined with the help of [`depinject`](../building-apps/01-depinject.md) – the SDK dependency injection framework, and includes all necessary modules to test the component. With the helps of the SDK testing package, we can easily create a minimal application and start the application with a set of genesis transactions: <https://github.com/cosmos/cosmos-sdk/blob/main/testutil/sims/app_helpers.go>.
### Example
Here, we will walkthrough the integration tests of the `x/distribution` module. The `x/distribution` module has, in addition to keeper unit tests, integration tests that test the `x/distribution` module with a minimal application. This is expected as you may want to test the `x/distribution` module with actual application logic, instead of only mocked dependencies.
For creating a minimal application, we use [`simtestutil.Setup`](https://github.com/cosmos/cosmos-sdk/blob/main/testutil/sims/app_helpers.go#L98-L102) and an [`AppConfig`](../building-chain/depinject.md) of the `x/distribution` minimal dependencies.
For creating a minimal application, we use [`simtestutil.Setup`](https://github.com/cosmos/cosmos-sdk/blob/main/testutil/sims/app_helpers.go#L98-L102) and an [`AppConfig`](../building-apps/01-depinject.md) of the `x/distribution` minimal dependencies.
For instance, the `AppConfig` of `x/distribution` is defined as:
@ -73,7 +73,7 @@ Now the types are injected and we can use them for our tests:
## Simulations
Simulations uses as well a minimal application, built with [`depinject`](../building-chain/depinject.md):
Simulations uses as well a minimal application, built with [`depinject`](../building-apps/01-depinject.md):
Following is an example for `x/gov/` simulations:

5
docs/docs/building-modules/_category_.json Normal file
View File

@ -0,0 +1,5 @@
{
"label": "Building Modules",
"position": 3,
"link": null
}

86
docs/core/baseapp.md → docs/docs/core/00-baseapp.md
View File

@ -1,15 +1,21 @@
<!--
order: 1
-->
---
sidebar_position: 1
---
# BaseApp
This document describes `BaseApp`, the abstraction that implements the core functionalities of a Cosmos SDK application. {synopsis}
:::note Synopsis
This document describes `BaseApp`, the abstraction that implements the core functionalities of a Cosmos SDK application.
:::
## Pre-requisite Readings
:::note
* [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
* [Lifecycle of a Cosmos SDK transaction](../basics/tx-lifecycle.md) {prereq}
### Pre-requisite Readings
* [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md)
* [Lifecycle of a Cosmos SDK transaction](../basics/01-tx-lifecycle.md)
:::
## Introduction
@ -54,7 +60,7 @@ 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`](./04-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
@ -72,8 +78,8 @@ First, the important parameters that are initialized during the bootstrapping of
* [`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),
[`BeginBlocker` and `EndBlocker`](../basics/app-anatomy.md#beginblocker-and-endblocker): These are
* [`InitChainer`](../basics/00-app-anatomy.md#initchainer),
[`BeginBlocker` and `EndBlocker`](../basics/00-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.
@ -97,7 +103,7 @@ Finally, a few more important parameters:
`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
[application's constructor function](../basics/app-anatomy.md#constructor-function).
[application's constructor function](../basics/00-app-anatomy.md#constructor-function).
## Constructor
@ -190,17 +196,17 @@ When messages and queries are received by the application, they must be routed t
### `Msg` Service Router
[`sdk.Msg`s](#../building-modules/messages-and-queries.md#messages) need to be routed after they are extracted from transactions, which are sent from the underlying Tendermint engine via the [`CheckTx`](#checktx) and [`DeliverTx`](#delivertx) ABCI messages. To do so, `BaseApp` holds a `msgServiceRouter` which maps fully-qualified service methods (`string`, defined in each module's Protobuf `Msg` service) to the appropriate module's `MsgServer` implementation.
[`sdk.Msg`s](../building-modules/02-messages-and-queries.md#messages) need to be routed after they are extracted from transactions, which are sent from the underlying Tendermint engine via the [`CheckTx`](#checktx) and [`DeliverTx`](#delivertx) ABCI messages. To do so, `BaseApp` holds a `msgServiceRouter` which maps fully-qualified service methods (`string`, defined in each module's Protobuf `Msg` service) to the appropriate module's `MsgServer` implementation.
The [default `msgServiceRouter` included in `BaseApp`](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/baseapp/msg_service_router.go) is stateless. However, some applications may want to make use of more stateful routing mechanisms such as allowing governance to disable certain routes or point them to new modules for upgrade purposes. For this reason, the `sdk.Context` is also passed into each [route handler inside `msgServiceRouter`](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/baseapp/msg_service_router.go#L31-L32). For a stateless router that doesn't want to make use of this, you can just ignore the `ctx`.
The application's `msgServiceRouter` is initialized with all the routes using the application's [module manager](../building-modules/module-manager.md#manager) (via the `RegisterServices` method), which itself is initialized with all the application's modules in the application's [constructor](../basics/app-anatomy.md#constructor-function).
The application's `msgServiceRouter` is initialized with all the routes using the application's [module manager](../building-modules/01-module-manager.md#manager) (via the `RegisterServices` method), which itself is initialized with all the application's modules in the application's [constructor](../basics/00-app-anatomy.md#constructor-function).
### gRPC Query Router
Similar to `sdk.Msg`s, [`queries`](../building-modules/messages-and-queries.md#queries) need to be routed to the appropriate module's [`Query` service](../building-modules/query-services.md). To do so, `BaseApp` holds a `grpcQueryRouter`, which maps modules' fully-qualified service methods (`string`, defined in their Protobuf `Query` gRPC) to their `QueryServer` implementation. The `grpcQueryRouter` is called during the initial stages of query processing, which can be either by directly sending a gRPC query to the gRPC endpoint, or via the [`Query` ABCI message](#query) on the Tendermint RPC endpoint.
Similar to `sdk.Msg`s, [`queries`](../building-modules/02-messages-and-queries.md#queries) need to be routed to the appropriate module's [`Query` service](../building-modules/04-query-services.md). To do so, `BaseApp` holds a `grpcQueryRouter`, which maps modules' fully-qualified service methods (`string`, defined in their Protobuf `Query` gRPC) to their `QueryServer` implementation. The `grpcQueryRouter` is called during the initial stages of query processing, which can be either by directly sending a gRPC query to the gRPC endpoint, or via the [`Query` ABCI message](#query) on the Tendermint RPC endpoint.
Just like the `msgServiceRouter`, the `grpcQueryRouter` is initialized with all the query routes using the application's [module manager](../building-modules/module-manager.md) (via the `RegisterServices` method), which itself is initialized with all the application's modules in the application's [constructor](../basics/app-anatomy.md#app-constructor).
Just like the `msgServiceRouter`, the `grpcQueryRouter` is initialized with all the query routes using the application's [module manager](../building-modules/01-module-manager.md) (via the `RegisterServices` method), which itself is initialized with all the application's modules in the application's [constructor](../basics/00-app-anatomy.md#app-constructor).
## Main ABCI Messages
@ -225,23 +231,23 @@ Unconfirmed transactions are relayed to peers only if they pass `CheckTx`.
`CheckTx()` can perform both _stateful_ and _stateless_ checks, but developers should strive to
make the checks **lightweight** because gas fees are not charged for the resources (CPU, data load...) used during the `CheckTx`.
In the Cosmos SDK, after [decoding transactions](./encoding.md), `CheckTx()` is implemented
In the Cosmos SDK, after [decoding transactions](./05-encoding.md), `CheckTx()` is implemented
to do the following checks:
1. Extract the `sdk.Msg`s from the transaction.
2. Perform _stateless_ checks by calling `ValidateBasic()` on each of the `sdk.Msg`s. This is done
first, as _stateless_ checks are less computationally expensive than _stateful_ checks. If
`ValidateBasic()` fail, `CheckTx` returns before running _stateful_ checks, which saves resources.
3. Perform non-module related _stateful_ checks on the [account](../basics/accounts.md). This step is mainly about checking
3. Perform non-module related _stateful_ checks on the [account](../basics/03-accounts.md). This step is mainly about checking
that the `sdk.Msg` signatures are valid, that enough fees are provided and that the sending account
has enough funds to pay for said fees. Note that no precise [`gas`](../basics/gas-fees.md) counting occurs here,
as `sdk.Msg`s are not processed. Usually, the [`AnteHandler`](../basics/gas-fees.md#antehandler) will check that the `gas` provided
has enough funds to pay for said fees. Note that no precise [`gas`](../basics/04-gas-fees.md) counting occurs here,
as `sdk.Msg`s are not processed. Usually, the [`AnteHandler`](../basics/04-gas-fees.md#antehandler) will check that the `gas` provided
with the transaction is superior to a minimum reference gas amount based on the raw transaction size,
in order to avoid spam with transactions that provide 0 gas.
`CheckTx` does **not** process `sdk.Msg`s - they only need to be processed when the canonical state need to be updated, which happens during `DeliverTx`.
Steps 2. and 3. are performed by the [`AnteHandler`](../basics/gas-fees.md#antehandler) in the [`RunTx()`](#runtx-antehandler-and-runmsgs)
Steps 2. and 3. are performed by the [`AnteHandler`](../basics/04-gas-fees.md#antehandler) in the [`RunTx()`](#runtx-antehandler-and-runmsgs)
function, which `CheckTx()` calls with the `runTxModeCheck` mode. During each step of `CheckTx()`, a
special [volatile state](#state-updates) called `checkState` is updated. This state is used to keep
track of the temporary changes triggered by the `CheckTx()` calls of each transaction without modifying
@ -263,7 +269,7 @@ The response contains:
* `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/v0.46.0/x/auth/ante/basic.go#L95-L95
* `Events ([]cmn.KVPair)`: Key-Value tags for filtering and indexing transactions (eg. by account). See [`event`s](./events.md) for more.
* `Events ([]cmn.KVPair)`: Key-Value tags for filtering and indexing transactions (eg. by account). See [`event`s](./08-events.md) for more.
* `Codespace (string)`: Namespace for the Code.
#### RecheckTx
@ -284,7 +290,7 @@ Before the first transaction of a given block is processed, a [volatile state](#
`DeliverTx` performs the **exact same steps as `CheckTx`**, with a little caveat at step 3 and the addition of a fifth step:
1. The `AnteHandler` does **not** check that the transaction's `gas-prices` is sufficient. That is because the `min-gas-prices` value `gas-prices` is checked against is local to the node, and therefore what is enough for one full-node might not be for another. This means that the proposer can potentially include transactions for free, although they are not incentivised to do so, as they earn a bonus on the total fee of the block they propose.
2. For each `sdk.Msg` in the transaction, route to the appropriate module's Protobuf [`Msg` service](../building-modules/msg-services.md). Additional _stateful_ checks are performed, and the branched multistore held in `deliverState`'s `context` is updated by the module's `keeper`. If the `Msg` service returns successfully, the branched multistore held in `context` is written to `deliverState` `CacheMultiStore`.
2. For each `sdk.Msg` in the transaction, route to the appropriate module's Protobuf [`Msg` service](../building-modules/03-msg-services.md). Additional _stateful_ checks are performed, and the branched multistore held in `deliverState`'s `context` is updated by the module's `keeper`. If the `Msg` service returns successfully, the branched multistore held in `context` is written to `deliverState` `CacheMultiStore`.
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:
@ -300,7 +306,7 @@ At any point, if `GasConsumed > GasWanted`, the function returns with `Code != 0
* `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.
* `Events ([]cmn.KVPair)`: Key-Value tags for filtering and indexing transactions (eg. by account). See [`event`s](./08-events.md) for more.
* `Codespace (string)`: Namespace for the Code.
## RunTx, AnteHandler, RunMsgs, PostHandler
@ -309,7 +315,7 @@ At any point, if `GasConsumed > GasWanted`, the function returns with `Code != 0
`RunTx` is called from `CheckTx`/`DeliverTx` to handle the transaction, with `runTxModeCheck` or `runTxModeDeliver` as parameter to differentiate between the two modes of execution. Note that when `RunTx` receives a transaction, it has already been decoded.
The first thing `RunTx` does upon being called is to retrieve the `context`'s `CacheMultiStore` by calling the `getContextForTx()` function with the appropriate mode (either `runTxModeCheck` or `runTxModeDeliver`). This `CacheMultiStore` is a branch of the main store, with cache functionality (for query requests), instantiated during `BeginBlock` for `DeliverTx` and during the `Commit` of the previous block for `CheckTx`. After that, two `defer func()` are called for [`gas`](../basics/gas-fees.md) management. They are executed when `runTx` returns and make sure `gas` is actually consumed, and will throw errors, if any.
The first thing `RunTx` does upon being called is to retrieve the `context`'s `CacheMultiStore` by calling the `getContextForTx()` function with the appropriate mode (either `runTxModeCheck` or `runTxModeDeliver`). This `CacheMultiStore` is a branch of the main store, with cache functionality (for query requests), instantiated during `BeginBlock` for `DeliverTx` and during the `Commit` of the previous block for `CheckTx`. After that, two `defer func()` are called for [`gas`](../basics/04-gas-fees.md) management. They are executed when `runTx` returns and make sure `gas` is actually consumed, and will throw errors, if any.
After that, `RunTx()` calls `ValidateBasic()` on each `sdk.Msg`in the `Tx`, which runs preliminary _stateless_ validity checks. If any `sdk.Msg` fails to pass `ValidateBasic()`, `RunTx()` returns with an error.
@ -317,7 +323,7 @@ Then, the [`anteHandler`](#antehandler) of the application is run (if it exists)
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/baseapp/baseapp.go#L647-L654
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.
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](./10-ocap.md) of the Cosmos SDK.
Finally, the [`RunMsgs()`](#runmsgs) function is called to process the `sdk.Msg`s in the `Tx`. In preparation of this step, just like with the `anteHandler`, both the `checkState`/`deliverState`'s `context` and `context`'s `CacheMultiStore` are branched using the `cacheTxContext()` function.
@ -329,19 +335,19 @@ The `AnteHandler` is a special handler that implements the `AnteHandler` interfa
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.
* 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`](./01-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.46.0/x/auth/ante/ante.go).
`BaseApp` holds an `anteHandler` as parameter that is initialized in the [application's constructor](../basics/00-app-anatomy.md#application-constructor). The most widely used `anteHandler` is the [`auth` module](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/auth/ante/ante.go).
Click [here](../basics/gas-fees.md#antehandler) for more on the `anteHandler`.
Click [here](../basics/04-gas-fees.md#antehandler) for more on the `anteHandler`.
### RunMsgs
`RunMsgs` is called from `RunTx` with `runTxModeCheck` as parameter to check the existence of a route for each message the transaction, and with `runTxModeDeliver` to actually process the `sdk.Msg`s.
First, it retrieves the `sdk.Msg`'s fully-qualified type name, by checking the `type_url` of the Protobuf `Any` representing the `sdk.Msg`. Then, using the application's [`msgServiceRouter`](#msg-service-router), it checks for the existence of `Msg` service method related to that `type_url`. At this point, if `mode == runTxModeCheck`, `RunMsgs` returns. Otherwise, if `mode == runTxModeDeliver`, the [`Msg` service](../building-modules/msg-services.md) RPC is executed, before `RunMsgs` returns.
First, it retrieves the `sdk.Msg`'s fully-qualified type name, by checking the `type_url` of the Protobuf `Any` representing the `sdk.Msg`. Then, using the application's [`msgServiceRouter`](#msg-service-router), it checks for the existence of `Msg` service method related to that `type_url`. At this point, if `mode == runTxModeCheck`, `RunMsgs` returns. Otherwise, if `mode == runTxModeDeliver`, the [`Msg` service](../building-modules/03-msg-services.md) RPC is executed, before `RunMsgs` returns.
### PostHandler
@ -362,9 +368,9 @@ The [`InitChain` ABCI message](https://docs.tendermint.com/master/spec/abci/abci
* [Consensus Parameters](https://docs.tendermint.com/master/spec/abci/apps.html#consensus-parameters) via `setConsensusParams`.
* [`checkState` and `deliverState`](#state-updates) via `setCheckState` and `setDeliverState`.
* The [block gas meter](../basics/gas-fees.md#block-gas-meter), with infinite gas to process genesis transactions.
* The [block gas meter](../basics/04-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.
Finally, the `InitChain(req abci.RequestInitChain)` method of `BaseApp` calls the [`initChainer()`](../basics/00-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/08-genesis.md#initgenesis) function of each of the application's modules.
### BeginBlock
@ -372,14 +378,14 @@ The [`BeginBlock` ABCI message](https://docs.tendermint.com/master/spec/abci/abc
* Initialize [`deliverState`](#state-updates) with the latest header using the `req abci.RequestBeginBlock` passed as parameter via the `setDeliverState` function.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/baseapp/baseapp.go#L386-L396
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://docs.tendermint.com/master/spec/abci/abci.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`.
This function also resets the [main gas meter](../basics/04-gas-fees.md#main-gas-meter).
* Initialize the [block gas meter](../basics/04-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/00-app-anatomy.md#beginblocker-and-endblock), which mainly runs the [`BeginBlocker()`](../building-modules/05-beginblock-endblock.md#beginblock) method of each of the application's modules.
* Set the [`VoteInfos`](https://docs.tendermint.com/master/spec/abci/abci.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`](./02-context.md) so that it can be used during `DeliverTx` and `EndBlock`.
### EndBlock
The [`EndBlock` ABCI message](https://docs.tendermint.com/master/spec/abci/abci.html#endblock) is sent from the underlying Tendermint engine after [`DeliverTx`](#delivertx) as been run for each transaction in the block. It allows developers to have logic be executed at the end of each block. In the Cosmos SDK, the bulk `EndBlock(req abci.RequestEndBlock)` method is to run the application's [`EndBlocker()`](../basics/app-anatomy.md#beginblocker-and-endblock), which mainly runs the [`EndBlocker()`](../building-modules/beginblock-endblock.md#beginblock) method of each of the application's modules.
The [`EndBlock` ABCI message](https://docs.tendermint.com/master/spec/abci/abci.html#endblock) is sent from the underlying Tendermint engine after [`DeliverTx`](#delivertx) as been run for each transaction in the block. It allows developers to have logic be executed at the end of each block. In the Cosmos SDK, the bulk `EndBlock(req abci.RequestEndBlock)` method is to run the application's [`EndBlocker()`](../basics/00-app-anatomy.md#beginblocker-and-endblock), which mainly runs the [`EndBlocker()`](../building-modules/05-beginblock-endblock.md#beginblock) method of each of the application's modules.
### Commit
@ -395,15 +401,11 @@ The [`Info` ABCI message](https://docs.tendermint.com/master/spec/abci/abci.html
### Query
The [`Query` ABCI message](https://docs.tendermint.com/master/spec/abci/abci.html#query-2) is used to serve queries received from the underlying consensus engine, including queries received via RPC like Tendermint RPC. It used to be the main entrypoint to build interfaces with the application, but with the introduction of [gRPC queries](../building-modules/query-services.md) in Cosmos SDK v0.40, its usage is more limited. The application must respect a few rules when implementing the `Query` method, which are outlined [here](https://docs.tendermint.com/master/spec/abci/apps.html#query).
The [`Query` ABCI message](https://docs.tendermint.com/master/spec/abci/abci.html#query-2) is used to serve queries received from the underlying consensus engine, including queries received via RPC like Tendermint RPC. It used to be the main entrypoint to build interfaces with the application, but with the introduction of [gRPC queries](../building-modules/04-query-services.md) in Cosmos SDK v0.40, its usage is more limited. The application must respect a few rules when implementing the `Query` method, which are outlined [here](https://docs.tendermint.com/master/spec/abci/apps.html#query).
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 split string (`split[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).
## Next {hide}
Learn more about [transactions](./transactions.md) {hide}
* 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/04-query-services.md#legacy-queriers).

48
docs/core/transactions.md → docs/docs/core/01-transactions.md
View File

@ -1,20 +1,26 @@
<!--
order: 2
-->
---
sidebar_position: 1
---
# Transactions
`Transactions` are objects created by end-users to trigger state changes in the application. {synopsis}
:::note Synopsis
`Transactions` are objects created by end-users to trigger state changes in the application.
:::
## Pre-requisite Readings
:::note
* [Anatomy of a Cosmos SDK Application](../basics/app-anatomy.md) {prereq}
### Pre-requisite Readings
* [Anatomy of a Cosmos SDK Application](../basics/00-app-anatomy.md)
:::
## Transactions
Transactions are comprised of metadata held in [contexts](./context.md) and [`sdk.Msg`s](../building-modules/messages-and-queries.md) that trigger state changes within a module through the module's Protobuf [`Msg` service](../building-modules/msg-services.md).
Transactions are comprised of metadata held in [contexts](./02-context.md) and [`sdk.Msg`s](../building-modules/02-messages-and-queries.md) that trigger state changes within a module through the module's Protobuf [`Msg` service](../building-modules/03-msg-services.md).
When users want to interact with an application and make state changes (e.g. sending coins), they create transactions. Each of a transaction's `sdk.Msg` must be signed using the private key associated with the appropriate account(s), before the transaction is broadcasted to the network. A transaction must then be included in a block, validated, and approved by the network through the consensus process. To read more about the lifecycle of a transaction, click [here](../basics/tx-lifecycle.md).
When users want to interact with an application and make state changes (e.g. sending coins), they create transactions. Each of a transaction's `sdk.Msg` must be signed using the private key associated with the appropriate account(s), before the transaction is broadcasted to the network. A transaction must then be included in a block, validated, and approved by the network through the consensus process. To read more about the lifecycle of a transaction, click [here](../basics/01-tx-lifecycle.md).
## Type Definition
@ -25,7 +31,7 @@ Transaction objects are Cosmos SDK types that implement the `Tx` interface
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/main/x/auth) module's `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/main/x/auth/spec) module, it first runs `ValidateBasic` on each message, then runs the `auth` module AnteHandler which calls `ValidateBasic` for the transaction itself.
* **ValidateBasic:** lightweight, [_stateless_](../basics/01-tx-lifecycle.md#types-of-checks) checks used by ABCI messages [`CheckTx`](./00-baseapp.md#checktx) and [`DeliverTx`](./00-baseapp.md#delivertx) to make sure transactions are not invalid. For example, the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth) module's `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/01-tx-lifecycle.md#ValidateBasic) methods, which perform basic validity checks on messages only. When [`runTx`](./00-baseapp.md#runtx) is checking a transaction created from the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/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).
@ -71,7 +77,7 @@ need to sign over the fees:
The use case is a multi-signer transaction, where one of the signers is appointed to gather all signatures, broadcast the signature and pay for fees, and the others only care about the transaction body. This generally allows for a better multi-signing UX. If Alice, Bob and Charlie are part of a 3-signer transaction, then Alice and Bob can both use `SIGN_MODE_DIRECT_AUX` to sign over the `TxBody` and their own signer info (no need an additional step to gather other signers' ones, like in `SIGN_MODE_DIRECT`), without specifying a fee in their SignDoc. Charlie can then gather both signatures from Alice and Bob, and
create the final transaction by appending a fee. Note that the fee payer of the transaction (in our case Charlie) must sign over the fees, so must use `SIGN_MODE_DIRECT` or `SIGN_MODE_LEGACY_AMINO_JSON`.
A concrete use case is implemented in [transaction tips](./tips.md): the tipper may use `SIGN_MODE_DIRECT_AUX` to specify a tip in the transaction, without signing over the actual transaction fees. Then, the fee payer appends fees inside the tipper's desired `TxBody`, and as an exchange for paying the fees and broadcasting the transaction, receives the tipper's transaction tips as payment.
A concrete use case is implemented in [transaction tips](./14-tips.md): the tipper may use `SIGN_MODE_DIRECT_AUX` to specify a tip in the transaction, without signing over the actual transaction fees. Then, the fee payer appends fees inside the tipper's desired `TxBody`, and as an exchange for paying the fees and broadcasting the transaction, receives the tipper's transaction tips as payment.
#### `SIGN_MODE_TEXTUAL`
@ -93,16 +99,16 @@ The next paragraphs will describe each of these components, in this order.
### Messages
::: tip
:::tip
Module `sdk.Msg`s are not to be confused with [ABCI Messages](https://docs.tendermint.com/master/spec/abci/abci.html#messages) which define interactions between the Tendermint and application layers.
:::
**Messages** (or `sdk.Msg`s) are module-specific objects that trigger state transitions within the scope of the module they belong to. Module developers define the messages for their module by adding methods to the Protobuf [`Msg` service](../building-modules/msg-services.md), and also implement the corresponding `MsgServer`.
**Messages** (or `sdk.Msg`s) are module-specific objects that trigger state transitions within the scope of the module they belong to. Module developers define the messages for their module by adding methods to the Protobuf [`Msg` service](../building-modules/03-msg-services.md), and also implement the corresponding `MsgServer`.
Each `sdk.Msg`s is related to exactly one Protobuf [`Msg` service](../building-modules/msg-services.md) RPC, defined inside each module's `tx.proto` file. A SDK app router automatically maps every `sdk.Msg` to a corresponding RPC. Protobuf generates a `MsgServer` interface for each module `Msg` service, and the module developer needs to implement this interface.
Each `sdk.Msg`s is related to exactly one Protobuf [`Msg` service](../building-modules/03-msg-services.md) RPC, defined inside each module's `tx.proto` file. A SDK app router automatically maps every `sdk.Msg` to a corresponding RPC. Protobuf generates a `MsgServer` interface for each module `Msg` service, and the module developer needs to implement this interface.
This design puts more responsibility on module developers, allowing application developers to reuse common functionalities without having to implement state transition logic repetitively.
To learn more about Protobuf `Msg` services and how to implement `MsgServer`, click [here](../building-modules/msg-services.md).
To learn more about Protobuf `Msg` services and how to implement `MsgServer`, click [here](../building-modules/03-msg-services.md).
While messages contain the information for state transition logic, a transaction's other metadata and relevant information are stored in the `TxBuilder` and `Context`.
@ -146,9 +152,9 @@ Once the transaction bytes are generated, there are currently three ways of broa
#### CLI
Application developers create entry points to the application by creating a [command-line interface](../core/cli.md), [gRPC and/or REST interface](../core/grpc_rest.md), typically found in the application's `./cmd` folder. These interfaces allow users to interact with the application through command-line.
Application developers create entry points to the application by creating a [command-line interface](../core/07-cli.md), [gRPC and/or REST interface](../core/06-grpc_rest.md), typically found in the application's `./cmd` folder. These interfaces allow users to interact with the application through command-line.
For the [command-line interface](../building-modules/module-interfaces.md#cli), module developers create subcommands to add as children to the application top-level transaction command `TxCmd`. CLI commands actually bundle all the steps of transaction processing into one simple command: creating messages, generating transactions and broadcasting. For concrete examples, see the [Interacting with a Node](../run-node/interact-node.md) section. An example transaction made using CLI looks like:
For the [command-line interface](../building-modules/09-module-interfaces.md#cli), module developers create subcommands to add as children to the application top-level transaction command `TxCmd`. CLI commands actually bundle all the steps of transaction processing into one simple command: creating messages, generating transactions and broadcasting. For concrete examples, see the [Interacting with a Node](../run-node/02-interact-node.md) section. An example transaction made using CLI looks like:
```bash
simd tx send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake
@ -156,24 +162,20 @@ simd tx send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake
#### gRPC
[gRPC](https://grpc.io) is the main component for the Cosmos SDK's RPC layer. Its principal usage 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:
[gRPC](https://grpc.io) is the main component for the Cosmos SDK's RPC layer. Its principal usage is in the context of modules' [`Query` services](../building-modules/04-query-services.md). 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.46.0/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.
Examples of broadcasting and simulating a transaction are shown [here](../run-node/txs.md#programmatically-with-go).
Examples of broadcasting and simulating a transaction are shown [here](../run-node/03-txs.md#programmatically-with-go).
#### REST
Each gRPC method has its corresponding REST endpoint, generated using [gRPC-gateway](https://github.com/grpc-ecosystem/grpc-gateway). Therefore, instead of using gRPC, you can also use HTTP to broadcast the same transaction, on the `POST /cosmos/tx/v1beta1/txs` endpoint.
An example can be seen [here](../run-node/txs.md#using-rest)
An example can be seen [here](../run-node/03-txs.md#using-rest)
#### Tendermint RPC
The three methods presented above are actually higher abstractions over the Tendermint RPC `/broadcast_tx_{async,sync,commit}` endpoints, documented [here](https://docs.tendermint.com/master/rpc/#/Tx). This means that you can use the Tendermint RPC endpoints directly to broadcast the transaction, if you wish so.
## Next {hide}
Learn about the [context](./context.md) {hide}

42
docs/core/context.md → docs/docs/core/02-context.md
View File

@ -1,35 +1,41 @@
<!--
order: 3
-->
---
sidebar_position: 1
---
# Context
The `context` is a data structure intended to be passed from function to function that carries information about the current state of the application. It provides access to a branched storage (a safe branch of the entire state) as well as useful objects and information like `gasMeter`, `block height`, `consensus parameters` and more. {synopsis}
:::note Synopsis
The `context` is a data structure intended to be passed from function to function that carries information about the current state of the application. It provides access to a branched storage (a safe branch of the entire state) as well as useful objects and information like `gasMeter`, `block height`, `consensus parameters` and more.
:::
:::note
## 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/00-app-anatomy.md)
* [Lifecycle of a Transaction](../basics/01-tx-lifecycle.md)
:::
## Context Definition
The Cosmos SDK `Context` is a custom data structure that contains Go's stdlib [`context`](https://pkg.go.dev/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.
The Cosmos SDK `Context` is a custom data structure that contains Go's stdlib [`context`](https://pkg.go.dev/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](./04-store.md#base-layer-kvstores) in the [`multistore`](./04-store.md#multistore) and retrieve transactional context such as the block header and gas meter.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/types/context.go#L17-L42
* **Base Context:** The base type is a Go [Context](https://pkg.go.dev/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`.
* **Multistore:** Every application's `BaseApp` contains a [`CommitMultiStore`](./04-store.md#multistore) which is provided when a `Context` is created. Calling the `KVStore()` and `TransientStore()` methods allows modules to fetch their respective [`KVStore`](./04-store.md#base-layer-kvstores) using their unique `StoreKey`.
* **Header:** The [header](https://docs.tendermint.com/master/spec/core/data_structures.html#header) is a Blockchain type. It carries important information about the state of the blockchain, such as block height and proposer of the current block.
* **Header Hash:** The current block header hash, obtained during `abci.RequestBeginBlock`.
* **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 do 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).
* **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/01-tx-lifecycle.md), some of which do not have any understanding of transaction types. Thus, transactions are marshaled into the generic `[]byte` type using some kind of [encoding format](./05-encoding.md) such as [Amino](./05-encoding.md).
* **Logger:** A `logger` from the Tendermint libraries. Learn more about logs [here](https://docs.tendermint.com/master/nodes/logging.html). Modules call this method to create their own unique module-specific logger.
* **VoteInfo:** A list of the ABCI type [`VoteInfo`](https://docs.tendermint.com/master/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.
* **Gas Meters:** Specifically, a [`gasMeter`](../basics/04-gas-fees.md#main-gas-meter) for the transaction currently being processed using the context and a [`blockGasMeter`](../basics/04-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/04-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**.
* **Min Gas Price:** The minimum [gas](../basics/04-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://docs.tendermint.com/master/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
* **Event Manager:** The event manager allows any caller with access to a `Context` to emit [`Events`](./08-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:
* **Priority:** The transaction priority, only relevant in `CheckTx`.
@ -67,14 +73,14 @@ goes wrong. The pattern of usage for a Context is as follows:
1. A process receives a Context `ctx` from its parent process, which provides information needed to
perform the process.
2. The `ctx.ms` is a **branched store**, i.e. a branch of the [multistore](./store.md#multistore) is made so that the process can make changes to the state as it executes, without changing the original`ctx.ms`. This is useful to protect the underlying multistore in case the changes need to be reverted at some point in the execution.
2. The `ctx.ms` is a **branched store**, i.e. a branch of the [multistore](./04-store.md#multistore) is made so that the process can make changes to the state as it executes, without changing the original`ctx.ms`. This is useful to protect the underlying multistore in case the changes need to be reverted at some point in the execution.
3. The process may read and write from `ctx` as it is executing. It may call a subprocess and pass
`ctx` to it as needed.
4. When a subprocess returns, it checks if the result is a success or failure. If a failure, nothing
needs to be done - the branch `ctx` is simply discarded. If successful, the changes made to
the `CacheMultiStore` can be committed to the original `ctx.ms` via `Write()`.
For example, here is a snippet from the [`runTx`](./baseapp.md#runtx-antehandler-runmsgs-posthandler) function in [`baseapp`](./baseapp.md):
For example, here is a snippet from the [`runTx`](./00-baseapp.md#runtx-antehandler-runmsgs-posthandler) function in [`baseapp`](./00-baseapp.md):
```go
runMsgCtx, msCache := app.cacheTxContext(ctx, txBytes)
@ -93,11 +99,7 @@ Here is the process:
1. Prior to calling `runMsgs` on the message(s) in the transaction, it uses `app.cacheTxContext()`
to branch and cache the context and multistore.
2. `runMsgCtx` - the context with branched store, is used in `runMsgs` to return a result.
3. If the process is running in [`checkTxMode`](./baseapp.md#checktx), there is no need to write the
3. If the process is running in [`checkTxMode`](./00-baseapp.md#checktx), there is no need to write the
changes - the result is returned immediately.
4. If the process is running in [`deliverTxMode`](./baseapp.md#delivertx) and the result indicates
4. If the process is running in [`deliverTxMode`](./00-baseapp.md#delivertx) and the result indicates
a successful run over all the messages, the branched multistore is written back to the original.
## Next {hide}
Learn about the [node client](./node.md) {hide}

32
docs/core/node.md → docs/docs/core/03-node.md
View File

@ -1,14 +1,20 @@
<!--
order: 4
-->
---
sidebar_position: 1
---
# Node Client (Daemon)
The main endpoint of a Cosmos SDK application is the daemon client, otherwise known as the full-node client. The full-node runs the state-machine, starting from a genesis file. It connects to peers running the same client in order to receive and relay transactions, block proposals and signatures. The full-node is constituted of the application, defined with the Cosmos SDK, and of a consensus engine connected to the application via the ABCI. {synopsis}
:::note Synopsis
The main endpoint of a Cosmos SDK application is the daemon client, otherwise known as the full-node client. The full-node runs the state-machine, starting from a genesis file. It connects to peers running the same client in order to receive and relay transactions, block proposals and signatures. The full-node is constituted of the application, defined with the Cosmos SDK, and of a consensus engine connected to the application via the ABCI.
:::
## Pre-requisite Readings
:::note
* [Anatomy of an SDK application](../basics/app-anatomy.md) {prereq}
### Pre-requisite Readings
* [Anatomy of an SDK application](../basics/00-app-anatomy.md)
:::
## `main` function
@ -16,8 +22,8 @@ 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 [`encodingCodec`](./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).
* First, an [`encodingCodec`](./05-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/03-accounts.md#addresses).
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/types/config.go#L14-L29
* 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).
@ -52,7 +58,7 @@ Note that an `appCreator` is a function that fulfills the `AppCreator` signature
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/server/types/app.go#L57-L59
In practice, the [constructor of the application](../basics/app-anatomy.md#constructor-function) is passed as the `appCreator`.
In practice, the [constructor of the application](../basics/00-app-anatomy.md#constructor-function) is passed as the `appCreator`.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/simapp/simd/cmd/root.go#L246-L295
@ -60,7 +66,7 @@ Then, the instance of `app` is used to instantiate a new Tendermint node:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/server/start.go#L291-L294
The Tendermint node can be created with `app` because the latter satisfies the [`abci.Application` interface](https://github.com/tendermint/tendermint/blob/v0.34.21/abci/types/application.go#L7-L32) (given that `app` extends [`baseapp`](./baseapp.md)). As part of the `node.New` 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, `node.New` 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.
The Tendermint node can be created with `app` because the latter satisfies the [`abci.Application` interface](https://github.com/tendermint/tendermint/blob/v0.34.21/abci/types/application.go#L7-L32) (given that `app` extends [`baseapp`](./00-baseapp.md)). As part of the `node.New` 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, `node.New` 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`](./00-baseapp.md#initchain) on the application to initialize the state from the genesis file.
Once the Tendermint node is instantiated and in sync with the application, the node can be started:
@ -70,8 +76,4 @@ Upon starting, the node will bootstrap its RPC and P2P server and start dialing
## Other commands
To discover how to concretely run a node and interact with it, please refer to our [Running a Node, API and CLI](../run-node/README.md) guide.
## Next {hide}
Learn about the [store](./store.md) {hide}
To discover how to concretely run a node and interact with it, please refer to our [Running a Node, API and CLI](../run-node/01-run-node.md) guide.

40
docs/core/store.md → docs/docs/core/04-store.md
View File

@ -1,18 +1,24 @@
<!--
order: 5
-->
---
sidebar_position: 1
---
# Store
A store is a data structure that holds the state of the application. {synopsis}
:::note Synopsis
A store is a data structure that holds the state of the application.
:::
## Pre-requisite Readings
:::note
* [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
### Pre-requisite Readings
* [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md)
:::
## 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.
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/06-keeper.md) of the module that declared the store.
```text
+-----------------------------------------------------+
@ -64,7 +70,7 @@ The `GetStoreType` is a simple method that returns the type of store, whereas a
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/store/types/store.go#L247-L277
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)
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](./02-context.md#Store-branching)
### Commit Store
@ -76,7 +82,7 @@ The `Committer` is an interface that defines methods to persist changes to disk:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/store/types/store.go#L21-L28
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`.
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](./10-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`.
The Cosmos SDK comes with many types of stores, the most used being [`CommitMultiStore`](#multistore), [`KVStore`](#kvstore) and [`GasKv` store](#gaskv-store). [Other types of stores](#other-stores) include `Transient` and `TraceKV` stores.
@ -100,7 +106,7 @@ As for concrete implementation, the [`rootMulti.Store`] is the go-to implementat
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/store/rootmulti/store.go#L38-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).
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`](./00-baseapp.md).
### CacheMultiStore
@ -116,9 +122,9 @@ Whenever the `rootMulti.Store` needs to be branched, a [`cachemulti.Store`](http
A `KVStore` is a simple key-value store used to store and retrieve data. A `CommitKVStore` is a `KVStore` that also implements a `Committer`. By default, stores mounted in `baseapp`'s main `CommitMultiStore` are `CommitKVStore`s. The `KVStore` interface is primarily used to restrict modules from accessing the committer.
Individual `KVStore`s are used by modules to manage a subset of the global state. `KVStores` can be accessed by objects that hold a specific key. This `key` should only be exposed to the [`keeper`](../building-modules/keeper.md) of the module that defines the store.
Individual `KVStore`s are used by modules to manage a subset of the global state. `KVStores` can be accessed by objects that hold a specific key. This `key` should only be exposed to the [`keeper`](../building-modules/06-keeper.md) of the module that defines the store.
`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.
`CommitKVStore`s are declared by proxy of their respective `key` and mounted on the application's [multistore](#multistore) in the [main application file](../basics/00-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.46.0/store/types/store.go#L192-L226
@ -160,7 +166,7 @@ This type of store is useful to persist information that is only relevant per-bl
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/params/types/subspace.go#L21-L31
Transient stores are typically accessed via the [`context`](./context.md) via the `TransientStore()` method:
Transient stores are typically accessed via the [`context`](./02-context.md) via the `TransientStore()` method:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/types/context.go#L264-L267
@ -188,7 +194,7 @@ This is the type used whenever an IAVL Store needs to be branched to create an i
### `GasKv` Store
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.46.0/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.
Cosmos SDK applications use [`gas`](../basics/04-gas-fees.md) to track resources usage and prevent spam. [`GasKv.Store`](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/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.46.0/store/gaskv/store.go#L11-L17
@ -196,7 +202,7 @@ When methods of the parent `KVStore` are called, `GasKv.Store` automatically con
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/store/types/gas.go#L219-L228
By default, all `KVStores` are wrapped in `GasKv.Stores` when retrieved. This is done in the `KVStore()` method of the [`context`](./context.md):
By default, all `KVStores` are wrapped in `GasKv.Stores` when retrieved. This is done in the `KVStore()` method of the [`context`](./02-context.md):
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/types/context.go#L259-L262
@ -275,7 +281,3 @@ This store can optionally be configured to use a different backend database inst
## SMT Store
`store/v2alpha1/smt.Store` maps values into a Sparse Merkle Tree (SMT), and supports a `BasicKVStore` interface as well as methods for cryptographic proof generation.
## Next {hide}
Learn about [encoding](./encoding.md) {hide}

36
docs/core/encoding.md → docs/docs/core/05-encoding.md
View File

@ -1,14 +1,20 @@
<!--
order: 6
-->
---
sidebar_position: 1
---
# Encoding
While encoding in the Cosmos SDK used to be mainly handled by `go-amino` codec, the Cosmos SDK is moving towards using `gogoprotobuf` for both state and client-side encoding. {synopsis}
:::note Synopsis
While encoding in the Cosmos SDK used to be mainly handled by `go-amino` codec, the Cosmos SDK is moving towards using `gogoprotobuf` for both state and client-side encoding.
:::
## Pre-requisite Readings
:::note
* [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
### Pre-requisite Readings
* [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md)
:::
## Encoding
@ -107,7 +113,7 @@ In addition to [following official Protocol Buffer guidelines](https://developer
### Transaction Encoding
Another important use of Protobuf is the encoding and decoding of
[transactions](./transactions.md). Transactions are defined by the application or
[transactions](./01-transactions.md). Transactions are defined by the application or
the Cosmos SDK but are then passed to the underlying consensus engine to be relayed to
other peers. Since the underlying consensus engine is agnostic to the application,
the consensus engine accepts only transactions in the form of raw bytes.
@ -117,7 +123,7 @@ the consensus engine accepts only transactions in the form of raw bytes.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/types/tx_msg.go#L72-L76
A standard implementation of both these objects can be found in the [`auth` module](../../x/auth/spec/README.md):
A standard implementation of both these objects can be found in the [`auth` module](../modules/auth/README.md):
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/auth/tx/decoder.go
@ -127,7 +133,7 @@ See [ADR-020](../architecture/adr-020-protobuf-transaction-encoding.md) for deta
### Interface Encoding and Usage of `Any`
The Protobuf DSL is strongly typed, which can make inserting variable-typed fields difficult. Imagine we want to create a `Profile` protobuf message that serves as a wrapper over [an account](../basics/accounts.md):
The Protobuf DSL is strongly typed, which can make inserting variable-typed fields difficult. Imagine we want to create a `Profile` protobuf message that serves as a wrapper over [an account](../basics/03-accounts.md):
```proto
message Profile {
@ -138,7 +144,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?
In this `Profile` example, we hardcoded `account` as a `BaseAccount`. However, there are several other types of [user accounts related to vesting](../modules/vesting/README.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.46.0/x/auth/types/account.go#L301-L324
@ -237,9 +243,9 @@ A real-life example of encoding the pubkey as `Any` inside the Validator struct
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)
* [`Msg`s](../building-modules/02-messages-and-queries.md#messages)
* [Query services](../building-modules/04-query-services.md)
* [genesis](../building-modules/08-genesis.md)
#### Naming and conventions
@ -292,7 +298,3 @@ A correct YAML output can be obtained through ProtoJSON, using the `JSONToYAML`
For example:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/auth/types/account.go#L139-L151
## Next {hide}
Learn about [gRPC, REST and other endpoints](./grpc_rest.md) {hide}

28
docs/core/grpc_rest.md → docs/docs/core/06-grpc_rest.md
View File

@ -1,10 +1,12 @@
<!--
order: 7
-->
---
sidebar_position: 1
---
# gRPC, REST, and Tendermint Endpoints
This document presents an overview of all the endpoints a node exposes: gRPC, REST as well as some other endpoints. {synopsis}
:::note Synopsis
This document presents an overview of all the endpoints a node exposes: gRPC, REST as well as some other endpoints.
:::
## An Overview of All Endpoints
@ -14,7 +16,7 @@ Each node exposes the following endpoints for users to interact with a node, eac
* the REST server (default port: `1317`),
* the Tendermint RPC endpoint (default port: `26657`).
::: tip
:::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.
:::
@ -22,11 +24,11 @@ The node also exposes some other endpoints, such as the Tendermint P2P endpoint,
In the Cosmos SDK, Protobuf is the main [encoding](./encoding) library. This brings a wide range of Protobuf-based tools that can be plugged into the Cosmos SDK. One such tool is [gRPC](https://grpc.io), a modern open-source high performance RPC framework that has decent client support in several languages.
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:
Each module exposes a [Protobuf `Query` service](../building-modules/02-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.46.0/server/types/app.go#L45-L47
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.
Note: It is not possible to expose any [Protobuf `Msg` service](../building-modules/02-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/03-txs.md) 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`:
@ -37,7 +39,7 @@ The `grpc.Server` is a concrete gRPC server, which spawns and serves all gRPC qu
`~/.simapp` is the directory where the node's configuration and databases are stored. By default, it's set to `~/.{app_name}`.
:::
Once the gRPC server is started, you can send requests to it using a gRPC client. Some examples are given in our [Interact with the Node](../run-node/interact-node.md#using-grpc) tutorial.
Once the gRPC server is started, you can send requests to it using a gRPC client. Some examples are given in our [Interact with the Node](../run-node/02-interact-node.md#using-grpc) tutorial.
An overview of all available gRPC endpoints shipped with the Cosmos SDK is [Protobuf documentation](https://buf.build/cosmos/cosmos-sdk).
@ -83,16 +85,12 @@ Some Tendermint RPC endpoints are directly related to the Cosmos SDK:
* `/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.
* `/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](./01-transactions.md#broadcasting-the-transaction), but they all use these 3 Tendermint RPCs under the hood.
## Comparison Table
| Name | Advantages | Disadvantages |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| gRPC | - can use code-generated stubs in various languages<br>- supports streaming and bidirectional communication (HTTP2)<br>- small wire binary sizes, faster transmission | - based on HTTP2, not available in browsers<br>- learning curve (mostly due to Protobuf) |
| REST | - ubiquitous<br>- client libraries in all languages, faster implementation<br> | - only supports unary request-response communication (HTTP1.1)<br>- bigger over-the-wire message sizes (JSON) |
| gRPC | - can use code-generated stubs in various languages <br /> - supports streaming and bidirectional communication (HTTP2) <br /> - small wire binary sizes, faster transmission | - based on HTTP2, not available in browsers <br /> - learning curve (mostly due to Protobuf) |
| REST | - ubiquitous <br/> - client libraries in all languages, faster implementation <br /> | - only supports unary request-response communication (HTTP1.1) <br/> - bigger over-the-wire message sizes (JSON) |
| Tendermint RPC | - easy to use | - bigger over-the-wire message sizes (JSON) |
## Next {hide}
Learn about [the CLI](./cli.md) {hide}

40
docs/core/cli.md → docs/docs/core/07-cli.md
View File

@ -1,10 +1,12 @@
<!--
order: 8
-->
---
sidebar_position: 1
---
# Command-Line Interface
This document describes how command-line interface (CLI) works on a high-level, for an [**application**](../basics/app-anatomy.md). A separate document for implementing a CLI for a Cosmos SDK [**module**](../building-modules/intro.md) can be found [here](../building-modules/module-interfaces.md#cli). {synopsis}
:::note Synopsis
This document describes how command-line interface (CLI) works on a high-level, for an [**application**](../basics/00-app-anatomy.md). A separate document for implementing a CLI for a Cosmos SDK [**module**](../building-modules/01-intro.md) can be found [here](../building-modules/09-module-interfaces.md#cli).
:::
## Command-Line Interface
@ -22,12 +24,12 @@ 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 subcommand `bank` to indicate which module to route the command to ([`x/bank`](../modules/bank/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).
The CLI interacts with a [node](../core/node.md) to handle this command. The interface itself is defined in a `main.go` file.
The CLI interacts with a [node](../core/03-node.md) to handle this command. The interface itself is defined in a `main.go` file.
### Building the CLI
@ -35,7 +37,7 @@ The `main.go` file needs to have a `main()` function that creates a root command
* **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.
* **instantiating the `codec`** by calling the application's `MakeCodec()` function (called `MakeTestEncodingConfig` in `simapp`). The [`codec`](../core/05-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://pkg.go.dev/github.com/spf13/cobra#Command.Execute) the root command. See an example of `main()` function from the `simapp` application:
@ -52,9 +54,9 @@ 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.46.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.46.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.46.0/server) to learn more.
* **Status** command from the Cosmos SDK rpc client tools, which prints information about the status of the connected [`Node`](../core/03-node.md). The Status of a node includes `NodeInfo`,`SyncInfo` and `ValidatorInfo`.
* **Keys** [commands](https://github.com/cosmos/cosmos-sdk/blob/v0.46.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.46.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/00-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](https://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.46.0/server) to learn more.
* [**Transaction**](#transaction-commands) commands.
* [**Query**](#query-commands) commands.
@ -76,15 +78,15 @@ The root-level `status` and `keys` subcommands are common across most applicatio
### Transaction Commands
[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 `txCommand` is generally added to the `rootCmd`:
[Transactions](./01-transactions.md) are objects wrapping [`Msg`s](../building-modules/02-messages-and-queries.md#messages) that trigger state changes. To enable the creation of transactions using the CLI interface, a function `txCommand` is generally added to the `rootCmd`:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/simapp/simd/cmd/root.go#L175-L181
This `txCommand` 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.
* **Sign command** from the [`auth`](../modules/auth/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.
* **All [module transaction commands](../building-modules/09-module-interfaces.md#transaction-commands)** the application is dependent on, retrieved by using the [basic module manager's](../building-modules/01-module-manager.md#basic-manager) `AddTxCommands()` function.
Here is an example of a `txCommand` aggregating these subcommands from the `simapp` application:
@ -92,7 +94,7 @@ Here is an example of a `txCommand` aggregating these subcommands from the `sima
### 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 queries using the CLI interface, a function `queryCommand` is generally added to the `rootCmd`:
[**Queries**](../building-modules/02-messages-and-queries.md#queries) are objects that allow users to retrieve information about the application's state. To enable the creation of queries using the CLI interface, a function `queryCommand` is generally added to the `rootCmd`:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/simapp/simd/cmd/root.go#L175-L181
@ -102,7 +104,7 @@ This `queryCommand` function adds all the queries available to end-users for the
* **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.
* **All [module query commands](../building-modules/09-module-interfaces.md#query-commands)** the application is dependent on, retrieved by using the [basic module manager's](../building-modules/01-module-manager.md#basic-manager) `AddQueryCommands()` function.
Here is an example of a `queryCommand` aggregating subcommands from the `simapp` application:
@ -110,11 +112,11 @@ Here is an example of a `queryCommand` aggregating subcommands from the `simapp`
## Flags
Flags are used to modify commands; developers can include them in a `flags.go` file with their CLI. Users can explicitly include them in commands or pre-configure them by inside their [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml). Commonly pre-configured flags include the `--node` to connect to and `--chain-id` of the blockchain the user wishes to interact with.
Flags are used to modify commands; developers can include them in a `flags.go` file with their CLI. Users can explicitly include them in commands or pre-configure them by inside their [`app.toml`](../run-node/02-interact-node.md#configuring-the-node-using-apptoml). Commonly pre-configured flags include the `--node` to connect to and `--chain-id` of the blockchain the user wishes to interact with.
A _persistent_ flag (as opposed to a _local_ flag) added to a command transcends all of its children: subcommands will inherit the configured values for these flags. Additionally, all flags have default values when they are added to commands; some toggle an option off but others are empty values that the user needs to override to create valid commands. A flag can be explicitly marked as _required_ so that an error is automatically thrown if the user does not provide a value, but it is also acceptable to handle unexpected missing flags differently.
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:
Flags are added to commands directly (generally in the [module's CLI file](../building-modules/09-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.46.0/simapp/simd/cmd/root.go#L210-L210
@ -150,7 +152,3 @@ Here is an example of an `PersistentPreRun()` function from `simapp`:
The `SetCmdClientContextHandler` call reads persistent flags via `ReadPersistentCommandFlags` which creates a `client.Context` and sets that on the root command's `Context`.
The `InterceptConfigsPreRunHandler` call creates a viper literal, default `server.Context`, and a logger and sets that on the root command's `Context`. The `server.Context` will be modified and saved to disk via the internal `interceptConfigs` call, which either reads or creates a Tendermint configuration based on the home path provided. In addition, `interceptConfigs` also reads and loads the application configuration, `app.toml`, and binds that to the `server.Context` viper literal. This is vital so the application can get access to not only the CLI flags, but also to the application configuration values provided by this file.
## Next {hide}
Learn about [events](./events.md) {hide}

49
docs/core/events.md → docs/docs/core/08-events.md
View File

@ -1,15 +1,20 @@
<!--
order: 9
-->
---
sidebar_position: 1
---
# Events
`Event`s are objects that contain information about the execution of the application. They are mainly used by service providers like block explorers and wallet to track the execution of various messages and index transactions. {synopsis}
:::note Synopsis
`Event`s are objects that contain information about the execution of the application. They are mainly used by service providers like block explorers and wallet to track the execution of various messages and index transactions.
:::
## Pre-requisite Readings
:::note
* [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}
### Pre-requisite Readings
* [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md)
* [Tendermint Documentation on Events](https://docs.tendermint.com/master/spec/abci/abci.html#events)
:::
## Typed Events
@ -23,23 +28,23 @@ 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}`.
::: tip
:::tip
To parse the attribute values as strings, make sure to add `'` (single quotes) around each attribute value.
:::
_Typed Events_ are Protobuf-defined [messages](../architecture/adr-032-typed-events.md) used by the Cosmos SDK
for emitting and querying Events. They are defined in a `event.proto` file, on a **per-module basis**.
They are triggered from the module's Protobuf [`Msg` service](../building-modules/msg-services.md)
They are triggered from the module's Protobuf [`Msg` service](../building-modules/03-msg-services.md)
by using the [`EventManager`](#eventmanager), where they are read as `proto.Message`.
In addition, each module documents its Events under `spec/xx_events.md`.
Lastly, 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`](./00-baseapp.md#beginblock)
* [`EndBlock`](./00-baseapp.md#endblock)
* [`CheckTx`](./00-baseapp.md#checktx)
* [`DeliverTx`](./00-baseapp.md#delivertx)
### Examples
@ -48,10 +53,10 @@ The following examples show how to query Events using the Cosmos SDK.
| Event | Description |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tx.height=23` | Query all transactions at height 23 |
| `message.action='/cosmos.bank.v1beta1.Msg/Send'` | Query all transactions containing a x/bank `Send` [Service `Msg`](../building-modules/msg-services.md). Note the `'`s around the value. |
| `message.action='send'` | Query all transactions containing a x/bank `Send` [legacy `Msg`](../building-modules/msg-services.md#legacy-amino-msgs). Note the `'`s around the value. |
| `message.action='/cosmos.bank.v1beta1.Msg/Send'` | Query all transactions containing a x/bank `Send` [Service `Msg`](../building-modules/03-msg-services.md). Note the `'`s around the value. |
| `message.action='send'` | Query all transactions containing a x/bank `Send` [legacy `Msg`](../building-modules/03-msg-services.md#legacy-amino-msgs). Note the `'`s around the value. |
| `message.module='bank'` | Query all transactions containing messages from the x/bank module. Note the `'`s around the value. |
| `create_validator.validator='cosmosval1...'` | x/staking-specific Event, see [x/staking SPEC](../../../cosmos-sdk/x/staking/spec/07_events.md). |
| `create_validator.validator='cosmosval1...'` | x/staking-specific Event, see [x/staking SPEC](../modules/staking/README.md). |
## EventManager
@ -69,7 +74,7 @@ an Event in the `EventManager`.
Module developers should handle Event emission via the `EventManager#EmitTypedEvent` in each message
`Handler` and in each `BeginBlock`/`EndBlock` handler. The `EventManager` is accessed via
the [`Context`](./context.md), where Event should be already registered, and emitted like this:
the [`Context`](./02-context.md), where Event should be already registered, and emitted like this:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/group/keeper/msg_server.go#L89-L92
@ -82,7 +87,7 @@ func NewHandler(keeper Keeper) sdk.Handler {
switch msg := msg.(type) {
```
See the [`Msg` services](../building-modules/msg-services.md) concept doc for a more detailed
See the [`Msg` services](../building-modules/03-msg-services.md) concept doc for a more detailed
view on how to typically implement Events and use the `EventManager` in modules.
## Subscribing to Events
@ -124,7 +129,7 @@ Subscribing to this Event would be done like so:
}
```
where `ownerAddress` is an address following the [`AccAddress`](../basics/accounts.md#addresses) format.
where `ownerAddress` is an address following the [`AccAddress`](../basics/03-accounts.md#addresses) format.
## Events
@ -133,7 +138,3 @@ Previously, the Cosmos SDK supported emitting Events that were defined in `types
This is why this methods as been deprecated, and replaced by [Typed Events](#typed-events).
To learn more about the previous way of defining events, please refer to the [previous SDK documentation](https://docs.cosmos.network/v0.45/core/events.html#events-2).
## Next {hide}
Learn about Cosmos SDK [telemetry](./telemetry.md) {hide}

14
docs/core/telemetry.md → docs/docs/core/09-telemetry.md
View File

@ -1,10 +1,12 @@
<!--
order: 10
-->
---
sidebar_position: 1
---
# Telemetry
Gather relevant insights about your application and modules with custom metrics and telemetry. {synopsis}
:::note Synopsis
Gather relevant insights about your application and modules with custom metrics and telemetry.
:::
The Cosmos SDK enables operators and developers to gain insight into the performance and behavior of
their application through the use of the `telemetry` package. To enable telemetrics, set `telemetry.enabled = true` in the app.toml config file.
@ -124,7 +126,3 @@ The following examples expose too much cardinality and may not even prove to be
| `store_iavl_delete` | Duration of an IAVL `Store#Delete` call | ms | summary |
| `store_iavl_commit` | Duration of an IAVL `Store#Commit` call | ms | summary |
| `store_iavl_query` | Duration of an IAVL `Store#Query` call | ms | summary |
## Next {hide}
Learn about the [object-capability](./ocap.md) model {hide}

11
docs/core/ocap.md → docs/docs/core/10-ocap.md
View File

@ -1,6 +1,6 @@
<!--
order: 11
-->
---
sidebar_position: 1
---
# Object-Capability Model
@ -71,8 +71,5 @@ In the Cosmos SDK, you can see the application of this principle in simapp.
The following diagram shows the current dependencies between keepers.
![Keeper dependencies](../uml/svg/keeper_dependencies.svg)
![Keeper dependencies](https://raw.githubusercontent.com/cosmos/cosmos-sdk/release/v0.46.x/docs/uml/svg/keeper_dependencies.svg)
## Next {hide}
Learn about the [`runTx` middleware](./runtx_middleware.md) {hide}

10
docs/core/runtx_middleware.md → docs/docs/core/11-runtx_middleware.md
View File

@ -1,6 +1,6 @@
<!--
order: 12
-->
---
sidebar_position: 1
---
# RunTx recovery middleware
@ -63,7 +63,3 @@ customHandler := func(recoveryObj interface{}) error {
baseApp := baseapp.NewBaseApp(...)
baseApp.AddRunTxRecoveryHandler(customHandler)
```
## Next {hide}
Learn about the [IBC](./../ibc/README.md) protocol {hide}

10
docs/core/simulation.md → docs/docs/core/12-simulation.md
View File

@ -1,6 +1,6 @@
<!--
order: 13
-->
---
sidebar_position: 1
---
# Cosmos Blockchain Simulator
@ -55,7 +55,7 @@ In addition to the various inputs and commands, the simulator runs in three mode
This allows for a more controlled and deterministic simulation setup while allowing the state space to still be pseudo-randomly simulated.
The list of available parameters are listed [here](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/simapp/config.go#L33-L57).
::: tip
:::tip
These modes are not mutually exclusive. So you can for example run a randomly
generated genesis state (`1`) with manually generated simulation params (`3`).
:::
@ -97,5 +97,5 @@ Here are some suggestions when encountering a simulation failure:
Learn how you can integrate the simulation into your Cosmos SDK-based application:
* Application Simulation Manager
* [Building modules: Simulator](../building-modules/simulator.md)
* [Building modules: Simulator](../building-modules/13-simulator.md)
* Simulator tests

6
docs/core/proto-docs.md → docs/docs/core/13-proto-docs.md
View File

@ -1,6 +1,6 @@
<!--
order: 14
-->
---
sidebar_position: 1
---
# Protobuf Documentation

10
docs/core/tips.md → docs/docs/core/14-tips.md
View File

@ -1,10 +1,12 @@
<!--
order: 14
-->
---
sidebar_position: 1
---
# Transaction Tips
Transaction tips are a mechanism to pay for transaction fees using another denom than the native fee denom of the chain. They are still in beta, and are not included by default in the SDK. {synopsis}
:::note Synopsis
Transaction tips are a mechanism to pay for transaction fees using another denom than the native fee denom of the chain. They are still in beta, and are not included by default in the SDK.
:::
## Context

20
docs/core/upgrade.md → docs/docs/core/15-upgrade.md
View File

@ -1,20 +1,22 @@
<!--
order: 15
-->
---
sidebar_position: 1
---
# In-Place Store Migrations
::: warning
:::warning
Read and understand all the in-place store migration documentation before you run a migration on a live chain.
:::
Upgrade your app modules smoothly with custom in-place store migration logic. {synopsis}
:::note Synopsis
Upgrade your app modules smoothly with custom in-place store migration logic.
:::
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.
* Perform upgrades in place, which 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.
* Perform upgrades in place, which significantly decrease the upgrade time for chains with a larger state. Use the [Module Upgrade Guide](../building-modules/12-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.
@ -61,7 +63,7 @@ app.UpgradeKeeper.SetUpgradeHandler("my-plan", func(ctx sdk.Context, plan upgrad
})
```
To learn more about configuring migration scripts for your modules, see the [Module Upgrade Guide](../building-modules/upgrade.md).
To learn more about configuring migration scripts for your modules, see the [Module Upgrade Guide](../building-modules/12-upgrade.md).
### Order Of Migrations
@ -130,7 +132,7 @@ The Cosmos SDK offers modules that the application developer can import in their
You can write your own `InitGenesis` function for an imported module. To do this, manually trigger your custom genesis function in the upgrade handler.
::: warning
:::warning
You MUST manually set the consensus version in the version map passed to the `UpgradeHandler` function. Without this, the SDK will run the Module's existing `InitGenesis` code even if you triggered your custom function in the `UpgradeHandler`.
:::
@ -157,4 +159,4 @@ You can sync a full node to an existing blockchain which has been upgraded using
To successfully sync, you must start with the initial binary that the blockchain started with at genesis. If all Software Upgrade Plans contain binary instruction, then you can run Cosmovisor with auto-download option to automatically handle downloading and switching to the binaries associated with each sequential upgrade. Otherwise, you need to manually provide all binaries to Cosmovisor.
To learn more about Cosmovisor, see the [Cosmovisor Quick Start](../run-node/cosmovisor.md).
To learn more about Cosmovisor, see the [Cosmovisor Quick Start](../run-node/06-cosmovisor.md).

5
docs/docs/core/_category_.json Normal file
View File

@ -0,0 +1,5 @@
{
"label": "Core Concepts",
"position": 2,
"link": null
}

0
docs/core/baseapp_state-begin_block.png → docs/docs/core/baseapp_state-begin_block.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 20 KiB

After

Width:  |  Height:  |  Size: 20 KiB

0
docs/core/baseapp_state-checktx.png → docs/docs/core/baseapp_state-checktx.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 80 KiB

After

Width:  |  Height:  |  Size: 80 KiB

0
docs/core/baseapp_state-commit.png → docs/docs/core/baseapp_state-commit.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 46 KiB

0
docs/core/baseapp_state-deliver_tx.png → docs/docs/core/baseapp_state-deliver_tx.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 58 KiB

After

Width:  |  Height:  |  Size: 58 KiB

0
docs/core/baseapp_state-initchain.png → docs/docs/core/baseapp_state-initchain.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 32 KiB

After

Width:  |  Height:  |  Size: 32 KiB

0
docs/core/baseapp_state_types.png → docs/docs/core/baseapp_state_types.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 131 KiB

After

Width:  |  Height:  |  Size: 131 KiB

8
docs/cosmwasm/README.md → docs/docs/cosmwasm/README.md
View File

@ -1,8 +1,6 @@
<!--
order: 1
parent:
order: 9
-->
---
sidebar_position: 1
---
# CosmWasm smart contracts

5
docs/docs/cosmwasm/_category_.json Normal file
View File

@ -0,0 +1,5 @@
{
"label": "CosmWasm",
"position": 9,
"link": null
}

8
docs/ibc/README.md → docs/docs/ibc/README.md
View File

@ -1,8 +1,6 @@
<!--
order: 1
parent:
order: 8
-->
---
sidebar_position: 1
---
# IBC

5
docs/docs/ibc/_category_.json Normal file
View File

@ -0,0 +1,5 @@
{
"label": "IBC",
"position": 8,
"link": null
}

18
docs/intro/overview.md → docs/docs/intro/00-overview.md
View File

@ -1,6 +1,6 @@
<!--
order: 1
-->
---
sidebar_position: 1
---
# High-level Overview
@ -8,7 +8,7 @@ order: 1
The [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) is an open-source framework for building multi-asset public Proof-of-Stake (PoS) <df value="blockchain">blockchains</df>, like the Cosmos Hub, as well as permissioned Proof-of-Authority (PoA) blockchains. Blockchains built with the Cosmos SDK are generally referred to as **application-specific blockchains**.
The goal of the Cosmos SDK is to allow developers to easily create custom blockchains from scratch that can natively interoperate with other blockchains. We envision the Cosmos SDK as the npm-like framework to build secure blockchain applications on top of [Tendermint](https://github.com/tendermint/tendermint). SDK-based blockchains are built out of composable [modules](../building-modules/intro.md), most of which are open-source and readily available for any developers to use. Anyone can create a module for the Cosmos SDK, and integrating already-built modules is as simple as importing them into your blockchain application. What's more, the Cosmos SDK is a capabilities-based system that allows developers to better reason about the security of interactions between modules. For a deeper look at capabilities, jump to [Object-Capability Model](../core/ocap.md).
The goal of the Cosmos SDK is to allow developers to easily create custom blockchains from scratch that can natively interoperate with other blockchains. We envision the Cosmos SDK as the npm-like framework to build secure blockchain applications on top of [Tendermint](https://github.com/tendermint/tendermint). SDK-based blockchains are built out of composable [modules](../building-modules/01-intro.md), most of which are open-source and readily available for any developers to use. Anyone can create a module for the Cosmos SDK, and integrating already-built modules is as simple as importing them into your blockchain application. What's more, the Cosmos SDK is a capabilities-based system that allows developers to better reason about the security of interactions between modules. For a deeper look at capabilities, jump to [Object-Capability Model](../core/10-ocap.md).
## What are Application-Specific Blockchains
@ -16,22 +16,18 @@ One development paradigm in the blockchain world today is that of virtual-machin
Application-specific blockchains offer a radically different development paradigm than virtual-machine blockchains. An application-specific blockchain is a blockchain customized to operate a single application: developers have all the freedom to make the design decisions required for the application to run optimally. They can also provide better sovereignty, security and performance.
Learn more about [application-specific blockchains](./why-app-specific.md).
Learn more about [application-specific blockchains](./01-why-app-specific.md).
## Why the Cosmos SDK
The Cosmos SDK is the most advanced framework for building custom application-specific blockchains today. Here are a few reasons why you might want to consider building your decentralized application with the Cosmos SDK:
* The default consensus engine available within the Cosmos SDK is [Tendermint Core](https://github.com/tendermint/tendermint). Tendermint is the most (and only) mature BFT consensus engine in existence. It is widely used across the industry and is considered the gold standard consensus engine for building Proof-of-Stake systems.
* The Cosmos SDK is open-source and designed to make it easy to build blockchains out of composable [modules](../../x/). As the ecosystem of open-source Cosmos SDK modules grows, it will become increasingly easier to build complex decentralized platforms with it.
* The Cosmos SDK is open-source and designed to make it easy to build blockchains out of composable [modules](../modules). As the ecosystem of open-source Cosmos SDK modules grows, it will become increasingly easier to build complex decentralized platforms with it.
* The Cosmos SDK is inspired by capabilities-based security, and informed by years of wrestling with blockchain state-machines. This makes the Cosmos SDK a very secure environment to build blockchains.
* Most importantly, the Cosmos SDK has already been used to build many application-specific blockchains that are already in production. Among others, we can cite [Cosmos Hub](https://hub.cosmos.network), [IRIS Hub](https://irisnet.org), [Binance Chain](https://docs.binance.org/), [Terra](https://terra.money/) or [Kava](https://www.kava.io/). [Many more](https://cosmos.network/ecosystem) are building on the Cosmos SDK.
## Getting started with the Cosmos SDK
* Learn more about the [architecture of a Cosmos SDK application](./sdk-app-architecture.md)
* Learn more about the [architecture of a Cosmos SDK application](./02-sdk-app-architecture.md)
* Learn how to build an application-specific blockchain from scratch with the [Cosmos SDK Tutorial](https://cosmos.network/docs/tutorial)
## Next {hide}
Learn about [application-specific blockchains](./why-app-specific.md) {hide}

14
docs/intro/why-app-specific.md → docs/docs/intro/01-why-app-specific.md
View File

@ -1,10 +1,12 @@
<!--
order: 2
-->
---
sidebar_position: 1
---
# Application-Specific Blockchains
This document explains what application-specific blockchains are, and why developers would want to build one as opposed to writing Smart Contracts. {synopsis}
:::note Synopsis
This document explains what application-specific blockchains are, and why developers would want to build one as opposed to writing Smart Contracts.
:::
## What are application-specific blockchains
@ -75,7 +77,3 @@ Security is hard to quantify, and greatly varies from platform to platform. That
One of the major benefits of application-specific blockchains is sovereignty. A decentralized application is an ecosystem that involves many actors: users, developers, third-party services, and more. When developers build on virtual-machine blockchain where many decentralized applications coexist, the community of the application is different than the community of the underlying blockchain, and the latter supersedes the former in the governance process. If there is a bug or if a new feature is needed, stakeholders of the application have very little leeway to upgrade the code. If the community of the underlying blockchain refuses to act, nothing can happen.
The fundamental issue here is that the governance of the application and the governance of the network are not aligned. This issue is solved by application-specific blockchains. Because application-specific blockchains specialize to operate a single application, stakeholders of the application have full control over the entire chain. This ensures that the community will not be stuck if a bug is discovered, and that it has the freedom to choose how it is going to evolve.
## Next {hide}
Learn more about the [high-level architecture](./sdk-app-architecture.md) of a Cosmos SDK application {hide}

16
docs/intro/sdk-app-architecture.md → docs/docs/intro/02-sdk-app-architecture.md
View File

@ -1,6 +1,6 @@
<!--
order: 3
-->
---
sidebar_position: 1
---
# Blockchain Architecture
@ -84,14 +84,10 @@ Note that **Tendermint only handles transaction bytes**. It has no knowledge of
Here are the most important messages of the ABCI:
* `CheckTx`: When a transaction is received by Tendermint Core, it is passed to the application to check if a few basic requirements are met. `CheckTx` is used to protect the mempool of full-nodes against spam transactions. . A special handler called the [`AnteHandler`](../basics/gas-fees.md#antehandler) is used to execute a series of validation steps such as checking for sufficient fees and validating the signatures. If the checks are valid, the transaction is added to the [mempool](https://docs.tendermint.com/v0.34/tendermint-core/mempool.html#mempool) and relayed to peer nodes. Note that transactions are not processed (i.e. no modification of the state occurs) with `CheckTx` since they have not been included in a block yet.
* `DeliverTx`: When a [valid block](https://docs.tendermint.com/v0.34/spec/blockchain/blockchain.html#validation) is received by Tendermint Core, each transaction in the block is passed to the application via `DeliverTx` in order to be processed. It is during this stage that the state transitions occur. The `AnteHandler` executes again, along with the actual [`Msg` service](../building-modules/msg-services.md) RPC for each message in the transaction.
* `CheckTx`: When a transaction is received by Tendermint Core, it is passed to the application to check if a few basic requirements are met. `CheckTx` is used to protect the mempool of full-nodes against spam transactions. . A special handler called the [`AnteHandler`](../basics/04-gas-fees.md#antehandler) is used to execute a series of validation steps such as checking for sufficient fees and validating the signatures. If the checks are valid, the transaction is added to the [mempool](https://docs.tendermint.com/v0.34/tendermint-core/mempool.html#mempool) and relayed to peer nodes. Note that transactions are not processed (i.e. no modification of the state occurs) with `CheckTx` since they have not been included in a block yet.
* `DeliverTx`: When a [valid block](https://docs.tendermint.com/v0.34/spec/blockchain/blockchain.html#validation) is received by Tendermint Core, each transaction in the block is passed to the application via `DeliverTx` in order to be processed. It is during this stage that the state transitions occur. The `AnteHandler` executes again, along with the actual [`Msg` service](../building-modules/03-msg-services.md) RPC for each message in the transaction.
* `BeginBlock`/`EndBlock`: These messages are executed at the beginning and the end of each block, whether the block contains transactions or not. It is useful to trigger automatic execution of logic. Proceed with caution though, as computationally expensive loops could slow down your blockchain, or even freeze it if the loop is infinite.
Find a more detailed view of the ABCI methods from the [Tendermint docs](https://docs.tendermint.com/v0.34/introduction/what-is-tendermint.html#abci-overview).
Any application built on Tendermint needs to implement the ABCI interface in order to communicate with the underlying local Tendermint engine. Fortunately, you do not have to implement the ABCI interface. The Cosmos SDK provides a boilerplate implementation of it in the form of [baseapp](./sdk-design.md#baseapp).
## Next {hide}
Read about the [high-level design principles of the Cosmos SDK](./sdk-design.md) {hide}
Any application built on Tendermint needs to implement the ABCI interface in order to communicate with the underlying local Tendermint engine. Fortunately, you do not have to implement the ABCI interface. The Cosmos SDK provides a boilerplate implementation of it in the form of [baseapp](./03-sdk-design.md#baseapp).

22
docs/intro/sdk-design.md → docs/docs/intro/03-sdk-design.md
View File

@ -1,10 +1,10 @@
<!--
order: 4
-->
---
sidebar_position: 1
---
# Main Components of the Cosmos SDK
The Cosmos SDK is a framework that facilitates the development of secure state-machines on top of Tendermint. At its core, the Cosmos SDK is a boilerplate implementation of the [ABCI](./sdk-app-architecture.md#abci) in Golang. It comes with a [`multistore`](../core/store.md#multistore) to persist data and a [`router`](../core/baseapp.md#routing) to handle transactions.
The Cosmos SDK is a framework that facilitates the development of secure state-machines on top of Tendermint. At its core, the Cosmos SDK is a boilerplate implementation of the [ABCI](./02-sdk-app-architecture.md#abci) in Golang. It comes with a [`multistore`](../core/04-store.md#multistore) to persist data and a [`router`](../core/00-baseapp.md#routing) to handle transactions.
Here is a simplified view of how transactions are handled by an application built on top of the Cosmos SDK when transferred from Tendermint via `DeliverTx`:
@ -15,7 +15,7 @@ Here is a simplified view of how transactions are handled by an application buil
## `baseapp`
`baseapp` is the boilerplate implementation of a Cosmos SDK application. It comes with an implementation of the ABCI to handle the connection with the underlying consensus engine. Typically, a Cosmos SDK application extends `baseapp` by embedding it in [`app.go`](../basics/app-anatomy.md#core-application-file).
`baseapp` is the boilerplate implementation of a Cosmos SDK application. It comes with an implementation of the ABCI to handle the connection with the underlying consensus engine. Typically, a Cosmos SDK application extends `baseapp` by embedding it in [`app.go`](../basics/00-app-anatomy.md#core-application-file).
Here is an example of this from `simapp`, the Cosmos SDK demonstration app:
@ -23,13 +23,13 @@ Here is an example of this from `simapp`, the Cosmos SDK demonstration app:
The goal of `baseapp` is to provide a secure interface between the store and the extensible state machine while defining as little about the state machine as possible (staying true to the ABCI).
For more on `baseapp`, please click [here](../core/baseapp.md).
For more on `baseapp`, please click [here](../core/00-baseapp.md).
## Multistore
The Cosmos SDK provides a [`multistore`](../core/store.md#multistore) for persisting state. The multistore allows developers to declare any number of [`KVStores`](../core/store.md#base-layer-kvstores). These `KVStores` only accept the `[]byte` type as value and therefore any custom structure needs to be marshalled using [a codec](../core/encoding.md) before being stored.
The Cosmos SDK provides a [`multistore`](../core/04-store.md#multistore) for persisting state. The multistore allows developers to declare any number of [`KVStores`](../core/04-store.md#base-layer-kvstores). These `KVStores` only accept the `[]byte` type as value and therefore any custom structure needs to be marshalled using [a codec](../core/05-encoding.md) before being stored.
The multistore abstraction is used to divide the state in distinct compartments, each managed by its own module. For more on the multistore, click [here](../core/store.md#multistore)
The multistore abstraction is used to divide the state in distinct compartments, each managed by its own module. For more on the multistore, click [here](../core/04-store.md#multistore)
## Modules
@ -82,7 +82,7 @@ Here is a simplified view of how a transaction is processed by the application o
v
```
Each module can be seen as a little state-machine. Developers need to define the subset of the state handled by the module, as well as custom message types that modify the state (*Note:* `messages` are extracted from `transactions` by `baseapp`). In general, each module declares its own `KVStore` in the `multistore` to persist the subset of the state it defines. Most developers will need to access other 3rd party modules when building their own modules. Given that the Cosmos SDK is an open framework, some of the modules may be malicious, which means there is a need for security principles to reason about inter-module interactions. These principles are based on [object-capabilities](../core/ocap.md). In practice, this means that instead of having each module keep an access control list for other modules, each module implements special objects called `keepers` that can be passed to other modules to grant a pre-defined set of capabilities.
Each module can be seen as a little state-machine. Developers need to define the subset of the state handled by the module, as well as custom message types that modify the state (*Note:* `messages` are extracted from `transactions` by `baseapp`). In general, each module declares its own `KVStore` in the `multistore` to persist the subset of the state it defines. Most developers will need to access other 3rd party modules when building their own modules. Given that the Cosmos SDK is an open framework, some of the modules may be malicious, which means there is a need for security principles to reason about inter-module interactions. These principles are based on [object-capabilities](../core/10-ocap.md). In practice, this means that instead of having each module keep an access control list for other modules, each module implements special objects called `keepers` that can be passed to other modules to grant a pre-defined set of capabilities.
Cosmos SDK modules are defined in the `x/` folder of the Cosmos SDK. Some core modules include:
@ -91,7 +91,3 @@ Cosmos SDK modules are defined in the `x/` folder of the Cosmos SDK. Some core m
* `x/staking` + `x/slashing`: Used to build Proof-Of-Stake blockchains.
In addition to the already existing modules in `x/`, that anyone can use in their app, the Cosmos SDK lets you build your own custom modules. You can check an [example of that in the tutorial](https://tutorials.cosmos.network/).
## Next {hide}
Learn more about the [anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {hide}

5
docs/docs/intro/_category_.json Normal file
View File

@ -0,0 +1,5 @@
{
"label": "Introduction",
"position": 0,
"link": null
}

10
docs/migrations/README.md → docs/docs/migrations/00-intro.md
View File

@ -1,10 +1,8 @@
<!--
order: false
parent:
order: 7
-->
---
sidebar_position: 1
---
# Migrations
# Introduction to Migrations
This document contains all the migration guides to update your app and modules to the current Cosmos SDK.

4
docs/migrations/pre-upgrade.md → docs/docs/migrations/01-pre-upgrade.md
View File

@ -1,3 +1,7 @@
---
sidebar_position: 1
---
# Pre-Upgrade Handling
Cosmovisor supports custom pre-upgrade handling. Use pre-upgrade handling when you need to implement application config changes that are required in the newer version before you perform the upgrade.

5
docs/docs/migrations/_category_.json Normal file
View File

@ -0,0 +1,5 @@
{
"label": "Migrations",
"position": 6,
"link": null
}

24
docs/run-node/keyring.md → docs/docs/run-node/00-keyring.md
View File

@ -1,10 +1,12 @@
<!--
order: 1
-->
---
sidebar_position: 1
---
# Setting up the keyring
This document describes how to configure and use the keyring and its various backends for an [**application**](../basics/app-anatomy.md). {synopsis}
:::note Synopsis
This document describes how to configure and use the keyring and its various backends for an [**application**](../basics/00-app-anatomy.md).
:::
The keyring holds the private/public keypairs used to interact with a node. For instance, a validator key needs to be set up before running the blockchain node, so that blocks can be correctly signed. The private key can be stored in different locations, called "backends", such as a file or the operating system's own key storage.
@ -56,7 +58,7 @@ $ (echo $KEYPASSWD; echo $KEYPASSWD) | gaiacli keys add me # multiple pro
$ echo $KEYPASSWD | gaiacli keys show me # single prompt
```
::: tip
:::tip
The first time you add a key to an empty keyring, you will be prompted to type the password twice.
:::
@ -68,7 +70,7 @@ within app-specific directories. `pass` is available for the most popular UNIX
operating systems as well as GNU/Linux distributions. Please refer to its manual page for
information on how to download and install it.
::: tip
:::tip
**pass** uses [GnuPG](https://gnupg.org/) for encryption. `gpg` automatically invokes the `gpg-agent`
daemon upon execution, which handles the caching of GnuPG credentials. Please refer to `gpg-agent`
man page for more information on how to configure cache parameters such as credentials TTL and
@ -106,7 +108,7 @@ The `memory` backend stores keys in memory. The keys are immediately deleted aft
## Adding keys to the keyring
::: warning
:::warning
Make sure you can build your own binary, and replace `simd` with the name of your binary in the snippets.
:::
@ -114,7 +116,7 @@ Applications developed using the Cosmos SDK come with the `keys` subcommand. For
You can use `simd keys` for help about the keys command and `simd keys [command] --help` for more information about a particular subcommand.
::: tip
:::tip
You can also enable auto-completion with the `simd completion` command. For example, at the start of a bash session, run `. <(simd completion)`, and all `simd` subcommands will be auto-completed.
:::
@ -129,8 +131,4 @@ MY_VALIDATOR_ADDRESS=$(simd keys show my_validator -a --keyring-backend test)
This command generates a new 24-word mnemonic phrase, persists it to the relevant backend, and outputs information about the keypair. If this keypair will be used to hold value-bearing tokens, be sure to write down the mnemonic phrase somewhere safe!
By default, the keyring generates a `secp256k1` keypair. The keyring also supports `ed25519` keys, which may be created by passing the `--algo ed25519` flag. A keyring can of course hold both types of keys simultaneously, and the Cosmos SDK's `x/auth` module (in particular its [middlewares](../core/baseapp.md#middleware)) supports natively these two public key algorithms.
## Next {hide}
Read about [running a node](./run-node.md) {hide}
By default, the keyring generates a `secp256k1` keypair. The keyring also supports `ed25519` keys, which may be created by passing the `--algo ed25519` flag. A keyring can of course hold both types of keys simultaneously, and the Cosmos SDK's `x/auth` module (in particular its [middlewares](../core/00-baseapp.md#middleware)) supports natively these two public key algorithms.

32
docs/run-node/run-node.md → docs/docs/run-node/01-run-node.md
View File

@ -1,19 +1,25 @@
<!--
order: 2
-->
---
sidebar_position: 1
---
# Running a Node
Now that the application is ready and the keyring populated, it's time to see how to run the blockchain node. In this section, the application we are running is called [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/main/simapp), and its corresponding CLI binary `simd`. {synopsis}
:::note Synopsis
Now that the application is ready and the keyring populated, it's time to see how to run the blockchain node. In this section, the application we are running is called [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/main/simapp), and its corresponding CLI binary `simd`.
:::
## Pre-requisite Readings
:::note
* [Anatomy of a Cosmos SDK Application](../basics/app-anatomy.md) {prereq}
* [Setting up the keyring](./keyring.md) {prereq}
### Pre-requisite Readings
* [Anatomy of a Cosmos SDK Application](../basics/00-app-anatomy.md)
* [Setting up the keyring](./00-keyring.md)
:::
## Initialize the Chain
::: warning
:::warning
Make sure you can build your own binary, and replace `simd` with the name of your binary in the snippets.
:::
@ -59,7 +65,7 @@ jq '.app_state.mint.minter.inflation = "0.300000000000000000"' genesis.json > te
## Adding Genesis Accounts
Before starting the chain, you need to populate the state with at least one account. To do so, first [create a new account in the keyring](./keyring.md#adding-keys-to-the-keyring) named `my_validator` under the `test` keyring backend (feel free to choose another name and another backend).
Before starting the chain, you need to populate the state with at least one account. To do so, first [create a new account in the keyring](./00-keyring.md#adding-keys-to-the-keyring) named `my_validator` under the `test` keyring backend (feel free to choose another name and another backend).
Now that you have created a local account, go ahead and grant it some `stake` tokens in your chain's genesis file. Doing so will also make sure your chain is aware of this account's existence:
@ -67,9 +73,9 @@ Now that you have created a local account, go ahead and grant it some `stake` to
simd add-genesis-account $MY_VALIDATOR_ADDRESS 100000000000stake
```
Recall that `$MY_VALIDATOR_ADDRESS` is a variable that holds the address of the `my_validator` key in the [keyring](./keyring.md#adding-keys-to-the-keyring). Also note that the tokens in the Cosmos SDK have the `{amount}{denom}` format: `amount` is is a 18-digit-precision decimal number, and `denom` is the unique token identifier with its denomination key (e.g. `atom` or `uatom`). Here, we are granting `stake` tokens, as `stake` is the token identifier used for staking in [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/main/simapp). For your own chain with its own staking denom, that token identifier should be used instead.
Recall that `$MY_VALIDATOR_ADDRESS` is a variable that holds the address of the `my_validator` key in the [keyring](./00-keyring.md#adding-keys-to-the-keyring). Also note that the tokens in the Cosmos SDK have the `{amount}{denom}` format: `amount` is is a 18-digit-precision decimal number, and `denom` is the unique token identifier with its denomination key (e.g. `atom` or `uatom`). Here, we are granting `stake` tokens, as `stake` is the token identifier used for staking in [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/main/simapp). For your own chain with its own staking denom, that token identifier should be used instead.
Now that your account has some tokens, you need to add a validator to your chain. Validators are special full-nodes that participate in the consensus process (implemented in the [underlying consensus engine](../intro/sdk-app-architecture.md#tendermint)) in order to add new blocks to the chain. Any account can declare its intention to become a validator operator, but only those with sufficient delegation get to enter the active set (for example, only the top 125 validator candidates with the most delegation get to be validators in the Cosmos Hub). For this guide, you will add your local node (created via the `init` command above) as a validator of your chain. Validators can be declared before a chain is first started via a special transaction included in the genesis file called a `gentx`:
Now that your account has some tokens, you need to add a validator to your chain. Validators are special full-nodes that participate in the consensus process (implemented in the [underlying consensus engine](../intro/02-sdk-app-architecture.md#tendermint)) in order to add new blocks to the chain. Any account can declare its intention to become a validator operator, but only those with sufficient delegation get to enter the active set (for example, only the top 125 validator candidates with the most delegation get to be validators in the Cosmos Hub). For this guide, you will add your local node (created via the `init` command above) as a validator of your chain. Validators can be declared before a chain is first started via a special transaction included in the genesis file called a `gentx`:
```bash
# Create a gentx.
@ -134,7 +140,3 @@ In config.toml:
```toml
log_level: "state:info,p2p:info,consensus:info,x/staking:info,x/ibc:info,*error"
```
## Next {hide}
Read about the [Interacting with your Node](./interact-node.md) {hide}

34
docs/run-node/interact-node.md → docs/docs/run-node/02-interact-node.md
View File

@ -1,15 +1,21 @@
<!--
order: 3
-->
---
sidebar_position: 1
---
# Interacting with the Node
There are multiple ways to interact with a node: using the CLI, using gRPC or using the REST endpoints. {synopsis}
:::note Synopsis
There are multiple ways to interact with a node: using the CLI, using gRPC or using the REST endpoints.
:::
## Pre-requisite Readings
:::note
* [gRPC, REST and Tendermint Endpoints](../core/grpc_rest.md) {prereq}
* [Running a Node](./run-node.md) {prereq}
### Pre-requisite Readings
* [gRPC, REST and Tendermint Endpoints](../core/06-grpc_rest.md)
* [Running a Node](./01-run-node.md)
:::
## Using the CLI
@ -50,7 +56,7 @@ You should see two delegations, the first one made from the `gentx`, and the sec
## Using gRPC
The Protobuf ecosystem developed tools for different use cases, including code-generation from `*.proto` files into various languages. These tools allow the building of clients easily. Often, the client connection (i.e. the transport) can be plugged and replaced very easily. Let's explore one of the most popular transport: [gRPC](../core/grpc_rest.md).
The Protobuf ecosystem developed tools for different use cases, including code-generation from `*.proto` files into various languages. These tools allow the building of clients easily. Often, the client connection (i.e. the transport) can be plugged and replaced very easily. Let's explore one of the most popular transport: [gRPC](../core/06-grpc_rest.md).
Since the code generation library largely depends on your own tech stack, we will only present three alternatives:
@ -62,7 +68,7 @@ Since the code generation library largely depends on your own tech stack, we wil
[grpcurl](https://github.com/fullstorydev/grpcurl) is like `curl` but for gRPC. It is also available as a Go library, but we will use it only as a CLI command for debugging and testing purposes. Follow the instructions in the previous link to install it.
Assuming you have a local node running (either a localnet, or connected a live network), you should be able to run the following command to list the Protobuf services available (you can replace `localhost:9000` by the gRPC server endpoint of another node, which is configured under the `grpc.address` field inside [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml)):
Assuming you have a local node running (either a localnet, or connected a live network), you should be able to run the following command to list the Protobuf services available (you can replace `localhost:9000` by the gRPC server endpoint of another node, which is configured under the `grpc.address` field inside [`app.toml`](../run-node/01-run-node.md#configuring-the-node-using-apptoml)):
```bash
grpcurl -plaintext localhost:9090 list
@ -209,7 +215,7 @@ CosmJS documentation can be found at [https://cosmos.github.io/cosmjs](https://c
## Using the REST Endpoints
As described in the [gRPC guide](../core/grpc_rest.md), all gRPC services on the Cosmos SDK are made available for more convenient REST-based queries through gRPC-gateway. The format of the URL path is based on the Protobuf service method's full-qualified name, but may contain small customizations so that final URLs look more idiomatic. For example, the REST endpoint for the `cosmos.bank.v1beta1.Query/AllBalances` method is `GET /cosmos/bank/v1beta1/balances/{address}`. Request arguments are passed as query parameters.
As described in the [gRPC guide](../core/06-grpc_rest.md), all gRPC services on the Cosmos SDK are made available for more convenient REST-based queries through gRPC-gateway. The format of the URL path is based on the Protobuf service method's full-qualified name, but may contain small customizations so that final URLs look more idiomatic. For example, the REST endpoint for the `cosmos.bank.v1beta1.Query/AllBalances` method is `GET /cosmos/bank/v1beta1/balances/{address}`. Request arguments are passed as query parameters.
As a concrete example, the `curl` command to make balances request is:
@ -222,7 +228,7 @@ curl \
Make sure to replace `localhost:1317` with the REST endpoint of your node, configured under the `api.address` field.
The list of all available REST endpoints is available as a Swagger specification file, it can be viewed at `localhost:1317/swagger`. Make sure that the `api.swagger` field is set to true in your [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml) file.
The list of all available REST endpoints is available as a Swagger specification file, it can be viewed at `localhost:1317/swagger`. Make sure that the `api.swagger` field is set to true in your [`app.toml`](../run-node/01-run-node.md#configuring-the-node-using-apptoml) file.
### Query for historical state using REST
@ -240,8 +246,4 @@ Assuming the state at that block has not yet been pruned by the node, this query
### Cross-Origin Resource Sharing (CORS)
[CORS policies](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) are not enabled by default to help with security. If you would like to use the rest-server in a public environment we recommend you provide a reverse proxy, this can be done with [nginx](https://www.nginx.com/). For testing and development purposes there is an `enabled-unsafe-cors` field inside [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml).
## Next {hide}
Sending transactions using gRPC and REST requires some additional steps: generating the transaction, signing it, and finally broadcasting it. Read about [generating and signing transactions](./txs.md). {hide}
[CORS policies](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) are not enabled by default to help with security. If you would like to use the rest-server in a public environment we recommend you provide a reverse proxy, this can be done with [nginx](https://www.nginx.com/). For testing and development purposes there is an `enabled-unsafe-cors` field inside [`app.toml`](../run-node/01-run-node.md#configuring-the-node-using-apptoml).

18
docs/run-node/txs.md → docs/docs/run-node/03-txs.md
View File

@ -1,14 +1,16 @@
<!--
order: 4
-->
---
sidebar_position: 1
---
# Generating, Signing and Broadcasting Transactions
This document describes how to generate an (unsigned) transaction, signing it (with one or multiple keys), and broadcasting it to the network. {synopsis}
:::note Synopsis
This document describes how to generate an (unsigned) transaction, signing it (with one or multiple keys), and broadcasting it to the network.
:::
## Using the CLI
The easiest way to send transactions is using the CLI, as we have seen in the previous page when [interacting with a node](./interact-node.md#using-the-cli). For example, running the following command
The easiest way to send transactions is using the CLI, as we have seen in the previous page when [interacting with a node](./02-interact-node.md#using-the-cli). For example, running the following command
```bash
simd tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake --chain-id my-test-chain --keyring-backend test
@ -18,7 +20,7 @@ will run the following steps:
* generate a transaction with one `Msg` (`x/bank`'s `MsgSend`), and print the generated transaction to the console.
* ask the user for confirmation to send the transaction from the `$MY_VALIDATOR_ADDRESS` account.
* fetch `$MY_VALIDATOR_ADDRESS` from the keyring. This is possible because we have [set up the CLI's keyring](./keyring.md) in a previous step.
* fetch `$MY_VALIDATOR_ADDRESS` from the keyring. This is possible because we have [set up the CLI's keyring](./00-keyring.md) in a previous step.
* sign the generated transaction with the keyring's account.
* broadcast the signed transaction to the network. This is possible because the CLI connects to the node's Tendermint RPC endpoint.
@ -51,7 +53,7 @@ Some useful flags to consider in the `tx sign` command:
#### Signing with Multiple Signers
::: warning
:::warning
Please note that signing a transaction with multiple signers or with a multisig account, where at least one signer uses `SIGN_MODE_DIRECT`, is not yet possible. You may follow [this Github issue](https://github.com/cosmos/cosmos-sdk/issues/8141) for more info.
:::
@ -263,7 +265,7 @@ func sendTx() error {
### Broadcasting a Transaction
The preferred way to broadcast a transaction is to use gRPC, though using REST (via `gRPC-gateway`) or the Tendermint RPC is also posible. An overview of the differences between these methods is exposed [here](../core/grpc_rest.md). For this tutorial, we will only describe the gRPC method.
The preferred way to broadcast a transaction is to use gRPC, though using REST (via `gRPC-gateway`) or the Tendermint RPC is also posible. An overview of the differences between these methods is exposed [here](../core/06-grpc_rest.md). For this tutorial, we will only describe the gRPC method.
```go
import (

6
docs/run-node/rosetta.md → docs/docs/run-node/04-rosetta.md
View File

@ -1,6 +1,6 @@
<!--
order: 6
-->
---
sidebar_position: 1
---
# Rosetta

12
docs/run-node/run-testnet.md → docs/docs/run-node/05-run-testnet.md
View File

@ -1,12 +1,14 @@
<!--
order: 7
-->
---
sidebar_position: 1
---
# Running a Testnet
The `simd testnet` subcommand makes it easy to initialize and start a simulated test network for testing purposes. {synopsis}
:::note Synopsis
The `simd testnet` subcommand makes it easy to initialize and start a simulated test network for testing purposes.
:::
In addition to the commands for [running a node](./run-node.html), the `simd` binary also includes a `testnet` command that allows you to start a simulated test network in-process or to initialize files for a simulated test network that runs in a separate process.
In addition to the commands for [running a node](./01-run-node.md), the `simd` binary also includes a `testnet` command that allows you to start a simulated test network in-process or to initialize files for a simulated test network that runs in a separate process.
## Initialize Files

5
docs/docs/run-node/_category_.json Normal file
View File

@ -0,0 +1,5 @@
{
"label": "Running a Node, API and CLI",
"position": 5,
"link": null
}

412
docs/docusaurus.config.js Normal file
View File

@ -0,0 +1,412 @@
// @ts-check
// Note: type annotations allow type checking and IDEs autocompletion
const lightCodeTheme = require("prism-react-renderer/themes/github");
const darkCodeTheme = require("prism-react-renderer/themes/dracula");
// const lastVersion = "v0.47";
const lastVersion = "current";
/** @type {import('@docusaurus/types').Config} */
const config = {
title: "Cosmos SDK",
tagline:
"Cosmos SDK is the world's most popular framework for building application-specific blockchains.",
url: "https://docs.cosmos.network",
baseUrl: "/",
onBrokenLinks: "warn",
onBrokenMarkdownLinks: "warn",
favicon: "img/favicon.svg",
trailingSlash: false,
// GitHub pages deployment config.
// If you aren't using GitHub pages, you don't need these.
organizationName: "cosmos",
projectName: "cosmos-sdk",
// Even if you don't use internalization, you can use this field to set useful
// metadata like html lang. For example, if your site is Chinese, you may want
// to replace "en" with "zh-Hans".
i18n: {
defaultLocale: "en",
locales: ["en"],
},
presets: [
[
"classic",
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
sidebarPath: require.resolve("./sidebars.js"),
routeBasePath: "/",
editUrl: "https://github.com/cosmos/cosmos-sdk/tree/main/",
lastVersion: lastVersion,
versions: {
current: {
path: "main",
// banner: "unreleased",
},
// "v0.47": {
// label: "v0.47",
// path: "v0.47",
// banner: "none",
// },
},
},
theme: {
customCss: require.resolve("./src/css/custom.css"),
},
}),
],
],
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
image: "img/banner.jpg",
docs: {
sidebar: {
autoCollapseCategories: true,
},
},
navbar: {
title: "Cosmos SDK",
hideOnScroll: false,
logo: {
alt: "Cosmos SDK Logo",
src: "img/logo-sdk.svg",
href: "https://docs.cosmos.network",
target: "_self",
},
items: [
{
href: "https://github.com/cosmos/cosmos-sdk",
html: `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg" class="github-icon">
<path fill-rule="evenodd" clip-rule="evenodd" d="M12 0.300049C5.4 0.300049 0 5.70005 0 12.3001C0 17.6001 3.4 22.1001 8.2 23.7001C8.8 23.8001 9 23.4001 9 23.1001C9 22.8001 9 22.1001 9 21.1001C5.7 21.8001 5 19.5001 5 19.5001C4.5 18.1001 3.7 17.7001 3.7 17.7001C2.5 17.0001 3.7 17.0001 3.7 17.0001C4.9 17.1001 5.5 18.2001 5.5 18.2001C6.6 20.0001 8.3 19.5001 9 19.2001C9.1 18.4001 9.4 17.9001 9.8 17.6001C7.1 17.3001 4.3 16.3001 4.3 11.7001C4.3 10.4001 4.8 9.30005 5.5 8.50005C5.5 8.10005 5 6.90005 5.7 5.30005C5.7 5.30005 6.7 5.00005 9 6.50005C10 6.20005 11 6.10005 12 6.10005C13 6.10005 14 6.20005 15 6.50005C17.3 4.90005 18.3 5.30005 18.3 5.30005C19 7.00005 18.5 8.20005 18.4 8.50005C19.2 9.30005 19.6 10.4001 19.6 11.7001C19.6 16.3001 16.8 17.3001 14.1 17.6001C14.5 18.0001 14.9 18.7001 14.9 19.8001C14.9 21.4001 14.9 22.7001 14.9 23.1001C14.9 23.4001 15.1 23.8001 15.7 23.7001C20.5 22.1001 23.9 17.6001 23.9 12.3001C24 5.70005 18.6 0.300049 12 0.300049Z" fill="currentColor"/>
</svg>
`,
position: "right",
},
{
type: "docsVersionDropdown",
position: "left",
dropdownActiveClassDisabled: true,
// versions not yet migrated to docusaurus
dropdownItemsAfter: [
{
href: "https://docs.cosmos.network/v0.46/",
label: "v0.46",
target: "_self",
},
{
href: "https://docs.cosmos.network/v0.45/",
label: "v0.45",
target: "_self",
},
],
},
],
},
footer: {
links: [
{
items: [
{
html: `<a href="https://cosmos.network"><img src="/img/logo-bw.svg" alt="Cosmos Logo"></a>`,
},
],
},
{
title: "Documentation",
items: [
{
label: "Cosmos Hub",
href: "https://hub.cosmos.network",
},
{
label: "Tendermint Core",
href: "https://docs.tendermint.com",
},
{
label: "IBC Go",
href: "https://ibc.cosmos.network",
},
],
},
{
title: "Community",
items: [
{
label: "Blog",
href: "https://blog.cosmos.network",
},
{
label: "Forum",
href: "https://forum.cosmos.network",
},
{
label: "Discord",
href: "https://discord.gg/cosmosnetwork",
},
{
label: "Reddit",
href: "https://reddit.com/r/cosmosnetwork",
},
],
},
{
title: "Social",
items: [
{
label: "Discord",
href: "https://discord.gg/cosmosnetwork",
},
{
label: "Twitter",
href: "https://twitter.com/cosmos",
},
{
label: "Youtube",
href: "https://www.youtube.com/c/CosmosProject",
},
{
label: "Telegram",
href: "https://t.me/cosmosproject",
},
],
},
],
copyright: `<p>The development of the Cosmos SDK is led primarily by <a href="https://interchain.io/ecosystem">Interchain Core Teams</a>. Funding for this development comes primarily from the Interchain Foundation, a Swiss non-profit.</p>`,
},
prism: {
theme: lightCodeTheme,
darkTheme: darkCodeTheme,
additionalLanguages: ["protobuf", "go-module"], // https://prismjs.com/#supported-languages
},
algolia: {
appId: "BH4D9OD16A",
apiKey: "ac317234e6a42074175369b2f42e9754",
indexName: "cosmos-sdk",
contextualSearch: false,
},
}),
plugins: [
async function myPlugin(context, options) {
return {
name: "docusaurus-tailwindcss",
configurePostCss(postcssOptions) {
postcssOptions.plugins.push(require("postcss-import"));
postcssOptions.plugins.push(require("tailwindcss/nesting"));
postcssOptions.plugins.push(require("tailwindcss"));
postcssOptions.plugins.push(require("autoprefixer"));
return postcssOptions;
},
};
},
[
"@docusaurus/plugin-google-analytics",
{
trackingID: "UA-51029217-2",
anonymizeIP: true,
},
],
[
"@docusaurus/plugin-client-redirects",
{
fromExtensions: ["html"],
toExtensions: ["html"],
redirects: [
{
from: ["/", "/master", "/v0.43", "/v0.44"],
to: "/main",
},
{
from: [
"/main/modules/auth/01_concepts",
"/main/modules/auth/02_state",
"/main/modules/auth/03_antehandlers",
"/main/modules/auth/04_keepers",
"/main/modules/auth/06_params",
"/main/modules/auth/07_client",
],
to: "/main/modules/auth",
},
{
from: "/main/modules/auth/05_vesting",
to: "/main/modules/vesting",
},
{
from: [
"/main/modules/authz/01_concepts",
"/main/modules/authz/02_state",
"/main/modules/authz/03_messages",
"/main/modules/authz/04_events",
"/main/modules/authz/05_client",
],
to: "/main/modules/authz",
},
{
from: [
"/main/modules/bank/01_state",
"/main/modules/bank/02_keepers",
"/main/modules/bank/04_events",
"/main/modules/bank/05_params",
"/main/modules/bank/06_client",
],
to: "/main/modules/bank",
},
{
from: [
"/main/modules/capability/01_concepts",
"/main/modules/capability/02_state",
],
to: "/main/modules/capability",
},
{
from: [
"/main/modules/crisis/01_state",
"/main/modules/crisis/02_messages",
"/main/modules/crisis/03_events",
"/main/modules/crisis/04_params",
"/main/modules/crisis/05_client",
],
to: "/main/modules/crisis",
},
{
from: [
"/main/modules/distribution/01_concepts",
"/main/modules/distribution/02_state",
"/main/modules/distribution/03_begin_block",
"/main/modules/distribution/04_messages",
"/main/modules/distribution/05_hooks",
"/main/modules/distribution/06_events",
"/main/modules/distribution/07_params",
"/main/modules/distribution/08_client",
],
to: "/main/modules/distribution",
},
{
from: [
"/main/modules/epoching/01_state",
"/main/modules/epoching/03_to_improve",
],
to: "/main/modules/epoching",
},
{
from: [
"/main/modules/evidence/01_concepts",
"/main/modules/evidence/02_state",
"/main/modules/evidence/03_messages",
"/main/modules/evidence/04_events",
"/main/modules/evidence/05_params",
"/main/modules/evidence/06_begin_block",
"/main/modules/evidence/07_client",
],
to: "/main/modules/evidence",
},
{
from: [
"/main/modules/feegrant/01_concepts",
"/main/modules/feegrant/02_state",
"/main/modules/feegrant/03_messages",
"/main/modules/feegrant/04_events",
"/main/modules/feegrant/05_client",
],
to: "/main/modules/feegrant",
},
{
from: [
"/main/modules/gov/01_concepts",
"/main/modules/gov/02_state",
"/main/modules/gov/03_messages",
"/main/modules/gov/04_events",
"/main/modules/gov/05_future_improvements",
"/main/modules/gov/06_params",
"/main/modules/gov/07_client",
"/main/modules/gov/08_metadata",
],
to: "/main/modules/gov",
},
{
from: [
"/main/modules/group/01_concepts",
"/main/modules/group/02_state",
"/main/modules/group/03_messages",
"/main/modules/group/04_events",
"/main/modules/group/05_client",
"/main/modules/group/06_metadata",
],
to: "/main/modules/group/",
},
{
from: [
"/main/modules/mint/01_concepts",
"/main/modules/mint/02_state",
"/main/modules/mint/03_begin_block",
"/main/modules/mint/04_params",
"/main/modules/mint/05_events",
"/main/modules/mint/06_client",
],
to: "/main/modules/mint/",
},
{
from: [
"/main/modules/nft/01_concepts",
"/main/modules/nft/02_state",
"/main/modules/nft/03_messages",
"/main/modules/nft/04_events",
],
to: "/main/modules/nft/",
},
{
from: [
"/main/modules/params/01_keeper",
"/main/modules/params/02_subspace",
],
to: "/main/modules/params/",
},
{
from: [
"/main/modules/slashing/01_concepts",
"/main/modules/slashing/02_state",
"/main/modules/slashing/03_messages",
"/main/modules/slashing/04_begin_block",
"/main/modules/slashing/05_hooks",
"/main/modules/slashing/06_events",
"/main/modules/slashing/07_tombstone",
"/main/modules/slashing/08_params",
"/main/modules/slashing/09_client",
],
to: "/main/modules/slashing/",
},
{
from: [
"/main/modules/staking/01_state",
"/main/modules/staking/02_state_transitions",
"/main/modules/staking/03_messages",
"/main/modules/staking/04_begin_block",
"/main/modules/staking/05_end_block",
"/main/modules/staking/06_hooks",
"/main/modules/staking/07_events",
"/main/modules/staking/08_params",
"/main/modules/staking/09_client",
],
to: "/main/modules/staking/",
},
{
from: [
"/main/modules/upgrade/01_concepts",
"/main/modules/upgrade/02_state",
"/main/modules/upgrade/03_events",
"/main/modules/upgrade/04_client",
],
to: "/main/modules/upgrade/",
},
],
},
],
],
};
module.exports = config;

16
docs/intro/README.md
View File

@ -1,16 +0,0 @@
<!--
order: false
parent:
order: 1
-->
# Introduction
This introduction gives a quick start on the Cosmos SDK.
1. [Overview](./overview.md)
2. [Application-Specific Blockchains](./why-app-specific.md)
3. [Architecture of a Cosmos SDK Application](./sdk-app-architecture.md)
4. [Cosmos SDK Design Overview](./sdk-design.md)
After reading the introduction material, head over to the [basics](../basics/README.md) to learn more.

5
docs/modules_category.json Normal file
View File

@ -0,0 +1,5 @@
{
"label": "SDK Modules",
"position": 7,
"link": null
}

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